idnits 2.17.1 draft-miller-jose-jwe-protected-jwk-01.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 lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (February 21, 2013) is 4076 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) == Outdated reference: A later version (-40) exists of draft-ietf-jose-json-web-algorithms-08 == Outdated reference: A later version (-40) exists of draft-ietf-jose-json-web-encryption-08 == Outdated reference: A later version (-41) exists of draft-ietf-jose-json-web-key-08 ** Obsolete normative reference: RFC 2898 (Obsoleted by RFC 8018) ** Downref: Normative reference to an Informational RFC: RFC 3394 ** Downref: Normative reference to an Informational RFC: RFC 4949 -- Duplicate reference: RFC2898, mentioned in 'RFC3447', was also mentioned in 'RFC2898'. -- Obsolete informational reference (is this intentional?): RFC 2898 (ref. 'RFC3447') (Obsoleted by RFC 8018) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Miller 3 Internet-Draft Cisco Systems, Inc. 4 Intended status: Standards Track February 21, 2013 5 Expires: August 25, 2013 7 Using JavaScript Object Notation (JSON) Web Encryption (JWE) for 8 Protecting JSON Web Key (JWK) Objects 9 draft-miller-jose-jwe-protected-jwk-01 11 Abstract 13 This document specifies an approach to protecting a private key 14 formatted as a JavaScript Syntax Object Notation (JSON) Web Key (JWK) 15 object using JSON Web Encryption (JWE). This document also specifies 16 a set of algorithms for protecting such content using password-based 17 cryptography. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on August 25, 2013. 36 Copyright Notice 38 Copyright (c) 2013 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. Protecting Keys . . . . . . . . . . . . . . . . . . . . . . . 3 56 3.1. Details for Private Keys . . . . . . . . . . . . . . . . 4 57 3.2. Details for Symmetric Keys . . . . . . . . . . . . . . . 4 58 4. Private Key Example . . . . . . . . . . . . . . . . . . . . . 5 59 5. Symmetric Key Example . . . . . . . . . . . . . . . . . . . . 8 60 6. Using Password-Based Cryptography . . . . . . . . . . . . . . 10 61 6.1. PBKDF2 Key Type . . . . . . . . . . . . . . . . . . . . . 10 62 6.1.1. 's' Parameter . . . . . . . . . . . . . . . . . . . . 10 63 6.1.2. 'c' Parameter . . . . . . . . . . . . . . . . . . . . 10 64 6.1.3. 'hint' Parameter . . . . . . . . . . . . . . . . . . 10 65 6.2. PBES2 Key Encryption Algorithms . . . . . . . . . . . . . 10 66 6.2.1. PBES2-HS256+A128KW . . . . . . . . . . . . . . . . . 11 67 6.2.2. PBES2-HS512+A256KW . . . . . . . . . . . . . . . . . 11 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 69 7.1. JSON Web Key Types Registration . . . . . . . . . . . . . 11 70 7.2. JSON Web Key Parameters Registration . . . . . . . . . . 12 71 7.3. JSON Web Encryption Algorithms . . . . . . . . . . . . . 12 72 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 73 8.1. Re-using Keying Material . . . . . . . . . . . . . . . . 13 74 8.2. Password Considerations . . . . . . . . . . . . . . . . . 13 75 9. Internationalization Considerations . . . . . . . . . . . . . 13 76 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 77 10.1. Normative References . . . . . . . . . . . . . . . . . . 14 78 10.2. Informative References . . . . . . . . . . . . . . . . . 15 79 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 80 Appendix B. Document History . . . . . . . . . . . . . . . . . . 15 81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 83 1. Introduction 85 There are times when it is necessary to transport a private key, 86 whether the private component to an asymmetric cipher key-pair or a 87 symmetric cipher key used for encryption or generating a message 88 authentication code (MAC), where the transport mechanism might not 89 provide adequate content protection for the key. For instance, end- 90 to-end scenarios where the key holder and key recipient are linked 91 through multiple network hops that might or might not employ 92 transport layer security (TLS, [RFC5246]), or the key holder an key 93 recipient (often the same human being) might exchange a private key 94 using physical media such as a USB drive that itself is not 95 encrypted. 97 This document specifies an approach that uses JavaScript Object 98 Notation (JSON) Web Encryption [JWE] to encrypt a private key that is 99 formatted as a JSON Web Key [JWK]. While [JWE] provides protection 100 of symmetric keys, this key is itself intended for the protection of 101 content, not as the content itself. Further, [JWE] does not itself 102 provide protection of an asymmetric private key. 104 Ofttimes the transport of private keys involves direct interaction 105 with human beings. In these scenarios the use of a human- 106 understandable password or passphrase to protect the private key is 107 desirable. Therefore, this document also specifies and registers JWK 108 formats and JWE algorithms based on [RFC2898] to allow for protecting 109 content using a password. 111 2. Terminology 113 This document inherits JSON Web Algorithms (JWA)-related terminology 114 from [JWA], JSON Web Encryption (JWE)-related terminology from [JWE], 115 JSON Web Key (JWK)-related terminology from [JWK], and password-based 116 cryptography-related terminology from [RFC2898]. Security-related 117 terms are to be understood in the sense defined in [RFC4949]. 119 The capitalized key words "MUST", "MUST NOT", "REQUIRED", "SHALL", 120 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 121 "OPTIONAL" in this document are to be interpreted as described in 122 [RFC2119]. 124 3. Protecting Keys 126 The process for protecting private keys and symmetric keys are 127 identical. The only differences are typically the algorithms used to 128 protect the key. 130 To protect a private key, the key holder performs the following 131 steps: 133 1. Converts the JWK object to a UTF-8 encoded string (K'). 135 2. Performs the message encryption steps from [JWE] to generate the 136 JWE header H, JWE Encrypted Key E, JWE Initialization Vector IV, 137 JWE Ciphertext C, and JWE Integrity Value I, using the following 138 inputs: 140 * The 'alg' property set to the intended key encryption 141 algorithm (e.g., "RSA-OAEP", or "PBES2-HS512+A256KW" from 142 below). 144 * Keying material appropriate for the selected key encryption 145 algorithm (e.g., private key for "RSA-OAEP", or shared 146 password, salt, and iteration count for "PBES2-HS512+A256KW"). 148 * The 'enc' property set to the intended content encryption 149 algorithm (e.g., "A256GCM" or "A256CBC+HS512"). 151 * Keying material appropriate for the selected content 152 encryption algorithm (e.g., Content Encryption Key and 153 Initialization Vector). 155 * K' as the plaintext content to encrypt. 157 3. Serializes to the appropriate format for exchange, such as the 158 Compact Serialization documented in [JWE]. 160 3.1. Details for Private Keys 162 Private keys are typically protected using a symmetric key. This 163 symmetric key can be exchanged or determined in various ways, such as 164 deriving one from a user-supplied password; the algorithms 165 "PBES2-HS256+A128KW" and "PBES2-HS512+A256KW" (defined in 166 Section 6.2) enable this. 168 3.2. Details for Symmetric Keys 170 Symmetric keys are typically protected using public-private key 171 pairs. It is assumed the key holder has the appropriate public 172 key(s) for the key recipient(s). 174 The process defined herein expects JWK objects. While more compact 175 to simply encrypt the symmetric key directly with a public key, using 176 the complete JWE process on complete JWK objects allows additional 177 properties to be protected (e.g., expected lifetime, acceptable uses) 178 without exceeding the very restrictive plaintext length limits in 179 most public-private key operations (e.g., 234 octects when using the 180 "RSA-OAEP" algorithm with a 2048-bit key). 182 4. Private Key Example 184 NOTE: unless otherwise indicated, all line breaks are included for 185 readability. 187 The key holder begins with the [JWK] representation of the private 188 key (here using a [RFC3447] RSA private key, formatted per [JPSK]): 190 { 191 "kty":"RSA", 192 "kid":"juliet@capulet.lit", 193 "n":"ALekPD1kotXZCY_YUz_ITWBZb2nTOw35VvZlnqTiYSeusO58qCtYDz 194 ahTEkEcjtduRqfkxJKHYVq9Iro4x1cewXFdJZUuMOQAhoD63AHemXE 195 kdPiKqJvkBXDT_Eo4NPOjMKKkFPy2MsJQBmdtVknUvzxEchhYjZ490 196 EJTvGJ7OYwrSwkcCxy9D29XxL-OQLkSLlH1XD8kgVmJw8hsb42Bg0j 197 PgKlkvcyENmYpYE_hqlJoqYNFzgtAnNtK4C3tspix46R3IgilQG2Of 198 i99vpUnmTvjrOlNef2l65PRsPHD1Gl9fyPLCxrkolXbdwvxZ9j2d2f 199 Iu-OBTxRhnBtarNls_k", 200 "e":"AQAB", 201 "d":"GRtbIQmhOZtyszfgKdg4u_N-R_mZGU_9k7JQ_jn1DnfTuMdSNprTea 202 STyWfSNkuaAwnOEbIQVy1IQbWVV25NY3ybc_IhUJtfri7bAXYEReWa 203 Cl3hdlPKXy9UvqPYGR0kIXTQRqns-dVJ7jahlI7LyckrpTmrM8dWBo 204 4_PMaenNnPiQgO0xnuToxutRZJfJvG4Ox4ka3GORQd9CsCZ2vsUDms 205 XOfUENOyMqADC6p1M3h33tsurY15k9qMSpG9OX_IJAXmxzAh_tWiZO 206 wk2K4yxH9tS3Lq1yX8C1EWmeRDkK2ahecG85-oLKQt5VEpWHKmjOi_ 207 gJSdSgqcN96X52esAQ", 208 "p":"ANq50jleISkjfLEuAoHEBxW7NPF26BQ6irpt7HOIdxkca05kHZdWSv 209 bsPjyB30D9BZMV1a8flhPmRG66orx_9ogi1Eu8AJel7wEbdSpCGlMT 210 z0mAfcpN9bNEPFCvehN_zqwAwGLQCbPjNycQi3zYKoeehw5xE00IR9 211 6wk-U98icL", 212 "q":"2a43135aa05479f570676fc36e3d693d0ab21d21e38fdd0be71fcc 213 3b3a9800931c2cc66d6d4b702aabd50eaded6c4a3764872885b0ed 214 b7a49b7e65b382069ba50c4dc6e069a0e39ffdafc780c5cafe586a 215 8a0238cbf92a4b5c18e762308d49f9ae046b27ec98a35878d4a47e 216 bf3da9621100798ae1b6d5adc55a8b0915620fa7", 217 "dp":"KkMTWqBUefVwZ2_Dbj1pPQqyHSHjj90L5x_MOzqYAJMcLMZtbUtwK 218 qvVDq3tbEo3ZIcohbDtt6SbfmWzggabpQxNxuBpoOOf_a_HgMXK_l 219 hqigI4y_kqS1wY52IwjUn5rgRrJ-yYo1h41KR-vz2pYhEAeYrhttW 220 txVqLCRViD6c", 221 "dq":"AvfS0-gRxvn0bwJoMSnFxYcK1WnuEjQFluMGfwGitQBWtfZ1Er7t1 222 xDkbN9GQTB9yqpDoYaN06H7CFtrkxhJIBQaj6nkF5KKS3TQtQ5qCz 223 kOkmxIe3KRbBymXxkb5qwUpX5ELD5xFc6FeiafWYY63TmmEAu_lRF 224 COJ3xDea-ots", 226 "qi":"AJUkIvsPQqclEXjBKz9UbAS5O8DbTr7OREKT6prjL6luezQVHM0nB 227 KD8JlKqmm7vVdPj8uHUOe_22qaCkbtUfdG77hZ1Ot0h1hBYJWULyQ 228 zHgL5o-LJvhadKGLv53qLYENIc2yOYK8u2o3WMvftpTcf--mgWaDl 229 LvRwiflLH0jiP" 230 } 232 The key holder uses the following [JWE] inputs: 234 JWE Header: 236 { 237 "alg":"PBES2-HS256+A128KW", 238 "enc":"A128CBC+HS256", 239 "jwk":{ 240 "kty":"PBKDF2", 241 "s":"2WCTcJZ1Rvd_CJuJripQ1w", 242 "c":4096 243 } 244 } 246 Password: 248 Thus from my lips, by yours, my sin is purged. 250 Content Master Key (encoded as base64url per [RFC4648]): 252 1ICvnpc3zPRNS7JoJ9bnJ929eX7EnRwmc0CHNOF1zKc 254 Initialization Vector (encoded as base64url per [RFC4648]): 256 B9BVK3hIsEu9zUOWjKeOSg 258 The key holder performs steps 1 and 2 to generate the [JWE] outputs 259 (represented using the Compact Serialization): 261 eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDK0hTMjU 262 2IiwiandrIjp7Imt0eSI6IlBCS0RGMiIsInNhbHQiOiIyV0NUY0paMVJ2ZF9DSn 263 VKcmlwUTF3IiwiaXRycyI6NDA5Nn19. 264 dO4VTHV1JJnnPxbc9xswMA6ezNLCQ1Nq0Bnt4l2hjzxyXfbgM3w-cQ. 265 B9BVK3hIsEu9zUOWjKeOSg. 266 mUt0YpU0Gsfis7tK70aggz5Qb5J6oppjl7aSn_S4DIHJkSF-Gd9KEu4XF0vbMc1 267 kvovNOmnahDLoJIq7hoB666zt1yp4umZKuzhOQ5O3jwOwC4rUf1W3hDM5p2nYZq 268 LFqDBme-Z8KVwosfBj2TkZSnFWC6cqMy6d7K6egWz7uct39ZH6_FAUrr0JiMMnj 269 0jxTEBP6apiLD-GJutxITnWISmGmX0jOWyTKRh-F-I3lJ3pXE0_4vWR8-gXaFGW 270 CgItofAOsdKKoxiSJvXPVxK-oqPFPlS0H5OLHw9tkjmPVZ0Ot-RLgoMPQJ0Yi47 271 U0DBh_2-IQBcpPvwBnUzl8KcrLFh-NpTSoC_zIn6xos5r4JVXf5v1V79MKGvk3- 272 evdQoEKtS9LnimKTP8YmeqAnU1Y3VoUkgeRTZikKhQ_kwpAxakaRuBzfaIOKjqY 273 X5J_jSJuuBQU_4fgHPkvrq1zJ3TnUAWZIqFcw27dKGMxXLMlz_sbW2YerZ0BULc 274 xbe8bJpbHkE64r7Nc86iZyL6e-8htkUvpGmdQGqno-q723Ry-u2Iz1-exjgjbNu 275 z4tbSrf49Y0_VSFEuHLnCRChVQE8cgupCy8GioEpuC7v1hMNE7JZTVbG3Ud3QzZ 276 Webr0sAYjWwqa2ySoJ7AaRfIiVgMdTAS2_gBdbYRSYI2pkQTHpyZ8D_lp5RvYFR 277 FNsHWoEToXeL1P_csuKaGsikKbzgXdevrjmCJTOpByGYO5cb2O8xFyYy1VX_pM6 278 bxqj5ai8-jyiCoDKvF_40wT_9F6H79UIZtuc3L7r7OxKrmY32LLvfofVRsfdIcK 279 AhMvnvOCpzRN3sHiR7iAx1bvaIaz40Mshf8z-__70GEqr5oWxRwyv2uhCiPHtV6 280 lBIhCqki6th317-n_lR58LHw894ja0xbOOxUJfZziaG14O9tqjetTSB0JGKXC4S 281 ry6zzeyqDwsSpY439Uqn7va_V5ELLfJf9S7fh0AtZS3ogpw4oT-6LbywFPf0jH9 282 LgNmatORG_J2wgu8R8QpKogo_WTQK7izHVtEMe1vQQElAy8P2SUjOJiOU6wAW4o 283 neU7HUUwD3cvFSn-ykze48FurI5f6DXyPNTVtzaEjBnVVP517bGb_3V_-1SCBdZ 284 1f_sYWJ0S8r2u5ccy28CP_7MhZOY8r4oJJn2NmT_jDOllCNtJLKVdKon0QslEER 285 GXa8r6Jtp3UbfLVjZQbnFl2mBygH4PoWbyGVxUNDE66mZVKM4Y-6ng5L84PrDt5 286 aAQ0HREqjvX4bsQgWyXKq-HRe5DXO2qdoPAIoPGhqOlZz70iYHO5lkX_Oso3eBv 287 DCDVbkD7Gr-LZJusrVtA6Hf82YpUUldjyPsD985T2hdcSQMoxol8aWNDL52T4Eo 288 FTTLFNG0Xy3qvS79ScgMOSIOE8k_DgzyBrcGJibeeaVKGdbqUQRADaeWO2QM3Rq 289 9TOyizLNyyjkJBgecWtIfLAWSTPx7n39zuBhGb5oChAFlR1HqrV76KO22rj08ra 290 J_zi8YQpp4qTTXmYwY5sjftE8IDDcLxk6ovvDM7262onZ5CP3GKp09s9dTJZi2L 291 tmZ8NAHlJ5Q9v9XMHi0tvLKKlahdcvgnG3sC_gL46osnNE3gBipLe_IQNl0X0zU 292 cakwzYtC02JeBbNFQSduY4OBiAAhD2VhyhLMNvGyt9QjntCru1z_gkr1qZR4y5W 293 Uec9WtxPqqC-dny-MZOINZd13LdStVY_g0KaAJET0etT4vYZJ6IfqdEXRSKKQKN 294 CJpencNhJH99NEumPwY0J8hYGC-KkGb6ZQ0yeQDIpcH2reMS9_DU0JaFtd5BpKm 295 pNDAvmekzWv65o6MCzLVN4Wlf4tZ6a7FnLxDg0jQBsPGh3ZKEeGmvxJKSvGK_Or 296 5-gXJdMyj1n0bWyex-ZTmtbR3OHKgAlFQUdLuB-47UFS0HtF0Lo1ENPZUoxwFcg 297 Uu2Yr30O8vhHLhkRAyAvrFPBHhSqcGr954FeMhMo18dKu3zdykyueIQpLIpU7qN 298 btXXSOu1c1rPqBMm3h77iLmNzSByFER32-W7hQwx9-Ikbwy52DaZACpXdyzZOQ2 299 PSYEJeuy8CyHap8_Dwucb3CQiqBi-iz25Mmwx8qBjWq3K31W4WeF0heC_rCe6LS 300 vOCuHJXpu8Wqa1LeyTbuHyQawH8Aev-MzVLXp0E-WtggfNi-mqcThs25993uveI 301 TpmK6lyQu6SX31t6MlQKI_29e46cYRMFhsEZSGM--acnZiryvi39IKsVNtOf33E 302 9zlKntRdmMoROenR-q5--9nObKaF81k3Xb-yWNTlQh1ot59rWAeqpPv0uA. 303 big8BFT-dXJqoKGScpLk0ssjuyWn7fxDvJc7AN7ONPw 305 5. Symmetric Key Example 307 NOTE: unless otherwise indicated, all line breaks are included for 308 readability. 310 The key holder begins with the [JWK] representation of the symmetric 311 key (here using a [AES] 128-bit key, formatted as per [JPSK]): 313 { 314 "kty":"oct", 315 "kid": "b8acba65-8af2-4e93-a8e0-d4abd7f25e52", 316 "k": "fKrBr19_ne9Cp3akXGpqgA" 317 } 319 The key holder uses the following [JWE] inputs: 321 JWE Header: 323 { 324 "alg":"RSA-OAEP", 325 "enc":"A128CBC+HS256", 326 "jwk":{ 327 "kty":"RSA", 328 "n":"ALekPD1kotXZCY_YUz_ITWBZb2nTOw35VvZlnqTiYSeusO58qCtYDz 329 ahTEkEcjtduRqfkxJKHYVq9Iro4x1cewXFdJZUuMOQAhoD63AHemXE 330 kdPiKqJvkBXDT_Eo4NPOjMKKkFPy2MsJQBmdtVknUvzxEchhYjZ490 331 EJTvGJ7OYwrSwkcCxy9D29XxL-OQLkSLlH1XD8kgVmJw8hsb42Bg0j 332 PgKlkvcyENmYpYE_hqlJoqYNFzgtAnNtK4C3tspix46R3IgilQG2Of 333 i99vpUnmTvjrOlNef2l65PRsPHD1Gl9fyPLCxrkolXbdwvxZ9j2d2f 334 Iu-OBTxRhnBtarNls_k", 335 "e":"AQAB" 336 } 337 } 339 Content Master Key (encoded as base64url per [RFC4648]): 341 ci5IlLIHnFLn-1lhL5CWOS3DdbXGU-BPuFCrLspXAkA 343 Initialization Vector (encoded as base64url per [RFC4648]): 345 _dYbckd_xuJUBUNsxkT9yw 346 The key holder performs steps 1 and 2 to generate the [JWE] outputs 347 (represented using the Compact Serialization): 349 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMrSFMyNTYiLCJqd2siOns 350 ia3R5IjoiUlNBIiwibiI6IkFMZWtQRDFrb3RYWkNZX1lVel9JVFdCWmIyblRPdz 351 M1VnZabG5xVGlZU2V1c081OHFDdFlEemFoVEVrRWNqdGR1UnFma3hKS0hZVnE5S 352 XJvNHgxY2V3WEZkSlpVdU1PUUFob0Q2M0FIZW1YRWtkUGlLcUp2a0JYRFRfRW80 353 TlBPak1LS2tGUHkyTXNKUUJtZHRWa25Vdnp4RWNoaFlqWjQ5MEVKVHZHSjdPWXd 354 yU3drY0N4eTlEMjlYeEwtT1FMa1NMbEgxWEQ4a2dWbUp3OGhzYjQyQmcwalBnS2 355 xrdmN5RU5tWXBZRV9ocWxKb3FZTkZ6Z3RBbk50SzRDM3RzcGl4NDZSM0lnaWxRR 356 zJPZmk5OXZwVW5tVHZqck9sTmVmMmw2NVBSc1BIRDFHbDlmeVBMQ3hya29sWGJk 357 d3Z4WjlqMmQyZkl1LU9CVHhSaG5CdGFyTmxzX2siLCJlIjoiQVFBQiJ9fQ. 358 UW26BTjbDGjgQ288JXJpGGpbZVV3WyZYJdm1Fvux8wM_t7bh6UbjbOdYXjL3rzD 359 phZteaD-DXiKrdGaVndTMLUmjg78H0R9K2WHxWNhTWiq8iMDGtw6BYnHW_r5DSf 360 vhojcDhCCBKWyO-QLXvTO1mfgo6UQwYY32Lvz-IrbxphrfBePsEXVYm75PLIIft 361 PnRwN3fWDMkKLCq2AesvWDuRWtKVjsh7uu_AX2ky6dvov2Lw_xMiDshsNz62RES 362 bNUW-ylMqNNn_VAYWKHK83k5CZppPlBb_8MDEUBPyGe_NDCa3118eo20tJGMn8v 363 XRg8k7D0nJ051hGlzAkMQ0S_x9g. 364 _dYbckd_xuJUBUNsxkT9yw. 365 QHkwptAlO0Gdo5BrbkaGPSek6wASr-twP8ZQ3YYHOkbRMedtsM0QwpvdnfUXoJL 366 7HZ0fbI-5YwO3PHvTOMXKx-K26cA-Hn9aseBvuICL2getFnrUcXs3vQI416PCw7 367 n39HtFLozCaBhJBaMv5x41CT6eaeRCMXE9Kbgz8lFicKNS9GYB7bUQfPXJl-qP7 368 05v-qkY4m2BAfofWtyGK-bnbs2ZKhKgaRTdRZlbnZTC19eSS8bPlalSNBrpr2eP 369 kDGDsYIKJvtbqD_xHeb7u5BT3ELmDl4CDjMruB3RiNwINcwNkCAhkg9tgV_vFCm 370 Qzsc9DH6dlnkYrbnyFrAD4Qe7xI1anDjLmRvU2cBB68-AtRd3PmpVzbr4t2eo33 371 GX9c_6fUILJS8WuExPs7KJkOuqDfKCPWDwRfX-yf8YUkrBZMj9aImyY2MyMJZFu 372 ITxseXbhkQFPJn-A4scSt1suWEXch5fKfl1KfxJlMio-Bm8kfUba4mgOKen7cJ0 373 whFSh7cupuSG0vVMLeBoBVGnndjARUxl5I57NZupH7xq3L8lDVHu_mQ_8Ae1j2h 374 QmPOA7_882j1ubpM9Kq-YmOPP4R8wk9SD0bl0k222mSMUMMEZoiSVk7OSHPHkXj 375 v-IkXkMmKT0lZiRohdKanb-Dfa1GWXeFTKFSKKJUQibLQ2zy6jlBptIEkxQNrJe 376 F-96Ie08r93r79ZRs3lNegzhI6ShMot1YBiG5C-WiOvPw6zysh_-AIGbuvZ9hBn 377 nuNfeGr2VPPcO5Z0FKGYGJ0DDnwlNHkdztEj_xLzSZjMxeO6o2hVJScLzzyG_Fy 378 T2v2kUHv_qeal18x-ICLR3yyF6JzoT0zKYPouBEIM5EZNAX9A3UjG0kNWW4Lou9 379 dlbLIZm-T7H6kj89RATMbDCwHa-nsF2kmnTRR6djt7lzDU1CHEEcM83ZWxi9qTR 380 cN_YrCokMkSjZYI87GqmnYHFsTktBBMNDX0u9SBdDZSwmz4EPsn7blYFt6Oiyd- 381 EBJlE_ocI4desERjIj0vKsgCoa9ea46S4m_gPa8xlCHK9wcsXU0ZhH8Lo_PyLm0 382 4CnjAbhKV0g8WvupjRQijkA6WoqYxQCP9EsDWH7kHJxDWV0uXXFoPZkcW5DBWrG 383 1NUC4TAjjI-9qhW7bpBZTLZHDJ99Awsh5lBqPYwUoPMS-lx-FPv9pAEih0rdHdH 384 __PelgmXKSwsoBSXzS_ErzePKwTfMAqedpe4WVykQ1rOTRn3uW01sv5gfRBRpo. 385 PnWwSPZ6TWOHKQwCIIt1HcCLhXof1j4frx2IcLXjIQ0 387 6. Using Password-Based Cryptography 389 There are often times when a key is exchanged through immediate human 390 interaction. To help facilitate such exchanges, a number of 391 password-based cryptography schemes utilizing [RFC2898] are defined 392 to supplement the key format and encryption algorithms from [JWA]. 394 6.1. PBKDF2 Key Type 396 The "PBKDF2" key type is used to contain the parameters necessary to 397 derive a cipher key from a password using the PBKDF2 algorithm from 398 [RFC2898]. The following parameters are defined: 400 6.1.1. 's' Parameter 402 The REQUIRED "s" parameter contains the PBKDF2 salt value (S), as a 403 base64url encoded string (per [RFC4648]). This value MUST NOT be the 404 empty string "". 406 The salt expands the possible keys that can be derived from a given 407 password. [RFC2898] originally recommended a minimum salt length of 408 8 octets (since there is no concern here of a derived key being re- 409 used for different purposes). The salt MUST be generated randomly; 410 see [RFC4086] for considerations on generating random values. 412 6.1.2. 'c' Parameter 414 The REQUIRED "c" parameter contains the PBKDF2 iteration count (c), 415 as an integer. This value MUST NOT be less than 1, as per [RFC2898]. 417 The iteration count adds computational expense, ideally compounded by 418 the possible range of keys introduced by the salt. [RFC2898] 419 originally recommended a minimum iteration count of 1000. 421 6.1.3. 'hint' Parameter 423 The OPTIONAL "hint" parameter contains a description clue to the 424 password, as a string. If present, this value SHOULD NOT be the 425 empty string "". 427 The hint is typically displayed to the user as a reminder or mnemonic 428 for the actual password used. This parameter MUST NOT contain the 429 actual password, and implementations MAY use various heuristic 430 algorithms to prohibit hints that are alternate forms of the actual 431 password. 433 6.2. PBES2 Key Encryption Algorithms 434 The "PBES2-HS256+A128KW" and "PBES2-HS512+A256KW" algorithms defined 435 below are used to encrypt a JWE Content Master Key using a user- 436 supplied password to derive the key encryption key. With these 437 algorithms, the derived key is used to encrypt the JWE Content Master 438 Key. These algorithms combine a key derivation function with an 439 encryption scheme to encrypt the JWE Content Master Key according to 440 PBES2 from section 6.2 of [RFC2898]. 442 6.2.1. PBES2-HS256+A128KW 444 The "PBES2-HS256+A128KW" algorithm uses "HMAC-SHA256" as the PRF and 445 "AES128-WRAP" as defined in [RFC3394] for the encryption scheme. The 446 salt (S) and iteration count (c) MUST be specified by the "s" and "c" 447 parameters (respectively) in the applicable "PBKDF2" JWK object. The 448 derived-key length (dkLen) is 16 octets. 450 6.2.2. PBES2-HS512+A256KW 452 The "PBES2-HS512+A256KW" algorithm uses "HMAC-SHA512" as the PRF "and 453 "AES256-WRAP" as defined in [RFC3394] for the encryption scheme. The 454 salt (S) and iteration count (c) MUST be specified by the "s" and "c" 455 parameters (respectively) in the applicable "PBKDF2" JWK object. The 456 derived-key length (dkLen) is 32 octets. 458 7. IANA Considerations 460 7.1. JSON Web Key Types Registration 462 This document registers the following to the JSON Web Key Types 463 registry: 465 o "kty" Paramater value: "PBKDF2" 467 o Implementation Requirements: OPTIONAL 469 o Change Controller: IETF 471 o Specification Document(s): Section 6.1 of [[ this document ]] 473 7.2. JSON Web Key Parameters Registration 475 This document registers the following to the JSON Web Key Parameters 476 registry: 478 o Parameter Name: "s" 480 o Change Controller: IETF 482 o Specification Document(s): Section 6.1.1 of [[ this document ]] 484 o Parameter Name: "c" 486 o Change Controller: IETF 488 o Specification Document(s): Section 6.1.2 of [[ this document ]] 490 o Parameter Name: "hint" 492 o Change Controller: IETF 494 o Specification Document(s): Section 6.1.3 of [[ this document ]] 496 7.3. JSON Web Encryption Algorithms 498 This document registers the following to the JSON Web Encryption 499 Algorithms registry: 501 o Algorithm Name: "PBES2-HS256+A128KW" 503 o Algorithm Usage Location(s): "alg" 505 o Implementation Requirements: OPTIONAL 507 o Change Controller: IETF 508 o Specification Document(s): Section 6.2.1 of [[ this document ]] 510 o Algorithm Name: "PBES2-HS512+A256KW" 512 o Algorithm Usage Location(s): "alg" 514 o Implementation Requirements: OPTIONAL 516 o Change Controller: IETF 518 o Specification Document(s): Section 6.2.2 of [[ this document ]] 520 8. Security Considerations 522 8.1. Re-using Keying Material 524 It is NOT RECOMMENDED to re-use the same keying material (Key 525 Encryption Key, Content Master Key, Initialization Vector, etc) to 526 protect multiple JWK objects, or to protect the same JWK object 527 multiple times. One suggestion for preventing re-use is to always 528 generate a new set keying material for each protection operation, 529 based on the considerations noted in this document as well as from 530 [RFC4086]. 532 8.2. Password Considerations 534 While convenient for end users, passwords have many drawbacks. To 535 help mitigate these limitations, this document applies principles 536 from [RFC2898] to derive cryptographic keys from user-supplied 537 passwords. 539 An ideal password is one that is as large (or larger) than the 540 derived key length but less than the PRF's block size. Passwords 541 larger than the PRF's block size are first hashed, which reduces an 542 attacker's effective search space to the length of the hash algorithm 543 (32 octects for HMAC-SHA-256; 64 octets for HMAC-SHA-512). For 544 "PBES2-HS256+A128KW", it is RECOMMENDED that the password be no 545 longer than 64 octets long; for "PBES2-HS512+A256KW", it is 546 RECOMMENDED that the password be no longer than 128 octets long. 548 9. Internationalization Considerations 549 Passwords obtained from users are likely to require preparation and 550 normalization to account for differences of octet sequences generated 551 by different input devices, locales, etc. It is RECOMMENDED for 552 applications to perform the steps outlined in [SASLPREP] to prepare a 553 password supplied directly by a user before performing key derivation 554 and encryption. 556 10. References 558 10.1. Normative References 560 [JWA] Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 561 json-web-algorithms-08 (work in progress), December 2012. 563 [JWE] Jones, M., Rescola, E., and J. Hildebrand, "JSON Web 564 Encryption (JWE)", draft-ietf-jose-json-web-encryption-08 565 (work in progress), December 2012. 567 [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 568 key-08 (work in progress), December 2012. 570 [JPSK] Jones, M., "JSON Private and Symmetric Key", draft-jones- 571 jose-json-private-and-symmetric-key-00 (work in progress), 572 December 2012. 574 [SASLPREP] 575 Saint-Andre, P., "Preparation and Comparison of 576 Internationalized Strings Representing Simple User Names 577 and Passwords", draft-melnikov-precis-saslprepbis-04 (work 578 in progress), September 2012. 580 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 581 Requirement Levels", BCP 14, RFC 2119, March 1997. 583 [RFC2898] Kaliski, B., "Password-Based Cryptography Specification", 584 RFC 2898, September 2000. 586 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 587 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 589 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 590 Requirements for Security", RFC 4086, June 2005. 592 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 593 Encodings", RFC 4648, October 2006. 595 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 596 4949, August 2007. 598 10.2. Informative References 600 [AES] National Institute of Standards and Technology (NIST), 601 "Advanced Encryption Standard (AES)", FIPS PUB 197, 602 November 2001. 604 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 605 Standards (PKCS) #1: RSA Cryptography Specifications 606 Version 2.1", RFC 2898, February 2003. 608 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 609 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 611 Appendix A. Acknowledgements 613 Appendix B. Document History 615 -01 Incorporated changes suggested by Jim Schaad: 617 * Expanded the acronym "JSON" on first use. 619 * Expanded the introduction to explain how this document's 620 protection of symmetric keys differs from [JWE]. 622 * Expanded the introduction to better explain why password-based 623 encryption algorithms are needed. 625 * Moved information on PBKDF2 salt from the security 626 considerations to the "s" JWK parameter definition. 628 * Moved information on PBKDF2 iteration count from security 629 considerations to the "c" JWK parameter definition. 631 * Added the "hint" JWK parameter. 633 * Explicitly noted what registries are updated by the IANA 634 considerations. 636 * Relaxed language around re-use of keying material. 638 * Removed section discussing protected key lifetimes. 640 * Improved recommendations around password lengths. 642 -00 Initial revision 644 Author's Address 646 Matthew Miller 647 Cisco Systems, Inc. 648 1899 Wynkoop Street, Suite 600 649 Denver, CO 80202 650 USA 652 Phone: +1-303-308-3204 653 Email: mamille2@cisco.com