One document matched: draft-rescorla-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 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:
-->
| PAFTECH AB 2003-2026 | 2026-04-22 12:54:10 |