Mike's New Years Eve 2023 Proofread

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

@@ -44,39 +44,39 @@ organization = "Ping Identity"
 
 .# Abstract
 
-The JSON Proof Algorithms (JPA) specification registers cryptographic algorithms and identifiers to be used with the JSON Web Proof and JSON Web Key (JWK) specifications. It defines several IANA registries for these identifiers.
+The JSON Proof Algorithms (JPA) specification registers cryptographic algorithms and identifiers to be used with the JSON Web Proof and JSON Web Key (JWK) specifications. It defines IANA registries for these identifiers.
 
 {mainmatter}
 
 # Introduction
 
 The JSON Web Proof (JWP) [@!I-D.ietf-jose-json-web-proof] draft establishes a new secure container format that supports selective disclosure and unlinkability using Zero-Knowledge Proofs (ZKPs) or other cryptographic algorithms.
 
-> Editor's Note: This draft is still early and incomplete, there will be significant changes to the algorithms as currently defined here.  Please do not use any of these definitions or examples for anything except personal experimentation and learning.  Contributions and feedback are welcome at https://github.com/json-web-proofs/json-web-proofs.
+> Editor's Note: This draft is still early and incomplete. There will be significant changes to the algorithms as currently defined here.  Please do not use any of these definitions or examples for anything except personal experimentation and learning.  Contributions and feedback are welcomed at https://github.com/json-web-proofs/json-web-proofs.
 
 # Conventions and Definitions
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
 "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [@RFC2119] [@RFC8174] when, and only when, they appear in all capitals, as shown here.
 
-The roles of "issuer", "holder", and "verifier" are used as defined by the [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/2021/REC-vc-data-model-20211109/).  The term "presentation" is also used as defined by this source, but the term "credential" is avoided in this specification in order to minimize confusion with other definitions.
+The roles of "issuer", "holder", and "verifier" are used as defined by the VC Data Model [@VC-DATA-MODEL-2.0].  The term "presentation" is also used as defined by this source, but the term "credential" is avoided in this specification to minimize confusion with other definitions.
 
 # Terminology
 
 The terms "JSON Web Signature (JWS)", "Base64url Encoding", "Header Parameter", "JOSE Header", "JWS Payload", "JWS Signature", and "JWS Protected Header" are defined by [@RFC7515].
 
-The terms "JSON Web Proof (JWP)", "JWP Payload", "JWP Proof", and "JWP Protected Header" are defined by the JWP draft.
+The terms "JSON Web Proof (JWP)", "JWP Payload", "JWP Proof", and "JWP Protected Header" are defined by [@!I-D.ietf-jose-json-web-proof].
 
 These terms are defined by this specification:
 
-Stable Key
-  An asymmetric key-pair used by an issuer that is also shared via an out-of-band mechanism to a verifier in order to validate the signature.
+Stable Key:
+:  An asymmetric key-pair used by an issuer that is also shared via an out-of-band mechanism to a verifier to validate the signature.
 
-Ephemeral Key
-  An asymmetric key-pair that is generated for one-time use by an issuer and never stored or used again outside of the creation of a single JWP.
+Ephemeral Key:
+:  An asymmetric key-pair that is generated for one-time use by an issuer and never stored or used again outside of the creation of a single JWP.
 
-Presentation Key
-  An asymmetric key-pair that is generated by a holder and used to ensure that a presentation is not able to be replayed by any other party.
+Presentation Key:
+:  An asymmetric key-pair that is generated by a holder and used to ensure that a presentation is not able to be replayed by any other party.
 
 
 # Background
@@ -99,17 +99,17 @@ All algorithms MUST provide integrity protection for the issuer header and all p
 
 ## Confirm
 
-Performed by the holder to validate the issued JWP is correctly formed and protected.
+Performed by the holder to validate that the issued JWP is correctly formed and protected.
 
