Skip to main content

8. IANA Considerations

The following registration procedures are used for all registries established by this specification.

Values are registered with a Specification Required [RFC5226] after a three-week review period on the [email protected] mailing list, on the advice of one or more Designated Experts. However, to allow for the allocation of values prior to publication, the Designated Expert(s) 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 JWK parameter: example").

Within the review period, the Designated Expert(s) 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 [email protected] mailing list) for resolution.

Criteria that should be applied by the Designated Expert(s) include determining whether the proposed registration duplicates existing functionality, whether it is likely to be of general applicability or whether it is useful only for a single application, and whether the registration description is clear.

IANA MUST only accept registry updates from the Designated Expert(s) 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 Expert(s).

8.1. JSON Web Key Parameters Registry​

This section establishes the IANA "JSON Web Key Parameters" registry for JWK parameter names. The registry records the parameter name, the key type(s) with which the parameter is used, and a reference to the specification that defines it. It also records whether the parameter conveys public or private information. This section registers the parameter names defined in Section 4. The same JWK parameter name can be registered multiple times, provided that duplicate parameter registrations are for JWK parameters that are specific to a key type; in this case, the meaning of the duplicate parameter name is disambiguated by the "kty" value of the JWK containing it.

8.1.1. Registration Template​

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 Expert(s) state that there is a compelling reason to allow an exception. However, matching names may be registered, provided that the accompanying sets of "kty" values that the parameter name is used with are disjoint; for the purposes of matching "kty" values, "*" matches all values.

Parameter Description: Brief description of the parameter (e.g., "Key ID").

Used with "kty" Value(s): The key type parameter value(s) that the parameter name is to be used with, or the value "*" if the parameter value is used with all key types. When the registered parameter names are the same (including when one matches in a case-insensitive manner), the values MUST NOT match other registered "kty" values in a case-insensitive manner unless the Designated Expert(s) state that there is a compelling reason to allow an exception.

Parameter Information Class: Registers whether the parameter conveys public or private information. Its value must be either Public or Private.

Change Controller: For Standards Track RFCs, state "IESG". 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(s) 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.

8.1.2. Initial Registry Contents​

This specification registers the following parameters:

  • kty - Key Type - * (all key types) - Public - RFC 7517 Section 4.1
  • use - Public Key Use - * (all key types) - Public - RFC 7517 Section 4.2
  • key_ops - Key Operations - * (all key types) - Public - RFC 7517 Section 4.3
  • alg - Algorithm - * (all key types) - Public - RFC 7517 Section 4.4
  • kid - Key ID - * (all key types) - Public - RFC 7517 Section 4.5
  • x5u - X.509 URL - * (all key types) - Public - RFC 7517 Section 4.6
  • x5c - X.509 Certificate Chain - * (all key types) - Public - RFC 7517 Section 4.7
  • x5t - X.509 Certificate SHA-1 Thumbprint - * (all key types) - Public - RFC 7517 Section 4.8
  • x5t#S256 - X.509 Certificate SHA-256 Thumbprint - * (all key types) - Public - RFC 7517 Section 4.9

8.2. JSON Web Key Use Registry​

This section establishes the IANA "JSON Web Key Use" registry for JWK "use" (public key use) member values. The registry records the public key use value and a reference to the specification that defines it. This section registers the parameter names defined in Section 4.2.

8.2.1. Registration Template​

Similar structure to Section 8.1.1, including Use Member Value, Use Description, Change Controller, and Specification Document(s) fields.

8.2.2. Initial Registry Contents​

  • sig - Digital Signature or MAC - RFC 7517 Section 4.2
  • enc - Encryption - RFC 7517 Section 4.2

8.3. JSON Web Key Operations Registry​

This section establishes the IANA "JSON Web Key Operations" registry for JWK "key_ops" (key operations) member values. The registry records the key operation value and a reference to the specification that defines it. This section registers the values defined in Section 4.3.

8.3.1. Registration Template​

Similar structure to Section 8.2.1.

8.3.2. Initial Registry Contents​

  • sign - Compute digital signature or MAC - RFC 7517 Section 4.3
  • verify - Verify digital signature or MAC - RFC 7517 Section 4.3
  • encrypt - Encrypt content - RFC 7517 Section 4.3
  • decrypt - Decrypt content and validate decryption - RFC 7517 Section 4.3
  • wrapKey - Encrypt key - RFC 7517 Section 4.3
  • unwrapKey - Decrypt key and validate decryption - RFC 7517 Section 4.3
  • deriveKey - Derive key - RFC 7517 Section 4.3
  • deriveBits - Derive bits not to be used as a key - RFC 7517 Section 4.3

8.4. JSON Web Key Set Parameters Registry​

This section establishes the IANA "JSON Web Key Set Parameters" registry for JWK Set parameter names. The registry records the parameter name and a reference to the specification that defines it. This section registers the parameter name defined in Section 5.

8.4.1. Registration Template​

Similar structure to Section 8.1.1, but for JWK Set parameters.

8.4.2. Initial Registry Contents​

  • keys - Array of JWK values - RFC 7517 Section 5.1

8.5. Media Type Registration​

8.5.1. Registry Contents​

This specification registers the following media types [RFC2046]:

application/jwk+json

  • Type name: application
  • Subtype name: jwk+json
  • Required parameters: N/A
  • Optional parameters: N/A
  • Encoding considerations: 8bit; application/jwk+json values are encoded in UTF-8; "8bit" content transfer encoding may be used
  • Security considerations: See RFC 7517 Section 9
  • Interoperability considerations: N/A
  • Published specification: RFC 7517
  • Applications that use this media type: OpenID Connect, Mozilla Persona, Salesforce, Google, Android, Windows Azure, Amazon Web Services, and other applications utilizing JWKs
  • Additional information: Magic number(s): N/A, File extension(s): .jwk, Macintosh file type code(s): N/A
  • Person & email address to contact for further information: Michael B. Jones, [email protected]
  • Intended usage: COMMON
  • Restrictions on usage: none
  • Author: Michael B. Jones, [email protected]
  • Change controller: IESG
  • Provisional registration? No

application/jwk-set+json

  • Similar structure for JWK Set
  • File extension(s): .jwks
Last updated on