One document matched: draft-jones-jose-jwe-json-serialization-02.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?xml-stylesheet type='text/xsl' href='http://xml.resource.org/authoring/rfc2629.xslt' ?>

<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="4"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>

<rfc category="std" ipr="trust200902" docName="draft-jones-jose-jwe-json-serialization-02">

  <front>
    <title abbrev="JWE JSON Serialization (JWE-JS)">JSON Web Encryption JSON Serialization (JWE-JS)</title>

    <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
      <organization>Microsoft</organization>
      <address>
        <email>mbj@microsoft.com</email>
        <uri>http://self-issued.info/</uri>
      </address>
    </author>

    <date day="15" month="October" year="2012" />

    <area>Security</area>
    <workgroup>JOSE Working Group</workgroup>

    <keyword>RFC</keyword>
    <keyword>Request for Comments</keyword>
    <keyword>I-D</keyword>
    <keyword>Internet-Draft</keyword>
    <keyword>JavaScript Object Notation</keyword>
    <keyword>JSON</keyword>
    <keyword>JSON Web Token</keyword>
    <keyword>JWT</keyword>
    <keyword>JSON Web Signature</keyword>
    <keyword>JWS</keyword>
    <keyword>JSON Web Encryption</keyword>
    <keyword>JWE</keyword>
    <keyword>JSON Web Key</keyword>
    <keyword>JWK</keyword>
    <keyword>JSON Web Algorithms</keyword>
    <keyword>JWA</keyword>

    <abstract>
      <t>
	The JSON Web Encryption JSON Serialization (JWE-JS) is a means
	of representing encrypted content using
	JavaScript Object Notation (JSON) data structures.
	This specification describes a means of representing
	secured content as a JSON data object
	(as opposed to the JWE specification, which uses a
	compact serialization with a URL-safe representation).
	It enables the same content to be encrypted to multiple
	parties (unlike JWE).
	Cryptographic algorithms and identifiers used with this
	specification are described in the separate
	JSON Web Algorithms (JWA) specification.
	The JSON Serialization for related digital signature and MAC
	functionality is described in the separate
	JSON Web Signature JSON Serialization (JWS-JS) specification.
      </t>
    </abstract>

  </front>

  <middle>
    <section title="Introduction">
      <t>
	The JSON Web Encryption JSON Serialization (JWE-JS) is a format for
	representing encrypted content as a
	JavaScript Object Notation (JSON) <xref target="RFC4627"/> object.
	It enables the same content to be encrypted to multiple parties
	(unlike JWE <xref target="JWE" />.)
	The encryption mechanisms are independent of the type of
	content being encrypted.
	Cryptographic algorithms and identifiers used with this
	specification are described in the separate
	JSON Web Algorithms (JWA) <xref target="JWA" /> specification.
	The JSON Serialization for related digital signature and MAC
	functionality is described in the separate
	JSON Web Signature JSON Serialization (JWS-JS) <xref target="JWS-JS" />
	specification.
      </t>

      <section title='Notational Conventions'>
        <t>
          The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
          "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
          and "OPTIONAL" in this document are to be interpreted as
          described in
	  Key words for use in RFCs to Indicate Requirement Levels <xref target='RFC2119' />.
        </t>
      </section>

    </section>

    <section title="Terminology">
      <t>
	This specification uses the same terminology as the
	JSON Web Encryption (JWE) <xref target="JWE" />
	specification.
      </t>
    </section>

    <section title="JSON Serialization">

      <t>
	The JSON Serialization represents encrypted content as a JSON object with
	a <spanx style="verb">recipients</spanx> member
	containing an array of per-recipient information,
	an <spanx style="verb">initialization_vector</spanx> member
	containing a shared Encoded JWE Initialization Vector value,
	and a <spanx style="verb">ciphertext</spanx> member
	containing a shared Encoded JWE Ciphertext value.
	Each member of the <spanx style="verb">recipients</spanx> array is a JSON object with
	a <spanx style="verb">header</spanx> member
	containing an Encoded JWE Header value,
	an <spanx style="verb">encrypted_key</spanx> member
	containing an Encoded JWE Encrypted Key value,
	and an <spanx style="verb">integrity_value</spanx> member
	containing an Encoded JWE Integrity Value value.
      </t>
      <t>
	Unlike the compact serialization used by JWEs, content using
	the JSON Serialization MAY be encrypted to more than one
	recipient.  Each recipient requires:

	<list style="symbols">
	  <t>
	    a JWE Header value specifying the cryptographic parameters
	    used to encrypt the JWE Encrypted Key to that recipient
	    and the parameters used to encrypt the plaintext to
	    produce the JWE Ciphertext;
	    this is represented as an Encoded JWE Header value
	    in the <spanx style="verb">header</spanx> member
	    of an object in the <spanx style="verb">recipients</spanx> array.
	  </t>
	  <t>
	    a JWE Encrypted Key value used to encrypt the ciphertext;
	    this is represented as an Encoded JWE Encrypted Key value
	    in the <spanx style="verb">encrypted_key</spanx> member
	    of the same object in the <spanx style="verb">recipients</spanx> array.
	  </t>
	  <t>
	    a JWE Integrity Value that ensures the integrity of
	    the Ciphertext and the parameters used to create it;
	    this is represented as an Encoded JWE Integrity Value value
	    in the <spanx style="verb">integrity_value</spanx> member
	    of the same object in the <spanx style="verb">recipients</spanx> array.
	  </t>
	</list>

	Therefore, the syntax is:
      </t>
      <figure><artwork><![CDATA[
  {"recipients":[
    {"header":"<header 1 contents>",
     "encrypted_key":"<encrypted key 1 contents>",
     "integrity_value":"<integrity value 1 contents>"},
    ...
    {"header":"<header N contents>",
     "encrypted_key":"<encrypted key N contents>",
     "integrity_value":"<integrity value N contents>"}],
   "initialization_vector":"<initialization vector contents>",
   "ciphertext":"<ciphertext contents>"
  }
]]></artwork></figure>

      <t>
	The contents of the
	Encoded JWE Header,
	Encoded JWE Encrypted Key,
	Encoded JWE Initialization Vector,
	Encoded JWE Ciphertext, and
	Encoded JWE Integrity Value
	values are exactly as
	specified in JSON Web Encryption (JWE) <xref target="JWE" />.
	They are interpreted and validated in the same manner, with
	each corresponding <spanx style="verb">header</spanx>,
	<spanx style="verb">encrypted_key</spanx>, and <spanx
	style="verb">integrity_value</spanx> value being created
	and validated together.
      </t>
      <t>
	Each JWE Encrypted Key value and the
	corresponding JWE Integrity Value are computed using the
	parameters of the corresponding JWE Header value in the same manner
	described in the JWE specification.  This has the desirable
	result that each Encoded JWE Encrypted Key value in the <spanx
	style="verb">recipients</spanx> array and
	each Encoded JWE Integrity Value in the same array element
	are identical to the
	values that would have been computed for the same
	parameters in a JWE, as is the shared JWE Ciphertext value.
      </t>
      <t>
	All recipients use the same JWE Ciphertext and
	JWE Initialization Vector values, resulting in
	potentially significant space savings if the message is large.
	Therefore, all header parameters that specify the treatment of
	the JWE Ciphertext value MUST be the same for all recipients.
	This primarily means that the <spanx
	style="verb">enc</spanx> (encryption method) header parameter
	value in the JWE Header for each recipient MUST be the same.
      </t>
    </section>

    <section title="Example JWE-JS" anchor="JSONSerializationExample">
      <t>
	This section contains an example using the JWE JSON
	Serialization.  This example demonstrates the capability for
	encrypting the same plaintext to multiple recipients.
      </t>

      <t>
	Two recipients are present in this example: the first using the
	RSAES-PKCS1-V1_5 algorithm to encrypt the Content Master Key (CMK)
	and the second using RSAES OAEP to encrypt the CMK.
	The Plaintext is encrypted using the AES CBC algorithm
	and the same block encryption parameters to produce
	the common JWE Ciphertext value.
	The two Decoded JWE Header Segments used are:
      </t>

      <figure><artwork><![CDATA[
  {"alg":"RSA1_5","enc":"A128CBC+HS256"}
]]></artwork></figure>

      <t>
	and:
      </t>

      <figure><artwork><![CDATA[
  {"alg":"RSA-OAEP","enc":"A128CBC+HS256"}
]]></artwork></figure>

      <t>
	The keys used for the first recipient are the same as those in
	Appendix A.2 of <xref target="JWE"/>, as is the plaintext used.
	The asymmetric encryption key used for the second recipient
	is the same as that used in Appendix A.1 of <xref target="JWE"/>;
	the block encryption keys and parameters for the second recipient
	are the same as those for the first recipient
	(which must be the case, since the initialization vector
	and ciphertext are shared).
      </t>

      <t>
	The complete JSON Web Encryption JSON Serialization (JWE-JS)
	for these values is as follows
	(with line breaks for display purposes only):
      </t>

      <figure><artwork><![CDATA[
  {"recipients":[
    {"header":
      "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0",
     "encrypted_key":
      "O6AqXqgVlJJ4c4lp5sXZd7bpGHAw6ARkHUeXQxD1cAW4-X1x0qtj_AN0mukqE
       Ol4Y6UOwJXIJY9-G1ELK-RQWrKH_StR-AM9H7GpKmSEji8QYOcMOjr-u9H1Lt
       _pBEieG802SxWz0rbFTXRcj4BWLxcpCtjUZ31AP-sc-L_eCZ5UNl0aSRNqFsk
       uPkzRsFZRDJqSSJeVOyJ7pZCQ83fli19Vgi_3R7XMUqluQuuc7ZHOWixi47jX
       lBTlWRZ5iFxaS8G6J8wUrd4BKggAw3qX5XoIfXQVlQZE0Vmkq_zQSIo5LnFKy
       owooRcdsEuNh9B9Mkyt0ZQElG-jGdtHWjZSOA",
     "integrity_value":
      "RBGhYzE8_cZLHjJqqHuLhzbgWgL_wV3LDSUrcbkOiIA"},
    {"header":
      "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMrSFMyNTYifQ",
     "encrypted_key":
      "myoFYZHErXG4gMVWl9UrFOCFIwvOUudYrxTsRsOt6maTc3W8G1FqGVOIBSZve
       BdZz2LqS42xta5OXEwLYaocObUxtfH9H8vMsjO-mBo7U9mp_PkS9PqVJMkeEe
       PLhzNLH0ecq7nYT6AFr5sSt4WMOPjSwHVQWtx43fZt4HvYaE_vgeSrxdi8KAb
       xbLzK_-qcYT6H7cwOMZrT6SFcXgLXESuKpF0azSGQtUmo0MLICP0YPBecGLTo
       PiveOH2awKZx0FkzPwi4JmOIvnAJ_wVQQJDVELwO9SIoF8olCQRHGyZ9rzDrr
       GRkoYgm2jVz-x0BuFVQFa4ZNufudtiT8pQxKg",
     "integrity_value":
      "i45dXWFjRKk805VtjIw_8iqGq1r9qPV7ULDLbnNAC_Q"}],
   "initialization_vector":
    "AxY8DCtDaGlsbGljb3RoZQ",
   "ciphertext":
    "1eBWFgcrz40wC88cgv8rPgu3EfmC1p4zT0kIxxfSF2zDJcQ-iEHk1jQM95xAdr5
     Z"
  }
]]></artwork></figure>

    </section>

    <section title="IANA Considerations" anchor="IANA">
      <t>
	This specification makes no requests of IANA.
      </t>
    </section>

    <section title="Security Considerations" anchor="Security">
      <t>
	The security considerations for this specification are the
	same as those for the JSON Web Encryption (JWE) <xref
	target="JWE" /> specification.
      </t>
    </section>

  </middle>

  <back>
    <references title="Normative References">
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml' ?>

      <reference anchor="JWE">
        <front>
          <title>JSON Web Encryption (JWE)</title>

	  <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
	    <organization>Microsoft</organization>
	    <address>
	      <email>mbj@microsoft.com</email>
	      <uri>http://self-issued.info/</uri>
	    </address>
	  </author>

	  <author fullname="Eric Rescorla" initials="E." surname="Rescorla">
	    <organization>RTFM, Inc.</organization>
	    <address>
	      <email>ekr@rtfm.com</email>
	    </address>
	  </author>

	  <author fullname="Joe Hildebrand" initials="J." surname="Hildebrand">
	    <organization>Cisco Systems, Inc.</organization>
	    <address>
	      <email>jhildebr@cisco.com</email>
	    </address>
	  </author>

	  <date day="15" month="October" year="2012" />
        </front>
        <format target="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption" type="HTML" />
      </reference>

      <reference anchor="JWA">
        <front>
	  <title>JSON Web Algorithms (JWA)</title>

	  <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
	    <organization>Microsoft</organization>
	    <address>
	      <email>mbj@microsoft.com</email>
	      <uri>http://self-issued.info/</uri>
	    </address>
	  </author>

	  <date day="15" month="October" year="2012" />
        </front>
        <format target="http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms" type="HTML" />
      </reference>

    </references>

    <references title="Informative References">
      <?rfc include="http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-rescorla-jsms-00.xml" ?>

      <reference anchor="JWS-JS">
        <front>
          <title>JSON Web Signature JSON Serialization (JWS-JS)</title>

	  <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
	    <organization>Microsoft</organization>
	    <address>
	      <email>mbj@microsoft.com</email>
	      <uri>http://self-issued.info/</uri>
	    </address>
	  </author>

	  <author fullname="John Bradley" initials="J." surname="Bradley">
	    <organization>independent</organization>
	    <address>
	      <email>ve7jtb@ve7jtb.com</email>
	    </address>
	  </author>

	  <author fullname="Nat Sakimura" initials="N." surname="Sakimura">
	    <organization>Nomura Research Institute</organization>
	    <address>
	      <email>n-sakimura@nri.co.jp</email>
	    </address>
	  </author>

	  <date day="15" month="October" year="2012" />
        </front>
        <format target="http://tools.ietf.org/html/draft-jones-jose-jws-json-serialization" type="HTML" />
      </reference>

      <reference anchor="JSE">
        <front>
          <title>JSON Simple Encryption</title>

	  <author fullname="John Bradley" initials="J." surname="Bradley">
	    <organization>independent</organization>
	  </author>

	  <author fullname="Nat Sakimura (editor)" initials="N. " surname="Sakimura (editor)">
	    <organization>Nomura Research Institute</organization>
	  </author>

          <date month="September" year="2010" />
        </front>
        <format target="http://jsonenc.info/enc/1.0/" type="HTML" />
      </reference>

    </references>

    <section title="Acknowledgements" anchor="Acknowledgements">

      <t>
	JSON serializations for encrypted content were previously explored by
	<xref target="JSE">JSON Simple Encryption</xref> and
	<xref target="I-D.rescorla-jsms">JavaScript Message Security
	Format</xref>.
      </t>

    </section>

    <section title="Open Issues" anchor="TBD">
      <t>
	[[ to be removed by the RFC editor before publication as an RFC ]]
      </t>

      <t>
	The following items remain to be considered or done in this draft:

	<list style="symbols">

	  <t>
	    Track changes that occur in the JWE spec.
	  </t>
	</list>
      </t>
    </section>

    <section title='Document History'>
      <t>
	[[ to be removed by the RFC editor before publication as an RFC ]]
      </t>

      <t>
	-02
	<list style='symbols'>
	  <t>
	    Changed to use an array of structures for per-recipient values,
	    rather than a set of parallel arrays.
	  </t>
	  <t>
	    Promoted Initialization Vector from being a header parameter to being
	    a top-level JWE element.
	    This saves approximately 16 bytes in the compact serialization,
	    which is a significant savings for some use cases.
	    Promoting the Initialization Vector out of the header also avoids repeating
	    this shared value in the JSON serialization.
	  </t>
	</list>
      </t>
      <t>
	-01
	<list style='symbols'>
	  <t>
	    Added a complete JWE-JS example.
	  </t>
	  <t>
	    Generalized language to refer to Message Authentication Codes (MACs)
	    rather than Hash-based Message Authentication Codes (HMACs).
	  </t>
	</list>
      </t>
      <t>
	-00
	<list style='symbols'>
	  <t>
	    Renamed draft-jones-json-web-encryption-json-serialization
	    to draft-jones-jose-jwe-json-serialization to have "jose"
	    be in the document name so it can be included in the
	    Related Documents list at http://datatracker.ietf.org/wg/jose/.
	    No normative changes.
	  </t>
	</list>
      </t>
      <t>
        draft-jones-json-web-encryption-json-serialization-02
        <list style='symbols'>
	  <t>
	    Updated examples to track updated algorithm properties in the JWA spec.
	  </t>
          <t>
           Tracked editorial changes made to the JWE spec.
	  </t>
        </list>
      </t>
      <t>
        draft-jones-json-web-encryption-json-serialization-01
        <list style='symbols'>
          <t>
	    Tracked changes between JOSE JWE draft -00 and -01, which
	    added an integrity check for non-AEAD algorithms.
	  </t>
        </list>
      </t>
      <t>
        draft-jones-json-web-encryption-json-serialization-00
        <list style='symbols'>
          <t>
            Created the initial version incorporating JOSE working
            group input and drawing from the JSON Serialization
            previously proposed in draft-jones-json-web-token-01.
	  </t>
        </list>
      </t>
    </section>     

  </back>
</rfc>