-Each algorithm MAY support using additional input items options such as those sent to the issuer for issuance. After confirmation, an algorithm MAY return a modified JWP for serialized storage without the local state (such as with blinded payloads now unblinded).
+Each algorithm MAY support using additional input items options, such as those sent to the issuer for issuance. After confirmation, an algorithm MAY return a modified JWP for serialized storage without the local state (such as with blinded payloads now unblinded).
 
-The algorithm MUST fully verify the issued proof value against the issuer protected header and all payloads.  If given a presented JWP instead of an issued one the confirm process MUST return an error.
+The algorithm MUST fully verify the issued proof value against the issuer protected header and all payloads.  If given a presented JWP instead of an issued one, the confirm process MUST return an error.
 
 ## Present
 
 Used to apply any selective disclosure choices and perform any unlinkability transformations.
 
-An algorithm MAY support additional input options from the requesting party such as for predicate proofs and verifiable computation requests.
+An algorithm MAY support additional input options from the requesting party, such as for predicate proofs and verifiable computation requests.
 
 Every algorithm MUST support the ability to hide any or all payloads.  It MUST always include the issuer protected header unmodified in the presentation.
 
@@ -122,7 +122,7 @@ Performed by the verifier to verify the protected headers along with any disclos
 The algorithm MUST verify the integrity of all disclosed payloads and MUST also verify the integrity of both the issuer and presentation protected headers.
 
 If the presented proof contains any assertions about the hidden payloads, the algorithm MUST also verify all of those assertions.
-It MAY support additional options such as those sent to the holder to generate the presentation.
+It MAY support additional options, such as those sent to the holder to generate the presentation.
 
 If given an issued JWP for verification, the algorithm MUST return an error.
 
@@ -132,7 +132,7 @@ This section defines how to use specific algorithms for JWPs.
 
 ## Single Use
 
-> Editor's Note: This algorithm is going to be renamed and slightly refactored; the new name is still TBD.
+> Editor's Note: This algorithm may be renamed and slightly refactored.
 
 The Single Use (SU) algorithm is based on composing multiple traditional JWS values into a single JWP proof value.  It enables a very simple form of selective disclosure without requiring any advanced cryptographic techniques.
 
@@ -152,7 +152,7 @@ The issuer MUST verify that the holder has possession of this key.  The holder-i
 
 ### Issuer Setup
 
-To create a Single Use JWP the issuer first generates a unique Ephemeral Key using the selected JWS algorithm.  This key-pair will be used to sign each of the payloads of a single JWP and then discarded.
+To create a Single Use JWP, the issuer first generates a unique Ephemeral Key using the selected JWS algorithm.  This key-pair will be used to sign each of the payloads of a single JWP and then discarded.
 
 ### Using JWS
 
@@ -170,7 +170,7 @@ The holder's Presentation Key JWK MUST be included in issuer protected header us
 
 The final issuer protected header is then used directly as the body of a JWS and signed using the issuer's Stable Key.  The resulting JWS signature value unencoded octet string is the first value in the JWP proof.
 
-In various examples in this specification the octet string serialized issuer header is referenced as `issuer_header`.
+In various examples in this specification, the octet string serialized issuer header is referenced as `issuer_header`.
 
 ### Payloads
 
@@ -180,13 +180,13 @@ The proof value as an octet string will have a total length that is the sum of t
 
 ### Presentation Protected Header
 
-In order 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.
+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.
 
 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.
 
 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.
 
-In various examples in this specification the octet string serialized presentation header is referenced as `presentation_header`.
+In various examples in this specification, the octet string serialized presentation header is referenced as `presentation_header`.
 
 ### Presentation
 
@@ -208,16 +208,16 @@ With the headers verified, the issuer's Ephemeral Key as given in the issuer pro
 
 ### JPA Registration
 
-Proposed JWP `alg` value is of the format "SU-" appended with the relevant JWS `alg` value for the chosen public and ephemeral key-pair algorithm, for example "SU-ES256".
+The proposed JWP `alg` value is of the format "SU-" appended with the relevant JWS `alg` value for the chosen public and ephemeral key-pair algorithm, for example "SU-ES256".
 
 ### Example
 
