hideki nara avatar hideki nara committed d088d92

JWE draft update(underway)

Comments (0)

Files changed (5)

docs/source/glossary.rst

     X.509
         (TBD)
 
+JWE
+=====
+
+.. glossary:: 
+    :sorted:
+
+    alg
+    enc
+    epk
+    zip
+    jku
+    kid
+    x5u
+    x5t
+    typ
+        See ":ref:`jwe.table.1`"
+

docs/source/jwe.rst

 
 .. contents:: Table of Contents
 
+.. _jwe.1:
+
+.. include:: jwe/1.rst
+
 .. _jwe.2:
 
 .. include:: jwe/2.rst
 
 .. include:: jwe/3.rst
 
+.. _jwe.3.1:
+
+.. include:: jwe/3.1.rst
+
 .. _jwe.4:
 
 .. include:: jwe/4.rst

docs/source/jwe/1.rst

+1.  Introduction
+
+JSON Web Encryption (JWE) is a compact encryption format 
+intended for space constrained environments 
+such as HTTP Authorization headers and 
+URI query parameters. 
+
+It provides a wrapper for encrypted content 
+using JSON RFC 4627 [:term:`RFC4627`] data structures. 
+The JWE encryption mechanisms are independent of the type of content being encrypted. 
+A related signature capability is described in a separate JSON Web Signature (JWS) [:term:`JWS`] specification.
+
+(December 13, 2011)

docs/source/jwe/3.1.rst

+3.1.  Example JWE
+------------------------------------------------------------
+
+The following example :term:`JWE Header` declares that:
+
+    - the :term:`Content Encryption Key` is encrypted to the recipient 
+      using the :term:`RSA-PKCS1_1.5` algorithm to produce the :term:`JWE Encrypted Key`,
+
+    - the :term:`Plaintext` is encrypted using the :term:`AES-256-GCM` algorithm to 
+      produce the :term:`JWE Ciphertext`,
+
+    - the specified **64-bit** :term:`Initialization Vector` 
+      with the base64url encoding **__79_Pv6-fg** was used, and
+
+    - the :term:`thumbprint` of the :term:`X.509 certificate` 
+      that corresponds to the key used to encrypt the JWE has the base64url encoding **7noOPq-hJ1_hCnvWh6IeYI2w9Q0**.
+
+.. code-block:: javascript
+
+   {"alg":"RSA1_5",
+    "enc":"A256GCM",
+    "iv":"__79_Pv6-fg",
+    "x5t":"7noOPq-hJ1_hCnvWh6IeYI2w9Q0"}
+
+Base64url encoding the bytes of the UTF-8 representation of the :term:`JWE Header` yields 
+this :term:`Encoded JWE Header` value (with line breaks for display purposes only):
+
+::
+
+    eyJhbGciOiJSU0ExXzUiLA0KICJlbmMiOiJBMjU2R0NNIiwNCiAiaXYiOiJfXzc5
+    X1B2Ni1mZyIsDQogIng1dCI6Ijdub09QcS1oSjFfaENudldoNkllWUkydzlRMCJ9
+
+TBD: 
+Finish this example by showing generation of a :term:`Content Encryption Key` (:term:`CEK`), 
+using the :term:`CEK` to encrypt the :term:`Plaintext` to produce the :term:`Ciphertext` 
+(and base64url encoding it), 
+and using the recipient's key to encrypt the :term:`CEK` 
+to produce the :term:`JWE Encrypted Key` (and base64url encoding it).
+
+(December 13, 2011)

docs/source/jwe/4.1.rst

 
 The following header parameter names are reserved. All the names are short because a core goal of JWE is for the representations to be compact.
 
-TBD: Describe the relationship between the JWS and JWE header parameters - especially the alg parameter, which can contain either signature algorithms (from JWS) or encryption algorithms (from JWE), and the key reference parameters jku, kid, x5u, and x5t. 
+TBD: 
+Describe the relationship between the JWS and JWE header parameters - especially the :term:`alg` parameter, 
+which can contain either signature algorithms (from :term:`JWS`) 
+or encryption algorithms (from :term:`JWE`), 
+and the key reference parameters :term:`jku`, :term:`kid`, :term:`x5u`, and :term:`x5t`. 
 
 .. _jwe.table.1:
 
-.. table::  Table 1: Reserved Header Parameter Definitions 
+.. list-table::  Table 1: Reserved Header Parameter Definitions 
+    :widths: 20 20 20 200
 
