diff --git a/draft-ietf-jose-json-proof-algorithms.md b/draft-ietf-jose-json-proof-algorithms.md index a67914a..fabb97d 100644 --- a/draft-ietf-jose-json-proof-algorithms.md +++ b/draft-ietf-jose-json-proof-algorithms.md @@ -207,7 +207,7 @@ The verifier MUST verify the issuer protected header against the first matching With the headers verified, the issuer's Ephemeral Key as given in the issuer protected header `proof_jwk` claim can then be used to verify each of the disclosed payload signatures. -### JPA Registration +### JPA Registration {#SU-registration} 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". @@ -222,7 +222,7 @@ The BBS Signature Scheme [@!I-D.irtf-cfrg-bbs-signatures] is under active develo 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. -### Algorithms +### JPA Algorithms {#BBS-registration} The `BBS-DRAFT-3` `alg` parameter value in the issuance protected header corresponds to a ciphersuite identifier of `BBS_BLS12381G1_XMD:SHA-256_SSWU_RO_H2G_HM2S_` from [@!I-D.irtf-cfrg-bbs-signatures]. @@ -230,7 +230,7 @@ The `BBS-PROOF-DRAFT-3` `alg` parameter value in the presentation protected head ### Key Format -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 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.ietf-cose-bls-key-representations]. @@ -322,7 +322,7 @@ To use the MAC algorithm, the issuer must have a stable public key pair to perfo 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. -### Issuer Protected Header +### Issuer Protected Header {#issuer-protected-header} The holder's presentation key JWK MUST be included in the issuer protected header using the `pjwk` claim. 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. @@ -398,7 +398,7 @@ Next, the verifier must validate all of the disclosed payloads using the followi 7. Create a JWS using a header containing the `alg` parameter along with the generated `jws_payload` value as the payload 8. Validate the JWS using the resolved issuer JWK and the extracted `issuer_signature` value -### JPA Registration +### JPA Registration {#MAC-registration} Proposed JWP `alg` value is of the format "MAC-" appended with a unique identifier for the set of MAC and signing algorithms used. Below are the initial registrations: @@ -661,11 +661,201 @@ Figure: mac-presentation-compact # IANA Considerations -## JWP Algorithms Registry - -This section establishes the IANA JWP Algorithms Registry. It also registers the following algorithms. +The following registration procedure is used for all the +registries established by this specification. + +Values are registered on a Specification Required [@RFC5226] basis +after a three-week review period on the jose-reg-review@ietf.org +mailing list, on the advice of one or more Designated Experts. +However, to allow for the allocation of values prior to publication, +the Designated Experts may approve registration once they are +satisfied that such a specification will be published. + +Registration requests sent to the mailing list for review should use +an appropriate subject (e.g., "Request to register JWP algorithm: example"). + +Within the review period, the Designated Experts will either approve or deny +the registration request, communicating this decision to the review list and IANA. +Denials should include an explanation and, if applicable, +suggestions as to how to make the request successful. +Registration requests that are undetermined for +a period longer than 21 days can be brought to the IESG's attention +(using the iesg@ietf.org mailing list) for resolution. + +Criteria that should be applied by the Designated Experts include +determining whether the proposed registration duplicates existing functionality, +whether it is likely to be of general applicability +or useful only for a single application, +and whether the registration description is clear. + +IANA must only accept registry updates from the Designated Experts and should direct +all requests for registration to the review mailing list. + +It is suggested that multiple Designated Experts be appointed who are able to +represent the perspectives of different applications using this specification, +in order to enable broadly informed review of registration decisions. +In cases where a registration decision could be perceived as +creating a conflict of interest for a particular Expert, +that Expert should defer to the judgment of the other Experts. + + +## JSON Web Proof Algorithms Registry {#AlgsReg} + +This specification establishes the +IANA "JSON Web Proof Algorithms" registry +for values of the JWP `alg` (algorithm) parameter in JWP Header Parameters. +The registry records the algorithm name, the algorithm description, +the algorithm usage locations, +the implementation requirements, the change controller, +and a reference to the specification that defines it. +The same algorithm name can be registered multiple times, +provided that the sets of usage locations are disjoint. + +It is suggested that the length of the key be included in the algorithm +name when multiple variations of algorithms are being +registered that use keys of different lengths and the key lengths for +each need to be fixed (for instance, because they will be created by +key derivation functions). +This allows readers of the JSON text to more easily make security decisions. + +The Designated Experts should perform reasonable due diligence +that algorithms being registered either are currently considered +cryptographically credible or are being registered as Deprecated +or Prohibited. + +The implementation requirements of an algorithm may be changed +over time as the +cryptographic landscape evolves, for instance, +to change the status of an algorithm to Deprecated or +to change the status of an algorithm from Optional +to Recommended+ or Required. +Changes of implementation requirements are only permitted +on a Specification Required basis after review by the Designated Experts, +with the new specification +defining the revised implementation requirements level. + +### Registration Template {#AlgsTemplate} + +* Algorithm Name: The name requested (e.g., "SU-ES256"). This name is a case-sensitive ASCII string. Names may not match other registered names in a case-insensitive manner unless the Designated Experts state that there is a compelling reason to allow an exception. +* Algorithm Description: Brief description of the algorithm (e.g., "Single-Use JWP using ES256"). +* Algorithm Usage Location(s): The algorithm usage locations, which should be one or more of the values `Issued` or `Presented`. Other values may be used with the approval of a Designated Expert. +* JWP Implementation Requirements: The algorithm implementation requirements for JWP, which must be one the words Required, Recommended, Optional, Deprecated, or Prohibited. Optionally, the word can be followed by a "+" or "-". The use of "+" indicates that the requirement strength is likely to be increased in a future version of the specification. The use of "-" indicates that the requirement strength is likely to be decreased in a future version of the specification. Any identifiers registered for non-authenticated encryption algorithms or other algorithms that are otherwise unsuitable for direct use as JWP algorithms must be registered as "Prohibited". +* Change Controller: For Standards Track RFCs, list the "IETF". For others, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included. +* Specification Document(s): Reference to the document or documents that specify the parameter, preferably including URIs that can be used to retrieve copies of the documents. An indication of the relevant sections may also be included but is not required. +* Algorithm Analysis Documents(s): References to a publication or publications in well-known cryptographic conferences, by national standards bodies, or by other authoritative sources analyzing the cryptographic soundness of the algorithm to be registered. The Designated Experts may require convincing evidence of the cryptographic soundness of a new algorithm to be provided with the registration request unless the algorithm is being registered as Deprecated or Prohibited. Having gone through working group and IETF review, the initial registrations made by this document are exempt from the need to provide this information. + + +### Initial Registry Contents {#AlgsContents} + +* Algorithm Name: `SU-ES256` +* Algorithm Description: Single-Use JWP using ES256 +* Algorithm Usage Location(s): Issued, Presented +* JWP Implementation Requirements: Recommended +* Change Controller: IETF +* Specification Document(s): (#SU-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +* Algorithm Name: `SU-ES384` +* Algorithm Description: Single-Use JWP using ES384 +* Algorithm Usage Location(s): Issued, Presented +* JWP Implementation Requirements: Optional +* Change Controller: IETF +* Specification Document(s): (#SU-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +* Algorithm Name: `SU-ES512` +* Algorithm Description: Single-Use JWP using ES512 +* Algorithm Usage Location(s): Issued, Presented +* JWP Implementation Requirements: Optional +* Change Controller: IETF +* Specification Document(s): (#SU-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +* Algorithm Name: `BBS-DRAFT-3` +* Algorithm Description: Corresponds to a ciphersuite identifier of `BBS_BLS12381G1_XMD:SHA-256_SSWU_RO_H2G_HM2S_` +* Algorithm Usage Location(s): Issued +* JWP Implementation Requirements: Required +* Change Controller: IETF +* Specification Document(s): (#BBS-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +* Algorithm Name: `BBS-PROOF-DRAFT-3` +* Algorithm Description: Corresponds to a ciphersuite identifier of `BBS_BLS12381G1_XMD:SHA-256_SSWU_RO_H2G_HM2S_` +* Algorithm Usage Location(s): Presented +* JWP Implementation Requirements: Required +* Change Controller: IETF +* Specification Document(s): (#BBS-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +* Algorithm Name: `MAC-H256` +* Algorithm Description: `MAC-H256` uses `HMAC SHA-256` as the MAC and `ECDSA using P-256 and SHA-256` for the signatures +* Algorithm Usage Location(s): Issued, Presented +* JWP Implementation Requirements: Optional +* Change Controller: IETF +* Specification Document(s): (#MAC-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +* Algorithm Name: `MAC-H384` +* Algorithm Description: `MAC-H384` uses `HMAC SHA-384` as the MAC and `ECDSA using P-384 and SHA-384` for the signatures +* Algorithm Usage Location(s): Issued, Presented +* JWP Implementation Requirements: Optional +* Change Controller: IETF +* Specification Document(s): (#MAC-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +* Algorithm Name: `MAC-H512` +* Algorithm Description: `MAC-H512` uses `HMAC SHA-512` as the MAC and `ECDSA using P-521 and SHA-512` for the signatures +* Algorithm Usage Location(s): Issued, Presented +* JWP Implementation Requirements: Optional +* Change Controller: IETF +* Specification Document(s): (#MAC-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +* Algorithm Name: `MAC-K25519` +* Algorithm Description: `MAC-K25519` uses `KMAC SHAKE128` as the MAC and `EdDSA using Curve25519` for the signatures +* Algorithm Usage Location(s): Issued, Presented +* JWP Implementation Requirements: Optional +* Change Controller: IETF +* Specification Document(s): (#MAC-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +* Algorithm Name: `MAC-K448` +* Algorithm Description: `MAC-K448` uses `KMAC SHAKE256` as the MAC and `EdDSA using Curve448` for the signatures +* Algorithm Usage Location(s): Issued, Presented +* JWP Implementation Requirements: Optional +* Change Controller: IETF +* Specification Document(s): (#MAC-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +* Algorithm Name: `MAC-H256K` +* Algorithm Description: `MAC-H256K` uses `HMAC SHA-256` as the MAC and `ECDSA using secp256k1 and SHA-256` for the signatures +* Algorithm Usage Location(s): Issued, Presented +* JWP Implementation Requirements: Optional +* Change Controller: IETF +* Specification Document(s): (#MAC-registration) of this specification +* Algorithm Analysis Documents(s): n/a + +## Header Parameter Names Registration {#HdrReg} + +This section registers the following Header Parameter names +defined by this specification in the IANA +"JSON Web Proof Header Parameters" registry +established by [@!I-D.ietf-jose-json-web-proof]. + +### Registry Contents {#HdrContents} + +* Header Parameter Name: `proof_jwk` +* Header Parameter Description: Issuer's Ephemeral Key +* Header Parameter Usage Location(s): Issued +* Change Controller: IETF +* Specification Document(s): (#issuer-protected-header) of this specification + +* Header Parameter Name: `presentation_jwk` +* Header Parameter Description: Holder's Presentation Key +* Header Parameter Usage Location(s): Issued +* Change Controller: IETF +* Specification Document(s): (#issuer-protected-header) of this specification -TBD {backmatter} diff --git a/draft-ietf-jose-json-web-proof.md b/draft-ietf-jose-json-web-proof.md index db34a42..31f5e50 100644 --- a/draft-ietf-jose-json-web-proof.md +++ b/draft-ietf-jose-json-web-proof.md @@ -102,6 +102,208 @@ While `issue` and `confirm` only occur when a JWP is initially created by the is Algorithm definitions that support JWPs are in separate companion specifications - just as the JSON Web Algorithms [@RFC7518] specification does for JWS and JWE [@RFC7516]. The JSON Proof Algorithms (JPA) [@!I-D.ietf-jose-json-proof-algorithms] specification defines how an initial set of algorithms are used with JWP. +# JWP Header + +The members of the JSON object(s) representing the JWP Header describe +the proof applied to the Protected Header and the Payload +and optionally, additional properties of the JWP. +The Header Parameter names within the JWP Header MUST be unique; +JWP parsers MUST either reject JWPs with duplicate Header Parameter names +or use a JSON parser that returns only the lexically last duplicate member name, +as specified in Section 15.12 ("The JSON Object") of ECMAScript 5.1 [@ECMAScript]. + +Implementations are required to understand +the specific Header Parameters defined by this specification +that are designated as "MUST be understood" +and process them in the manner defined in this specification. +All other Header Parameters defined by this specification that +are not so designated MUST be ignored when not understood. +Unless listed as a critical Header Parameter, per (#critDef), +all Header Parameters not defined by this specification +MUST be ignored when not understood. + +There are three classes of Header Parameter names: +Registered Header Parameter names, Public Header Parameter names, +and Private Header Parameter names. + +These requirements are intentionally parallel to those in Section 4 of [@RFC7515]. + +## Registered Header Parameter Names {#RegisteredHeaderParameterNames} + +The following Header Parameter names for use in JWPs are registered +in the IANA "JSON Web Proof Header Parameters" registry established by (#HdrReg), +with meanings as defined in the subsections below. + +As indicated by the common registry, Header Parameters used +in the Issued Form (see (#issued-form)) and the Presented Form (#presented-form) +share a common Header Parameter space; +when a parameter is used by both forms, its usage must be compatible between them. + +These Header Parameters are intentionally parallel to those in Section 4.1 of [@RFC7515]. + +### "alg" (Algorithm) Header Parameter {#algDef} + +The `alg` (algorithm) Header Parameter identifies the cryptographic algorithm +used to secure the JWP. +The JWP Proof value is not valid if the `alg` value does not represent +a supported algorithm or if there is not a key for use with that algorithm +associated with the party that secured the content. +`alg` values should either be registered in +the IANA "JSON Web Proof Algorithms" registry +established by [@!I-D.ietf-jose-json-proof-algorithms] +or be a value that contains a Collision-Resistant Name. +The `alg` value is a case-sensitive ASCII string containing a StringOrURI value. +This Header Parameter MUST be present +and MUST be understood and processed by implementations. + +A list of defined `alg` values for this use can be found +in the IANA "JSON Web Proof Algorithms" registry +established by [@!I-D.ietf-jose-json-proof-algorithms]; +the initial contents of this registry are registered +by [@!I-D.ietf-jose-json-proof-algorithms]. + +### "kid" (Key ID) Header Parameter {#kidDef} + +The `kid` (key ID) Header Parameter +is a hint indicating which key was used to secure the JWP. +This parameter allows originators to explicitly signal a change of +key to recipients. +The structure of the `kid` value is unspecified. +Its value MUST be a case-sensitive string. +Use of this Header Parameter is OPTIONAL. + +When used with a JWK, +the `kid` value is used to match a JWK `kid` parameter value. + +### "typ" (Type) Header Parameter {#typDef} + +The `typ` (type) Header Parameter is used by JWP applications to declare the +media type (#IANA.MediaTypes) of this complete JWP. +This is intended for use by the application when +more than one kind of object could be present in +an application data structure that can contain a JWP; +the application can use this value to disambiguate among +the different kinds of objects that might be present. +It will typically not be used by applications when +the kind of object is already known. +This parameter is ignored by JWP implementations; +any processing of this parameter is performed by the JWP application. +Use of this Header Parameter is OPTIONAL. + +Per [@RFC2045], all media type values, +subtype values, and parameter names are case insensitive. +However, parameter values are case sensitive unless +otherwise specified for the specific parameter. + +To keep messages compact in common situations, +it is RECOMMENDED that producers omit an "application/" prefix +of a media type value in a `typ` +Header Parameter when no other '/' appears in the media type value. +A recipient using the media type value MUST treat it as if +"application/" were prepended to any `typ` value not containing a '/'. +For instance, a `typ` value of `example` SHOULD be used to represent +the `application/example` media type, +whereas the media type `application/example;part="1/2"` cannot +be shortened to `example;part="1/2"`. + +The `typ` value `jwp` can be used by applications +to indicate that this object is a JWP using the JWP Compact Serialization. +The `typ` value `jwp+json` can be used by applications +to indicate that this object is a JWP using the JWP JSON Serialization. +Other type values can also be used by applications. + +It is RECOMMENDED that the `typ` Header Parameter be used for explicit typing, +in parallel to the recommendations in Section 3.11 of [@RFC8725]. + +### "crit" (Critical) Header Parameter {#critDef} + +The `crit` (critical) Header Parameter indicates that extensions to +this specification and/or [@!I-D.ietf-jose-json-proof-algorithms] +are being used that MUST be understood and processed. +Its value is an array listing the Header Parameter names +present in the JWP Header that use those extensions. +If any of the listed extension Header Parameters are not +understood and supported by the recipient, then the JWP is invalid. +Producers MUST NOT include Header Parameter names defined by +this specification or [@!I-D.ietf-jose-json-proof-algorithms] for use with JWP, +duplicate names, or +names that do not occur as Header Parameter names within the JWP Header +in the `crit` list. +Producers MUST NOT use the empty list `[]` as the `crit` value. +Recipients MAY consider the JWP to be invalid if the critical list +contains any Header Parameter names defined by +this specification or [@!I-D.ietf-jose-json-proof-algorithms] for use with JWP +or if any other constraints on its use are violated. +When used, this Header Parameter MUST be integrity protected; +therefore, it MUST occur only within the JWP Protected Header. +Use of this Header Parameter is OPTIONAL. +This Header Parameter MUST be understood and processed by implementations. + +### "proof_jwk" (Proof JWK) Header Parameter {#proof_jwkDef} + +The `proof_jwk` (Proof JWK) represents the public key used by the issuer +for proof of possession. +This key is represented as a JSON Web Key public key value. +It MUST contain only public key parameters and +SHOULD contain only the minimum JWK parameters necessary to represent the key; +other JWK parameters included can be checked for consistency and honored, or they can be ignored. +This Header Parameter MUST be present in the JWP issuer header parameters +and MUST be understood and processed by implementations. + +### "presentation_jwk" (Presentation JWK) Header Parameter {#presentation_jwkDef} + +The `presentation_jwk` (Presentation JWK) represents the public key used by the holder +for proof of possession. +This key is represented as a JSON Web Key public key value. +It MUST contain only public key parameters and +SHOULD contain only the minimum JWK parameters necessary to represent the key; +other JWK parameters included can be checked for consistency and honored, or they can be ignored. +This Header Parameter MUST be present in the JWP issuer header parameters +and MUST be understood and processed by implementations. + +### "iss" (Issuer) Header Parameter {#issDef} + +The `iss` (issuer) Header Parameter identifies the principal that issued the JWP. +The processing of this claim is generally application specific. +The `iss` value is a case-sensitive string +containing a StringOrURI value. +Its definition is intentionally parallel to the `iss` claim defined in [@!RFC7519]. +Use of this Header Parameter is OPTIONAL. + +### "claims" (Claims) Header Parameter {#claimsDef} + +The `claims` Header Parameter is an array listing the Claim Names +corresponding to the JWP payloads, in the same order as the payloads. +Each array value is a Claim Name, as defined in [@!RFC7519]. +Use of this Header Parameter is OPTIONAL. + +## Public Header Parameter Names {#PublicHeaderParameterName} + +Additional Header Parameter names can be defined by those +using JWPs. However, in order to prevent collisions, any new +Header Parameter name should either be registered in the IANA +"JSON Web Proof Header Parameters" registry +established by +(#HdrReg) or be a Public Name +(a value that contains a Collision-Resistant Name). +In each case, the definer of the name +or value needs to take reasonable precautions to make sure they +are in control of the part of the namespace they use to +define the Header Parameter name. + +New Header Parameters should be introduced sparingly, as +they can result in non-interoperable JWPs. + +## Private Header Parameter Names {#PrivateHeaderParameterName} + +A producer and consumer of a JWP may agree to use Header Parameter names +that are Private Names (names that are +not Registered Header Parameter names (#RegisteredHeaderParameterNames) +or Public Header Parameter names (#PublicHeaderParameterName). +Unlike Public Header Parameter names, +Private Header Parameter names are subject to collision and +should be used with caution. + # JWP Forms A JWP is always in one of two forms: the issued form or the presented form. A structural difference between the two forms is the number of protected headers. An issued JWP has only one issuer protected header, while a presented JWP will have both the issuer protected header and an additional presentation protected header. Each protected header is a JSON object that is serialized as a UTF-8 encoded octet string. @@ -110,7 +312,7 @@ All JWP forms have one or more payloads; each payload is an octet string. The p The JWP proof value is a single octet string that is only generated from and processed by the underlying JPA. Internally, the proof value may contain one or more cryptographic statements that are used to check the integrity protection of the header(s) and all payloads. Each of these statements may be a ZKP or a traditional cryptographic signature. The algorithm is responsible for how these statements are serialized into a single proof value. -## Issued Form +## Issued Form {#issued-form} When a JWP is first created, it is always in the issued form. It will contain the issuer protected header along with all of the payloads. @@ -142,7 +344,7 @@ The proof value is a binary octet string that is opaque to applications. Indivi The issuer proof is used by the holder to perform validation, checking that the issuer header and all payloads are properly encoded and protected by the given proof. -## Presented Form +## Presented Form {#presented-form} When an issued JWP is presented, it undergoes a transformation that adds a presentation protected header. It may also have one or more payloads hidden, disclosing only a subset of the original issued payloads. The proof value will always be updated to add integrity protection of the presentation header along with the necessary cryptographic statements to verify the presented JWP. @@ -235,7 +437,161 @@ Notes to be expanded: # IANA Considerations -This document has no IANA actions. +The following registration procedure is used for all the +registries established by this specification. + +Values are registered on a Specification Required [@RFC5226] basis +after a three-week review period on the jose-reg-review@ietf.org +mailing list, on the advice of one or more Designated Experts. +However, to allow for the allocation of values prior to publication, +the Designated Experts may approve registration once they are +satisfied that such a specification will be published. + +Registration requests sent to the mailing list for review should use +an appropriate subject (e.g., "Request to register JWP header parameter: example"). + +Within the review period, the Designated Experts will either approve or deny +the registration request, communicating this decision to the review list and IANA. +Denials should include an explanation and, if applicable, +suggestions as to how to make the request successful. +Registration requests that are undetermined for +a period longer than 21 days can be brought to the IESG's attention +(using the iesg@ietf.org mailing list) for resolution. + +Criteria that should be applied by the Designated Experts includes +determining whether the proposed registration duplicates existing functionality, +whether it is likely to be of general applicability +or useful only for a single application, +and whether the registration description is clear. + +IANA must only accept registry updates from the Designated Experts and should direct +all requests for registration to the review mailing list. + +It is suggested that multiple Designated Experts be appointed who are able to +represent the perspectives of different applications using this specification, +in order to enable broadly informed review of registration decisions. +In cases where a registration decision could be perceived as +creating a conflict of interest for a particular Expert, +that Expert should defer to the judgment of the other Experts. + +## JSON Web Proof Header Parameters Registry {#HdrReg} + +This specification establishes the +IANA "JSON Web Proof Header Parameters" registry +for Header Parameter names. +The registry records the Header Parameter name +and a reference to the specification that defines it. +The same Header Parameter name can be registered multiple times, +provided that the parameter usage is compatible between the specifications. +Different registrations of the same Header Parameter name +will typically use different Header Parameter Usage Locations values. + +### Registration Template {#HdrTemplate} + +* Header Parameter Name: The name requested (e.g., "kid"). Because a core goal of this specification is for the resulting representations to be compact, it is RECOMMENDED that the name be short -- not to exceed 8 characters without a compelling reason to do so. This name is case sensitive. Names may not match other registered names in a case-insensitive manner unless the Designated Experts state that there is a compelling reason to allow an exception. +* Header Parameter Description: Brief description of the Header Parameter (e.g., "Key ID"). +* Header Parameter Usage Location(s): The Header Parameter usage locations, which should be one or more of the values `Issued` or `Presented`. Other values may be used with the approval of a Designated Expert. +* Change Controller: For Standards Track RFCs, list the "IETF". For others, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included. +* Specification Document(s): Reference to the document or documents that specify the parameter, preferably including URIs that can be used to retrieve copies of the documents. An indication of the relevant sections may also be included but is not required. + +### Initial Registry Contents {#HdrContents} + +This section registers the Header Parameter names defined in +(#RegisteredHeaderParameterNames) in this registry. + +* Header Parameter Name: `alg` +* Header Parameter Description: Algorithm +* Header Parameter Usage Location(s): Issued, Presented +* Change Controller: IETF +* Specification Document(s): (#algDef) of this specification + +* Header Parameter Name: `kid` +* Header Parameter Description: Key ID +* Header Parameter Usage Location(s): Issued, Presented +* Change Controller: IETF +* Specification Document(s): (#kidDef) of this specification + +* Header Parameter Name: `typ` +* Header Parameter Description: Type +* Header Parameter Usage Location(s): Issued, Presented +* Change Controller: IETF +* Specification Document(s): (#typDef) of this specification + +* Header Parameter Name: `crit` +* Header Parameter Description: Critical +* Header Parameter Usage Location(s): Issued, Presented +* Change Controller: IETF +* Specification Document(s): (#critDef) of this specification + +* Header Parameter Name: `iss` +* Header Parameter Description: Issuer +* Header Parameter Usage Location(s): Issued, Presented +* Change Controller: IETF +* Specification Document(s): (#issDef) of this specification + +* Header Parameter Name: `claims` +* Header Parameter Description: claims +* Header Parameter Usage Location(s): Issued +* Change Controller: IETF +* Specification Document(s): (#claimsDef) of this specification + +## Media Type Registration {#MediaReg} + +### Registry Contents {#MediaContents} + +This section registers the `application/jwp` +media type [@RFC2046] +in the IANA "Media Types" registry (#IANA.MediaTypes) +in the manner described in [@RFC6838], +which can be used to indicate that the content is +a JWP using the JWP Compact Serialization. +This section also registers the `application/jwp+json` +media type in the IANA "Media Types" registry, +which can be used to indicate that the content is +a JWP using the JWP JSON Serialization. + +* Type name: application +* Subtype name: jwp +* Required parameters: n/a +* Optional parameters: n/a +* Encoding considerations: 8bit; application/jwp values are encoded as a series of base64url-encoded values (some of which may be the empty string), each separated from the next by a single period ('.') character. +* Security considerations: See the Security Considerations section of this specification. +* Interoperability considerations: n/a +* Published specification: this specification +* Applications that use this media type: TBD +* Fragment identifier considerations: n/a +* Additional information: + - Magic number(s): n/a + - File extension(s): n/a + - Macintosh file type code(s): n/a +* Person & email address to contact for further information: Michael B. Jones, michael_b_jones@hotmail.com +* Intended usage: COMMON +* Restrictions on usage: none +* Author: Michael B. Jones, michael_b_jones@hotmail.com +* Change Controller: IETF +* Provisional registration? No + +* Type name: application +* Subtype name: jwp+json +* Required parameters: n/a +* Optional parameters: n/a +* Encoding considerations: 8bit; application/jwp+json values are represented as a JSON Object; UTF-8 encoding SHOULD be employed for the JSON object. +* Security considerations: See the Security Considerations section of this specification +* Interoperability considerations: n/a +* Published specification: this specification +* Applications that use this media type: TBD +* Fragment identifier considerations: n/a +* Additional information: + - Magic number(s): n/a + - File extension(s): n/a + - Macintosh file type code(s): n/a +* Person & email address to contact for further information: Michael B. Jones, michael_b_jones@hotmail.com +* Intended usage: COMMON +* Restrictions on usage: none +* Author: Michael B. Jones, michael_b_jones@hotmail.com +* Change Controller: IETF +* Provisional registration? No + {backmatter} @@ -261,6 +617,31 @@ This document has no IANA actions. + + + ECMAScript Language Specification, 5.1 Edition + + Ecma International + + + + + + + + + + + Media Types + + IANA + + + + + + # Example JWPs The following examples use algorithms defined in JSON Proof Algorithms and also contain the keys used, so that implementations can validate these samples. @@ -316,7 +697,7 @@ The JWP Protected Header declares that the data structure is a JPT and the JWP P "email", "age" ], - "typ": "JPT", + "typ": "jpt", "proof_jwk": { "crv": "P-256", "kty": "EC",