-See the example in the appendix of the JSON Web Proof draft.
+See the example in the appendix of [@!I-D.ietf-jose-json-web-proof].
 
 
 ## BBS
 
-The BBS Signature Scheme [@!I-D.irtf-cfrg-bbs-signatures] is under active development within the CRFG. Prior to this effort work was done under the DIF [Applied Cryptography Working Group](https://identity.foundation/working-groups/crypto.html), an effort to clarify and bring best practices to early prototypes leveraged by multiple early stage decentralized identity projects.
+The BBS Signature Scheme [@!I-D.irtf-cfrg-bbs-signatures] is under active development within the CRFG.
 
 This algorithm supports both selective disclosure and unlinkability, enabling the holder to generate multiple presentations from one issued JWP without a verifier being able to correlate those presentations together based on the proof.
 
@@ -231,18 +231,18 @@ The `BBS-PROOF-DRAFT-3` `alg` parameter value in the presentation protected head
 
 The key used for the `BBS-DRAFT-3` algorithm is an elliptic curve-based key pair, specifically against the G_2 subgroup of a pairing friendly curve. Additional details on key generation can be found in [@!I-D.irtf-cfrg-bbs-signatures, Section 3.3]
 
-The JWK form of this key is an `OKP` type with a curve of `BLs12381G2`, with `x` being the BASE64URL-encoded form of the output of `point_to_octets_g2`. The use of this curve is described in [@!I-D.looker-cose-bls-key-representations].
+The JWK form of this key is an `OKP` type with a curve of `BLs12381G2`, with `x` being the BASE64URL-encoded form of the output of `point_to_octets_g2`. The use of this curve is described in [@!I-D.ietf-cose-bls-key-representations].
 
 <{{./fixtures/build/private-key.jwk.wrapped}}
 Figure: BBS private key in JWK format
 
-There is no additional prover key necessary for presentation proofs.
+There is no additional holder key necessary for presentation proofs.
 
 ### Issuance
 
 Issuance is performed using the `Sign` operation from [@!I-D.irtf-cfrg-bbs-signatures, section 3.4.1]. This operation utilizes the issuer's BLS12-381 G2 key pair as `SK` and `PK`, along with desired protected header and payloads as the octets header and the octets array messages.
 
-The octets result of this operation forms the issuance proof, to be used along with the protected header and payloads to serialize the JWP.
+The octets resulting from this operation form the issuance proof, to be used along with the protected header and payloads to serialize the JWP.
 
 As an example, consider following protected header and array of payloads:
 
@@ -283,7 +283,7 @@ For example, given the following presentation header:
 <{{./fixtures/template/bbs-prover-presentation-header.json}}
 Figure: Holder Presentation Header
 
-The prover decides to share all information other than the email address, and generates a proof. That proof is represented in the following serializations:
+The holder decides to share all information other than the email address, and generates a proof. That proof is represented in the following serializations:
 
 <{{./fixtures/build/bbs-prover.json.jwp.wrapped}}
 Figure: Presentation JWP (JSON serialization)
@@ -309,15 +309,15 @@ The design is intentionally minimal and only involves using a single standardize
 
 ### Holder Setup
 
-Prior to the issuer creating a new JWP it must have presentation binding information provided by the holder.  This enables the holder to perform replay prevention while presenting the JWP.
+Prior to the issuer creating a new JWP, it must have presentation binding information provided by the holder.  This enables the holder to perform replay prevention while presenting the JWP.
 
-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.
+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` claim 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 `pjwk` claim with a JWK as the value.
 
 ### Issuer Setup
 
-To use the MAC algorithm the issuer must have a stable public key pair to perform signing.  To start the issuance process, a single 32-byte random Shared Secret must first be generated.  This value will be shared privately to the holder as part of the issuer's JWP proof value.
+To use the MAC algorithm, the issuer must have a stable public key pair to perform signing.  To start the issuance process, a single 32-byte random Shared Secret must first be generated.  This value will be shared privately to the holder as part of the issuer's JWP proof value.
 
 The Shared Secret is used by both the issuer and holder as the MAC method's key to generate a new set of unique ephemeral keys.  These keys are then used as the input to generate a MAC that protects each payload.
 
@@ -335,7 +335,7 @@ Each payload is serialized using UTF-8 and encoded with base64url into an octet
 
 ### Issuer Proof
 
-The issuer proof consists of two items appended together, the issuer's signature of the appended array of MACs, and the Shared Secret used to generate the set of payload keys.
+The issuer proof consists of two items appended together: the issuer's signature of the appended array of MACs and the Shared Secret used to generate the set of payload keys.
 
 To generate the signature, the array containing the final MAC of the issuer protected header followed by all of the payload MACs appended in order is used as the input to a new JWS.
 
@@ -361,7 +361,7 @@ See the JWS [Presentation Protected Header](#presentation-protected-header) sect
 
 The presentation proof is constructed as a large octet array containing multiple appended items similar to the issuer proof value.  The first item is the JWS decoded signature value generated when the holder uses the presentation key to sign the presentation header.  The second item is the issuer signature from the issuer's proof value.
 
-These two signatures are then followed by a MAC value for each payload.  The MAC values used will depend on if that payload has been disclosed or is hidden.  Disclosed payloads will include the MAC key input, and hidden payloads will include only their final MAC value.
+These two signatures are then followed by a MAC value for each payload.  The MAC values used will depend on whether that payload has been disclosed or is hidden.  Disclosed payloads will include the MAC key input, and hidden payloads will include only their final MAC value.
 
 ```
 presentation_proof = [presentation_signature, issuer_signature,
@@ -373,7 +373,7 @@ The size of this value will depend on the underlying cryptographic algorithms.
 
 ### Verifier Setup
 
-In order to verify that the presentation was protected from replay attacks, the verifier must be able to validate the presentation protected header.  This involves the following steps:
+To verify that the presentation was protected from replay attacks, the verifier must be able to validate the presentation protected header.  This involves the following steps:
 
 1. JSON parse the presentation header
 2. Validate the contained `nonce` claim
@@ -668,8 +668,32 @@ TBD
 
 {backmatter}
 
+<reference anchor="VC-DATA-MODEL-2.0" target="https://www.w3.org/TR/vc-data-model-2.0">
+  <front>
+    <title>Verifiable Credentials Data Model 2.0</title>
+    <author fullname="Manu Sporny">
+      <organization>Digital Bazaar</organization>
+    </author>
+    <author fullname="Ted Thibodeau Jr">
+      <organization>OpenLink Software</organization>
+    </author>
+    <author fullname="Ivan Herman">
+      <organization>W3C</organization>
+    </author>
+    <author fullname="Michael B. Jones">
+      <organization>Invited Expert</organization>
+    </author>
+    <author fullname="Gabe Cohen">
+      <organization>Block</organization>
+    </author>
+   <date day="27" month="December" year="2023"/>
+  </front>
+</reference>
+
 # Acknowledgements
 
+This work was incubated in the DIF [Applied Cryptography Working Group](https://identity.foundation/working-groups/crypto.html).
+
 We would like to thank
 Alberto Solavagione
 for his valuable contributions to this specification.
@@ -680,6 +704,10 @@ The BBS examples were generated using the library at https://github.com/mattrglo
 
    [[ To be removed from the final specification ]]
 
+  -03
+
+  * Improvements resulting from a full proofreading.
+
   -02
 
   * Add new `BBS-DRAFT-3` and `BBS-PROOF-DRAFT-3` algorithms based on [@!I-D.irtf-cfrg-bbs-signatures], Draft 3.