idnits 2.17.00 (12 Aug 2021) /tmp/idnits13369/draft-rescorla-jsms-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 7, 2011) is 4086 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'TODO' is mentioned on line 943, but not defined ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Downref: Normative reference to an Informational RFC: RFC 5649 == Outdated reference: A later version (-04) exists of draft-zyp-json-schema-03 ** Downref: Normative reference to an Informational draft: draft-zyp-json-schema (ref. 'I-D.zyp-json-schema') -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS-180-3' Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Rescorla 3 Internet-Draft RTFM, Inc. 4 Intended status: Standards Track J. Hildebrand 5 Expires: September 8, 2011 Cisco Systems, Inc. 6 March 7, 2011 8 JavaScript Message Security Format 9 draft-rescorla-jsms-00.txt 11 Abstract 13 Many applications require the ability to send cryptographically 14 secured messages. While the IETF has defined a number of formats for 15 such messages (e.g. CMS) those formats use encodings which are not 16 congenial for Web applications. This document describes a new 17 cryptographic message format which is based on JavaScript Object 18 Notation (JSON) and thus is easy for Web applications to generate and 19 parse. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on September 8, 2011. 38 Copyright Notice 40 Copyright (c) 2011 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 This document may contain material from IETF Documents or IETF 54 Contributions published or made publicly available before November 55 10, 2008. The person(s) controlling the copyright in some of this 56 material may not have granted the IETF Trust the right to allow 57 modifications of such material outside the IETF Standards Process. 58 Without obtaining an adequate license from the person(s) controlling 59 the copyright in such materials, this document may not be modified 60 outside the IETF Standards Process, and derivative works of it may 61 not be created outside the IETF Standards Process, except to format 62 it for publication as an RFC or to translate it into languages other 63 than English. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. Conventions Used In This Document . . . . . . . . . . . . . . 4 69 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 70 3.1. Operational Modes . . . . . . . . . . . . . . . . . . . . 4 71 3.2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 5 72 3.3. Certificate Processing . . . . . . . . . . . . . . . . . . 6 73 3.4. Certificate Discovery . . . . . . . . . . . . . . . . . . 6 74 4. Message Format . . . . . . . . . . . . . . . . . . . . . . . . 6 75 4.1. Base64 Handling . . . . . . . . . . . . . . . . . . . . . 6 76 4.2. Content Object . . . . . . . . . . . . . . . . . . . . . . 7 77 4.3. Common Elements . . . . . . . . . . . . . . . . . . . . . 7 78 4.4. Signed Data . . . . . . . . . . . . . . . . . . . . . . . 8 79 4.4.1. Signature Computation . . . . . . . . . . . . . . . . 9 80 4.4.2. Signature Verification . . . . . . . . . . . . . . . . 10 81 4.5. Encrypted Data . . . . . . . . . . . . . . . . . . . . . . 12 82 4.5.1. Message Encryption . . . . . . . . . . . . . . . . . . 13 83 4.5.2. Message Decryption . . . . . . . . . . . . . . . . . . 13 84 4.5.3. Key Derivation . . . . . . . . . . . . . . . . . . . . 14 85 4.5.4. CMK Encryption . . . . . . . . . . . . . . . . . . . . 14 86 4.6. Composition . . . . . . . . . . . . . . . . . . . . . . . 15 87 5. Version Processing . . . . . . . . . . . . . . . . . . . . . . 15 88 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 89 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 90 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 91 8.1. Normative References . . . . . . . . . . . . . . . . . . . 15 92 8.2. Informative References . . . . . . . . . . . . . . . . . . 17 93 Appendix A. JSON Schema . . . . . . . . . . . . . . . . . . . . . 17 94 A.1. Message Contents Schema . . . . . . . . . . . . . . . . . 18 95 A.2. Common Elements Schema . . . . . . . . . . . . . . . . . . 19 96 A.3. Signed Message Schema . . . . . . . . . . . . . . . . . . 20 97 A.4. PKIX Certificate Chain Schema . . . . . . . . . . . . . . 21 98 A.5. Encrypted Message Schema . . . . . . . . . . . . . . . . . 21 99 A.6. Recipient Schema . . . . . . . . . . . . . . . . . . . . . 23 100 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . . 23 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 103 1. Introduction 105 Many applications require the ability to send cryptographically 106 secured (encrypted, digitally signed, etc.) messages. While the IETF 107 has defined a number of formats for such messages, those formats are 108 widely viewed as being excessively complicated for the demands of Web 109 applications, which typically only need the ability to secure simple 110 messages. In addition, existing formats use encoding mechanisms 111 (e.g., ASN.1 BER/DER) which are not congenial for Web applications. 112 This presents an obstacle to the deployment of strong security by 113 such applications. 115 This document describes a new cryptographic message format, 116 JavaScript Message Security (JSMS) intended to meet the need of the 117 Web environment. While JSMS is modeled on existing formats -- 118 principally CMS [RFC5652] -- it uses JavaScript Object Notation 119 (JSON) rather than ASN.1/BER/DER, making it far easier for Web 120 applications to handle. In the interest of simplicity, JSMS also 121 omits as many as possible of the CMS modes (multiple signatures, 122 password-based encryption). 124 2. Conventions Used In This Document 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 128 document are to be interpreted as described in [RFC2119]. 130 3. Overview 132 The JSMS message format is simply a JSON [RFC4627] dictionary with an 133 appropriate collection of fields. Each operating mode will have a 134 separate set of fields, with a common field to distinguish between 135 the modes. 137 3.1. Operational Modes 139 JSMS supports two operational modes: 141 Encrypted Data 142 A block of data encrypted under a random message encryption key 143 (MEK). The MEK is then separately encrypted for each recipient, 144 either via symmetric or asymmetric encryption. The data is always 145 integrity protected, either via a separate Message Authentication 146 Code (MAC) or an Authenticated Encryption with Associated Data 147 (AEAD) algorithm such as AES-GCM or AES-CCM. 149 Signed Data 150 A block of data signed by a single signer using his asymmetric key 151 and optionally carrying his certificate. Multiple signatures are 152 not permitted in order to keep things simple. 154 Any other desired security functions are provided by composition of 155 these modes. For instance, a signed and encrypted message is 156 produced by first creating a Signed message and then encrypting that 157 data. (See Section 4.6 for more on composition. 159 3.2. Conventions 161 In general, JSMS follows the following structural conventions: 163 Minimize implementation complexity 164 Wherever possible, protocol choices have been made such that the 165 time and effort required to implement the protocol in many 166 different programming languages will be minimized. This means 167 that optimizations for bandwidth, CPU, and memory utilization have 168 been explicitly avoided. 169 Base64 as the only encoding 170 Any data that does not have a straightforward string 171 representation (binary values, large integers, etc.) is base64- 172 encoded (see: [RFC4648]). In some cases, hexadecimal encodings 173 might be more convenient, but consistency is even more important 174 to reduce implementation complexity. 175 No canonicalization 176 In many cryptographic message formats, canonical encodings are 177 used to allow the same value to be computed at both sender and 178 recipient (e.g., for digital signatures). This is inconvenient in 179 JSON, which just views messages as a bundle of key/value pairs. 180 Instead, whenever canonicalization would be required, the relevant 181 data is serialized and base64-encoded for transport, allowing both 182 sides to run computations over the same original set of octets. 183 In-memory processing 184 We assume that the entire message can fit in main memory and make 185 no effort to design a wire representation which can be handled in 186 small chunks in a single pass. This means, for instance, that 187 there is no need to have a message digest indicator at the 188 beginning of the message and then the signature at the end, as is 189 done in CMS. Fields are simply serialized in whatever order is 190 most convenient for the JSON implementation. The examples in this 191 document are generally shown in whatever order seems most readable 192 and are not normative. 194 3.3. Certificate Processing 196 Experience has shown that certificate handling (path construction) is 197 one of the trickier parts of building a cryptographic system. While 198 JSMS supports PKIX certificates, its certificate processing is far 199 simpler than that of CMS. When a JSMS agent provides its 200 certificate, it must provide an ordered chain (as in TLS [RFC5246]) 201 terminating in its own certificate, thus removing the need to 202 construct certificate paths. The certificates MUST be ordered with 203 the end-entity certificate first and each certificate that follows 204 signing the certificate immediately preceding it. In addition, 205 because many implementations will not want to do any ASN.1/BER 206 processing at all, we will define a Web Service which applications 207 can use for chain validation and translation to an easy-to-parse 208 format. (See [TODO]). 210 3.4. Certificate Discovery 212 JSMS will often be used in an online messaging environment with users 213 that have an address of the form user@domain, such as email, XMPP, or 214 SIP. As such, protocols such as WebFinger [I-D.hammer-webfinger] or 215 an end-to-end protocol can be used to retrieve appropriate 216 certificates. Downstream uses of JSMS SHOULD define a discovery 217 mechanism suitable for the intended use. 219 4. Message Format 221 All of the field definitions in this section make use of JSON Schema 222 [I-D.zyp-json-schema]. For each of the fields that is designed to 223 hold an enumerated value, a registry will be created allowing other 224 values to be used in addition to the values enumerated in the schema. 226 4.1. Base64 Handling 228 As stated in section 3.1 of [RFC4648], Base64 does not require 229 linefeeds after a specific number of characters. Since linefeeds are 230 not valid characters in a JSON string, whenever a field is specified 231 to be Base64-encoded in this document, it MUST NOT include any line 232 breaks. Base64-encoded fields also MUST NOT include JSON-encoded 233 linefeeds such as "\n". Any linebreaks in the middle of Base64- 234 encoded sections of the examples are unintended side-effects of the 235 production process. 237 Implementation Note: Much existing Base64-encoding code will 238 generate linefeeds every 64 or 76 characters of output. Ensure 239 that these linefeeds are removed before inserting the output into 240 a JSON structure. 242 4.2. Content Object 244 JSMS operates by providing transformations on "Content" objects, 245 which are just mime-typed JSON objects. These objects are then 246 wrapped in a signed/encrypted wrapper with the following fields: 248 ContentType: A MIME [RFC2045] media type that MUST be included 249 indicating the type of the "Data" field. 250 Type: The constant string "content", to facilitate easy 251 determination that this is the target content. This is useful 252 (for example) in certain operating conditions where you must 253 continue to unwrap layers of signatures until you get to the 254 content. This field MUST be included. 255 Data: The data value MUST be included as a text encoded as Base64 256 (See: [RFC4648]). 257 ID: An OPTIONAL universally unique ID that identifies this message, 258 for use in detecting replay attacks. 259 Created: An OPTIONAL field describing the UTC date/time that the 260 content was encoded into JSON, formatted according to the "date- 261 time" production of [RFC3339]. 263 Signing and encryption transform a "Content" object into "Signed" and 264 "Encrypted" objects respectively. Verification and decryption 265 transform "Signed" and "Encrypted" objects back into "Content" 266 objects. For example: 268 { 269 "ContentType":"text/plain; charset=UTF-8", 270 "Type":"content", 271 "Data":"SGVsbG8sIFdvcmxkCg==", 272 "ID":"746a4c9f-8e84-4313-b669-81590ee2949e", 273 "Created":"2011-03-07T16:17Z" 274 } 276 Figure 1: Content Example 278 4.3. Common Elements 280 A JSMS message is a JSON dictionary object containing a set of 281 specific values. 283 The following fields MUST be present in all messages: 285 Version: The version number. For this specification this value MUST 286 be set to the string "1.0". See Section 5 for details on version 287 handling. 289 Type: The type of the message. MUST be either "signed" or 290 "encrypted", to indicate a signed message (Section 4.4) or an 291 encrypted message (Section 4.5) respectively. 293 4.4. Signed Data 295 A "signed" message contains a signed data block plus a digital 296 signature over that data. To simplify implementation, only one 297 signer is allowed. In addition to the required fields from 298 Section 4.3, the fields in a signature message are: 300 SignedData: This field MUST consist of a Base64-encoded "Content" 301 structure (see Section 4.2), which MUST have been encoded into 302 octets as UTF-8 prior to Base64-encoding. The signature is 303 computed over the UTF-8 octet stream before Base64-encoding to 304 ensure that the sender and receiver have the exact same 305 representation. 307 DigestAlgorithm: The message digest used to compute the signature. 308 This field MUST be present for RSA-based signatures but MAY be 309 omitted for future signatures which do not allow flexible digests. 310 For now, this field MUST have the value "SHA-256", meaning the 311 digest algorithm was SHA-256 [FIPS-180-3]. 313 SignatureAlgorithm: The signature algorithm used to compute the 314 signature. This field MUST be present. For now, this field MUST 315 have the value "RSA-PKCS1-1.5", meaning the signature algorithm 316 was RSASSA-PKCS1-v1_5 as specified in [RFC3447]. 318 Signer: The signer's identity, expressed as a URI [RFC3986]. This 319 field MUST be present. 321 CertChain: The signer's certificate chain, if any (see 322 Section 4.4.2.1). 324 Signature: The Base64-encoded signature, which MUST be included (see 325 Section 4.4.1). 327 { 328 "SignedData":"ewogICAgIkNvbnRlbnRUeXBlIjoidGV4dC9wbGFpbjsgY2hhcn 329 NldD1VVEYtOCIsCiAgICAiVHlwZSI6ImNvbnRlbnQiLAogICAg 330 IkRhdGEiOiJTR1ZzYkc4c0lGZHZjbXhrQ2c9PSIsCiAgICAiSU 331 QiOiI3NDZhNGM5Zi04ZTg0LTQzMTMtYjY2OS04MTU5MGVlMjk0 332 OWUiLAogICAgIkNyZWF0ZWQiOiIyMDExLTAzLTA3VDE2OjE3Wi 333 IKfQ==", 334 "DigestAlgorithm":"SHA-256", 335 "SignatureAlgorithm":"RSA-PKCS1-1.5", 336 "Signer":"xmpp:romeo@example.net", 337 "Signature":"sNsxJltUaz4pSzAtJiPZagUMV4SwWugWexGbffK/WJRDi2uq7TxN 338 /V9SwG/kvQ7CaTABbeUuc6cKGO5YxnH5hME3bHB5L9PKPWSjxzxo 339 68RPxQyPli2YJDDHKVPbofEa86CLqYcwTF5qrcL7fQFvlRSOVxpS 340 SJfIdiAJNA+nEnk=" 341 } 343 Figure 2: Signed Message Example 345 4.4.1. Signature Computation 347 The signature is computed over the string prior to base64 encoding. 348 I.e., the processing order for encoding is: 350 1. Serialize the inner "Content" value into a UTF8-encoded octet 351 series X. 352 2. Compute the signature value over X, and call the result Y. (In 353 the case of signatures which use digests, this means feed the 354 literal octets of the signature into the digest function.) 355 3. Compute the Base64 representation of X and insert it into the 356 "SignedData" field of the message. 357 4. Compute the Base64 representation of Y, and insert the result 358 into the "Signature" field. 360 This procedure removes dependencies on the exact serialization 361 algorithm; variation in spacing, field order, etc. do not affect 362 signature validity since the Base64 representation preserves them on 363 the wire and protects them from modification by intermediaries. 365 Note: An alternative algorithm would be to compute the signature on 366 the base64 representation itself, but this has two disadvantages: 367 (1) any intermediaries which change spacing/line breaks would 368 break the signature. (2) it is inconsistent with the algorithm for 369 encryption (Section 4.5), which is designed to avoid multiple 370 base64 encoding. 372 This procedure only specifies the input to the signature computation. 373 The details of the computation depend on the signature algorithm 374 itself. The mapping from code points to algorithms is found in 375 Section 6. 377 4.4.2. Signature Verification 379 In order to verify the signature, the steps of the previous section 380 are reversed. 382 1. Process the provided "Signer" and "CertChain" fields as described 383 in Section 4.4.2.1 in order to determine the sender's public key. 384 2. Base64 decode the "SignedData" field in order to recover a string 385 X. 386 3. Verify the "Signature" field against X using the sender's public 387 key and the "SignatureAlgorithm" and "DigestAlgorithm" fields. 388 If the signature fails, return an error. 389 4. Deserialize X to recover the inner "Content" value. 390 5. Check any "ID" or "Created" fields for replay. 391 6. Using the value of the "ContentType" field to give MIME type 392 context, Base64-decode the "Data" field to retrieve the intended 393 message. 395 4.4.2.1. Certificate Processing 397 JSMS uses the "CertChain" element to carry certificate chains. For 398 the moment, each certificate in the chain is expected to be a PKIX 399 certificate BER-encoded then Base64-encoded. Future versions of this 400 document will likely specify other valid certificate formats, since 401 one of the goals of this format is to avoid . The meaning of the 402 fields is described below: 404 Type: The type of the certificate chain. The only defined value is 405 "PKIX", referring to PKIX [RFC5280] certificates. 407 Chain: An array of certificate values. In the case of "PKIX" 408 certificates this is a list of base64-encoded DER/BER PKIX 409 certificate values. PKIX certificates MUST be represented in 410 order with each certificate certifying the next and the final 411 certificate representing the end-entity. 413 { 414 "Type":"PKIX", 415 "Chain":[ 416 "MIICPjCCAaegAwIBAgIBETANBgkqhkiG9w0BAQUFADBDMRMwEQ 417 YKCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQBGRYHZXhh 418 bXBsZTETMBEGA1UEAxMKRXhhbXBsZSBDQTAeFw0wNDA0MzAxND 419 I1MzRaFw0wNTA0MzAxNDI1MzRaMEMxEzARBgoJkiaJk/IsZAEZ 420 FgNjb20xFzAVBgoJkiaJk/IsZAEZFgdleGFtcGxlMRMwEQYDVQ 421 QDEwpFeGFtcGxlIENBMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCB 422 iQKBgQDC15dtKHCqW88jLoBwOe7bb9Ut1WpPejQt+SJyR3Ad74 423 DpyjCMAMSabltFtG6l5myUDfqR6UD8JZ3Ht2gZVo8RcGrX8ckR 424 Tzp+P5mNbnaldF9epFVT5cdoNlPHHTsSpoX+vW6hyt81UKwI17 425 m0flz+4qMs0SOEqpjAm2YYmmhH6QIDAQABo0IwQDAdBgNVHQ4E 426 FgQUCGivhTPIOUp6+IKTjnBqSiCELDIwDgYDVR0PAQH/BAQDAg 427 EGMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEFBQADgYEA 428 bPgCdKZh4mQEplQMbHITrTxH+/ZlE6mFkDPqdqMm2fzRDhVfKL 429 fvk7888+I+fLlS/BZuKarh9Hpv1X/vs5XK82aIg06hNUWEy7yb 430 uMitxV5G2QsOjYDhMyvcviuSfkpDqWrvimNhs25HOL7oDaNnXf 431 P6kYE8krvFXyUl63zn2KE=", 432 "MIICcTCCAdqgAwIBAgIBEjANBgkqhkiG9w0BAQUFADBDMRMwEQ 433 YKCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQBGRYHZXhh 434 bXBsZTETMBEGA1UEAxMKRXhhbXBsZSBDQTAeFw0wNDA5MTUxMT 435 Q4MjFaFw0wNTAzMTUxMTQ4MjFaMEMxEzARBgoJkiaJk/IsZAEZ 436 FgNjb20xFzAVBgoJkiaJk/IsZAEZFgdleGFtcGxlMRMwEQYDVQ 437 QDEwpFbmQgRW50aXR5MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCB 438 iQKBgQDhauQDMJcCPPQQ87UeTX8Ue/b10HjppIrwo3Xs7bZWln 439 +ImYWa8j5od4frntGfwLQX3KuJI6QdfhYjTE+oTfUxuHyq4xpJ 440 CfRLJtsnZzCCEgFK6Rq2wQxTi2z8L3pD7DM2fjKye9WqzwEUxh 441 LsE/ItFHqLIVgUE0xGo5ryFpX/IwIDAQABo3UwczAhBgNVHREE 442 GjAYgRZlbmQuZW50aXR5QGV4YW1wbGUuY29tMB0GA1UdDgQWBB 443 QXe5Iw/0TWZuGQECJsFk/AjkHdbTAfBgNVHSMEGDAWgBQIaK+F 444 M8g5Snr4gpOOcGpKIIQsMjAOBgNVHQ8BAf8EBAMCBsAwDQYJKo 445 ZIhvcNAQEFBQADgYEAACAoNFtoMgG7CjYOrXHFlRrhBM+urcdi 446 FKQbNjHA4gw92R7AANwQoLqFb0HLYnq3TGOBJl7SgEVeM+dwRT 447 s5OyZKnDvyJjZpCHm7+5ZDd0thi6GrkWTg8zdhPBqjpMmKsr9z 448 1E3kWORi6rwgdJKGDs6EYHbpc7vHhdORRepiXc0=" 449 ] 450 } 452 Figure 3: PKIX CertChain Example 454 The recipient MUST verify the certificate chain (in the case of PKIX 455 certificates according to [RFC5280]). If any validation failure 456 occurs, the implementation MUST abort processing and return an error. 458 Once the certificate chain is validated, the end-entity certificate 459 must contain an identity which matches the "Signer" field. In the 460 case of PKIX certificates, the certificate MUST contain a 461 subjectAltName field of type "uniformResourceIdentifier". This field 462 MUST be equivalent to the URI in the "Signer" field. If not, an 463 error MUST be returned. 465 4.5. Encrypted Data 467 An "encrypted" message contains an encrypted "Content" block. All 468 "encrypted" messages contain a symmetric integrity check, either via 469 a MAC or via an AEAD [RFC5116] algorithm such as Galois/Counter Mode 470 (GCM: [GCM]). A message may be encrypted to an arbitrary number of 471 recipients. Each recipient is represented by a "Recipient" block, 472 which contains a copy of the keying material encrypted for that 473 recipient. Both symmetric and asymmetric key establishment is 474 supported. In order to support both integrity and encryption, what 475 is carried in the Recipient block is a Content Master Key (CMK) which 476 is then used with a Key Derivation Function (KDF) to generate the 477 Content Encryption Key (CEK) used to encrypt the message and the 478 Content Integrity Key (CIK) used with the MAC. In addition to the 479 required fields from Section 4.3 the fields in an encrypted message 480 are: 482 Recipients: The list of recipients. This is an array of Recipient 483 objects, each of which establishes the CMK for that recipient. 484 KDF: Specifies the key derivation function used to generate the CEK 485 and the CIK from the CMK. This field MAY be absent if an AEAD 486 algorithm is used, in which case the CEK is derived by copying the 487 CMK. 488 Encryption: Specifies the properties of the encryption. The 489 Algorithm field MUST contain the encryption algorithm and the IV 490 field specifies the initialization vector (if required for the 491 algorithm). This field MUST be present. 492 Integrity: Specifies the properties of the integrity check. The 493 Algorithm field MUST contain the MAC algorithm and the Value field 494 MUST contain the MAC. This field MAY be absent if no integrity 495 check is used. 496 Data: Contains the ciphertext. 498 Each Recipient object provides an encrypted copy of the CMK for a 499 single recipient. The meaning of the fields is described below: 501 KEKidentifier Describes the key encrypting key (KEK) used to encrypt 502 the CMK. Either a "RecipientName" or a "KeyIdentifier" MUST be 503 provided. If the "RecipientName" is provided, then a 504 "CertificateDigest" SHOULD be provided. 506 RecipientName: Provides the recipient's name in URI form. 507 CertificateDigest: For now, the SHA-1 fingerprint of the PKIX 508 certificate associated with the recipient. 509 KeyIdentifier The name of a shared symmetric key known to both 510 sender and recipient. This need not be globally unique as long 511 as it is unique within the recipient's context. 512 Algorithm: The algorithm used to encrypt the CMK. For now, one of 513 "RSA-PKCS1-1.5" (meaning RSASSA-PKCS1-v1_5 as specified in 514 [RFC3447]) or "AES-256-CBC" (meaning [FIPS-180-3]). Note the JSMS 515 only supports key transport and not key agreement (since key 516 agreement can always be turned into key transport). 517 Value: The CMK encrypted under the specified algorithm and key. 519 4.5.1. Message Encryption 521 The message encryption process is as follows. 523 1. Generate a random CMK. The CMK MUST have a length at least equal 524 to that of the larger of the required integrity or encryption 525 keys and MUST be generated randomly. See [RFC4086] for 526 considerations on generating random values. [[ TODO - we need a 527 section on generating randomness in browsers - it's easy to screw 528 up ]] 529 2. Encrypt the CMK for each recipient (see Section 4.5.4) 530 3. Generate a random IV (if required for the algorithm). 531 4. Run the key derivation algorithm (see Section 4.5.3) to generate 532 the CEK and CIK (if not using an AEAD algorithm). 533 5. Serialize the content into a bitstring M. 534 6. Encrypt M using the CEK and IV to form the bitstring C. 535 7. Set the Value element equal to the base64-encoded representation 536 of C. 537 8. If not using an AEAD algorithm, compute the function I = MAC(CIK, 538 C) using the chosen integrity algorithm. Note that this is EtA 539 encryption which is considered the best cryptographic choice 540 (See: [krawczyk-ate]). Set the Integrity.Value element equal to 541 the base64-encoded representation of I. 543 4.5.2. Message Decryption 545 The message decryption process is the reverse of the encryption 546 process. 548 1. Identify a Recipient block which appears to reference a key known 549 to the recipient. 550 2. Decrypt the CMK. If this fails and another Recipient block 551 appears plausible, that MAY be tried. 553 3. Run the key derivation algorithm (see Section 4.5.3) to generate 554 the CEK and CIK (if not using an AEAD algorithm). 555 4. If not using an AEAD algorithm, compute the integrity check value 556 I' on the binary representation of the Value element using the 557 indicated integrity check. If the Integrity.Value does not match 558 I', then an error MUST be reported and processing MUST be 559 aborted. 560 5. Decrypt the binary representation of the Value element and output 561 the result 563 4.5.3. Key Derivation 565 The key derivation process converts the CMK into a CEK. It assumes 566 as a primitive a Key Derivation Function (KDF) which notionally takes 567 three arguments: 568 MasterKey: The master key used to compute the individual use keys 569 Label: The use key label, used to differentiate individual use keys 570 Length: The length of the desired use key 571 The only real KDF specified in this document is the TLS PRF, which is 572 invoked as PRF(MasterKey, Label) with an empty seed and produces an 573 arbitrary length output. The appropriate number of bits (Length) is 574 simply extracted from the beginning of the output. The KDF name 575 "P_XXX" in this document refers the the TLS [RFC5246] PRF using P_XXX 576 as the underlying P_hash function. 578 To compute the CEK from the CMK, the label "Encryption" is used. 580 To compute the CIK from the CMK, the label "Integrity" is used. 582 When AEAD algorithms are used the KDF element MUST NOT be present. 583 When they are not used, it MUST be present. 585 4.5.4. CMK Encryption 587 JSMS supports two forms of CMK encryption: 589 o Asymmetric encryption under the recipient's public key. 590 o Symmetric encryption under a shared key. 592 4.5.4.1. Asymmetric Encryption 594 In the asymmetric encryption mode, the CMK is encrypted under the 595 recipient's public key. The only currently defined asymmetric 596 encryption mode is RSA-PKCS1-1.5, which refers to [RFC3447] RSAES- 597 PKCS1-v1_5. 599 4.5.4.2. Symmetric Encryption 601 In the symmetric encryption mode, the CMK is encrypted under a 602 symmetric key shared between the sender and receiver. All such modes 603 MUST provide integrity for the CMK. This document defines four such 604 modes: AES-128-CBC, AES-256-CBC referring to the [RFC5649] AES key 605 wrapping modes and AES-128-GCM, AES-256-GCM, referring to AES 606 encryption with GCM. For GCM the random 64-bit IV is prepended to 607 the ciphertext. 609 4.6. Composition 611 This document does not specify a combination signed and encrypted 612 mode. However, because the contents of a message can be arbitrary, 613 and encryption and data origin authentication can be provided by 614 recursively encapsulating multiple JSMS messages. In general, 615 senders SHOULD sign the message and then encrypt the result (thus 616 encrypting the signature). This prevents attacks in which the 617 signature is stripped, leaving just an encrypted message, as well as 618 providing privacy for the signer. 620 5. Version Processing 622 For the moment, all version numbers in the protocol MUST be 1.0. 623 Receivers MUST return an error for any other version number. More 624 interesting version processing will be defined in the future. 626 6. IANA Considerations 628 [TODO] 629 o Register MIME types 630 o Registries for signature, encryption, MAC 631 o Well known HTTP URLs 633 7. Security Considerations 635 Much more to follow here. 637 8. References 639 8.1. Normative References 641 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 642 Extensions (MIME) Part One: Format of Internet Message 643 Bodies", RFC 2045, November 1996. 645 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 646 Requirement Levels", BCP 14, RFC 2119, March 1997. 648 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 649 Internet: Timestamps", RFC 3339, July 2002. 651 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 652 Standards (PKCS) #1: RSA Cryptography Specifications 653 Version 2.1", RFC 3447, February 2003. 655 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 656 Requirements for Security", BCP 106, RFC 4086, June 2005. 658 [RFC4627] Crockford, D., "The application/json Media Type for 659 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 661 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 662 Encodings", RFC 4648, October 2006. 664 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 665 Encryption", RFC 5116, January 2008. 667 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 668 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 670 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 671 Housley, R., and W. Polk, "Internet X.509 Public Key 672 Infrastructure Certificate and Certificate Revocation List 673 (CRL) Profile", RFC 5280, May 2008. 675 [RFC5649] Housley, R. and M. Dworkin, "Advanced Encryption Standard 676 (AES) Key Wrap with Padding Algorithm", RFC 5649, 677 September 2009. 679 [I-D.zyp-json-schema] 680 Zyp, K. and G. Court, "A JSON Media Type for Describing 681 the Structure and Meaning of JSON Documents", 682 draft-zyp-json-schema-03 (work in progress), 683 November 2010. 685 [FIPS-180-3] 686 National Institute of Standards and Technology (NIST), 687 "Secure Hash Standard (SHS)", FIPS PUB 180-3, 688 October 2008. 690 8.2. Informative References 692 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 693 Resource Identifier (URI): Generic Syntax", STD 66, 694 RFC 3986, January 2005. 696 [I-D.hammer-webfinger] 697 Hammer-Lahav, E., Fitzpatrick, B., and B. Cook, "The 698 WebFinger Protocol", draft-hammer-webfinger-00 (work in 699 progress), October 2009. 701 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 702 RFC 5652, September 2009. 704 [krawczyk-ate] 705 Krawczyk, H., "The Order of Encryption and Authentication 706 for Protecting Communications (or: How Secure Is SSL?)", 707 Advances in cryptology--CRYPTO 2001 August 2001. 709 [GCM] National Institute of Standards and Technology (NIST), 710 "Recommendation for Block Cipher Modes of Operation: 711 Galois/Counter Mode (GCM) and GMAC", SP 800-38D, 712 November 2007. 714 Appendix A. JSON Schema 716 The following schemas formally define various namespaces used in this 717 document, in conformance with [I-D.zyp-json-schema]. Because 718 validation of JSON documents is optional, these schemas are not 719 normative and are provided for descriptive purposes only. 721 A.1. Message Contents Schema 723 { 724 "description":"Message Contents", 725 "type":"object", 726 "properties":{ 727 "ContentType":{ 728 "description":"A MIME content type", 729 "type":"string", 730 "required":true 731 }, 732 "Type":{ 733 "description":"Dictionary type", 734 "type":"string", 735 "enum":["content"], 736 "required":true 737 }, 738 "Data":{ 739 "description":"The underlying data", 740 "type":"string", 741 "required":true 742 }, 743 "ID":{ 744 "description":"(optional) unique ID for this message", 745 "type":"string" 746 }, 747 "Created":{ 748 "description":"(optional) time the message was created", 749 "type":"string", 750 "format":"date-time" 751 } 752 } 753 } 755 A.2. Common Elements Schema 757 { 758 "description":"The basic schema for a JSMS message", 759 "type":"object", 760 "properties":{ 761 "Type":{ 762 "description":"Message type", 763 "type":"string", 764 "enum":["signed", "encrypted"] 765 }, 766 "Version":{ 767 "description":"Version number for the message", 768 "type":"string", 769 "enum":["1.0"] 770 } 771 } 772 } 774 A.3. Signed Message Schema 776 { 777 "description":"A signed message", 778 "type":"object", 779 "extends":message_schema, 780 "properties":{ 781 "Signature":{ 782 "description":"The signature over the SignedData", 783 "type":"object", 784 "properties":{ 785 "SignedData":{ 786 "description":"content to be signed, Base64", 787 "type":"string", 788 "required":true 789 }, 790 "DigestAlgorithm":{ 791 "description":"", 792 "type":"string", 793 "enum":["SHA-256"] 794 }, 795 "SignatureAlgorithm":{ 796 "description":"", 797 "type":"string", 798 "enum":["RSA-PKCS1-1.5"] 799 }, 800 "Signer":{ 801 "description":"", 802 "type":"string", 803 "format":"uri", 804 "required":true 805 }, 806 "CertChain": { 807 "description":"the signer's cert chain", 808 "type":"PKIXcertchain" 809 }, 810 "Signature":{ 811 "description":"the signature", 812 "type":"string", 813 "required":true 814 } 815 } 816 } 817 } 818 } 820 A.4. PKIX Certificate Chain Schema 822 { 823 "description":"A chain of PKIX certificates", 824 "id":"PKIXcertchain", 825 "properties":{ 826 "Type":{ 827 "description":"The type of certificate chain", 828 "type":"string", 829 "enum":["PKIX"] }, 830 "Chain":{ 831 "description":"PKIX certs ordered from root to end", 832 "type":"array", 833 "items":{ 834 "description":"A base64-encoded BER certificate", 835 "type":"string" 836 } 837 } 838 } 839 } 841 A.5. Encrypted Message Schema 843 { 844 "description":"An encrypted object", 845 "type":"object", 846 "extends":message_schema, 847 "properties":{ 848 "Recipients":{ 849 "description":"The list of recipient blocks", 850 "type":"array", 851 "required":true, 852 "items":{ 853 "description":"A single recipient block", 854 "type":"Recipient" 855 } 856 }, 857 "KDF":{ 858 "description": 859 "The KDF used to derive the MAC and encryption keys", 860 "type":"string", 861 "enum":["P_SHA256"] 862 }, 863 "Encryption":{ 864 "description":"Encryption control information", 865 "type":"object", 866 "required":true, 867 "properties":{ 868 "Algorithm":{ 869 "description":"The algorithm used to encrypt", 870 "type":"string", 871 "enum":["AES-256-CBC"] 872 }, 873 "IV":{ 874 "description":"Initialization vector (base64)", 875 "type":"string" 876 } 877 } 878 }, 879 "Integrity":{ 880 "description":"The integrity control information", 881 "type":"object", 882 "properties":{ 883 "Algorithm":{ 884 "description":"The MAC algorithm", 885 "type":"string", 886 "enum":["HMAC-SHA-256"] 887 }, 888 "Value":{ 889 "description":"The MAC value (base64-encoded)", 890 "type":"string", 891 "required":true 892 } 893 } 894 }, 895 "Data":{ 896 "description":"The ciphertext (Base64-encoded)", 897 "type":"string", 898 "required":true 899 } 900 } 901 } 903 A.6. Recipient Schema 905 { 906 "description":"The recipient of an encrypted object", 907 "type":"object", 908 "id":"Recipient", 909 "properties":{ 910 "KEKidentifier":{ 911 "type":"object", 912 "description":"Identifies the key encrypting key", 913 "properties":{ 914 "RecipientName":{ 915 "type":"string", 916 "description":"The recipient's name", 917 "format":"uri" 918 }, 919 "CertificateDigest":{ 920 "type":"string", 921 "description":"Recipient's cert fingerprint" 922 }, 923 "KeyIdentifier":{ 924 "type":"string", 925 "description": "Shared symmetric key (opaque)" 926 } 927 } 928 }, 929 "Algorithm":{ 930 "description":"The algorithm used to protect the CMK", 931 "type":"string", 932 "enum":["RSA-PKCS1-1.5", "AES-256-CBC"] 933 }, 934 "Value":{ 935 "description": "Base64 of the encrypted CMK", 936 "type":"string" 937 } 938 } 939 } 941 Appendix B. Acknowledgments 943 [TODO] 945 Authors' Addresses 947 Eric Rescorla 948 RTFM, Inc. 949 2064 Edgewood Drive 950 Palo Alto, CA 94303 951 USA 953 Email: ekr@rtfm.com 955 Joe Hildebrand 956 Cisco Systems, Inc. 957 1899 Wyknoop Street, Suite 600 958 Denver, CO 80202 959 USA 961 Email: jhildebr@cisco.com