[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                                        E. Rescorla
Internet-Draft                                                RTFM, Inc.
Intended status:  Standards Track                          J. Hildebrand
Expires:  September 8, 2011                          Cisco Systems, Inc.
                                                           March 7, 2011


                   JavaScript Message Security Format
                       draft-rescorla-jsms-00.txt

Abstract

   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.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on September 8, 2011.

Copyright Notice

   Copyright (c) 2011 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must



Rescorla & Hildebrand   Expires September 8, 2011               [Page 1]


Internet-Draft                    JSMS                        March 2011


   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

   This document may contain material from IETF Documents or IETF
   Contributions published or made publicly available before November
   10, 2008.  The person(s) controlling the copyright in some of this
   material may not have granted the IETF Trust the right to allow
   modifications of such material outside the IETF Standards Process.
   Without obtaining an adequate license from the person(s) controlling
   the copyright in such materials, this document may not be modified
   outside the IETF Standards Process, and derivative works of it may
   not be created outside the IETF Standards Process, except to format
   it for publication as an RFC or to translate it into languages other
   than English.




































Rescorla & Hildebrand   Expires September 8, 2011               [Page 2]


Internet-Draft                    JSMS                        March 2011


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
   2.  Conventions Used In This Document  . . . . . . . . . . . . . .  4
   3.  Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
     3.1.  Operational Modes  . . . . . . . . . . . . . . . . . . . .  4
     3.2.  Conventions  . . . . . . . . . . . . . . . . . . . . . . .  5
     3.3.  Certificate Processing . . . . . . . . . . . . . . . . . .  6
     3.4.  Certificate Discovery  . . . . . . . . . . . . . . . . . .  6
   4.  Message Format . . . . . . . . . . . . . . . . . . . . . . . .  6
     4.1.  Base64 Handling  . . . . . . . . . . . . . . . . . . . . .  6
     4.2.  Content Object . . . . . . . . . . . . . . . . . . . . . .  7
     4.3.  Common Elements  . . . . . . . . . . . . . . . . . . . . .  7
     4.4.  Signed Data  . . . . . . . . . . . . . . . . . . . . . . .  8
       4.4.1.  Signature Computation  . . . . . . . . . . . . . . . .  9
       4.4.2.  Signature Verification . . . . . . . . . . . . . . . . 10
     4.5.  Encrypted Data . . . . . . . . . . . . . . . . . . . . . . 12
       4.5.1.  Message Encryption . . . . . . . . . . . . . . . . . . 13
       4.5.2.  Message Decryption . . . . . . . . . . . . . . . . . . 13
       4.5.3.  Key Derivation . . . . . . . . . . . . . . . . . . . . 14
       4.5.4.  CMK Encryption . . . . . . . . . . . . . . . . . . . . 14
     4.6.  Composition  . . . . . . . . . . . . . . . . . . . . . . . 15
   5.  Version Processing . . . . . . . . . . . . . . . . . . . . . . 15
   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 15
   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 15
   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 15
     8.2.  Informative References . . . . . . . . . . . . . . . . . . 17
   Appendix A.  JSON Schema . . . . . . . . . . . . . . . . . . . . . 17
     A.1.  Message Contents Schema  . . . . . . . . . . . . . . . . . 18
     A.2.  Common Elements Schema . . . . . . . . . . . . . . . . . . 19
     A.3.  Signed Message Schema  . . . . . . . . . . . . . . . . . . 20
     A.4.  PKIX Certificate Chain Schema  . . . . . . . . . . . . . . 21
     A.5.  Encrypted Message Schema . . . . . . . . . . . . . . . . . 21
     A.6.  Recipient Schema . . . . . . . . . . . . . . . . . . . . . 23
   Appendix B.  Acknowledgments . . . . . . . . . . . . . . . . . . . 23
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23














Rescorla & Hildebrand   Expires September 8, 2011               [Page 3]


Internet-Draft                    JSMS                        March 2011


1.  Introduction

   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.

   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 [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).


2.  Conventions Used In This Document

   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 [RFC2119].


3.  Overview

   The JSMS message format is simply a JSON [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.

3.1.  Operational Modes

   JSMS supports two operational modes:

   Encrypted Data
      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.




Rescorla & Hildebrand   Expires September 8, 2011               [Page 4]


Internet-Draft                    JSMS                        March 2011


   Signed Data
      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.

   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 Section 4.6 for more on composition.

3.2.  Conventions

   In general, JSMS follows the following structural conventions:

   Minimize implementation complexity
      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.
   Base64 as the only encoding
      Any data that does not have a straightforward string
      representation (binary values, large integers, etc.) is base64-
      encoded (see:  [RFC4648]).  In some cases, hexadecimal encodings
      might be more convenient, but consistency is even more important
      to reduce implementation complexity.
   No canonicalization
      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.
   In-memory processing
      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.







Rescorla & Hildebrand   Expires September 8, 2011               [Page 5]


Internet-Draft                    JSMS                        March 2011


3.3.  Certificate Processing

   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 [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]).

3.4.  Certificate Discovery

   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 [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.


4.  Message Format

   All of the field definitions in this section make use of JSON Schema
   [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.

4.1.  Base64 Handling

   As stated in section 3.1 of [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.








Rescorla & Hildebrand   Expires September 8, 2011               [Page 6]


Internet-Draft                    JSMS                        March 2011


   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.

4.2.  Content Object

   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:


   ContentType:  A MIME [RFC2045] media type that MUST be included
      indicating the type of the "Data" field.
   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.
   Data:  The data value MUST be included as a text encoded as Base64
      (See:  [RFC4648]).
   ID:  An OPTIONAL universally unique ID that identifies this message,
      for use in detecting replay attacks.
   Created:  An OPTIONAL field describing the UTC date/time that the
      content was encoded into JSON, formatted according to the "date-
      time" production of [RFC3339].

   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:

   {
       "ContentType":"text/plain; charset=UTF-8",
       "Type":"content",
       "Data":"SGVsbG8sIFdvcmxkCg==",
       "ID":"746a4c9f-8e84-4313-b669-81590ee2949e",
       "Created":"2011-03-07T16:17Z"
   }

                         Figure 1: Content Example

4.3.  Common Elements

   A JSMS message is a JSON dictionary object containing a set of
   specific values.

   The following fields MUST be present in all messages:



Rescorla & Hildebrand   Expires September 8, 2011               [Page 7]


Internet-Draft                    JSMS                        March 2011



   Version:  The version number.  For this specification this value MUST
      be set to the string "1.0".  See Section 5 for details on version
      handling.

   Type:  The type of the message.  MUST be either "signed" or
      "encrypted", to indicate a signed message (Section 4.4) or an
      encrypted message (Section 4.5) respectively.

4.4.  Signed Data

   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
   Section 4.3, the fields in a signature message are:


   SignedData:  This field MUST consist of a Base64-encoded "Content"
      structure (see Section 4.2), 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.

   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 [FIPS-180-3].

   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 [RFC3447].

   Signer:  The signer's identity, expressed as a URI [RFC3986].  This
      field MUST be present.

   CertChain:  The signer's certificate chain, if any (see
      Section 4.4.2.1).

   Signature:  The Base64-encoded signature, which MUST be included (see
      Section 4.4.1).








Rescorla & Hildebrand   Expires September 8, 2011               [Page 8]


Internet-Draft                    JSMS                        March 2011


   {
       "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="
   }

                     Figure 2: Signed Message Example

4.4.1.  Signature Computation

   The signature is computed over the string prior to base64 encoding.
   I.e., the processing order for encoding is:

   1.  Serialize the inner "Content" value into a UTF8-encoded octet
       series X.
   2.  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.)
   3.  Compute the Base64 representation of X and insert it into the
       "SignedData" field of the message.
   4.  Compute the Base64 representation of Y, and insert the result
       into the "Signature" field.

   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.

   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 (Section 4.5), which is designed to avoid multiple
      base64 encoding.

   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



Rescorla & Hildebrand   Expires September 8, 2011               [Page 9]


Internet-Draft                    JSMS                        March 2011


   Section 6.

4.4.2.  Signature Verification

   In order to verify the signature, the steps of the previous section
   are reversed.

   1.  Process the provided "Signer" and "CertChain" fields as described
       in Section 4.4.2.1 in order to determine the sender's public key.
   2.  Base64 decode the "SignedData" field in order to recover a string
       X.
   3.  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.
   4.  Deserialize X to recover the inner "Content" value.
   5.  Check any "ID" or "Created" fields for replay.
   6.  Using the value of the "ContentType" field to give MIME type
       context, Base64-decode the "Data" field to retrieve the intended
       message.

4.4.2.1.  Certificate Processing

   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:


   Type:  The type of the certificate chain.  The only defined value is
      "PKIX", referring to PKIX [RFC5280] certificates.

   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.













Rescorla & Hildebrand   Expires September 8, 2011              [Page 10]


Internet-Draft                    JSMS                        March 2011


   {
       "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="
       ]
   }

                     Figure 3: PKIX CertChain Example

   The recipient MUST verify the certificate chain (in the case of PKIX
   certificates according to [RFC5280]).  If any validation failure
   occurs, the implementation MUST abort processing and return an error.

   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



Rescorla & Hildebrand   Expires September 8, 2011              [Page 11]


Internet-Draft                    JSMS                        March 2011


   subjectAltName field of type "uniformResourceIdentifier".  This field
   MUST be equivalent to the URI in the "Signer" field.  If not, an
   error MUST be returned.

4.5.  Encrypted Data

   An "encrypted" message contains an encrypted "Content" block.  All
   "encrypted" messages contain a symmetric integrity check, either via
   a MAC or via an AEAD [RFC5116] algorithm such as Galois/Counter Mode
   (GCM:  [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 Section 4.3 the fields in an encrypted message
   are:

   Recipients:  The list of recipients.  This is an array of Recipient
      objects, each of which establishes the CMK for that recipient.
   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.
   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.
   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.
   Data:  Contains the ciphertext.

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


   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.






Rescorla & Hildebrand   Expires September 8, 2011              [Page 12]


Internet-Draft                    JSMS                        March 2011



      RecipientName:  Provides the recipient's name in URI form.
      CertificateDigest:  For now, the SHA-1 fingerprint of the PKIX
         certificate associated with the recipient.
      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.
   Algorithm:  The algorithm used to encrypt the CMK.  For now, one of
      "RSA-PKCS1-1.5" (meaning RSASSA-PKCS1-v1_5 as specified in
      [RFC3447]) or "AES-256-CBC" (meaning [FIPS-180-3]).  Note the JSMS
      only supports key transport and not key agreement (since key
      agreement can always be turned into key transport).
   Value:  The CMK encrypted under the specified algorithm and key.

4.5.1.  Message Encryption

   The message encryption process is as follows.

   1.  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 [RFC4086] for
       considerations on generating random values. [[ TODO - we need a
       section on generating randomness in browsers - it's easy to screw
       up ]]
   2.  Encrypt the CMK for each recipient (see Section 4.5.4)
   3.  Generate a random IV (if required for the algorithm).
   4.  Run the key derivation algorithm (see Section 4.5.3) to generate
       the CEK and CIK (if not using an AEAD algorithm).
   5.  Serialize the content into a bitstring M.
   6.  Encrypt M using the CEK and IV to form the bitstring C.
   7.  Set the Value element equal to the base64-encoded representation
       of C.
   8.  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:  [krawczyk-ate]).  Set the Integrity.Value element equal to
       the base64-encoded representation of I.

4.5.2.  Message Decryption

   The message decryption process is the reverse of the encryption
   process.

   1.  Identify a Recipient block which appears to reference a key known
       to the recipient.
   2.  Decrypt the CMK.  If this fails and another Recipient block
       appears plausible, that MAY be tried.




Rescorla & Hildebrand   Expires September 8, 2011              [Page 13]


Internet-Draft                    JSMS                        March 2011


   3.  Run the key derivation algorithm (see Section 4.5.3) to generate
       the CEK and CIK (if not using an AEAD algorithm).
   4.  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.
   5.  Decrypt the binary representation of the Value element and output
       the result

4.5.3.  Key Derivation

   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:
   MasterKey:  The master key used to compute the individual use keys
   Label:  The use key label, used to differentiate individual use keys
   Length:  The length of the desired use key
   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 [RFC5246] PRF using P_XXX
   as the underlying P_hash function.

   To compute the CEK from the CMK, the label "Encryption" is used.

   To compute the CIK from the CMK, the label "Integrity" is used.

   When AEAD algorithms are used the KDF element MUST NOT be present.
   When they are not used, it MUST be present.

4.5.4.  CMK Encryption

   JSMS supports two forms of CMK encryption:

   o  Asymmetric encryption under the recipient's public key.
   o  Symmetric encryption under a shared key.

4.5.4.1.  Asymmetric Encryption

   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 [RFC3447] RSAES-
   PKCS1-v1_5.






Rescorla & Hildebrand   Expires September 8, 2011              [Page 14]


Internet-Draft                    JSMS                        March 2011


4.5.4.2.  Symmetric Encryption

   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 [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.

4.6.  Composition

   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.


5.  Version Processing

   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.


6.  IANA Considerations

   [TODO]
   o  Register MIME types
   o  Registries for signature, encryption, MAC
   o  Well known HTTP URLs


7.  Security Considerations

   Much more to follow here.


8.  References

8.1.  Normative References

   [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part One: Format of Internet Message



Rescorla & Hildebrand   Expires September 8, 2011              [Page 15]


Internet-Draft                    JSMS                        March 2011


              Bodies", RFC 2045, November 1996.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3339]  Klyne, G., Ed. and C. Newman, "Date and Time on the
              Internet: Timestamps", RFC 3339, July 2002.

   [RFC3447]  Jonsson, J. and B. Kaliski, "Public-Key Cryptography
              Standards (PKCS) #1: RSA Cryptography Specifications
              Version 2.1", RFC 3447, February 2003.

   [RFC4086]  Eastlake, D., Schiller, J., and S. Crocker, "Randomness
              Requirements for Security", BCP 106, RFC 4086, June 2005.

   [RFC4627]  Crockford, D., "The application/json Media Type for
              JavaScript Object Notation (JSON)", RFC 4627, July 2006.

   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
              Encodings", RFC 4648, October 2006.

   [RFC5116]  McGrew, D., "An Interface and Algorithms for Authenticated
              Encryption", RFC 5116, January 2008.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246, August 2008.

   [RFC5280]  Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
              Housley, R., and W. Polk, "Internet X.509 Public Key
              Infrastructure Certificate and Certificate Revocation List
              (CRL) Profile", RFC 5280, May 2008.

   [RFC5649]  Housley, R. and M. Dworkin, "Advanced Encryption Standard
              (AES) Key Wrap with Padding Algorithm", RFC 5649,
              September 2009.

   [I-D.zyp-json-schema]
              Zyp, K. and G. Court, "A JSON Media Type for Describing
              the Structure and Meaning of JSON Documents",
              draft-zyp-json-schema-03 (work in progress),
              November 2010.

   [FIPS-180-3]
              National Institute of Standards and Technology (NIST),
              "Secure Hash Standard (SHS)", FIPS PUB 180-3,
              October 2008.





Rescorla & Hildebrand   Expires September 8, 2011              [Page 16]


Internet-Draft                    JSMS                        March 2011


8.2.  Informative References

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, January 2005.

   [I-D.hammer-webfinger]
              Hammer-Lahav, E., Fitzpatrick, B., and B. Cook, "The
              WebFinger Protocol", draft-hammer-webfinger-00 (work in
              progress), October 2009.

   [RFC5652]  Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
              RFC 5652, September 2009.

   [krawczyk-ate]
              Krawczyk, H., "The Order of Encryption and Authentication
              for Protecting Communications (or: How Secure Is SSL?)",
              Advances in cryptology--CRYPTO 2001 August 2001.

   [GCM]      National Institute of Standards and Technology (NIST),
              "Recommendation for Block Cipher Modes of Operation:
              Galois/Counter Mode (GCM) and GMAC", SP 800-38D,
              November 2007.


Appendix A.  JSON Schema

   The following schemas formally define various namespaces used in this
   document, in conformance with [I-D.zyp-json-schema].  Because
   validation of JSON documents is optional, these schemas are not
   normative and are provided for descriptive purposes only.




















Rescorla & Hildebrand   Expires September 8, 2011              [Page 17]


Internet-Draft                    JSMS                        March 2011


A.1.  Message Contents Schema

   {
       "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"
           }
       }
   }


















Rescorla & Hildebrand   Expires September 8, 2011              [Page 18]


Internet-Draft                    JSMS                        March 2011


A.2.  Common Elements Schema

   {
       "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"]
           }
       }
   }

































