Address some 2023 review questions (#93)

* Address some 2023 review questions

* Applied DW's suggestion

Co-authored-by: David Waite <[email protected]>

---------

Co-authored-by: David Waite <[email protected]>

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

@@ -181,10 +181,11 @@ The proof value as an octet string will have a total length that is the sum of t
 ### Presentation Protected Header
 
 To generate a new presentation, the holder first creates a presentation protected header that is specific to the verifier being presented to.  This header MUST contain a claim that both the holder and verifier trust as being unique and non-replayable.
+Use of the `nonce` header parameter is RECOMMENDED for this purpose.
 
-This specification registers a `nonce` claim for the presentation protected header that contains a string value either generated by the verifier or derived from values provided by the verifier.  When present, the verifier MUST ensure the nonce value matches during verification.
+This specification registers the `nonce` header parameter for the presentation protected header that contains a string value either generated by the verifier or derived from values provided by the verifier.  When present, the verifier MUST ensure the nonce value matches during verification.
 
-The presentation protected header MAY contain other claims that are either provided by the verifier or by the holder.  These presentation claims SHOULD NOT contain values that are common across multiple presentations and SHOULD be unique to a single presentation and verifier.
+The presentation protected header MAY contain other header parameters that are either provided by the verifier or by the holder.  These presentation claims 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`.
 
@@ -297,7 +298,7 @@ Verification of a presentation is done by the verifier using the `ProofVerify` o
 
 This operation utilizes the issuer's public key as `PK`, the issuer protected header as `header`, the issuance proof as `signature`, the holder's presentation protected header as `ph`, and the payloads as `disclosed_messages`.
 
-In addition, the `disclosed_indexes` vector value is calculated from the payloads. For each absent value in payloads (`null` in JSON serialization or a zero-length string in compact serialization), the index of that payload is added to this vector.
+In addition, the `disclosed_indexes` vector value is calculated from the payloads. For each value present in payloads (e.g. all values not `null` in JSON serialization or a zero-length string in compact serialization), the index of that payload is added to this vector.
 
 ## Message Authentication Code
 

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

@@ -77,7 +77,7 @@ Any other data that is repeated across multiple JPTs is externalized so that it
 
 ## Selective Disclosure
 
-While JWPs provide the underling structure for easily supporting selective disclosure, JPTs must go a step further to ensure that applications can effectively provide choice and consent on exactly what is being disclosed.  Software using JWPs must know the mappings from payloads to claims.  JPTs do not support disclosing claims that are intended to be private from the issuer to the relying party.  All disclosed payloads MUST be mapped to claims and made accessible to the application.
+While JWPs provide the underling structure for easily supporting selective disclosure, JPTs must go a step further to ensure that holders can effectively provide choice and consent on exactly what is being disclosed.  Software using JWPs must know the mappings from payloads to claims.  JPTs do not support disclosing claims from the issuer that are intended only for a specific verifier.  All disclosed payloads MUST be mapped to claims and made accessible to the application.
 
 ## Familiarity
 
@@ -106,6 +106,8 @@ To facilitate this external definition of the claim names, an additional `cid` k
 If there is an associated JWK containing the signing key information, the `claims` key is also registered there as a convenient location for the claim names.
 
 All payloads are claim values and MUST be the base64url encoding of the UTF-8 representation of a JSON value.
+That said, predicate proofs derived from payload values are not represented as claims;
+they are contained in the presentation proof using algorithm-specific representations.
 
 The following is an example JWP Protected Header that includes a claims array:
 ```json

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

@@ -46,7 +46,7 @@ organization = "Self-Issued Consulting"
 
 The JOSE set of standards established JSON-based container formats for Keys, Signatures, and Encryption.  They also established IANA registries to enable the algorithms and representations used for them to be extended.  Since those were created, newer cryptographic algorithms that support selective disclosure and unlinkability have matured and started seeing early market adoption.
 
-This document defines a new container format similar in purpose and design to JSON Web Signature (JWS) called a _JSON Web Proof (JWP)_.  Unlike JWS, which integrity-protects only a single payload, JWP can integrity-protect multiple payloads in one message.  It also specifies a new presentation form that supports selective disclosure of individual payloads, enables additional proof computation, and adds a protected header to prevent replay and support binding mechanisms.
+This document defines a new container format similar in purpose and design to JSON Web Signature (JWS) called a _JSON Web Proof (JWP)_.  Unlike JWS, which integrity-protects only a single payload, JWP can integrity-protect multiple payloads in one message.  It also specifies a new presentation form that supports selective disclosure of individual payloads, enables additional proof computation, and adds a protected header to prevent replay.
 
 {mainmatter}
 
@@ -119,6 +119,7 @@ The issued form can only be confirmed by a holder as being correctly formed and
 ### Issuer Protected Header
 
 The issuer protected header applies to all of the payloads equally.  It is recommended that any payload-specific information not be included in this header and instead be handled outside of the cryptographic envelope.  This is to minimize any correlatable signals in the metadata, to reduce a verifier's ability to group different presentations based on small header variations from the same issuer.
+The protected header is always disclosed, whereas payloads can be selectively disclosed.
 
 Every issuer protected header MUST have an `alg` value that identifies a valid JSON Proof Algorithm (JPA).
 
@@ -164,6 +165,7 @@ Any one or more payloads may be non-disclosed in a presented JWP.  When a payloa
 The disclosed payloads will always be in the same array positions to preserve any index-based references by the application between the issued and presented forms of the JWP.  How the sparse array is represented is specific to the serialization used.
 
 Algorithms MAY support including a proof about a payload in the presentation.  Applications then treat that proven payload the same as any other non-disclosed payload and do not include it in the presented array of payloads.
+Rather, proofs about payloads, such as "age >= 21", are included in the presentation proof.
 
 ### Presentation Proof
 
@@ -379,13 +381,13 @@ Figure: jwp-issuer-header-base64
 
 Each payload must also be individually encoded:
 
-The first payload is the string `"Doe"` with the octet sequence of `[ 34, 68, 111, 101, 34 ]` and base64url-encoded as `IkRvZSI`.
+The first payload is the JSON string `"Doe"` with the octet sequence of `[ 34, 68, 111, 101, 34 ]` and base64url-encoded as `IkRvZSI`.
 
-The second payload is the string `"Jay"` with the octet sequence of `[ 34, 74, 97, 121, 34 ]` and base64url-encoded as `IkpheSI`.
+The second payload is the JSON string `"Jay"` with the octet sequence of `[ 34, 74, 97, 121, 34 ]` and base64url-encoded as `IkpheSI`.
 
-The third payload is the string `"[email protected]"` with the octet sequence of `[ 34, 106, 97, 121, 100, 111, 101, 64, 101, 120, 97, 109, 112, 108, 101, 46, 111, 114, 103, 34 ]` and base64url-encoded as `ImpheWRvZUBleGFtcGxlLm9yZyI`.
+The third payload is the JSON string `"[email protected]"` with the octet sequence of `[ 34, 106, 97, 121, 100, 111, 101, 64, 101, 120, 97, 109, 112, 108, 101, 46, 111, 114, 103, 34 ]` and base64url-encoded as `ImpheWRvZUBleGFtcGxlLm9yZyI`.
 
-The fourth payload is the string `42` with the octet sequence of `[52, 50]` and base64url-encoded as `NDI`.
+The fourth payload is the JSON number `42` with the octet sequence of `[52, 50]` and base64url-encoded as `NDI`.
 
 The Single Use algorithm utilizes multiple individual JWS Signatures.  Each signature value is generated by creating a JWS with a single Protected Header with the associated `alg` value. In this example, the fixed header used for each JWS is the serialized JSON Object `{"alg":"ES256"}`.  The JWS payload for each varies and the resulting signature value is used in its unencoded form (the octet string, not the base64url-encoded form).