<?xml version="1.0" encoding="US-ASCII"?>
<?xml-stylesheet type='text/xsl' href='http://xml.resource.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-smith-oauth-json-web-document-00"
     ipr="trust200902">
  <front>
    <title abbrev="JWD">JSON Web Document (JWD)</title>

    <author fullname="Christian Smith" initials="C." surname="Smith">
      <organization>MIT</organization>

      <address>
        <email>csmth@mit.edu</email>
      </address>
    </author>

    <author fullname="Thomas Hardjono" initials="T." surname="Hardjono">
      <organization>MIT</organization>

      <address>
        <email>hardjono@mit.edu</email>
      </address>
    </author>

    <date day="6" month="February" year="2017"/>

    <area>Security</area>

    <workgroup>OAuth Working Group</workgroup>

    <keyword>Sample</keyword>

    <keyword>Draft</keyword>

    <abstract>
      <t>
        JSON Web Document (JWD) is a means of representing optionally
        signed and/or encrypted JSON content suitable for storage, retrieval,
        transmission, and display in a graphical user interface. The content
        of a JWD is used as the payload of a JSON Web Signature (JWS) structure
        or as the plaintext of a JSON Web Encryption (JWE) structure.
      </t>
    </abstract>

    <note title="Requirements Language">
      <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 <xref
      target="RFC2119">RFC 2119</xref>.</t>
    </note>
  </front>

  <middle>
    <section title="Introduction">
      <t>
        JWD introduces a new set of serializations to JWS and JWE called the
        Document Serializations. These serializations follow the form of the JSON
        Serialization and Flattened JSON Serialization described in
        <eref target="https://tools.ietf.org/html/rfc7515#section-7.2">JWS Section 7.2</eref>,
        except that the payload, integrity-protected header, and non-integrity-protected
        header contents are all represented as unencoded JSON values and MUST NOT
        be base64url-encoded.
      </t>
      <t>
        Signatures present in the data structure MUST be base64url-encoded.
        Signatures are computed using base64url-encoded JSON values for the payload and
        integrity-protected headers as in JWS. For a given payload and JOSE Header, the
        signature(s) of a JWD MUST be identical to signatures computed for semantically
        equivalent JWT serializations.
      </t>
    </section>

    <section title="Terminology">
      <t>This specification uses terms defined in the JSON Web Token [JWT],
      JSON Web Signature [JWS], and JSON Web Encryption [JWE] specifications.</t>

      <t>These terms are defined by this specification:
        <list style="hanging">
          <t>JSON Web Document (JWD)
            <list style="empty">
              <t>
                A data structure representing a digitally signed, MACed, or encrypted JSON document.
              </t>
            </list>
          </t>

          <t>JWS Document Serialization
            <list style="empty">
              <t>
                A representation of the JWD as a JSON document.  Unlike the JWS
                JSON Serialization, the JWS Document Serialization represents
                the JWS Payload and integrity-protected JOSE Header parameters
                as unencoded JSON values. This representation simplifies storage
                and retrieval of signed content with document stores and search
                engines, as well as display in applications.
              </t>
            </list>
          </t>

        </list>
      </t>
    </section>

    <section title="JWS Document Serialization">
      <figure anchor="jws_document_serialization_example">
          <artwork><![CDATA[
{
  "payload": <payload contents>,
  "signatures": [
    {
      "protected": <integrity-protected header 1 contents>,
      "header": <non-integrity-protected header 1 contents>,
      "signature": "<signature 1 contents>"
    },
    ...
    {
      "protected": <integrity-protected header N contents>,
      "header": <non-integrity-protected header N contents>,
      "signature": "<signature N contents>"
    }
  ]
}
          ]]></artwork>
      </figure>
    </section>

    <section title="JWS Flattened Document Serialization">
      <figure anchor="jws_flattened_document_serialization_example">
          <artwork><![CDATA[
{
    "payload": <payload contents>,
    "protected": <integrity-protected header contents>,
    "header": <non-integrity-protected header contents>,
    "signature": "<signature contents>"
}
          ]]></artwork>
      </figure>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>TBD</t>
    </section>

    <section anchor="Security" title="Security Considerations">
      <t>TBD</t>
    </section>

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>TBD</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include="reference.RFC.2119"?>
      <?rfc include="reference.RFC.7515"?>
      <?rfc include="reference.RFC.7516"?>
      <?rfc include="reference.RFC.7519"?>
    </references>

    <section title="Example Signed JWD">
      <figure anchor="example_signed_jwd">
          <artwork><![CDATA[
{
  "protected": {
    "alg": "ES512",
    "jku": "https://example.com/jwks"
  },
  "payload": {
    "a": "Please don't BASE64URL encode me!",
    "b": "I need to be indexed!",
    "c": "I need to be rendered!"
  },
  "signature": ""
}
          ]]></artwork>
      </figure>
    </section>
  </back>
</rfc>
