One document matched: draft-barnes-jose-jsms-00.xml
<?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 rfc5083 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5083.xml">
<!ENTITY rfc5840 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5840.xml">
<!ENTITY webfinger SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hammer-webfinger-00.xml">
<!ENTITY jws SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-jose-json-web-signature-02.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-barnes-jose-jsms-00.txt" ipr="trust200902">
<front>
<title abbrev="JSMS">JavaScript Message Security Format</title>
<author fullname="Richard Barnes" initials="R." surname="Barnes">
<organization>BBN Technologies</organization>
<address>
<postal>
<street>1300 N. 17th St.</street>
<city>Arlington</city>
<region>VA</region>
<code>22209</code>
<country>USA</country>
</postal>
<email>rbarnes@bbn.com</email>
</address>
</author>
<date day="15" month="June" year="2012"/>
<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 easy
to use in modern applications. This document describes the JavaScript
Message Security format (JSMS), a new cryptographic message format which
is based on JavaScript Object Notation (JSON) and thus is easy for many
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 DER) which are not congenial for many classes of applications
(e.g., 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). This format is intended to meet the
need of modern applications, including JavaScript-based Web
applications. While JSMS is modeled on existing formats -- principally
CMS <xref target="RFC5652"/> -- it uses JavaScript Object Notation
(JSON) rather than ASN.1, making it far easier for applications to
handle. In the interest of simplicity, JSMS also omits many of less
commonly used CMS modes (such as password-based
encryption).</t>
</section>
<section anchor="sec.conventions"
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>
<t>In order to enable JSON to carry binary data, JSMS makes extensive
use of Base64 encoding <xref target="RFC4648"/>. Whenever this document
refers to Base64 encoding, we mean the URL-safe variant "base64url"
encoding. As stated in section 3.1 of <xref target="RFC4648"/>, Base64
does not allow linefeeds. 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 in
this document have been inserted in order to make the examples fit on
the page. Any trailing "=" characters SHOULD be removed. They are not
needed, because JSON strings have defined lengths (namely the number of
characters between unescaped '"' characters).</t>
</section>
<section title="Overview">
<t>The JSMS message format is simply a JSON <xref target="RFC4627"/>
object 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 three operational modes:<list style="hanging">
<t hangText="Signed Data"/>
<t>A block of data signed by a single signer using his asymmetric
key and optionally carrying his certificate. </t>
<t hangText="Authenticated Data"/>
<t>A block of data with authentication and integrity protection
provided using a symmetric-key Message Authentication Code (MAC).
The MAC key may be provided in encrypted form (as with Encryped
Data) or identified by name.</t>
<t hangText="Encrypted Data"/>
<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, through the use of an Authenticated
Encryption with Associated Data (AEAD) algorithm such as AES-GCM
or AES-CCM.</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.</t>
</section>
<section title="Design Principles">
<t>In general, JSMS follows the following design principles.</t>
<t><list style="hanging">
<t hangText="Minimize implementation complexity"/>
<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>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>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>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>
<t hangText="Consistency with CMS"/>
<t>To simplify the adaptation of existing cryptographic modules
and the validation of JSMS implementations, changes from the CMS
cryptographic operations are minimized. JSMS is semantically
equivalent to a profile of CMS, as described in <xref
target="sec.cms"/>.</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. (It also supports the use of bare public
keys in order to avoid the use of X.509 altogether.) 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.</t>
</section>
<section title="Certificate Discovery">
<t>JSMS will often be used in an online messaging environments 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>A JSMS object is a JSON object that encodes cryptographic informaton
related to a content byte string. This document specifies the set of
keys that must be present in a JSMS object, what the associated values
are, and how these values are generated and processed in order to
realize security features. In processing JSMS objects, unknown keys MUST
be ignored.</t>
<t>JSMS defines three top-level types of secure object, each of which
provides a specific cryptographic protection to a byte string.</t>
<t><list style="hanging">
<t hangText="SignedData:">Signature using a public-key digital
signature algorithm</t>
<t hangText="AuthenticatedData:">Authentication using a Message
Authentication Code (MAC)</t>
<t hangText="EncryptedData:">Encryption and authentication using an
Authenticated Encryption with Associated Data (AEAD) algorithm</t>
</list></t>
<section title="Data types">
<t>For each field in a JSON object, we define the type of information
that must be included in that field. At base are the object, array,
string, number types defined by JSON. We also use two special
sub-classes of strings: Fields with type "Token" contain a string
drawn from a defined list of strings (e.g., an IANA registry for
algorithm names). Fields with type "ByteString" contain a
Base64-encoded byte string (note the considerations related to Base64
encoding in <xref target="sec.conventions"/> above).</t>
<t>In addition to the primitive data types, <xref
target="sec.sec.useful"/> defines a collection of useful object types
that are used by the top-level JSMS objects. These are simply referred
to by name when they appear as a field value in another object.</t>
</section>
<section title="Basic Types">
<t>The following elements are common to all JSMS messages:</t>
<t><list style="hanging">
<t hangText=""version":">REQUIRED Number. The version of
JSMS used by this objec.t. This field MUST be set to 1.</t>
<t hangText=""type":">REQUIRED Token. The type of this
JSMS object. This field MUST be set to one of the following
values<list style="hanging">
<t hangText=""signed":">SignedData object</t>
<t hangText=""authenticated":">AuthenticatedData
object</t>
<t hangText=""encrypted":">EncryptedData object</t>
</list></t>
<t hangText=""content":">OPTIONAL ByteString. The
content byte string, Base64-encoded.</t>
</list></t>
<t>If the "content" key is not present in a given JSMS object, then
the JSMS object is "detached". In this case, the content must be
associated with the JSMS object through some out-of-band mechanism
before the JSMS object can be processed. Note that there is a risk
that detached JSMS object might become invalid if the content is
transformed, even if this transformation preserves the semantics of
the content. For example, if the content is a JSON object, and the
object passes through an intermediate process that adds whitespace or
re-orders the fields in the object (neither of which changes the
meaning of the object), then the recipient will not be able to verify
the signature. For this reason, detached JSMS objects SHOULD NOT be
used unless there is a canonical form for the content being
processed.</t>
</section>
<section title="SignedData">
<t>A SignedData object MUST have a "type" field set to "signed". In
addition, a SignedData object contains the following keys:</t>
<t><list style="hanging">
<t hangText=""digestAlgorithm":">REQUIRED
AlgorithmIdentifier. The digest algorithm used in signing the
content.</t>
<t hangText=""signatures":">REQUIRED Array of Signature.
One or more digital signatures over the content.</t>
<t hangText=""certificates":">OPTIONAL Array of String.
A certificate chain associating the signer's public key with an
identifier. Each element in the array is a string containing the
Base64-encoded representation of a DER-formatted certificate. The
certificates MUST be ordered with the end-entity certificate first
and each certificate that follows signing the certificate
immediately preceding it.</t>
<t hangText=""certificatesURI":">OPTIONAL String. An
HTTP or HTTPS URI referring to a certificate chain. The referenced
resource MUST have type "application/json" and contain an array of
certificates in the same format as the "certificates" element
above, including the ordering constraint.</t>
</list></t>
<t/>
<section title="Signature">
<t>A Signature object represents the signature over the content in
the SignedData object by a specific key pair. A Signature objec can
contain the following keys:</t>
<t><list style="hanging">
<t hangText=""signatureAlgorithm":">REQUIRED
AlgorithmIdentifier. The signature algorithm used in signing the
content.</t>
<t hangText=""key"">REQUIRED PublicKey. The public key
identifier for the signer, represented as a PublicKey object
(see <xref target="sec.sec.sec.public-key"/>)</t>
<t hangText=""signature"">REQUIRED ByteString. The
Base64-encoded signature value</t>
</list></t>
<t>If the "key" value represents the public key as an identifier,
then a certificate for the signer MUST be provided by setting either
the "certificates" or "certificatesURL" fields. The subject key in
the end-entity certificate MUST match the identifier in the "key"
value; the certificate SHOULD contain the subjectKeyIdentifier
field, with a value matching the "key" value. (Note that this
implies that when there are multiple signers, only one key can be
represented by ID.)</t>
</section>
<section title="Generating a SignedData Object ">
<t>The inputs to the process of generating a SignedData object
are:</t>
<t><list style="symbols">
<t>The content, as a byte string</t>
<t>A digest algorithm</t>
<t>One or more signature algorithms and asymmetric key pairs</t>
</list></t>
<t>To generate the signature for SignedData object, the originator
takes the following steps:</t>
<t><list style="numbers">
<t>Compute the message digest by applying the digest algorithm
to the content.</t>
<t>For each signing key pair, compute the signature by using the
signature algorithm to sign the message digest with the private
key from the asymmetric key pair.</t>
</list></t>
<t>The originator then encodes the SignedData object by including
the appropriate AlgorithmIdentifiers for the digest algorithms, a
Signature object for each signature, and (optionally) the
content.</t>
</section>
<section title="Verifying a SignedData Object">
<t>To verify a SignedData object, the recipient takes the following
steps:</t>
<t><list style="numbers">
<t>Verify that the digest and signature algorithms are
supported. Otherwise, report an error and fail.</t>
<t>Compute the content byte string by decoding the "content"
value of the JSMS object. If the JSMS object does not contain a
"content" field, retrieve the content by other means.</t>
<t>Compute the message digest by applying the digest algorithm
to the content.</t>
<t>Compute the signature by decoding the "signature" value of
the JSMS object.</t>
<t>Compute the public key: <list style="symbols">
<t>If the key is represented directly, then decode it
according to the rules specified by the algorithm name.</t>
<t>If the key is represented by an ID, then retrieve the
corresponding subject public key from the end-entity
certificate . If no "certificates" or "certificatesURI"
value is present, then report an error and fail.</t>
<t>If the key is represented by a URI, retrieve the public
key from the URI.</t>
</list></t>
<t>Verify the signature by using the signature algorithm to
verify the message digest with the public key.</t>
</list></t>
</section>
</section>
<section title="AuthenticatedData">
<t>An AuthenticatedData object MUST have a "type" field set to
"authenticated". In addition, an AuthenticatedData object contains the
following keys:</t>
<t><list style="hanging">
<t hangText=""algorithm":">REQUIRED AlgorithmIdentifier.
The MAC algorithm used to authenticate the content.</t>
<t hangText=""mac":">REQUIRED ByteString. The MAC
value</t>
<t hangText=""keys":">OPTIONAL Array of WrappedKey.
Wrapped versions of the symmetric key used for this MAC. Each
element in the array MUST be a WrappedKey object (see below)</t>
<t hangText=""keyId":">OPTIONAL ByteString. An opaque
identifier for a pre-shared MAC key</t>
</list></t>
<t>An AuthenticatedData object MUST contain either the "key" field or
the "keyId" field, so that the recipient knows which key to use to
verify the MAC.</t>
<section title="Generating an AuthenticatedData Object ">
<t>The inputs to the process of generating a AuthenticatedData
object are:</t>
<t><list style="symbols">
<t>The content, as a byte string</t>
<t>A MAC algorithm</t>
<t>A MAC key and key identifier, or</t>
<t>One or more recipient keys and key encipherment
algorithms</t>
</list></t>
<t>If the recipient key is specified rather than the MAC key
directly, then a random MAC key is generated and encoded in a
WrappedKey objects for each recipient (see <xref
target="sec.sec.sec.wrapped"/>). Once the MAC key has been
determined, the originator uses the MAC algorithm and MAC key to
compute the MAC over the content byte string.</t>
<t>The originator then encodes the AuthenticatedData object by
including the appropriate AlgorithmIdentifier for the MAC algorithm
and the Base64 representations of the MAC value and (optionally) the
content. If the MAC key was specified directly, then the Base64
representation of the key identifier is set as the "keyId" value;
otherwise, the WrappedKey objects are collected in an array and set
as the "keys" value.</t>
</section>
<section title="Verifying an AuthenticatedData Object">
<t>To verify a AuthenticatedData object, the recipient takes the
following steps:</t>
<t><list style="numbers">
<t>Verify that the MAC algorithm is supported. If not, report an
error and fail.</t>
<t>Compute the content byte string by decoding the "content"
value of the JSMS object. If the JSMS object does not contain a
"content" field, retrieve the content by other means.</t>
<t>Compute the MAC key:<list style="symbols">
<t>If the "keyId" value is present and represents a known
key, use the identified key.</t>
<t>If the "keys" value is present, check each WrappedKey
object to determine if it matches a known key for this
recipient. If any of the wrapped keys matches, unwrap the
key from the first one and use it (see Section <xref
target="sec.sec.sec.wrapped"/>). Otherwise, report an error
and fail.</t>
</list></t>
<t>Use the MAC algorithm and MAC key to compute the MAC over the
content byte string</t>
<t>Decode the MAC value from the "mac" field.</t>
<t>Verify that the computed MAC matches the MAC from the
object.</t>
</list></t>
</section>
</section>
<section title="EncryptedData">
<t>An EncryptedData object MUST have a "type" field set to
"encrypted". Note also that in an EncryptedData object, the "content"
field contains the encrypted form of the content, not the content
itself (as plaintext). An EncryptedData object contains the following
keys in addition to any common fields:</t>
<t><list style="hanging">
<t hangText=""algorithm":">REQUIRED AlgorithmIdentifier.
The encryption algorithm used to encrypt the content</t>
<t hangText=""keys":">REQUIRED Array of WrappedKey.
Wrapped versions of the symmetric key used to encrypt the content.
Each element in the array MUST be a WrappedKey object (see <xref
target="sec.sec.sec.wrapped"/>).</t>
<t hangText=""mac":">OPTIONAL ByteString. The MAC value,
if required by the algorithm</t>
</list></t>
<t>Note that although the "mac" field is optional, an EncryptedData
object always has an integrity check. All of the encryption algorithms
used in JSMS are "Authenticated Encryption with Associated Data"
algorithms, which include an authentication / integrity fuction by
definition. The MAC field is optional because some AEAD algorithms
have a separate MAC value (e.g., GCM), while others incorporate the
MAC value into the ciphertext (e.g., CCM).</t>
<section title="Generating an EncryptedData Object ">
<t>The inputs to the process of generating a SignedData object
are:</t>
<t><list style="symbols">
<t>The content, as a byte string</t>
<t>An encryption algorithm</t>
<t>One or more recipient keys and key encipherment
algorithms</t>
</list></t>
<t>The originator generates a random encryption key of a length
suitable for the encryption algorithm, then encodes it in a
WrappedKey object for each recipient (see <xref
target="sec.sec.sec.wrapped"/>). The content is then encrypted using
the generated encryption key and the specified encryption
algorithm.</t>
<t>The originator then encodes the EncryptedData object by including
the appropriate AlgorithmIdentifier for the encryption algorithm, an
array containing the WrappedKey objects, and (optionally) the Base64
representation of the content.</t>
</section>
<section title="Decrypting a EncryptedData Object">
<t>To decrypt an EncryptedData object, the recipient takes the
following steps:</t>
<t><list style="numbers">
<t>Verify that the encryption algorithm is supported. If not,
report an error and fail.</t>
<t>Compute the content byte string by decoding the "content"
value of the JSMS object. If the JSMS object does not contain a
"content" field, retrieve the content by other means.</t>
<t>Locate the encryption key: Check each WrappedKey object to
determine if it matches a known key for this recipient. If any
of the wrapped keys matches, unwrap the key from the first one
and use it (see <xref target="sec.sec.sec.wrapped"/>).
Otherwise, report an error and fail.</t>
<t>Decrypt the content using the encryption key and the
specified encryption algorithm.</t>
<t>Verify that the integrity check in the AEAD decryption was
successful. If not, report an error and fail.</t>
<t>Return the decrypted content.</t>
</list></t>
</section>
</section>
<section anchor="sec.sec.useful" title="Useful Objects">
<t>In this section we define some common object types that are used
across the top-level objects above.</t>
<section anchor="sec.sec.sec.algo" title="AlgorithmIdentifier">
<t>An AlgorithmIdentifier object names a cryptographic algorithm and
specifies any associated parameters such as nonces or initialization
vectors (IVs). If the algorithm has no parameters, then the
AlgorithmIdentifier object is simply a token representing the name
of the algorithm, drawn from an IANA registry of algorithm
names.</t>
<t>If the algorithm specifies parameters, the AlgorithmIdentifier
object is a JSON object. There is only one required field, "name".
Any other fields are specified in the algorithm definition.<list
style="hanging">
<t hangText=""name":">REQUIRED Token. The name of the
algorithm, chosen from one of the IANA registries defined by
this document.</t>
</list></t>
<t>The following table summarizes the algorithms to be used with
JSMS. [[ More detail to be added later, in a separate document
]]</t>
<t/>
<figure>
<artwork><![CDATA[Name Parameters Reference Example
===================================================================
SIGNING
rsa no [RFC3447] "rsa"
dsa yes (p,q,g) [FIPS186] {name:"dsa",
p:1, q:2, g:3}
ecdsa yes (curve) [RFC6090] {name:"ecdsa",
curve:"P-256"}
-------------------------------------------------------------------
DIGEST
sha1 no [FIPS180-1] "sha1"
sha256 no [FIPS180-3] "sha256"
sha384 no [FIPS180-3] "sha384"
sha512 no [FIPS180-3] "sha512"
-------------------------------------------------------------------
MAC
hs1 no [FIPS180-1] "hs1"
hs256 no [FIPS180-3] "hs256"
hs384 no [FIPS180-3] "hs384"
hs512 no [FIPS180-3] "hs512"
-------------------------------------------------------------------
ENCRYPTION
aes128-ccm yes (n,M) [RFC3610] {name:"aes128-ccm",
n:"ZONce...lU-g",
m:8}
aes128-gcm yes (iv) [McGrew & Viega] {name:"aes128-gcm",
iv:"ZONce...lU-g"}
-------------------------------------------------------------------
KEY ENCIPHERMENT
aes no [RFC3394] "aes"
rsaes-oaep no [RFC3447] "rsaes-oaep"
-------------------------------------------------------------------
KEY AGREEMENT
dh-es yes (group) [RFC2631] {name:"dh-es",
group: 14}
ecdh-es yes (curve) [RFC6090] {name:"ecdh-es",
curve:"P-256"}
===================================================================
]]></artwork>
</figure>
<t>Obviously, there will be more detail needed beyond the above, and
some IANA considerations to create the necessary registries. For
some algorithms, there will be specific notes about how they are to
be used with JSMS, for example:<list style="symbols">
<t>The signature value produced by DSA is comprised of two
integers. The byte string to be filled in the "signature" field
is the two-element JSON array containing two integers,
"[r,s]"</t>
<t>RSAES-OAEP is always used with SHA-256 and the default MGF1
masking generation function</t>
<t>Elliptic curves may only be specified by name, not by
directly specifying curve parameters. [[ We may define our own
registry, or re-use the ones from TLS/IKE. ]]</t>
<t>AEAD algorithms are only used for authenticated encryption;
there is never associated data. Further AEAD algorithms may be
defined using [draft-mcgrew-aead-aes-cbc-hmac-sha1]</t>
</list></t>
</section>
<section anchor="sec.sec.sec.public-key" title="PublicKey">
<t>A PublicKey object describes the public key used by a signer. The
key may be specified as a JSON structure directly, as a URI, or as
an identifier. A PublicKey object has the following fields:</t>
<t><list style="hanging">
<t hangText=""type"">OPTIONAL Token. The name of the
algorithm with which this key is to be used</t>
<t hangText=""id"">OPTIONAL ByteString. An identifier
for the key</t>
<t hangText=""uri"">OPTIONAL String. A URI pointing to
a direct form of the key</t>
</list></t>
<t>If the key is specified directly, then the "type" key MUST be
present; the "id" and "uri" fields MAY be present. Subsequent
entries in the array specify the elements of the key, in a manner
determined by the algorithm. Formats for RSA and ECDH/ECDSA public
keys are specified below.</t>
<t>If the key is provided as a URI, then the "uri" field MUST be
present, containing a URI where the key can be retrieved, in the
JSON format described above. The method that the recipient of a JSMS
object uses to retrieve the key will depend on the URI scheme. For
HTTP URIs, the relying party MUST issue an HTTP request with the GET
method and an Accept header including the MIME type for JSMS
PublicKey object, "[[MIMETYPE-TBD]]". For MAILTO, SIP, and XMPP
URIs, the recipient MAY use the WebFinger protocol <xref
target="I-D.hammer-webfinger"/> to retrieve a public key for the
user.</t>
<t>If the key is referenced by an opaque identifier or
"fingerprint", then the "id" field MUST be present, and contain the
Base64-encoded SHA-1 hash of the public key, represented as a
DER-encoded subjectPublicKeyInfo data structure. (This fingerprint
value is the same as the one commonly included in the
subjectKeyIdentifier field in an X.509 certificate.)</t>
<t>The recipient of a JSMS object can determine which of the above
cases a given key falls into by seeking the three fields in
sequence. If a "type" field is present, then the key is represented
directly. If a "uri" field is present, then the key is represented
directly, but must be retreived from the URI. Finally, if the "id"
field is the only one of the three present, then the key is
represented by ID only, and must be retrieved from somewhere else
(e.g., from a certificate in the JSMS object).</t>
<t>Example: {"id": "i1LbR8FCEw-aiFcAAfUvpp75wdY="}</t>
<t>Example: {"uri": "xmpp:juliet@example.com"}</t>
<section title="RSA Public Key">
<t>An RSA public key comprises two additional parameters in
addition to the algorithm identifier "rsa".</t>
<t><list style="hanging">
<t hangText=""n":">REQUIRED ByteString. The modulus,
represented as an integer in network byte order
(big-endian)</t>
<t hangText=""e":">REQUIRED Integer. The public
exponent, represented as an integer in network byte order
(big-endian)</t>
</list></t>
<t>Example: {"type":"rsa", "n":98739...04251, "e": 3}</t>
</section>
<section title="Elliptic-Curve Public Key">
<t>Public keys for several types of elliptic curve algorithms,
including ECDSA and ECDH, have the same format, namely an point on
a specified elliptic curve. In an elliptic curve PublicKey object,
the curve parameters are specified in the algorithm identifier,
and there are two additional fields that specify the point on the
curve:</t>
<t><list style="hanging">
<t hangText=""x":">REQUIRED ByteString. The x
coordinate of the point</t>
<t hangText=""y":">REQUIRED Integer. The y
coordinate of the point. MUST be equal to 0 or 1.</t>
</list></t>
<t>These coordinates correspond to the compressed form of an
elliptic curve point, as specified in [[SEC01]]. In terms of the
calculation specified in section 2.3.3 of [[SEC01]], the "x"
coordinate is the byte string X and the "y" coordinate is the
reduced y coordinate (or, equivalently, Y mod 2).</t>
<t>Example: {"type":"ecdh",
"x":"IIIs_x1m6Na6xKN37vOwvy7AvFeG9HhBN2EN3u5EZQ4", "y": 1}</t>
</section>
</section>
<section anchor="sec.sec.sec.wrapped" title="WrappedKey">
<t>In JSMS objects that use symmetric keys (for MAC or encryption),
it is necessary for the originator to convey the symmetric key used
for in JSMS computations to the recipient. The WrappedKey object is
a JSON object that allows these keys to be provided either using key
transport or key agreement. The following fields may be present in a
WrappedKey object:</t>
<t><list style="hanging">
<t hangText=""type":">REQUIRED TOKEN The type of
wrapping being done. This document defines the following values
for this field:<list style="hanging">
<t hangText=""encryption":">Symmetric key
transport. The "KEKIdentifier" field MUST be present. Any
other non-required fields MUST be ignored.</t>
<t hangText=""transport":">Asymmetric key
transport. The "recipientKey" field MUST be present. Any
other non-required fields MUST be ignored.</t>
<t hangText=""agreement":">Key agreement. The
"originatorKey" and "recipientKey" MUST be present, and the
"userKeyMaterial" field MAY be present. Any other
non-required fields MUST be ignored.</t>
</list></t>
<t hangText=""algorithm":">REQUIRED
AlgorithmIdentifier The algorithm used to encrypt the symmetric
key</t>
<t hangText=""encryptedKey":">REQUIRED BYTES The
symmetric key, encrypted according to the algorithm indicated by
the "algorithm" value</t>
<t hangText=""KEKIdentifier":">OPTIONAL BYTES An
opaque identifier for the symmtric key encryption key</t>
<t hangText=""originatorKey":">OPTIONAL PublicKey The
public key of the originator</t>
<t hangText=""recipientKey":">OPTIONAL PublicKey The
public key of the recipient</t>
<t hangText=""userKeyMaterial":">OPTIONAL BYTES User
key material</t>
</list></t>
<t>The techniques used for wrapping and unwrapping the encrypted key
is determined by "type" and "algorithm" fields. In general, the
options are the same as for CMS [RFC5280], without the option for
password-based key wrapping.</t>
<t><list style="hanging">
<t hangText=""encryption": ">The key is encrypted
under a pre-shared symmetric key encryption key identified by
the "KEKIdentifier" field</t>
<t hangText=""transport":">The key is encrypted under
the recipient's public key, identified in the "recipientKey"
field.</t>
<t hangText=""agreement":">The key is encrypted under
a shared secret derived using a key agreement algorithm
combining the originator's private key and the recipient's
public key, corresponding to the "originatorKey" and
"recipientKey", respectively. The value provided in the
"userKeyMaterial" field may be used to provide additional
entropy.</t>
</list>[[ More detail to be added. ]]</t>
</section>
</section>
</section>
<section title="Compact Format">
<t>The compact JSON format of a JSMS object is identical to the normal
JSMS format, except that field names are replaced with shorter
equivalent field names. Translations for the field names above are given
in the table below. In a given JSMS object, field names MUST either all
be in long form or all be in short form. An implementation MUST reject a
JSMS object with mixed long and short names as improperly formatted.</t>
<figure>
<artwork><![CDATA[Common Signature
-------------------------- --------------------------
version v sign atureAlgorithm sa
type t key k
signed s signature sg
authenticated au --------------------------
encrypted en
content c
-------------------------- AlgorithmIdentifier
--------------------------
name nm
SignedData --------------------------
--------------------------
digestAlgorithm da
signatures ss PublicKey
certificates ce --------------------------
certificatesURI cu type t
-------------------------- id i
uri u
--------------------------
AuthenticatedData
--------------------------
algorithm a WrappedKey
mac mac --------------------------
keys ks type t
keyId ki encryption ec
-------------------------- transport tr
agreement ag
algorithm a
EncryptedData encryptedKey ek
-------------------------- KEKIdentifier i
algorithm a originatorKey o
keys ks recipientKey r
mac mac userKeyMaterial uk
-------------------------- --------------------------
]]></artwork>
</figure>
<t>In applications where a JSMS object is required to be URL-safe, it is
RECOMMENDED that it be rendered in the compact serialization, then
Base64-encoded.</t>
<t>[[ If there is a desire to avoid double-base64url-encoding things,
then we could define a mechanism for moving some fields out of the
object. ]]</t>
</section>
<section title="Examples">
<t>This section contains complete examples of all three JSMS types. All
white space is for readability only, and must be removed before the
examples can be considered valid JSMS objects.</t>
<section title="Parameters">
<t/>
<figure>
<artwork><![CDATA[RSA key:
{
"type": "rsa",
"n": "AfWGinFrdktMCi4LkD_vcIsqc0m4JSS0rNDk_5Zdi8fwja_qH0M7d3
U4tPUw7L0gP1iSMakdTKX0S7uTV_v9FeY8_WrxDgbphrH9Zaz0PvTL
OuiKfRkMWK5A6nzl_PdP7_ujDWkvHKhWcJtM7irdn9K059X21EDtuq
GJyq7_v_c_",
"e": "AQAB",
"d": "EMwfyOqzfJQgZyhl_W40k8SpNdfgDpmqjBiPYubhLqIk7LZns6XDO3
7ZuLiZxT_WP04uMZ7UmV5URwUJVlxEpmfozhtLooCTP1oWtRQQjhTa
Pz1f5nRKoHsO8e3PZY7O44ut2prRWNNxYxDk52rH9GTECqGAmDNb1f
he6zX4KJk="
}
Key Tag: HK1RA8AQwcI=
Symmetric key: rQS8Dx6WQ_xDWTER8mAHnw==
Content:
"Attack at dawn!"
]]></artwork>
</figure>
</section>
<section title="SignedData">
<t>In this object the content is signed under the specified RSA key
pair, using SHA256 as the digest.</t>
<figure>
<artwork><![CDATA[{
"version": 1,
"type": "signed",
"digestAlgorithm": "sha256",
"content": "QXR0YWNrIGF0IGRhd24h",
"signatures": [{
"signatureAlgorithm": "rsa",
"key": {
"type": "rsa",
"n": "AfWGinFrdktMCi4LkD_vcIsqc0m4JSS0rNDk_5Zdi8
fwja_qH0M7d3U4tPUw7L0gP1iSMakdTKX0S7uTV_v9
FeY8_WrxDgbphrH9Zaz0PvTLOuiKfRkMWK5A6nzl_P
dP7_ujDWkvHKhWcJtM7irdn9K059X21EDtuqGJyq7_
v_c_",
"e": "AQAB",
},
"signature": "AJll1tVYsRtGeHaJenAU-U3x4LxXklNoGrFwyu
xJWnYIeLZL16Ib7ZPvD79peMiSQAHAdLKcI8e-
CpU6HNQ-MxeE-tEXvaXOxuNZfVG9LBP9hq_ZwX
SguffHHzS9lLtVB0OzrXeszXtqD5igmeco1A0E
8eabzujA4bdN6Umyc7rA"
}]
}]]></artwork>
</figure>
</section>
<section title="AuthenticatedData">
<t>In this object the content is authenticated with a MAC under a
randomly-generated key (AuthenticatedData Key above), wrapped using
the key encryption key above, identified by the above key tag.</t>
<figure>
<artwork><![CDATA[{
"version": 1,
"type": "authenticated",
"algorithm": "hs256",
"content": "QXR0YWNrIGF0IGRhd24h",
"mac": "990xwhrsX-COXUN0uF09HUHLU2CjdneeMqTtM4sGVDY=",
"keys": [{
"type": "encryption",
"algorithm": "aes",
"encryptedKey": "Dbf2O_ZIX0_Zfj-0aU6zQjn3xixj6vm7LVX
XFDdX4xqie5bZUS1nnstIPYOyzxNx9Udt-J
LZZh-zM8A_FbsZ8zAibdJ3EPyd",
"KEKIdentifier": "HK1RA8AQwcI="
}]
}]]></artwork>
</figure>
<t>As another example, the following object is a detached MAC (over
the same content string) in the compact encoding. Here we use the key
as the MAC key directly (instead of as a key encryption key). The
object is shown both in raw JSON form and in the Base64 encoding.</t>
<figure>
<artwork><![CDATA[{"v": 1,"t": "au","a": "hs256","ki": "HK1RA8AQwcI=",
"mac": "PMVmhmrgbj-KNybfMqHu4ySJ0GnVrwe11MKpiuuGlIQ="}
eyJ2IjogMSwidCI6ICJhdSIsImEiOiAiaHMyNTYiLCJraSI6ICJISzFSQThBUXdj
ST0iLA0KICAibWFjIjogIlBNVm1obXJnYmotS055YmZNcUh1NHlTSjBHblZyd2Ux
MU1LcGl1dUdsSVE9In0=
]]></artwork>
</figure>
<t/>
</section>
<section title="EncryptedData">
<t>In this object, the content is encrypted under the general AEAD
algorithm using AES-128-CBC for encryption and HMAC-SHA1 for
authentication. The keys are described above as "EncryptedData Key
(E)" and "EncryptedData Key (A)", respectively. The temporary keys are
wrapped using the PKCS#1 wrapping, under the RSA key pair above.</t>
<figure>
<artwork><![CDATA[{
"version": 1,
"type": "encrypted",
"algorithm": {
"name": "aes128-ccm",
"n": "LTR8s7KKbd1QlQ==",
"m": 8
},
"content": "0nkXCLOVxM2oNJOsDCwASLTODIMVZQE=",
"keys": [{
"type": "transport",
"algorithm": "rsaes-oaep",
"encryptedKey": "AbAxRnd_u7lICJlBskq3kgQVs54RLMgOjNmALXF
JjKqsQ4kLNL60VAoEswGOd2arGfcxoMCw9wMeSP
FOIvOXGvSt2wJXR_6kwzOJv_YyTC_eZUJHpcLNr
jKxB7Zf2_ap24W6JqcOYYVy2DhECcPgyvVRA_Ql
ZNHFYdqaImgOKJv-",
"recipientKey": {
"type": "rsa",
"n": "AfWGinFrdktMCi4LkD_vcIsqc0m4JSS0rNDk_5Zdi8fwja
_qH0M7d3U4tPUw7L0gP1iSMakdTKX0S7uTV_v9FeY8_Wrx
DgbphrH9Zaz0PvTLOuiKfRkMWK5A6nzl_PdP7_ujDWkvHK
hWcJtM7irdn9K059X21EDtuqGJyq7_v_c_",
"e": "AQAB",
}
}]
}]]></artwork>
</figure>
</section>
</section>
<section anchor="sec.cms" title="Mapping to CMS">
<t>The JSMS message format is semantically equivalent to a profile of
the Cryptographic Message Syntax (CMS), and mirrors a fair bit of its
syntactical structure as well. The top-level message types each map to
top-level CMS types: SignedData to SignedData, AuthenticatedData to
AuthenticatedData, and EncryptedData to AuthEnvelopedData <xref
target="RFC5083"/>. The main difference other than encoding is that many
optional fields have been removed, for example the protected and
unprotected attributes.</t>
<t>This similarity also applies to the secondary objects. Just as in
CMS, AlgorithmIdentifier objects carry an identifier for the algorithm
(here a name instead of an OID) and any related parameters. The
PublicKey object format is an amalgam of the SubjectKeyIdentifier from
CMS and the SubjectPublicKeyInfo from X.509. PublicKey objects can be
mapped to CMS constructs by converting them to SubjectKeyIdentifier
objects (using the appropriate hash) and including a certificate
containing the public key. The WrappedKey object format maps directly to
the CMS RecipientInfo structure, with the above considerations related
to public keys, and without the option for password-based wrapping.</t>
<t>The major way in which JSMS diverges from CMS is that it allows the
use of static MAC keys, referenced by an identifier. CMS requires the
use of random MAC keys, encrypted in a RecipientInfo (i.e., a
WrappedKey) for each recipient. JSMS allows the use of random keys, but
also includes the "keyId" field to reference static MAC keys directly.
The security implications of this change are discussed in <xref
target="sec.sec-cons"/>.</t>
<t>In fact, it should be possible to translate JSMS objects back and
forth to CMS without changing any values (simply reformatting), with
only a couple of exception cases:</t>
<t><list style="symbols">
<t>JSMS objects that use static MAC keys cannot be translated to CMS
because CMS does not allow this keying mechanism.</t>
<t>JSMS objects using general AEAD algorithms (according to
[[draft-mcgrew-aead-aes-cbc-hmac-sha1]]) because the required
algorithm identifiers have not been defined for CMS.</t>
<t>CMS objects using features that are not supported in JSMS (e.g.,
password-based key wrapping) cannot be translated to JSMS.</t>
</list></t>
</section>
<section title="Comparison to JWS/JWE/JWK">
<t>The overall JSMS structure covers the integrity, authentication, and
encryption use cases as the JSON Web Encryption (JWE) and JSON Web
Signature (JWS) specifications. Most of the fields in JWS and JWE map
conceptually to JSMS fields, with a couple of exceptions. The major
differences are as follows:<list style="symbols">
<t>The signature and MAC functions of the JWS object are separated
into SignedData and AuthenticatedData JSMS objects.</t>
<t>JSMS is pure JSON, whereas in JWE and JWS only the header
parameters are represented in JSON.</t>
<t>JSMS parameters are not integrity-protected, as they are in JWE
and JWS.</t>
<t>JSMS allows for full algorithm agility in key agreement, while
JWE only allows ECDH-ES.</t>
<t>JSMS supports multiple recipients for EncryptedData and
AuthenticatedData objects via the inclusion of multiple WrappedKey
objects. Sending a JWE to multiple recipients requires re-encryption
of the entire object for each recipient.</t>
<t>The "typ" and "zip" parameters are not defined in JSMS, but could
be added without significant change.</t>
<t>JSMS requires that recipients MUST ignore unknown header
parameters, in order to facilitate extensibility.</t>
</list></t>
<t>The PublicKey structure is analogous to the JSON Web Key (JWK) (with
the public key parameters specified in the JSON Web Algorithms (JWA)
document). The JWK "use" and "kid" parameters are not defined in JSMS,
but could be added without significant change.</t>
</section>
<section anchor="sec.iana-cons" title="IANA Considerations">
<t>TODO:<list style="symbols">
<t>Register MIME types</t>
<t>Registries for algorithms (signing, hash, MAC, encrypion,
encipherment, agreement)</t>
</list></t>
</section>
<section anchor="sec.sec-cons" title="Security Considerations">
<t>Much more to follow here.</t>
<t>[[ Given the CMS mapping above, import CMS security considerations.
]]</t>
<t>[[ Notes on identity for SignedData and AuthenticatedData: It is
important to note that the above verification process only checks that
the JSMS object was signed with a given public key. In order for this
information to be useful to an applications, it is usually necessary to
bind the public key to an application-layer identifier. If the
"certificates" or "certificatesURI" value is present, then the recipient
SHOULD verify that the chain is valid, and that the the end-entity
certificate chains to a trust anchor. In this case, the recipient can
consider the identity asserted in the end-entity certificate to be bound
to the public key. Applications using this specification without
certificates will need to specify an alternative mechanism for binding
public keys to identifiers. ]]</t>
<t>[[ Notes on the security of static-key MACs. Need to periodically
refresh keys. ]]</t>
<t>[[ For multiple signatures, the considerations of RFC 4853. ]]</t>
</section>
<section title="Acknowledgements">
<t>The inspirataion and starting point for this document was
draft-rescorla-jsms-00. Thanks to Eric Rescorla and Joe Hildebrand for
allowing me to re-use a fair bit of their document, and for some helpful
early reviews.</t>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2045;
&rfc2119;
&rfc3339;
&rfc3447;
&rfc4086;
&rfc4627;
&rfc4648;
&rfc5116;
&rfc5246;
&rfc5280;
&rfc5649;
&rfc5840;
<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;
&rfc5083;
&jws;
<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"/>
</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="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:
-->
| PAFTECH AB 2003-2026 | 2026-04-22 20:53:05 |