Merge branch 'main' into mbj-06-history-labels

draft-ietf-jose-json-proof-algorithms.md

@@ -183,8 +183,6 @@ This specification registers the `nonce` header parameter for the presentation p
 
 The presentation protected header MAY contain other header parameters that are either provided by the verifier or by the holder.  These presentation header parameters SHOULD NOT contain values that are common across multiple presentations and SHOULD be unique to a single presentation and verifier.
 
-In various examples in this specification, the octet string serialized presentation header is referenced as `presentation_header`.
-
 ### Presentation
 
 > Editor's Note: The current definition here is incomplete, the holder's signature needs to also incorporate the presented proof.
@@ -275,7 +273,7 @@ Prior to the issuer creating a new JWP, it must have presentation binding inform
 
 The presentation key used by the holder must be transferred to the issuer and verified, likely through a challenge and self-signing mechanism.  If the holder requires unlinkability, it must also generate a new key that is verified and bound to each new JWP.
 
-How these holder presentation keys are transferred and verified is out of scope of this specification. Protocols such as OpenID Connect can be used to accomplish this.  What is required by this definition is that the holder's presentation key MUST be included in the issuer's protected header using the `pjwk` parameter with a JWK as the value.
+How these holder presentation keys are transferred and verified is out of scope of this specification. Protocols such as OpenID Connect can be used to accomplish this.  What is required by this definition is that the holder's presentation key MUST be included in the issuer's protected header using the `presentation_jwk` parameter with a JWK as the value.
 
 ### Issuer Setup
 
@@ -285,7 +283,7 @@ The Shared Secret is used by both the issuer and holder as the MAC method's key
 
 ### Issuer Protected Header {#issuer-protected-header}
 
-The holder's presentation key JWK MUST be included in the issuer protected header using the `pjwk` parameter.  The issuer MUST validate that the holder has possession of this key through a trusted mechanism such as verifying the signature of a unique nonce value from the holder.
+The holder's presentation key JWK MUST be included in the issuer protected header using the `presentation_jwk` parameter.  The issuer MUST validate that the holder has possession of this key through a trusted mechanism such as verifying the signature of a unique nonce value from the holder.
 
 ### Combined MAC Representation
 
