idnits 2.17.1 draft-miller-jose-jwe-protected-jwk-02.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 (June 13, 2013) is 3971 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 June 13, 2013 5 Expires: December 15, 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-02 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 December 15, 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 . . . . . . . . . . . . . . . 5 58 4. Private Key Example . . . . . . . . . . . . . . . . . . . . . 5 59 5. Symmetric Key Example . . . . . . . . . . . . . . . . . . . . 8 60 6. Using Password-Based Cryptography . . . . . . . . . . . . . . 9 61 6.1. PBKDF2 Key Type . . . . . . . . . . . . . . . . . . . . . 9 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-HS256+A256KW . . . . . . . . . . . . . . . . . 11 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 69 7.1. JSON Web Key Types Registration . . . . . . . . . . . . . 11 70 7.2. JSON Web Key Parameters Registration . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . 14 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-HS256+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-HS256+A256KW"). 148 * The 'enc' property set to the intended content encryption 149 algorithm (e.g., "A256GCM" or "A256CBC+HS512"). 151 * The 'cty' property set to "application/jwk+json", indicating 152 the content is a JWK object. 154 * Keying material appropriate for the selected content 155 encryption algorithm (e.g., Content Encryption Key and 156 Initialization Vector). 158 * K' as the plaintext content to encrypt. 160 3. Serializes to the appropriate format for exchange, such as the 161 Compact Serialization documented in [JWE]. 163 3.1. Details for Private Keys 165 Private keys are typically protected using a symmetric key. This 166 symmetric key can be exchanged or determined in various ways, such as 167 deriving one from a user-supplied password; the algorithms 168 "PBES2-HS256+A128KW" and "PBES2-HS256+A256KW" (defined in 169 Section 6.2) enable this. 171 3.2. Details for Symmetric Keys 173 Symmetric keys are typically protected using public-private key 174 pairs. It is assumed the key holder has the appropriate public 175 key(s) for the key recipient(s). 177 The process defined herein expects JWK objects. While more compact 178 to simply encrypt the symmetric key directly with a public key, using 179 the complete JWE process on complete JWK objects allows additional 180 properties to be protected (e.g., expected lifetime, acceptable uses) 181 without exceeding the very restrictive plaintext length limits in 182 most public-private key operations (e.g., 234 octects when using the 183 "RSA-OAEP" algorithm with a 2048-bit key). 185 4. Private Key Example 187 NOTE: unless otherwise indicated, all line breaks are included for 188 readability. 190 The key holder begins with the [JWK] representation of the private 191 key (here using a [RFC3447] RSA private key, formatted per [JPSK]): 193 { 194 "kty":"RSA", 195 "kid":"juliet@capulet.lit", 196 "n":"ALekPD1kotXZCY_YUz_ITWBZb2nTOw35VvZlnqTiYSeusO58qCtYDz 197 ahTEkEcjtduRqfkxJKHYVq9Iro4x1cewXFdJZUuMOQAhoD63AHemXE 198 kdPiKqJvkBXDT_Eo4NPOjMKKkFPy2MsJQBmdtVknUvzxEchhYjZ490 199 EJTvGJ7OYwrSwkcCxy9D29XxL-OQLkSLlH1XD8kgVmJw8hsb42Bg0j 200 PgKlkvcyENmYpYE_hqlJoqYNFzgtAnNtK4C3tspix46R3IgilQG2Of 201 i99vpUnmTvjrOlNef2l65PRsPHD1Gl9fyPLCxrkolXbdwvxZ9j2d2f 202 Iu-OBTxRhnBtarNls_k", 203 "e":"AQAB", 204 "d":"GRtbIQmhOZtyszfgKdg4u_N-R_mZGU_9k7JQ_jn1DnfTuMdSNprTea 205 STyWfSNkuaAwnOEbIQVy1IQbWVV25NY3ybc_IhUJtfri7bAXYEReWa 206 Cl3hdlPKXy9UvqPYGR0kIXTQRqns-dVJ7jahlI7LyckrpTmrM8dWBo 207 4_PMaenNnPiQgO0xnuToxutRZJfJvG4Ox4ka3GORQd9CsCZ2vsUDms 208 XOfUENOyMqADC6p1M3h33tsurY15k9qMSpG9OX_IJAXmxzAh_tWiZO 209 wk2K4yxH9tS3Lq1yX8C1EWmeRDkK2ahecG85-oLKQt5VEpWHKmjOi_ 210 gJSdSgqcN96X52esAQ", 211 "p":"ANq50jleISkjfLEuAoHEBxW7NPF26BQ6irpt7HOIdxkca05kHZdWSv 212 bsPjyB30D9BZMV1a8flhPmRG66orx_9ogi1Eu8AJel7wEbdSpCGlMT 213 z0mAfcpN9bNEPFCvehN_zqwAwGLQCbPjNycQi3zYKoeehw5xE00IR9 214 6wk-U98icL", 215 "q":"ANbv0YhQz-ywWIdzeBly0_TqUimD9LkGcommcAbTggTSYEMWo9dEVo 216 7GbtHOiHnYrOEuwf3KEigdCo_T2j2gc4PiMkkb73ELj2pkLuuq4jIY 217 1bRuk5VfAiwmCq2Jeds4qitBP8ptkJ5MLFF-3mEwey2wB0SvRqqHAx 218 OQdH_NPCOL", 220 "dp":"KkMTWqBUefVwZ2_Dbj1pPQqyHSHjj90L5x_MOzqYAJMcLMZtbUtwK 221 qvVDq3tbEo3ZIcohbDtt6SbfmWzggabpQxNxuBpoOOf_a_HgMXK_l 222 hqigI4y_kqS1wY52IwjUn5rgRrJ-yYo1h41KR-vz2pYhEAeYrhttW 223 txVqLCRViD6c", 224 "dq":"AvfS0-gRxvn0bwJoMSnFxYcK1WnuEjQFluMGfwGitQBWtfZ1Er7t1 225 xDkbN9GQTB9yqpDoYaN06H7CFtrkxhJIBQaj6nkF5KKS3TQtQ5qCz 226 kOkmxIe3KRbBymXxkb5qwUpX5ELD5xFc6FeiafWYY63TmmEAu_lRF 227 COJ3xDea-ots", 228 "qi":"AJUkIvsPQqclEXjBKz9UbAS5O8DbTr7OREKT6prjL6luezQVHM0nB 229 KD8JlKqmm7vVdPj8uHUOe_22qaCkbtUfdG77hZ1Ot0h1hBYJWULyQ 230 zHgL5o-LJvhadKGLv53qLYENIc2yOYK8u2o3WMvftpTcf--mgWaDl 231 LvRwiflLH0jiP" 232 } 234 The key holder uses the following [JWE] inputs: 236 JWE Header: 238 { 239 "alg":"PBES2-HS256+A128KW", 240 "jwk":{ 241 kty:"PBKDF2", 242 kid:"27a4c46f-6d36-4a8c-814c-c954165f6dc9", 243 s:"2WCTcJZ1Rvd_CJuJripQ1w", 244 c:4096 245 }, 246 "enc":"A128CBC+HS256", 247 "cty":"application/jwk+json" 248 } 250 Password: 252 Thus from my lips, by yours, my sin is purged. 254 Content Master Key (encoded as base64url per [RFC4648]): 256 D0GoLoMS35BtD4_rSF56VGg_Syj0VG6-lb4xrpQIQmU 258 Initialization Vector (encoded as base64url per [RFC4648]): 260 XYqmb7uopcN1pCNRGJ5hKw 262 The key holder performs steps 1 and 2 to generate the [JWE] outputs 263 (represented using the Compact Serialization): 265 eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJqd2siOnsia3R5IjoiUEJLREY 266 yIiwia2lkIjoiMjdhNGM0NmYtNmQzNi00YThjLTgxNGMtYzk1NDE2NWY2ZGM5Ii 267 wicyI6IjJXQ1RjSloxUnZkX0NKdUpyaXBRMXciLCJjIjo0MDk2fSwiZW5jIjoiQ 268 TEyOENCQytIUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2p3aytqc29uIn0. 269 b735tKJtEzS9VNxgEO6hT6WYZ9-zOpEIAFk3k0jIiCju7bPLb7FQKw. 270 XYqmb7uopcN1pCNRGJ5hKw. 271 dmqTOCIGwHdNOixUkmQ9H0g-JWU74ayVUeuSnsRnRdBPy0wRdBkZBsiQC6-Cl8q 272 QSjmC376EJvffG2xUBqjt4omuzMX9KY3Kn64GAHr528N5Bv5487fu-iHBy7uVvT 273 F0zgBaSV4Rt-44FWoMoE7H4vcQn_Lf7mv0dviciDM3Spp_IZrb5ufzDhrQlzArM 274 xOh7rBTgwoeOaFywXuFrxqr9GbV4Qzn7Vy78T8UUd5alr6GlfF-_O0hW37Gwju_ 275 AT4bN6fs42NKYvqsAq90ZDujQjRlj3BJc1wAJbw9Ev7oxEvPvUSXgfDk6rvnB-n 276 uKD-0KU-M9td2QM8De0AXYRf2rTMiIIuNsRWeJxgeL97Unz9yNywAfcf4SX1P38 277 pgCZAbVwLRdbZwcOjK0_R3BQAtyysX-f4rtDCH9BKKFLB_YLcDkQn547QS2RMWf 278 GrVPT5CKp5Z5H8RSC47HEnmwppAKtGfUPb4wSs6zT8yV60RxOYD8Ze5DK9UJrPN 279 MFfN33_JlpeNKF7w9ulN57-ooYbXkX0WI4JjdF9G9NdJbh8F1NRqLc4KyQBW2bJ 280 S_SCZdeVZ4O_spCKfwKpIDFoXE9Nm-3o8mxhfdUbq_Ck8WqiJ6CKm-XjN1b7Z0f 281 lkGz6YkXdbd3-F62bB09VzsYERnSBIdsWtwaKMvSyqi8MkhMyhZe2-Iz481r4gi 282 v8ESWXAMeVihmOU9HLtgO4MMY3kSbB1qLzhbH7-CRh4h7k83tCmHPvNIQc-JYLm 283 80aHs_W_91SPRwnUZJHKasybepqika_CNwkmYsRkiV0GOpzrl2T28Nor74xPrBb 284 tk5LJMT_ZKErrCQoIvcgXrWcaTknCpe2sDYkOMuvNlsT8g6r45HuPJ6u561-sw7 285 wvam2P1AEg4wuQBAt7Y1_VDy6N-q71ZejayANTCtMGeJiWea79X6xdUJQ_py5xR 286 SuSjSwjsXCvisWyiKLAKXoVO9gQGEZLZMhYqRSGwip-KSkYpFYPd5ofn21MHXKG 287 D6r0gapo7lMysKlCpfd5v0_sB0JJYKsm12F49cvtK_CEtMYQw9n5R2wo8_2m5og 288 HGG3hMajGmem3anRAoSfifBBzx4kP_OOSqo_FoDbRzGluImVwcGL_pzCRRVNwAx 289 e5Bx8Al2xGLYncgs-QG7MRKu6LRB5pUq_ZbarL8JJengaa6AbxWsIMkTPEqilyi 290 SPpl7zmOFrUtuu-UUnNwhr6WEdLJm7o0iUoXr-Eyi8rfnZgdSvJOdMj-pGKQrWl 291 xyAo-Td8IqU-3DHk-otvjCd_i9SW0zRoL4GmqMkiJkIzZ7mjLdFLIFnX85sx4Qt 292 yYhMzEIfpgqnv66RnKVLyQ-sIap-9XO_mvSxsLL0yr8a4c_jufv0aFAbbLa_bo0 293 Mz_U309z0PmMp7BMh7CuwbiLhaoM6ZoafsxxVcOTHMbmEpybvsDOf8HPQ_k2kN2 294 qrVUfvYW5Be9ViOBNxKZWSiDDY0YWs5MhMZUvqnfq8amtAQNYTrpu5w2LfJIWhA 295 KkqzYAkzH7Jm7NFnOlcSrLPzFndjVZgIysYnBqkziTqtDoSNHCFY2TaJyZ3cT-o 296 WZQkVn07E8zuzMd6SGqPRAzY51CKbXdEfRaNgvaSb-V9TZYyhCmSHCGbwo0iErG 297 TfGiHtrfo4Jf6GD8-CcdmggWN-824rGOtp3Bgl8VAi_jmKkzF5s_sIEwhe7oa1H 298 S6PMYPkp9llZAiwmFCKHdQbfOdKXbD8FI7p7kUX8llOFLk3w12R2ffVR-gOm7qs 299 9MJjmi14nXmp13mV9YP_CgkNNss45B1DdcNMhtippHJ07CWIvKm1pkQOrsXG45C 300 4bNJ6YCn63X9ctdzhnFGmCJxCji3TasWWbnI4eA6XthWkJC5e5Nbz_2K-99PC9K 301 zwmauA98sqU1yKZFugSYOB6NRwN_y_GB1LEXDSE_FPRSEPNZNJyEMvKo5CeAtEj 302 7YPvFR6-yzWDTG0Uq1PafxITByg6UXHl9xBRborklCdfL3gUj3EoXHkvEsXdg22 303 jkpGZUmhWWlNvHeM5y0FUHZTIgyyJqHx_Y8v7yaZ881xwFaYAW52aSnL_8h68U1 304 8Sv7Q66FKi1gtOYU41FRW6i7oAC9xPYr1Jt5A-am4IwPPR-CPL071mGqOPrDd7l 305 gSCumoFESqi24d0IQuzPdEh643DHbWbeAQ7YB-LpZR_hTEC4IndRugQA. 306 3c4RF_muOYT02o5Klxv-IQ 308 5. Symmetric Key Example 310 NOTE: unless otherwise indicated, all line breaks are included for 311 readability. 313 The key holder begins with the [JWK] representation of the symmetric 314 key (here using a [AES] 128-bit key, formatted as per [JPSK]): 316 { 317 "kty":"oct", 318 "kid": "b8acba65-8af2-4e93-a8e0-d4abd7f25e52", 319 "k": "fKrBr19_ne9Cp3akXGpqgA" 320 } 322 The key holder uses the following [JWE] inputs: 324 JWE Header: 326 { 327 "alg":"RSA-OAEP", 328 "jwk":{ 329 "kty":"RSA", 330 "kid":"juliet@capulet.lit", 331 "n":"ALekPD1kotXZCY_YUz_ITWBZb2nTOw35VvZlnqTiYSeusO58qCtYDz 332 ahTEkEcjtduRqfkxJKHYVq9Iro4x1cewXFdJZUuMOQAhoD63AHemXE 333 kdPiKqJvkBXDT_Eo4NPOjMKKkFPy2MsJQBmdtVknUvzxEchhYjZ490 334 EJTvGJ7OYwrSwkcCxy9D29XxL-OQLkSLlH1XD8kgVmJw8hsb42Bg0j 335 PgKlkvcyENmYpYE_hqlJoqYNFzgtAnNtK4C3tspix46R3IgilQG2Of 336 i99vpUnmTvjrOlNef2l65PRsPHD1Gl9fyPLCxrkolXbdwvxZ9j2d2f 337 Iu-OBTxRhnBtarNls_k", 338 "e":"AQAB" 339 }, 340 "enc":"A128CBC+HS256", 341 "cty":"application/jwk+json" 342 } 344 Content Master Key (encoded as base64url per [RFC4648]): 346 QkWU4j0bOc_meVgxNYoad74fQAosvz-4rnKqAhHEV-c 347 Initialization Vector (encoded as base64url per [RFC4648]): 349 VMmZ6nLXHkcOUmBTlZaSsQ 351 The key holder performs steps 1 and 2 to generate the [JWE] outputs 352 (represented using the Compact Serialization): 354 eyJhbGciOiJSU0EtT0FFUCIsImp3ayI6eyJrdHkiOiJSU0EiLCJraWQiOiJqdWx 355 pZXRAY2FwdWxldC5saXQiLCJuIjoiQUxla1BEMWtvdFhaQ1lfWVV6X0lUV0JaYj 356 JuVE93MzVWdlpsbnFUaVlTZXVzTzU4cUN0WUR6YWhURWtFY2p0ZHVScWZreEpLS 357 FlWcTlJcm80eDFjZXdYRmRKWlV1TU9RQWhvRDYzQUhlbVhFa2RQaUtxSnZrQlhE 358 VF9FbzROUE9qTUtLa0ZQeTJNc0pRQm1kdFZrblV2enhFY2hoWWpaNDkwRUpUdkd 359 KN09Zd3JTd2tjQ3h5OUQyOVh4TC1PUUxrU0xsSDFYRDhrZ1ZtSnc4aHNiNDJCZz 360 BqUGdLbGt2Y3lFTm1ZcFlFX2hxbEpvcVlORnpndEFuTnRLNEMzdHNwaXg0NlIzS 361 WdpbFFHMk9maTk5dnBVbm1UdmpyT2xOZWYybDY1UFJzUEhEMUdsOWZ5UExDeHJr 362 b2xYYmR3dnhaOWoyZDJmSXUtT0JUeFJobkJ0YXJObHNfayIsImUiOiJBUUFCIn0 363 sImVuYyI6IkExMjhDQkMrSFMyNTYiLCJjdHkiOiJhcHBsaWNhdGlvbi9qd2sran 364 NvbiJ9. 365 ReivAR0RfDi-03K9Db3gC3MSJQJvCe378Anzg0vKj45DJGwfEaPFym_tt6HkbgB 366 vgIBaFX_WZE1E3xXMngH_oBz-zUJzB9Gc_hAeov6uLz0pp4knb20pOZCls0Lcjs 367 xqgAF_RwB7l_mcPP3HVAwfoEz-_Um7FOztq5Wjse1fBmEX0fwqJT3VC7HVKzJpo 368 pJgrrsYFyGPlraNBJJ3yvmRMYLOzTLNoNDYqQz89yZ_dYDcN7zjrke8T3NnSwx2 369 9xF3kwiD_AO2SUsA23Zw3xEFQoiskK0w54KKa75yFlSbnObFLOOvqncxJy0bbha 370 GqW6I-jeoXVaG7aia6hGU9aMX2g. 371 VMmZ6nLXHkcOUmBTlZaSsQ. 372 N3j7CW5JfJj7C6uL9PCVIm4U_NWRtAVjrnqnPRXIwhepaGoL-TQHeMyHveg5Uyg 373 rPP_PBwk-VkwAyFBJClPNJ6cGSS_VN5a9Z60rxlXEQi8nBhCgQzA3wU1XMTHCs- 374 QF. 375 trBdLTmkE2mIPdA7eefNyQ 377 6. Using Password-Based Cryptography 379 There are often times when a key is exchanged through immediate human 380 interaction. To help facilitate such exchanges, a number of 381 password-based cryptography schemes utilizing [RFC2898] are defined 382 to supplement the key format and encryption algorithms from [JWA]. 384 6.1. PBKDF2 Key Type 386 The "PBKDF2" key type is used to contain the parameters necessary to 387 derive a cipher key from a password using the PBKDF2 algorithm from 388 [RFC2898]. The following parameters are defined: 390 6.1.1. 's' Parameter 392 The REQUIRED "s" parameter contains the PBKDF2 salt value (S), as a 393 base64url encoded string (per [RFC4648]). This value MUST NOT be the 394 empty string "". 396 The salt expands the possible keys that can be derived from a given 397 password. [RFC2898] originally recommended a minimum salt length of 398 8 octets (since there is no concern here of a derived key being re- 399 used for different purposes). The salt MUST be generated randomly; 400 see [RFC4086] for considerations on generating random values. 402 6.1.2. 'c' Parameter 404 The REQUIRED "c" parameter contains the PBKDF2 iteration count (c), 405 as an integer. This value MUST NOT be less than 1, as per [RFC2898]. 407 The iteration count adds computational expense, ideally compounded by 408 the possible range of keys introduced by the salt. [RFC2898] 409 originally recommended a minimum iteration count of 1000. 411 6.1.3. 'hint' Parameter 413 The OPTIONAL "hint" parameter contains a description clue to the 414 password, as a string. If present, this value SHOULD NOT be the 415 empty string "". 417 The hint is typically displayed to the user as a reminder or mnemonic 418 for the actual password used. This parameter MUST NOT contain the 419 actual password, and implementations MAY use various heuristic 420 algorithms to prohibit hints that are alternate forms of the actual 421 password. 423 6.2. PBES2 Key Encryption Algorithms 425 The "PBES2-HS256+A128KW" and "PBES2-HS256+A256KW" algorithms defined 426 below are used to encrypt a JWE Content Master Key using a user- 427 supplied password to derive the key encryption key. With these 428 algorithms, the derived key is used to encrypt the JWE Content Master 429 Key. These algorithms combine a key derivation function with an 430 encryption scheme to encrypt the JWE Content Master Key according to 431 PBES2 from section 6.2 of [RFC2898]. 433 6.2.1. PBES2-HS256+A128KW 435 The "PBES2-HS256+A128KW" algorithm uses "HMAC-SHA256" as the PRF and 436 "AES128-WRAP" as defined in [RFC3394] for the encryption scheme. The 437 salt (S) and iteration count (c) MUST be specified by the "s" and "c" 438 parameters (respectively) in the applicable "PBKDF2" JWK object. The 439 derived-key length (dkLen) is 16 octets. 441 6.2.2. PBES2-HS256+A256KW 443 The "PBES2-HS256+A256KW" algorithm uses "HMAC-SHA256" as the PRF "and 444 "AES256-WRAP" as defined in [RFC3394] for the encryption scheme. The 445 salt (S) and iteration count (c) MUST be specified by the "s" and "c" 446 parameters (respectively) in the applicable "PBKDF2" JWK object. The 447 derived-key length (dkLen) is 32 octets. 449 7. IANA Considerations 451 7.1. JSON Web Key Types Registration 453 This document registers the following to the JSON Web Key Types 454 registry: 456 o "kty" Paramater value: "PBKDF2" 458 o Implementation Requirements: OPTIONAL 460 o Change Controller: IETF 462 o Specification Document(s): Section 6.1 of [[ this document ]] 464 7.2. JSON Web Key Parameters Registration 466 This document registers the following to the JSON Web Key Parameters 467 registry: 469 o Parameter Name: "s" 471 o Change Controller: IETF 473 o Specification Document(s): Section 6.1.1 of [[ this document ]] 474 o Parameter Name: "c" 476 o Change Controller: IETF 478 o Specification Document(s): Section 6.1.2 of [[ this document ]] 480 o Parameter Name: "hint" 482 o Change Controller: IETF 484 o Specification Document(s): Section 6.1.3 of [[ this document ]] 486 7.3. JSON Web Encryption Algorithms 488 This document registers the following to the JSON Web Encryption 489 Algorithms registry: 491 o Algorithm Name: "PBES2-HS256+A128KW" 493 o Algorithm Usage Location(s): "alg" 495 o Implementation Requirements: OPTIONAL 497 o Change Controller: IETF 499 o Specification Document(s): Section 6.2.1 of [[ this document ]] 501 o Algorithm Name: "PBES2-HS256+A256KW" 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.2 of [[ this document ]] 510 8. Security Considerations 512 8.1. Re-using Keying Material 514 It is NOT RECOMMENDED to re-use the same keying material (Key 515 Encryption Key, Content Master Key, Initialization Vector, etc) to 516 protect multiple JWK objects, or to protect the same JWK object 517 multiple times. One suggestion for preventing re-use is to always 518 generate a new set keying material for each protection operation, 519 based on the considerations noted in this document as well as from 520 [RFC4086]. 522 8.2. Password Considerations 524 While convenient for end users, passwords are vulnerable to a number 525 of attacks. To help mitigate some of these limitations, this 526 document applies principles from [RFC2898] to derive cryptographic 527 keys from user-supplied passwords. 529 However, the strength of the password still has a significant impact. 530 A high-entry password has greater resistance to dictionary attacks. 531 [NIST-800-63-1] contains guidelines for estimating password entropy, 532 which can help applications and users generate stronger passwords. 534 An ideal password is one that is as large (or larger) than the 535 derived key length but less than the PRF's block size. Passwords 536 larger than the PRF's block size are first hashed, which reduces an 537 attacker's effective search space to the length of the hash algorithm 538 (32 octects for HMAC-SHA-256). It is RECOMMENDED that the password 539 be no longer than 64 octets long; for "PBES2-HS256+A256KW". 541 Still, care needs to be taken in where and how password-based 542 encryption is used. Such algorithms MUST NOT be used where the 543 attacker can make an indefinite number of attempts to circumvent the 544 protection. 546 9. Internationalization Considerations 548 Passwords obtained from users are likely to require preparation and 549 normalization to account for differences of octet sequences generated 550 by different input devices, locales, etc. It is RECOMMENDED for 551 applications to perform the steps outlined in [SASLPREP] to prepare a 552 password supplied directly by a user before performing key derivation 553 and encryption. 555 10. References 557 10.1. Normative References 559 [JWA] Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 560 json-web-algorithms-08 (work in progress), December 2012. 562 [JWE] Jones, M., Rescola, E., and J. Hildebrand, "JSON Web 563 Encryption (JWE)", draft-ietf-jose-json-web-encryption-08 564 (work in progress), December 2012. 566 [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 567 key-08 (work in progress), December 2012. 569 [JPSK] Jones, M., "JSON Private and Symmetric Key", draft-jones- 570 jose-json-private-and-symmetric-key-00 (work in progress), 571 December 2012. 573 [SASLPREP] 574 Saint-Andre, P., "Preparation and Comparison of 575 Internationalized Strings Representing Simple User Names 576 and Passwords", draft-melnikov-precis-saslprepbis-04 (work 577 in progress), September 2012. 579 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 580 Requirement Levels", BCP 14, RFC 2119, March 1997. 582 [RFC2898] Kaliski, B., "Password-Based Cryptography Specification", 583 RFC 2898, September 2000. 585 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 586 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 588 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 589 Requirements for Security", RFC 4086, June 2005. 591 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 592 Encodings", RFC 4648, October 2006. 594 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 595 4949, August 2007. 597 10.2. Informative References 599 [AES] National Institute of Standards and Technology (NIST), 600 "Advanced Encryption Standard (AES)", FIPS PUB 197, 601 November 2001. 603 [NIST-800-63-1] 604 National Institute of Standards and Technology (NIST), 605 "Electronic Authentication Guideline", NIST 800-63-1, 606 December 2011. 608 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 609 Standards (PKCS) #1: RSA Cryptography Specifications 610 Version 2.1", RFC 2898, February 2003. 612 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 613 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 615 Appendix A. Acknowledgements 617 Appendix B. Document History 619 -02 621 * Incorporated changes suggested at the JOSE interim meeting on 622 2012-04-28: 624 + Replaced JWE key encryption algorithm "PBES2-HS512+A256KW" 625 with "PBES2-HS256+A256KW". 627 + Added considerations for password-based encryption 628 algorithms around dictionary and brute force attacks. 630 * Updated to latest versions of JOSE dependencies. 632 -01 Incorporated changes suggested by Jim Schaad: 634 * Expanded the acronym "JSON" on first use. 636 * Expanded the introduction to explain how this document's 637 protection of symmetric keys differs from [JWE]. 639 * Expanded the introduction to better explain why password-based 640 encryption algorithms are needed. 642 * Moved information on PBKDF2 salt from the security 643 considerations to the "s" JWK parameter definition. 645 * Moved information on PBKDF2 iteration count from security 646 considerations to the "c" JWK parameter definition. 648 * Added the "hint" JWK parameter. 650 * Explicitly noted what registries are updated by the IANA 651 considerations. 653 * Relaxed language around re-use of keying material. 655 * Removed section discussing protected key lifetimes. 657 * Improved recommendations around password lengths. 659 -00 Initial revision 661 Author's Address 663 Matthew Miller 664 Cisco Systems, Inc. 665 1899 Wynkoop Street, Suite 600 666 Denver, CO 80202 667 USA 669 Phone: +1-303-308-3204 670 Email: mamille2@cisco.com