<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2045 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml">
<!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY rfc3339 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml">
<!ENTITY rfc3447 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3447.xml">
<!ENTITY rfc3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY rfc4086 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4086.xml">
<!ENTITY rfc4627 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
<!ENTITY rfc4648 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY rfc5116 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5116.xml">
<!ENTITY rfc5246 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml">
<!ENTITY rfc5280 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5280.xml">
<!ENTITY rfc5649 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5649.xml">
<!ENTITY rfc5652 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5652.xml">

<!ENTITY webfinger SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hammer-webfinger-00.xml">
<!ENTITY jsonschema SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-zyp-json-schema-03.xml">
]>
<!-- $Id -->
<?rfc inline="yes"?>
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<?rfc compact="yes" ?>
<?rfc sortrefs="no" ?>
<?rfc colonspace='yes' ?>
<rfc category="std" docName="draft-rescorla-jsms-00.txt"
     ipr="pre5378Trust200902">
  <front>
    <title abbrev="JSMS">JavaScript Message Security Format</title>

    <author fullname="Eric Rescorla" initials="E." surname="Rescorla">
      <organization>RTFM, Inc.</organization>

      <address>
        <postal>
          <street>2064 Edgewood Drive</street>

          <city>Palo Alto</city>

          <region>CA</region>

          <code>94303</code>

          <country>USA</country>
        </postal>

        <email>ekr@rtfm.com</email>
      </address>
    </author>

    <author fullname="Joe Hildebrand" initials="J." surname="Hildebrand">
      <organization>Cisco Systems, Inc.</organization>

      <address>
        <postal>
          <street>1899 Wyknoop Street, Suite 600</street>

          <city>Denver</city>

          <region>CO</region>

          <code>80202</code>

          <country>USA</country>
        </postal>

        <email>jhildebr@cisco.com</email>
      </address>
    </author>

    <date day="7" month="March" year="2011" />

    <abstract>
      <t>Many applications require the ability to send
      cryptographically secured messages. While the IETF has defined a
      number of formats for such messages (e.g. CMS) those formats use
      encodings which are not congenial for Web applications. This
      document describes a new cryptographic message format which is
      based on JavaScript Object Notation (JSON) and thus is easy for
      Web applications to generate and parse.</t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <t>Many applications require the ability to send
      cryptographically secured (encrypted, digitally signed, etc.)
      messages. While the IETF has defined a number of formats for
      such messages, those formats are widely viewed as being
      excessively complicated for the demands of Web applications,
      which typically only need the ability to secure simple
      messages. In addition, existing formats use encoding mechanisms
      (e.g., ASN.1 BER/DER) which are not congenial for Web
      applications. This presents an obstacle to the deployment of
      strong security by such applications.</t>

      <t>This document describes a new cryptographic message format,
      JavaScript Message Security (JSMS) intended to meet the need of
      the Web environment. While JSMS is modeled on existing formats
      -- principally CMS <xref target="RFC5652"/> -- it uses
      JavaScript Object Notation (JSON) rather than ASN.1/BER/DER,
      making it far easier for Web applications to handle. In the
      interest of simplicity, JSMS also omits as many as possible of
      the CMS modes (multiple signatures, password-based
      encryption).</t>
    </section>

    <section title="Conventions Used In This Document">
      <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"/>.</t>
    </section>

    <section title="Overview">
      <t>The JSMS message format is simply a JSON <xref
      target="RFC4627"/> dictionary with an appropriate
      collection of fields.  Each operating mode will have a separate
      set of fields, with a common field to distinguish between the
      modes.
      </t>

      <section title="Operational Modes">
        <t>JSMS supports two operational modes:</t>

        <t><list style="hanging">
            <t hangText="Encrypted Data"></t>

            <t>A block of data encrypted under a random message
            encryption key (MEK). The MEK is then separately encrypted
            for each recipient, either via symmetric or asymmetric
            encryption. The data is always integrity protected, either
            via a separate Message Authentication Code (MAC) or an
            Authenticated Encryption with Associated Data (AEAD)
            algorithm such as AES-GCM or AES-CCM.</t>

            <t hangText="Signed Data"></t>

            <t>A block of data signed by a single signer using his asymmetric
            key and optionally carrying his certificate. Multiple signatures
            are not permitted in order to keep things simple.</t>
          </list></t>

        <t>Any other desired security functions are provided by composition of
        these modes. For instance, a signed and encrypted message is produced
        by first creating a Signed message and then encrypting that data. (See
        <xref target="sec.msg-composition"/> for more on
        composition.</t>
      </section>

      <section title="Conventions">
        <t>In general, JSMS follows the following structural conventions:</t>

        <t><list style="hanging">
          <t hangText="Minimize implementation complexity"></t>

          <t>Wherever possible, protocol choices have been made such
          that the time and effort required to implement the protocol
          in many different programming languages will be minimized.
          This means that optimizations for bandwidth, CPU, and memory
          utilization have been explicitly avoided.</t>

          <t hangText="Base64 as the only encoding"></t>

          <t>Any data that does not have a straightforward string
          representation (binary values, large integers, etc.) is
          base64-encoded (see: <xref target="RFC4648"/>). In
          some cases, hexadecimal encodings might be more convenient,
          but consistency is even more important to reduce
          implementation complexity.</t>

          <t hangText="No canonicalization"></t>

          <t>In many cryptographic message formats, canonical
          encodings are used to allow the same value to be computed at
          both sender and recipient (e.g., for digital
          signatures). This is inconvenient in JSON, which just views
          messages as a bundle of key/value pairs. Instead, whenever
          canonicalization would be required, the relevant data is
          serialized and base64-encoded for transport, allowing both
          sides to run computations over the same original set of
          octets.</t>

          <t hangText="In-memory processing"></t>

          <t>We assume that the entire message can fit in main memory
          and make no effort to design a wire representation which can
          be handled in small chunks in a single pass. This means, for
          instance, that there is no need to have a message digest
          indicator at the beginning of the message and then the
          signature at the end, as is done in CMS. Fields are simply
          serialized in whatever order is most convenient for the JSON
          implementation. The examples in this document are generally
          shown in whatever order seems most readable and are not
          normative.</t>
        </list></t>
      </section>

      <section title="Certificate Processing">
        <t>Experience has shown that certificate handling (path
        construction) is one of the trickier parts of building a
        cryptographic system. While JSMS supports PKIX certificates,
        its certificate processing is far simpler than that of
        CMS. When a JSMS agent provides its certificate, it must
        provide an ordered chain (as in TLS <xref target="RFC5246"/>)
        terminating in its own certificate, thus removing the need to
        construct certificate paths. The certificates MUST be ordered
        with the end-entity certificate first and each certificate
        that follows signing the certificate immediately preceding it.
        In addition, because many implementations will not want to do
        any ASN.1/BER processing at all, we will define a Web Service
        which applications can use for chain validation and
        translation to an easy-to-parse format. (See [TODO]).</t>
      </section>

      <section title="Certificate Discovery">
        <t>JSMS will often be used in an online messaging environment
        with users that have an address of the form user@domain, such as
        email, XMPP, or SIP.  As such, protocols such as WebFinger
        <xref target="I-D.hammer-webfinger"/> or an end-to-end
        protocol can be used to retrieve appropriate certificates.
        Downstream uses of JSMS SHOULD define a discovery mechanism
        suitable for the intended use.</t>
      </section>
    </section>

    <section title="Message Format">
      <t>All of the field definitions in this section make use of JSON
      Schema <xref target="I-D.zyp-json-schema"/>.  For each of the
      fields that is designed to hold an enumerated value, a registry
      will be created allowing other values to be used in addition to
      the values enumerated in the schema.</t>

      <section anchor="sec.base64" title="Base64 Handling">
        <t>As stated in section 3.1 of <xref target="RFC4648"/>,
        Base64 does not require linefeeds after a specific number of
        characters.  Since linefeeds are not valid characters in a
        JSON string, whenever a field is specified to be
        Base64-encoded in this document, it MUST NOT include any line
        breaks.  Base64-encoded fields also MUST NOT include
        JSON-encoded linefeeds such as "\n".  Any linebreaks in the
        middle of Base64-encoded sections of the examples are
        unintended side-effects of the production process.</t>

        <t><list style="hanging">
              <t hangText="Implementation Note:">Much existing Base64-encoding code
              will generate linefeeds every 64 or 76 characters of output.
              Ensure that these linefeeds are removed before inserting the
              output into a JSON structure.</t>
        </list></t>
      </section>

      <section anchor="sec.content" title="Content Object">
        <t>JSMS operates by providing transformations on "Content" objects,
        which are just mime-typed JSON objects. These objects are then wrapped
        in a signed/encrypted wrapper with the following fields:</t>

        <t><list style="hanging">
            <t></t>

            <t hangText="ContentType:">A MIME <xref target="RFC2045"/>
            media type that MUST be included indicating the type of
            the "Data" field.</t>

            <t hangText="Type:">The constant string "content", to
            facilitate easy determination that this is the target
            content.  This is useful (for example) in certain
            operating conditions where you must continue to unwrap
            layers of signatures until you get to the content.  This
            field MUST be included.</t>

            <t hangText="Data:">The data value MUST be included as a
            text encoded as Base64 (See: <xref target="RFC4648"/>).</t>

            <t hangText="ID:">An OPTIONAL universally unique ID that
            identifies this message, for use in detecting replay
            attacks.</t>

            <t hangText="Created:">An OPTIONAL field describing the UTC
            date/time that the content was encoded into JSON, formatted
            according to the "date-time" production of <xref target="RFC3339"/>.</t>

          </list></t>

        <t>Signing and encryption transform a "Content" object into "Signed"
        and "Encrypted" objects respectively. Verification and decryption
        transform "Signed" and "Encrypted" objects back into "Content"
        objects. For example:</t>

       <figure anchor="fig.content" title="Content Example">
          <!--begin-pdu-->

          <artwork><![CDATA[
{
    "ContentType":"text/plain; charset=UTF-8",
    "Type":"content",
    "Data":"SGVsbG8sIFdvcmxkCg==",
    "ID":"746a4c9f-8e84-4313-b669-81590ee2949e",
    "Created":"2011-03-07T16:17Z"
}]]></artwork>
       </figure>
      </section>

      <section anchor="sec.message-common" title="Common Elements">
        <t>A JSMS message is a JSON dictionary object containing a set
        of specific values.</t>

        <t>The following fields MUST be present in all messages:</t>

        <t><list style="hanging">
            <t></t>

            <t hangText="Version:">The version number. For this specification
            this value MUST be set to the string "1.0".  See <xref
            target="sec.version"/> for details on version handling.</t>

            <t></t>

            <t hangText="Type:">The type of the message. MUST be either
            "signed" or "encrypted", to indicate a signed message (<xref
            target="sec.signed"/>) or an encrypted message (<xref
            target="sec.encrypted"/>) respectively.</t>
        </list></t>

      </section>

      <section anchor="sec.signed" title="Signed Data">
        <t>A "signed" message contains a signed data block plus a digital
        signature over that data. To simplify implementation, only one
        signer is allowed. In addition to the required fields from <xref
        target="sec.message-common"/>, the fields in a signature
        message are:</t>

        <t><list style="hanging">
            <t></t>

            <t hangText="SignedData:">This field MUST consist of a
            Base64-encoded "Content" structure (see <xref
            target="sec.content"/>), which MUST have been
            encoded into octets as UTF-8 prior to Base64-encoding.
            The signature is computed over the UTF-8 octet stream
            before Base64-encoding to ensure that the sender and
            receiver have the exact same representation.</t>

            <t></t>

            <t hangText="DigestAlgorithm:">The message digest used to compute
            the signature. This field MUST be present for RSA-based signatures
            but MAY be omitted for future signatures which do not allow
            flexible digests.  For now, this field MUST have the value
            "SHA-256", meaning the digest algorithm was SHA-256 
        <xref target="FIPS-180-3"/>.
        </t>

            <t></t>

            <t hangText="SignatureAlgorithm:">The signature algorithm used to
            compute the signature. This field MUST be present.  For
            now, this field MUST have the value "RSA-PKCS1-1.5",
            meaning the signature algorithm was RSASSA-PKCS1-v1_5 as
            specified in <xref target="RFC3447"/>.</t>

            <t></t>

            <t hangText="Signer:">The signer's identity, expressed as a URI
            <xref target="RFC3986"/>. This field MUST be present.</t>

            <t></t>

            <t hangText="CertChain:">The signer's certificate chain, if any
            (see <xref target="sec.certificates"/>).</t>

            <t></t>

            <t hangText="Signature:">The Base64-encoded signature, which
            MUST be included (see <xref target="sec.signature_computation"/>).</t>
        </list></t>

        <figure anchor="fig.signed" title="Signed Message Example">
          <!--begin-pdu-->

          <artwork><![CDATA[
{
    "SignedData":"ewogICAgIkNvbnRlbnRUeXBlIjoidGV4dC9wbGFpbjsgY2hhcn
                  NldD1VVEYtOCIsCiAgICAiVHlwZSI6ImNvbnRlbnQiLAogICAg
                  IkRhdGEiOiJTR1ZzYkc4c0lGZHZjbXhrQ2c9PSIsCiAgICAiSU
                  QiOiI3NDZhNGM5Zi04ZTg0LTQzMTMtYjY2OS04MTU5MGVlMjk0
                  OWUiLAogICAgIkNyZWF0ZWQiOiIyMDExLTAzLTA3VDE2OjE3Wi
                  IKfQ==",
    "DigestAlgorithm":"SHA-256",
    "SignatureAlgorithm":"RSA-PKCS1-1.5",
    "Signer":"xmpp:romeo@example.net",
    "Signature":"sNsxJltUaz4pSzAtJiPZagUMV4SwWugWexGbffK/WJRDi2uq7TxN
                 /V9SwG/kvQ7CaTABbeUuc6cKGO5YxnH5hME3bHB5L9PKPWSjxzxo
                 68RPxQyPli2YJDDHKVPbofEa86CLqYcwTF5qrcL7fQFvlRSOVxpS
                 SJfIdiAJNA+nEnk="
}]]></artwork>
        </figure>

        <section anchor="sec.signature_computation"
                 title="Signature Computation">
          <t>The signature is computed over the string prior to base64
          encoding. I.e., the processing order for encoding is:</t>

          <t><list style="numbers">
              <t>Serialize the inner "Content" value into a
              UTF8-encoded octet series X.</t>

              <t>Compute the signature value over X, and call the
              result Y. (In the case of signatures which use digests,
              this means feed the literal octets of the signature into
              the digest function.)</t>

              <t>Compute the Base64 representation of X and insert it into the
              "SignedData" field of the message.</t>

              <t>Compute the Base64 representation of Y, and insert the result
              into the "Signature" field.</t>

           </list></t>

          <t>This procedure removes dependencies on the exact serialization
          algorithm; variation in spacing, field order, etc. do not affect
          signature validity since the Base64 representation preserves them on
          the wire and protects them from modification by intermediaries.</t>

          <t><list style="hanging">
              <t hangText="Note:">An alternative algorithm would be to compute
              the signature on the base64 representation itself, but this has
              two disadvantages: (1) any intermediaries which change
              spacing/line breaks would break the signature. (2) it is
              inconsistent with the algorithm for encryption (<xref
              target="sec.encrypted"/>), which is designed to avoid
              multiple base64 encoding.</t>
            </list></t>

          <t>This procedure only specifies the input to the signature
          computation. The details of the computation depend on the signature
          algorithm itself. The mapping from code points to algorithms is
          found in <xref target="sec.iana-cons"/>.</t>
        </section>

        <section anchor="sec.signature_verification"
                 title="Signature Verification">
          <t>In order to verify the signature, the steps of the previous
          section are reversed.</t>

          <t><list style="numbers">
              <t>Process the provided "Signer" and "CertChain" fields as
              described in <xref target="sec.certificates"/> in order to
              determine the sender's public key.</t>

              <t>Base64 decode the "SignedData" field in order to recover a string
              X.</t>

              <t>Verify the "Signature" field against X using the sender's
              public key and the "SignatureAlgorithm" and "DigestAlgorithm"
              fields. If the signature fails, return an error.</t>

              <t>Deserialize X to recover the inner "Content"
              value.</t>

              <t>Check any "ID" or "Created" fields for replay.</t>

              <t>Using the value of the "ContentType" field to give
              MIME type context, Base64-decode the "Data" field to
              retrieve the intended message.</t>
            </list></t>
          <t></t>

          <section anchor="sec.certificates" title="Certificate Processing">
            <t>JSMS uses the "CertChain" element to carry certificate
            chains.  For the moment, each certificate in the chain is
            expected to be a PKIX certificate BER-encoded then
            Base64-encoded.  Future versions of this document will
            likely specify other valid certificate formats, since one
            of the goals of this format is to avoid . The
            meaning of the fields is described below:</t>

            <t><list style="hanging">
                <t></t>

                <t hangText="Type:">The type of the certificate chain. The
                only defined value is "PKIX", referring to PKIX <xref
                target="RFC5280"/> certificates.</t>

                <t></t>

                <t hangText="Chain:">An array of certificate values. In the
                case of "PKIX" certificates this is a list of base64-encoded
                DER/BER PKIX certificate values. PKIX certificates MUST be
                represented in order with each certificate certifying the next
                and the final certificate representing the end-entity.</t>
              </list></t>

              <figure anchor="fig.pkixchain" title="PKIX CertChain Example">
                <!--begin-pdu-->

                <artwork><![CDATA[
{
    "Type":"PKIX",
    "Chain":[
        "MIICPjCCAaegAwIBAgIBETANBgkqhkiG9w0BAQUFADBDMRMwEQ
         YKCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQBGRYHZXhh
         bXBsZTETMBEGA1UEAxMKRXhhbXBsZSBDQTAeFw0wNDA0MzAxND
         I1MzRaFw0wNTA0MzAxNDI1MzRaMEMxEzARBgoJkiaJk/IsZAEZ
         FgNjb20xFzAVBgoJkiaJk/IsZAEZFgdleGFtcGxlMRMwEQYDVQ
         QDEwpFeGFtcGxlIENBMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCB
         iQKBgQDC15dtKHCqW88jLoBwOe7bb9Ut1WpPejQt+SJyR3Ad74
         DpyjCMAMSabltFtG6l5myUDfqR6UD8JZ3Ht2gZVo8RcGrX8ckR
         Tzp+P5mNbnaldF9epFVT5cdoNlPHHTsSpoX+vW6hyt81UKwI17
         m0flz+4qMs0SOEqpjAm2YYmmhH6QIDAQABo0IwQDAdBgNVHQ4E
         FgQUCGivhTPIOUp6+IKTjnBqSiCELDIwDgYDVR0PAQH/BAQDAg
         EGMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEFBQADgYEA
         bPgCdKZh4mQEplQMbHITrTxH+/ZlE6mFkDPqdqMm2fzRDhVfKL
         fvk7888+I+fLlS/BZuKarh9Hpv1X/vs5XK82aIg06hNUWEy7yb
         uMitxV5G2QsOjYDhMyvcviuSfkpDqWrvimNhs25HOL7oDaNnXf
         P6kYE8krvFXyUl63zn2KE=",
        "MIICcTCCAdqgAwIBAgIBEjANBgkqhkiG9w0BAQUFADBDMRMwEQ
         YKCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQBGRYHZXhh
         bXBsZTETMBEGA1UEAxMKRXhhbXBsZSBDQTAeFw0wNDA5MTUxMT
         Q4MjFaFw0wNTAzMTUxMTQ4MjFaMEMxEzARBgoJkiaJk/IsZAEZ
         FgNjb20xFzAVBgoJkiaJk/IsZAEZFgdleGFtcGxlMRMwEQYDVQ
         QDEwpFbmQgRW50aXR5MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCB
         iQKBgQDhauQDMJcCPPQQ87UeTX8Ue/b10HjppIrwo3Xs7bZWln
         +ImYWa8j5od4frntGfwLQX3KuJI6QdfhYjTE+oTfUxuHyq4xpJ
         CfRLJtsnZzCCEgFK6Rq2wQxTi2z8L3pD7DM2fjKye9WqzwEUxh
         LsE/ItFHqLIVgUE0xGo5ryFpX/IwIDAQABo3UwczAhBgNVHREE
         GjAYgRZlbmQuZW50aXR5QGV4YW1wbGUuY29tMB0GA1UdDgQWBB
         QXe5Iw/0TWZuGQECJsFk/AjkHdbTAfBgNVHSMEGDAWgBQIaK+F
         M8g5Snr4gpOOcGpKIIQsMjAOBgNVHQ8BAf8EBAMCBsAwDQYJKo
         ZIhvcNAQEFBQADgYEAACAoNFtoMgG7CjYOrXHFlRrhBM+urcdi
         FKQbNjHA4gw92R7AANwQoLqFb0HLYnq3TGOBJl7SgEVeM+dwRT
         s5OyZKnDvyJjZpCHm7+5ZDd0thi6GrkWTg8zdhPBqjpMmKsr9z
         1E3kWORi6rwgdJKGDs6EYHbpc7vHhdORRepiXc0="
    ]
}]]></artwork>
              </figure>

            <t>The recipient MUST verify the certificate chain (in the
            case of PKIX certificates according to <xref
            target="RFC5280"/>). If any validation failure
            occurs, the implementation MUST abort processing and
            return an error.</t>

            <t>Once the certificate chain is validated, the end-entity
            certificate must contain an identity which matches the "Signer"
            field. In the case of PKIX certificates, the certificate MUST
            contain a subjectAltName field of type
            "uniformResourceIdentifier". This field MUST be equivalent to the
            URI in the "Signer" field. If not, an error MUST be returned.</t>
          </section>
        </section>
     </section>

      <section anchor="sec.encrypted" title="Encrypted Data">
        <t>An "encrypted" message contains an encrypted "Content"
        block. All "encrypted" messages contain a symmetric integrity
        check, either via a MAC or via an AEAD <xref
        target="RFC5116"/> algorithm such as Galois/Counter Mode
        (GCM: <xref target="GCM"/>). A message may be encrypted to an
        arbitrary number of recipients. Each recipient is represented
        by a "Recipient" block, which contains a copy of the keying
        material encrypted for that recipient. Both symmetric and
        asymmetric key establishment is supported. In order to support
        both integrity and encryption, what is carried in the
        Recipient block is a Content Master Key (CMK) which is then
        used with a Key Derivation Function (KDF) to generate the
        Content Encryption Key (CEK) used to encrypt the message and
        the Content Integrity Key (CIK) used with the MAC. In addition
        to the required fields from <xref
        target="sec.message-common"/> the fields in an encrypted
        message are:</t>

        <t></t>

        <t><list style="hanging">
            <t hangText="Recipients:">The list of recipients. This is
            an array of Recipient objects, each of which establishes
            the CMK for that recipient.</t>

            <t hangText="KDF:">Specifies the key derivation function used to
            generate the CEK and the CIK from the CMK. This field MAY be
            absent if an AEAD algorithm is used, in which case the CEK is
            derived by copying the CMK.</t>

            <t hangText="Encryption:">Specifies the properties of the
            encryption. The Algorithm field MUST contain the encryption algorithm
            and the IV field specifies the initialization vector (if required
            for the algorithm).  This field MUST be present.</t>

            <t hangText="Integrity:">Specifies the properties of the integrity
            check. The Algorithm field MUST contain the MAC algorithm and the
            Value field MUST contain the MAC. This field MAY be absent if no
            integrity check is used.</t>

            <t hangText="Data:">Contains the ciphertext.</t>
          </list></t>

        <t>Each Recipient object provides an encrypted copy of the CMK for a
        single recipient.  The meaning of the fields is described below:</t>

        <t><list style="hanging">
            <t></t>

            <t hangText="KEKidentifier">Describes the key encrypting
            key (KEK) used to encrypt the CMK.  Either a
            "RecipientName" or a "KeyIdentifier" MUST be provided. If
            the "RecipientName" is provided, then a
            "CertificateDigest" SHOULD be provided.</t>

            <t><list style="hanging">
                <t hangText="RecipientName:">Provides the recipient's name in
                URI form.</t>

                <t hangText="CertificateDigest:">For now, the SHA-1
                fingerprint of the PKIX certificate associated with
                the recipient.</t>

                <t hangText="KeyIdentifier">The name of a shared symmetric key
                known to both sender and recipient. This need not be globally
                unique as long as it is unique within the recipient's
                context.</t>
              </list></t>

            <t hangText="Algorithm:">The algorithm used to encrypt the
            CMK.  For now, one of "RSA-PKCS1-1.5" (meaning
            RSASSA-PKCS1-v1_5 as specified in <xref
            target="RFC3447"/>) or "AES-256-CBC" (meaning <xref
            target="FIPS-180-3"/>).  Note the JSMS only supports key
            transport and not key agreement (since key agreement can
            always be turned into key transport).</t>

            <t hangText="Value:">The CMK encrypted under the specified
            algorithm and key.</t>
          </list></t>

        <section anchor="sec.encryption" title="Message Encryption">
          <t>The message encryption process is as follows.</t>

          <t><list style="numbers">
              <t>Generate a random CMK. The CMK MUST have a length at least
              equal to that of the larger of the required integrity or
              encryption keys and MUST be generated randomly. See <xref
              target="RFC4086"/> for considerations on generating random
              values. [[ TODO - we need a section on generating randomness in
              browsers - it's easy to screw up ]]</t>

              <t>Encrypt the CMK for each recipient (see <xref
              target="sec.encrypt_cmk"/>)</t>

              <t>Generate a random IV (if required for the algorithm).</t>

              <t>Run the key derivation algorithm (see <xref
              target="sec.key_derivation"/>) to generate the CEK and CIK
              (if not using an AEAD algorithm).</t>

              <t>Serialize the content into a bitstring M.</t>

              <t>Encrypt M using the CEK and IV to form the bitstring C.</t>

              <t>Set the Value element equal to the base64-encoded
              representation of C.</t>

              <t>If not using an AEAD algorithm, compute the function
              I = MAC(CIK, C) using the chosen integrity
              algorithm. Note that this is EtA encryption which is
              considered the best cryptographic choice (See: <xref
              target="krawczyk-ate"/>). Set the Integrity.Value
              element equal to the base64-encoded representation of
              I.</t>
            </list></t>
        </section>

        <section anchor="sec.decryption" title="Message Decryption">
          <t>The message decryption process is the reverse of the encryption
          process.</t>

          <t><list style="numbers">
              <t>Identify a Recipient block which appears to reference a key
              known to the recipient.</t>

              <t>Decrypt the CMK. If this fails and another Recipient block
              appears plausible, that MAY be tried.</t>

              <t>Run the key derivation algorithm (see <xref
              target="sec.key_derivation"/>) to generate the CEK and CIK
              (if not using an AEAD algorithm).</t>

              <t>If not using an AEAD algorithm, compute the integrity check
              value I' on the binary representation of the Value element using
              the indicated integrity check. If the Integrity.Value does not
              match I', then an error MUST be reported and processing MUST be
              aborted.</t>

              <t>Decrypt the binary representation of the Value element and
              output the result</t>
            </list></t>
        </section>

        <section anchor="sec.key_derivation" title="Key Derivation">
          <t>The key derivation process converts the CMK into a CEK. It
          assumes as a primitive a Key Derivation Function (KDF) which
          notionally takes three arguments: <list style="hanging">
              <t hangText="MasterKey:">The master key used to compute the
              individual use keys</t>

              <t hangText="Label:">The use key label, used to differentiate
              individual use keys</t>

              <t hangText="Length:">The length of the desired use key</t>
            </list> The only real KDF specified in this document is the TLS
          PRF, which is invoked as PRF(MasterKey, Label) with an empty seed
          and produces an arbitrary length output. The appropriate number of
          bits (Length) is simply extracted from the beginning of the output.
          The KDF name "P_XXX" in this document refers the the TLS <xref
          target="RFC5246"/> PRF using P_XXX as the underlying P_hash
          function. </t>

          <t>To compute the CEK from the CMK, the label "Encryption" is
          used.</t>

          <t>To compute the CIK from the CMK, the label "Integrity" is
          used.</t>

          <t>When AEAD algorithms are used the KDF element MUST NOT be
          present. When they are not used, it MUST be present.</t>
        </section>

        <section anchor="sec.encrypt_cmk" title="CMK Encryption">
          <t>JSMS supports two forms of CMK encryption:</t>

          <t><list style="symbols">
              <t>Asymmetric encryption under the recipient's public key.</t>

              <t>Symmetric encryption under a shared key.</t>
            </list></t>

          <section anchor="sec.asymmetric_encryption"
                   title="Asymmetric Encryption">
            <t>In the asymmetric encryption mode, the CMK is encrypted under
            the recipient's public key. The only currently defined asymmetric
            encryption mode is RSA-PKCS1-1.5, which refers to <xref
            target="RFC3447"/> RSAES-PKCS1-v1_5.</t>
          </section>

          <section anchor="sec.symmetric_encryption"
                   title="Symmetric Encryption">
            <t>In the symmetric encryption mode, the CMK is encrypted under a
            symmetric key shared between the sender and receiver. All such
            modes MUST provide integrity for the CMK. This document defines
            four such modes: AES-128-CBC, AES-256-CBC referring to the <xref
            target="RFC5649"/> AES key wrapping modes and AES-128-GCM,
            AES-256-GCM, referring to AES encryption with GCM. For GCM the
            random 64-bit IV is prepended to the ciphertext.</t>
          </section>
        </section>
      </section>

      <section anchor="sec.msg-composition" title="Composition">
        <t>This document does not specify a combination signed and encrypted
        mode. However, because the contents of a message can be arbitrary, and
        encryption and data origin authentication can be provided by
        recursively encapsulating multiple JSMS messages. In general, senders
        SHOULD sign the message and then encrypt the result (thus encrypting
        the signature). This prevents attacks in which the signature is
        stripped, leaving just an encrypted message, as well as providing
        privacy for the signer.</t>
      </section>
    </section>

    <section anchor="sec.version" title="Version Processing">
      <t>For the moment, all version numbers in the protocol MUST be
      1.0.  Receivers MUST return an error for any other version
      number.  More interesting version processing will be defined in
      the future.</t>
    </section>

    <section anchor="sec.iana-cons" title="IANA Considerations">
      <t>[TODO] <list style="symbols">
          <t>Register MIME types</t>

          <t>Registries for signature, encryption, MAC</t>

          <t>Well known HTTP URLs</t>
        </list></t>
    </section>
    

    <!--
    <section title="Open Issues">
      <t>Reading the number of ways AEAD is handled differently, I don't want
      it.</t>
    </section>
    -->

    <section anchor="sec.sec-cons" title="Security Considerations">
      <t>Much more to follow here.</t>
    </section>


 </middle>

  <back>
    <references title="Normative References">
      &rfc2045;

      &rfc2119;

      &rfc3339;

      &rfc3447;

      &rfc4086;

      &rfc4627;

      &rfc4648;

      &rfc5116;

      &rfc5246;

      &rfc5280;

      &rfc5649;

      &jsonschema;

      <reference anchor="FIPS-180-3">
        <front>
          <title>Secure Hash Standard (SHS)</title>
          <author>
            <organization>National Institute of Standards and Technology (NIST)
            </organization>
          </author>
          <date month="October" year="2008" />
        </front>
        <seriesInfo name="FIPS" value="PUB 180-3" />
      </reference>

    </references>

    <references title="Informative References">
      &rfc3986;

      &webfinger;
      
      &rfc5652;

      <reference anchor="krawczyk-ate">
        <front>
          <title>The Order of Encryption and Authentication for
          Protecting Communications (or: How Secure Is SSL?)</title>
    
          <author fullname="Hugo Krawczyk" initials="H." surname="Krawczyk">
          </author>
        </front>
        <seriesInfo name="Advances in cryptology--CRYPTO 2001" value="August 2001"/>
      </reference>
      
      <reference anchor="GCM">
        <front>
          <title>Recommendation for Block Cipher Modes of Operation:
          Galois/Counter Mode (GCM) and GMAC</title>
          <author>
            <organization>National Institute of Standards and Technology (NIST)
            </organization>
          </author>
          <date month="November" year="2007" />
        </front>
        <seriesInfo name="SP" value="800-38D" />
      </reference>
    </references>

    <section title="JSON Schema">
      <t>The following schemas formally define various namespaces used
      in this document, in conformance with <xref
      target="I-D.zyp-json-schema"/>.  Because validation of
      JSON documents is optional, these schemas are not normative and
      are provided for descriptive purposes only.</t>

      <section anchor="schema.content" title="Message Contents Schema">
       <figure>
          <!--begin-pdu-->

          <artwork><![CDATA[
{
    "description":"Message Contents",
    "type":"object",
    "properties":{
        "ContentType":{
            "description":"A MIME content type",
            "type":"string",
            "required":true
        },
        "Type":{
            "description":"Dictionary type",
            "type":"string",
            "enum":["content"],
            "required":true
        },
        "Data":{
            "description":"The underlying data",
            "type":"string",
            "required":true
        },
        "ID":{
            "description":"(optional) unique ID for this message",
            "type":"string"
        },
        "Created":{
            "description":"(optional) time the message was created",
            "type":"string",
            "format":"date-time"
        }
    }
}]]></artwork>
        </figure>
      </section>

      <section anchor="schema.common" title="Common Elements Schema">
       <figure>
          <!--begin-pdu-->

          <artwork><![CDATA[
{
    "description":"The basic schema for a JSMS message",
    "type":"object",
    "properties":{
        "Type":{
            "description":"Message type",
            "type":"string",
            "enum":["signed", "encrypted"]
        },
        "Version":{
            "description":"Version number for the message",
            "type":"string",
            "enum":["1.0"]
        }
    }
}]]></artwork>
        </figure>
      </section>

      <section anchor="schema.signed" title="Signed Message Schema">
       <figure>
          <!--begin-pdu-->

          <artwork><![CDATA[
{
    "description":"A signed message",
    "type":"object",
    "extends":message_schema,
    "properties":{
        "Signature":{
            "description":"The signature over the SignedData",
            "type":"object",
            "properties":{
                "SignedData":{
                    "description":"content to be signed, Base64",
                    "type":"string",
                    "required":true
                },
                "DigestAlgorithm":{
                    "description":"",
                    "type":"string",
                    "enum":["SHA-256"] 
                },
                "SignatureAlgorithm":{
                    "description":"",
                    "type":"string",
                    "enum":["RSA-PKCS1-1.5"] 
                },
                "Signer":{
                    "description":"",
                    "type":"string",
                    "format":"uri",
                    "required":true 
                },
                "CertChain": {
                    "description":"the signer's cert chain",
                    "type":"PKIXcertchain"
                },
                "Signature":{
                    "description":"the signature",
                    "type":"string",
                    "required":true
                }
            }
        }
    }
}]]></artwork>
        </figure>
      </section>

      <section anchor="schema.PKIXcertchain" title="PKIX Certificate Chain Schema">
       <figure>
          <!--begin-pdu-->

          <artwork><![CDATA[
{
    "description":"A chain of PKIX certificates",
    "id":"PKIXcertchain",
    "properties":{
        "Type":{
            "description":"The type of certificate chain",
            "type":"string",
            "enum":["PKIX"] },
        "Chain":{
            "description":"PKIX certs ordered from root to end",
            "type":"array",
            "items":{
                "description":"A base64-encoded BER certificate",
                "type":"string"
            }
        }
    }
}]]></artwork>
        </figure>
      </section>

      <section anchor="schema.ecncrypted" title="Encrypted Message Schema">
       <figure>
          <!--begin-pdu-->

          <artwork><![CDATA[
{
    "description":"An encrypted object",
    "type":"object",
    "extends":message_schema,
    "properties":{
        "Recipients":{
            "description":"The list of recipient blocks",
            "type":"array",
            "required":true,
            "items":{
                "description":"A single recipient block",
                "type":"Recipient"
            }
        },
        "KDF":{
            "description":
            "The KDF used to derive the MAC and encryption keys",
            "type":"string",
            "enum":["P_SHA256"]
        },
        "Encryption":{
            "description":"Encryption control information",
            "type":"object",
            "required":true,
            "properties":{
                "Algorithm":{
                    "description":"The algorithm used to encrypt",
                    "type":"string",
                    "enum":["AES-256-CBC"]
                },
                "IV":{
                    "description":"Initialization vector (base64)",
                    "type":"string"
                } 
            }
        },
        "Integrity":{
            "description":"The integrity control information",
            "type":"object",
            "properties":{
                "Algorithm":{
                    "description":"The MAC algorithm",
                    "type":"string",
                    "enum":["HMAC-SHA-256"]
                },
                "Value":{
                    "description":"The MAC value (base64-encoded)",
                    "type":"string",
                    "required":true
                }
            }
        },
        "Data":{
            "description":"The ciphertext (Base64-encoded)",
            "type":"string",
            "required":true
        }
    }
}]]></artwork>
        </figure>
      </section>


      <section anchor="schema.recipient" title="Recipient Schema">
       <figure>
          <!--begin-pdu-->

          <artwork><![CDATA[
{
    "description":"The recipient of an encrypted object",
    "type":"object",
    "id":"Recipient",
    "properties":{
        "KEKidentifier":{
            "type":"object",
            "description":"Identifies the key encrypting key",
            "properties":{
                "RecipientName":{
                    "type":"string",
                    "description":"The recipient's name",
                    "format":"uri"
                },
                "CertificateDigest":{
                    "type":"string",
                    "description":"Recipient's cert fingerprint"
                },
                "KeyIdentifier":{
                    "type":"string",
                    "description": "Shared symmetric key (opaque)"
                }
            }
        },
        "Algorithm":{
            "description":"The algorithm used to protect the CMK",
            "type":"string",
            "enum":["RSA-PKCS1-1.5", "AES-256-CBC"]
        },
        "Value":{
            "description": "Base64 of the encrypted CMK",
            "type":"string"
        }
    }
}]]></artwork>
        </figure>
      </section>

    </section>



    <section title="Acknowledgments">
      <t>[TODO]</t>
    </section>
  </back>
</rfc>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