Rescorla & Hildebrand   Expires September 8, 2011              [Page 19]


Internet-Draft                    JSMS                        March 2011


A.3.  Signed Message Schema

   {
       "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
                   }
               }
           }
       }
   }






Rescorla & Hildebrand   Expires September 8, 2011              [Page 20]


Internet-Draft                    JSMS                        March 2011


A.4.  PKIX Certificate Chain Schema

   {
       "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"
               }
           }
       }
   }

A.5.  Encrypted Message Schema

   {
       "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":{



Rescorla & Hildebrand   Expires September 8, 2011              [Page 21]


Internet-Draft                    JSMS                        March 2011


                   "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
           }
       }
   }

















Rescorla & Hildebrand   Expires September 8, 2011              [Page 22]


Internet-Draft                    JSMS                        March 2011


A.6.  Recipient Schema

   {
       "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"
           }
       }
   }


Appendix B.  Acknowledgments

   [TODO]









Rescorla & Hildebrand   Expires September 8, 2011              [Page 23]


Internet-Draft                    JSMS                        March 2011


Authors' Addresses

   Eric Rescorla
   RTFM, Inc.
   2064 Edgewood Drive
   Palo Alto, CA  94303
   USA

   Email:  ekr@rtfm.com


   Joe Hildebrand
   Cisco Systems, Inc.
   1899 Wyknoop Street, Suite 600
   Denver, CO  80202
   USA

   Email:  jhildebr@cisco.com

































Rescorla & Hildebrand   Expires September 8, 2011              [Page 24]


Html markup produced by rfcmarkup 1.124, available from https://tools.ietf.org/tools/rfcmarkup/