-    ======================   =============== ======================= ============================
-    Header Parameter Name    JSON Value Type Header Parameter Syntax Header Parameter Semantics
-    ======================   =============== ======================= ============================
+    *   - Header Parameter Name   
+        - JSON Value Type 
+        - Header Parameter Syntax 
+        - Header Parameter Semantics
 
-.. glossary::
+    *   - alg 
+        - string  
+        - StringOrURI  
+        - The :term:`alg` (algorithm) header parameter identifies 
+          the cryptographic algorithm used to secure the :term:`JWE Encrypted Key`. 
 
-    alg     
-        string  
+          A list of defined :term:`alg` values is presented in :ref:`Table 3 <jwe.table.3>`. 
 
-        StringOrURI     
+          The processing of the :term:`alg` (algorithm) header parameter requires 
+          that the value MUST be one that is both supported and 
+          for which there exists a key for use with that algorithm associated with the intended recipient. 
+          The :term:`alg `value is case sensitive. This header parameter is REQUIRED.
 
-        The alg (algorithm) header parameter identifies the cryptographic algorithm 
-        used to secure the :term:`JWE Encrypted Key`. 
-        A list of defined alg values is presented in :ref:`Table 3 <jwe.table.3>`. 
-        The processing of the alg (algorithm) header parameter requires 
-        that the value MUST be one that is both supported 
-        and for which there exists a key for use with that algorithm 
-        associated with the intended recipient. 
-        The alg value is case sensitive. This header parameter is REQUIRED.
+    *   - enc 
+        - string  
+        - StringOrURI  
+        - The :term:`enc` (encryption method) header parameter identifies 
+          the :term:`symmetric encryption algorithm` used to secure the :term:`Ciphertext`. 
 
-    enc     
-        string  
+          A list of defined :term:`enc` values is presented in :ref:`Table 4 <jwe.table.4>`. 
+          The processing of the enc (encryption method) header parameter requires that the value MUST be one that is supported. The enc value is case sensitive. This header parameter is REQUIRED.
 
-        StringOrURI     
 
-        The enc (encryption method) header parameter identifies the symmetric encryption algorithm 
-        used to secure the Ciphertext. 
-        A list of defined enc values is presented in :ref:`Table 4 <jwe.table.4>`. 
-        The processing of the enc (encryption method) header parameter requires 
-        that the value MUST be one that is supported. 
-        The enc value is case sensitive. This header parameter is REQUIRED.
+    *   - iv  
+        - string  
+        - String   
+        - Initialization Vector (iv) value for algorithms requiring it, represented as a base64url encoded string. This header parameter is OPTIONAL.
 
-    iv  
-        string  
+    *   - epk 
+        - object  
+        - JWK Key Object   
+        - Ephemeral Public Key (epk) value created by the originator for the use in ECDH-ES RFC 6090 [RFC6090] encryption. This key is represented in the same manner as a JSON Web Key [JWK] JWK Key Object value, containing crv (curve), x, and y members. The inclusion of the JWK Key Object alg (algorithm) member is OPTIONAL. This header parameter is OPTIONAL.
 
-        String  
+    *   - zip 
+        - string  
+        - String   
+        - Compression algorithm (zip) applied to the Plaintext before encryption, if any. This specification defines the value GZIP to refer to the encoding format produced by the file compression program "gzip" (GNU zip) as described in [RFC1952]; this format is a Lempel-Ziv coding (LZ77) with a 32 bit CRC. If no zip parameter is present, or its value is none, no compression is applied to the Plaintext before encryption. The zip value is case sensitive. This header parameter is OPTIONAL.
 
-        Initialization Vector (iv) value for algorithms requiring it, 
-        represented as a base64url encoded string. 
-        This header parameter is OPTIONAL.
+    *   - jku 
+        - string  
+        - URL  
+        - The jku (JSON Web Key URL) header parameter is an absolute URL that refers to a resource for a set of JSON-encoded public keys, one of which corresponds to the key that was used to encrypt the JWE. The keys MUST be encoded as described in the JSON Web Key (JWK) [JWK] specification. The protocol used to acquire the resource MUST provide integrity protection. An HTTP GET request to retrieve the certificate MUST use TLS RFC 2818 [RFC2818] RFC 5246 [RFC5246] with server authentication RFC 6125 [RFC6125]. This header parameter is OPTIONAL.
 
-    epk     
-        object  
+    *   - kid 
+        - string  
+        - String   
+        - The kid (key ID) header parameter is a hint indicating which key was used to encrypt the JWE. This allows originators to explicitly signal a change of key to recipients. The interpretation of the contents of the kid parameter is unspecified. This header parameter is OPTIONAL.
 