@@ -319,7 +317,7 @@ See the JWS [Presentation Protected Header](#presentation-protected-header) sect
 
 > Editor's Note: The current definition here is incomplete, the holder's signature needs to also incorporate the presented proof.
 
-The first value in the presentation proof is the presentation signature. This is a signature over the presentation protected header, using the key specified by the `pjwk` parameter in the issuer protected header.
+The first value in the presentation proof is the presentation signature. This is a signature over the presentation protected header, using the key specified by the `presentation_jwk` parameter in the issuer protected header.
 
 The second value is the issuer signature over the Combined MAC Representation provided with the issued form.
 
@@ -805,6 +803,8 @@ The BBS examples were generated using the library at https://github.com/mattrglo
  -06
 
   * Update reference to new repository home
+  * Fixed #77: Removed vestigial use of `presentation_header`.
+  * Correct `pjwk` to `presentation_jwk`
 
  -05
 

draft-ietf-jose-json-proof-token.md

@@ -128,34 +128,39 @@ The following is an example JWP Protected Header that includes a `cid`:
 
 <{{./fixtures/template/jpt-issuer-protected-header-with-cid.json}}
 
-# Payloads
+# Presented Claims and Proofs
 
-> Editor's Note: This section is incomplete. Use it only as an indicator of the intended direction.
-
-Application resolves each claim as required when processing the JPT.  Resolution can result in one of three things:
-1. A disclosed JSON value
-2. A custom proof method
-3. A `null` value
+Each claim in the issued form of the JPT results in one of three things in the presented form of the JPT:
+1. A disclosed JSON value.
+1. An indicator that the value was not disclosed.
+1. An algorithm-specific proof method.
 
 ## Disclosed
 
-Always an octet string of valid JSON text.
+A disclosed payload is represented as a UTF-encoded octet string representing a valid JSON value.
+
+## Undisclosed
+
+The placeholder indicating that a payload was not disclosed is represented as
+described in Section 6 (Serializations) of [@!I-D.ietf-jose-json-web-proof].
 
 ## Proof Methods
 
-* proof methods can be returned instead of a disclosed payload
-* these are generated by the algorithm from information in the JWP's proof value
-* a proof method may be custom based on the capabilities of the algorithm
-* define common proof method types available?
+Proof methods can be returned instead of a disclosed payload.
+These are generated in an algorithm-specific manner from information in the JWP's proof value.
+
+A proof method may be custom based on the capabilities of the algorithm.
+
+* TBD: Describe common proof method types available?
   * range
   * membership
   * time
   * knowledge
   * linking
 
-# Example JPT
+# Example JPTs
 
-See the [@!I-D.ietf-jose-json-web-proof] appendix.
+See the examples in Appendix A.1 of [@I-D.ietf-jose-json-proof-algorithms].
 
 # Security Considerations
 
@@ -207,6 +212,7 @@ for his valuable contributions to this specification.
  -06
 
   * Update reference to new repository home
+  * Fixed #99: Discussed issued and presented forms of JPTs.
 
  -05
 

draft-ietf-jose-json-web-proof.md

@@ -425,32 +425,80 @@ The algorithm is responsible for representing selective disclosure of payloads i
 
 Each disclosed payload MUST be base64url encoded when preparing it to be serialized.  The headers and proof are also individually base64url encoded.
 
-Like JWS, JWP supports both a Compact Serialization and a JSON Serialization.
+Like JWS, JWP supports both a Compact Serialization and a JSON Serialization. These serializations both represent the same JSON-based header, payload and proof, and are thus interchangeable without breaking the proof value.
 
 ## Compact Serialization {#CompactSerialization}
 
-The individually encoded payloads are concatenated with the `~` character to form an ordered delimited array. Any non-disclosed payloads are left blank, resulting in sequential `~~` characters such that all payload positions are preserved.
+The compact serialiation provides a space-efficient encoding of a JWP in URL-safe characters. In addition to the alphabet of unpadded BASE64 URL-safe encoding, it uses the "." and "~" characters as separators.
 
-A payload which is disclosed but which contains no data (i.e. a zero-length octet string) is encoded as a single `_` character of data, which is not a valid result from base64url-encoding a value.
+All binary data is BASE64URL encoded, including the octets of the UTF-8 encoded headers and the individual payloads and proof values.
 
-Additionally, an algorithm MAY supply multiple octet strings for a proof. These are concatenated with the `~` character to form an ordered delimited array.
+Payloads and proofs are each concatenated into a single text form by concatenating the BASE64URL encoded values using the `~` character.
 
-The headers, concatenated payloads, and proof value are then concatenated with a `.` character to form the final compact serialization.  The issued form will only contain one header and always have three `.` separated parts.  The presented form will always have four `.` separated parts, the issued header, followed by the protected header, then the payloads and the proof.
+Individual payloads are allowed to be omitted; if a payload is omitted, it is represented as a zero-length text value, potentially resulting in leading, trailing, or consecutive `~` characters in the concatenated form.
+
+If a payload or proof value was a zero-length octet string, it does not get output as its zero-length BASE64URL-encoded form but as a single `_` character. This character does not represent a valid BASE64URL-encoded octet string, allowing it to be distinguished from normally encoded data.
+
+The issued form is created by concatenating the base64url-encoded issuer protected header, concatenated payloads, and concatenated proof separated each by a `.` character. The concatenated payloads MAY be omitted if the application is using detached payloads.
+
+The presented form is created by concatenating the base64url-encoded presenter protected header, base64url-encoded issuer protected header, concatenated payloads, and concatenated proof separated each by a `.` character. The concatenated payloads MAY be omitted if the application is using detached payloads.
 
 <{{./fixtures/build/bbs-holder.compact.jwp.wrapped}}>
 Figure: Compact Serialization of Presentation
 
 ## JSON Serialization {#JSONSerialization}
 
-Non-disclosed payloads in the JSON serialization are represented with a `null` value in the `payloads` array. A zero-length payload is represented as a zero-length base64url encoded sequence, the empty string `""`.
+The JSON Serialization is in the form of a JSON object, with property names representing the various components.
+
+The `issuer` key has a string value holding the BASE64URL-encoded issuer protected header. This key MUST be included.
 
-Proofs are represented as an array of one or more encoded octet strings.
+The `presentation` key has a string value holding the BASE64URL-encoded presentation protected header. It MUST be included for presented form, and MUST be omitted for issued form.
 
-This example flattened JSON serialization shows the presentation form with both the issuer and presentation headers, and with the first and third payloads hidden.
+The `payloads` key has an array value, representing the ordered sequence of payloads. If a payload has been omitted, it is represented by the JSON value `null`. A payload is otherwise reprented by the BASE64URL-encoded form of the payload octets. A zero-length payload does not have special encoding rules as needed by compact encoding, and is represented by the zero-length string output by BASE64URL. This key MUST be included unless the application is using detached payloads.
+
+The `proofs` key has an array value, representing the array of octet strings produced by the chosen algorithm. These octets are BASE64URL encoded into a JSON array.
+
+This example JSON serialization shows the presentation form with both the issuer and presentation headers, and with the first and third payloads hidden.
 
 <{{./fixtures/build/bbs-holder.json.jwp.wrapped}}>
 Figure: JSON Serialization of Presentation
 
+# Encrypted JSON Web Proofs
+
+Access to JWPs containing non-public material
+by parties without legitimate access to the non-public information
+MUST be prevented.
+This can be accomplished by encrypting the JWP
+when potentially observable by such parties
+to prevent the disclosure of private information.
+The use of an Encrypted JWP, which is a JWE [@!RFC7516]
+with a JWP as its plaintext value,
+is recommended for this purpose.
+The processing of Encrypted JWPs is identical to
+the processing of other JWEs.
+
+The `cty` (content type) JWE Header Parameter is used to indicate
+that the content of the JWE is a JWP.
+The `cty` value of the JWE SHOULD be the same as
+the `typ` (type) JWP Header Parameter value of the unencrypted JWP to be encrypted.
+If the JWP has no `typ` value, then the following JWE Header Parameter `cty` (content type) values SHOULD be used:
+
+* `jwp` is used to indicate that the content of the JWE is a JWP using the JWP Compact Serialization.
+* `jwp+json` is used to indicate that the content of the JWE is the UTF-8 encoding of a JWP using the JWP JSON Serialization.
+
+The `cty` (content type) Header Parameter MUST be present
+unless the application knows that the encrypted content is
+a JWP by another means or convention,
+in which case the `cty` value MAY be omitted.
+
+# Detached Payloads
+
+In some contexts, it is useful to make statements about payloads which are not themselves contained within the JWP, similar to "Detached Content" in JWS [@RFC7515].
+
+For this purpose, the compact, JSON and CBOR serializations allow for all payloads to be omitted from a serialized form. While this is a legal serialization, it is not on its own able to be verified.
+
+The recipient is expected to perform some sequence of steps defined by the application to recreate the array of payloads, including order and optionality. This effectively recreates the fully specified serialization of the JWP.
+
 # Security Considerations {#SecurityConsiderations}
 
 Notes to be expanded:
@@ -657,7 +705,8 @@ This section registers the `+jwp`
 structured syntax suffix [@RFC6838]
 in the IANA "Structured Syntax Suffix" registry (#IANA.StructuredSuffix)
 in the manner described in [@RFC6838],
-which can be used to indicate that the media type is encoded as a JWP.
+which can be used to indicate that the media type is encoded as a JWP
+using the JWP Compact Serialization.
 
 #### The +jwp Structured Syntax Suffix
 
@@ -768,8 +817,11 @@ for his valuable contributions to this specification.
   [[ To be removed from the final specification ]]
 
  -06
-
-  * Update reference to new repository home
+
+  * Update reference to new repository home.
+  * Fixed #83: Added encrypted JWPs.
+  * Added additional clarification around the compact and JSON serializations
+  * Added text around fully detached payloads
 
  -05
 

fixtures/mac-h256-fixtures.mjs

@@ -35,7 +35,7 @@ const holderPrivateKey = crypto.createPrivateKey({
 /// Create Issued JWP
 
 // Modify the issuer protected header by adding the Holder's public key
-issuerProtectedHeaderJSON.pjwk = holderPublicKeyJSON;
+issuerProtectedHeaderJSON.presentation_jwk = holderPublicKeyJSON;
 
 // encode/sign the issuer protected header w/ the stable key
 const finalIssuerProtectedHeader = JSON.stringify(issuerProtectedHeaderJSON);