idnits 2.17.1 draft-madden-jose-ecdh-1pu-04.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 : ---------------------------------------------------------------------------- ** There are 8 instances of too long lines in the document, the longest one being 8 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (May 6, 2021) is 1083 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) ** Downref: Normative reference to an Informational RFC: RFC 7748 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group N. Madden 3 Internet-Draft ForgeRock 4 Intended status: Standards Track May 6, 2021 5 Expires: November 7, 2021 7 Public Key Authenticated Encryption for JOSE: ECDH-1PU 8 draft-madden-jose-ecdh-1pu-04 10 Abstract 12 This document describes the ECDH-1PU public key authenticated 13 encryption algorithm for JWE. The algorithm is similar to the 14 existing ECDH-ES encryption algorithm, but adds an additional ECDH 15 key agreement between static keys of the sender and recipient. This 16 additional step allows the recipient to be assured of sender 17 authenticity without requiring a nested signed-then-encrypted message 18 structure. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on November 7, 2021. 37 Copyright Notice 39 Copyright (c) 2021 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Requirements Terminology . . . . . . . . . . . . . . . . 3 56 2. Key Agreement with Elliptic Curve Diffie-Hellman One-Pass 57 Unified Model (ECDH-1PU) . . . . . . . . . . . . . . . . . . 4 58 2.1. Special Considerations for Key Agreement with Key 59 Wrapping mode . . . . . . . . . . . . . . . . . . . . . . 5 60 2.2. Header Parameters used for ECDH Key Agreement . . . . . . 5 61 2.2.1. "skid" Header Parameter . . . . . . . . . . . . . . . 6 62 2.3. Key Derivation for ECDH-1PU Key Agreement . . . . . . . . 6 63 3. IANA considerations . . . . . . . . . . . . . . . . . . . . . 8 64 3.1. JSON Web Signature and Encryption Algorithms Registration 8 65 3.1.1. ECDH-1PU . . . . . . . . . . . . . . . . . . . . . . 8 66 3.2. JSON Web Signature and Encryption Header Parameters 67 Registration . . . . . . . . . . . . . . . . . . . . . . 9 68 3.2.1. skid . . . . . . . . . . . . . . . . . . . . . . . . 9 69 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 70 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 5.1. Normative References . . . . . . . . . . . . . . . . . . 10 72 5.2. Informative References . . . . . . . . . . . . . . . . . 11 73 Appendix A. Example ECDH-1PU Key Agreement Computation with 74 A256GCM . . . . . . . . . . . . . . . . . . . . . . 11 75 Appendix B. Example ECDH-1PU+A128KW Key Agreement computation 76 with A256CBC-HS256 . . . . . . . . . . . . . . . . . 14 77 B.1. JWE Protected Header . . . . . . . . . . . . . . . . . . 15 78 B.2. JWE Per-Recipient Unprotected Headers . . . . . . . . . . 15 79 B.3. JWE Shared Unprotected Header . . . . . . . . . . . . . . 15 80 B.4. Additional Authenticated Data . . . . . . . . . . . . . . 15 81 B.5. Content Encryption Key . . . . . . . . . . . . . . . . . 16 82 B.6. Initialization Vector . . . . . . . . . . . . . . . . . . 16 83 B.7. JWE Plaintext . . . . . . . . . . . . . . . . . . . . . . 16 84 B.8. Content Encryption . . . . . . . . . . . . . . . . . . . 16 85 B.9. Key Agreement for Bob . . . . . . . . . . . . . . . . . . 17 86 B.10. Key Agreement for Charlie . . . . . . . . . . . . . . . . 19 87 B.11. Complete JWE JSON Serialization Representation . . . . . 20 88 Appendix C. Document History . . . . . . . . . . . . . . . . . . 21 89 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 91 1. Introduction 93 JSON Object Signing and Encryption (JOSE) defines a number of 94 encryption (JWE) [RFC7516] and digital signature (JWS) [RFC7515] 95 algorithms. When symmetric cryptography is used, JWE provides 96 authenticated encryption that ensures both confidentiality and sender 97 authentication. However, for public key cryptography the existing 98 JWE encryption algorithms provide only confidentiality and some level 99 of ciphertext integrity. When sender authentication is required, 100 users must resort to nested signed-then-encrypted structures, which 101 increases the overhead and size of resulting messages. This document 102 describes an alternative encryption algorithm called ECDH-1PU that 103 provides public key authenticated encryption, allowing the benefits 104 of authenticated encryption to be enjoyed for public key JWE as it 105 currently is for symmetric cryptography. 107 ECDH-1PU is based on the One-Pass Unified Model for Elliptic Curve 108 Diffie-Hellman key agreement described in [NIST.800-56A]. 110 The advantages of public key authenticated encryption with ECDH-1PU 111 compared to using nested signed-then-encrypted documents include the 112 following: 114 o The resulting message size is more compact as an additional layer 115 of headers and base64url-encoding is avoided. A 500-byte payload 116 when encrypted and authenticated with ECDH-1PU (with P-256 keys 117 and "A256GCM" Content Encryption Method) results in a 1087-byte 118 JWE in Compact Encoding. An equivalent nested signed-then- 119 encrypted JOSE message using the same keys and encryption method 120 is 1489 bytes (37% larger). 122 o The same primitives are used for both confidentiality and 123 authenticity, providing savings in code size for constrained 124 environments. 126 o The generic composition of signatures and public key encryption 127 involves a number of subtle details that are essential to security 128 [PKAE]. Providing a dedicated algorithm for public key 129 authenticated encryption reduces complexity for users of JOSE 130 libraries. 132 o ECDH-1PU provides only authenticity and not the stronger security 133 properties of non-repudiation or third-party verifiability. This 134 can be an advantage in applications where privacy, anonymity, or 135 plausible deniability are goals. 137 1.1. Requirements Terminology 139 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 140 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 141 "OPTIONAL" in this document are to be interpreted as described in BCP 142 14 [RFC8174] when, and only when, they appear in all capitals, as 143 shown here. 145 2. Key Agreement with Elliptic Curve Diffie-Hellman One-Pass Unified 146 Model (ECDH-1PU) 148 This section defines the specifics of key agreement with Elliptic 149 Curve Diffie-Hellman One-Pass Unified Model, in combination with the 150 one-step KDF, as defined in Section 5.8.2.1 of [NIST.800-56A] using 151 the Concatenation Format of Section 5.8.2.1.1. This is identical to 152 the ConcatKDF function used by the existing JWE ECDH-ES algorithm 153 defined in Section 4.6 of [RFC7518]. As for ECDH-ES, the key 154 agreement result can be used in one of two ways: 156 1. directly as the Content Encryption Key (CEK) for the "enc" 157 algorithm, in the Direct Key Agreement mode, or 159 2. as a symmetric key used to wrap the CEK with the "A128KW", 160 "A192KW", or "A256KW" algorithms, in the Key Agreement with Key 161 Wrapping mode. 163 A fresh ephemeral public key value MUST be generated for each 164 message. When encrypting the message to multiple recipients using 165 ECDH-1PU, the same ephemeral keys MAY be reused for multiple 166 recipients [MRES]. 168 In Direct Key Agreement mode, the output of the KDF MUST be a key of 169 the same length as that used by the "enc" algorithm. In this case, 170 the empty octet sequence is used as the JWE Encrypted Key value. The 171 "alg" (algorithm) Header Parameter value "ECDH-1PU" is used in Direct 172 Key Agreement mode. 174 In Key Agreement with Key Wrapping mode, the output of the KDF MUST 175 be a key of the length needed for the specified key wrapping 176 algorithm. In this case, the JWE Encrypted Key is the CEK wrapped 177 with the agreed-upon key. 179 The following "alg" (algorithm) Header Parameter values are used to 180 indicate the JWE Encrypted Key is the result of encrypting the CEK 181 using the result of the key agreement algorithm as the key encryption 182 key for the corresponding key wrapping algorithm: 184 +-----------------+-------------------------------------------------+ 185 | "alg" Param | Key Management Algorithm | 186 | Value | | 187 +-----------------+-------------------------------------------------+ 188 | ECDH-1PU+A128KW | ECDH-1PU using one-pass KDF and CEK wrapped | 189 | | with "A128KW" | 190 | ECDH-1PU+A192KW | ECDH-1PU using one-pass KDF and CEK wrapped | 191 | | with "A192KW" | 192 | ECDH-1PU+A256KW | ECDH-1PU using one-pass KDF and CEK wrapped | 193 | | with "A256KW" | 194 +-----------------+-------------------------------------------------+ 196 2.1. Special Considerations for Key Agreement with Key Wrapping mode 198 In Key Agreement with Key Wrapping mode, the JWE Authentication Tag 199 is included in the input to the Key Derivation Function as described 200 in section Section 2.3. This ensures that the content of the JWE was 201 produced by the original sender and not by another recipient, as 202 described in section Section 4. 204 Key Agreement with Key Wrapping mode MUST only be used with content 205 encryption algorithms that are compactly committing AEADs as 206 described in [ccAEAD]. The AES_CBC_HMAC_SHA2 algorithms described in 207 section 5.2 of [RFC7518] are compactly committing and can be used 208 with ECDH-1PU in Key Agreement with Key Wrapping mode. Other content 209 encryption algorithms MUST be rejected. In Direct Key Agreement 210 mode, any JWE content encryption algorithm MAY be used. 212 The requirement to include the JWE Authentication Tag in the input to 213 the Key Derivation Function implies an adjustment to the order of 214 operations performed during JWE Message Encryption described in 215 section 5.1 of [RFC7516]. Steps 3-8 are deferred until after step 216 15, using the randomly generated CEK from step 2 for encryption of 217 the message content. 219 2.2. Header Parameters used for ECDH Key Agreement 221 The "epk" (ephemeral public key), "apu" (Agreement PartyUInfo), and 222 "apv" (Agreement PartyVInfo) header parameters are used in ECDH-1PU 223 exactly as defined in Section 4.6.1 of [RFC7518]. 225 When no other values are supplied, it is RECOMMENDED that the 226 producer software initializes the "apu" header to the base64url- 227 encoding of the SHA-256 hash of the concatenation of the sender's 228 static public key and the ephemeral public key, and the "apv" header 229 to the base64url-encoding of the SHA-256 hash of the recipient's 230 static public key. This ensures that all keys involved in the key 231 agreement are cryptographically bound to the derived keys. 233 2.2.1. "skid" Header Parameter 235 A new Header Parameter "skid" (Sender Key ID) is registered as a hint 236 as to which of the sender's keys was used to authenticate the JWE. 237 The structure of the "skid" value is unspecified. Its value MUST be 238 a case-sensitive string. Use of this Header Parameter is OPTIONAL. 239 When used with a JWK, the "skid" value is used to match a JWK "kid" 240 parameter value [RFC7517]. 242 2.3. Key Derivation for ECDH-1PU Key Agreement 244 The key derivation process derives the agreed-upon key from the 245 shared secret Z established through the ECDH algorithm, per 246 Section 6.2.1.2 of [NIST.800-56A]. For the NIST prime order curves 247 "P-256", "P-384", and "P-521", the ECC CDH primitive for cofactor 248 Diffie-Hellman defined in Section 5.7.1.2 of [NIST.800-56A] is used 249 (taking note that the cofactor for all these curves is 1). For 250 curves "X25519" and "X448" the appropriate ECDH primitive from 251 Section 5 of [RFC7748] is used. 253 Key derivation is performed using the one-step KDF, as defined in 254 Section 5.8.1 and Section 5.8.2.1 of [NIST.800-56A] using the 255 Concatenation Format of Section 5.8.2.1.1, where the Auxilary 256 Function H is SHA-256. The KDF parameters are set as follows: 258 Z This is set to the representation of the shared secret Z as an 259 octet sequence. As per Section 6.2.1.2 of [NIST.800-56A] Z is the 260 concatenation of Ze and Zs, where Ze is the shared secret derived 261 from applying the ECDH primitive to the sender's ephemeral private 262 key and the recipient's static public key (when sending) or the 263 recipient's static private key and the sender's ephemeral public 264 key (when receiving). Zs is the shared secret derived from 265 applying the ECDH primitive to the sender's static private key and 266 the recipient's static public key (when sending) or the 267 recipient's static private key and the sender's static public key 268 (when receiving). 270 keydatalen This is set to the number of bits in the desired output 271 key. For "ECDH-1PU", this is the length of the key used by the 272 "enc" algorithm. For "ECDH-1PU+A128KW", "ECDH-1PU+A192KW", and 273 "ECDH-1PU+A256KW", this is 128, 192, and 256, respectively. 275 cctag In Direct Key Agreement mode this is set to an empty octet 276 string. In Key Agreement with Key Wrapping mode, this is set to a 277 value of the form Datalen || Data, where Data is the raw octets of 278 the JWE Authentication Tag, and Datalen is the big-endian 32-bit 279 length of the authentication tag (in octets). 281 AlgorithmID The AlgorithmID value is of the form Datalen || Data, 282 where Data is a variable-length string of zero or more octets, and 283 Datalen is a fixed-length, big-endian 32-bit counter that 284 indicates the length (in octets) of Data. In the Direct Key 285 Agreement case, Data is set to the octets of the ASCII 286 representation of the "enc" Header Parameter value. In the Key 287 Agreement with Key Wrapping case, Data is set to the octets of the 288 ASCII representation of the "alg" (algorithm) Header Parameter 289 value. 291 PartyUInfo The PartyUInfo value is of the form Datalen || Data, 292 where Data is a variable-length string of zero or more octets, and 293 Datalen is a fixed-length, big-endian 32-bit counter that 294 indicates the length (in octets) of Data. If an "apu" (agreement 295 PartyUInfo) Header Parameter is present, Data is set to the result 296 of base64url decoding the "apu" value and Datalen is set to the 297 number of octets in Data. Otherwise, Datalen is set to 0 and Data 298 is set to the empty octet sequence. 300 PartyVInfo The PartyVInfo value is of the form Datalen || Data, 301 where Data is a variable-length string of zero or more octets, and 302 Datalen is a fixed-length, big-endian 32-bit counter that 303 indicates the length (in octets) of Data. If an "apv" (agreement 304 PartyVInfo) Header Parameter is present, Data is set to the result 305 of base64url decoding the "apv" value and Datalen is set to the 306 number of octets in Data. Otherwise, Datalen is set to 0 and Data 307 is set to the empty octet sequence. 309 SuppPubInfo This is set to the keydatalen represented as a 32-bit 310 big-endian integer followed by the octets of the cctag. 312 SuppPrivInfo This is set to the empty octet sequence. 314 Applications need to specify how the "apu" and "apv" Header 315 Parameters are used for that application. The "apu" and "apv" values 316 MUST be distinct, when used. Applications wishing to conform to 317 [NIST.800-56A] need to provide values that meet the requirements of 318 that document, e.g., by using values that identify the producer and 319 consumer. 321 See Appendix A for an example key agreement computation using Direct 322 Key Agreement mode, and Appendix B for an example sending to multiple 323 recipients using Key Agreement with Key Wrapping mode. 325 3. IANA considerations 327 This section registers identifiers under the IANA JSON Web Signature 328 and Encryption Algorithms Registry established by [RFC7518] and the 329 IANA JSON Web Signature and Encryption Header Parameters registry 330 established by [RFC7515]. 332 3.1. JSON Web Signature and Encryption Algorithms Registration 334 This section registers JWE algorithms as per the registry established 335 in [RFC7518]. 337 3.1.1. ECDH-1PU 339 Algorithm Name: "ECDH-1PU" 340 Algorithm Description: ECDH One-Pass Unified Model using one-pass 341 KDF 342 Algorithm Usage Location(s): "alg" 343 JOSE Implementation Requirements: Optional 344 Change Controller: IESG 345 Specification Document(s): Section 2 346 Algorithm Analysis Document(s): [NIST.800-56A] (Section 7.3), 347 [PKAE] 349 Algorithm Name: "ECDH-1PU+A128KW" 350 Algorithm Description: ECDH One-Pass Unified Model using one-pass 351 KDF and "A128KW" 352 Algorithm Usage Location(s): "alg" 353 JOSE Implementation Requirements: Optional 354 Change Controller: IESG 355 Specification Document(s): Section 2 356 Algorithm Analysis Document(s): [NIST.800-56A] (Section 7.3), 357 [PKAE] 359 Algorithm Name: "ECDH-1PU+A192KW" 360 Algorithm Description: ECDH One-Pass Unified Model using one-pass 361 KDF and "A192KW" 362 Algorithm Usage Location(s): "alg" 363 JOSE Implementation Requirements: Optional 364 Change Controller: IESG 365 Specification Document(s): Section 2 366 Algorithm Analysis Document(s): [NIST.800-56A] (Section 7.3), 367 [PKAE] 369 Algorithm Name: "ECDH-1PU+A256KW" 370 Algorithm Description: ECDH One-Pass Unified Model using one-pass 371 KDF and "A256KW" 372 Algorithm Usage Location(s): "alg" 373 JOSE Implementation Requirements: Optional 374 Change Controller: IESG 375 Specification Document(s): Section 2 376 Algorithm Analysis Document(s): [NIST.800-56A] (Section 7.3), 377 [PKAE] 379 3.2. JSON Web Signature and Encryption Header Parameters Registration 381 This section registers new Header Parameters as per the registry 382 established in [RFC7515]. 384 3.2.1. skid 386 Header Parameter Name: "skid" 387 Header Parameter Description: Sender Key ID 388 Header Parameter Usage Location(s): JWE 389 Change Controller: IESG 390 Specification Document(s): Section 2.2.1 392 4. Security Considerations 394 The security considerations of [RFC7516] and [RFC7518] relevant to 395 ECDH-ES also apply to this specification. 397 The security considerations of [NIST.800-56A] apply here. 399 When performing an ECDH key agreement between a static private key 400 and any untrusted public key, care should be taken to ensure that the 401 public key is a valid point on the same curve as the private key. 402 Failure to do so may result in compromise of the static private key. 403 For the NIST curves P-256, P-384, and P-521, appropriate validation 404 routines are given in Section 5.6.2.3.3 of [NIST.800-56A]. For the 405 curves used by X25519 and X448, consult the security considerations 406 of [RFC7748]. 408 The ECDH-1PU algorithm is vulnerable to Key Compromise Impersonation 409 (KCI) attacks. If the long-term static private key of a party is 410 compromised, then the attacker can not only impersonate that party to 411 other parties, but also impersonate any other party when 412 communicating with the compromised party. If resistance to KCI is 413 desired in a single message, then the sender SHOULD use a nested JWS 414 signature over the content. 416 When Key Agreement with Key Wrapping is used, the JWE Authentication 417 Tag is included in the input to the Key Derivation Function, as 418 described in section Section 2.3. Without this step, when the same 419 Content Encryption Key (CEK) is reused for multiple recipients, then 420 any of those recipients can produce a new message that appears to 421 come from the original sender. If the MAC used by the content 422 encryption algorithm is not compactly committing ([ccAEAD]) then it 423 may be possible for a recipient to calculate an alternative message 424 that produces the same authentication tag. An alternative is to 425 encrypt the message separately to each recipient using Direct Key 426 Agreement, or to sign the message using a nested signed-then- 427 encrypted JOSE composition. 429 The security properties of the one-pass unified model are given in 430 Section 7.3 of [NIST.800-56A]. 432 5. References 434 5.1. Normative References 436 [NIST.800-56A] 437 Barker, E., Chen, L., Roginsky, A., Vassilev, A., and R. 438 Davis, "Recommendation for Pair-Wise Key Establishment 439 Using Discrete Logarithm Cryptography Revision 3.", NIST 440 Special Publication 800-56A, April 2018. 442 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 443 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 444 2015, . 446 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 447 RFC 7516, DOI 10.17487/RFC7516, May 2015, 448 . 450 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 451 DOI 10.17487/RFC7517, May 2015, 452 . 454 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 455 DOI 10.17487/RFC7518, May 2015, 456 . 458 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 459 for Security", RFC 7748, DOI 10.17487/RFC7748, January 460 2016, . 462 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 463 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 464 May 2017, . 466 5.2. Informative References 468 [ccAEAD] Grubbs, P., Lu, J., and T. Ristenpart, "Message Franking 469 via Committing Authenticated Encryption", IACR ePrint 470 2017/664, 2017. 472 [MRES] Bellare, M., Boldyreva, A., Kurosawa, K., and J. Staddon, 473 "Multi-Recipient Encryption Schemes: Efficient 474 Constructions and their Security", IEEE Transactions on 475 Information Theory Vol. 53, Number 11, 2007. 477 [PKAE] An, J., "Authenticated Encryption in the Public-Key 478 Setting: Security Notions and Analyses", IACR ePrint 479 2001/079, 2001. 481 [RFC8037] Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH) 482 and Signatures in JSON Object Signing and Encryption 483 (JOSE)", RFC 8037, DOI 10.17487/RFC8037, January 2017, 484 . 486 Appendix A. Example ECDH-1PU Key Agreement Computation with A256GCM 488 This example uses ECDH-1PU in Direct Key Agreement mode ("alg" value 489 "ECDH-1PU") to produce an agreed-upon key for AES GCM with a 256-bit 490 key ("enc" value "A256GCM"). The example re-uses the keys and 491 parameters of the example computation in Appendix C of [RFC7518], 492 with the addition of an extra static key-pair for Alice. 494 In this example, a producer Alice is encrypting content to a consumer 495 Bob. Alice's static key-pair (in JWK format) used for the key 496 agreement in this example (including the private part) is: 498 {"kty":"EC", 499 "crv":"P-256", 500 "x":"WKn-ZIGevcwGIyyrzFoZNBdaq9_TsqzGl96oc0CWuis", 501 "y":"y77t-RvAHRKTsSGdIYUfweuOvwrvDD-Q3Hv5J0fSKbE", 502 "d":"Hndv7ZZjs_ke8o9zXYo3iq-Yr8SewI5vrqd0pAvEPqg"} 504 Bob's static key-pair (in JWK format) is: 506 {"kty":"EC", 507 "crv":"P-256", 508 "x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ", 509 "y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck", 510 "d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw"} 512 The producer (Alice) generates an ephemeral key for the key agreement 513 computation. Alice's ephemeral key (in JWK format) is: 515 {"kty":"EC", 516 "crv":"P-256", 517 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 518 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps", 519 "d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo"} 521 Header Parameter values used in this example are as follows. The 522 "apu" (agreement PartyUInfo) Header Parameter value is the base64url 523 encoding of the UTF-8 string "Alice" and the "apv" (agreement 524 PartyVInfo) Header Parameter value is the base64url encoding of the 525 UTF-8 string "Bob". The "epk" (ephemeral public key) Header 526 Parameter is used to communicate the producer's (Alice's) ephemeral 527 public key value to the consumer (Bob). 529 {"alg":"ECDH-1PU", 530 "enc":"A256GCM", 531 "apu":"QWxpY2U", 532 "apv":"Qm9i", 533 "epk": 534 {"kty":"EC", 535 "crv":"P-256", 536 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 537 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps" 538 } 539 } 541 The resulting one-pass KDF [NIST.800-56A] parameter values are: 543 Ze This is set to the output of the ECDH key agreement between 544 Alice's ephemeral private key and Bob's static public key. In 545 this example, Ze is the following octet sequence (in hexadecimal 546 notation): 548 9e 56 d9 1d 81 71 35 d3 72 83 42 83 bf 84 26 9c 549 fb 31 6e a3 da 80 6a 48 f6 da a7 79 8c fe 90 c4 551 Zs This is set to the output of the ECDH key agreement between 552 Alice's static private key and Bob's static public key. In this 553 example, Zs is the following octet sequence (in hexadecimal 554 notation): 556 e3 ca 34 74 38 4c 9f 62 b3 0b fd 4c 68 8b 3e 7d 557 41 10 a1 b4 ba dc 3c c5 4e f7 b8 12 41 ef d5 0d 559 Z This is set to the concatenation of Ze followed by Zs. In this 560 example, Z is the following octet sequence (in hexadecimal 561 notation): 563 9e 56 d9 1d 81 71 35 d3 72 83 42 83 bf 84 26 9c 564 fb 31 6e a3 da 80 6a 48 f6 da a7 79 8c fe 90 c4 565 e3 ca 34 74 38 4c 9f 62 b3 0b fd 4c 68 8b 3e 7d 566 41 10 a1 b4 ba dc 3c c5 4e f7 b8 12 41 ef d5 0d 568 keydatalen This value is 256 - the number of bits in the desired 569 output key (because "A256GCM" uses a 256-bit key). 570 cctag This value is the empty octet string. 571 AlgorithmID This is set to the octets representing the 32-bit big- 572 endian value 7 - 00 00 00 07 in hexadecimal notation - the number 573 of octets in the AlgorithmID content "A256GCM", followed by the 574 octets representing the ASCII string "A256GCM" - 41 32 35 36 47 43 575 4d (in hex). The complete value is therefore: 00 00 00 07 41 32 576 35 36 47 43 4d 577 PartyUInfo This is set to the octets representing the 32-bit big- 578 endian value 5, followed by the octets representing the UTF-8 579 string "Alice". In hexadecimal notation: 00 00 00 05 41 6c 69 63 580 65 581 PartyVInfo This is set to the octets representing the 32-bit big- 582 endian value 3, followed by the octets representing the UTF-8 583 string "Bob". In hexadecimal notation: 00 00 00 03 42 6f 62 584 SuppPubInfo This is set to the octets representing the 32-bit big- 585 endian value 256 - the keydatalen value. In hexadecimal notation: 586 00 00 01 00 587 SuppPrivInfo This is set to the empty octet sequence. 589 Concatenating the parameters AlgorithmID through SuppPrivInfo results 590 in a FixedInfo value in Concatenation Format (as per 591 Section 5.8.2.1.1 of [NIST.800-56A]) of (in hexidecimal notation): 593 00 00 00 07 41 32 35 36 47 43 4d 00 00 00 05 41 594 6c 69 63 65 00 00 00 03 42 6f 62 00 00 01 00 596 Concatenating the round number 1 (00 00 00 01), Z, and the FixedInfo 597 value results in a one-pass KDF round 1 hash input of (hexadecimal): 599 00 00 00 01 9e 56 d9 1d 81 71 35 d3 72 83 42 83 600 bf 84 26 9c fb 31 6e a3 da 80 6a 48 f6 da a7 79 601 8c fe 90 c4 e3 ca 34 74 38 4c 9f 62 b3 0b fd 4c 602 68 8b 3e 7d 41 10 a1 b4 ba dc 3c c5 4e f7 b8 12 603 41 ef d5 0d 00 00 00 07 41 32 35 36 47 43 4d 00 604 00 00 05 41 6c 69 63 65 00 00 00 03 42 6f 62 00 605 00 01 00 607 The resulting derived key, which is the full 256 bits of the round 1 608 hash output is: 610 6c af 13 72 3d 14 85 0a d4 b4 2c d6 dd e9 35 bf 611 fd 2f ff 00 a9 ba 70 de 05 c2 03 a5 e1 72 2c a7 613 The base64url-encoded representation of this derived key is: 615 bK8Tcj0UhQrUtCzW3ek1v_0v_wCpunDeBcIDpeFyLKc 617 Appendix B. Example ECDH-1PU+A128KW Key Agreement computation with 618 A256CBC-HS256 620 This example uses ECDH-1PU in Key Agreement with Key Wrapping mode 621 ("alg" value "ECDH-1PU+A128KW") to encrypt a JWE for multiple 622 recipients using the JWE JSON Serialization. The example uses X25519 623 key pairs, as described in [RFC8037]. Alice is sending an identical 624 message to Bob and Charlie. Because Bob and Charlie are using the 625 same curve (X25519), Alice reuses the same ephemeral key-pair for 626 both recipients and includes it in the JWE Protected Header. If this 627 was not the case, Alice should generate a separate ephemeral key-pair 628 for each recipient and include it in each per-recipient header 629 instead. 631 Alice's static key pair, represented as an OKP JWK (including the 632 private component) is: 634 {"kty": "OKP", 635 "crv": "X25519", 636 "x": "Knbm_BcdQr7WIoz-uqit9M0wbcfEr6y-9UfIZ8QnBD4", 637 "d": "i9KuFhSzEBsiv3PKVL5115OCdsqQai5nj_Flzfkw5jU"} 639 Bob's static key-pair (in JWK format) is: 641 {"kty": "OKP", 642 "crv": "X25519", 643 "x": "BT7aR0ItXfeDAldeeOlXL_wXqp-j5FltT0vRSG16kRw", 644 "d": "1gDirl_r_Y3-qUa3WXHgEXrrEHngWThU3c9zj9A2uBg"} 646 Charlie's static key-pair (in JWK format) is: 648 {"kty": "OKP", 649 "crv": "X25519", 650 "x": "q-LsvU772uV_2sPJhfAIq-3vnKNVefNoIlvyvg1hrnE", 651 "d": "Jcv8gklhMjC0b-lsk5onBbppWAx5ncNtbM63Jr9xBQE"} 653 Alice generates an ephemeral key-pair on the same curve. Alice's 654 ephemeral key-pair (in JWK format) is: 656 {"kty": "OKP", 657 "crv": "X25519", 658 "x": "k9of_cpAajy0poW5gaixXGs9nHkwg1AFqUAFa39dyBc", 659 "d": "x8EVZH4Fwk673_mUujnliJoSrLz0zYzzCWp5GUX2fc8"} 661 B.1. JWE Protected Header 663 The JWE Protected Header is as follows. The "apu" (agreement 664 PartyUInfo) Header Parameter value is the base64url encoding of the 665 UTF-8 string "Alice" and the "apv" (agreement PartyVInfo) Header 666 Parameter value is the base64url encoding of the UTF-8 string "Bob 667 and Charlie". The "epk" (ephemeral public key) Header Parameter is 668 used to communicate the producer's (Alice's) ephemeral public key to 669 the consumers (Bob and Charlie). 671 {"alg":"ECDH-1PU+A128KW", 672 "enc":"A256CBC-HS512", 673 "apu":"QWxpY2U", 674 "apv":"Qm9iIGFuZCBDaGFybGll", 675 "epk": 676 {"kty":"OKP", 677 "crv":"X25519", 678 "x":"k9of_cpAajy0poW5gaixXGs9nHkwg1AFqUAFa39dyBc"}} 680 B.2. JWE Per-Recipient Unprotected Headers 682 The following JWE Per-Recipient Unprotected Header values are used 683 for Bob and Charlie respectively: 685 {"kid":"bob-key-2"} 686 {"kid":"2021-05-06"} 688 B.3. JWE Shared Unprotected Header 690 This JWE uses the "jku" Header Parameter to reference a JWK Set. 691 This is represented in the following JWE Shared Unprotected Header 692 value as: 694 {"jku":"https://alice.example.com/keys.jwks"} 696 B.4. Additional Authenticated Data 698 Let the Additional Authenticated Data encryption parameter be 699 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 701 [123, 34, 97, 108, 103, 34, 58, 34, 69, 67, 68, 72, 45, 49, 80, 85, 702 43, 65, 49, 50, 56, 75, 87, 34, 44, 34, 101, 110, 99, 34, 58, 34, 703 65, 50, 53, 54, 67, 66, 67, 45, 72, 83, 53, 49, 50, 34, 44, 34, 97, 704 112, 117, 34, 58, 34, 81, 87, 120, 112, 89, 50, 85, 34, 44, 34, 97, 705 112, 118, 34, 58, 34, 81, 109, 57, 105, 73, 71, 70, 117, 90, 67, 66, 706 68, 97, 71, 70, 121, 98, 71, 108, 108, 34, 44, 34, 101, 112, 107, 707 34, 58, 123, 34, 107, 116, 121, 34, 58, 34, 79, 75, 80, 34, 44, 34, 708 99, 114, 118, 34, 58, 34, 88, 50, 53, 53, 49, 57, 34, 44, 34, 120, 709 34, 58, 34, 107, 57, 111, 102, 95, 99, 112, 65, 97, 106, 121, 48, 710 112, 111, 87, 53, 103, 97, 105, 120, 88, 71, 115, 57, 110, 72, 107, 711 119, 103, 49, 65, 70, 113, 85, 65, 70, 97, 51, 57, 100, 121, 66, 99, 712 34, 125, 125] 714 B.5. Content Encryption Key 716 Alice generates the following 512-bit Content Encryption Key (CEK) 717 for A256CBC-HS512 (shown in hexadecimal): 719 ff fe fd fc fb fa f9 f8 f7 f6 f5 f4 f3 f2 f1 f0 720 ef ee ed ec eb ea e9 e8 e7 e6 e5 e4 e3 e2 e1 e0 721 df de dd dc db da d9 d8 d7 d6 d5 d4 d3 d2 d1 d0 722 cf ce cd cc cb ca c9 c8 c7 c6 c5 c4 c3 c2 c1 c0 724 B.6. Initialization Vector 726 She then generates the following random JWE Initialization Vector 727 (IV): 729 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 731 B.7. JWE Plaintext 733 The plaintext of the message Alice sends to Bob and Charlie is the 734 UTF-8 bytes of the string "Three is a magic number." (without the 735 quotes). The octets of the plaintext are: 737 [84, 104, 114, 101, 101, 32, 105, 115, 32, 97, 32, 109, 97, 103, 105, 99, 738 32, 110, 117, 109, 98, 101, 114, 46] 740 B.8. Content Encryption 742 Alice performs authenticated encryption on the plaintext with the 743 AES_256_CBC_HMAC_SHA_512 algorithm using the CEK as the encryption 744 key, the JWE Initialization Vector, and the Additional Authenticated 745 Data value above. This algorithm is described in [RFC7518]. The 746 resulting ciphertext (in base64url encoding) is: 748 Az2IWsISEMDJvyc5XRL-3-d-RgNBOGolCsxFFoUXFYw 750 The resulting JWE Authentication Tag is (in base64url encoding): 752 HLb4fTlm8spGmij3RyOs2gJ4DpHM4hhVRwdF_hGb3WQ 754 B.9. Key Agreement for Bob 756 The KDF input parameters for Bob are as follows: 758 Ze This is set to the ECDH key agreement output between Alice's 759 ephemeral private key and Bob's static public key. In this 760 example, Ze is the following octet sequence (in hexadecimal): 762 32 81 08 96 e0 fe 4d 57 0e d1 ac fc ed f6 71 17 763 dc 19 4e d5 da ac 21 d8 ff 7a f3 24 46 94 89 7f 765 Zs This is set to the ECDH key agreement output between Alice's 766 static private key and Bob's static public key. In this example, 767 Zs is the following octet sequence (in hexadecimal): 769 21 57 61 2c 90 48 ed fa e7 7c b2 e4 23 71 40 60 770 59 67 c0 5c 7f 77 a4 8e ea f2 cf 29 a5 73 7c 4a 772 Z Z is the concatenation of Ze followed by Zs. In this example, the 773 value of Z is: 775 32 81 08 96 e0 fe 4d 57 0e d1 ac fc ed f6 71 17 776 dc 19 4e d5 da ac 21 d8 ff 7a f3 24 46 94 89 7f 777 21 57 61 2c 90 48 ed fa e7 7c b2 e4 23 71 40 60 778 59 67 c0 5c 7f 77 a4 8e ea f2 cf 29 a5 73 7c 4a 780 keydatalen This value is 128 - the number of bits in the desired 781 output key (because "ECDH-1PU+A128KW" uses a 128-bit key-wrapping 782 key). 783 cctag This is set to the octets of the JWE Authentication Tag, 784 prefixed by the length of the authentication tag (number of 785 octets) as a big-endian 32-bit unsigned integer. For the 786 "A256CBC-HS512" algorithm used in this example, the tag is 32 787 octets in size (00 00 00 20 in hex). The complete value of the 788 cctag parameter for this example (in hex) is: 790 00 00 00 20 1c b6 f8 7d 39 66 f2 ca 46 9a 28 f7 791 47 23 ac da 02 78 0e 91 cc e2 18 55 47 07 45 fe 792 11 9b dd 64 794 AlgorithmID This is set to the octets representing the big-endian 795 value 15 - 00 00 00 0F in hexadecimal notation - the number of 796 octets in the ASCII encoding of "ECDH-1PU+A128KW", followed by the 797 octets representing that string - 45 43 44 48 2d 31 50 55 2b 41 31 798 32 38 4b 57 (in hex). The complete value is therefore 00 00 00 0f 799 45 43 44 48 2d 31 50 55 2b 41 31 32 38 4b 57 800 PartyUInfo This is set to the octets representing the big-endian 801 value 5 followed by the octets of the UTF-8 encoding of "Alice": 802 00 00 00 05 41 6c 69 63 65 (in hex). 803 PartyVInfo This is set to the octets representing the big-endian 804 value 15 followed by the octets of the UTF-8 encoding of "Bob and 805 Charlie": 00 00 00 0f 42 6f 62 20 61 6e 64 20 43 68 61 72 6c 69 65 806 (in hex). 807 SuppPubInfo This is set to the octets representing the 32-bit big- 808 endian encoding of the keydatalen followed by the octets of the 809 cctag. The complete value is as follows (in hex): 811 00 00 00 80 00 00 00 20 1c b6 f8 7d 39 66 f2 ca 812 46 9a 28 f7 47 23 ac da 02 78 0e 91 cc e2 18 55 813 47 07 45 fe 11 9b dd 64 815 SuppPrivInfo This is set to the empty octet sequence. 817 Concatenating the parameters AlgorithmID through SuppPrivInfo results 818 in a FixedInfo value in Concatenation Format (as per 819 Section 5.8.2.1.1 of [NIST.800-56A] of (in hexadecimal notation): 821 00 00 00 0f 45 43 44 48 2d 31 50 55 2b 41 31 32 822 38 4b 57 00 00 00 05 41 6c 69 63 65 00 00 00 0f 823 42 6f 62 20 61 6e 64 20 43 68 61 72 6c 69 65 00 824 00 00 80 00 00 00 20 1c b6 f8 7d 39 66 f2 ca 46 825 9a 28 f7 47 23 ac da 02 78 0e 91 cc e2 18 55 47 826 07 45 fe 11 9b dd 64 828 Concatenating the round number 1 (00 00 00 01), Z, and the FixedInfo 829 value results in a one-pass KDF round 1 hash input of (hexadecimal): 831 00 00 00 01 32 81 08 96 e0 fe 4d 57 0e d1 ac fc 832 ed f6 71 17 dc 19 4e d5 da ac 21 d8 ff 7a f3 24 833 46 94 89 7f 21 57 61 2c 90 48 ed fa e7 7c b2 e4 834 23 71 40 60 59 67 c0 5c 7f 77 a4 8e ea f2 cf 29 835 a5 73 7c 4a 00 00 00 0f 45 43 44 48 2d 31 50 55 836 2b 41 31 32 38 4b 57 00 00 00 05 41 6c 69 63 65 837 00 00 00 0f 42 6f 62 20 61 6e 64 20 43 68 61 72 838 6c 69 65 00 00 00 80 00 00 00 20 1c b6 f8 7d 39 839 66 f2 ca 46 9a 28 f7 47 23 ac da 02 78 0e 91 cc 840 e2 18 55 47 07 45 fe 11 9b dd 64 842 The resulting derived key, which is the first 16 octets of the round 843 1 hash output is: 845 df 4c 37 a0 66 83 06 a1 1e 3d 6b 00 74 b5 d8 df 847 The derived key is then used with the "A128KW" key-wrapping algorithm 848 described in [RFC7518] to encrypt the CEK, resulting the following 849 JWE Encrypted Key (in base64url encoding with line breaks for display 850 purposes only): 852 pOMVA9_PtoRe7xXW1139NzzN1UhiFoio8lGto9cf0t8PyU-sjNXH8-LIRLycq8CHJQ 853 bDwvQeU1cSl55cQ0hGezJu2N9IY0QN 855 B.10. Key Agreement for Charlie 857 The KDF input parameters for Charlie are as follows: 859 Ze This is set to the ECDH key agreement output between Alice's 860 ephemeral private key and Charlie's static public key. In this 861 example, Ze is the following octet sequence (in hexadecimal): 863 89 dc fe 4c 37 c1 dc 02 71 f3 46 b5 b3 b1 9c 3b 864 70 5c a2 a7 2f 9a 23 77 85 c3 44 06 fc b7 5f 10 866 Zs This is set to the ECDH key agreement output between Alice's 867 static private key and Charlie's static public key. In this 868 example, Zs is the following octet sequence (in hexadecimal): 870 78 fe 63 fc 66 1c f8 d1 8f 92 a8 42 2a 64 18 e4 871 ed 5e 20 a9 16 81 85 fd ee dc a1 c3 d8 e6 a6 1c 873 Z Z is the concatenation of Ze followed by Zs. In this example, the 874 value of Z is: 876 89 dc fe 4c 37 c1 dc 02 71 f3 46 b5 b3 b1 9c 3b 877 70 5c a2 a7 2f 9a 23 77 85 c3 44 06 fc b7 5f 10 878 78 fe 63 fc 66 1c f8 d1 8f 92 a8 42 2a 64 18 e4 879 ed 5e 20 a9 16 81 85 fd ee dc a1 c3 d8 e6 a6 1c 881 The FixedInfo value is identical to that computed for Bob. 882 Concatenating the round number 1 (00 00 00 01), Z, and the FixedInfo 883 value results in a one-pass KDF round 1 hash input of (hexadecimal): 885 00 00 00 01 89 dc fe 4c 37 c1 dc 02 71 f3 46 b5 886 b3 b1 9c 3b 70 5c a2 a7 2f 9a 23 77 85 c3 44 06 887 fc b7 5f 10 78 fe 63 fc 66 1c f8 d1 8f 92 a8 42 888 2a 64 18 e4 ed 5e 20 a9 16 81 85 fd ee dc a1 c3 889 d8 e6 a6 1c 00 00 00 0f 45 43 44 48 2d 31 50 55 890 2b 41 31 32 38 4b 57 00 00 00 05 41 6c 69 63 65 891 00 00 00 0f 42 6f 62 20 61 6e 64 20 43 68 61 72 892 6c 69 65 00 00 00 80 00 00 00 20 1c b6 f8 7d 39 893 66 f2 ca 46 9a 28 f7 47 23 ac da 02 78 0e 91 cc 894 e2 18 55 47 07 45 fe 11 9b dd 64 896 The resulting derived key, which is the first 16 octets of the round 897 1 hash output is: 899 57 d8 12 6f 1b 7e c4 cc b0 58 4d ac 03 cb 27 cc 901 The derived key is then used with the "A128KW" key-wrapping algorithm 902 described in [RFC7518] to encrypt the CEK, resulting the following 903 JWE Encrypted Key (in base64url encoding with line breaks for display 904 purposes only): 906 56GVudgRLIMEElQ7DpXsijJVRSWUSDNdbWkdV3g0GUNq6hcT_GkxwnxlPIWrTXCqRp 907 VKQC8fe4z3PQ2YH2afvjQ28aiCTWFE 909 B.11. Complete JWE JSON Serialization Representation 911 The complete JWE JSON Serialization for these values is as follows 912 (with line breaks within values for display purposes only): 914 { 915 "protected": 916 "eyJhbGciOiJFQ0RILTFQVStBMTI4S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiYXB1Ijoi 917 UVd4cFkyVSIsImFwdiI6IlFtOWlJR0Z1WkNCRGFHRnliR2xsIiwiZXBrIjp7Imt0eSI6Ik9L 918 UCIsImNydiI6IlgyNTUxOSIsIngiOiJrOW9mX2NwQWFqeTBwb1c1Z2FpeFhHczluSGt3ZzFB 919 RnFVQUZhMzlkeUJjIn19", 920 "unprotected": 921 {"jku":"https://alice.example.com/keys.jwks"}, 922 "recipients":[ 923 {"header": 924 {"kid":"bob-key-2"}, 925 "encrypted_key": 926 "pOMVA9_PtoRe7xXW1139NzzN1UhiFoio8lGto9cf0t8PyU-sjNXH8-LIRLycq8CHJQbDwvQ 927 eU1cSl55cQ0hGezJu2N9IY0QN"}, 928 {"header": 929 {"kid":"2021-05-06"}, 930 "encrypted_key": 931 "56GVudgRLIMEElQ7DpXsijJVRSWUSDNdbWkdV3g0GUNq6hcT_GkxwnxlPIWrTXCqRpVKQC8 932 fe4z3PQ2YH2afvjQ28aiCTWFE"}], 933 "iv": 934 "AAECAwQFBgcICQoLDA0ODw", 935 "ciphertext": 936 "Az2IWsISEMDJvyc5XRL-3-d-RgNBOGolCsxFFoUXFYw", 937 "tag": 938 "HLb4fTlm8spGmij3RyOs2gJ4DpHM4hhVRwdF_hGb3WQ" 939 } 941 Appendix C. Document History 943 -04 Added requirement to include the JWE Authentication Tag in the 944 KDF input when using Key Agreement with Key Wrapping mode to 945 ensure security against insider threats when sending to multiple 946 recipients. Added worked example for a multi-recipient JWE in 947 Appendix B. 948 -03 Corrected typos and clarified wording. Removed unnecessary 949 references. 950 -02 Removed two-way interactive handshake protocol section and 951 example after discussion with Hannes Tschofenig. 952 -01 Added examples in Appendix A and a two-way handshake example. 953 Added "skid" Header Parameter and registration. Fleshed out 954 Security Considerations. 956 Author's Address 958 Neil Madden 959 ForgeRock 960 Broad Quay House 961 Prince Street 962 Bristol BS1 4DJ 963 United Kingdom 965 Email: neil.madden@forgerock.com