-        JWK Key Object  
+    *   - x5u 
+        - string  
+        - URL  
+        - The x5u (X.509 URL) header parameter is an absolute URL that refers to a resource for the X.509 public key certificate or certificate chain corresponding to the key used to encrypt the JWE. The identified resource MUST provide a representation of the certificate or certificate chain that conforms to RFC 5280 [RFC5280] in PEM encoded form RFC 1421 [RFC1421]. The protocol used to acquire the resource MUST provide integrity protection. An HTTP GET request to retrieve the certificate MUST use TLS RFC 2818 [RFC2818] RFC 5246 [RFC5246] with server authentication RFC 6125 [RFC6125]. This header parameter is OPTIONAL.
 
-        Ephemeral Public Key (epk) value created by the originator 
-        for the use in ECDH-ES RFC 6090 [:term:`RFC6090`] encryption. 
-        This key is represented in the same manner as a JSON Web Key [JWK] JWK Key Object value, 
-        containing crv (curve), x, and y members. 
-        The inclusion of the JWK Key Object alg (algorithm) member is OPTIONAL. 
-        This header parameter is OPTIONAL.
+    *   - x5t 
+        - string  
+        - String   
+        - The x5t (x.509 certificate thumbprint) header parameter provides a base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of the X.509 certificate that corresponds to the key that was used to encrypt the JWE. This header parameter is OPTIONAL.
 
-    zip     
-        string  
+    *   - typ 
+        - string  
+        - String   
+        - The typ (type) header parameter is used to declare the type of the encrypted content. The typ value is case sensitive. This header parameter is OPTIONAL.
 
-        String  
 
-        Compression algorithm (zip) applied to the Plaintext before encryption, if any. 
-        This specification defines the value GZIP to refer to the encoding format 
-        produced by the file compression program "gzip" (GNU zip) as described in [:term:`RFC1952`]; 
-        this format is a Lempel-Ziv coding (LZ77) with a 32 bit CRC. 
-        If no zip parameter is present, 
-        or its value is none, no compression is applied to the Plaintext before encryption. 
-        The zip value is case sensitive. This header parameter is OPTIONAL.
 
-    jku     
-        string  
 
-        URL     
-
-        The jku (JSON Web Key URL) header parameter is an absolute URL 
-        that refers to a resource for a set of JSON-encoded public keys, 
-        one of which corresponds to the key that was used to encrypt the JWE. 
-        The keys MUST be encoded as described in the JSON Web Key (JWK) [:term:`JWK`] specification. 
-        The protocol used to acquire the resource MUST provide integrity protection. 
-        An HTTP GET request to retrieve the certificate MUST use TLS RFC 2818 [RFC2818] RFC 5246 [RFC5246] 
-        with server authentication RFC 6125 [RFC6125]. 
-        This header parameter is OPTIONAL.
-
-    kid     
-        string  
-
-        String  
-
-        The kid (key ID) header parameter is a hint indicating which key was used to encrypt the JWE. 
-        This allows originators to explicitly signal a change of key to recipients. 
-        The interpretation of the contents of the kid parameter is unspecified. This header parameter is OPTIONAL.
-
-    x5u     
-        string  
-
-        URL     
-
-        The x5u (X.509 URL) header parameter is an absolute URL that refers to a resource 
-        for the X.509 public key certificate or certificate chain corresponding to the key used to encrypt the JWE. 
-        The identified resource MUST provide a representation of the certificate or certificate chain 
-        that conforms to RFC 5280 [RFC5280] in PEM encoded form RFC 1421 [RFC1421]. 
-        The protocol used to acquire the resource MUST provide integrity protection. 
-        An HTTP GET request to retrieve the certificate MUST use TLS RFC 2818 [RFC2818] RFC 5246 [RFC5246] 
-        with server authentication RFC 6125 [RFC6125]. 
-        This header parameter is OPTIONAL.
-
-    x5t     
-        string  
-
-        String  
-
-        The x5t (x.509 certificate thumbprint) header parameter provides 
-        a base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding 
-        of the X.509 certificate that corresponds to the key that was used to encrypt the JWE. This header parameter is OPTIONAL.
-
-    typ     
-        string  
-
-        String  
-
-        The typ (type) header parameter is used to declare the type of the encrypted content. 
-        The typ value is case sensitive. This header parameter is OPTIONAL. 
 
 
 Additional reserved header parameter names MAY be defined via the IANA JSON Web Encryption Header Parameters registry, as per Section 10. The syntax values used above are defined as follows: 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.