1
2 PKCS #11 Cryptographic Token Interface
3 Current Mechanisms Specification Version
4 3.0
5 Working Draft 110 Rev. 2
6 728 May 2019
7 Technical Committee: 8 OASIS PKCS 11 TC 9 Chairs: 10 Robert Relyea ([email protected]), Red Hat 11 Tony Cox ([email protected]), Cryptsoft 12 Editor: 13 Chris Zimman ([email protected]), Individual 14 Dieter Bong ([email protected]), Utimaco 15 Additional artifacts: 16 This prose specification is one component of a Work Product that also includes the following 17 normative computer language definition files for PKCS #11 v3.0 rev01 18 include/pkcs11-v3.0/pkcs11.h 19 include/pkcs11-v3.0/pkcs11t.h
20 include/pkcs11-v3.0/pkcs11f.hThis prose specification is one component of a Work Product that Formatted: List Paragraph, Bulleted + Level: 1 + Aligned at: 21 also includes these computer language files: 0.63 cm + Indent at: 1.27 cm
22 pkcs11-curr-v30.h Formatted: List Paragraph, No bullets or numbering 23 Related work: 24 This specification replaces or supersedes: 25 PKCS #11 Cryptographic Token Interface Current Mechanisms Specification Version 2.40 26 Plus Errata 01. Edited by Susan Gleeson, Chris Zimman, Robert Griffin, Tim Hudson. OASIS 27 Standard. http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/errata01/pkcs11-base-v2.40- 28 errata01-complete.html . 29 This specification is related to: 30 PKCS #11 Cryptographic Token Interface Base Specification Version 3.0 31
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 1 of 278 41 PKCS #11 Cryptographic Token Interface Usage Guide Version 3.0. Edited by John 42 Leiseboer and Robert Griffin. Latest version. http://docs.oasis-open.org/pkcs11/pkcs11- 43 ug/v2.41/pkcs11-ug-v2.41.html. 44 PKCS #11 Cryptographic Token Interface Profiles Version 3.0. Edited by Tim Hudson. Latest 45 version. http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.41/pkcs11-profiles-v2.41.html. 46 Abstract: 47 This document defines mechanisms that are anticipated for use with the current version of PKCS 48 #11. 49 Status: 50 This Working Draft (WD) has been produced by one or more TC Members; it has not yet been 51 voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a 52 Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote 53 to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re- 54 approve it any number of times as a Committee Draft. 55 URI patterns: 56 Initial publication URI: 57 http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.41/csd01/pkcs11-curr-v2.41-csd01.doc 58 Permanent “Latest version” URI: 59 http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.41/pkcs11-curr-v2.41.doc 60 (Managed by OASIS TC Administration; please don’t modify.) 61 62 63 Copyright © OASIS Open 2019. All Rights Reserved. 64 All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual 65 Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website. 66 This document and translations of it may be copied and furnished to others, and derivative works that 67 comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, 68 and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice 69 and this section are included on all such copies and derivative works. However, this document itself may 70 not be modified in any way, including by removing the copyright notice or references to OASIS, except as 71 needed for the purpose of developing any document or deliverable produced by an OASIS Technical 72 Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must 73 be followed) or as required to translate it into languages other than English. 74 The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors 75 or assigns. 76 This document and the information contained herein is provided on an "AS IS" basis and OASIS 77 DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY 78 WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY 79 OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 80 PARTICULAR PURPOSE. 81
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 2 of 278 82 Table of Contents
83 1 Introduction ...... 14 84 1.1 Terminology ...... 14 85 1.2 Definitions ...... 14 86 1.3 Normative References ...... 15 87 1.4 Non-Normative References ...... 17 88 2 Mechanisms ...... 20 89 2.1 RSA ...... 20 90 2.1.1 Definitions ...... 21 91 2.1.2 RSA public key objects ...... 22 92 2.1.3 RSA private key objects ...... 23 93 2.1.4 PKCS #1 RSA key pair generation ...... 24 94 2.1.5 X9.31 RSA key pair generation ...... 25 95 2.1.6 PKCS #1 v1.5 RSA ...... 25 96 2.1.7 PKCS #1 RSA OAEP mechanism parameters ...... 26 97 2.1.8 PKCS #1 RSA OAEP ...... 28 98 2.1.9 PKCS #1 RSA PSS mechanism parameters ...... 28 99 2.1.10 PKCS #1 RSA PSS ...... 29 100 2.1.11 ISO/IEC 9796 RSA ...... 29 101 2.1.12 X.509 (raw) RSA...... 30 102 2.1.13 ANSI X9.31 RSA ...... 31 103 2.1.14 PKCS #1 v1.5 RSA signature with MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512, RIPE- 104 MD 128 or RIPE-MD 160 ...... 32 105 2.1.15 PKCS #1 v1.5 RSA signature with SHA-224 ...... 32 106 2.1.16 PKCS #1 RSA PSS signature with SHA-224 ...... 32 107 2.1.17 PKCS #1 RSA PSS signature with SHA-1, SHA-256, SHA-384 or SHA-512 ...... 32 108 2.1.18 PKCS #1 v1.5 RSA signature with SHA3 ...... 33 109 2.1.19 PKCS #1 RSA PSS signature with SHA3 ...... 33 110 2.1.20 ANSI X9.31 RSA signature with SHA-1 ...... 33 111 2.1.21 TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA ...... 34 112 2.1.22 TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP ...... 34 113 2.1.23 RSA AES KEY WRAP ...... 35 114 2.1.24 RSA AES KEY WRAP mechanism parameters ...... 36 115 2.1.25 FIPS 186-4 ...... 36 116 2.2 DSA ...... 36 117 2.2.1 Definitions ...... 37 118 2.2.2 DSA public key objects ...... 38 119 2.2.3 DSA Key Restrictions ...... 39 120 2.2.4 DSA private key objects ...... 39 121 2.2.5 DSA domain parameter objects ...... 40 122 2.2.6 DSA key pair generation ...... 41 123 2.2.7 DSA domain parameter generation ...... 41 124 2.2.8 DSA probabilistic domain parameter generation...... 41 125 2.2.9 DSA Shawe-Taylor domain parameter generation ...... 42
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 3 of 278 126 2.2.10 DSA base domain parameter generation ...... 42 127 2.2.11 DSA without hashing ...... 42 128 2.2.12 DSA with SHA-1 ...... 43 129 2.2.13 FIPS 186-4 ...... 43 130 2.2.14 DSA with SHA-224 ...... 43 131 2.2.15 DSA with SHA-256 ...... 44 132 2.2.16 DSA with SHA-384 ...... 44 133 2.2.17 DSA with SHA-512 ...... 45 134 2.2.18 DSA with SHA3-224 ...... 45 135 2.2.19 DSA with SHA3-256 ...... 46 136 2.2.20 DSA with SHA3-384 ...... 46 137 2.2.21 DSA with SHA3-512 ...... 46 138 2.3 Elliptic Curve ...... 47 139 2.3.1 EC Signatures ...... 49 140 2.3.2 Definitions ...... 49 141 2.3.3 ECDSA public key objects ...... 50 142 2.3.4 Elliptic curve private key objects ...... 51 143 2.3.5 Edwards Elliptic curve public key objects ...... 52 144 2.3.6 Edwards Elliptic curve private key objects ...... 53 145 2.3.7 Montgomery Elliptic curve public key objects ...... 54 146 2.3.8 Montgomery Elliptic curve private key objects ...... 55 147 2.3.9 Elliptic curve key pair generation...... 56 148 2.3.10 Edwards Elliptic curve key pair generation ...... 57 149 2.3.11 Montgomery Elliptic curve key pair generation ...... 57 150 2.3.12 ECDSA without hashing ...... 58 151 2.3.13 ECDSA with hashing ...... 58 152 2.3.14 EdDSA ...... 59 153 2.3.15 XEdDSA ...... 59 154 2.3.16 EC mechanism parameters ...... 60 155 2.3.17 Elliptic curve Diffie-Hellman key derivation ...... 65 156 2.3.18 Elliptic curve Diffie-Hellman with cofactor key derivation ...... 65 157 2.3.19 Elliptic curve Menezes-Qu-Vanstone key derivation ...... 66 158 2.3.20 ECDH AES KEY WRAP...... 67 159 2.3.21 ECDH AES KEY WRAP mechanism parameters ...... 68 160 2.3.22 FIPS 186-4 ...... 69 161 2.4 Diffie-Hellman ...... 69 162 2.4.1 Definitions ...... 69 163 2.4.2 Diffie-Hellman public key objects ...... 70 164 2.4.3 X9.42 Diffie-Hellman public key objects ...... 70 165 2.4.4 Diffie-Hellman private key objects ...... 71 166 2.4.5 X9.42 Diffie-Hellman private key objects ...... 72 167 2.4.6 Diffie-Hellman domain parameter objects ...... 73 168 2.4.7 X9.42 Diffie-Hellman domain parameters objects ...... 73 169 2.4.8 PKCS #3 Diffie-Hellman key pair generation ...... 74 170 2.4.9 PKCS #3 Diffie-Hellman domain parameter generation ...... 75
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 4 of 278 171 2.4.10 PKCS #3 Diffie-Hellman key derivation ...... 75 172 2.4.11 X9.42 Diffie-Hellman mechanism parameters ...... 76 173 2.4.12 X9.42 Diffie-Hellman key pair generation ...... 79 174 2.4.13 X9.42 Diffie-Hellman domain parameter generation ...... 79 175 2.4.14 X9.42 Diffie-Hellman key derivation ...... 79 176 2.4.15 X9.42 Diffie-Hellman hybrid key derivation ...... 80 177 2.4.16 X9.42 Diffie-Hellman Menezes-Qu-Vanstone key derivation ...... 80 178 2.5 Extended Triple Diffie-Hellman (x3dh) ...... 81 179 2.5.1 Definitions ...... 81 180 2.5.2 Extended Triple Diffie-Hellman key objects ...... 81 181 2.5.3 Initiating an Extended Triple Diffie-Hellman key exchange ...... 82 182 2.5.4 Responding to an Extended Triple Diffie-Hellman key exchange ...... 82 183 2.5.5 Extended Triple Diffie-Hellman parameters ...... 83 184 2.6 Double Ratchet ...... 84 185 2.6.1 Definitions ...... 84 186 2.6.2 Double Ratchet secret key objects ...... 84 187 2.6.3 Double Ratchet key derivation ...... 85 188 2.6.4 Double Ratchet Encryption mechanism ...... 87 189 2.6.5 Double Ratchet parameters ...... 87 190 2.7 Wrapping/unwrapping private keys ...... 87 191 2.8 Generic secret key ...... 90 192 2.8.1 Definitions ...... 90 193 2.8.2 Generic secret key objects ...... 90 194 2.8.3 Generic secret key generation ...... 91 195 2.9 HMAC mechanisms ...... 91 196 2.9.1 General block cipher mechanism parameters ...... 91 197 2.10 AES ...... 91 198 2.10.1 Definitions ...... 92 199 2.10.2 AES secret key objects ...... 92 200 2.10.3 AES key generation ...... 93 201 2.10.4 AES-ECB ...... 93 202 2.10.5 AES-CBC ...... 94 203 2.10.6 AES-CBC with PKCS padding ...... 95 204 2.10.7 AES-OFB ...... 95 205 2.10.8 AES-CFB...... 96 206 2.10.9 General-length AES-MAC ...... 96 207 2.10.10 AES-MAC ...... 96 208 2.10.11 AES-XCBC-MAC ...... 97 209 2.10.12 AES-XCBC-MAC-96 ...... 97 210 2.11 AES with Counter ...... 97 211 2.11.1 Definitions ...... 97 212 2.11.2 AES with Counter mechanism parameters ...... 98 213 2.11.3 AES with Counter Encryption / Decryption ...... 98 214 2.12 AES CBC with Cipher Text Stealing CTS ...... 99 215 2.12.1 Definitions ...... 99
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 5 of 278 216 2.12.2 AES CTS mechanism parameters ...... 99 217 2.13 Additional AES Mechanisms ...... 99 218 2.13.1 Definitions ...... 99 219 2.13.2 AES-GCM Authenticated Encryption / Decryption ...... 100 220 2.13.3 AES-CCM authenticated Encryption / Decryption ...... 101 221 2.13.4 AES-GMAC ...... 103 222 2.13.5 AES GCM and CCM Mechanism parameters ...... 104 223 2.14 AES CMAC ...... 106 224 2.14.1 Definitions ...... 107 225 2.14.2 Mechanism parameters ...... 107 226 2.14.3 General-length AES-CMAC ...... 107 227 2.14.4 AES-CMAC ...... 107 228 2.15 AES XTS ...... 108 229 2.15.1 Definitions ...... 108 230 2.15.2 AES-XTS secret key objects ...... 108 231 2.15.3 AES-XTS key generation ...... 108 232 2.15.4 AES-XTS ...... 109 233 2.16 AES Key Wrap ...... 109 234 2.16.1 Definitions ...... 109 235 2.16.2 AES Key Wrap Mechanism parameters ...... 109 236 2.16.3 AES Key Wrap ...... 109 237 2.17 Key derivation by data encryption – DES & AES ...... 110 238 2.17.1 Definitions ...... 110 239 2.17.2 Mechanism Parameters ...... 111 240 2.17.3 Mechanism Description ...... 111 241 2.18 Double and Triple-length DES...... 111 242 2.18.1 Definitions ...... 112 243 2.18.2 DES2 secret key objects ...... 112 244 2.18.3 DES3 secret key objects ...... 113 245 2.18.4 Double-length DES key generation ...... 113 246 2.18.5 Triple-length DES Order of Operations ...... 114 247 2.18.6 Triple-length DES in CBC Mode...... 114 248 2.18.7 DES and Triple length DES in OFB Mode ...... 114 249 2.18.8 DES and Triple length DES in CFB Mode ...... 115 250 2.19 Double and Triple-length DES CMAC ...... 115 251 2.19.1 Definitions ...... 115 252 2.19.2 Mechanism parameters ...... 116 253 2.19.3 General-length DES3-MAC ...... 116 254 2.19.4 DES3-CMAC ...... 116 255 2.20 SHA-1 ...... 116 256 2.20.1 Definitions ...... 117 257 2.20.2 SHA-1 digest ...... 117 258 2.20.3 General-length SHA-1-HMAC ...... 117 259 2.20.4 SHA-1-HMAC ...... 118 260 2.20.5 SHA-1 key derivation ...... 118
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 6 of 278 261 2.20.6 SHA-1 HMAC key generation ...... 118 262 2.21 SHA-224...... 119 263 2.21.1 Definitions ...... 119 264 2.21.2 SHA-224 digest ...... 119 265 2.21.3 General-length SHA-224-HMAC ...... 120 266 2.21.4 SHA-224-HMAC ...... 120 267 2.21.5 SHA-224 key derivation ...... 120 268 2.21.6 SHA-224 HMAC key generation ...... 120 269 2.22 SHA-256...... 120 270 2.22.1 Definitions ...... 121 271 2.22.2 SHA-256 digest ...... 121 272 2.22.3 General-length SHA-256-HMAC ...... 121 273 2.22.4 SHA-256-HMAC ...... 122 274 2.22.5 SHA-256 key derivation ...... 122 275 2.22.6 SHA-256 HMAC key generation ...... 122 276 2.23 SHA-384...... 122 277 2.23.1 Definitions ...... 123 278 2.23.2 SHA-384 digest ...... 123 279 2.23.3 General-length SHA-384-HMAC ...... 123 280 2.23.4 SHA-384-HMAC ...... 123 281 2.23.5 SHA-384 key derivation ...... 124 282 2.23.6 SHA-384 HMAC key generation ...... 124 283 2.24 SHA-512...... 124 284 2.24.1 Definitions ...... 124 285 2.24.2 SHA-512 digest ...... 124 286 2.24.3 General-length SHA-512-HMAC ...... 125 287 2.24.4 SHA-512-HMAC ...... 125 288 2.24.5 SHA-512 key derivation ...... 125 289 2.24.6 SHA-512 HMAC key generation ...... 125 290 2.25 SHA-512/224 ...... 126 291 2.25.1 Definitions ...... 126 292 2.25.2 SHA-512/224 digest ...... 126 293 2.25.3 General-length SHA-512/224-HMAC ...... 126 294 2.25.4 SHA-512/224-HMAC ...... 127 295 2.25.5 SHA-512/224 key derivation ...... 127 296 2.25.6 SHA-512/224 HMAC key generation ...... 127 297 2.26 SHA-512/256 ...... 127 298 2.26.1 Definitions ...... 128 299 2.26.2 SHA-512/256 digest ...... 128 300 2.26.3 General-length SHA-512/256-HMAC ...... 128 301 2.26.4 SHA-512/256-HMAC ...... 129 302 2.26.5 SHA-512/256 key derivation ...... 129 303 2.26.6 SHA-512/256 HMAC key generation ...... 129 304 2.27 SHA-512/t ...... 129 305 2.27.1 Definitions ...... 130
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 7 of 278 306 2.27.2 SHA-512/t digest ...... 130 307 2.27.3 General-length SHA-512/t-HMAC ...... 130 308 2.27.4 SHA-512/t-HMAC ...... 130 309 2.27.5 SHA-512/t key derivation ...... 131 310 2.27.6 SHA-512/t HMAC key generation ...... 131 311 2.28 SHA3-224 ...... 131 312 2.28.1 Definitions ...... 131 313 2.28.2 SHA3-224 digest ...... 132 314 2.28.3 General-length SHA3-224-HMAC ...... 132 315 2.28.4 SHA3-224-HMAC ...... 132 316 2.28.5 SHA3-224 key derivation ...... 132 317 2.28.6 SHA3-224 HMAC key generation ...... 132 318 2.29 SHA3-256 ...... 133 319 2.29.1 Definitions ...... 133 320 2.29.2 SHA3-256 digest ...... 133 321 2.29.3 General-length SHA3-256-HMAC ...... 133 322 2.29.4 SHA3-256-HMAC ...... 134 323 2.29.5 SHA3-256 key derivation ...... 134 324 2.29.6 SHA3-256 HMAC key generation ...... 134 325 2.30 SHA3-384 ...... 134 326 2.30.1 Definitions ...... 135 327 2.30.2 SHA3-384 digest ...... 135 328 2.30.3 General-length SHA3-384-HMAC ...... 135 329 2.30.4 SHA3-384-HMAC ...... 136 330 2.30.5 SHA3-384 key derivation ...... 136 331 2.30.6 SHA3-384 HMAC key generation ...... 136 332 2.31 SHA3-512 ...... 136 333 2.31.1 Definitions ...... 136 334 2.31.2 SHA3-512 digest ...... 137 335 2.31.3 General-length SHA3-512-HMAC ...... 137 336 2.31.4 SHA3-512-HMAC ...... 137 337 2.31.5 SHA3-512 key derivation ...... 137 338 2.31.6 SHA3-512 HMAC key generation ...... 138 339 2.32 SHAKE ...... 138 340 2.32.1 Definitions ...... 138 341 2.32.2 SHAKE Key Derivation ...... 138 342 2.33 Blake2b-160 ...... 139 343 2.33.1 Definitions ...... 139 344 2.33.2 BLAKE2B-160 digest ...... 139 345 2.33.3 General-length BLAKE2B-160-HMAC ...... 140 346 2.33.4 BLAKE2B-160-HMAC ...... 140 347 2.33.5 BLAKE2B-160 key derivation ...... 140 348 2.33.6 BLAKE2B-160 HMAC key generation ...... 140 349 2.34 BLAKE2B-256 ...... 140 350 2.34.1 Definitions ...... 141
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 8 of 278 351 2.34.2 BLAKE2B-256 digest ...... 141 352 2.34.3 General-length BLAKE2B-256-HMAC ...... 141 353 2.34.4 BLAKE2B-256-HMAC ...... 142 354 2.34.5 BLAKE2B-256 key derivation ...... 142 355 2.34.6 BLAKE2B-256 HMAC key generation ...... 142 356 2.35 BLAKE2B-384 ...... 142 357 2.35.1 Definitions ...... 143 358 2.35.2 BLAKE2B-384 digest ...... 143 359 2.35.3 General-length BLAKE2B-384-HMAC ...... 143 360 2.35.4 BLAKE2B-384-HMAC ...... 143 361 2.35.5 BLAKE2B-384 key derivation ...... 144 362 2.35.6 BLAKE2B-384 HMAC key generation ...... 144 363 2.36 BLAKE2B-512 ...... 144 364 2.36.1 Definitions ...... 144 365 2.36.2 BLAKE2B-512 digest ...... 144 366 2.36.3 General-length BLAKE2B-512-HMAC ...... 145 367 2.36.4 BLAKE2B-512-HMAC ...... 145 368 2.36.5 BLAKE2B-512 key derivation ...... 145 369 2.36.6 BLAKE2B-512 HMAC key generation ...... 145 370 2.37 PKCS #5 and PKCS #5-style password-based encryption (PBE) ...... 146 371 2.37.1 Definitions ...... 146 372 2.37.2 Password-based encryption/authentication mechanism parameters ...... 146 373 2.37.3 PKCS #5 PBKDF2 key generation mechanism parameters ...... 147 374 2.37.4 PKCS #5 PBKD2 key generation ...... 149 375 2.38 PKCS #12 password-based encryption/authentication mechanisms ...... 149 376 2.38.1 SHA-1-PBE for 3-key triple-DES-CBC ...... 150 377 2.38.2 SHA-1-PBE for 2-key triple-DES-CBC ...... 150 378 2.38.3 SHA-1-PBA for SHA-1-HMAC ...... 150 379 2.39 SSL ...... 151 380 2.39.1 Definitions ...... 151 381 2.39.2 SSL mechanism parameters ...... 151 382 2.39.3 Pre-master key generation ...... 153 383 2.39.4 Master key derivation ...... 154 384 2.39.5 Master key derivation for Diffie-Hellman ...... 154 385 2.39.6 Key and MAC derivation ...... 155 386 2.39.7 MD5 MACing in SSL 3.0 ...... 156 387 2.39.8 SHA-1 MACing in SSL 3.0 ...... 156 388 2.40 TLS 1.2 Mechanisms ...... 157 389 2.40.1 Definitions ...... 157 390 2.40.2 TLS 1.2 mechanism parameters ...... 157 391 2.40.3 TLS MAC...... 160 392 2.40.4 Master key derivation ...... 161 393 2.40.5 Master key derivation for Diffie-Hellman ...... 161 394 2.40.6 Key and MAC derivation ...... 162 395 2.40.7 CKM_TLS12_KEY_SAFE_DERIVE ...... 163
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 9 of 278 396 2.40.8 Generic Key Derivation using the TLS PRF ...... 163 397 2.40.9 Generic Key Derivation using the TLS12 PRF ...... 164 398 2.41 WTLS ...... 165 399 2.41.1 Definitions ...... 165 400 2.41.2 WTLS mechanism parameters ...... 165 401 2.41.3 Pre master secret key generation for RSA key exchange suite ...... 168 402 2.41.4 Master secret key derivation ...... 169 403 2.41.5 Master secret key derivation for Diffie-Hellman and Elliptic Curve Cryptography ...... 169 404 2.41.6 WTLS PRF (pseudorandom function) ...... 170 405 2.41.7 Server Key and MAC derivation ...... 170 406 2.41.8 Client key and MAC derivation ...... 171 407 2.42 SP 800-108 Key Derivation ...... 172 408 2.42.1 Definitions ...... 172 409 2.42.2 Mechanism Parameters ...... 173 410 2.42.3 Counter Mode KDF ...... 178 411 2.42.4 Feedback Mode KDF ...... 178 412 2.42.5 Double Pipeline Mode KDF ...... 179 413 2.42.6 Deriving Additional Keys ...... 180 414 2.42.7 Key Derivation Attribute Rules ...... 181 415 2.42.8 Constructing PRF Input Data ...... 181 416 2.43 Miscellaneous simple key derivation mechanisms ...... 186 417 2.43.1 Definitions ...... 186 418 2.43.2 Parameters for miscellaneous simple key derivation mechanisms ...... 186 419 2.43.3 Concatenation of a base key and another key ...... 187 420 2.43.4 Concatenation of a base key and data ...... 188 421 2.43.5 Concatenation of data and a base key ...... 188 422 2.43.6 XORing of a key and data ...... 189 423 2.43.7 Extraction of one key from another key ...... 190 424 2.44 CMS ...... 191 425 2.44.1 Definitions ...... 191 426 2.44.2 CMS Signature Mechanism Objects ...... 191 427 2.44.3 CMS mechanism parameters ...... 191 428 2.44.4 CMS signatures ...... 193 429 2.45 Blowfish ...... 193 430 2.45.1 Definitions ...... 194 431 2.45.2 BLOWFISH secret key objects ...... 194 432 2.45.3 Blowfish key generation ...... 195 433 2.45.4 Blowfish-CBC ...... 195 434 2.45.5 Blowfish-CBC with PKCS padding ...... 195 435 2.46 Twofish ...... 196 436 2.46.1 Definitions ...... 196 437 2.46.2 Twofish secret key objects ...... 196 438 2.46.3 Twofish key generation ...... 197 439 2.46.4 Twofish -CBC ...... 197 440 2.46.5 Twofish-CBC with PKCS padding ...... 197
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 10 of 278 441 2.47 CAMELLIA ...... 197 442 2.47.1 Definitions ...... 198 443 2.47.2 Camellia secret key objects ...... 198 444 2.47.3 Camellia key generation ...... 199 445 2.47.4 Camellia-ECB ...... 199 446 2.47.5 Camellia-CBC ...... 200 447 2.47.6 Camellia-CBC with PKCS padding ...... 200 448 2.47.7 CAMELLIA with Counter mechanism parameters ...... 201 449 2.47.8 General-length Camellia-MAC ...... 202 450 2.47.9 Camellia-MAC ...... 202 451 2.48 Key derivation by data encryption - Camellia ...... 203 452 2.48.1 Definitions ...... 203 453 2.48.2 Mechanism Parameters ...... 203 454 2.49 ARIA...... 203 455 2.49.1 Definitions ...... 204 456 2.49.2 Aria secret key objects ...... 204 457 2.49.3 ARIA key generation ...... 205 458 2.49.4 ARIA-ECB ...... 205 459 2.49.5 ARIA-CBC ...... 205 460 2.49.6 ARIA-CBC with PKCS padding ...... 206 461 2.49.7 General-length ARIA-MAC ...... 207 462 2.49.8 ARIA-MAC ...... 207 463 2.50 Key derivation by data encryption - ARIA ...... 207 464 2.50.1 Definitions ...... 208 465 2.50.2 Mechanism Parameters ...... 208 466 2.51 SEED ...... 208 467 2.51.1 Definitions ...... 209 468 2.51.2 SEED secret key objects ...... 209 469 2.51.3 SEED key generation ...... 210 470 2.51.4 SEED-ECB ...... 210 471 2.51.5 SEED-CBC ...... 210 472 2.51.6 SEED-CBC with PKCS padding ...... 210 473 2.51.7 General-length SEED-MAC ...... 211 474 2.51.8 SEED-MAC ...... 211 475 2.52 Key derivation by data encryption - SEED ...... 211 476 2.52.1 Definitions ...... 211 477 2.52.2 Mechanism Parameters ...... 211 478 2.53 OTP ...... 211 479 2.53.1 Usage overview ...... 211 480 2.53.2 Case 1: Generation of OTP values ...... 212 481 2.53.3 Case 2: Verification of provided OTP values ...... 213 482 2.53.4 Case 3: Generation of OTP keys ...... 213 483 2.53.5 OTP objects ...... 214 484 2.53.6 OTP-related notifications ...... 216 485 2.53.7 OTP mechanisms ...... 217
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 11 of 278 486 2.53.8 RSA SecurID ...... 221 487 2.53.9 OATH HOTP ...... 223 488 2.53.10 ActivIdentity ACTI ...... 224 489 2.54 CT-KIP ...... 226 490 2.54.1 Principles of Operation ...... 226 491 2.54.2 Mechanisms ...... 226 492 2.54.3 Definitions ...... 227 493 2.54.4 CT-KIP Mechanism parameters ...... 227 494 2.54.5 CT-KIP key derivation ...... 227 495 2.54.6 CT-KIP key wrap and key unwrap ...... 228 496 2.54.7 CT-KIP signature generation ...... 228 497 2.55 GOST 28147-89 ...... 228 498 2.55.1 Definitions ...... 229 499 2.55.2 GOST 28147-89 secret key objects ...... 229 500 2.55.3 GOST 28147-89 domain parameter objects ...... 230 501 2.55.4 GOST 28147-89 key generation ...... 230 502 2.55.5 GOST 28147-89-ECB ...... 231 503 2.55.6 GOST 28147-89 encryption mode except ECB ...... 231 504 2.55.7 GOST 28147-89-MAC ...... 232 505 2.55.8 GOST 28147-89 keys wrapping/unwrapping with GOST 28147-89 ...... 232 506 2.56 GOST R 34.11-94 ...... 233 507 2.56.1 Definitions ...... 233 508 2.56.2 GOST R 34.11-94 domain parameter objects ...... 233 509 2.56.3 GOST R 34.11-94 digest ...... 234 510 2.56.4 GOST R 34.11-94 HMAC ...... 235 511 2.57 GOST R 34.10-2001 ...... 235 512 2.57.1 Definitions ...... 236 513 2.57.2 GOST R 34.10-2001 public key objects ...... 236 514 2.57.3 GOST R 34.10-2001 private key objects ...... 237 515 2.57.4 GOST R 34.10-2001 domain parameter objects ...... 239 516 2.57.5 GOST R 34.10-2001 mechanism parameters ...... 240 517 2.57.6 GOST R 34.10-2001 key pair generation ...... 241 518 2.57.7 GOST R 34.10-2001 without hashing ...... 242 519 2.57.8 GOST R 34.10-2001 with GOST R 34.11-94 ...... 242 520 2.57.9 GOST 28147-89 keys wrapping/unwrapping with GOST R 34.10-2001 ...... 243 521 2.57.10 Common key derivation with assistance of GOST R 34.10-2001 keys ...... 243 522 2.58 ChaCha20 ...... 243 523 2.58.1 Definitions ...... 243 524 2.58.2 ChaCha20 secret key objects ...... 243 525 2.58.3 ChaCha20 mechanism parameters ...... 244 526 2.58.4 ChaCha20 key generation ...... 244 527 2.58.5 ChaCha20 mechanism ...... 245 528 2.59 Salsa20 ...... 246 529 2.59.1 Definitions ...... 246 530 2.59.2 Salsa20 secret key objects ...... 246
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 12 of 278 531 2.59.3 Salsa20 mechanism parameters ...... 247 532 2.59.4 Salsa20 key generation ...... 247 533 2.59.5 Salsa20 mechanism ...... 247 534 2.60 Poly1305 ...... 248 535 2.60.1 Definitions ...... 248 536 2.60.2 Poly1305 secret key objects ...... 249 537 2.60.3 Poly1305 mechanism ...... 249 538 2.61 Chacha20/Poly1305 and Salsa20/Poly1305 Authenticated Encryption / Decryption ...... 249 539 2.61.1 Definitions ...... 250 540 2.61.2 Usage...... 250 541 2.61.3 ChaCha20/Poly1305 and Salsa20/Poly1305 Mechanism parameters ...... 251 542 2.62 HKDF Mechanisms ...... 252 543 2.62.1 Definitions ...... 253 544 2.62.2 HKDF mechanism parameters ...... 253 545 2.62.3 HKDF derive ...... 254 546 2.62.4 HKDF Data ...... 254 547 2.62.5 HKDF Key gen ...... 255 548 2.63 NULL Mechanism ...... 255 549 2.63.1 Definitions ...... 255 550 2.63.2 CKM_NULL mechanism parameters ...... 255 551 3 PKCS #11 Implementation Conformance ...... 256 552 Appendix A. Acknowledgments ...... 257 553 Appendix B. Manifest Constants ...... 260 554 B.1 Object classes ...... 260 555 B.2 Key types ...... 260 556 B.3 Key derivation functions ...... 261 557 B.4 Mechanisms ...... 262 558 B.5 Attributes...... 271 559 B.6 Attribute constants ...... 273 560 B.7 Other constants ...... 273 561 B.8 Notifications ...... 274 562 B.9 Return values ...... 274 563 Appendix C. Revision History ...... 277 564
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 13 of 278 565 1 Introduction 566 This document defines mechanisms that are anticipated to be used with the current version of PKCS #11. 567 All text is normative unless otherwise labeled.
568 1.1 Terminology 569 The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD 570 NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described 571 in [RFC2119]
572 1.2 Definitions 573 For the purposes of this standard, the following definitions apply. Please refer to the [PKCS#11-Base] for 574 further definitions: 575 AES Advanced Encryption Standard, as defined in FIPS PUB 197.
576 CAMELLIA The Camellia encryption algorithm, as defined in RFC 3713.
577 BLOWFISH The Blowfish Encryption Algorithm of Bruce Schneier, 578 www.schneier.com.
579 CBC Cipher-Block Chaining mode, as defined in FIPS PUB 81.
580 CDMF Commercial Data Masking Facility, a block encipherment method 581 specified by International Business Machines Corporation and 582 based on DES.
583 CMAC Cipher-based Message Authenticate Code as defined in [NIST 584 sp800-38b] and [RFC 4493].
585 CMS Cryptographic Message Syntax (see RFC 2630)
586 CT-KIP Cryptographic Token Key Initialization Protocol (as defined in [CT- 587 KIP])
588 DES Data Encryption Standard, as defined in FIPS PUB 46-3.
589 DSA Digital Signature Algorithm, as defined in FIPS PUB 186-2.
590 EC Elliptic Curve
591 ECB Electronic Codebook mode, as defined in FIPS PUB 81.
592 ECDH Elliptic Curve Diffie-Hellman.
593 ECDSA Elliptic Curve DSA, as in ANSI X9.62.
594 ECMQV Elliptic Curve Menezes-Qu-Vanstone
595 GOST 28147-89 The encryption algorithm, as defined in Part 2 [GOST 28147-89] 596 and [RFC 4357] [RFC 4490], and RFC [4491].
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 14 of 278 597 GOST R 34.11-94 Hash algorithm, as defined in [GOST R 34.11-94] and [RFC 4357], 598 [RFC 4490], and [RFC 4491].
599 GOST R 34.10-2001 The digital signature algorithm, as defined in [GOST R 34.10-2001] 600 and [RFC 4357], [RFC 4490], and [RFC 4491].
601 IV Initialization Vector.
602 MAC Message Authentication Code.
603 MQV Menezes-Qu-Vanstone
604 OAEP Optimal Asymmetric Encryption Padding for RSA.
605 PKCS Public-Key Cryptography Standards.
606 PRF Pseudo random function.
607 PTD Personal Trusted Device, as defined in MeT-PTD
608 RSA The RSA public-key cryptosystem.
609 SHA-1 The (revised) Secure Hash Algorithm with a 160-bit message digest, 610 as defined in FIPS PUB 180-2.
611 SHA-224 The Secure Hash Algorithm with a 224-bit message digest, as 612 defined in RFC 3874. Also defined in FIPS PUB 180-2 with Change 613 Notice 1.
614 SHA-256 The Secure Hash Algorithm with a 256-bit message digest, as 615 defined in FIPS PUB 180-2.
616 SHA-384 The Secure Hash Algorithm with a 384-bit message digest, as 617 defined in FIPS PUB 180-2.
618 SHA-512 The Secure Hash Algorithm with a 512-bit message digest, as 619 defined in FIPS PUB 180-2.
620 SSL The Secure Sockets Layer 3.0 protocol.
621 SO A Security Officer user.
622 TLS Transport Layer Security.
623 WIM Wireless Identification Module.
624 WTLS Wireless Transport Layer Security.
625
626 1.3 Normative References 627 [ARIA] National Security Research Institute, Korea, “Block Cipher Algorithm ARIA”, 628 URL: http://tools.ietf.org/html/rfc5794
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 15 of 278 629 [BLOWFISH] B. Schneier. Description of a New Variable-Length Key, 64-Bit Block Cipher 630 (Blowfish), December 1993. 631 URL: https://www.schneier.com/paper-blowfish-fse.html 632 [CAMELLIA] M. Matsui, J. Nakajima, S. Moriai. A Description of the Camellia Encryption 633 Algorithm, April 2004. 634 URL: http://www.ietf.org/rfc/rfc3713.txt 635 [CDMF] Johnson, D.B The Commercial Data Masking Facility (CDMF) data privacy 636 algorithm, March 1994. 637 URL: http://ieeexplore.ieee.org/xpl/articleDetails.jsp?arnumber=5389557 638 [CHACHA] D. Bernstein, ChaCha, a variant of Salsa20, Jan 2008. 639 URL: http://cr.yp.to/chacha/chacha-20080128.pdf 640 [DH] W. Diffie, M. Hellman. New Directions in Cryptography. Nov, 1976. 641 URL: http://www-ee.stanford.edu/~hellman/publications/24.pdf 642 [FIPS PUB 81] NIST. FIPS 81: DES Modes of Operation. December 1980. 643 URL: http://csrc.nist.gov/publications/fips/fips81/fips81.htm 644 [FIPS PUB 186-4] NIST. FIPS 186-4: Digital Signature Standard. July 2013. 645 URL: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf 646 [FIPS PUB 197] NIST. FIPS 197: Advanced Encryption Standard. November 26, 2001. 647 URL: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf 648 [FIPS SP 800-56A] NIST. Special Publication 800-56A Revision 2: Recommendation for Pair-Wise 649 Key Establishment Schemes Using Discrete Logarithm Cryptography, May 2013. 650 URL: http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar2.pdf 651 [FIPS SP 800-108] NIST. Special Publication 800-108 (Revised): Recommendation for Key 652 Derivation Using Pseudorandom Functions, October 2009. 653 URL: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800- 654 108.pdf 655 [GOST] V. Dolmatov, A. Degtyarev. GOST R. 34.11-2012: Hash Function. August 2013. 656 URL: http://tools.ietf.org/html/rfc6986 657 [MD2] B. Kaliski. RSA Laboratories. The MD2 Message-Digest Algorithm. April, 1992. 658 URL: http://tools.ietf.org/html/rfc1319 659 [MD5] RSA Data Security. R. Rivest. The MD5 Message-Digest Algorithm. April, 1992. 660 URL: http://tools.ietf.org/html/rfc1319 661 [OAEP] M. Bellare, P. Rogaway. Optimal Asymmetric Encryption – How to Encrypt with 662 RSA. Nov 19, 1995. 663 URL: http://cseweb.ucsd.edu/users/mihir/papers/oae.pdf 664 [PKCS11-Base] PKCS #11 Cryptographic Token Interface Base Specification Version 3.00. 665 Edited by Chris Zimman and Dieter Bong. Latest version: http://docs.oasis- 666 open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html. 667 [PKCS11-Hist] PKCS #11 Cryptographic Token Interface Historical Mechanisms Specification 668 Version 3.00. Edited by Chris Zimman and Dieter Bong. Latest version: 669 http://docs.oasis-open.org/pkcs11/pkcs11-hist/v2.40/pkcs11-hist-v2.40.html. 670 [PKCS11-Prof] PKCS #11 Cryptographic Token Interface Profiles Version 3.00. Edited by Tim 671 Hudson. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11- 672 profiles/v2.40/pkcs11-profiles-v2.40.html. 673 [POLY1305] D.J. Bernstein. The Poly1305-AES message-authentication code. Jan 2005. 674 URL: https://cr.yp.to/mac/poly1305-20050329.pdf 675 [RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 676 14, RFC 2119, March 1997. 677 URL: http://www.ietf.org/rfc/rfc2119.txt. 678 [RIPEMD] H. Dobbertin, A. Bosselaers, B. Preneel. The hash function RIPEMD-160, Feb 679 13, 2012. 680 URL: http://homes.esat.kuleuven.be/~bosselae/ripemd160.html
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 16 of 278 681 [SALSA] D. Bernstein, ChaCha, a variant of Salsa20, Jan 2008. 682 URL: http://cr.yp.to/chacha/chacha-20080128.pdf 683 [SEED] KISA. SEED 128 Algorithm Specification. Sep 2003. 684 URL: http://seed.kisa.or.kr/html/egovframework/iwt/ds/ko/ref/%5B2%5D_SEED+1 685 28_Specification_english_M.pdf 686 [SHA-1] NIST. FIPS 180-4: Secure Hash Standard. March 2012. 687 URL: http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf 688 [SHA-2] NIST. FIPS 180-4: Secure Hash Standard. March 2012. 689 URL: http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf 690 [TWOFISH] B. Schneier, J. Kelsey, D. Whiting, C. Hall, N. Ferguson. Twofish: A 128-Bit Block 691 Cipher. June 15, 1998. 692 URL: https://www.schneier.com/paper-twofish-paper.pdf
693 1.4 Non-Normative References 694 [CAP-1.2] Common Alerting Protocol Version 1.2. 01 July 2010. OASIS Standard. 695 URL: http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html 696 [AES KEYWRAP] National Institute of Standards and Technology, NIST Special Publication 800- 697 38F, Recommendation for Block Cipher Modes of Operation: Methods for Key 698 Wrapping, December 2012, 699 http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf 700 [ANSI C] ANSI/ISO. American National Standard for Programming Languages – C. 1990. 701 [ANSI X9.31] Accredited Standards Committee X9. Digital Signatures Using Reversible Public 702 Key Cryptography for the Financial Services Industry (rDSA). 1998. 703 [ANSI X9.42] Accredited Standards Committee X9. Public Key Cryptography for the Financial 704 Services Industry: Agreement of Symmetric Keys Using Discrete Logarithm 705 Cryptography. 2003. 706 [ANSI X9.62] Accredited Standards Committee X9. Public Key Cryptography for the Financial 707 Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA). 1998. 708 [ANSI X9.63] Accredited Standards Committee X9. Public Key Cryptography for the Financial 709 Services Industry: Key Agreement and Key Transport Using Elliptic Curve 710 Cryptography. 2001. 711 URL: http://webstore.ansi.org/RecordDetail.aspx?sku=X9.63-2011 712 [BRAINPOOL] ECC Brainpool Standard Curves and Curve Generation, v1.0, 19.10.2005 713 URL: http://www.ecc-brainpool.org 714 [CT-KIP] RSA Laboratories. Cryptographic Token Key Initialization Protocol. Version 1.0, 715 December 2005. 716 URL: ftp://ftp.rsasecurity.com/pub/otps/ct-kip/ct-kip-v1-0.pdf. 717 [CC/PP] CCPP-STRUCT-VOCAB, G. Klyne, F. Reynolds, C. , H. Ohto, J. Hjelm, M. H. 718 Butler, L. Tran, Editors, W3C Recommendation, 15 January 2004, 719 URL: http://www.w3.org/TR/2004/REC-CCPP-struct-vocab-20040115/ 720 Latest version available at http://www.w3.org/TR/CCPP-struct-vocab/ 721 [LEGIFRANCE] Avis relatif aux paramètres de courbes elliptiques définis par l'Etat français 722 (Publication of elliptic curve parameters by the French state) 723 URL: 724 https://www.legifrance.gouv.fr/affichTexte.do?cidTexte=JORFTEXT00002466881 725 6 726 [NIST AES CTS] National Institute of Standards and Technology, Addendum to NIST Special 727 Publication 800-38A, “Recommendation for Block Cipher Modes of Operation: 728 Three Variants of Ciphertext Stealing for CBC Mode” 729 URL: http://csrc.nist.gov/publications/nistpubs/800-38a/addendum-to-nist_sp800- 730 38A.pdf
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 17 of 278 731 [PKCS11-UG] PKCS #11 Cryptographic Token Interface Usage Guide Version 2.41. Edited by 732 John Leiseboer and Robert Griffin. version: http://docs.oasis- 733 open.org/pkcs11/pkcs11-ug/v2.40/pkcs11-ug-v2.40.html. 734 [RFC 2865] Rigney et al, “Remote Authentication Dial In User Service (RADIUS)”, IETF 735 RFC2865, June 2000. 736 URL: http://www.ietf.org/rfc/rfc2865.txt. 737 [RFC 3686] Housley, “Using Advanced Encryption Standard (AES) Counter Mode With IPsec 738 Encapsulating Security Payload (ESP),” IETF RFC 3686, January 2004. 739 URL: http://www.ietf.org/rfc/rfc3686.txt. 740 [RFC 3717] Matsui, et al, ”A Description of the Camellia Encryption Algorithm,” IETF RFC 741 3717, April 2004. 742 URL: http://www.ietf.org/rfc/rfc3713.txt. 743 [RFC 3610] Whiting, D., Housley, R., and N. Ferguson, “Counter with CBC-MAC (CCM)", 744 IETF RFC 3610, September 2003. 745 URL: http://www.ietf.org/rfc/rfc3610.txt 746 [RFC 3874] Smit et al, “A 224-bit One-way Hash Function: SHA-224,” IETF RFC 3874, June 747 2004. 748 URL: http://www.ietf.org/rfc/rfc3874.txt. 749 [RFC 3748] Aboba et al, “Extensible Authentication Protocol (EAP)”, IETF RFC 3748, June 750 2004. 751 URL: http://www.ietf.org/rfc/rfc3748.txt. 752 [RFC 4269] South Korean Information Security Agency (KISA) “The SEED Encryption 753 Algorithm”, December 2005. 754 URL: ftp://ftp.rfc-editor.org/in-notes/rfc4269.txt 755 [RFC 4309] Housley, R., “Using Advanced Encryption Standard (AES) CCM Mode with IPsec 756 Encapsulating Security Payload (ESP),” IETF RFC 4309, December 2005. 757 URL: http://www.ietf.org/rfc/rfc4309.txt 758 [RFC 4357] V. Popov, I. Kurepkin, S. Leontiev “Additional Cryptographic Algorithms for Use 759 with GOST 28147-89, GOST R 34.10-94, GOST R 34.10-2001, and GOST R 760 34.11-94 Algorithms”, January 2006. 761 URL: http://www.ietf.org/rfc/rfc4357.txt 762 [RFC 4490] S. Leontiev, Ed. G. Chudov, Ed. “Using the GOST 28147-89, GOST R 34.11- 763 94,GOST R 34.10-94, and GOST R 34.10-2001 Algorithms with Cryptographic 764 Message Syntax (CMS)”, May 2006. 765 URL: http://www.ietf.org/rfc/rfc4490.txt 766 [RFC 4491] S. Leontiev, Ed., D. Shefanovski, Ed., “Using the GOST R 34.10-94, GOST R 767 34.10-2001, and GOST R 34.11-94 Algorithms with the Internet X.509 Public Key 768 Infrastructure Certificate and CRL Profile”, May 2006. 769 URL: http://www.ietf.org/rfc/rfc4491.txt 770 [RFC 4493] J. Song et al. RFC 4493: The AES-CMAC Algorithm. June 2006. 771 URL: http://www.ietf.org/rfc/rfc4493.txt 772 [RFC 5705] Rescorla, E., “The Keying Material Exporters for Transport Layer Security (TLS)”, 773 RFC 5705, March 2010. 774 URL: http://www.ietf.org/rfc/rfc5705.txt 775 [RFC 5869] H. Krawczyk, P. Eronen, “HMAC-based Extract-and-Expand Key Derivation 776 Function (HKDF)“, May 2010 777 URL: http://www.ietf.org/rfc/rfc5869.txt 778 [RFC 7539] Y Nir, A. Langley. RFC 7539: ChaCha20 and Poly1305 for IETF Protocols, May 779 2015 780 URL: https://tools.ietf.org/rfc/rfc7539.txt 781 [RFC 7748] Aboba et al, “Elliptic Curves for Security”, IETF RFC 7748, January 2016 782 URL: https://tools.ietf.org/html/rfc7748
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 18 of 278 783 [RFC 8032] Aboba et al, “Edwards-Curve Digital Signature Algorithm (EdDSA)”, IETF RFC 784 8032, January 2017 785 URL: https://tools.ietf.org/html/rfc8032 786 [SEC 1] Standards for Efficient Cryptography Group (SECG). Standards for Efficient 787 Cryptography (SEC) 1: Elliptic Curve Cryptography. Version 1.0, September 20, 788 2000. 789 [SEC 2] Standards for Efficient Cryptography Group (SECG). Standards for Efficient 790 Cryptography (SEC) 2: Recommended Elliptic Curve Domain Parameters. 791 Version 1.0, September 20, 2000. 792 [SIGNAL] The X3DH Key Agreement Protocol, Revision 1, 2016-11-04, Moxie Marlinspike, 793 Trevor Perrin (editor) 794 URL: https://signal.org/docs/specifications/x3dh/ 795 [TLS] [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, 796 January 1999. http://www.ietf.org/rfc/rfc2246.txt, superseded by [RFC4346] 797 Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 798 1.1", RFC 4346, April 2006. http://www.ietf.org/rfc/rfc4346.txt, which was 799 superseded by [5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 800 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 801 URL: http://www.ietf.org/rfc/rfc5246.txt 802 [TLS12] [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) 803 Protocol Version 1.2", RFC 5246, August 2008. 804 URL: http://www.ietf.org/rfc/rfc5246.txt 805 [WIM] WAP. Wireless Identity Module. — WAP-260-WIM-20010712-a. July 2001. 806 URL: http://technical.openmobilealliance.org/tech/affiliates/LicenseAgreement.as 807 p?DocName=/wap/wap-260-wim-20010712-a.pdf 808 [WPKI] Wireless Application Protocol: Public Key Infrastructure Definition. — WAP-217- 809 WPKI-20010424-a. April 2001. 810 URL: http://technical.openmobilealliance.org/tech/affiliates/LicenseAgreement.as 811 p?DocName=/wap/wap-217-wpki-20010424-a.pdf 812 [WTLS] WAP. Wireless Transport Layer Security Version — WAP-261-WTLS-20010406- 813 a. April 2001. 814 URL: http://technical.openmobilealliance.org/tech/affiliates/LicenseAgreement.as 815 p?DocName=/wap/wap-261-wtls-20010406-a.pdf 816 [XEDDSA] The XEdDSA and VXEdDSA Signature Schemes - Revision 1, 2016-10-20, 817 Trevor Perrin (editor) 818 URL: https://signal.org/docs/specifications/xeddsa/ 819 [X.500] ITU-T. Information Technology — Open Systems Interconnection — The 820 Directory: Overview of Concepts, Models and Services. February 2001. Identical 821 to ISO/IEC 9594-1 822 [X.509] ITU-T. Information Technology — Open Systems Interconnection — The 823 Directory: Public-key and Attribute Certificate Frameworks. March 2000. 824 Identical to ISO/IEC 9594-8 825 [X.680] ITU-T. Information Technology — Abstract Syntax Notation One (ASN.1): 826 Specification of Basic Notation. July 2002. Identical to ISO/IEC 8824-1 827 [X.690] ITU-T. Information Technology — ASN.1 Encoding Rules: Specification of Basic 828 Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished 829 Encoding Rules (DER). July 2002. Identical to ISO/IEC 8825-1 830
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 19 of 278 831 2 Mechanisms 832 A mechanism specifies precisely how a certain cryptographic process is to be performed. PKCS #11 833 implementations MAY use one of more mechanisms defined in this document. 834 The following table shows which Cryptoki mechanisms are supported by different cryptographic 835 operations. For any particular token, of course, a particular operation may well support only a subset of 836 the mechanisms listed. There is also no guarantee that a token which supports one mechanism for some 837 operations supports any other mechanism for any other operation (or even supports that same 838 mechanism for any other operation). For example, even if a token is able to create RSA digital signatures 839 with the CKM_RSA_PKCS mechanism, it may or may not be the case that the same token can also 840 perform RSA encryption with CKM_RSA_PKCS. 841 Each mechanism description is be preceded by a table, of the following format, mapping mechanisms to 842 API functions. 843
Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair
844 1 SR = SignRecover, VR = VerifyRecover. 845 2 Single-part operations only. 846 3 Mechanism can only be used for wrapping, not unwrapping. 847 The remainder of this section will present in detail the mechanisms supported by Cryptoki and the parameters which are supplied to them. 848 In general, if a mechanism makes no mention of the ulMinKeyLen and ulMaxKeyLen fields of the CK_MECHANISM_INFO structure, then those fields have no 849 meaning for that particular mechanism.
850 2.1 RSA 851 Table 1, Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR Key/ Unwrap 1 Key Pair CKM_RSA_PKCS_KEY_PAIR_GEN CKM_RSA_X9_31_KEY_PAIR_GEN CKM_RSA_PKCS 2 2 CKM_RSA_PKCS_OAEP 2 CKM_RSA_PKCS_PSS 2 CKM_RSA_9796 2 CKM_RSA_X_509 2 2 CKM_RSA_X9_31 2 CKM_SHA1_RSA_PKCS CKM_SHA256_RSA_PKCS CKM_SHA384_RSA_PKCS CKM_SHA512_RSA_PKCS
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 20 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR Key/ Unwrap 1 Key Pair CKM_SHA1_RSA_PKCS_PSS CKM_SHA256_RSA_PKCS_PSS CKM_SHA384_RSA_PKCS_PSS CKM_SHA512_RSA_PKCS_PSS CKM_SHA1_RSA_X9_31 CKM_RSA_PKCS_TPM_1_1 2 CKM_RSA_PKCS_OAEP_TPM_1_1 2 CKM_SHA3_224_RSA_PKCS CKM_SHA3_256_RSA_PKCS CKM_SHA3_384_RSA_PKCS CKM_SHA3_512_RSA_PKCS CKM_SHA3_224_RSA_PKCS_PSS CKM_SHA3_256_RSA_PKCS_PSS CKM_SHA3_384_RSA_PKCS_PSS CKM_SHA3_512_RSA_PKCS_PSS
852 2.1.1 Definitions 853 This section defines the RSA key type “CKK_RSA” for type CK_KEY_TYPE as used in the 854 CKA_KEY_TYPE attribute of RSA key objects. 855 Mechanisms: 856 CKM_RSA_PKCS_KEY_PAIR_GEN 857 CKM_RSA_PKCS 858 CKM_RSA_9796 859 CKM_RSA_X_509 860 CKM_MD2_RSA_PKCS 861 CKM_MD5_RSA_PKCS 862 CKM_SHA1_RSA_PKCS 863 CKM_SHA224_RSA_PKCS 864 CKM_SHA256_RSA_PKCS 865 CKM_SHA384_RSA_PKCS 866 CKM_SHA512_RSA_PKCS 867 CKM_RIPEMD128_RSA_PKCS 868 CKM_RIPEMD160_RSA_PKCS 869 CKM_RSA_PKCS_OAEP 870 CKM_RSA_X9_31_KEY_PAIR_GEN 871 CKM_RSA_X9_31 872 CKM_SHA1_RSA_X9_31 873 CKM_RSA_PKCS_PSS 874 CKM_SHA1_RSA_PKCS_PSS 875 CKM_SHA224_RSA_PKCS_PSS
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 21 of 278 876 CKM_SHA256_RSA_PKCS_PSS 877 CKM_SHA512_RSA_PKCS_PSS 878 CKM_SHA384_RSA_PKCS_PSS 879 CKM_RSA_PKCS_TPM_1_1 880 CKM_RSA_PKCS_OAEP_TPM_1_1 881 CKM_RSA_AES_KEY_WRAP 882 CKM_SHA3_224_RSA_PKCS 883 CKM_SHA3_256_RSA_PKCS 884 CKM_SHA3_384_RSA_PKCS 885 CKM_SHA3_512_RSA_PKCS 886 CKM_SHA3_224_RSA_PKCS_PSS 887 CKM_SHA3_256_RSA_PKCS_PSS 888 CKM_SHA3_384_RSA_PKCS_PSS 889 CKM_SHA3_512_RSA_PKCS_PSS 890
891 2.1.2 RSA public key objects 892 RSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_RSA) hold RSA public keys. 893 The following table defines the RSA public key object attributes, in addition to the common attributes 894 defined for this object class: 895 Table 2, RSA Public Key Object Attributes Attribute Data type Meaning CKA_MODULUS1,4 Big integer Modulus n CKA_MODULUS_BITS2,3 CK_ULONG Length in bits of modulus n CKA_PUBLIC_EXPONENT1 Big integer Public exponent e 896 - Refer to [PKCS11-Base] table 11 for footnotes 897 Depending on the token, there may be limits on the length of key components. See PKCS #1 for more 898 information on RSA keys. 899 The following is a sample template for creating an RSA public key object: 900 CK_OBJECT_CLASS class = CKO_PUBLIC_KEY; 901 CK_KEY_TYPE keyType = CKK_RSA; 902 CK_UTF8CHAR label[] = “An RSA public key object”; 903 CK_BYTE modulus[] = {...}; 904 CK_BYTE exponent[] = {...}; 905 CK_BBOOL true = CK_TRUE; 906 CK_ATTRIBUTE template[] = { 907 {CKA_CLASS, &class, sizeof(class)}, 908 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 909 {CKA_TOKEN, &true, sizeof(true)}, 910 {CKA_LABEL, label, sizeof(label)-1}, 911 {CKA_WRAP, &true, sizeof(true)}, 912 {CKA_ENCRYPT, &true, sizeof(true)}, 913 {CKA_MODULUS, modulus, sizeof(modulus)}, 914 {CKA_PUBLIC_EXPONENT, exponent, sizeof(exponent)} 915 };
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 22 of 278 916 2.1.3 RSA private key objects 917 RSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_RSA) hold RSA private keys. 918 The following table defines the RSA private key object attributes, in addition to the common attributes 919 defined for this object class: 920 Table 3, RSA Private Key Object Attributes Attribute Data type Meaning CKA_MODULUS1,4,6 Big integer Modulus n CKA_PUBLIC_EXPONENT4,6 Big integer Public exponent e CKA_PRIVATE_EXPONENT1,4,6,7 Big integer Private exponent d CKA_PRIME_14,6,7 Big integer Prime p CKA_PRIME_24,6,7 Big integer Prime q CKA_EXPONENT_14,6,7 Big integer Private exponent d modulo p-1 CKA_EXPONENT_24,6,7 Big integer Private exponent d modulo q-1 CKA_COEFFICIENT4,6,7 Big integer CRT coefficient q-1 mod p 921 - Refer to [PKCS11-Base] table 11 for footnotes 922 Depending on the token, there may be limits on the length of the key components. See PKCS #1 for 923 more information on RSA keys. 924 Tokens vary in what they actually store for RSA private keys. Some tokens store all of the above 925 attributes, which can assist in performing rapid RSA computations. Other tokens might store only the 926 CKA_MODULUS and CKA_PRIVATE_EXPONENT values. Effective with version 2.40, tokens MUST 927 also store CKA_PUBLIC_EXPONENT. This permits the retrieval of sufficient data to reconstitute the 928 associated public key. 929 Because of this, Cryptoki is flexible in dealing with RSA private key objects. When a token generates an 930 RSA private key, it stores whichever of the fields in Table 3 it keeps track of. Later, if an application asks 931 for the values of the key’s various attributes, Cryptoki supplies values only for attributes whose values it 932 can obtain (i.e., if Cryptoki is asked for the value of an attribute it cannot obtain, the request fails). Note 933 that a Cryptoki implementation may or may not be able and/or willing to supply various attributes of RSA 934 private keys which are not actually stored on the token. E.g., if a particular token stores values only for 935 the CKA_PRIVATE_EXPONENT, CKA_PRIME_1, and CKA_PRIME_2 attributes, then Cryptoki is 936 certainly able to report values for all the attributes above (since they can all be computed efficiently from 937 these three values). However, a Cryptoki implementation may or may not actually do this extra 938 computation. The only attributes from Table 3 for which a Cryptoki implementation is required to be able 939 to return values are CKA_MODULUS and CKA_PRIVATE_EXPONENT. 940 If an RSA private key object is created on a token, and more attributes from Table 3 are supplied to the 941 object creation call than are supported by the token, the extra attributes are likely to be thrown away. If 942 an attempt is made to create an RSA private key object on a token with insufficient attributes for that 943 particular token, then the object creation call fails and returns CKR_TEMPLATE_INCOMPLETE. 944 Note that when generating an RSA private key, there is no CKA_MODULUS_BITS attribute specified. 945 This is because RSA private keys are only generated as part of an RSA key pair, and the 946 CKA_MODULUS_BITS attribute for the pair is specified in the template for the RSA public key. 947 The following is a sample template for creating an RSA private key object: 948 CK_OBJECT_CLASS class = CKO_PRIVATE_KEY; 949 CK_KEY_TYPE keyType = CKK_RSA; 950 CK_UTF8CHAR label[] = “An RSA private key object”; 951 CK_BYTE subject[] = {...}; 952 CK_BYTE id[] = {123}; 953 CK_BYTE modulus[] = {...}; 954 CK_BYTE publicExponent[] = {...}; 955 CK_BYTE privateExponent[] = {...};
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 23 of 278 956 CK_BYTE prime1[] = {...}; 957 CK_BYTE prime2[] = {...}; 958 CK_BYTE exponent1[] = {...}; 959 CK_BYTE exponent2[] = {...}; 960 CK_BYTE coefficient[] = {...}; 961 CK_BBOOL true = CK_TRUE; 962 CK_ATTRIBUTE template[] = { 963 {CKA_CLASS, &class, sizeof(class)}, 964 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 965 {CKA_TOKEN, &true, sizeof(true)}, 966 {CKA_LABEL, label, sizeof(label)-1}, 967 {CKA_SUBJECT, subject, sizeof(subject)}, 968 {CKA_ID, id, sizeof(id)}, 969 {CKA_SENSITIVE, &true, sizeof(true)}, 970 {CKA_DECRYPT, &true, sizeof(true)}, 971 {CKA_SIGN, &true, sizeof(true)}, 972 {CKA_MODULUS, modulus, sizeof(modulus)}, 973 {CKA_PUBLIC_EXPONENT, publicExponent, 974 sizeof(publicExponent)}, 975 {CKA_PRIVATE_EXPONENT, privateExponent, 976 sizeof(privateExponent)}, 977 {CKA_PRIME_1, prime1, sizeof(prime1)}, 978 {CKA_PRIME_2, prime2, sizeof(prime2)}, 979 {CKA_EXPONENT_1, exponent1, sizeof(exponent1)}, 980 {CKA_EXPONENT_2, exponent2, sizeof(exponent2)}, 981 {CKA_COEFFICIENT, coefficient, sizeof(coefficient)} 982 };
983 2.1.4 PKCS #1 RSA key pair generation 984 The PKCS #1 RSA key pair generation mechanism, denoted CKM_RSA_PKCS_KEY_PAIR_GEN, is a 985 key pair generation mechanism based on the RSA public-key cryptosystem, as defined in PKCS #1. 986 It does not have a parameter. 987 The mechanism generates RSA public/private key pairs with a particular modulus length in bits and public 988 exponent, as specified in the CKA_MODULUS_BITS and CKA_PUBLIC_EXPONENT attributes of the 989 template for the public key. The CKA_PUBLIC_EXPONENT may be omitted in which case the 990 mechanism shall supply the public exponent attribute using the default value of 0x10001 (65537). 991 Specific implementations may use a random value or an alternative default if 0x10001 cannot be used by 992 the token. 993 Note: Implementations strictly compliant with version 2.11 or prior versions may generate an error 994 if this attribute is omitted from the template. Experience has shown that many implementations of 2.11 995 and prior did allow the CKA_PUBLIC_EXPONENT attribute to be omitted from the template, and 996 behaved as described above. The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, 997 CKA_MODULUS, and CKA_PUBLIC_EXPONENT attributes to the new public key. 998 CKA_PUBLIC_EXPONENT will be copied from the template if supplied. 999 CKR_TEMPLATE_INCONSISTENT shall be returned if the implementation cannot use the supplied 1000 exponent value. It contributes the CKA_CLASS and CKA_KEY_TYPE attributes to the new private key; it 1001 may also contribute some of the following attributes to the new private key: CKA_MODULUS, 1002 CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, 1003 CKA_EXPONENT_1, CKA_EXPONENT_2, CKA_COEFFICIENT. Other attributes supported by the
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 24 of 278 1004 RSA public and private key types (specifically, the flags indicating which functions the keys support) may 1005 also be specified in the templates for the keys, or else are assigned default initial values. 1006 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1007 specify the supported range of RSA modulus sizes, in bits.
1008 2.1.5 X9.31 RSA key pair generation 1009 The X9.31 RSA key pair generation mechanism, denoted CKM_RSA_X9_31_KEY_PAIR_GEN, is a key 1010 pair generation mechanism based on the RSA public-key cryptosystem, as defined in X9.31. 1011 It does not have a parameter. 1012 The mechanism generates RSA public/private key pairs with a particular modulus length in bits and public 1013 exponent, as specified in the CKA_MODULUS_BITS and CKA_PUBLIC_EXPONENT attributes of the 1014 template for the public key. 1015 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_MODULUS, and 1016 CKA_PUBLIC_EXPONENT attributes to the new public key. It contributes the CKA_CLASS and 1017 CKA_KEY_TYPE attributes to the new private key; it may also contribute some of the following attributes 1018 to the new private key: CKA_MODULUS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, 1019 CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT_2, CKA_COEFFICIENT. 1020 Other attributes supported by the RSA public and private key types (specifically, the flags indicating which 1021 functions the keys support) may also be specified in the templates for the keys, or else are assigned 1022 default initial values. Unlike the CKM_RSA_PKCS_KEY_PAIR_GEN mechanism, this mechanism is 1023 guaranteed to generate p and q values, CKA_PRIME_1 and CKA_PRIME_2 respectively, that meet the 1024 strong primes requirement of X9.31. 1025 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1026 specify the supported range of RSA modulus sizes, in bits.
1027 2.1.6 PKCS #1 v1.5 RSA 1028 The PKCS #1 v1.5 RSA mechanism, denoted CKM_RSA_PKCS, is a multi-purpose mechanism based 1029 on the RSA public-key cryptosystem and the block formats initially defined in PKCS #1 v1.5. It supports 1030 single-part encryption and decryption; single-part signatures and verification with and without message 1031 recovery; key wrapping; and key unwrapping. This mechanism corresponds only to the part of PKCS #1 1032 v1.5 that involves RSA; it does not compute a message digest or a DigestInfo encoding as specified for 1033 the md2withRSAEncryption and md5withRSAEncryption algorithms in PKCS #1 v1.5 . 1034 This mechanism does not have a parameter. 1035 This mechanism can wrap and unwrap any secret key of appropriate length. Of course, a particular token 1036 may not be able to wrap/unwrap every appropriate-length secret key that it supports. For wrapping, the 1037 “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; 1038 similarly for unwrapping. The mechanism does not wrap the key type or any other information about the 1039 key, except the key length; the application must convey these separately. In particular, the mechanism 1040 contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes 1041 to the recovered key during unwrapping; other attributes must be specified in the template. 1042 Constraints on key types and the length of the data are summarized in the following table. For 1043 encryption, decryption, signatures and signature verification, the input and output data may begin at the 1044 same location in memory. In the table, k is the length in bytes of the RSA modulus. 1045 Table 4, PKCS #1 v1.5 RSA: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 25 of 278 Function Key type Input Output Comments length length C_Encrypt1 RSA public key k-11 k block type 02 C_Decrypt1 RSA private key k k-11 block type 02 C_Sign1 RSA private key k-11 k block type 01 C_SignRecover RSA private key k-11 k block type 01 C_Verify1 RSA public key k-11, k2 N/A block type 01 C_VerifyRecover RSA public key k k-11 block type 01 C_WrapKey RSA public key k-11 k block type 02 C_UnwrapKey RSA private key k k-11 block type 02 1046 1 Single-part operations only. 1047 2 Data length, signature length. 1048 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1049 specify the supported range of RSA modulus sizes, in bits.
1050 2.1.7 PKCS #1 RSA OAEP mechanism parameters
1051 CK_RSA_PKCS_MGF_TYPE; CK_RSA_PKCS_MGF_TYPE_PTR
1052 CK_RSA_PKCS_MGF_TYPE is used to indicate the Message Generation Function (MGF) applied to a 1053 message block when formatting a message block for the PKCS #1 OAEP encryption scheme or the 1054 PKCS #1 PSS signature scheme. It is defined as follows: 1055 typedef CK_ULONG CK_RSA_PKCS_MGF_TYPE; 1056 1057 The following MGFs are defined in PKCS #1. The following table lists the defined functions. 1058 Table 5, PKCS #1 Mask Generation Functions Source Identifier Value CKG_MGF1_SHA1 0x00000001UL CKG_MGF1_SHA224 0x00000005UL CKG_MGF1_SHA256 0x00000002UL CKG_MGF1_SHA384 0x00000003UL CKG_MGF1_SHA512 0x00000004UL CKG_MGF1_SHA3_224 0x00000006UL CKG_MGF1_SHA3_256 0x00000007UL CKG_MGF1_SHA3_384 0x00000008UL CKG_MGF1_SHA3_512 0x00000009UL 1059 CK_RSA_PKCS_MGF_TYPE_PTR is a pointer to a CK_RSA_PKCS_ MGF_TYPE.
1060 CK_RSA_PKCS_OAEP_SOURCE_TYPE; 1061 CK_RSA_PKCS_OAEP_SOURCE_TYPE_PTR
1062 CK_RSA_PKCS_OAEP_SOURCE_TYPE is used to indicate the source of the encoding parameter 1063 when formatting a message block for the PKCS #1 OAEP encryption scheme. It is defined as follows: 1064 typedef CK_ULONG CK_RSA_PKCS_OAEP_SOURCE_TYPE; 1065
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 26 of 278 1066 The following encoding parameter sources are defined in PKCS #1. The following table lists the defined 1067 sources along with the corresponding data type for the pSourceData field in the 1068 CK_RSA_PKCS_OAEP_PARAMS structure defined below. 1069 Table 6, PKCS #1 RSA OAEP: Encoding parameter sources Source Identifier Value Data Type CKZ_DATA_SPECIFIED 0x00000001UL Array of CK_BYTE containing the value of the encoding parameter. If the parameter is empty, pSourceData must be NULL and ulSourceDataLen must be zero. 1070 CK_RSA_PKCS_OAEP_SOURCE_TYPE_PTR is a pointer to a 1071 CK_RSA_PKCS_OAEP_SOURCE_TYPE.
1072 CK_RSA_PKCS_OAEP_PARAMS; CK_RSA_PKCS_OAEP_PARAMS_PTR
1073 CK_RSA_PKCS_OAEP_PARAMS is a structure that provides the parameters to the 1074 CKM_RSA_PKCS_OAEP mechanism. The structure is defined as follows: 1075 typedef struct CK_RSA_PKCS_OAEP_PARAMS { 1076 CK_MECHANISM_TYPE hashAlg; 1077 CK_RSA_PKCS_MGF_TYPE mgf; 1078 CK_RSA_PKCS_OAEP_SOURCE_TYPE source; 1079 CK_VOID_PTR pSourceData; 1080 CK_ULONG ulSourceDataLen; 1081 } CK_RSA_PKCS_OAEP_PARAMS; 1082 1083 The fields of the structure have the following meanings: 1084 hashAlg mechanism ID of the message digest algorithm used to calculate 1085 the digest of the encoding parameter
1086 mgf mask generation function to use on the encoded block
1087 source source of the encoding parameter
1088 pSourceData data used as the input for the encoding parameter source
1089 ulSourceDataLen length of the encoding parameter source input
1090 CK_RSA_PKCS_OAEP_PARAMS_PTR is a pointer to a CK_RSA_PKCS_OAEP_PARAMS. 1091 Table 7, Add to following to table 7 ( PKCS #1 Mask Generation Functions) in section 2,1..7 (PKCS #1 1092 RSA OAEP mechanism parameters) Source Identifier Value CKG_MGF1_SHA3_224 0x00000006UL CKG_MGF1_SHA3_256 0x00000007UL CKG_MGF1_SHA3_384 0x00000008UL CKG_MGF1_SHA3_512 0x00000009UL 1093
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 27 of 278 1094 2.1.8 PKCS #1 RSA OAEP 1095 The PKCS #1 RSA OAEP mechanism, denoted CKM_RSA_PKCS_OAEP, is a multi-purpose 1096 mechanism based on the RSA public-key cryptosystem and the OAEP block format defined in PKCS #1. 1097 It supports single-part encryption and decryption; key wrapping; and key unwrapping. 1098 It has a parameter, a CK_RSA_PKCS_OAEP_PARAMS structure. 1099 This mechanism can wrap and unwrap any secret key of appropriate length. Of course, a particular token 1100 may not be able to wrap/unwrap every appropriate-length secret key that it supports. For wrapping, the 1101 “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; 1102 similarly for unwrapping. The mechanism does not wrap the key type or any other information about the 1103 key, except the key length; the application must convey these separately. In particular, the mechanism 1104 contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes 1105 to the recovered key during unwrapping; other attributes must be specified in the template. 1106 Constraints on key types and the length of the data are summarized in the following table. For encryption 1107 and decryption, the input and output data may begin at the same location in memory. In the table, k is the 1108 length in bytes of the RSA modulus, and hLen is the output length of the message digest algorithm 1109 specified by the hashAlg field of the CK_RSA_PKCS_OAEP_PARAMS structure. 1110 Table 8, PKCS #1 RSA OAEP: Key And Data Length Function Key type Input length Output length C_Encrypt1 RSA public key k-2-2hLen k C_Decrypt1 RSA private key k k-2-2hLen C_WrapKey RSA public key k-2-2hLen k C_UnwrapKey RSA private key k k-2-2hLen 1111 1 Single-part operations only. 1112 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1113 specify the supported range of RSA modulus sizes, in bits.
1114 2.1.9 PKCS #1 RSA PSS mechanism parameters
1115 CK_RSA_PKCS_PSS_PARAMS; CK_RSA_PKCS_PSS_PARAMS_PTR
1116 CK_RSA_PKCS_PSS_PARAMS is a structure that provides the parameters to the 1117 CKM_RSA_PKCS_PSS mechanism. The structure is defined as follows: 1118 typedef struct CK_RSA_PKCS_PSS_PARAMS { 1119 CK_MECHANISM_TYPE hashAlg; 1120 CK_RSA_PKCS_MGF_TYPE mgf; 1121 CK_ULONG sLen; 1122 } CK_RSA_PKCS_PSS_PARAMS; 1123 1124 The fields of the structure have the following meanings: 1125 hashAlg hash algorithm used in the PSS encoding; if the signature 1126 mechanism does not include message hashing, then this value must 1127 be the mechanism used by the application to generate the message 1128 hash; if the signature mechanism includes hashing, then this value 1129 must match the hash algorithm indicated by the signature 1130 mechanism
1131 mgf mask generation function to use on the encoded block
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 28 of 278 1132 sLen length, in bytes, of the salt value used in the PSS encoding; typical 1133 values are the length of the message hash and zero
1134 CK_RSA_PKCS_PSS_PARAMS_PTR is a pointer to a CK_RSA_PKCS_PSS_PARAMS.
1135 2.1.10 PKCS #1 RSA PSS 1136 The PKCS #1 RSA PSS mechanism, denoted CKM_RSA_PKCS_PSS, is a mechanism based on the 1137 RSA public-key cryptosystem and the PSS block format defined in PKCS #1. It supports single-part 1138 signature generation and verification without message recovery. This mechanism corresponds only to the 1139 part of PKCS #1 that involves block formatting and RSA, given a hash value; it does not compute a hash 1140 value on the message to be signed. 1141 It has a parameter, a CK_RSA_PKCS_PSS_PARAMS structure. The sLen field must be less than or 1142 equal to k*-2-hLen and hLen is the length of the input to the C_Sign or C_Verify function. k* is the length 1143 in bytes of the RSA modulus, except if the length in bits of the RSA modulus is one more than a multiple 1144 of 8, in which case k* is one less than the length in bytes of the RSA modulus. 1145 Constraints on key types and the length of the data are summarized in the following table. In the table, k 1146 is the length in bytes of the RSA. 1147 Table 9, PKCS #1 RSA PSS: Key And Data Length Function Key type Input length Output length C_Sign1 RSA private key hLen k C_Verify1 RSA public key hLen, k N/A 1148 1 Single-part operations only. 1149 2 Data length, signature length. 1150 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1151 specify the supported range of RSA modulus sizes, in bits.
1152 2.1.11 ISO/IEC 9796 RSA 1153 The ISO/IEC 9796 RSA mechanism, denoted CKM_RSA_9796, is a mechanism for single-part 1154 signatures and verification with and without message recovery based on the RSA public-key 1155 cryptosystem and the block formats defined in ISO/IEC 9796 and its annex A. 1156 This mechanism processes only byte strings, whereas ISO/IEC 9796 operates on bit strings. Accordingly, 1157 the following transformations are performed: 1158 Data is converted between byte and bit string formats by interpreting the most-significant bit of the 1159 leading byte of the byte string as the leftmost bit of the bit string, and the least-significant bit of the 1160 trailing byte of the byte string as the rightmost bit of the bit string (this assumes the length in bits of 1161 the data is a multiple of 8). 1162 A signature is converted from a bit string to a byte string by padding the bit string on the left with 0 to 1163 7 zero bits so that the resulting length in bits is a multiple of 8, and converting the resulting bit string 1164 as above; it is converted from a byte string to a bit string by converting the byte string as above, and 1165 removing bits from the left so that the resulting length in bits is the same as that of the RSA modulus. 1166 This mechanism does not have a parameter. 1167 Constraints on key types and the length of input and output data are summarized in the following table. 1168 In the table, k is the length in bytes of the RSA modulus. 1169 Table 10, ISO/IEC 9796 RSA: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 29 of 278 Function Key type Input Output length length C_Sign1 RSA private key k/2 k C_SignRecover RSA private key k/2 k C_Verify1 RSA public key k/2, k2 N/A C_VerifyRecover RSA public key k k/2 1170 1 Single-part operations only. 1171 2 Data length, signature length. 1172 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1173 specify the supported range of RSA modulus sizes, in bits.
1174 2.1.12 X.509 (raw) RSA 1175 The X.509 (raw) RSA mechanism, denoted CKM_RSA_X_509, is a multi-purpose mechanism based on 1176 the RSA public-key cryptosystem. It supports single-part encryption and decryption; single-part signatures 1177 and verification with and without message recovery; key wrapping; and key unwrapping. All these 1178 operations are based on so-called “raw” RSA, as assumed in X.509. 1179 “Raw” RSA as defined here encrypts a byte string by converting it to an integer, most-significant byte first, 1180 applying “raw” RSA exponentiation, and converting the result to a byte string, most-significant byte first. 1181 The input string, considered as an integer, must be less than the modulus; the output string is also less 1182 than the modulus. 1183 This mechanism does not have a parameter. 1184 This mechanism can wrap and unwrap any secret key of appropriate length. Of course, a particular token 1185 may not be able to wrap/unwrap every appropriate-length secret key that it supports. For wrapping, the 1186 “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; 1187 similarly for unwrapping. The mechanism does not wrap the key type, key length, or any other 1188 information about the key; the application must convey these separately, and supply them when 1189 unwrapping the key. 1190 Unfortunately, X.509 does not specify how to perform padding for RSA encryption. For this mechanism, 1191 padding should be performed by prepending plaintext data with 0-valued bytes. In effect, to encrypt the n-1 n-2 1192 sequence of plaintext bytes b1 b2 … bn (n k), Cryptoki forms P=2 b1+2 b2+…+bn. This number must 1193 be less than the RSA modulus. The k-byte ciphertext (k is the length in bytes of the RSA modulus) is 1194 produced by raising P to the RSA public exponent modulo the RSA modulus. Decryption of a k-byte 1195 ciphertext C is accomplished by raising C to the RSA private exponent modulo the RSA modulus, and 1196 returning the resulting value as a sequence of exactly k bytes. If the resulting plaintext is to be used to 1197 produce an unwrapped key, then however many bytes are specified in the template for the length of the 1198 key are taken from the end of this sequence of bytes. 1199 Technically, the above procedures may differ very slightly from certain details of what is specified in 1200 X.509. 1201 Executing cryptographic operations using this mechanism can result in the error returns 1202 CKR_DATA_INVALID (if plaintext is supplied which has the same length as the RSA modulus and is 1203 numerically at least as large as the modulus) and CKR_ENCRYPTED_DATA_INVALID (if ciphertext is 1204 supplied which has the same length as the RSA modulus and is numerically at least as large as the 1205 modulus). 1206 Constraints on key types and the length of input and output data are summarized in the following table. 1207 In the table, k is the length in bytes of the RSA modulus. 1208 Table 11, X.509 (Raw) RSA: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 30 of 278 Function Key type Input Output length length C_Encrypt1 RSA public key k k C_Decrypt1 RSA private key k k C_Sign1 RSA private key k k C_SignRecover RSA private key k k C_Verify1 RSA public key k, k2 N/A C_VerifyRecover RSA public key k k C_WrapKey RSA public key k k C_UnwrapKey RSA private key k k (specified in template) 1209 1 Single-part operations only. 1210 2 Data length, signature length. 1211 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1212 specify the supported range of RSA modulus sizes, in bits. 1213 This mechanism is intended for compatibility with applications that do not follow the PKCS #1 or ISO/IEC 1214 9796 block formats.
1215 2.1.13 ANSI X9.31 RSA 1216 The ANSI X9.31 RSA mechanism, denoted CKM_RSA_X9_31, is a mechanism for single-part signatures 1217 and verification without message recovery based on the RSA public-key cryptosystem and the block 1218 formats defined in ANSI X9.31. 1219 This mechanism applies the header and padding fields of the hash encapsulation. The trailer field must 1220 be applied by the application. 1221 This mechanism processes only byte strings, whereas ANSI X9.31 operates on bit strings. Accordingly, 1222 the following transformations are performed: 1223 Data is converted between byte and bit string formats by interpreting the most-significant bit of the 1224 leading byte of the byte string as the leftmost bit of the bit string, and the least-significant bit of the 1225 trailing byte of the byte string as the rightmost bit of the bit string (this assumes the length in bits of 1226 the data is a multiple of 8). 1227 A signature is converted from a bit string to a byte string by padding the bit string on the left with 0 to 1228 7 zero bits so that the resulting length in bits is a multiple of 8, and converting the resulting bit string 1229 as above; it is converted from a byte string to a bit string by converting the byte string as above, and 1230 removing bits from the left so that the resulting length in bits is the same as that of the RSA modulus. 1231 This mechanism does not have a parameter. 1232 Constraints on key types and the length of input and output data are summarized in the following table. 1233 In the table, k is the length in bytes of the RSA modulus. For all operations, the k value must be at least 1234 128 and a multiple of 32 as specified in ANSI X9.31. 1235 Table 12, ANSI X9.31 RSA: Key And Data Length Function Key type Input Output length length C_Sign1 RSA private key k-2 k C_Verify1 RSA public key k-2, k2 N/A 1236 1 Single-part operations only. 1237 2 Data length, signature length. 1238 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1239 specify the supported range of RSA modulus sizes, in bits.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 31 of 278 1240 2.1.14 PKCS #1 v1.5 RSA signature with MD2, MD5, SHA-1, SHA-256, SHA- 1241 384, SHA-512, RIPE-MD 128 or RIPE-MD 160 1242 The PKCS #1 v1.5 RSA signature with MD2 mechanism, denoted CKM_MD2_RSA_PKCS, performs 1243 single- and multiple-part digital signatures and verification operations without message recovery. The 1244 operations performed are as described initially in PKCS #1 v1.5 with the object identifier 1245 md2WithRSAEncryption, and as in the scheme RSASSA-PKCS1-v1_5 in the current version of PKCS #1, 1246 where the underlying hash function is MD2. 1247 Similarly, the PKCS #1 v1.5 RSA signature with MD5 mechanism, denoted CKM_MD5_RSA_PKCS, 1248 performs the same operations described in PKCS #1 with the object identifier md5WithRSAEncryption. 1249 The PKCS #1 v1.5 RSA signature with SHA-1 mechanism, denoted CKM_SHA1_RSA_PKCS, performs 1250 the same operations, except that it uses the hash function SHA-1 with object identifier 1251 sha1WithRSAEncryption. 1252 Likewise, the PKCS #1 v1.5 RSA signature with SHA-256, SHA-384, and SHA-512 mechanisms, denoted 1253 CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, and CKM_SHA512_RSA_PKCS respectively, 1254 perform the same operations using the SHA-256, SHA-384 and SHA-512 hash functions with the object 1255 identifiers sha256WithRSAEncryption, sha384WithRSAEncryption and sha512WithRSAEncryption 1256 respectively. 1257 The PKCS #1 v1.5 RSA signature with RIPEMD-128 or RIPEMD-160, denoted 1258 CKM_RIPEMD128_RSA_PKCS and CKM_RIPEMD160_RSA_PKCS respectively, perform the same 1259 operations using the RIPE-MD 128 and RIPE-MD 160 hash functions. 1260 None of these mechanisms has a parameter. 1261 Constraints on key types and the length of the data for these mechanisms are summarized in the 1262 following table. In the table, k is the length in bytes of the RSA modulus. For the PKCS #1 v1.5 RSA 1263 signature with MD2 and PKCS #1 v1.5 RSA signature with MD5 mechanisms, k must be at least 27; for 1264 the PKCS #1 v1.5 RSA signature with SHA-1 mechanism, k must be at least 31, and so on for other 1265 underlying hash functions, where the minimum is always 11 bytes more than the length of the hash value. 1266 Table 13, PKCS #1 v1.5 RSA Signatures with Various Hash Functions: Key And Data Length Function Key type Input length Output length Comments C_Sign RSA private key any k block type 01 C_Verify RSA public key any, k2 N/A block type 01 1267 2 Data length, signature length. 1268 For these mechanisms, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO 1269 structure specify the supported range of RSA modulus sizes, in bits.
1270 2.1.15 PKCS #1 v1.5 RSA signature with SHA-224 1271 The PKCS #1 v1.5 RSA signature with SHA-224 mechanism, denoted CKM_SHA224_RSA_PKCS, 1272 performs similarly as the other CKM_SHAX_RSA_PKCS mechanisms but uses the SHA-224 hash 1273 function.
1274 2.1.16 PKCS #1 RSA PSS signature with SHA-224 1275 The PKCS #1 RSA PSS signature with SHA-224 mechanism, denoted CKM_SHA224_RSA_PKCS_PSS, 1276 performs similarly as the other CKM_SHAX_RSA_PSS mechanisms but uses the SHA-224 hash 1277 function.
1278 2.1.17 PKCS #1 RSA PSS signature with SHA-1, SHA-256, SHA-384 or SHA- 1279 512 1280 The PKCS #1 RSA PSS signature with SHA-1 mechanism, denoted CKM_SHA1_RSA_PKCS_PSS, 1281 performs single- and multiple-part digital signatures and verification operations without message
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 32 of 278 1282 recovery. The operations performed are as described in PKCS #1 with the object identifier id-RSASSA- 1283 PSS, i.e., as in the scheme RSASSA-PSS in PKCS #1 where the underlying hash function is SHA-1. 1284 The PKCS #1 RSA PSS signature with SHA-256, SHA-384, and SHA-512 mechanisms, denoted 1285 CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, and 1286 CKM_SHA512_RSA_PKCS_PSS respectively, perform the same operations using the SHA-256, SHA- 1287 384 and SHA-512 hash functions. 1288 The mechanisms have a parameter, a CK_RSA_PKCS_PSS_PARAMS structure. The sLen field must 1289 be less than or equal to k*-2-hLen where hLen is the length in bytes of the hash value. k* is the length in 1290 bytes of the RSA modulus, except if the length in bits of the RSA modulus is one more than a multiple of 1291 8, in which case k* is one less than the length in bytes of the RSA modulus. 1292 Constraints on key types and the length of the data are summarized in the following table. In the table, k 1293 is the length in bytes of the RSA modulus. 1294 Table 14, PKCS #1 RSA PSS Signatures with Various Hash Functions: Key And Data Length Function Key type Input length Output length C_Sign RSA private key any k C_Verify RSA public key any, k2 N/A 1295 2 Data length, signature length. 1296 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1297 specify the supported range of RSA modulus sizes, in bits.
1298 2.1.18 PKCS #1 v1.5 RSA signature with SHA3 1299 The PKCS #1 v1.5 RSA signature with SHA3-224, SHA3-256, SHA3-384, SHA3-512 mechanisms, 1300 denoted CKM_SHA3_224_RSA_PKCS, CKM_SHA3_256_RSA_PKCS, CKM_SHA3_384_RSA_PKCS, 1301 and CKM_SHA3_512_RSA_PKCS respectively, performs similarly as the other 1302 CKM_SHAX_RSA_PKCS mechanisms but uses the corresponding SHA3 hash functions.
1303 2.1.19 PKCS #1 RSA PSS signature with SHA3 1304 The PKCS #1 RSA PSS signature with SHA3-224, SHA3-256, SHA3-384, SHA3-512 mechanisms, 1305 denoted CKM_SHA3_224_RSA_PSS, CKM_SHA3_256_RSA_PSS, CKM_SHA3_384_RSA_PSS, and 1306 CKM_SHA3_512_RSA_PSS respectively, performs similarly as the other CKM_SHAX_RSA_PSS 1307 mechanisms but uses the corresponding SHA-3 hash functions.
1308 2.1.20 ANSI X9.31 RSA signature with SHA-1 1309 The ANSI X9.31 RSA signature with SHA-1 mechanism, denoted CKM_SHA1_RSA_X9_31, performs 1310 single- and multiple-part digital signatures and verification operations without message recovery. The 1311 operations performed are as described in ANSI X9.31. 1312 This mechanism does not have a parameter. 1313 Constraints on key types and the length of the data for these mechanisms are summarized in the 1314 following table. In the table, k is the length in bytes of the RSA modulus. For all operations, the k value 1315 must be at least 128 and a multiple of 32 as specified in ANSI X9.31. 1316 Table 15, ANSI X9.31 RSA Signatures with SHA-1: Key And Data Length Function Key type Input length Output length C_Sign RSA private key any k C_Verify RSA public key any, k2 N/A 1317 2 Data length, signature length. 1318 For these mechanisms, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO 1319 structure specify the supported range of RSA modulus sizes, in bits.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 33 of 278 1320 2.1.21 TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA 1321 The TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA mechanism, denoted CKM_RSA_PKCS_TPM_1_1, is a 1322 multi-use mechanism based on the RSA public-key cryptosystem and the block formats initially defined in 1323 PKCS #1 v1.5, with additional formatting rules defined in TCPA TPM Specification Version 1.1b. 1324 Additional formatting rules remained the same in TCG TPM Specification 1.2 The mechanism supports 1325 single-part encryption and decryption; key wrapping; and key unwrapping. 1326 This mechanism does not have a parameter. It differs from the standard PKCS#1 v1.5 RSA encryption 1327 mechanism in that the plaintext is wrapped in a TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1328 1.2) structure before being submitted to the PKCS#1 v1.5 encryption process. On encryption, the version 1329 field of the TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1.2) structure must contain 0x01, 0x01, 1330 0x00, 0x00. On decryption, any structure of the form 0x01, 0x01, 0xXX, 0xYY may be accepted. 1331 This mechanism can wrap and unwrap any secret key of appropriate length. Of course, a particular token 1332 may not be able to wrap/unwrap every appropriate-length secret key that it supports. For wrapping, the 1333 “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; 1334 similarly for unwrapping. The mechanism does not wrap the key type or any other information about the 1335 key, except the key length; the application must convey these separately. In particular, the mechanism 1336 contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes 1337 to the recovered key during unwrapping; other attributes must be specified in the template. 1338 Constraints on key types and the length of the data are summarized in the following table. For encryption 1339 and decryption, the input and output data may begin at the same location in memory. In the table, k is the 1340 length in bytes of the RSA modulus. 1341 Table 16, TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA: Key And Data Length Function Key type Input Output length length C_Encrypt1 RSA public key k-11-5 k C_Decrypt1 RSA private key k k-11-5 C_WrapKey RSA public key k-11-5 k C_UnwrapKey RSA private key k k-11-5 1342 1 Single-part operations only. 1343 1344 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1345 specify the supported range of RSA modulus sizes, in bits.
1346 2.1.22 TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP 1347 The TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP mechanism, denoted 1348 CKM_RSA_PKCS_OAEP_TPM_1_1, is a multi-purpose mechanism based on the RSA public-key 1349 cryptosystem and the OAEP block format defined in PKCS #1, with additional formatting defined in TCPA 1350 TPM Specification Version 1.1b. Additional formatting rules remained the same in TCG TPM 1351 Specification 1.2. The mechanism supports single-part encryption and decryption; key wrapping; and key 1352 unwrapping. 1353 This mechanism does not have a parameter. It differs from the standard PKCS#1 OAEP RSA encryption 1354 mechanism in that the plaintext is wrapped in a TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1355 1.2) structure before being submitted to the encryption process and that all of the values of the 1356 parameters that are passed to a standard CKM_RSA_PKCS_OAEP operation are fixed. On encryption, 1357 the version field of the TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1.2) structure must contain 1358 0x01, 0x01, 0x00, 0x00. On decryption, any structure of the form 0x01, 0x01, 0xXX, 0xYY may be 1359 accepted. 1360 This mechanism can wrap and unwrap any secret key of appropriate length. Of course, a particular token 1361 may not be able to wrap/unwrap every appropriate-length secret key that it supports. For wrapping, the 1362 “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 34 of 278 1363 similarly for unwrapping. The mechanism does not wrap the key type or any other information about the 1364 key, except the key length; the application must convey these separately. In particular, the mechanism 1365 contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes 1366 to the recovered key during unwrapping; other attributes must be specified in the template. 1367 Constraints on key types and the length of the data are summarized in the following table. For encryption 1368 and decryption, the input and output data may begin at the same location in memory. In the table, k is the 1369 length in bytes of the RSA modulus. 1370 Table 17, TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP: Key And Data Length Function Key type Input length Output length C_Encrypt1 RSA public key k-2-40-5 k C_Decrypt1 RSA private key k k-2-40-5 C_WrapKey RSA public key k-2-40-5 k C_UnwrapKey RSA private key k k-2-40-5 1371 1 Single-part operations only. 1372 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1373 specify the supported range of RSA modulus sizes, in bits.
1374 2.1.23 RSA AES KEY WRAP 1375 The RSA AES key wrap mechanism, denoted CKM_RSA_AES_KEY_WRAP, is a mechanism based on 1376 the RSA public-key cryptosystem and the AES key wrap mechanism. It supports single-part key 1377 wrapping; and key unwrapping. 1378 It has a parameter, a CK_RSA_AES_KEY_WRAP_PARAMS structure. 1379 The mechanism can wrap and unwrap a target asymmetric key of any length and type using an RSA key. 1380 - A temporary AES key is used for wrapping the target key using 1381 CKM_AES_KEY_WRAP_KWP mechanism. 1382 - The temporary AES key is wrapped with the wrapping RSA key using 1383 CKM_RSA_PKCS_OAEP mechanism. 1384 1385 For wrapping, the mechanism - 1386 Generates a temporary random AES key of ulAESKeyBits length. This key is not accessible to the 1387 user - no handle is returned. 1388 Wraps the AES key with the wrapping RSA key using CKM_RSA_PKCS_OAEP with parameters 1389 of OAEPParams. 1390 Wraps the target key with the temporary AES key using CKM_AES_KEY_WRAP_KWP ([AES 1391 KEYWRAP] section 6.3). 1392 Zeroizes the temporary AES key 1393 Concatenates two wrapped keys and outputs the concatenated blob. The first is the wrapped AES 1394 key, and the second is the wrapped target key. 1395 1396 The recommended format for an asymmetric target key being wrapped is as a PKCS8 PrivateKeyInfo 1397 1398 The use of Attributes in the PrivateKeyInfo structure is OPTIONAL. In case of conflicts between the 1399 object attribute template, and Attributes in the PrivateKeyInfo structure, an error should be thrown 1400 1401 For unwrapping, the mechanism - 1402 Splits the input into two parts. The first is the wrapped AES key, and the second is the wrapped 1403 target key. The length of the first part is equal to the length of the unwrapping RSA key.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 35 of 278 1404 Un-wraps the temporary AES key from the first part with the private RSA key using 1405 CKM_RSA_PKCS_OAEP with parameters of OAEPParams. 1406 Un-wraps the target key from the second part with the temporary AES key using 1407 CKM_AES_KEY_WRAP_KWP ([AES KEYWRAP] section 6.3). 1408 Zeroizes the temporary AES key. 1409 Returns the handle to the newly unwrapped target key. 1410 Table 18, CKM_RSA_AES_KEY_WRAP Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive
Decrypt Verify VR1 Key Unwrap Pair CKM_RSA_AES_KEY_WRAP
1SR = SignRecover, VR = VerifyRecover
1411 2.1.24 RSA AES KEY WRAP mechanism parameters
1412 CK_RSA_AES_KEY_WRAP_PARAMS; CK_RSA_AES_KEY_WRAP_PARAMS_PTR
1413 CK_RSA_AES_KEY_WRAP_PARAMS is a structure that provides the parameters to the 1414 CKM_RSA_AES_KEY_WRAP mechanism. It is defined as follows: 1415 typedef struct CK_RSA_AES_KEY_WRAP_PARAMS { 1416 CK_ULONG ulAESKeyBits; 1417 CK_RSA_PKCS_OAEP_PARAMS_PTR pOAEPParams; 1418 } CK_RSA_AES_KEY_WRAP_PARAMS;
1419
1420 The fields of the structure have the following meanings: 1421 ulAESKeyBits length of the temporary AES key in bits. Can be only 128, 192 or 1422 256.
1423 pOAEPParams pointer to the parameters of the temporary AES key wrapping. See 1424 also the description of PKCS #1 RSA OAEP mechanism 1425 parameters.
1426 CK_RSA_AES_KEY_WRAP_PARAMS_PTR is a pointer to a CK_RSA_AES_KEY_WRAP_PARAMS.
1427 2.1.25 FIPS 186-4 1428 When CKM_RSA_PKCS is operated in FIPS mode, the length of the modulus SHALL only be 1024, 1429 2048, or 3072 bits.
1430 2.2 DSA 1431 Table 19, DSA Mechanisms vs. Functions
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 36 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verif VR1 Key Unwrap y Pair CKM_DSA_KEY_PAIR_GEN CKM_DSA_PARAMETER_GEN CKM_DSA_PROBABALISTIC_P ARAMETER_GEN CKM_DSA_SHAWE_TAYLOR_ PARAMETER_GEN CKM_DSA_FIPS_G_GEN CKM_DSA 2 CKM_DSA_SHA1 CKM_DSA_SHA224 CKM_DSA_SHA256 CKM_DSA_SHA384 CKM_DSA_SHA512 CKM_DSA_SHA3_224 CKM_DSA_SHA3_256 CKM_DSA_SHA3_384 CKM_DSA_SHA3_512
1432 2.2.1 Definitions 1433 This section defines the key type “CKK_DSA” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE 1434 attribute of DSA key objects. 1435 Mechanisms: 1436 CKM_DSA_KEY_PAIR_GEN 1437 CKM_DSA 1438 CKM_DSA_SHA1 1439 CKM_DSA_SHA224 1440 CKM_DSA_SHA256 1441 CKM_DSA_SHA384 1442 CKM_DSA_SHA512 1443 CKM_DSA_SHA3_224 1444 CKM_DSA_SHA3_256 1445 CKM_DSA_SHA3_384 1446 CKM_DSA_SHA3_512 1447 CKM_DSA_PARAMETER_GEN 1448 CKM_DSA_PROBABLISTIC_PARAMETER_GEN 1449 CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN 1450 CKM_DSA_FIPS_G_GEN 1451
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 37 of 278 1452 CK_DSA_PARAMETER_GEN_PARAM
1453 CK_DSA_PARAMETER_GEN_PARAM is a structure which provides and returns parameters for the 1454 NIST FIPS 186-4 parameter generating algorithms. 1455 1456 typedef struct CK_DSA_PARAMETER_GEN_PARAM { 1457 CK_MECHANISM_TYPE hash; 1458 CK_BYTE_PTR pSeed; 1459 CK_ULONG ulSeedLen; 1460 CK_ULONG ulIndex; 1461 } CK_DSA_PARAMETER_GEN_PARAM; 1462 1463 The fields of the structure have the following meanings: 1464 hash Mechanism value for the base hash used in PQG generation, Valid 1465 values are CKM_SHA1, CKM_SHA224, CKM_SHA256, 1466 CKM_SHA384, CKM_SHA512.
1467 pSeed Seed value used to generate PQ and G. This value is returned by 1468 CKM_DSA_PROBABLISTIC_PARAMETER_GEN, 1469 CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN, and passed 1470 into CKM_DSA_FIPS_G_GEN.
1471 ulSeedLen Length of seed value.
1472 ulIndex Index value for generating G. Input for CKM_DSA_FIPS_G_GEN. 1473 Ignored by CKM_DSA_PROBABALISTIC_PARAMETER_GEN and 1474 CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN.
1475 2.2.2 DSA public key objects 1476 DSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_DSA) hold DSA public keys. 1477 The following table defines the DSA public key object attributes, in addition to the common attributes 1478 defined for this object class: 1479 Table 20, DSA Public Key Object Attributes Attribute Data type Meaning CKA_PRIME1,3 Big integer Prime p (512 to 3072 bits, in steps of 64 bits) CKA_SUBPRIME1,3 Big integer Subprime q (160, 224 bits, or 256 bits) CKA_BASE1,3 Big integer Base g CKA_VALUE1,4 Big integer Public value y 1480 - Refer to [PKCS11-Base] table 11 for footnotes 1481 The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA domain 1482 parameters”. See FIPS PUB 186-4 for more information on DSA keys. 1483 The following is a sample template for creating a DSA public key object: 1484 CK_OBJECT_CLASS class = CKO_PUBLIC_KEY; 1485 CK_KEY_TYPE keyType = CKK_DSA; 1486 CK_UTF8CHAR label[] = “A DSA public key object”; 1487 CK_BYTE prime[] = {...}; 1488 CK_BYTE subprime[] = {...}; 1489 CK_BYTE base[] = {...};
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 38 of 278 1490 CK_BYTE value[] = {...}; 1491 CK_BBOOL true = CK_TRUE; 1492 CK_ATTRIBUTE template[] = { 1493 {CKA_CLASS, &class, sizeof(class)}, 1494 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 1495 {CKA_TOKEN, &true, sizeof(true)}, 1496 {CKA_LABEL, label, sizeof(label)-1}, 1497 {CKA_PRIME, prime, sizeof(prime)}, 1498 {CKA_SUBPRIME, subprime, sizeof(subprime)}, 1499 {CKA_BASE, base, sizeof(base)}, 1500 {CKA_VALUE, value, sizeof(value)} 1501 }; 1502
1503 2.2.3 DSA Key Restrictions 1504 FIPS PUB 186-4 specifies permitted combinations of prime and sub-prime lengths. They are: 1505 Prime: 1024 bits, Subprime: 160 1506 Prime: 2048 bits, Subprime: 224 1507 Prime: 2048 bits, Subprime: 256 1508 Prime: 3072 bits, Subprime: 256 1509 Earlier versions of FIPS 186 permitted smaller prime lengths, and those are included here for backwards 1510 compatibility. An implementation that is compliant to FIPS 186-4 does not permit the use of primes of 1511 any length less than 1024 bits.
1512 2.2.4 DSA private key objects 1513 DSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_DSA) hold DSA private keys. 1514 The following table defines the DSA private key object attributes, in addition to the common attributes 1515 defined for this object class: 1516 Table 21, DSA Private Key Object Attributes Attribute Data type Meaning CKA_PRIME1,4,6 Big integer Prime p (512 to 1024 bits, in steps of 64 bits) CKA_SUBPRIME1,4,6 Big integer Subprime q (160 bits, 224 bits, or 256 bits) CKA_BASE1,4,6 Big integer Base g CKA_VALUE1,4,6,7 Big integer Private value x 1517 - Refer to [PKCS11-Base] table 11 for footnotes 1518 The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA domain 1519 parameters”. See FIPS PUB 186-4 for more information on DSA keys. 1520 Note that when generating a DSA private key, the DSA domain parameters are not specified in the key’s 1521 template. This is because DSA private keys are only generated as part of a DSA key pair, and the DSA 1522 domain parameters for the pair are specified in the template for the DSA public key. 1523 The following is a sample template for creating a DSA private key object: 1524 CK_OBJECT_CLASS class = CKO_PRIVATE_KEY; 1525 CK_KEY_TYPE keyType = CKK_DSA; 1526 CK_UTF8CHAR label[] = “A DSA private key object”; 1527 CK_BYTE subject[] = {...}; 1528 CK_BYTE id[] = {123};
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 39 of 278 1529 CK_BYTE prime[] = {...}; 1530 CK_BYTE subprime[] = {...}; 1531 CK_BYTE base[] = {...}; 1532 CK_BYTE value[] = {...}; 1533 CK_BBOOL true = CK_TRUE; 1534 CK_ATTRIBUTE template[] = { 1535 {CKA_CLASS, &class, sizeof(class)}, 1536 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 1537 {CKA_TOKEN, &true, sizeof(true)}, 1538 {CKA_LABEL, label, sizeof(label)-1}, 1539 {CKA_SUBJECT, subject, sizeof(subject)}, 1540 {CKA_ID, id, sizeof(id)}, 1541 {CKA_SENSITIVE, &true, sizeof(true)}, 1542 {CKA_SIGN, &true, sizeof(true)}, 1543 {CKA_PRIME, prime, sizeof(prime)}, 1544 {CKA_SUBPRIME, subprime, sizeof(subprime)}, 1545 {CKA_BASE, base, sizeof(base)}, 1546 {CKA_VALUE, value, sizeof(value)} 1547 };
1548 2.2.5 DSA domain parameter objects 1549 DSA domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type CKK_DSA) hold 1550 DSA domain parameters. The following table defines the DSA domain parameter object attributes, in 1551 addition to the common attributes defined for this object class: 1552 Table 22, DSA Domain Parameter Object Attributes Attribute Data type Meaning CKA_PRIME1,4 Big integer Prime p (512 to 1024 bits, in steps of 64 bits) CKA_SUBPRIME1,4 Big integer Subprime q (160 bits, 224 bits, or 256 bits) CKA_BASE1,4 Big integer Base g CKA_PRIME_BITS2,3 CK_ULONG Length of the prime value. 1553 - Refer to [PKCS11-Base] table 11 for footnotes 1554 The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA domain 1555 parameters”. See FIPS PUB 186-4 for more information on DSA domain parameters. 1556 To ensure backwards compatibility, if CKA_SUBPRIME_BITS is not specified for a call to 1557 C_GenerateKey, it takes on a default based on the value of CKA_PRIME_BITS as follows: 1558 If CKA_PRIME_BITS is less than or equal to 1024 then CKA_SUBPRIME_BITS shall be 160 bits 1559 If CKA_PRIME_BITS equals 2048 then CKA_SUBPRIME_BITS shall be 224 bits 1560 If CKA_PRIME_BITS equals 3072 then CKA_SUBPRIME_BITS shall be 256 bits 1561 1562 The following is a sample template for creating a DSA domain parameter object: 1563 CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS; 1564 CK_KEY_TYPE keyType = CKK_DSA; 1565 CK_UTF8CHAR label[] = “A DSA domain parameter object”; 1566 CK_BYTE prime[] = {...}; 1567 CK_BYTE subprime[] = {...}; 1568 CK_BYTE base[] = {...};
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 40 of 278 1569 CK_BBOOL true = CK_TRUE; 1570 CK_ATTRIBUTE template[] = { 1571 {CKA_CLASS, &class, sizeof(class)}, 1572 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 1573 {CKA_TOKEN, &true, sizeof(true)}, 1574 {CKA_LABEL, label, sizeof(label)-1}, 1575 {CKA_PRIME, prime, sizeof(prime)}, 1576 {CKA_SUBPRIME, subprime, sizeof(subprime)}, 1577 {CKA_BASE, base, sizeof(base)}, 1578 };
1579 2.2.6 DSA key pair generation 1580 The DSA key pair generation mechanism, denoted CKM_DSA_KEY_PAIR_GEN, is a key pair generation 1581 mechanism based on the Digital Signature Algorithm defined in FIPS PUB 186-2. 1582 This mechanism does not have a parameter. 1583 The mechanism generates DSA public/private key pairs with a particular prime, subprime and base, as 1584 specified in the CKA_PRIME, CKA_SUBPRIME, and CKA_BASE attributes of the template for the public 1585 key. 1586 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 1587 public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_BASE, and 1588 CKA_VALUE attributes to the new private key. Other attributes supported by the DSA public and private 1589 key types (specifically, the flags indicating which functions the keys support) may also be specified in the 1590 templates for the keys, or else are assigned default initial values. 1591 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1592 specify the supported range of DSA prime sizes, in bits.
1593 2.2.7 DSA domain parameter generation 1594 The DSA domain parameter generation mechanism, denoted CKM_DSA_PARAMETER_GEN, is a 1595 domain parameter generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 1596 186-2. 1597 This mechanism does not have a parameter. 1598 The mechanism generates DSA domain parameters with a particular prime length in bits, as specified in 1599 the CKA_PRIME_BITS attribute of the template. 1600 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, 1601 CKA_BASE and CKA_PRIME_BITS attributes to the new object. Other attributes supported by the DSA 1602 domain parameter types may also be specified in the template, or else are assigned default initial values. 1603 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1604 specify the supported range of DSA prime sizes, in bits.
1605 2.2.8 DSA probabilistic domain parameter generation 1606 The DSA probabilistic domain parameter generation mechanism, denoted 1607 CKM_DSA_PROBABLISTIC_PARAMETER_GEN, is a domain parameter generation mechanism based 1608 on the Digital Signature Algorithm defined in FIPS PUB 186-4, section Appendix A.1.1 Generation and 1609 Validation of Probable Primes.. 1610 This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash and 1611 returns the seed (pSeed) and the length (ulSeedLen). 1612 The mechanism generates DSA the prime and subprime domain parameters with a particular prime 1613 length in bits, as specified in the CKA_PRIME_BITS attribute of the template and the subprime length as 1614 specified in the CKA_SUBPRIME_BITS attribute of the template.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 41 of 278 1615 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, 1616 CKA_PRIME_BITS, and CKA_SUBPRIME_BITS attributes to the new object. CKA_BASE is not set by 1617 this call. Other attributes supported by the DSA domain parameter types may also be specified in the 1618 template, or else are assigned default initial values. 1619 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1620 specify the supported range of DSA prime sizes, in bits.
1621 2.2.9 DSA Shawe-Taylor domain parameter generation 1622 The DSA Shawe-Taylor domain parameter generation mechanism, denoted 1623 CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN, is a domain parameter generation mechanism 1624 based on the Digital Signature Algorithm defined in FIPS PUB 186-4, section Appendix A.1.2 1625 Construction and Validation of Provable Primes p and q. 1626 This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash and 1627 returns the seed (pSeed) and the length (ulSeedLen). 1628 The mechanism generates DSA the prime and subprime domain parameters with a particular prime 1629 length in bits, as specified in the CKA_PRIME_BITS attribute of the template and the subprime length as 1630 specified in the CKA_SUBPRIME_BITS attribute of the template. 1631 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, 1632 CKA_PRIME_BITS, and CKA_SUBPRIME_BITS attributes to the new object. CKA_BASE is not set by 1633 this call. Other attributes supported by the DSA domain parameter types may also be specified in the 1634 template, or else are assigned default initial values. 1635 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1636 specify the supported range of DSA prime sizes, in bits.
1637 2.2.10 DSA base domain parameter generation 1638 The DSA base domain parameter generation mechanism, denoted CKM_DSA_FIPS_G_GEN, is a base 1639 parameter generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 186-4, 1640 section Appendix A.2 Generation of Generator G. 1641 This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash the seed 1642 (pSeed) and the length (ulSeedLen) and the index value. 1643 The mechanism generates the DSA base with the domain parameter specified in the CKA_PRIME and 1644 CKA_SUBPRIME attributes of the template. 1645 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_BASE attributes to the new 1646 object. Other attributes supported by the DSA domain parameter types may also be specified in the 1647 template, or else are assigned default initial values. 1648 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1649 specify the supported range of DSA prime sizes, in bits.
1650 2.2.11 DSA without hashing 1651 The DSA without hashing mechanism, denoted CKM_DSA, is a mechanism for single-part signatures and 1652 verification based on the Digital Signature Algorithm defined in FIPS PUB 186-2. (This mechanism 1653 corresponds only to the part of DSA that processes the 20-byte hash value; it does not compute the hash 1654 value.) 1655 For the purposes of this mechanism, a DSA signature is a 40-byte string, corresponding to the 1656 concatenation of the DSA values r and s, each represented most-significant byte first. 1657 It does not have a parameter. 1658 Constraints on key types and the length of data are summarized in the following table: 1659 Table 23, DSA: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 42 of 278 Function Key type Input length Output length C_Sign1 DSA private key 20, 28, 32, 2*length of 48, or 64 bits subprime C_Verify1 DSA public key (20, 28, 32, N/A 48, or 64 bits), (2*length of subprime)2 1660 1 Single-part operations only. 1661 2 Data length, signature length. 1662 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1663 specify the supported range of DSA prime sizes, in bits.
1664 2.2.12 DSA with SHA-1 1665 The DSA with SHA-1 mechanism, denoted CKM_DSA_SHA1, is a mechanism for single- and multiple- 1666 part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-2. 1667 This mechanism computes the entire DSA specification, including the hashing with SHA-1. 1668 For the purposes of this mechanism, a DSA signature is a 40-byte string, corresponding to the 1669 concatenation of the DSA values r and s, each represented most-significant byte first. 1670 This mechanism does not have a parameter. 1671 Constraints on key types and the length of data are summarized in the following table: 1672 Table 24, DSA with SHA-1: Key And Data Length Function Key type Input length Output length C_Sign DSA private key any 2*subprime length C_Verify DSA public key any, N/A 2*subprime length2 1673 2 Data length, signature length. 1674 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1675 specify the supported range of DSA prime sizes, in bits.
1676 2.2.13 FIPS 186-4 1677 When CKM_DSA is operated in FIPS mode, only the following bit lengths of p and q, represented by L 1678 and N, SHALL be used: 1679 L = 1024, N = 160 1680 L = 2048, N = 224 1681 L = 2048, N = 256 1682 L = 3072, N = 256 1683
1684 2.2.14 DSA with SHA-224 1685 The DSA with SHA-1 mechanism, denoted CKM_DSA_SHA224, is a mechanism for single- and multiple- 1686 part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-4. 1687 This mechanism computes the entire DSA specification, including the hashing with SHA-224. 1688 For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to 1689 the concatenation of the DSA values r and s, each represented most-significant byte first.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 43 of 278 1690 This mechanism does not have a parameter. 1691 Constraints on key types and the length of data are summarized in the following table: 1692 Table 25, DSA with SHA-244: Key And Data Length Function Key type Input length Output length C_Sign DSA private key any 2*subprime length C_Verify DSA public key any, N/A 2*subprime length2 1693 2 Data length, signature length.
1694 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1695 specify the supported range of DSA prime sizes, in bits.
1696 2.2.15 DSA with SHA-256 1697 The DSA with SHA-1 mechanism, denoted CKM_DSA_SHA256, is a mechanism for single- and multiple- 1698 part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-4. 1699 This mechanism computes the entire DSA specification, including the hashing with SHA-256. 1700 For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to 1701 the concatenation of the DSA values r and s, each represented most-significant byte first. 1702 This mechanism does not have a parameter. 1703 Constraints on key types and the length of data are summarized in the following table: 1704 Table 26, DSA with SHA-256: Key And Data Length Function Key type Input length Output length C_Sign DSA private key any 2*subprime length C_Verify DSA public key any, N/A 2*subprime length2 1705 2 Data length, signature length.
1706 2.2.16 DSA with SHA-384 1707 The DSA with SHA-1 mechanism, denoted CKM_DSA_SHA384, is a mechanism for single- and multiple- 1708 part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-4. 1709 This mechanism computes the entire DSA specification, including the hashing with SHA-384. 1710 For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to 1711 the concatenation of the DSA values r and s, each represented most-significant byte first. 1712 This mechanism does not have a parameter. 1713 Constraints on key types and the length of data are summarized in the following table: 1714 Table 27, DSA with SHA-384: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 44 of 278 Function Key type Input length Output length C_Sign DSA private key any 2*subprime length C_Verify DSA public key any, N/A 2*subprime length2 1715 2 Data length, signature length.
1716 2.2.17 DSA with SHA-512 1717 The DSA with SHA-1 mechanism, denoted CKM_DSA_SHA512, is a mechanism for single- and multiple- 1718 part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-4. 1719 This mechanism computes the entire DSA specification, including the hashing with SHA-512. 1720 For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to 1721 the concatenation of the DSA values r and s, each represented most-significant byte first. 1722 This mechanism does not have a parameter. 1723 Constraints on key types and the length of data are summarized in the following table: 1724 Table 28, DSA with SHA-512: Key And Data Length Function Key type Input length Output length C_Sign DSA private key any 2*subprime length C_Verify DSA public key any, N/A 2*subprime length2 1725 2 Data length, signature length.
1726 2.2.18 DSA with SHA3-224 1727 The DSA with SHA3-224 mechanism, denoted CKM_DSA_SHA3_224, is a mechanism for single- and 1728 multiple-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1729 186-4. This mechanism computes the entire DSA specification, including the hashing with SHA3-224. 1730 For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to 1731 the concatenation of the DSA values r and s, each represented most-significant byte first. 1732 This mechanism does not have a parameter. 1733 Constraints on key types and the length of data are summarized in the following table: 1734 Table 29, DSA with SHA3-224: Key And Data Length Function Key type Input length Output length C_Sign DSA private key any 2*subprime length C_Verify DSA public key any, N/A 2*subprime length2 1735 2 Data length, signature length.
1736 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 1737 specify the supported range of DSA prime sizes, in bits.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 45 of 278 1738 2.2.19 DSA with SHA3-256 1739 The DSA with SHA3-256 mechanism, denoted CKM_DSA_SHA3_256, is a mechanism for single- and 1740 multiple-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1741 186-4. This mechanism computes the entire DSA specification, including the hashing with SHA3-256. 1742 For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to 1743 the concatenation of the DSA values r and s, each represented most-significant byte first. 1744 This mechanism does not have a parameter. 1745 Constraints on key types and the length of data are summarized in the following table: 1746 Table 30, DSA with SHA3-256: Key And Data Length Function Key type Input length Output length C_Sign DSA private key any 2*subprime length C_Verify DSA public key any, N/A 2*subprime length2 1747 2 Data length, signature length.
1748 2.2.20 DSA with SHA3-384 1749 The DSA with SHA3-384 mechanism, denoted CKM_DSA_SHA3_384, is a mechanism for single- and 1750 multiple-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1751 186-4. This mechanism computes the entire DSA specification, including the hashing with SHA3-384. 1752 For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to 1753 the concatenation of the DSA values r and s, each represented most-significant byte first. 1754 This mechanism does not have a parameter. 1755 Constraints on key types and the length of data are summarized in the following table: 1756 Table 31, DSA with SHA3-384: Key And Data Length Function Key type Input length Output length C_Sign DSA private key any 2*subprime length C_Verify DSA public key any, N/A 2*subprime length2 1757 2 Data length, signature length.
1758 2.2.21 DSA with SHA3-512 1759 The DSA with SHA3-512 mechanism, denoted CKM_DSA_SHA3-512, is a mechanism for single- and 1760 multiple-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1761 186-4. This mechanism computes the entire DSA specification, including the hashing with SH3A-512. 1762 For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to 1763 the concatenation of the DSA values r and s, each represented most-significant byte first. 1764 This mechanism does not have a parameter. 1765 Constraints on key types and the length of data are summarized in the following table: 1766 Table 32, DSA with SHA3-512: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 46 of 278 Function Key type Input length Output length C_Sign DSA private key any 2*subprime length C_Verify DSA public key any, N/A 2*subprime length2 1767 2 Data length, signature length. 1768
1769 2.3 Elliptic Curve 1770 The Elliptic Curve (EC) cryptosystem (also related to ECDSA) in this document was originally based on 1771 the one described in the ANSI X9.62 and X9.63 standards developed by the ANSI X9F1 working group. 1772 The EC cryptosystem developed by the ANSI X9F1 working group was created at a time when EC curves 1773 were always represented in their Weierstrass form. Since that time, new curves represented in Edwards 1774 form (RFC 8032) and Montgomery form (RFC 7748) have become more common. To support these new 1775 curves, the EC cryptosystem in this document has been extended from the original. Additional key 1776 generation mechanisms have been added as well as an additional signature generation mechanism. 1777 1778 Table 33, Elliptic Curve Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_EC_KEY_PAIR_GEN CKM_EC_KEY_PAIR_GEN_W_ EXTRA_BITS CKM_EC_EDWARDS_KEY_PAI R_GEN CKM_EC_MONTGOMERY_KEY _PAIR_GEN CKM_ECDSA 2 CKM_ECDSA_SHA1 CKM_ECDSA_SHA224 CKM_ECDSA_SHA256 CKM_ECDSA_SHA384 CKM_ECDSA_SHA512 CKM_ECDSA_SHA3_224 CKM_ECDSA_SHA3_256 CKM_ECDSA_SHA3_384 CKM_ECDSA_SHA3_512 CKM_EDDSA CKM_XEDDSA CKM_ECDH1_DERIVE CKM_ECDH1_COFACTOR_DE RIVE CKM_ECMQV_DERIVE
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 47 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_ECDH_AES_KEY_WRAP
1779 1780 Table 34, Mechanism Information Flags CKF_EC_F_P 0x00100000UL True if the mechanism can be used with EC domain parameters over Fp CKF_EC_F_2M 0x00200000UL True if the mechanism can be used
with EC domain parameters over F2m CKF_EC_ECPARAMETERS 0x00400000UL True if the mechanism can be used with EC domain parameters of the choice ecParameters CKF_EC_OID 0x00800000UL True if the mechanism can be used with EC domain parameters of the choice oId CKF_EC_UNCOMPRESS 0x01000000UL True if the mechanism can be used with elliptic curve point uncompressed CKF_EC_COMPRESS 0x02000000UL True if the mechanism can be used with elliptic curve point compressed CKF_EC_CURVENAME 0x04000000UL True of the mechanism can be used with EC domain parameters of the choice curveName 1781 Note: CKF_EC_NAMEDCURVE is deprecated with PKCS#11 3.00. It is replaced by CKF_EC_OID. 1782 In these standards, there are two different varieties of EC defined:
1783 1. EC using a field with an odd prime number of elements (i.e. the finite field Fp).
1784 2. EC using a field of characteristic two (i.e. the finite field F2m). 1785 An EC key in Cryptoki contains information about which variety of EC it is suited for. It is preferable that a 1786 Cryptoki library, which can perform EC mechanisms, be capable of performing operations with the two 1787 varieties of EC, however this is not required. The CK_MECHANISM_INFO structure CKF_EC_F_P flag 1788 identifies a Cryptoki library supporting EC keys over Fp whereas the CKF_EC_F_2M flag identifies a
1789 Cryptoki library supporting EC keys over F2m. A Cryptoki library that can perform EC mechanisms must 1790 set either or both of these flags for each EC mechanism. 1791 In these specifications there are also four representation methods to define the domain parameters for an 1792 EC key. Only the ecParameters, the oId and the curveName choices are supported in Cryptoki. The 1793 CK_MECHANISM_INFO structure CKF_EC_ECPARAMETERS flag identifies a Cryptoki library 1794 supporting the ecParameters choice whereas the CKF_EC_OID flag identifies a Cryptoki library 1795 supporting the oId choice, and the CKF_EC_CURVENAME flag identifies a Cryptoki library supporting 1796 the curveName choice. A Cryptoki library that can perform EC mechanisms must set the appropriate 1797 flag(s) for each EC mechanism. 1798 In these specifications, an EC public key (i.e. EC point Q) or the base point G when the ecParameters 1799 choice is used can be represented as an octet string of the uncompressed form or the compressed form. 1800 The CK_MECHANISM_INFO structure CKF_EC_UNCOMPRESS flag identifies a Cryptoki library 1801 supporting the uncompressed form whereas the CKF_EC_COMPRESS flag identifies a Cryptoki library 1802 supporting the compressed form. A Cryptoki library that can perform EC mechanisms must set either or 1803 both of these flags for each EC mechanism.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 48 of 278 1804 Note that an implementation of a Cryptoki library supporting EC with only one variety, one representation 1805 of domain parameters or one form may encounter difficulties achieving interoperability with other 1806 implementations. 1807 If an attempt to create, generate, derive or unwrap an EC key of an unsupported curve is made, the 1808 attempt should fail with the error code CKR_CURVE_NOT_SUPPORTED. If an attempt to create, 1809 generate, derive, or unwrap an EC key with invalid or of an unsupported representation of domain 1810 parameters is made, that attempt should fail with the error code CKR_DOMAIN_PARAMS_INVALID. If 1811 an attempt to create, generate, derive, or unwrap an EC key of an unsupported form is made, that 1812 attempt should fail with the error code CKR_TEMPLATE_INCONSISTENT.
1813 2.3.1 EC Signatures 1814 For the purposes of these mechanisms, an ECDSA signature is an octet string of even length which is at 1815 most two times nLen octets, where nLen is the length in octets of the base point order n. The signature 1816 octets correspond to the concatenation of the ECDSA values r and s, both represented as an octet string 1817 of equal length of at most nLen with the most significant byte first. If r and s have different octet length, 1818 the shorter of both must be padded with leading zero octets such that both have the same octet length. 1819 Loosely spoken, the first half of the signature is r and the second half is s. For signatures created by a 1820 token, the resulting signature is always of length 2nLen. For signatures passed to a token for verification, 1821 the signature may have a shorter length but must be composed as specified before. 1822 If the length of the hash value is larger than the bit length of n, only the leftmost bits of the hash up to the 1823 length of n will be used. Any truncation is done by the token. 1824 Note: For applications, it is recommended to encode the signature as an octet string of length two times 1825 nLen if possible. This ensures that the application works with PKCS#11 modules which have been 1826 implemented based on an older version of this document. Older versions required all signatures to have 1827 length two times nLen. It may be impossible to encode the signature with the maximum length of two 1828 times nLen if the application just gets the integer values of r and s (i.e. without leading zeros), but does 1829 not know the base point order n, because r and s can have any value between zero and the base point 1830 order n. 1831 1832 An EdDSA signature is an octet string of even length which is two times nLen octets, where nLen is 1833 calculated as EdDSA parameter b divided by 8. The signature octets correspond to the concatenation of 1834 the EdDSA values R and S as defined in [RFC 8032], both represented as an octet string of equal length 1835 of nLen bytes in little endian order.
1836 2.3.2 Definitions 1837 This section defines the key type “CKK_EC” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE 1838 attribute of key objects. 1839 Note: CKK_ECDSA is deprecated. It is replaced by CKK_EC. 1840 Mechanisms: 1841 1842 CKM_EC_KEY_PAIR_GEN 1843 CKM_EC_EDWARDS_KEY_PAIR_GEN 1844 CKM_EC_MONTGOMERY_KEY_PAIR_GEN 1845 CKM_ECDSA 1846 CKM_ECDSA_SHA1 1847 CKM_ECDSA_SHA224 1848 CKM_ECDSA_SHA256 1849 CKM_ECDSA_SHA384 1850 CKM_ECDSA_SHA512
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 49 of 278 1851 CKM_ECDSA_SHA3_224 1852 CKM_ECDSA_SHA3_256 1853 CKM_ECDSA_SHA3_384 1854 CKM_ECDSA_SHA3_512 1855 CKM_EDDSA 1856 CKM_XEDDSA 1857 CKM_ECDH1_DERIVE 1858 CKM_ECDH1_COFACTOR_DERIVE 1859 CKM_ECMQV_DERIVE 1860 CKM_ECDH_AES_KEY_WRAP 1861 1862 CKD_NULL 1863 CKD_SHA1_KDF 1864 CKD_SHA224_KDF 1865 CKD_SHA256_KDF 1866 CKD_SHA384_KDF 1867 CKD_SHA512_KDF 1868 CKD_SHA3_224_KDF 1869 CKD_SHA3_256_KDF 1870 CKD_SHA3_384_KDF 1871 CKD_SHA3_512_KDF 1872 CKD_SHA1_KDF_SP800 1873 CKD_SHA224_KDF_SP800 1874 CKD_SHA256_KDF_SP800 1875 CKD_SHA384_KDF_SP800 1876 CKD_SHA512_KDF_SP800 1877 CKD_SHA3_224_KDF_SP800 1878 CKD_SHA3_256_KDF_SP800 1879 CKD_SHA3_384_KDF_SP800 1880 CKD_SHA3_512_KDF_SP800 1881 CKD_BLAKE2B_160_KDF 1882 CKD_BLAKE2B_256_KDF 1883 CKD_BLAKE2B_384_KDF 1884 CKD_BLAKE2B_512_KDF 1885
1886 2.3.3 ECDSA public key objects 1887 EC (also related to ECDSA) public key objects (object class CKO_PUBLIC_KEY, key type CKK_EC) 1888 hold EC public keys. The following table defines the EC public key object attributes, in addition to the 1889 common attributes defined for this object class: 1890 Table 35, Elliptic Curve Public Key Object Attributes
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 50 of 278 Attribute Data type Meaning CKA_EC_PARAMS1,3 Byte array DER-encoding of an ANSI X9.62 Parameters value CKA_EC_POINT1,4 Byte array DER-encoding of ANSI X9.62 ECPoint value Q 1891 - Refer to [PKCS11-Base] table 11 for footnotes 1892 Note: CKA_ECDSA_PARAMS is deprecated. It is replaced by CKA_EC_PARAMS. 1893 The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI 1894 X9.62 as a choice of three parameter representation methods with the following syntax: 1895 Parameters ::= CHOICE { 1896 ecParameters ECParameters, 1897 oId CURVES.&id({CurveNames}), 1898 implicitlyCA NULL, 1899 curveName PrintableString 1900 } 1901 1902 This allows detailed specification of all required values using choice ecParameters, the use of oId as an 1903 object identifier substitute for a particular set of elliptic curve domain parameters, or implicitlyCA to 1904 indicate that the domain parameters are explicitly defined elsewhere, or curveName to specify a curve 1905 name as e.g. define in [ANSI X9.62], [BRAINPOOL], [SEC 2], [LEGIFRANCE]. The use of oId or 1906 curveName is recommended over the choice ecParameters. The choice implicitlyCA must not be used 1907 in Cryptoki. 1908 The following is a sample template for creating an EC (ECDSA) public key object: 1909 CK_OBJECT_CLASS class = CKO_PUBLIC_KEY; 1910 CK_KEY_TYPE keyType = CKK_EC; 1911 CK_UTF8CHAR label[] = “An EC public key object”; 1912 CK_BYTE ecParams[] = {...}; 1913 CK_BYTE ecPoint[] = {...}; 1914 CK_BBOOL true = CK_TRUE; 1915 CK_ATTRIBUTE template[] = { 1916 {CKA_CLASS, &class, sizeof(class)}, 1917 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 1918 {CKA_TOKEN, &true, sizeof(true)}, 1919 {CKA_LABEL, label, sizeof(label)-1}, 1920 {CKA_EC_PARAMS, ecParams, sizeof(ecParams)}, 1921 {CKA_EC_POINT, ecPoint, sizeof(ecPoint)} 1922 };
1923 2.3.4 Elliptic curve private key objects 1924 EC (also related to ECDSA) private key objects (object class CKO_PRIVATE_KEY, key type CKK_EC) 1925 hold EC private keys. See Section 2.3 for more information about EC. The following table defines the EC 1926 private key object attributes, in addition to the common attributes defined for this object class: 1927 Table 36, Elliptic Curve Private Key Object Attributes
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 51 of 278 Attribute Data type Meaning CKA_EC_PARAMS1,4,6 Byte array DER-encoding of an ANSI X9.62 Parameters value CKA_VALUE1,4,6,7 Big integer ANSI X9.62 private value d 1928 - Refer to [PKCS11-Base] table 11 for footnotes 1929 The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI 1930 X9.62 as a choice of three parameter representation methods with the following syntax: 1931 Parameters ::= CHOICE { 1932 ecParameters ECParameters, 1933 oId CURVES.&id({CurveNames}), 1934 implicitlyCA NULL, 1935 curveName PrintableString 1936 } 1937 1938 This allows detailed specification of all required values using choice ecParameters, the use of oId as an 1939 object identifier substitute for a particular set of elliptic curve domain parameters, or implicitlyCA to 1940 indicate that the domain parameters are explicitly defined elsewhere, or curveName to specify a curve 1941 name as e.g. define in [ANSI X9.62], [BRAINPOOL], [SEC 2], [LEGIFRANCE]. The use of oId or 1942 curveName is recommended over the choice ecParameters. The choice implicitlyCA must not be used 1943 in Cryptoki.Note that when generating an EC private key, the EC domain parameters are not specified in 1944 the key’s template. This is because EC private keys are only generated as part of an EC key pair, and 1945 the EC domain parameters for the pair are specified in the template for the EC public key. 1946 The following is a sample template for creating an EC (ECDSA) private key object: 1947 CK_OBJECT_CLASS class = CKO_PRIVATE_KEY; 1948 CK_KEY_TYPE keyType = CKK_EC; 1949 CK_UTF8CHAR label[] = “An EC private key object”; 1950 CK_BYTE subject[] = {...}; 1951 CK_BYTE id[] = {123}; 1952 CK_BYTE ecParams[] = {...}; 1953 CK_BYTE value[] = {...}; 1954 CK_BBOOL true = CK_TRUE; 1955 CK_ATTRIBUTE template[] = { 1956 {CKA_CLASS, &class, sizeof(class)}, 1957 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 1958 {CKA_TOKEN, &true, sizeof(true)}, 1959 {CKA_LABEL, label, sizeof(label)-1}, 1960 {CKA_SUBJECT, subject, sizeof(subject)}, 1961 {CKA_ID, id, sizeof(id)}, 1962 {CKA_SENSITIVE, &true, sizeof(true)}, 1963 {CKA_DERIVE, &true, sizeof(true)}, 1964 {CKA_EC_PARAMS, ecParams, sizeof(ecParams)}, 1965 {CKA_VALUE, value, sizeof(value)} 1966 };
1967 2.3.5 Edwards Elliptic curve public key objects 1968 Edwards EC public key objects (object class CKO_PUBLIC_KEY, key type CKK_EC_EDWARDS) hold 1969 Edwards EC public keys. The following table defines the Edwards EC public key object attributes, in 1970 addition to the common attributes defined for this object class:
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 52 of 278 1971 Table 37, Edwards Elliptic Curve Public Key Object Attributes Attribute Data type Meaning CKA_EC_PARAMS1,3 Byte array DER-encoding of a Parameters value as defined above CKA_EC_POINT1,4 Byte array DER-encoding of the b-bit public key value in little endian order as defined in RFC 8032 1972 - Refer to [PKCS #11-Base] table 11 for footnotes 1973 The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI 1974 X9.62 as a choice of three parameter representation methods. A 4th choice is added to support Edwards 1975 and Montgomery Elliptic curves. The CKA_EC_PARAMS attribute has the following syntax: 1976 Parameters ::= CHOICE { 1977 ecParameters ECParameters, 1978 oId CURVES.&id({CurveNames}), 1979 implicitlyCA NULL, 1980 curveName PrintableString 1981 } 1982 Edwards EC public keys only support the use of the curveName selection to specify a curve name as 1983 defined in [RFC 8032] and the use of the oID selection to specify a curve through an EdDSA algorithm as 1984 defined in [RFC 8410]. Note that keys defined by RFC 8032 and RFC 8410 are incompatible. 1985 The following is a sample template for creating an Edwards EC public key object with Edwards25519 1986 being specified as curveName: 1987 CK_OBJECT_CLASS class = CKO_PUBLIC_KEY; 1988 CK_KEY_TYPE keyType = CKK_EC; 1989 CK_UTF8CHAR label[] = “An Edwards EC public key object”; 1990 CK_BYTE ecParams[] = {0x13, 0x0c, 0x65, 0x64, 0x77, 0x61, 1991 0x72, 0x64, 0x73, 0x32, 0x35, 0x35, 0x31, 0x39}; 1992 CK_BYTE ecPoint[] = {...}; 1993 CK_BBOOL true = CK_TRUE; 1994 CK_ATTRIBUTE template[] = { 1995 {CKA_CLASS, &class, sizeof(class)}, 1996 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 1997 {CKA_TOKEN, &true, sizeof(true)}, 1998 {CKA_LABEL, label, sizeof(label)-1}, 1999 {CKA_EC_PARAMS, ecParams, sizeof(ecParams)}, 2000 {CKA_EC_POINT, ecPoint, sizeof(ecPoint)} 2001 };
2002 2.3.6 Edwards Elliptic curve private key objects 2003 Edwards EC private key objects (object class CKO_PRIVATE_KEY, key type CKK_EC_EDWARDS) 2004 hold Edwards EC private keys. See Section 2.3 for more information about EC. The following table 2005 defines the Edwards EC private key object attributes, in addition to the common attributes defined for this 2006 object class: 2007 Table 38, Edwards Elliptic Curve Private Key Object Attributes
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 53 of 278 Attribute Data type Meaning CKA_EC_PARAMS1,4,6 Byte array DER-encoding of a Parameters value as defined above CKA_VALUE1,4,6,7 Big integer b-bit private key value in little endian order as defined in RFC 8032 2008 - Refer to [PKCS #11-Base] table 11 for footnotes 2009 The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI 2010 X9.62 as a choice of three parameter representation methods. A 4th choice is added to support Edwards 2011 and Montgomery Elliptic curves. The CKA_EC_PARAMS attribute has the following syntax: 2012 Parameters ::= CHOICE { 2013 ecParameters ECParameters, 2014 oId CURVES.&id({CurveNames}), 2015 implicitlyCA NULL, 2016 curveName PrintableString 2017 } 2018 Edwards EC private keys only support the use of the curveName selection to specify a curve name as 2019 defined in [RFC 8032] and the use of the oID selection to specify a curve through an EdDSA algorithm as 2020 defined in [RFC 8410]. Note that keys defined by RFC 8032 and RFC 8410 are incompatible. 2021 Note that when generating an Edwards EC private key, the EC domain parameters are not specified in 2022 the key’s template. This is because Edwards EC private keys are only generated as part of an Edwards 2023 EC key pair, and the EC domain parameters for the pair are specified in the template for the Edwards EC 2024 public key. 2025 The following is a sample template for creating an Edwards EC private key object: 2026 CK_OBJECT_CLASS class = CKO_PRIVATE_KEY; 2027 CK_KEY_TYPE keyType = CKK_EC; 2028 CK_UTF8CHAR label[] = “An Edwards EC private key object”; 2029 CK_BYTE subject[] = {...}; 2030 CK_BYTE id[] = {123}; 2031 CK_BYTE ecParams[] = {...}; 2032 CK_BYTE value[] = {...}; 2033 CK_BBOOL true = CK_TRUE; 2034 CK_ATTRIBUTE template[] = { 2035 {CKA_CLASS, &class, sizeof(class)}, 2036 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 2037 {CKA_TOKEN, &true, sizeof(true)}, 2038 {CKA_LABEL, label, sizeof(label)-1}, 2039 {CKA_SUBJECT, subject, sizeof(subject)}, 2040 {CKA_ID, id, sizeof(id)}, 2041 {CKA_SENSITIVE, &true, sizeof(true)}, 2042 {CKA_DERIVE, &true, sizeof(true)}, 2043 {CKA_VALUE, value, sizeof(value)} 2044 };
2045 2.3.7 Montgomery Elliptic curve public key objects 2046 Montgomery EC public key objects (object class CKO_PUBLIC_KEY, key type 2047 CKK_EC_MONTGOMERY) hold Montgomery EC public keys. The following table defines the 2048 Montgomery EC public key object attributes, in addition to the common attributes defined for this object 2049 class:
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 54 of 278 2050 Table 39, Montgomery Elliptic Curve Public Key Object Attributes Attribute Data type Meaning CKA_EC_PARAMS1,3 Byte array DER-encoding of a Parameters value as defined above CKA_EC_POINT1,4 Byte array DER-encoding of the public key value in little endian order as defined in RFC 7748 2051 - Refer to [PKCS #11-Base] table 11 for footnotes 2052 The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI 2053 X9.62 as a choice of three parameter representation methods. A 4th choice is added to support Edwards 2054 and Montgomery Elliptic curves. The CKA_EC_PARAMS attribute has the following syntax: 2055 Parameters ::= CHOICE { 2056 ecParameters ECParameters, 2057 oId CURVES.&id({CurveNames}), 2058 implicitlyCA NULL, 2059 curveName PrintableString 2060 } 2061 Montgomery EC public keys only support the use of the curveName selection to specify a curve name as 2062 defined in [RFC7748] and the use of the oID selection to specify a curve through an ECDH algorithm as 2063 defined in [RFC 8410]. Note that keys defined by RFC 7748 and RFC 8410 are incompatible. 2064 The following is a sample template for creating a Montgomery EC public key object: 2065 CK_OBJECT_CLASS class = CKO_PUBLIC_KEY; 2066 CK_KEY_TYPE keyType = CKK_EC; 2067 CK_UTF8CHAR label[] = “A Montgomery EC public key object”; 2068 CK_BYTE ecParams[] = {...}; 2069 CK_BYTE ecPoint[] = {...}; 2070 CK_BBOOL true = CK_TRUE; 2071 CK_ATTRIBUTE template[] = { 2072 {CKA_CLASS, &class, sizeof(class)}, 2073 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 2074 {CKA_TOKEN, &true, sizeof(true)}, 2075 {CKA_LABEL, label, sizeof(label)-1}, 2076 {CKA_EC_PARAMS, ecParams, sizeof(ecParams)}, 2077 {CKA_EC_POINT, ecPoint, sizeof(ecPoint)} 2078 };
2079 2.3.8 Montgomery Elliptic curve private key objects 2080 Montgomery EC private key objects (object class CKO_PRIVATE_KEY, key type 2081 CKK_EC_MONTGOMERY) hold Montgomery EC private keys. See Section 2.3 for more information 2082 about EC. The following table defines the Montgomery EC private key object attributes, in addition to the 2083 common attributes defined for this object class: 2084 Table 40, Montgomery Elliptic Curve Private Key Object Attributes Attribute Data type Meaning CKA_EC_PARAMS1,4,6 Byte array DER-encoding of a Parameters value as defined above CKA_VALUE1,4,6,7 Big integer Private key value in little endian order as defined in RFC 7748 2085 - Refer to [PKCS #11-Base] table 11 for footnotes
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 55 of 278 2086 The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI 2087 X9.62 as a choice of three parameter representation methods. A 4th choice is added to support Edwards 2088 and Montgomery Elliptic curves. The CKA_EC_PARAMS attribute has the following syntax: 2089 Parameters ::= CHOICE { 2090 ecParameters ECParameters, 2091 oId CURVES.&id({CurveNames}), 2092 implicitlyCA NULL, 2093 curveName PrintableString 2094 } 2095 Edwards EC private keys only support the use of the curveName selection to specify a curve name as 2096 defined in [RFC7748] and the use of the oID selection to specify a curve through an ECDH algorithm as 2097 defined in [RFC 8410]. Note that keys defined by RFC 7748 and RFC 8410 are incompatible. 2098 Note that when generating a Montgomery EC private key, the EC domain parameters are not specified in 2099 the key’s template. This is because Montgomery EC private keys are only generated as part of a 2100 Montgomery EC key pair, and the EC domain parameters for the pair are specified in the template for the 2101 Montgomery EC public key. 2102 The following is a sample template for creating a Montgomery EC private key object: 2103 CK_OBJECT_CLASS class = CKO_PRIVATE_KEY; 2104 CK_KEY_TYPE keyType = CKK_EC; 2105 CK_UTF8CHAR label[] = “A Montgomery EC private key object”; 2106 CK_BYTE subject[] = {...}; 2107 CK_BYTE id[] = {123}; 2108 CK_BYTE ecParams[] = {...}; 2109 CK_BYTE value[] = {...}; 2110 CK_BBOOL true = CK_TRUE; 2111 CK_ATTRIBUTE template[] = { 2112 {CKA_CLASS, &class, sizeof(class)}, 2113 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 2114 {CKA_TOKEN, &true, sizeof(true)}, 2115 {CKA_LABEL, label, sizeof(label)-1}, 2116 {CKA_SUBJECT, subject, sizeof(subject)}, 2117 {CKA_ID, id, sizeof(id)}, 2118 {CKA_SENSITIVE, &true, sizeof(true)}, 2119 {CKA_DERIVE, &true, sizeof(true)}, 2120 {CKA_VALUE, value, sizeof(value)} 2121 };
2122 2.3.9 Elliptic curve key pair generation 2123 The EC (also related to ECDSA) key pair generation mechanism, denoted CKM_EC_KEY_PAIR_GEN, is 2124 a key pair generation mechanism that uses the method defined by the ANSI X9.62 and X9.63 standards. 2125 The EC (also related to ECDSA) key pair generation mechanism, denoted 2126 CKM_EC_KEY_PAIR_GEN_W_EXTRA_BITS, is a key pair generation mechanism that uses the method 2127 defined by FIPS 186-4 Appendix B.4.1. 2128 These mechanisms do not have a parameter. 2129 These mechanisms generate EC public/private key pairs with particular EC domain parameters, as 2130 specified in the CKA_EC_PARAMS attribute of the template for the public key. Note that this version of 2131 Cryptoki does not include a mechanism for generating these EC domain parameters.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 56 of 278 2132 These mechanism contribute the CKA_CLASS, CKA_KEY_TYPE, and CKA_EC_POINT attributes to the 2133 new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_EC_PARAMS and CKA_VALUE 2134 attributes to the new private key. Other attributes supported by the EC public and private key types 2135 (specifically, the flags indicating which functions the keys support) may also be specified in the templates 2136 for the keys, or else are assigned default initial values. 2137 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2138 specify the minimum and maximum supported number of bits in the field sizes, respectively. For 2139 example, if a Cryptoki library supports only ECDSA using a field of characteristic 2 which has between 2140 2200 and 2300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary 2141 notation, the number 2200 consists of a 1 bit followed by 200 0 bits. It is therefore a 201-bit number. 2142 Similarly, 2300 is a 301-bit number).
2143 2.3.10 Edwards Elliptic curve key pair generation 2144 The Edwards EC key pair generation mechanism, denoted CKM_EC_EDWARDS_KEY_PAIR_GEN, is a 2145 key pair generation mechanism for EC keys over curves represented in Edwards form. 2146 This mechanism does not have a parameter. 2147 The mechanism can only generate EC public/private key pairs over the curves edwards25519 and 2148 edwards448 as defined in RFC 8032 or the curves id-Ed25519 and id-Ed448 as defined in RFC 8410. 2149 These curves can only be specified in the CKA_EC_PARAMS attribute of the template for the public key 2150 using the curveName or the oID methods. Attempts to generate keys over these curves using any other 2151 EC key pair generation mechanism will fail with CKR_CURVE_NOT_SUPPORTED. 2152 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_EC_POINT attributes to the 2153 new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_EC_PARAMS and CKA_VALUE 2154 attributes to the new private key. Other attributes supported by the Edwards EC public and private key 2155 types (specifically, the flags indicating which functions the keys support) may also be specified in the 2156 templates for the keys, or else are assigned default initial values. 2157 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2158 specify the minimum and maximum supported number of bits in the field sizes, respectively. For this 2159 mechanism, the only allowed values are 255 and 448 as RFC 8032 only defines curves of these two 2160 sizes. A Cryptoki implementation may support one or both of these curves and should set the 2161 ulMinKeySize and ulMaxKeySize fields accordingly.
2162 2.3.11 Montgomery Elliptic curve key pair generation 2163 The Montgomery EC key pair generation mechanism, denoted 2164 CKM_EC_MONTGOMERY_KEY_PAIR_GEN, is a key pair generation mechanism for EC keys over 2165 curves represented in Montgomery form. 2166 This mechanism does not have a parameter. 2167 The mechanism can only generate Montgomery EC public/private key pairs over the curves curve25519 2168 and curve448 as defined in RFC 7748 or the curves id-X25519 and id-X448 as defined in RFC 8410. 2169 These curves can only be specified in the CKA_EC_PARAMS attribute of the template for the public key 2170 using the curveName or oId methods. Attempts to generate keys over these curves using any other EC 2171 key pair generation mechanism will fail with CKR_CURVE_NOT_SUPPORTED. 2172 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_EC_POINT attributes to the 2173 new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_EC_PARAMS and CKA_VALUE 2174 attributes to the new private key. Other attributes supported by the EC public and private key types 2175 (specifically, the flags indicating which functions the keys support) may also be specified in the templates 2176 for the keys, or else are assigned default initial values. 2177 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2178 specify the minimum and maximum supported number of bits in the field sizes, respectively. For this 2179 mechanism, the only allowed values are 255 and 448 as RFC 7748 only defines curves of these two 2180 sizes. A Cryptoki implementation may support one or both of these curves and should set the 2181 ulMinKeySize and ulMaxKeySize fields accordingly.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 57 of 278 2182 2.3.12 ECDSA without hashing 2183 Refer section 2.3.1 for signature encoding. 2184 The ECDSA without hashing mechanism, denoted CKM_ECDSA, is a mechanism for single-part 2185 signatures and verification for ECDSA. (This mechanism corresponds only to the part of ECDSA that 2186 processes the hash value, which should not be longer than 1024 bits; it does not compute the hash 2187 value.) 2188 This mechanism does not have a parameter. 2189 Constraints on key types and the length of data are summarized in the following table: 2190 Table 41, ECDSA without hashing: Key and Data Length Function Key type Input length Output length C_Sign1 ECDSA private key any3 2nLen C_Verify1 ECDSA public key any3, 2nLen 2 N/A 2191 1 Single-part operations only. 2192 2 Data length, signature length. 2193 3 Input the entire raw digest. Internally, this will be truncated to the appropriate number of bits. 2194 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2195 specify the minimum and maximum supported number of bits in the field sizes, respectively. For 2196 example, if a Cryptoki library supports only ECDSA using a field of characteristic 2 which has between 2197 2200 and 2300 elements (inclusive), then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in 2198 binary notation, the number 2200 consists of a 1 bit followed by 200 0 bits. It is therefore a 201-bit number. 2199 Similarly, 2300 is a 301-bit number).
2200 2.3.13 ECDSA with hashing 2201 Refer to section 2.3.1 for signature encoding. 2202 The ECDSA with SHA-1, SHA-224, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 2203 mechanism, denoted 2204 CKM_ECDSA_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512] 2205 respectively, is a mechanism for single- and multiple-part signatures and verification for ECDSA. This 2206 mechanism computes the entire ECDSA specification, including the hashing with SHA-1, SHA-224, SHA- 2207 384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 respectively. 2208 This mechanism does not have a parameter. 2209 Constraints on key types and the length of data are summarized in the following table: 2210 Table 42, ECDSA with hashing: Key and Data Length Function Key type Input length Output length C_Sign ECDSA private key any 2nLen C_Verify ECDSA public key any, 2nLen 2 N/A 2211 2 Data length, signature length. 2212 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2213 specify the minimum and maximum supported number of bits in the field sizes, respectively. For 2214 example, if a Cryptoki library supports only ECDSA using a field of characteristic 2 which has between 2215 2200 and 2300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary 2216 notation, the number 2200 consists of a 1 bit followed by 200 0 bits. It is therefore a 201-bit number. 2217 Similarly, 2300 is a 301-bit number).
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 58 of 278 2218 2.3.14 EdDSA 2219 The EdDSA mechanism, denoted CKM_EDDSA, is a mechanism for single-part and multipart signatures 2220 and verification for EdDSA. This mechanism implements the five EdDSA signature schemes defined in 2221 RFC 8032 and RFC 8410. 2222 For curves according to RFC 8032, this mechanism has an optional parameter, a CK_EDDSA_PARAMS 2223 structure. The absence or presence of the parameter as well as its content is used to identify which 2224 signature scheme is to be used. Table 32 enumerates the five signature schemes defined in RFC 8032 2225 and all supported permutations of the mechanism parameter and its content. 2226 Table 43, Mapping to RFC 8032 Signature Schemes Signature Scheme Mechanism Param phFlag Context Data Ed25519 Not Required N/A N/A
Ed25519ctx Required False Optional
Ed25519ph Required True Optional
Ed448 Required False Optional
Ed448ph Required True Optional
2227 For curves according to RFC 8410, the mechanism is implicitly given by the curve, which is EdDSA in 2228 pure mode. 2229 Constraints on key types and the length of data are summarized in the following table: 2230 Table 44, EdDSA: Key and Data Length Function Key type Input length Output length C_Sign CKK_EC_EDWARDS private key any 2bLen
C_Verify CKK_EC_EDWARDS public key any, 2bLen 2 N/A
2231 2 Data length, signature length. 2232 Note that for EdDSA in pure mode, Ed25519 and Ed448 the data must be processed twice. Therefore, a 2233 token might need to cache all the data, especially when used with C_SignUpdate/C_VerifyUpdate. If 2234 tokens are unable to do so they can return CKM_TOKEN_RESOURCE_EXCEEDED.
2235 2.3.15 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of 2236 the CK_MECHANISM_INFO structure specify the minimum and 2237 maximum supported number of bits in the field sizes, respectively. 2238 For this mechanism, the only allowed values are 255 and 448 as RFC 2239 8032and RFC 8410 only define curves of these two sizes. A Cryptoki 2240 implementation may support one or both of these curves and should 2241 set the ulMinKeySize and ulMaxKeySize fields accordingly.XEdDSA 2242 The XEdDSA mechanism, denoted CKM_XEDDSA, is a mechanism for single-part signatures and 2243 verification for XEdDSA. This mechanism implements the XEdDSA signature scheme defined in 2244 [XEDDSA]. CKM_XEDDSA operates on CKK_EC_MONTGOMERY type EC keys, which allows these 2245 keys to be used both for signing/verification and for Diffie-Hellman style key-exchanges. This double use 2246 is necessary for the Extended Triple Diffie-Hellman where the long-term identity key is used to sign short- 2247 term keys and also contributes to the DH key-exchange. 2248 This mechanism has a parameter, a CK_XEDDSA_PARAMS structure.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 59 of 278 2249 Table 45, XEdDSA: Key and Data Length Function Key type Input length Output length C_Sign1 CKK_EC_MONTGOMERY private key any3 2b
C_Verify1 CKK_EC_MONTGOMERY public key any3, 2b 2 N/A
2250 2 Data length, signature length. 2251 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2252 specify the minimum and maximum supported number of bits in the field sizes, respectively. For this 2253 mechanism, the only allowed values are 255 and 448 as [XEDDSA] only defines curves of these two 2254 sizes. A Cryptoki implementation may support one or both of these curves and should set the 2255 ulMinKeySize and ulMaxKeySize fields accordingly. 2256
2257 2.3.16 EC mechanism parameters 2258 CK_EDDSA_PARAMS, CK_EDDSA_PARAMS_PTR
2259 CK_EDDSA_PARAMS is a structure that provides the parameters for the CKM_EDDSA signature 2260 mechanism. The structure is defined as follows: 2261 typedef struct CK_EDDSA_PARAMS { 2262 CK_BBOOL phFlag; 2263 CK_ULONG ulContextDataLen; 2264 CK_BYTE_PTR pContextData; 2265 } CK_EDDSA_PARAMS; 2266 2267 The fields of the structure have the following meanings: 2268 phFlag a Boolean value which indicates if Prehashed variant of EdDSA should 2269 used
2270 ulContextDataLen the length in bytes of the context data where 0 <= ulContextDataLen <= 2271 255.
2272 pContextData context data shared between the signer and verifier
2273 CK_EDDSA_PARAMS_PTR is a pointer to a CK_EDDSA_PARAMS. 2274 2275 CK_XEDDSA_PARAMS, CK_XEDDSA_PARAMS_PTR
2276 CK_XEDDSA_PARAMS is a structure that provides the parameters for the CKM_XEDDSA signature 2277 mechanism. The structure is defined as follows: 2278 typedef struct CK_XEDDSA_PARAMS { 2279 CK_XEDDSA_HASH_TYPE hash; 2280 } CK_XEDDSA_PARAMS; 2281 2282 The fields of the structure have the following meanings: 2283 hash a Hash mechanism to be used by the mechanism.
2284 CK_XEDDSA_PARAMS_PTR is a pointer to a CK_XEDDSA_PARAMS.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 60 of 278 2285 2286 CK_XEDDSA_HASH_TYPE, CK_XEDDSA_HASH_TYPE_PTR
2287 CK_XEDDSA_HASH_TYPE is used to indicate the hash function used in XEDDSA. It is defined as 2288 follows: 2289 typedef CK_ULONG CK_XEDDSA_HASH_TYPE; 2290 2291 The following table lists the defined functions. 2292 Table 46, EC: Key Derivation Functions Source Identifier CKM_BLAKE2B_256 CKM_BLAKE2B_512 CKM_SHA3_256 CKM_SHA3_512 CKM_SHA256 CKM_SHA512 2293 2294 CK_XEDDSA_HASH_TYPE_PTR is a pointer to a CK_XEDDSA_HASH_TYPE. 2295 2296 CK_EC_KDF_TYPE, CK_EC_KDF_TYPE_PTR
2297 CK_EC_KDF_TYPE is used to indicate the Key Derivation Function (KDF) applied to derive keying data 2298 from a shared secret. The key derivation function will be used by the EC key agreement schemes. It is 2299 defined as follows: 2300 typedef CK_ULONG CK_EC_KDF_TYPE; 2301 2302 The following table lists the defined functions. 2303 Table 47, EC: Key Derivation Functions Source Identifier CKD_NULL CKD_SHA1_KDF CKD_SHA224_KDF CKD_SHA256_KDF CKD_SHA384_KDF CKD_SHA512_KDF CKD_SHA3_224_KDF CKD_SHA3_256_KDF CKD_SHA3_384_KDF CKD_SHA3_512_KDF CKD_SHA1_KDF_SP800 CKD_SHA224_KDF_SP800 CKD_SHA256_KDF_SP800 CKD_SHA384_KDF_SP800
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 61 of 278 CKD_SHA512_KDF_SP800 CKD_SHA3_224_KDF_SP800 CKD_SHA3_256_KDF_SP800 CKD_SHA3_384_KDF_SP800 CKD_SHA3_512_KDF_SP800 CKD_BLAKE2B_160_KDF CKD_BLAKE2B_256_KDF CKD_BLAKE2B_384_KDF CKD_BLAKE2B_512_KDF 2304 The key derivation function CKD_NULL produces a raw shared secret value without applying any key 2305 derivation function. 2306 The key derivation functions 2307 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF, which are 2308 based on SHA-1, SHA-224, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 2309 respectively, derive keying data from the shared secret value as defined in [ANSI X9.63]. 2310 The key derivation functions 2311 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF_SP800, 2312 which are based on SHA-1, SHA-224, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 2313 respectively, derive keying data from the shared secret value as defined in [FIPS SP800-56A] section 2314 5.8.1.1. 2315 The key derivation functions CKD_BLAKE2B_[160|256|384|512]_KDF, which are based on the Blake2b 2316 family of hashes, derive keying data from the shared secret value as defined in [FIPS SP800-56A] section 2317 5.8.1.1.CK_EC_KDF_TYPE_PTR is a pointer to a CK_EC_KDF_TYPE. 2318 2319 CK_ECDH1_DERIVE_PARAMS, CK_ECDH1_DERIVE_PARAMS_PTR
2320 CK_ECDH1_DERIVE_PARAMS is a structure that provides the parameters for the 2321 CKM_ECDH1_DERIVE and CKM_ECDH1_COFACTOR_DERIVE key derivation mechanisms, where 2322 each party contributes one key pair. The structure is defined as follows: 2323 typedef struct CK_ECDH1_DERIVE_PARAMS { 2324 CK_EC_KDF_TYPE kdf; 2325 CK_ULONG ulSharedDataLen; 2326 CK_BYTE_PTR pSharedData; 2327 CK_ULONG ulPublicDataLen; 2328 CK_BYTE_PTR pPublicData; 2329 } CK_ECDH1_DERIVE_PARAMS; 2330 2331 The fields of the structure have the following meanings: 2332 kdf key derivation function used on the shared secret value
2333 ulSharedDataLen the length in bytes of the shared info
2334 pSharedData some data shared between the two parties
2335 ulPublicDataLen the length in bytes of the other party’s EC public key
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 62 of 278 2336 pPublicData1 pointer to other party’s EC public key value. A token MUST be able 2337 to accept this value encoded as a raw octet string (as per section 2338 A.5.2 of [ANSI X9.62]). A token MAY, in addition, support accepting 2339 this value as a DER-encoded ECPoint (as per section E.6 of [ANSI 2340 X9.62]) i.e. the same as a CKA_EC_POINT encoding. The calling 2341 application is responsible for converting the offered public key to the 2342 compressed or uncompressed forms of these encodings if the token 2343 does not support the offered form.
2344 With the key derivation function CKD_NULL, pSharedData must be NULL and ulSharedDataLen must be 2345 zero. With the key derivation functions 2346 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF, 2347 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF_SP800, an 2348 optional pSharedData may be supplied, which consists of some data shared by the two parties intending 2349 to share the shared secret. Otherwise, pSharedData must be NULL and ulSharedDataLen must be zero. 2350 CK_ECDH1_DERIVE_PARAMS_PTR is a pointer to a CK_ECDH1_DERIVE_PARAMS. 2351 CK_ECDH2_DERIVE_PARAMS, CK_ECDH2_DERIVE_PARAMS_PTR
2352 CK_ECDH2_DERIVE_PARAMS is a structure that provides the parameters to the 2353 CKM_ECMQV_DERIVE key derivation mechanism, where each party contributes two key pairs. The 2354 structure is defined as follows: 2355 typedef struct CK_ECDH2_DERIVE_PARAMS { 2356 CK_EC_KDF_TYPE kdf; 2357 CK_ULONG ulSharedDataLen; 2358 CK_BYTE_PTR pSharedData; 2359 CK_ULONG ulPublicDataLen; 2360 CK_BYTE_PTR pPublicData; 2361 CK_ULONG ulPrivateDataLen; 2362 CK_OBJECT_HANDLE hPrivateData; 2363 CK_ULONG ulPublicDataLen2; 2364 CK_BYTE_PTR pPublicData2; 2365 } CK_ECDH2_DERIVE_PARAMS; 2366 2367 The fields of the structure have the following meanings: 2368 kdf key derivation function used on the shared secret value
2369 ulSharedDataLen the length in bytes of the shared info
2370 pSharedData some data shared between the two parties
2371 ulPublicDataLen the length in bytes of the other party’s first EC public key
2372 pPublicData pointer to other party’s first EC public key value. Encoding rules are 2373 as per pPublicData of CK_ECDH1_DERIVE_PARAMS
2374 ulPrivateDataLen the length in bytes of the second EC private key
1 The encoding in V2.20 was not specified and resulted in different implementations choosing different encodings. Applications relying only on a V2.20 encoding (e.g. the DER variant) other than the one specified now (raw) may not work with all V2.30 compliant tokens.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 63 of 278 2375 hPrivateData key handle for second EC private key value
2376 ulPublicDataLen2 the length in bytes of the other party’s second EC public key
2377 pPublicData2 pointer to other party’s second EC public key value. Encoding rules 2378 are as per pPublicData of CK_ECDH1_DERIVE_PARAMS
2379 With the key derivation function CKD_NULL, pSharedData must be NULL and ulSharedDataLen must be 2380 zero. With the key derivation function CKD_SHA1_KDF, an optional pSharedData may be supplied, 2381 which consists of some data shared by the two parties intending to share the shared secret. Otherwise, 2382 pSharedData must be NULL and ulSharedDataLen must be zero. 2383 CK_ECDH2_DERIVE_PARAMS_PTR is a pointer to a CK_ECDH2_DERIVE_PARAMS. 2384 2385 CK_ECMQV_DERIVE_PARAMS, CK_ECMQV_DERIVE_PARAMS_PTR
2386 CK_ECMQV_DERIVE_PARAMS is a structure that provides the parameters to the 2387 CKM_ECMQV_DERIVE key derivation mechanism, where each party contributes two key pairs. The 2388 structure is defined as follows: 2389 typedef struct CK_ECMQV_DERIVE_PARAMS { 2390 CK_EC_KDF_TYPE kdf; 2391 CK_ULONG ulSharedDataLen; 2392 CK_BYTE_PTR pSharedData; 2393 CK_ULONG ulPublicDataLen; 2394 CK_BYTE_PTR pPublicData; 2395 CK_ULONG ulPrivateDataLen; 2396 CK_OBJECT_HANDLE hPrivateData; 2397 CK_ULONG ulPublicDataLen2; 2398 CK_BYTE_PTR pPublicData2; 2399 CK_OBJECT_HANDLE publicKey; 2400 } CK_ECMQV_DERIVE_PARAMS; 2401 2402 The fields of the structure have the following meanings: 2403 kdf key derivation function used on the shared secret value
2404 ulSharedDataLen the length in bytes of the shared info
2405 pSharedData some data shared between the two parties
2406 ulPublicDataLen the length in bytes of the other party’s first EC public key
2407 pPublicData pointer to other party’s first EC public key value. Encoding rules are 2408 as per pPublicData of CK_ECDH1_DERIVE_PARAMS
2409 ulPrivateDataLen the length in bytes of the second EC private key
2410 hPrivateData key handle for second EC private key value
2411 ulPublicDataLen2 the length in bytes of the other party’s second EC public key
2412 pPublicData2 pointer to other party’s second EC public key value. Encoding rules 2413 are as per pPublicData of CK_ECDH1_DERIVE_PARAMS
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 64 of 278 2414 publicKey Handle to the first party’s ephemeral public key
2415 With the key derivation function CKD_NULL, pSharedData must be NULL and ulSharedDataLen must be 2416 zero. With the key derivation functions 2417 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF, 2418 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF_SP800, an 2419 optional pSharedData may be supplied, which consists of some data shared by the two parties intending 2420 to share the shared secret. Otherwise, pSharedData must be NULL and ulSharedDataLen must be zero. 2421 CK_ECMQV_DERIVE_PARAMS_PTR is a pointer to a CK_ECMQV_DERIVE_PARAMS.
2422 2.3.17 Elliptic curve Diffie-Hellman key derivation 2423 The elliptic curve Diffie-Hellman (ECDH) key derivation mechanism, denoted CKM_ECDH1_DERIVE, is a 2424 mechanism for key derivation based on the Diffie-Hellman version of the elliptic curve key agreement 2425 scheme, as defined in ANSI X9.63, where each party contributes one key pair all using the same EC 2426 domain parameters. 2427 It has a parameter, a CK_ECDH1_DERIVE_PARAMS structure. 2428 This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE 2429 attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of 2430 the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism 2431 contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key 2432 type must be specified in the template. 2433 This mechanism has the following rules about key sensitivity and extractability: 2434 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 2435 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 2436 default value. 2437 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 2438 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 2439 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 2440 CKA_SENSITIVE attribute. 2441 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 2442 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 2443 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 2444 value from its CKA_EXTRACTABLE attribute. 2445 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2446 specify the minimum and maximum supported number of bits in the field sizes, respectively. For 2447 example, if a Cryptoki library supports only EC using a field of characteristic 2 which has between 2 200 2448 and 2300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, 2449 the number 2200 consists of a 1 bit followed by 200 0 bits. It is therefore a 201-bit number. Similarly, 2300 2450 is a 301-bit number). 2451 Constraints on key types are summarized in the following table: 2452 Table 48: ECDH: Allowed Key Types Function Key type C_Derive CKK_EC or CKK_EC_MONTGOMERY
2453 2.3.18 Elliptic curve Diffie-Hellman with cofactor key derivation 2454 The elliptic curve Diffie-Hellman (ECDH) with cofactor key derivation mechanism, denoted 2455 CKM_ECDH1_COFACTOR_DERIVE, is a mechanism for key derivation based on the cofactor Diffie- 2456 Hellman version of the elliptic curve key agreement scheme, as defined in ANSI X9.63, where each party 2457 contributes one key pair all using the same EC domain parameters. Cofactor multiplication is 2458 computationally efficient and helps to prevent security problems like small group attacks.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 65 of 278 2459 It has a parameter, a CK_ECDH1_DERIVE_PARAMS structure. 2460 This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE 2461 attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of 2462 the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism 2463 contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key 2464 type must be specified in the template. 2465 This mechanism has the following rules about key sensitivity and extractability: 2466 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 2467 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 2468 default value. 2469 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 2470 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 2471 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 2472 CKA_SENSITIVE attribute. 2473 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 2474 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 2475 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 2476 value from its CKA_EXTRACTABLE attribute. 2477 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2478 specify the minimum and maximum supported number of bits in the field sizes, respectively. For 2479 example, if a Cryptoki library supports only EC using a field of characteristic 2 which has between 2 200 2480 and 2300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, 2481 the number 2200 consists of a 1 bit followed by 200 0 bits. It is therefore a 201-bit number. Similarly, 2300 2482 is a 301-bit number). 2483 Constraints on key types are summarized in the following table: 2484 Table 49: ECDH with cofactor: Allowed Key Types Function Key type C_Derive CKK_EC
2485 2.3.19 Elliptic curve Menezes-Qu-Vanstone key derivation 2486 The elliptic curve Menezes-Qu-Vanstone (ECMQV) key derivation mechanism, denoted 2487 CKM_ECMQV_DERIVE, is a mechanism for key derivation based the MQV version of the elliptic curve 2488 key agreement scheme, as defined in ANSI X9.63, where each party contributes two key pairs all using 2489 the same EC domain parameters. 2490 It has a parameter, a CK_ECMQV_DERIVE_PARAMS structure. 2491 This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE 2492 attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of 2493 the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism 2494 contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key 2495 type must be specified in the template. 2496 This mechanism has the following rules about key sensitivity and extractability: 2497 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 2498 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 2499 default value. 2500 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 2501 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 2502 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 2503 CKA_SENSITIVE attribute. 2504 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 2505 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 66 of 278 2506 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 2507 value from its CKA_EXTRACTABLE attribute. 2508 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2509 specify the minimum and maximum supported number of bits in the field sizes, respectively. For 2510 example, if a Cryptoki library supports only EC using a field of characteristic 2 which has between 2200 2511 and 2300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, 2512 the number 2200 consists of a 1 bit followed by 200 0 bits. It is therefore a 201-bit number. Similarly, 2300 2513 is a 301-bit number). 2514 Constraints on key types are summarized in the following table: 2515 Table 50: ECDH MQV: Allowed Key Types Function Key type C_Derive CKK_EC
2516 2.3.20 ECDH AES KEY WRAP 2517 The ECDH AES KEY WRAP mechanism, denoted CKM_ECDH_AES_KEY_WRAP, is a mechanism 2518 based on elliptic curve public-key crypto-system and the AES key wrap mechanism. It supports single- 2519 part key wrapping; and key unwrapping. 2520 It has a parameter, a CK_ECDH_AES_KEY_WRAP_PARAMS structure. 2521 2522 The mechanism can wrap and unwrap an asymmetric target key of any length and type using an EC key. 2523 - A temporary AES key is derived from a temporary EC key and the wrapping EC key using the 2524 CKM_ECDH1_DERIVE mechanism. 2525 - The derived AES key is used for wrapping the target key using the 2526 CKM_AES_KEY_WRAP_KWP mechanism. 2527 2528 For wrapping, the mechanism - 2529 Generates a temporary random EC key (transport key) having the same parameters as the 2530 wrapping EC key (and domain parameters). Saves the transport key public key material. 2531 Performs ECDH operation using CKM_ECDH1_DERIVE with parameters of kdf, ulSharedDataLen 2532 and pSharedData using the private key of the transport EC key and the public key of wrapping EC 2533 key and gets the first ulAESKeyBits bits of the derived key to be the temporary AES key. 2534 Wraps the target key with the temporary AES key using CKM_AES_KEY_WRAP_KWP ([AES 2535 KEYWRAP] section 6.3). 2536 Zeroizes the temporary AES key and EC transport private key. 2537 Concatenates public key material of the transport key and output the concatenated blob. The first 2538 part is the public key material of the transport key and the second part is the wrapped target key. 2539 2540 The recommended format for an asymmetric target key being wrapped is as a PKCS8 PrivateKeyInfo 2541 2542 The use of Attributes in the PrivateKeyInfo structure is OPTIONAL. In case of conflicts between the object 2543 attribute template, and Attributes in the PrivateKeyInfo structure, an error should be thrown. 2544 2545 For unwrapping, the mechanism - 2546 Splits the input into two parts. The first part is the public key material of the transport key and the 2547 second part is the wrapped target key. The length of the first part is equal to the length of the public 2548 key material of the unwrapping EC key. 2549 Note: since the transport key and the wrapping EC key share the same domain, the length of the 2550 public key material of the transport key is the same length of the public key material of the 2551 unwrapping EC key.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 67 of 278 2552 Performs ECDH operation using CKM_ECDH1_DERIVE with parameters of kdf, ulSharedDataLen 2553 and pSharedData using the private part of unwrapping EC key and the public part of the transport 2554 EC key and gets first ulAESKeyBits bits of the derived key to be the temporary AES key. 2555 Un-wraps the target key from the second part with the temporary AES key using 2556 CKM_AES_KEY_WRAP_KWP ([AES KEYWRAP] section 6.3). 2557 Zeroizes the temporary AES key. 2558 2559 Table 51, CKM_ECDH_AES_KEY_WRAP Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive
Decrypt Verify VR1 Key Unwrap Pair CKM_ECDH_AES_KEY_WRAP
1SR = SignRecover, VR = VerifyRecover 2560 2561 Constraints on key types are summarized in the following table: 2562 Table 52: ECDH AES Key Wrap: Allowed Key Types Function Key type C_Derive CKK_EC or CKK_EC_MONTGOMERY
2563 2.3.21 ECDH AES KEY WRAP mechanism parameters
2564 CK_ECDH_AES_KEY_WRAP_PARAMS; CK_ECDH_AES_KEY_WRAP_PARAMS_PTR
2565 CK_ECDH_AES_KEY_WRAP_PARAMS is a structure that provides the parameters to the 2566 CKM_ECDH_AES_KEY_WRAP mechanism. It is defined as follows: 2567 2568 typedef struct CK_ECDH_AES_KEY_WRAP_PARAMS { 2569 CK_ULONG ulAESKeyBits; 2570 CK_EC_KDF_TYPE kdf; 2571 CK_ULONG ulSharedDataLen; 2572 CK_BYTE_PTR pSharedData; 2573 } CK_ECDH_AES_KEY_WRAP_PARAMS; 2574 2575 The fields of the structure have the following meanings: 2576 2577 ulAESKeyBits length of the temporary AES key in bits. Can be only 128, 192 or 2578 256.
2579 kdf key derivation function used on the shared secret value to generate 2580 AES key.
2581 ulSharedDataLen the length in bytes of the shared info
2582 pSharedData Some data shared between the two parties
2583
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 68 of 278 2584 CK_ECDH_AES_KEY_WRAP_PARAMS_PTR is a pointer to a 2585 CK_ECDH_AES_KEY_WRAP_PARAMS. 2586
2587 2.3.22 FIPS 186-4 2588 When CKM_ECDSA is operated in FIPS mode, the curves SHALL either be NIST recommended curves 2589 (with a fixed set of domain parameters) or curves with domain parameters generated as specified by 2590 ANSI X9.64. The NIST recommended curves are: 2591 2592 P-192, P-224, P-256, P-384, P-521 2593 K-163, B-163, K-233, B-233 2594 K-283, B-283, K-409, B-409 2595 K-571, B-571
2596 2.4 Diffie-Hellman 2597 Table 53, Diffie-Hellman Mechanisms vs. Functions
Functions
Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_DH_PKCS_KEY_PAIR_GEN CKM_DH_PKCS_PARAMETER_GEN CKM_DH_PKCS_DERIVE CKM_X9_42_DH_KEY_PAIR_GEN CKM_X9_42_DH_PKCS_PARAMETER_GEN CKM_X9_42_DH_DERIVE CKM_X9_42_DH_HYBRID_DERIVE CKM_X9_42_MQV_DERIVE
2598 2.4.1 Definitions 2599 This section defines the key type “CKK_DH” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE 2600 attribute of [DH] key objects. 2601 Mechanisms: 2602 CKM_DH_PKCS_KEY_PAIR_GEN 2603 CKM_DH_PKCS_DERIVE 2604 CKM_X9_42_DH_KEY_PAIR_GEN 2605 CKM_X9_42_DH_DERIVE 2606 CKM_X9_42_DH_HYBRID_DERIVE 2607 CKM_X9_42_MQV_DERIVE 2608 CKM_DH_PKCS_PARAMETER_GEN 2609 CKM_X9_42_DH_PARAMETER_GEN
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 69 of 278 2610 2.4.2 Diffie-Hellman public key objects 2611 Diffie-Hellman public key objects (object class CKO_PUBLIC_KEY, key type CKK_DH) hold Diffie- 2612 Hellman public keys. The following table defines the Diffie-Hellman public key object attributes, in 2613 addition to the common attributes defined for this object class: 2614 Table 54, Diffie-Hellman Public Key Object Attributes Attribute Data type Meaning CKA_PRIME1,3 Big integer Prime p CKA_BASE1,3 Big integer Base g CKA_VALUE1,4 Big integer Public value y 2615 - Refer to [PKCS11-Base] table 11 for footnotes 2616 The CKA_PRIME and CKA_BASE attribute values are collectively the “Diffie-Hellman domain 2617 parameters”. Depending on the token, there may be limits on the length of the key components. See 2618 PKCS #3 for more information on Diffie-Hellman keys. 2619 The following is a sample template for creating a Diffie-Hellman public key object: 2620 CK_OBJECT_CLASS class = CKO_PUBLIC_KEY; 2621 CK_KEY_TYPE keyType = CKK_DH; 2622 CK_UTF8CHAR label[] = “A Diffie-Hellman public key object”; 2623 CK_BYTE prime[] = {...}; 2624 CK_BYTE base[] = {...}; 2625 CK_BYTE value[] = {...}; 2626 CK_BBOOL true = CK_TRUE; 2627 CK_ATTRIBUTE template[] = { 2628 {CKA_CLASS, &class, sizeof(class)}, 2629 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 2630 {CKA_TOKEN, &true, sizeof(true)}, 2631 {CKA_LABEL, label, sizeof(label)-1}, 2632 {CKA_PRIME, prime, sizeof(prime)}, 2633 {CKA_BASE, base, sizeof(base)}, 2634 {CKA_VALUE, value, sizeof(value)} 2635 };
2636 2.4.3 X9.42 Diffie-Hellman public key objects 2637 X9.42 Diffie-Hellman public key objects (object class CKO_PUBLIC_KEY, key type CKK_X9_42_DH) 2638 hold X9.42 Diffie-Hellman public keys. The following table defines the X9.42 Diffie-Hellman public key 2639 object attributes, in addition to the common attributes defined for this object class: 2640 Table 55, X9.42 Diffie-Hellman Public Key Object Attributes Attribute Data type Meaning CKA_PRIME1,3 Big integer Prime p ( 1024 bits, in steps of 256 bits) CKA_BASE1,3 Big integer Base g CKA_SUBPRIME1,3 Big integer Subprime q ( 160 bits) CKA_VALUE1,4 Big integer Public value y 2641 - Refer to [PKCS11-Base] table 11 for footnotes 2642 The CKA_PRIME, CKA_BASE and CKA_SUBPRIME attribute values are collectively the “X9.42 Diffie- 2643 Hellman domain parameters”. See the ANSI X9.42 standard for more information on X9.42 Diffie- 2644 Hellman keys.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 70 of 278 2645 The following is a sample template for creating a X9.42 Diffie-Hellman public key object: 2646 CK_OBJECT_CLASS class = CKO_PUBLIC_KEY; 2647 CK_KEY_TYPE keyType = CKK_X9_42_DH; 2648 CK_UTF8CHAR label[] = “A X9.42 Diffie-Hellman public key 2649 object”; 2650 CK_BYTE prime[] = {...}; 2651 CK_BYTE base[] = {...}; 2652 CK_BYTE subprime[] = {...}; 2653 CK_BYTE value[] = {...}; 2654 CK_BBOOL true = CK_TRUE; 2655 CK_ATTRIBUTE template[] = { 2656 {CKA_CLASS, &class, sizeof(class)}, 2657 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 2658 {CKA_TOKEN, &true, sizeof(true)}, 2659 {CKA_LABEL, label, sizeof(label)-1}, 2660 {CKA_PRIME, prime, sizeof(prime)}, 2661 {CKA_BASE, base, sizeof(base)}, 2662 {CKA_SUBPRIME, subprime, sizeof(subprime)}, 2663 {CKA_VALUE, value, sizeof(value)} 2664 };
2665 2.4.4 Diffie-Hellman private key objects 2666 Diffie-Hellman private key objects (object class CKO_PRIVATE_KEY, key type CKK_DH) hold Diffie- 2667 Hellman private keys. The following table defines the Diffie-Hellman private key object attributes, in 2668 addition to the common attributes defined for this object class: 2669 Table 56, Diffie-Hellman Private Key Object Attributes Attribute Data type Meaning CKA_PRIME1,4,6 Big integer Prime p CKA_BASE1,4,6 Big integer Base g CKA_VALUE1,4,6,7 Big integer Private value x CKA_VALUE_BITS2,6 CK_ULONG Length in bits of private value x 2670 - Refer to [PKCS11-Base] table 11 for footnotes 2671 The CKA_PRIME and CKA_BASE attribute values are collectively the “Diffie-Hellman domain 2672 parameters”. Depending on the token, there may be limits on the length of the key components. See 2673 PKCS #3 for more information on Diffie-Hellman keys. 2674 Note that when generating a Diffie-Hellman private key, the Diffie-Hellman parameters are not specified in 2675 the key’s template. This is because Diffie-Hellman private keys are only generated as part of a Diffie- 2676 Hellman key pair, and the Diffie-Hellman parameters for the pair are specified in the template for the 2677 Diffie-Hellman public key. 2678 The following is a sample template for creating a Diffie-Hellman private key object: 2679 CK_OBJECT_CLASS class = CKO_PRIVATE_KEY; 2680 CK_KEY_TYPE keyType = CKK_DH; 2681 CK_UTF8CHAR label[] = “A Diffie-Hellman private key object”; 2682 CK_BYTE subject[] = {...}; 2683 CK_BYTE id[] = {123}; 2684 CK_BYTE prime[] = {...}; 2685 CK_BYTE base[] = {...};
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 71 of 278 2686 CK_BYTE value[] = {...}; 2687 CK_BBOOL true = CK_TRUE; 2688 CK_ATTRIBUTE template[] = { 2689 {CKA_CLASS, &class, sizeof(class)}, 2690 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 2691 {CKA_TOKEN, &true, sizeof(true)}, 2692 {CKA_LABEL, label, sizeof(label)-1}, 2693 {CKA_SUBJECT, subject, sizeof(subject)}, 2694 {CKA_ID, id, sizeof(id)}, 2695 {CKA_SENSITIVE, &true, sizeof(true)}, 2696 {CKA_DERIVE, &true, sizeof(true)}, 2697 {CKA_PRIME, prime, sizeof(prime)}, 2698 {CKA_BASE, base, sizeof(base)}, 2699 {CKA_VALUE, value, sizeof(value)} 2700 };
2701 2.4.5 X9.42 Diffie-Hellman private key objects 2702 X9.42 Diffie-Hellman private key objects (object class CKO_PRIVATE_KEY, key type CKK_X9_42_DH) 2703 hold X9.42 Diffie-Hellman private keys. The following table defines the X9.42 Diffie-Hellman private key 2704 object attributes, in addition to the common attributes defined for this object class: 2705 Table 57, X9.42 Diffie-Hellman Private Key Object Attributes Attribute Data type Meaning CKA_PRIME1,4,6 Big integer Prime p ( 1024 bits, in steps of 256 bits) CKA_BASE1,4,6 Big integer Base g CKA_SUBPRIME1,4,6 Big integer Subprime q ( 160 bits) CKA_VALUE1,4,6,7 Big integer Private value x 2706 - Refer to [PKCS11-Base] table 11 for footnotes 2707 The CKA_PRIME, CKA_BASE and CKA_SUBPRIME attribute values are collectively the “X9.42 Diffie- 2708 Hellman domain parameters”. Depending on the token, there may be limits on the length of the key 2709 components. See the ANSI X9.42 standard for more information on X9.42 Diffie-Hellman keys. 2710 Note that when generating a X9.42 Diffie-Hellman private key, the X9.42 Diffie-Hellman domain 2711 parameters are not specified in the key’s template. This is because X9.42 Diffie-Hellman private keys are 2712 only generated as part of a X9.42 Diffie-Hellman key pair, and the X9.42 Diffie-Hellman domain 2713 parameters for the pair are specified in the template for the X9.42 Diffie-Hellman public key. 2714 The following is a sample template for creating a X9.42 Diffie-Hellman private key object: 2715 CK_OBJECT_CLASS class = CKO_PRIVATE_KEY; 2716 CK_KEY_TYPE keyType = CKK_X9_42_DH; 2717 CK_UTF8CHAR label[] = “A X9.42 Diffie-Hellman private key object”; 2718 CK_BYTE subject[] = {...}; 2719 CK_BYTE id[] = {123}; 2720 CK_BYTE prime[] = {...}; 2721 CK_BYTE base[] = {...}; 2722 CK_BYTE subprime[] = {...}; 2723 CK_BYTE value[] = {...}; 2724 CK_BBOOL true = CK_TRUE; 2725 CK_ATTRIBUTE template[] = { 2726 {CKA_CLASS, &class, sizeof(class)},
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 72 of 278 2727 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 2728 {CKA_TOKEN, &true, sizeof(true)}, 2729 {CKA_LABEL, label, sizeof(label)-1}, 2730 {CKA_SUBJECT, subject, sizeof(subject)}, 2731 {CKA_ID, id, sizeof(id)}, 2732 {CKA_SENSITIVE, &true, sizeof(true)}, 2733 {CKA_DERIVE, &true, sizeof(true)}, 2734 {CKA_PRIME, prime, sizeof(prime)}, 2735 {CKA_BASE, base, sizeof(base)}, 2736 {CKA_SUBPRIME, subprime, sizeof(subprime)}, 2737 {CKA_VALUE, value, sizeof(value)} 2738 };
2739 2.4.6 Diffie-Hellman domain parameter objects 2740 Diffie-Hellman domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type 2741 CKK_DH) hold Diffie-Hellman domain parameters. The following table defines the Diffie-Hellman domain 2742 parameter object attributes, in addition to the common attributes defined for this object class: 2743 Table 58, Diffie-Hellman Domain Parameter Object Attributes Attribute Data type Meaning CKA_PRIME1,4 Big integer Prime p CKA_BASE1,4 Big integer Base g CKA_PRIME_BITS2,3 CK_ULONG Length of the prime value. 2744 - Refer to [PKCS11-Base] table 11 for footnotes 2745 The CKA_PRIME and CKA_BASE attribute values are collectively the “Diffie-Hellman domain 2746 parameters”. Depending on the token, there may be limits on the length of the key components. See 2747 PKCS #3 for more information on Diffie-Hellman domain parameters. 2748 The following is a sample template for creating a Diffie-Hellman domain parameter object: 2749 CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS; 2750 CK_KEY_TYPE keyType = CKK_DH; 2751 CK_UTF8CHAR label[] = “A Diffie-Hellman domain parameters 2752 object”; 2753 CK_BYTE prime[] = {...}; 2754 CK_BYTE base[] = {...}; 2755 CK_BBOOL true = CK_TRUE; 2756 CK_ATTRIBUTE template[] = { 2757 {CKA_CLASS, &class, sizeof(class)}, 2758 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 2759 {CKA_TOKEN, &true, sizeof(true)}, 2760 {CKA_LABEL, label, sizeof(label)-1}, 2761 {CKA_PRIME, prime, sizeof(prime)}, 2762 {CKA_BASE, base, sizeof(base)}, 2763 };
2764 2.4.7 X9.42 Diffie-Hellman domain parameters objects 2765 X9.42 Diffie-Hellman domain parameters objects (object class CKO_DOMAIN_PARAMETERS, key type 2766 CKK_X9_42_DH) hold X9.42 Diffie-Hellman domain parameters. The following table defines the X9.42
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 73 of 278 2767 Diffie-Hellman domain parameters object attributes, in addition to the common attributes defined for this 2768 object class: 2769 Table 59, X9.42 Diffie-Hellman Domain Parameters Object Attributes Attribute Data type Meaning CKA_PRIME1,4 Big integer Prime p ( 1024 bits, in steps of 256 bits) CKA_BASE1,4 Big integer Base g CKA_SUBPRIME1,4 Big integer Subprime q ( 160 bits) CKA_PRIME_BITS2,3 CK_ULONG Length of the prime value. CKA_SUBPRIME_BITS2,3 CK_ULONG Length of the subprime value. 2770 - Refer to [PKCS11-Base] table 11 for footnotes 2771 The CKA_PRIME, CKA_BASE and CKA_SUBPRIME attribute values are collectively the “X9.42 Diffie- 2772 Hellman domain parameters”. Depending on the token, there may be limits on the length of the domain 2773 parameters components. See the ANSI X9.42 standard for more information on X9.42 Diffie-Hellman 2774 domain parameters. 2775 The following is a sample template for creating a X9.42 Diffie-Hellman domain parameters object: 2776 CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS; 2777 CK_KEY_TYPE keyType = CKK_X9_42_DH; 2778 CK_UTF8CHAR label[] = “A X9.42 Diffie-Hellman domain 2779 parameters object”; 2780 CK_BYTE prime[] = {...}; 2781 CK_BYTE base[] = {...}; 2782 CK_BYTE subprime[] = {...}; 2783 CK_BBOOL true = CK_TRUE; 2784 CK_ATTRIBUTE template[] = { 2785 {CKA_CLASS, &class, sizeof(class)}, 2786 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 2787 {CKA_TOKEN, &true, sizeof(true)}, 2788 {CKA_LABEL, label, sizeof(label)-1}, 2789 {CKA_PRIME, prime, sizeof(prime)}, 2790 {CKA_BASE, base, sizeof(base)}, 2791 {CKA_SUBPRIME, subprime, sizeof(subprime)}, 2792 };
2793 2.4.8 PKCS #3 Diffie-Hellman key pair generation 2794 The PKCS #3 Diffie-Hellman key pair generation mechanism, denoted 2795 CKM_DH_PKCS_KEY_PAIR_GEN, is a key pair generation mechanism based on Diffie-Hellman key 2796 agreement, as defined in PKCS #3. This is what PKCS #3 calls “phase I”. It does not have a parameter. 2797 The mechanism generates Diffie-Hellman public/private key pairs with a particular prime and base, as 2798 specified in the CKA_PRIME and CKA_BASE attributes of the template for the public key. If the 2799 CKA_VALUE_BITS attribute of the private key is specified, the mechanism limits the length in bits of the 2800 private value, as described in PKCS #3. 2801 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 2802 public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, and CKA_VALUE (and 2803 the CKA_VALUE_BITS attribute, if it is not already provided in the template) attributes to the new private 2804 key; other attributes required by the Diffie-Hellman public and private key types must be specified in the 2805 templates. 2806 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2807 specify the supported range of Diffie-Hellman prime sizes, in bits.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 74 of 278 2808 2.4.9 PKCS #3 Diffie-Hellman domain parameter generation 2809 The PKCS #3 Diffie-Hellman domain parameter generation mechanism, denoted 2810 CKM_DH_PKCS_PARAMETER_GEN, is a domain parameter generation mechanism based on Diffie- 2811 Hellman key agreement, as defined in PKCS #3. 2812 It does not have a parameter. 2813 The mechanism generates Diffie-Hellman domain parameters with a particular prime length in bits, as 2814 specified in the CKA_PRIME_BITS attribute of the template. 2815 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, and 2816 CKA_PRIME_BITS attributes to the new object. Other attributes supported by the Diffie-Hellman domain 2817 parameter types may also be specified in the template, or else are assigned default initial values. 2818 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2819 specify the supported range of Diffie-Hellman prime sizes, in bits.
2820 2.4.10 PKCS #3 Diffie-Hellman key derivation 2821 The PKCS #3 Diffie-Hellman key derivation mechanism, denoted CKM_DH_PKCS_DERIVE, is a 2822 mechanism for key derivation based on Diffie-Hellman key agreement, as defined in PKCS #3. This is 2823 what PKCS #3 calls “phase II”. 2824 It has a parameter, which is the public value of the other party in the key agreement protocol, represented 2825 as a Cryptoki “Big integer” (i.e., a sequence of bytes, most-significant byte first). 2826 This mechanism derives a secret key from a Diffie-Hellman private key and the public value of the other 2827 party. It computes a Diffie-Hellman secret value from the public value and private key according to PKCS 2828 #3, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one 2829 and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes 2830 bytes from the leading end of the secret value.) The mechanism contributes the result as the 2831 CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the 2832 template. 2833 This mechanism has the following rules about key sensitivity and extractability2: 2834 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 2835 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 2836 default value. 2837 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 2838 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 2839 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 2840 CKA_SENSITIVE attribute. 2841 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 2842 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 2843 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 2844 value from its CKA_EXTRACTABLE attribute. 2845 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2846 specify the supported range of Diffie-Hellman prime sizes, in bits.
2 Note that the rules regarding the CKA_SENSITIVE, CKA_EXTRACTABLE, CKA_ALWAYS_SENSITIVE, and CKA_NEVER_EXTRACTABLE attributes have changed in version 2.11 to match the policy used by other key derivation mechanisms such as CKM_SSL3_MASTER_KEY_DERIVE.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 75 of 278 2847 2.4.11 X9.42 Diffie-Hellman mechanism parameters 2848 CK_X9_42_DH_KDF_TYPE, CK_X9_42_DH_KDF_TYPE_PTR
2849 CK_X9_42_DH_KDF_TYPE is used to indicate the Key Derivation Function (KDF) applied to derive 2850 keying data from a shared secret. The key derivation function will be used by the X9.42 Diffie-Hellman 2851 key agreement schemes. It is defined as follows: 2852 typedef CK_ULONG CK_X9_42_DH_KDF_TYPE; 2853 2854 The following table lists the defined functions. 2855 Table 60, X9.42 Diffie-Hellman Key Derivation Functions Source Identifier CKD_NULL CKD_SHA1_KDF_ASN1 CKD_SHA1_KDF_CONCATENATE 2856 The key derivation function CKD_NULL produces a raw shared secret value without applying any key 2857 derivation function whereas the key derivation functions CKD_SHA1_KDF_ASN1 and 2858 CKD_SHA1_KDF_CONCATENATE, which are both based on SHA-1, derive keying data from the 2859 shared secret value as defined in the ANSI X9.42 standard. 2860 CK_X9_42_DH_KDF_TYPE_PTR is a pointer to a CK_X9_42_DH_KDF_TYPE.
2861 CK_X9_42_DH1_DERIVE_PARAMS, CK_X9_42_DH1_DERIVE_PARAMS_PTR
2862 CK_X9_42_DH1_DERIVE_PARAMS is a structure that provides the parameters to the 2863 CKM_X9_42_DH_DERIVE key derivation mechanism, where each party contributes one key pair. The 2864 structure is defined as follows: 2865 typedef struct CK_X9_42_DH1_DERIVE_PARAMS { 2866 CK_X9_42_DH_KDF_TYPE kdf; 2867 CK_ULONG ulOtherInfoLen; 2868 CK_BYTE_PTR pOtherInfo; 2869 CK_ULONG ulPublicDataLen; 2870 CK_BYTE_PTR pPublicData; 2871 } CK_X9_42_DH1_DERIVE_PARAMS; 2872 2873 The fields of the structure have the following meanings: 2874 kdf key derivation function used on the shared secret value
2875 ulOtherInfoLen the length in bytes of the other info
2876 pOtherInfo some data shared between the two parties
2877 ulPublicDataLen the length in bytes of the other party’s X9.42 Diffie-Hellman public 2878 key
2879 pPublicData pointer to other party’s X9.42 Diffie-Hellman public key value
2880 With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero. 2881 With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains 2882 an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by 2883 the two parties intending to share the shared secret. With the key derivation function
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 76 of 278 2884 CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some 2885 data shared by the two parties intending to share the shared secret. Otherwise, pOtherInfo must be 2886 NULL and ulOtherInfoLen must be zero. 2887 CK_X9_42_DH1_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_DH1_DERIVE_PARAMS.
2888 CK_X9_42_DH2_DERIVE_PARAMS, CK_X9_42_DH2_DERIVE_PARAMS_PTR
2889 CK_X9_42_DH2_DERIVE_PARAMS is a structure that provides the parameters to the 2890 CKM_X9_42_DH_HYBRID_DERIVE and CKM_X9_42_MQV_DERIVE key derivation mechanisms, 2891 where each party contributes two key pairs. The structure is defined as follows: 2892 typedef struct CK_X9_42_DH2_DERIVE_PARAMS { 2893 CK_X9_42_DH_KDF_TYPE kdf; 2894 CK_ULONG ulOtherInfoLen; 2895 CK_BYTE_PTR pOtherInfo; 2896 CK_ULONG ulPublicDataLen; 2897 CK_BYTE_PTR pPublicData; 2898 CK_ULONG ulPrivateDataLen; 2899 CK_OBJECT_HANDLE hPrivateData; 2900 CK_ULONG ulPublicDataLen2; 2901 CK_BYTE_PTR pPublicData2; 2902 } CK_X9_42_DH2_DERIVE_PARAMS; 2903 2904 The fields of the structure have the following meanings: 2905 kdf key derivation function used on the shared secret value
2906 ulOtherInfoLen the length in bytes of the other info
2907 pOtherInfo some data shared between the two parties
2908 ulPublicDataLen the length in bytes of the other party’s first X9.42 Diffie-Hellman 2909 public key
2910 pPublicData pointer to other party’s first X9.42 Diffie-Hellman public key value
2911 ulPrivateDataLen the length in bytes of the second X9.42 Diffie-Hellman private key
2912 hPrivateData key handle for second X9.42 Diffie-Hellman private key value
2913 ulPublicDataLen2 the length in bytes of the other party’s second X9.42 Diffie-Hellman 2914 public key
2915 pPublicData2 pointer to other party’s second X9.42 Diffie-Hellman public key 2916 value
2917 With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero. 2918 With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains 2919 an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by 2920 the two parties intending to share the shared secret. With the key derivation function 2921 CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some 2922 data shared by the two parties intending to share the shared secret. Otherwise, pOtherInfo must be 2923 NULL and ulOtherInfoLen must be zero. 2924 CK_X9_42_DH2_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_DH2_DERIVE_PARAMS.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 77 of 278 2925 CK_X9_42_MQV_DERIVE_PARAMS, CK_X9_42_MQV_DERIVE_PARAMS_PTR
2926 CK_X9_42_MQV_DERIVE_PARAMS is a structure that provides the parameters to the 2927 CKM_X9_42_MQV_DERIVE key derivation mechanism, where each party contributes two key pairs. The 2928 structure is defined as follows: 2929 typedef struct CK_X9_42_MQV_DERIVE_PARAMS { 2930 CK_X9_42_DH_KDF_TYPE kdf; 2931 CK_ULONG ulOtherInfoLen; 2932 CK_BYTE_PTR pOtherInfo; 2933 CK_ULONG ulPublicDataLen; 2934 CK_BYTE_PTR pPublicData; 2935 CK_ULONG ulPrivateDataLen; 2936 CK_OBJECT_HANDLE hPrivateData; 2937 CK_ULONG ulPublicDataLen2; 2938 CK_BYTE_PTR pPublicData2; 2939 CK_OBJECT_HANDLE publicKey; 2940 } CK_X9_42_MQV_DERIVE_PARAMS; 2941 2942 The fields of the structure have the following meanings: 2943 kdf key derivation function used on the shared secret value
2944 ulOtherInfoLen the length in bytes of the other info
2945 pOtherInfo some data shared between the two parties
2946 ulPublicDataLen the length in bytes of the other party’s first X9.42 Diffie-Hellman 2947 public key
2948 pPublicData pointer to other party’s first X9.42 Diffie-Hellman public key value
2949 ulPrivateDataLen the length in bytes of the second X9.42 Diffie-Hellman private key
2950 hPrivateData key handle for second X9.42 Diffie-Hellman private key value
2951 ulPublicDataLen2 the length in bytes of the other party’s second X9.42 Diffie-Hellman 2952 public key
2953 pPublicData2 pointer to other party’s second X9.42 Diffie-Hellman public key 2954 value
2955 publicKey Handle to the first party’s ephemeral public key
2956 With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero. 2957 With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains 2958 an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by 2959 the two parties intending to share the shared secret. With the key derivation function 2960 CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some 2961 data shared by the two parties intending to share the shared secret. Otherwise, pOtherInfo must be 2962 NULL and ulOtherInfoLen must be zero. 2963 CK_X9_42_MQV_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_MQV_DERIVE_PARAMS.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 78 of 278 2964 2.4.12 X9.42 Diffie-Hellman key pair generation 2965 The X9.42 Diffie-Hellman key pair generation mechanism, denoted CKM_X9_42_DH_KEY_PAIR_GEN, 2966 is a key pair generation mechanism based on Diffie-Hellman key agreement, as defined in the ANSI 2967 X9.42 standard. 2968 It does not have a parameter. 2969 The mechanism generates X9.42 Diffie-Hellman public/private key pairs with a particular prime, base and 2970 subprime, as specified in the CKA_PRIME, CKA_BASE and CKA_SUBPRIME attributes of the template 2971 for the public key. 2972 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 2973 public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, CKA_SUBPRIME, and 2974 CKA_VALUE attributes to the new private key; other attributes required by the X9.42 Diffie-Hellman 2975 public and private key types must be specified in the templates. 2976 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2977 specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.
2978 2.4.13 X9.42 Diffie-Hellman domain parameter generation 2979 The X9.42 Diffie-Hellman domain parameter generation mechanism, denoted 2980 CKM_X9_42_DH_PARAMETER_GEN, is a domain parameters generation mechanism based on X9.42 2981 Diffie-Hellman key agreement, as defined in the ANSI X9.42 standard. 2982 It does not have a parameter. 2983 The mechanism generates X9.42 Diffie-Hellman domain parameters with particular prime and subprime 2984 length in bits, as specified in the CKA_PRIME_BITS and CKA_SUBPRIME_BITS attributes of the 2985 template for the domain parameters. 2986 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, 2987 CKA_SUBPRIME, CKA_PRIME_BITS and CKA_SUBPRIME_BITS attributes to the new object. Other 2988 attributes supported by the X9.42 Diffie-Hellman domain parameter types may also be specified in the 2989 template for the domain parameters, or else are assigned default initial values. 2990 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 2991 specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits.
2992 2.4.14 X9.42 Diffie-Hellman key derivation 2993 The X9.42 Diffie-Hellman key derivation mechanism, denoted CKM_X9_42_DH_DERIVE, is a 2994 mechanism for key derivation based on the Diffie-Hellman key agreement scheme, as defined in the 2995 ANSI X9.42 standard, where each party contributes one key pair, all using the same X9.42 Diffie-Hellman 2996 domain parameters. 2997 It has a parameter, a CK_X9_42_DH1_DERIVE_PARAMS structure. 2998 This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE 2999 attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of 3000 the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism 3001 contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key 3002 type must be specified in the template. Note that in order to validate this mechanism it may be required to 3003 use the CKA_VALUE attribute as the key of a general-length MAC mechanism (e.g. 3004 CKM_SHA_1_HMAC_GENERAL) over some test data. 3005 This mechanism has the following rules about key sensitivity and extractability: 3006 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 3007 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 3008 default value. 3009 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 3010 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 79 of 278 3011 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 3012 CKA_SENSITIVE attribute. 3013 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 3014 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 3015 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 3016 value from its CKA_EXTRACTABLE attribute. 3017 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3018 specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.
3019 2.4.15 X9.42 Diffie-Hellman hybrid key derivation 3020 The X9.42 Diffie-Hellman hybrid key derivation mechanism, denoted 3021 CKM_X9_42_DH_HYBRID_DERIVE, is a mechanism for key derivation based on the Diffie-Hellman 3022 hybrid key agreement scheme, as defined in the ANSI X9.42 standard, where each party contributes two 3023 key pair, all using the same X9.42 Diffie-Hellman domain parameters. 3024 It has a parameter, a CK_X9_42_DH2_DERIVE_PARAMS structure. 3025 This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE 3026 attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of 3027 the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism 3028 contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key 3029 type must be specified in the template. Note that in order to validate this mechanism it may be required to 3030 use the CKA_VALUE attribute as the key of a general-length MAC mechanism (e.g. 3031 CKM_SHA_1_HMAC_GENERAL) over some test data. 3032 This mechanism has the following rules about key sensitivity and extractability: 3033 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 3034 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 3035 default value. 3036 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 3037 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 3038 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 3039 CKA_SENSITIVE attribute. 3040 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 3041 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 3042 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 3043 value from its CKA_EXTRACTABLE attribute. 3044 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3045 specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.
3046 2.4.16 X9.42 Diffie-Hellman Menezes-Qu-Vanstone key derivation 3047 The X9.42 Diffie-Hellman Menezes-Qu-Vanstone (MQV) key derivation mechanism, denoted 3048 CKM_X9_42_MQV_DERIVE, is a mechanism for key derivation based the MQV scheme, as defined in 3049 the ANSI X9.42 standard, where each party contributes two key pairs, all using the same X9.42 Diffie- 3050 Hellman domain parameters. 3051 It has a parameter, a CK_X9_42_MQV_DERIVE_PARAMS structure. 3052 This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE 3053 attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of 3054 the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism 3055 contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key 3056 type must be specified in the template. Note that in order to validate this mechanism it may be required to 3057 use the CKA_VALUE attribute as the key of a general-length MAC mechanism (e.g. 3058 CKM_SHA_1_HMAC_GENERAL) over some test data. 3059 This mechanism has the following rules about key sensitivity and extractability: pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 80 of 278 3060 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 3061 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 3062 default value. 3063 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 3064 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 3065 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 3066 CKA_SENSITIVE attribute. 3067 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 3068 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 3069 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 3070 value from its CKA_EXTRACTABLE attribute. 3071 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3072 specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.
3073 2.5 Extended Triple Diffie-Hellman (x3dh) 3074 The Extended Triple Diffie-Hellman mechanism described here is the one described in 3075 [SIGNAL]. 3076 3077 Table 61, Extended Triple Diffie-Hellman Mechanisms vs. Functions
Functions
Encrypt Sign SR Gen. Wrap Derive Mechanism & & & Digest Key/ & Decrypt Verify VR1 Key Unwr Pair ap CKM_X3DH_INITIATE CKM_X3DH_RESPOND
3078 2.5.1 Definitions 3079 Mechanisms: 3080 CKM_X3DH_INITIATE 3081 CKM_X3DH_RESPOND
3082 2.5.2 Extended Triple Diffie-Hellman key objects 3083 Extended Triple Diffie-Hellman uses Elliptic Curve keys in Montgomery representation 3084 (CKK_EC_MONTGOMERY). Three different kinds of keys are used, they differ in their lifespan: 3085 identity keys are long-term keys, which identify the peer, 3086 prekeys are short-term keys, which should be rotated often (weekly to hourly) 3087 onetime prekeys are keys, which should be used only once. 3088 Any peer intending to be contacted using X3DH must publish their so-called prekey-bundle, consisting of 3089 their: 3090 public Identity key, 3091 current prekey, signed using XEDDA with their identity key 3092 optionally a batch of One-time public keys.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 81 of 278 3093 2.5.3 Initiating an Extended Triple Diffie-Hellman key exchange 3094 Initiating an Extended Triple Diffie-Hellman key exchange starts by retrieving the following required public 3095 keys (the so-called prekey-bundle) of the other peer: the Identity key, the signed public Prekey, and 3096 optionally one One-time public key. 3097 When the necessary key material is available, the initiating party calls 3098 CKM_X3DH_INITIATE, also providing the following additional parameters: 3099 the initiators identity key 3100 the initiators ephemeral key (a fresh, one-time CKK_EC_MONTGOMERY type key) 3101 3102 CK_X3DH_INITIATE_PARAMS is a structure that provides the parameters to the CKM_X3DH_INITIATE 3103 key exchange mechanism. The structure is defined as follows: 3104 typedef struct CK_X3DH_INITIATE_PARAMS { 3105 CK_X3DH_KDF_TYPE kdf; 3106 CK_OBJECT_HANDLE pPeer_identity; 3107 CK_OBJECT_HANDLE pPeer_prekey; 3108 CK_BYTE_PTR pPrekey_signature; 3109 CK_BYTE_PTR pOnetime_key; 3110 CK_OBJECT_HANDLE pOwn_identity; 3111 CK_OBJECT_HANDLE pOwn_ephemeral; 3112 } CK_X3DH_INITIATE_PARAMS; 3113 Table 62, Extended Triple Diffie-Hellman Initiate Message parameters: Parameter Data type Meaning kdf CK_X3DH_KDF_TYPE Key derivation function pPeer_identity Key handle Peers public Identity key (from the prekey- bundle) pPeer_prekey Key Handle Peers public prekey (from the prekey-bundle) pPrekey_signature Byte array XEDDSA signature of PEER_PREKEY (from prekey-bundle) pOnetime_key Byte array Optional one-time public prekey of peer (from the prekey-bundle) pOwn_identity Key Handle Initiators Identity key pOwn_ephemeral Key Handle Initiators ephemeral key 3114
3115 2.5.4 Responding to an Extended Triple Diffie-Hellman key exchange 3116 Responding an Extended Triple Diffie-Hellman key exchange is done by executing a 3117 CKM_X3DH_RESPOND mechanism. CK_X3DH_RESPOND_PARAMS is a structure that provides the 3118 parameters to the CKM_X3DH_RESPOND key exchange mechanism. All these parameter should be 3119 supplied by the Initiator in a message to the responder. The structure is defined as follows: 3120 typedef struct CK_X3DH_RESPOND_PARAMS { 3121 CK_X3DH_KDF_TYPE kdf; 3122 CK_BYTE_PTR pIdentity_id; 3123 CK_BYTE_PTR pPrekey_id; 3124 CK_BYTE_PTR pOnetime_id; 3125 CK_OBJECT_HANDLE pInitiator_identity; 3126 CK_BYTE_PTR pInitiator_ephemeral;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 82 of 278 3127 } CK_X3DH_RESPOND_PARAMS; 3128 3129 Table 63, Extended Triple Diffie-Hellman 1st Message parameters: Parameter Data type Meaning kdf CK_X3DH_KDF_ Key derivation function TYPE pIdentity_id Byte array Peers public Identity key identifier (from the prekey-bundle) pPrekey_id Byte array Peers public prekey identifier (from the prekey-bundle) pOnetime_id Byte array Optional one-time public prekey of peer (from the prekey-bundle) pInitiator_identity Key handle Initiators Identity key pInitiator_ephemeral Byte array Initiators ephemeral key 3130 3131 Where the *_id fields are identifiers marking which key has been used from the prekey-bundle, these 3132 identifiers could be the keys themselves. 3133 3134 This mechanism has the following rules about key sensitivity and extractability3: 3135 1 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 3136 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 3137 default value. 3138 2 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 3139 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 3140 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 3141 CKA_SENSITIVE attribute. 3142 3 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 3143 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 3144 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 3145 value from its CKA_EXTRACTABLE attribute.
3146 2.5.5 Extended Triple Diffie-Hellman parameters
3147 CK_X3DH_KDF_TYPE, CK_X3DH_KDF_TYPE_PTR
3148 CK_X3DH_KDF_TYPE is used to indicate the Key Derivation Function (KDF) applied to derive keying 3149 data from a shared secret. The key derivation function will be used by the X3DH key agreement 3150 schemes. It is defined as follows: 3151 typedef CK_ULONG CK_X3DH_KDF_TYPE; 3152 3153 The following table lists the defined functions. 3154 Table 64, X3DH: Key Derivation Functions Source Identifier CKD_NULL
3 Note that the rules regarding the CKA_SENSITIVE, CKA_EXTRACTABLE, CKA_ALWAYS_SENSITIVE, and CKA_NEVER_EXTRACTABLE attributes have changed in version 2.11 to match the policy used by other key derivation mechanisms such as CKM_SSL3_MASTER_KEY_DERIVE.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 83 of 278 CKD_BLAKE2B_256_KDF CKD_BLAKE2B_512_KDF CKD_SHA3_256_KDF CKD_SHA256_KDF CKD_SHA3_512_KDF CKD_SHA512_KDF
3155 2.6 Double Ratchet 3156 The Double Ratchet is a key management algorithm managing the ongoing renewal and maintenance of 3157 short-lived session keys providing forward secrecy and break-in recovery for encrypt/decrypt operations. 3158 The algorithm is described in [DoubleRatchet]. The Signal protocol uses X3DH to exchange a shared 3159 secret in the first step, which is then used to derive a Double Ratchet secret key. 3160 Table 65, Double Ratchet Mechanisms vs. Functions Functions Encrypt Sign SR Digest Gen. Wrap Derive Mechanism & & & Key/ & Decrypt Verify 1 Key Unwrap VR Pair CKM_X2RATCHET_INITALIZE ✓ CKM_X2RATCHET_RESPOND ✓ CKM_X2RATCHET_ENCRYPT ✓ ✓ CKM_X2RATCHET_DECRYPT ✓ ✓ 3161
3162 2.6.1 Definitions 3163 This section defines the key type “CKK_X2RATCHET” for type CK_KEY_TYPE as used in the 3164 CKA_KEY_TYPE attribute of key objects. 3165 Mechanisms: 3166 CKM_X2RATCHET_INITALIZE 3167 CKM_X2RATCHET_RESPOND 3168 CKM_X2RATCHET_ENCRYPT 3169 CKM_X2RATCHET_DECRYPT
3170 2.6.2 Double Ratchet secret key objects 3171 Double Ratchet secret key objects (object class CKO_SECRET_KEY, key type CKK_X2RATCHET) hold 3172 Double Ratchet keys. Double Ratchet secret keys can only be derived from shared secret keys using the 3173 mechanism CKM_X2RATCHET_INITALIZE or CKM_X2RATCHET_RESPOND. In the Signal protocol 3174 these are seeded with the shared secret derived from an Extended Triple Diffie-Hellman [X3DH] key- 3175 exchange. The following table defines the Double Ratchet secret key object attributes, in addition to the 3176 common attributes defined for this object class: 3177 Table 66, Double Ratchet Secret Key Object Attributes
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 84 of 278 Attribute Data type Meaning CKA_X2RATCHET_RK Byte array Root key CKA_X2RATCHET_HKS Byte array Sender Header key CKA_X2RATCHET_HKR Byte array Receiver Header key CKA_X2RATCHET_NHKR Byte array Next Sender Header Key CKA_X2RATCHET_NHKR Byte array Next Receiver Header Key CKA_X2RATCHET_CKS Byte array Sender Chain key CKA_X2RATCHET_CKR Byte array Receiver Chain key CKA_X2RATCHET_DHS Byte array Sender DH secret key CKA_X2RATCHET_DHP Byte array Sender DH public key CKA_X2RATCHET_DHR Byte array Receiver DH public key CKA_X2RATCHET_NS ULONG Message number send CKA_X2RATCHET_NR ULONG Message number receive CKA_X2RATCHET_PNS ULONG Previous message number send CKA_X2RATCHET_BOBS1STMSG BOOL Is this bob and has he ever sent a message? CKA_X2RATCHET_ISALICE BOOL Is this Alice? CKA_X2RATCHET_BAGSIZE ULONG How many out-of-order keys do we store CKA_X2RATCHET_BAG Byte array Out-of-order keys
3178 2.6.3 Double Ratchet key derivation 3179 The Double Ratchet key derivation mechanisms depend on who is the initiating party, and who the 3180 receiving, denoted CKM_X2RATCHET_INITIALIZE and CKM_X2RATCHET_RESPOND, are the key 3181 derivation mechanisms for the Double Ratchet. Usually the keys are derived from a shared secret by 3182 executing a X3DH key exchange. 3183 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 3184 key. Additionally the attribute flags indicating which functions the key supports are also contributed by the 3185 mechanism. 3186 For this mechanism, the only allowed values are 255 and 448 as RFC 8032 only defines curves of these 3187 two sizes. A Cryptoki implementation may support one or both of these curves and should set the 3188 ulMinKeySize and ulMaxKeySize fields accordingly.
3189 CK_X2RATCHET_INITIALIZE_PARAMS; 3190 CK_X2RATCHET_INITIALIZE_PARAMS_PTR
3191 CK_X2RATCHET_INITIALIZE_PARAMS provides the parameters to the 3192 CKM_X2RATCHET_INITIALIZE mechanism. It is defined as follows: 3193 typedef struct CK_X2RATCHET_INITIALIZE_PARAMS { 3194 CK_BYTE_PTR sk; 3195 CK_OBJECT_HANDLE peer_public_prekey; 3196 CK_OBJECT_HANDLE peer_public_identity; 3197 CK_OBJECT_HANDLE own_public_identity; 3198 CK_BBOOL bEncryptedHeader; 3199 CK_ULONG eCurve; 3200 CK_MECHANISM_TYPE aeadMechanism; 3201 CK_X2RATCHET_KDF_TYPE kdfMechanism; 3202 } CK_X2RATCHET_INITIALIZE_PARAMS; 3203 3204 The fields of the structure have the following meanings: pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 85 of 278 3205 sk the shared secret with peer (derived using X3DH)
3206 peers_public_prekey Peers public prekey which the Initiator used in the X3DH
3207 peers_public_identity Peers public identity which the Initiator used in the X3DH
3208 own_public_identity Initiators public identity as used in the X3DH
3209 bEncryptedHeader whether the headers are encrypted
3210 eCurve 255 for curve 25519 or 448 for curve 448
3211 aeadMechanism a mechanism supporting AEAD encryption, e.g. 3212 CKM_XCHACHA20
3213 kdfMechanism a Key Derivation Mechanism, such as 3214 CKD_BLAKE2B_512_KDF
3215 CK_X2RATCHET_RESPOND_PARAMS; 3216 CK_X2RATCHET_RESPOND_PARAMS_PTR
3217 CK_X2RATCHET_RESPOND_PARAMS provides the parameters to the 3218 CKM_X2RATCHET_RESPOND mechanism. It is defined as follows: 3219 typedef struct CK_X2RATCHET_RESPOND_PARAMS { 3220 CK_BYTE_PTR sk; 3221 CK_OBJECT_HANDLE own_prekey; 3222 CK_OBJECT_HANDLE initiator_identity; 3223 CK_OBJECT_HANDLE own_public_identity; 3224 CK_BBOOL bEncryptedHeader; 3225 CK_ULONG eCurve; 3226 CK_MECHANISM_TYPE aeadMechanism; 3227 CK_X2RATCHET_KDF_TYPE kdfMechanism; 3228 } CK_X2RATCHET_RESPOND_PARAMS; 3229 3230 The fields of the structure have the following meanings: 3231 sk shared secret with the Initiator
3232 own_prekey Own Prekey pair that the Initiator used
3233 initiator_identity Initiators public identity key used
3234 own_public_identity as used in the prekey bundle by the initiator in the X3DH
3235 bEncryptedHeader whether the headers are encrypted
3236 eCurve 255 for curve 25519 or 448 for curve 448
3237 aeadMechanism a mechanism supporting AEAD encryption, e.g. 3238 CKM_XCHACHA20
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 86 of 278 3239 kdfMechanism a Key Derivation Mechanism, such as 3240 CKD_BLAKE2B_512_KDF
3241 2.6.4 Double Ratchet Encryption mechanism 3242 The Double Ratchet encryption mechanism, denoted CKM_X2RATCHET_ENCRYPT and 3243 CKM_X2RATCHET_DECRYPT, are a mechanisms for single part encryption and decryption based on 3244 the Double Ratchet and its underlying AEAD cipher.
3245 2.6.5 Double Ratchet parameters
3246 CK_X2RATCHET_KDF_TYPE, CK_X2RATCHET_KDF_TYPE_PTR
3247 CK_X2RATCHET_KDF_TYPE is used to indicate the Key Derivation Function (KDF) applied to derive 3248 keying data from a shared secret. The key derivation function will be used by the X key derivation 3249 scheme. It is defined as follows: 3250 typedef CK_ULONG CK_X2RATCHET_KDF_TYPE; 3251 3252 The following table lists the defined functions. 3253 Table 67, X2RATCHET: Key Derivation Functions Source Identifier CKD_NULL CKD_BLAKE2B_256_KDF CKD_BLAKE2B_512_KDF CKD_SHA3_256_KDF CKD_SHA256_KDF CKD_SHA3_512_KDF CKD_SHA512_KDF
3254
3255 2.7 Wrapping/unwrapping private keys 3256 Cryptoki Versions 2.01 and up allow the use of secret keys for wrapping and unwrapping RSA private 3257 keys, Diffie-Hellman private keys, X9.42 Diffie-Hellman private keys, EC (also related to ECDSA) private 3258 keys and DSA private keys. For wrapping, a private key is BER-encoded according to PKCS #8’s 3259 PrivateKeyInfo ASN.1 type. PKCS #8 requires an algorithm identifier for the type of the private key. The 3260 object identifiers for the required algorithm identifiers are as follows: 3261 rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1 } 3262 3263 dhKeyAgreement OBJECT IDENTIFIER ::= { pkcs-3 1 } 3264 3265 dhpublicnumber OBJECT IDENTIFIER ::= { iso(1) member-body(2) 3266 us(840) ansi-x942(10046) number-type(2) 1 } 3267 3268 id-ecPublicKey OBJECT IDENTIFIER ::= { iso(1) member-body(2) 3269 us(840) ansi-x9-62(10045) publicKeyType(2) 1 } 3270 3271 id-dsa OBJECT IDENTIFIER ::= { 3272 iso(1) member-body(2) us(840) x9-57(10040) x9cm(4) 1 } pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 87 of 278 3273 3274 where 3275 pkcs-1 OBJECT IDENTIFIER ::= { 3276 iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 1 } 3277 3278 pkcs-3 OBJECT IDENTIFIER ::= { 3279 iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 3 } 3280 3281 These parameters for the algorithm identifiers have the 3282 following types, respectively: 3283 NULL 3284 3285 DHParameter ::= SEQUENCE { 3286 prime INTEGER, -- p 3287 base INTEGER, -- g 3288 privateValueLength INTEGER OPTIONAL 3289 } 3290 3291 DomainParameters ::= SEQUENCE { 3292 prime INTEGER, -- p 3293 base INTEGER, -- g 3294 subprime INTEGER, -- q 3295 cofactor INTEGER OPTIONAL, -- j 3296 validationParms ValidationParms OPTIONAL 3297 } 3298 3299 ValidationParms ::= SEQUENCE { 3300 Seed BIT STRING, -- seed 3301 PGenCounter INTEGER -- parameter verification 3302 } 3303 3304 Parameters ::= CHOICE { 3305 ecParameters ECParameters, 3306 namedCurve CURVES.&id({CurveNames}), 3307 implicitlyCA NULL 3308 } 3309 3310 Dss-Parms ::= SEQUENCE { 3311 p INTEGER, 3312 q INTEGER, 3313 g INTEGER 3314 } 3315 3316 For the X9.42 Diffie-Hellman domain parameters, the cofactor and the validationParms optional fields 3317 should not be used when wrapping or unwrapping X9.42 Diffie-Hellman private keys since their values 3318 are not stored within the token. 3319 For the EC domain parameters, the use of namedCurve is recommended over the choice 3320 ecParameters. The choice implicitlyCA must not be used in Cryptoki.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 88 of 278 3321 Within the PrivateKeyInfo type: 3322 RSA private keys are BER-encoded according to PKCS #1’s RSAPrivateKey ASN.1 type. This type 3323 requires values to be present for all the attributes specific to Cryptoki’s RSA private key objects. In 3324 other words, if a Cryptoki library does not have values for an RSA private key’s CKA_MODULUS, 3325 CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, 3326 CKA_EXPONENT_1, CKA_EXPONENT2, and CKA_COEFFICIENT values, it must not create an 3327 RSAPrivateKey BER-encoding of the key, and so it must not prepare it for wrapping. 3328 Diffie-Hellman private keys are represented as BER-encoded ASN.1 type INTEGER. 3329 X9.42 Diffie-Hellman private keys are represented as BER-encoded ASN.1 type INTEGER. 3330 EC (also related with ECDSA) private keys are BER-encoded according to SECG SEC 1 3331 ECPrivateKey ASN.1 type: 3332 ECPrivateKey ::= SEQUENCE { 3333 Version INTEGER { ecPrivkeyVer1(1) } 3334 (ecPrivkeyVer1), 3335 privateKey OCTET STRING, 3336 parameters [0] Parameters OPTIONAL, 3337 publicKey [1] BIT STRING OPTIONAL 3338 } 3339 3340 Since the EC domain parameters are placed in the PKCS #8’s privateKeyAlgorithm field, the optional 3341 parameters field in an ECPrivateKey must be omitted. A Cryptoki application must be able to 3342 unwrap an ECPrivateKey that contains the optional publicKey field; however, what is done with this 3343 publicKey field is outside the scope of Cryptoki. 3344 DSA private keys are represented as BER-encoded ASN.1 type INTEGER. 3345 Once a private key has been BER-encoded as a PrivateKeyInfo type, the resulting string of bytes is 3346 encrypted with the secret key. This encryption must be done in CBC mode with PKCS padding. 3347 Unwrapping a wrapped private key undoes the above procedure. The CBC-encrypted ciphertext is 3348 decrypted, and the PKCS padding is removed. The data thereby obtained are parsed as a 3349 PrivateKeyInfo type, and the wrapped key is produced. An error will result if the original wrapped key 3350 does not decrypt properly, or if the decrypted unpadded data does not parse properly, or its type does not 3351 match the key type specified in the template for the new key. The unwrapping mechanism contributes 3352 only those attributes specified in the PrivateKeyInfo type to the newly-unwrapped key; other attributes 3353 must be specified in the template, or will take their default values. 3354 Earlier drafts of PKCS #11 Version 2.0 and Version 2.01 used the object identifier 3355 DSA OBJECT IDENTIFIER ::= { algorithm 12 } 3356 algorithm OBJECT IDENTIFIER ::= { 3357 iso(1) identifier-organization(3) oiw(14) secsig(3) 3358 algorithm(2) } 3359 3360 with associated parameters 3361 DSAParameters ::= SEQUENCE { 3362 prime1 INTEGER, -- modulus p 3363 prime2 INTEGER, -- modulus q 3364 base INTEGER -- base g 3365 } 3366
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 89 of 278 3367 for wrapping DSA private keys. Note that although the two structures for holding DSA domain 3368 parameters appear identical when instances of them are encoded, the two corresponding object 3369 identifiers are different.
3370 2.8 Generic secret key 3371 Table 68, Generic Secret Key Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_GENERIC _SECRET_KEY _GEN
3372 2.8.1 Definitions 3373 This section defines the key type “CKK_GENERIC_SECRET” for type CK_KEY_TYPE as used in the 3374 CKA_KEY_TYPE attribute of key objects. 3375 Mechanisms: 3376 CKM_GENERIC_SECRET_KEY_GEN
3377 2.8.2 Generic secret key objects 3378 Generic secret key objects (object class CKO_SECRET_KEY, key type CKK_GENERIC_SECRET) hold 3379 generic secret keys. These keys do not support encryption or decryption; however, other keys can be 3380 derived from them and they can be used in HMAC operations. The following table defines the generic 3381 secret key object attributes, in addition to the common attributes defined for this object class: 3382 These key types are used in several of the mechanisms described in this section. 3383 Table 69, Generic Secret Key Object Attributes Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key value (arbitrary length) CKA_VALUE_LEN2,3 CK_ULONG Length in bytes of key value 3384 - Refer to [PKCS11-Base] table 11 for footnotes 3385 The following is a sample template for creating a generic secret key object: 3386 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 3387 CK_KEY_TYPE keyType = CKK_GENERIC_SECRET; 3388 CK_UTF8CHAR label[] = “A generic secret key object”; 3389 CK_BYTE value[] = {...}; 3390 CK_BBOOL true = CK_TRUE; 3391 CK_ATTRIBUTE template[] = { 3392 {CKA_CLASS, &class, sizeof(class)}, 3393 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 3394 {CKA_TOKEN, &true, sizeof(true)}, 3395 {CKA_LABEL, label, sizeof(label)-1}, 3396 {CKA_DERIVE, &true, sizeof(true)}, 3397 {CKA_VALUE, value, sizeof(value)} pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 90 of 278 3398 }; 3399 3400 CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three 3401 bytes of the SHA-1 hash of the generic secret key object’s CKA_VALUE attribute.
3402 2.8.3 Generic secret key generation 3403 The generic secret key generation mechanism, denoted CKM_GENERIC_SECRET_KEY_GEN, is used 3404 to generate generic secret keys. The generated keys take on any attributes provided in the template 3405 passed to the C_GenerateKey call, and the CKA_VALUE_LEN attribute specifies the length of the key 3406 to be generated. 3407 It does not have a parameter. 3408 The template supplied must specify a value for the CKA_VALUE_LEN attribute. If the template specifies 3409 an object type and a class, they must have the following values: 3410 CK_OBJECT_CLASS = CKO_SECRET_KEY; 3411 CK_KEY_TYPE = CKK_GENERIC_SECRET; 3412 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3413 specify the supported range of key sizes, in bits.
3414 2.9 HMAC mechanisms 3415 Refer to RFC2104 and FIPS 198 for HMAC algorithm description. The HMAC secret key shall correspond 3416 to the PKCS11 generic secret key type or the mechanism specific key types (see mechanism definition). 3417 Such keys, for use with HMAC operations can be created using C_CreateObject or C_GenerateKey. 3418 The RFC also specifies test vectors for the various hash function based HMAC mechanisms described in 3419 the respective hash mechanism descriptions. The RFC should be consulted to obtain these test vectors.
3420 2.9.1 General block cipher mechanism parameters
3421 CK_MAC_GENERAL_PARAMS; CK_MAC_GENERAL_PARAMS_PTR
3422 CK_MAC_GENERAL_PARAMS provides the parameters to the general-length MACing mechanisms of 3423 the DES, DES3 (triple-DES), AES, Camellia, SEED, and ARIA ciphers. It also provides the parameters to 3424 the general-length HMACing mechanisms (i.e.,SHA-1, SHA-256, SHA-384, SHA-512, and SHA-512/T 3425 family) and the two SSL 3.0 MACing mechanisms, (i.e., MD5 and SHA-1). It holds the length of the MAC 3426 that these mechanisms produce. It is defined as follows: 3427 typedef CK_ULONG CK_MAC_GENERAL_PARAMS; 3428 3429 CK_MAC_GENERAL_PARAMS_PTR is a pointer to a CK_MAC_GENERAL_PARAMS.
3430 2.10 AES 3431 For the Advanced Encryption Standard (AES) see [FIPS PUB 197]. 3432 Table 70, AES Mechanisms vs. Functions
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 91 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_AES_KEY_GEN CKM_AES_ECB CKM_AES_CBC CKM_AES_CBC_PAD CKM_AES_MAC_GENERAL CKM_AES_MAC CKM_AES_OFB CKM_AES_CFB64 CKM_AES_CFB8 CKM_AES_CFB128 CKM_AES_CFB1 CKM_AES_XCBC_MAC CKM_AES_XCBC_MAC_96
3433 2.10.1 Definitions 3434 This section defines the key type “CKK_AES” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE 3435 attribute of key objects. 3436 Mechanisms: 3437 CKM_AES_KEY_GEN 3438 CKM_AES_ECB 3439 CKM_AES_CBC 3440 CKM_AES_MAC 3441 CKM_AES_MAC_GENERAL 3442 CKM_AES_CBC_PAD 3443 CKM_AES_OFB 3444 CKM_AES_CFB64 3445 CKM_AES_CFB8 3446 CKM_AES_CFB128 3447 CKM_AES_CFB1 3448 CKM_AES_XCBC_MAC 3449 CKM_AES_XCBC_MAC_96
3450 2.10.2 AES secret key objects 3451 AES secret key objects (object class CKO_SECRET_KEY, key type CKK_AES) hold AES keys. The 3452 following table defines the AES secret key object attributes, in addition to the common attributes defined 3453 for this object class: 3454 Table 71, AES Secret Key Object Attributes
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 92 of 278 Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key value (16, 24, or 32 bytes) CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value 3455 - Refer to [PKCS11-Base] table 11 for footnotes 3456 The following is a sample template for creating an AES secret key object: 3457 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 3458 CK_KEY_TYPE keyType = CKK_AES; 3459 CK_UTF8CHAR label[] = “An AES secret key object”; 3460 CK_BYTE value[] = {...}; 3461 CK_BBOOL true = CK_TRUE; 3462 CK_ATTRIBUTE template[] = { 3463 {CKA_CLASS, &class, sizeof(class)}, 3464 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 3465 {CKA_TOKEN, &true, sizeof(true)}, 3466 {CKA_LABEL, label, sizeof(label)-1}, 3467 {CKA_ENCRYPT, &true, sizeof(true)}, 3468 {CKA_VALUE, value, sizeof(value)} 3469 }; 3470 3471 CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three 3472 bytes of the ECB encryption of a single block of null (0x00) bytes, using the default cipher associated with 3473 the key type of the secret key object.
3474 2.10.3 AES key generation 3475 The AES key generation mechanism, denoted CKM_AES_KEY_GEN, is a key generation mechanism for 3476 NIST’s Advanced Encryption Standard. 3477 It does not have a parameter. 3478 The mechanism generates AES keys with a particular length in bytes, as specified in the 3479 CKA_VALUE_LEN attribute of the template for the key. 3480 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 3481 key. Other attributes supported by the AES key type (specifically, the flags indicating which functions the 3482 key supports) may be specified in the template for the key, or else are assigned default initial values. 3483 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3484 specify the supported range of AES key sizes, in bytes.
3485 2.10.4 AES-ECB 3486 AES-ECB, denoted CKM_AES_ECB, is a mechanism for single- and multiple-part encryption and 3487 decryption; key wrapping; and key unwrapping, based on NIST Advanced Encryption Standard and 3488 electronic codebook mode. 3489 It does not have a parameter. 3490 This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 3491 wrap/unwrap every secret key that it supports. For wrapping, the mechanism encrypts the value of the 3492 CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus 3493 one null bytes so that the resulting length is a multiple of the block size. The output data is the same 3494 length as the padded input data. It does not wrap the key type, key length, or any other information about 3495 the key; the application must convey these separately.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 93 of 278 3496 For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the 3497 CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the 3498 CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the CKA_VALUE 3499 attribute of the new key; other attributes required by the key type must be specified in the template. 3500 Constraints on key types and the length of data are summarized in the following table: 3501 Table 72, AES-ECB: Key And Data Length Function Key Input length Output length Comments type C_Encrypt AES multiple of same as input length no final part block size C_Decrypt AES multiple of same as input length no final part block size C_WrapKey AES any input length rounded up to multiple of block size C_UnwrapKey AES multiple of determined by type of key block size being unwrapped or CKA_VALUE_LEN 3502 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3503 specify the supported range of AES key sizes, in bytes.
3504 2.10.5 AES-CBC 3505 AES-CBC, denoted CKM_AES_CBC, is a mechanism for single- and multiple-part encryption and 3506 decryption; key wrapping; and key unwrapping, based on NIST’s Advanced Encryption Standard and 3507 cipher-block chaining mode. 3508 It has a parameter, a 16-byte initialization vector. 3509 This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 3510 wrap/unwrap every secret key that it supports. For wrapping, the mechanism encrypts the value of the 3511 CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus 3512 one null bytes so that the resulting length is a multiple of the block size. The output data is the same 3513 length as the padded input data. It does not wrap the key type, key length, or any other information about 3514 the key; the application must convey these separately. 3515 For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the 3516 CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the 3517 CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the CKA_VALUE 3518 attribute of the new key; other attributes required by the key type must be specified in the template. 3519 Constraints on key types and the length of data are summarized in the following table: 3520 Table 73, AES-CBC: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 94 of 278 Function Key Input length Output length Comments type C_Encrypt AES multiple of same as input length no final part block size C_Decrypt AES multiple of same as input length no final part block size C_WrapKey AES any input length rounded up to multiple of the block size C_UnwrapKey AES multiple of determined by type of key block size being unwrapped or CKA_VALUE_LEN 3521 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3522 specify the supported range of AES key sizes, in bytes.
3523 2.10.6 AES-CBC with PKCS padding 3524 AES-CBC with PKCS padding, denoted CKM_AES_CBC_PAD, is a mechanism for single- and multiple- 3525 part encryption and decryption; key wrapping; and key unwrapping, based on NIST’s Advanced 3526 Encryption Standard; cipher-block chaining mode; and the block cipher padding method detailed in PKCS 3527 #7. 3528 It has a parameter, a 16-byte initialization vector. 3529 The PKCS padding in this mechanism allows the length of the plaintext value to be recovered from the 3530 ciphertext value. Therefore, when unwrapping keys with this mechanism, no value should be specified 3531 for the CKA_VALUE_LEN attribute. 3532 In addition to being able to wrap and unwrap secret keys, this mechanism can wrap and unwrap RSA, 3533 Diffie-Hellman, X9.42 Diffie-Hellman, EC (also related to ECDSA) and DSA private keys (see Section 2.7 3534 for details). The entries in the table below for data length constraints when wrapping and unwrapping 3535 keys do not apply to wrapping and unwrapping private keys. 3536 Constraints on key types and the length of data are summarized in the following table: 3537 Table 74, AES-CBC with PKCS Padding: Key And Data Length Function Key Input length Output length type C_Encrypt AES any input length rounded up to multiple of the block size C_Decrypt AES multiple of between 1 and block size bytes block size shorter than input length C_WrapKey AES any input length rounded up to multiple of the block size C_UnwrapKey AES multiple of between 1 and block length block size bytes shorter than input length 3538 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3539 specify the supported range of AES key sizes, in bytes.
3540 2.10.7 AES-OFB 3541 AES-OFB, denoted CKM_AES_OFB. It is a mechanism for single and multiple-part encryption and 3542 decryption with AES. AES-OFB mode is described in [NIST sp800-38a]. 3543 It has a parameter, an initialization vector for this mode. The initialization vector has the same length as 3544 the block size. 3545
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 95 of 278 3546 Constraints on key types and the length of data are summarized in the following table: 3547 3548 Table 75, AES-OFB: Key And Data Length Function Key Input length Output length Comments type C_Encrypt AES any same as input length no final part C_Decrypt AES any same as input length no final part 3549 For this mechanism the CK_MECHANISM_INFO structure is as specified for CBC mode.
3550 2.10.8 AES-CFB 3551 Cipher AES has a cipher feedback mode, AES-CFB, denoted CKM_AES_CFB8, CKM_AES_CFB64, and 3552 CKM_AES_CFB128. It is a mechanism for single and multiple-part encryption and decryption with AES. 3553 AES-OFB mode is described [NIST sp800-38a]. 3554 It has a parameter, an initialization vector for this mode. The initialization vector has the same length as 3555 the block size. 3556 3557 Constraints on key types and the length of data are summarized in the following table: 3558 3559 Table 76, AES-CFB: Key And Data Length Function Key Input length Output length Comments type C_Encrypt AES any same as input length no final part C_Decrypt AES any same as input length no final part 3560 For this mechanism the CK_MECHANISM_INFO structure is as specified for CBC mode.
3561 2.10.9 General-length AES-MAC 3562 General-length AES-MAC, denoted CKM_AES_MAC_GENERAL, is a mechanism for single- and 3563 multiple-part signatures and verification, based on NIST Advanced Encryption Standard as defined in 3564 FIPS PUB 197 and data authentication as defined in FIPS PUB 113. 3565 It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length 3566 desired from the mechanism. 3567 The output bytes from this mechanism are taken from the start of the final AES cipher block produced in 3568 the MACing process. 3569 Constraints on key types and the length of data are summarized in the following table: 3570 Table 77, General-length AES-MAC: Key And Data Length Function Key type Data length Signature length C_Sign AES any 1-block size, as specified in parameters C_Verify AES any 1-block size, as specified in parameters 3571 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3572 specify the supported range of AES key sizes, in bytes.
3573 2.10.10 AES-MAC 3574 AES-MAC, denoted by CKM_AES_MAC, is a special case of the general-length AES-MAC mechanism. 3575 AES-MAC always produces and verifies MACs that are half the block size in length. 3576 It does not have a parameter. 3577 Constraints on key types and the length of data are summarized in the following table: pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 96 of 278 3578 Table 78, AES-MAC: Key And Data Length Function Key type Data length Signature length C_Sign AES Any ½ block size (8 bytes) C_Verify AES Any ½ block size (8 bytes) 3579 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3580 specify the supported range of AES key sizes, in bytes.
3581 2.10.11 AES-XCBC-MAC 3582 AES-XCBC-MAC, denoted CKM_AES_XCBC_MAC, is a mechanism for single and multiple part 3583 signatures and verification; based on NIST’s Advanced Encryption Standard and [RFC 3566]. 3584 It does not have a parameter. 3585 Constraints on key types and the length of data are summarized in the following table: 3586 Table 79, AES-XCBC-MAC: Key And Data Length Function Key type Data length Signature length C_Sign AES Any 16 bytes C_Verify AES Any 16 bytes 3587 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3588 specify the supported range of AES key sizes, in bytes.
3589 2.10.12 AES-XCBC-MAC-96 3590 AES-XCBC-MAC-96, denoted CKM_AES_XCBC_MAC-96, is a mechanism for single and multiple part 3591 signatures and verification; based on NIST’s Advanced Encryption Standard and [RFC 3566]. 3592 It does not have a parameter. 3593 Constraints on key types and the length of data are summarized in the following table: 3594 Table 80, AES-XCBC-MAC: Key And Data Length Function Key type Data length Signature length C_Sign AES Any 12 bytes C_Verify AES Any 12 bytes 3595 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3596 specify the supported range of AES key sizes, in bytes. 3597
3598 2.11 AES with Counter 3599 Table 81, AES with Counter Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_AES_CTR
3600 2.11.1 Definitions 3601 Mechanisms:
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 97 of 278 3602 CKM_AES_CTR
3603 2.11.2 AES with Counter mechanism parameters
3604 CK_AES_CTR_PARAMS; CK_AES_CTR_PARAMS_PTR
3605 CK_AES_CTR_PARAMS is a structure that provides the parameters to the CKM_AES_CTR mechanism. 3606 It is defined as follows: 3607 typedef struct CK_AES_CTR_PARAMS { 3608 CK_ULONG ulCounterBits; 3609 CK_BYTE cb[16]; 3610 } CK_AES_CTR_PARAMS; 3611 3612 ulCounterBits specifies the number of bits in the counter block (cb) that shall be incremented. This 3613 number shall be such that 0 < ulCounterBits <= 128. For any values outside this range the mechanism 3614 shall return CKR_MECHANISM_PARAM_INVALID. 3615 It's up to the caller to initialize all of the bits in the counter block including the counter bits. The counter 3616 bits are the least significant bits of the counter block (cb). They are a big-endian value usually starting 3617 with 1. The rest of ‘cb’ is for the nonce, and maybe an optional IV. 3618 E.g. as defined in [RFC 3686]: 3619 0 1 2 3 3620 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 3621 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3622 | Nonce | 3623 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3624 | Initialization Vector (IV) | 3625 | | 3626 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3627 | Block Counter | 3628 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3629 3630 This construction permits each packet to consist of up to 232-1 blocks = 4,294,967,295 blocks = 3631 68,719,476,720 octets. 3632 CK_AES_CTR_PARAMS_PTR is a pointer to a CK_AES_CTR_PARAMS.
3633 2.11.3 AES with Counter Encryption / Decryption 3634 Generic AES counter mode is described in NIST Special Publication 800-38A and in RFC 3686. These 3635 describe encryption using a counter block which may include a nonce to guarantee uniqueness of the 3636 counter block. Since the nonce is not incremented, the mechanism parameter must specify the number of 3637 counter bits in the counter block. 3638 The block counter is incremented by 1 after each block of plaintext is processed. There is no support for 3639 any other increment functions in this mechanism. 3640 If an attempt to encrypt/decrypt is made which will cause an overflow of the counter block’s counter bits, 3641 then the mechanism shall return CKR_DATA_LEN_RANGE. Note that the mechanism should allow the 3642 final post increment of the counter to overflow (if it implements it this way) but not allow any further 3643 processing after this point. E.g. if ulCounterBits = 2 and the counter bits start as 1 then only 3 blocks of 3644 data can be processed. 3645
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 98 of 278 3646 2.12 AES CBC with Cipher Text Stealing CTS 3647 Ref [NIST AES CTS] 3648 This mode allows unpadded data that has length that is not a multiple of the block size to be encrypted to 3649 the same length of cipher text. 3650 Table 82, AES CBC with Cipher Text Stealing CTS Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_AES_CTS
3651 2.12.1 Definitions 3652 Mechanisms: 3653 CKM_AES_CTS
3654 2.12.2 AES CTS mechanism parameters 3655 It has a parameter, a 16-byte initialization vector. 3656 Table 83, AES-CTS: Key And Data Length Function Key Input length Output length Comments type C_Encrypt AES Any, ≥ block same as input length no final part size (16 bytes) C_Decrypt AES any, ≥ block same as input length no final part size (16 bytes) 3657
3658 2.13 Additional AES Mechanisms 3659 Table 84, Additional AES Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_AES_GCM CKM_AES_CCM CKM_AES_GMAC 3660
3661 2.13.1 Definitions 3662 Mechanisms: 3663 CKM_AES_GCM 3664 CKM_AES_CCM
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 99 of 278 3665 CKM_AES_GMAC 3666 Generator Functions: 3667 CKG_NO_GENERATE 3668 CKG_GENERATE 3669 CKG_GENERATE_COUNTER 3670 CKG_GENERATE_RANDOM
3671 2.13.2 AES-GCM Authenticated Encryption / Decryption 3672 Generic GCM mode is described in [GCM]. To set up for AES-GCM use the following process, where K 3673 (key) and AAD (additional authenticated data) are as described in [GCM]. AES-GCM uses 3674 CK_GCM_PARAMS for Encrypt, Decrypt and CK_GCM_MESSAGE_PARAMS for MessageEncrypt and 3675 MessageDecrypt. 3676 Encrypt: 3677 Set the IV length ulIvLen in the parameter block. 3678 Set the IV data pIv in the parameter block. 3679 Set the AAD data pAAD and size ulAADLen in the parameter block. pAAD may be NULL if 3680 ulAADLen is 0. 3681 Set the tag length ulTagBits in the parameter block. 3682 Call C_EncryptInit() for CKM_AES_GCM mechanism with parameters and key K. 3683 Call C_Encrypt(), or C_EncryptUpdate()*4 C_EncryptFinal(), for the plaintext obtaining ciphertext 3684 and authentication tag output. 3685 Decrypt: 3686 Set the IV length ulIvLen in the parameter block. 3687 Set the IV data pIv in the parameter block. 3688 Set the AAD data pAAD and size ulAADLen in the parameter block. pAAD may be NULL if 3689 ulAADLen is 0. 3690 Set the tag length ulTagBits in the parameter block. 3691 Call C_DecryptInit() for CKM_AES_GCM mechanism with parameters and key K. 3692 Call C_Decrypt(), or C_DecryptUpdate()*1 C_DecryptFinal(), for the ciphertext, including the 3693 appended tag, obtaining plaintext output. Note: since CKM_AES_GCM is an AEAD cipher, no data 3694 should be returned until C_Decrypt() or C_DecryptFinal(). 3695 MessageEncrypt: 3696 Set the IV length ulIvLen in the parameter block. 3697 Set pIv to hold the IV data returned from C_EncryptMessage() and C_EncryptMessageBegin(). If 3698 ulIvFixedBits is not zero, then the most significant bits of pIV contain the fixed IV. If ivGenerator is 3699 set to CKG_NO_GENERATE, pIv is an input parameter with the full IV. 3700 Set the ulIvFixedBits and ivGenerator fields in the parameter block. 3701 Set the tag length ulTagBits in the parameter block.
4 “*” indicates 0 or more calls may be made as required
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 100 of 278 3702 Set pTag to hold the tag data returned from C_EncryptMessage() or the final 3703 C_EncryptMessageNext(). 3704 Call C_MessageEncryptInit() for CKM_AES_GCM mechanism key K. 3705 Call C_EncryptMessage(), or C_EncryptMessageBegin() followed by C_EncryptMessageNext()* 5. 3706 The mechanism parameter is passed to all three of these functions. 3707 Call C_MessageEncryptFinal() to close the message decryption. 3708 MessageDecrypt: 3709 Set the IV length ulIvLen in the parameter block. 3710 Set the IV data pIv in the parameter block. 3711 The ulIvFixedBits and ivGenerator fields are ignored. 3712 Set the tag length ulTagBits in the parameter block. 3713 Set the tag data pTag in the parameter block before C_DecryptMessage() or the final 3714 C_DecryptMessageNext(). 3715 Call C_MessageDecryptInit() for CKM_AES_GCM mechanism key K. 3716 Call C_DecryptMessage(), or C_DecryptMessageBegin followed by C_DecryptMessageNext()*6. 3717 The mechanism parameter is passed to all three of these functions. 3718 Call C_MessageDecryptFinal() to close the message decryption. 3719 In pIv the least significant bit of the initialization vector is the rightmost bit. ulIvLen is the length of the 3720 initialization vector in bytes. 3721 On MessageEncrypt, the meaning of ivGenerator is as follows: CKG_NO_GENERATE means the IV is 3722 passed in on MessageEncrypt and no internal IV generation is done. CKG_GENERATE means that the 3723 non-fixed portion of the IV is generated by the module internally. The generation method is not defined. 3724 CKG_GENERATE_COUNTER means that the non-fixed portion of the IV is generated by the module 3725 internally by use of an incrementing counter. CKG_GENERATE_RANDOM means that the non-fixed 3726 portion of the IV is generated by the module internally using a PRNG. In any case the entire IV, including 3727 the fixed portion, is returned in pIV. 3728 Modules must implement CKG_GENERATE. Modules may also reject ulIvFixedBits values which are too 3729 large. Zero is always an acceptable value for ulIvFixedBits. 3730 In Encrypt and Decrypt the tag is appended to the cipher text and the least significant bit of the tag is the 3731 rightmost bit and the tag bits are the rightmost ulTagBits bits. In MessageEncrypt the tag is returned in 3732 the pTag field of CK_GCM_MESSAGE_PARAMS. In MesssageDecrypt the tag is provided by the pTag 3733 field of CK_GCM_MESSAGE_PARAMS. 3734 The key type for K must be compatible with CKM_AES_ECB and the 3735 C_EncryptInit()/C_DecryptInit()/C_MessageEncryptInit()/C_MessageDecryptInit() calls shall behave, with 3736 respect to K, as if they were called directly with CKM_AES_ECB, K and NULL parameters.
3737 2.13.3 AES-CCM authenticated Encryption / Decryption 3738 For IPsec (RFC 4309) and also for use in ZFS encryption. Generic CCM mode is described in [RFC 3739 3610].
5 “*” indicates 0 or more calls may be made as required
6 “*” indicates 0 or more calls may be made as required
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 101 of 278 3740 To set up for AES-CCM use the following process, where K (key), nonce and additional authenticated 3741 data are as described in [RFC 3610]. AES-CCM uses CK_CCM_PARAMS for Encrypt and Decrypt, and 3742 CK_CCM_MESSAGE_PARAMS for MessageEncrypt and MessageDecrypt. 3743 Encrypt: 3744 Set the message/data length ulDataLen in the parameter block. 3745 Set the nonce length ulNonceLen and the nonce data pNonce in the parameter block. 3746 Set the AAD data pAAD and size ulAADLen in the parameter block. pAAD may be NULL if 3747 ulAADLen is 0. 3748 Set the MAC length ulMACLen in the parameter block. 3749 Call C_EncryptInit() for CKM_AES_CCM mechanism with parameters and key K. 3750 Call C_Encrypt(), C_EncryptUpdate(), or C_EncryptFinal(), for the plaintext obtaining the final 3751 ciphertext output and the MAC. The total length of data processed must be ulDataLen. The output 3752 length will be ulDataLen + ulMACLen. 3753 Decrypt: 3754 Set the message/data length ulDataLen in the parameter block. This length must not include the 3755 length of the MAC that is appended to the cipher text. 3756 Set the nonce length ulNonceLen and the nonce data pNonce in the parameter block. 3757 Set the AAD data pAAD and size ulAADLen in the parameter block. pAAD may be NULL if 3758 ulAADLen is 0. 3759 Set the MAC length ulMACLen in the parameter block. 3760 Call C_DecryptInit() for CKM_AES_CCM mechanism with parameters and key K. 3761 Call C_Decrypt(), C_DecryptUpdate(), or C_DecryptFinal(), for the ciphertext, including the 3762 appended MAC, obtaining plaintext output. The total length of data processed must be ulDataLen 3763 + ulMACLen. Note: since CKM_AES_CCM is an AEAD cipher, no data should be returned until 3764 C_Decrypt() or C_DecryptFinal(). 3765 MessageEncrypt: 3766 Set the message/data length ulDataLen in the parameter block. 3767 Set the nonce length ulNonceLen. 3768 Set pNonce to hold the nonce data returned from C_EncryptMessage() and 3769 C_EncryptMessageBegin(). If ulNonceFixedBits is not zero, then the most significant bits of pNonce 3770 contain the fixed nonce. If nonceGenerator is set to CKG_NO_GENERATE, pNonce is an input 3771 parameter with the full nonce. 3772 Set the ulNonceFixedBits and nonceGenerator fields in the parameter block. 3773 Set the MAC length ulMACLen in the parameter block. 3774 Set pMAC to hold the MAC data returned from C_EncryptMessage() or the final 3775 C_EncryptMessageNext(). 3776 Call C_MessageEncryptInit() for CKM_AES_CCM mechanism key K. 3777 Call C_EncryptMessage(), or C_EncryptMessageBegin() followed by C_EncryptMessageNext()*7.. 3778 The mechanism parameter is passed to all three functions.
7 “*” indicates 0 or more calls may be made as required
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 102 of 278 3779 Call C_MessageEncryptFinal() to close the message encryption. 3780 The MAC is returned in pMac of the CK_CCM_MESSAGE_PARAMS structure. 3781 MessageDecrypt: 3782 Set the message/data length ulDataLen in the parameter block. 3783 Set the nonce length ulNonceLen and the nonce data pNonce in the parameter block 3784 The ulNonceFixedBits and nonceGenerator fields in the parameter block are ignored. 3785 Set the MAC length ulMACLen in the parameter block. 3786 Set the MAC data pMAC in the parameter block before C_DecryptMessage() or the final 3787 C_DecryptMessageNext(). 3788 Call C_MessageDecryptInit() for CKM_AES_CCM mechanism key K. 3789 Call C_DecryptMessage(), or C_DecryptMessageBegin() followed by C_DecryptMessageNext()*8. 3790 The mechanism parameter is passed to all three functions. 3791 Call C_MessageDecryptFinal() to close the message decryption. 3792 In pNonce the least significant bit of the nonce is the rightmost bit. ulNonceLen is the length of the nonce 3793 in bytes. 3794 On MessageEncrypt, the meaning of nonceGenerator is as follows: CKG_NO_GENERATE means the 3795 nonce is passed in on MessageEncrypt and no internal MAC generation is done. CKG_GENERATE 3796 means that the non-fixed portion of the nonce is generated by the module internally. The generation 3797 method is not defined. CKG_GENERATE_COUNTER means that the non-fixed portion of the nonce is 3798 generated by the module internally by use of an incrementing counter. CKG_GENERATE_RANDOM 3799 means that the non-fixed portion of the nonce is generated by the module internally using a PRNG. In any 3800 case the entire nonce, including the fixed portion, is returned in pNonce. 3801 Modules must implement CKG_GENERATE. Modules may also reject ulNonceFixedBits values which are 3802 too large. Zero is always an acceptable value for ulNonceFixedBits. 3803 In Encrypt and Decrypt the MAC is appended to the cipher text and the least significant byte of the MAC is 3804 the rightmost byte and the MAC bytes are the rightmost ulMACLen bytes. In MessageEncrypt the MAC is 3805 returned in the pMAC field of CK_CCM_MESSAGE_PARAMS. In MesssageDecrypt the MAC is provided 3806 by the pMAC field of CK_CCM_MESSAGE_PARAMS. 3807 The key type for K must be compatible with CKM_AES_ECB and the 3808 C_EncryptInit()/C_DecryptInit()/C_MessageEncryptInit()/C_MessageDecryptInit() calls shall behave, with 3809 respect to K, as if they were called directly with CKM_AES_ECB, K and NULL parameters.
3810 2.13.4 AES-GMAC 3811 AES-GMAC, denoted CKM_AES_GMAC, is a mechanism for single and multiple-part signatures and 3812 verification. It is described in NIST Special Publication 800-38D [GMAC]. GMAC is a special case of 3813 GCM that authenticates only the Additional Authenticated Data (AAD) part of the GCM mechanism 3814 parameters. When GMAC is used with C_Sign or C_Verify, pData points to the AAD. GMAC does not 3815 use plaintext or ciphertext. 3816 The signature produced by GMAC, also referred to as a Tag, the tag’s length is determined by the 3817 CK_GMAC_PARAMS field ulTagBits. 3818 The IV length is determined by the CK_GMAC_PARAMS field ulIvLen. 3819 Constraints on key types and the length of data are summarized in the following table:
8 “*” indicates 0 or more calls may be made as required
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 103 of 278 3820 Table 85, AES-GMAC: Key And Data Length Function Key type Data length Signature length C_Sign CKK_AES < 2^64 Depends on param’s ulTagBits C_Verify CKK_AES < 2^64 Depends on param’s ulTagBits 3821 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3822 specify the supported range of AES key sizes, in bytes.
3823 2.13.5 AES GCM and CCM Mechanism parameters
3824 CK_GENERATOR_FUNCTION
3825 Functions to generate unique IVs and nonces.
3826 typedef CK_ULONG CK_GENERATOR_FUCNTION;
3827 CK_GCM_PARAMS; CK_GCM_PARAMS_PTR
3828 CK_GCM_PARAMS is a structure that provides the parameters to the CKM_AES_GCM mechanism 3829 when used for Encrypt or Decrypt. It is defined as follows: 3830 typedef struct CK_GCM_PARAMS { 3831 CK_BYTE_PTR pIv; 3832 CK_ULONG ulIvLen; 3833 CK_BYTE_PTR pAAD; 3834 CK_ULONG ulAADLen; 3835 CK_ULONG ulTagBits; 3836 } CK_GCM_PARAMS; 3837 3838 The fields of the structure have the following meanings: 3839 pIv pointer to initialization vector
3840 ulIvLen length of initialization vector in bytes. The length of the initialization 3841 vector can be any number between 1 and (2^32) - 1. 96-bit (12 3842 byte) IV values can be processed more efficiently, so that length is 3843 recommended for situations in which efficiency is critical.
3844 pAAD pointer to additional authentication data. This data is authenticated 3845 but not encrypted.
3846 ulAADLen length of pAAD in bytes. The length of the AAD can be any number 3847 between 0 and (2^32) – 1.
3848 ulTagBits length of authentication tag (output following cipher text) in bits. Can 3849 be any value between 0 and 128.
3850 CK_GCM_PARAMS_PTR is a pointer to a CK_GCM_PARAMS.
3851 CK_GCM_MESSAGE_PARAMS; CK_GCM_MESSAGE_PARAMS_PTR
3852 CK_GCM_MESSAGE_PARAMS is a structure that provides the parameters to the CKM_AES_GCM 3853 mechanism when used for MessageEncrypt or MessageDecrypt. It is defined as follows:
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 104 of 278 3854 typedef struct CK_GCM_MESSAGE_PARAMS { 3855 CK_BYTE_PTR pIv; 3856 CK_ULONG ulIvLen; 3857 CK_ULONG ulIvFixedBits; 3858 CK_GENERATOR_FUNCTION ivGenerator; 3859 CK_BYTE_PTR pTag; 3860 CK_ULONG ulTagBits; 3861 } CK_GCM_MESSAGE_PARAMS; 3862 3863 The fields of the structure have the following meanings: 3864 pIv pointer to initialization vector
3865 ulIvLen length of initialization vector in bytes. The length of the initialization 3866 vector can be any number between 1 and (2^32) - 1. 96-bit (12 byte) 3867 IV values can be processed more efficiently, so that length is 3868 recommended for situations in which efficiency is critical.
3869 ulIvFixedBits number of bits of the original IV to preserve when generating an 3870 new IV. These bits are counted from the Most significant bits (to the 3871 right).
3872 ivGenerator Function used to generate a new IV. Each IV must be unique for a 3873 given session.
3874 pTag location of the authentication tag which is returned on 3875 MessageEncrypt, and provided on MessageDecrypt.
3876 ulTagBits length of authentication tag in bits. Can be any value between 0 and 3877 128.
3878 CK_GCM_MESSAGE_PARAMS_PTR is a pointer to a CK_GCM_MESSAGE_PARAMS. 3879
3880 CK_CCM_PARAMS; CK_CCM_PARAMS_PTR
3881 CK_CCM_PARAMS is a structure that provides the parameters to the CKM_AES_CCM mechanism 3882 when used for Encrypt or Decrypt. It is defined as follows: 3883 typedef struct CK_CCM_PARAMS { 3884 CK_ULONG ulDataLen; /*plaintext or ciphertext*/ 3885 CK_BYTE_PTR pNonce; 3886 CK_ULONG ulNonceLen; 3887 CK_BYTE_PTR pAAD; 3888 CK_ULONG ulAADLen; 3889 CK_ULONG ulMACLen; 3890 } CK_CCM_PARAMS; 3891 The fields of the structure have the following meanings, where L is the size in bytes of the data length’s 3892 length (2 <= L <= 8): 3893 ulDataLen length of the data where 0 <= ulDataLen < 2^(8L).
3894 pNonce the nonce.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 105 of 278 3895 ulNonceLen length of pNonce in bytes where 7 <= ulNonceLen <= 13.
3896 pAAD Additional authentication data. This data is authenticated but not 3897 encrypted.
3898 ulAADLen length of pAAD in bytes where 0 <= ulAADLen <= (2^32) - 1.
3899 ulMACLen length of the MAC (output following cipher text) in bytes. Valid 3900 values are 4, 6, 8, 10, 12, 14, and 16.
3901 CK_CCM_PARAMS_PTR is a pointer to a CK_CCM_PARAMS.
3902 CK_CCM_MESSAGE_PARAMS; CK_CCM_MESSAGE_PARAMS_PTR
3903 CK_CCM_MESSAGE_PARAMS is a structure that provides the parameters to the CKM_AES_CCM 3904 mechanism when used for MessageEncrypt or MessageDecrypt. It is defined as follows: 3905 typedef struct CK_CCM_MESSAGE_PARAMS { 3906 CK_ULONG ulDataLen; /*plaintext or ciphertext*/ 3907 CK_BYTE_PTR pNonce; 3908 CK_ULONG ulNonceLen; 3909 CK_ULONG ulNonceFixedBits; 3910 CK_GENERATOR_FUNCTION nonceGenerator; 3911 CK_BYTE_PTR pMAC; 3912 CK_ULONG ulMACLen; 3913 } CK_CCM_MESSAGE_PARAMS; 3914 3915 The fields of the structure have the following meanings, where L is the size in bytes of the data length’s 3916 length (2 <= L <= 8): 3917 ulDataLen length of the data where 0 <= ulDataLen < 2^(8L).
3918 pNonce the nonce.
3919 ulNonceLen length of pNonce in bytes where 7 <= ulNonceLen <= 13.
3920 ulNonceFixedBits number of bits of the original nonce to preserve when generating a 3921 new nonce. These bits are counted from the Most significant bits (to 3922 the right).
3923 nonceGenerator Function used to generate a new nonce. Each nonce must be 3924 unique for a given session.
3925 pMAC location of the CCM MAC returned on MessageEncrypt, provided on 3926 MessageDecrypt
3927 ulMACLen length of the MAC (output following cipher text) in bytes. Valid 3928 values are 4, 6, 8, 10, 12, 14, and 16.
3929 CK_CCM_MESSAGE_PARAMS_PTR is a pointer to a CK_CCM_MESSAGE_PARAMS. 3930
3931 2.14 AES CMAC 3932 Table 86, Mechanisms vs. Functions
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 106 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_AES_CMAC_GENERAL CKM_AES_CMAC 3933 1 SR = SignRecover, VR = VerifyRecover.
3934 2.14.1 Definitions 3935 Mechanisms: 3936 CKM_AES_CMAC_GENERAL 3937 CKM_AES_CMAC
3938 2.14.2 Mechanism parameters 3939 CKM_AES_CMAC_GENERAL uses the existing CK_MAC_GENERAL_PARAMS structure. 3940 CKM_AES_CMAC does not use a mechanism parameter.
3941 2.14.3 General-length AES-CMAC 3942 General-length AES-CMAC, denoted CKM_AES_CMAC_GENERAL, is a mechanism for single- and 3943 multiple-part signatures and verification, based on [NIST SP800-38B] and [RFC 4493]. 3944 It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length 3945 desired from the mechanism. 3946 The output bytes from this mechanism are taken from the start of the final AES cipher block produced in 3947 the MACing process. 3948 Constraints on key types and the length of data are summarized in the following table: 3949 Table 87, General-length AES-CMAC: Key And Data Length Function Key type Data length Signature length C_Sign CKK_AES any 1-block size, as specified in parameters C_Verify CKK_AES any 1-block size, as specified in parameters 3950 References [NIST SP800-38B] and [RFC 4493] recommend that the output MAC is not truncated to less 3951 than 64 bits. The MAC length must be specified before the communication starts, and must not be 3952 changed during the lifetime of the key. It is the caller’s responsibility to follow these rules. 3953 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3954 specify the supported range of AES key sizes, in bytes.
3955 2.14.4 AES-CMAC 3956 AES-CMAC, denoted CKM_AES_CMAC, is a special case of the general-length AES-CMAC mechanism. 3957 AES-MAC always produces and verifies MACs that are a full block size in length, the default output length 3958 specified by [RFC 4493]. 3959 Constraints on key types and the length of data are summarized in the following table: 3960 Table 88, AES-CMAC: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 107 of 278 Function Key type Data length Signature length C_Sign CKK_AES any Block size (16 bytes) C_Verify CKK_AES any Block size (16 bytes) 3961 References [NIST SP800-38B] and [RFC 4493] recommend that the output MAC is not truncated to less 3962 than 64 bits. The MAC length must be specified before the communication starts, and must not be 3963 changed during the lifetime of the key. It is the caller’s responsibility to follow these rules. 3964 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3965 specify the supported range of AES key sizes, in bytes.
3966 2.15 AES XTS 3967 Table 89, Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair
CKM_AES_XTS
CKM_AES_XTS_KEY_GEN
3968 2.15.1 Definitions 3969 This section defines the key type “CKK_AES_XTS” for type CK_KEY_TYPE as used in the 3970 CKA_KEY_TYPE attribute of key objects. 3971 Mechanisms: 3972 CKM_AES_XTS 3973 CKM_AES_CTS_KEY_GEN
3974 2.15.2 AES-XTS secret key objects 3975 Table 90, AES-XTS Secret Key Object Attributes Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key value (32 or 64 bytes) CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value 3976 - Refer to [PKCS11-Base] table 11 for footnotes
3977 2.15.3 AES-XTS key generation 3978 The double-length AES-XTS key generation mechanism, denoted CKM_AES_XTS_KEY_GEN, is a key 3979 generation mechanism for double-length AES-XTS keys. 3980 The mechanism generates AES-XTS keys with a particular length in bytes as specified in the 3981 CKA_VALUE_LEN attributes of the template for the key. 3982 This mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 3983 key. Other attributes supported by the double-length AES-XTS key type (specifically, the flags indicating 3984 which functions the key supports) may be specified in the template for the key, or else are assigned 3985 default initial values. 3986 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 3987 specify the supported range of AES-XTS key sizes, in bytes.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 108 of 278 3988 2.15.4 AES-XTS 3989 AES-XTS (XEX-based Tweaked CodeBook mode with CipherText Stealing), denoted CKM_AES_XTS, 3990 isa mechanism for single- and multiple-part encryption and decryption. It is specified in NIST SP800-38E. 3991 Its single parameter is a Data Unit Sequence Number 16 bytes long. Supported key lengths are 32 and 3992 64 bytes. Keys are internally split into half-length sub-keys of 16 and 32 bytes respectively. Constraintson 3993 key types and the length of data are summarized in the following table: 3994 Table 91, AES-XTS: Key And Data Length Function Key type Input length Output length Comments C_Encrypt CKK_AES_XTS Any, ≥ block size (16 Same as input length No final part bytes) C_Decrypt CKK_AES_XTS Any, ≥ block size (16 Same as input length No final part bytes) 3995
3996 2.16 AES Key Wrap 3997 Table 92, AES Key Wrap Mechanisms vs. Functions 3998 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_AES_KEY_WRAP CKM_AES_KEY_WRAP_PAD CKM_AES_KEY_WRAP_KWP 1SR = SignRecover, VR = VerifyRecover
3999 2.16.1 Definitions 4000 Mechanisms: 4001 CKM_AES_KEY_WRAP 4002 CKM_AES_KEY_WRAP_PAD 4003 CKM_AES_KEY_WRAP_KWP
4004 2.16.2 AES Key Wrap Mechanism parameters 4005 The mechanisms will accept an optional mechanism parameter as the Initialization vector which, if 4006 present, must be a fixed size array of 8 bytes for CKM_AES_KEY_WRAP and 4007 CKM_AES_KEY_WRAP_PAD, resp. 4 bytes for CKM_AES_KEY_WRAP_KWP; and, if NULL, will use 4008 the default initial value defined in Section 4.3 resp. 6.2 / 6.3 of [AES KEYWRAP]. 4009 The type of this parameter is CK_BYTE_PTR and the pointer points to the array of bytes to be used as 4010 the initial value. The length shall be either 0 and the pointer NULL; or 8 for CKM_AES_KEY_WRAP / 4011 CKM_AES_KEY_WRAP_PAD, resp. 4 for CKM_AES_KEY_WRAP_KWP, and the pointer non-NULL.
4012 2.16.3 AES Key Wrap 4013 The mechanisms support only single-part operations, single part wrapping and unwrapping, and single- 4014 part encryption and decryption.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 109 of 278 4015 The CKM_AES_KEY_WRAP mechanism can only wrap a key resp. encrypt a block of data whose size is 4016 an exact multiple of the AES Key Wrap algorithm block size. Wrapping / encryption is done as defined in 4017 Section 6.2 of [AES KEYWRAP]. 4018 The CKM_AES_KEY_WRAP_PAD mechanism can wrap a key or encrypt a block of data of any length. It 4019 does the padding detailed in PKCS #7 of inputs (keys or data blocks), always producing wrapped output 4020 that is larger than the input key/data to be wrapped. This padding is done by the token before being 4021 passed to the AES key wrap algorithm, which then wraps / encrypts the padded block of data as defined 4022 in Section 6.2 of [AES KEYWRAP]. 4023 The CKM_AES_KEY_WRAP_KWP mechanism can wrap a key or encrypt block of data of any length. 4024 The input is padded and wrapped / encrypted as defined in Section 6.3 of [AES KEYWRAP], which 4025 produces same results as RFC 5649.
4026 2.17 Key derivation by data encryption – DES & AES 4027 These mechanisms allow derivation of keys using the result of an encryption operation as the key value. 4028 They are for use with the C_DeriveKey function. 4029 Table 93, Key derivation by data encryption Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_DES_ECB_ENCRYPT_DATA CKM_DES_CBC_ENCRYPT_DATA CKM_DES3_ECB_ENCRYPT_DATA CKM_DES3_CBC_ENCRYPT_DATA CKM_AES_ECB_ENCRYPT_DATA CKM_AES_CBC_ENCRYPT_DATA
4030 2.17.1 Definitions 4031 Mechanisms: 4032 CKM_DES_ECB_ENCRYPT_DATA 4033 CKM_DES_CBC_ENCRYPT_DATA 4034 CKM_DES3_ECB_ENCRYPT_DATA 4035 CKM_DES3_CBC_ENCRYPT_DATA 4036 CKM_AES_ECB_ENCRYPT_DATA 4037 CKM_AES_CBC_ENCRYPT_DATA 4038 4039 typedef struct CK_DES_CBC_ENCRYPT_DATA_PARAMS { 4040 CK_BYTE iv[8]; 4041 CK_BYTE_PTR pData; 4042 CK_ULONG length; 4043 } CK_DES_CBC_ENCRYPT_DATA_PARAMS; 4044 4045 typedef CK_DES_CBC_ENCRYPT_DATA_PARAMS CK_PTR 4046 CK_DES_CBC_ENCRYPT_DATA_PARAMS_PTR; 4047
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 110 of 278 4048 typedef struct CK_AES_CBC_ENCRYPT_DATA_PARAMS { 4049 CK_BYTE iv[16]; 4050 CK_BYTE_PTR pData; 4051 CK_ULONG length; 4052 } CK_AES_CBC_ENCRYPT_DATA_PARAMS; 4053 4054 typedef CK_AES_CBC_ENCRYPT_DATA_PARAMS CK_PTR 4055 CK_AES_CBC_ENCRYPT_DATA_PARAMS_PTR;
4056 2.17.2 Mechanism Parameters 4057 Uses CK_KEY_DERIVATION_STRING_DATA as defined in section 2.43.2 4058 Table 94, Mechanism Parameters CKM_DES_ECB_ENCRYPT_DATA Uses CK_KEY_DERIVATION_STRING_DATA CKM_DES3_ECB_ENCRYPT_DATA structure. Parameter is the data to be encrypted and must be a multiple of 8 bytes long. CKM_AES_ECB_ENCRYPT_DATA Uses CK_KEY_DERIVATION_STRING_DATA structure. Parameter is the data to be encrypted and must be a multiple of 16 long. CKM_DES_CBC_ENCRYPT_DATA Uses CK_DES_CBC_ENCRYPT_DATA_PARAMS. CKM_DES3_CBC_ENCRYPT_DATA Parameter is an 8 byte IV value followed by the data. The data value part must be a multiple of 8 bytes long. CKM_AES_CBC_ENCRYPT_DATA Uses CK_AES_CBC_ENCRYPT_DATA_PARAMS. Parameter is an 16 byte IV value followed by the data. The data value part must be a multiple of 16 bytes long.
4059 2.17.3 Mechanism Description 4060 The mechanisms will function by performing the encryption over the data provided using the base key. 4061 The resulting cipher text shall be used to create the key value of the resulting key. If not all the cipher text 4062 is used then the part discarded will be from the trailing end (least significant bytes) of the cipher text data. 4063 The derived key shall be defined by the attribute template supplied but constrained by the length of cipher 4064 text available for the key value and other normal PKCS11 derivation constraints. 4065 Attribute template handling, attribute defaulting and key value preparation will operate as per the SHA-1 4066 Key Derivation mechanism in section 2.20.5. 4067 If the data is too short to make the requested key then the mechanism returns 4068 CKR_DATA_LEN_RANGE.
4069 2.18 Double and Triple-length DES 4070 Table 95, Double and Triple-Length DES Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_DES2_KEY_GEN CKM_DES3_KEY_GEN CKM_DES3_ECB
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 111 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_DES3_CBC CKM_DES3_CBC_PAD CKM_DES3_MAC_GENERAL CKM_DES3_MAC
4071 2.18.1 Definitions 4072 This section defines the key type “CKK_DES2” and “CKK_DES3” for type CK_KEY_TYPE as used in the 4073 CKA_KEY_TYPE attribute of key objects. 4074 Mechanisms: 4075 CKM_DES2_KEY_GEN 4076 CKM_DES3_KEY_GEN 4077 CKM_DES3_ECB 4078 CKM_DES3_CBC 4079 CKM_DES3_MAC 4080 CKM_DES3_MAC_GENERAL 4081 CKM_DES3_CBC_PAD
4082 2.18.2 DES2 secret key objects 4083 DES2 secret key objects (object class CKO_SECRET_KEY, key type CKK_DES2) hold double-length 4084 DES keys. The following table defines the DES2 secret key object attributes, in addition to the common 4085 attributes defined for this object class: 4086 Table 96, DES2 Secret Key Object Attributes Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key value (always 16 bytes long) 4087 - Refer to [PKCS11-Base] table 11 for footnotes 4088 DES2 keys must always have their parity bits properly set as described in FIPS PUB 46-3 (i.e., each of 4089 the DES keys comprising a DES2 key must have its parity bits properly set). Attempting to create or 4090 unwrap a DES2 key with incorrect parity will return an error. 4091 The following is a sample template for creating a double-length DES secret key object: 4092 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 4093 CK_KEY_TYPE keyType = CKK_DES2; 4094 CK_UTF8CHAR label[] = “A DES2 secret key object”; 4095 CK_BYTE value[16] = {...}; 4096 CK_BBOOL true = CK_TRUE; 4097 CK_ATTRIBUTE template[] = { 4098 {CKA_CLASS, &class, sizeof(class)}, 4099 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 4100 {CKA_TOKEN, &true, sizeof(true)}, 4101 {CKA_LABEL, label, sizeof(label)-1},
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 112 of 278 4102 {CKA_ENCRYPT, &true, sizeof(true)}, 4103 {CKA_VALUE, value, sizeof(value)} 4104 }; 4105 4106 CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three 4107 bytes of the ECB encryption of a single block of null (0x00) bytes, using the default cipher associated with 4108 the key type of the secret key object.
4109 2.18.3 DES3 secret key objects 4110 DES3 secret key objects (object class CKO_SECRET_KEY, key type CKK_DES3) hold triple-length DES 4111 keys. The following table defines the DES3 secret key object attributes, in addition to the common 4112 attributes defined for this object class: 4113 Table 97, DES3 Secret Key Object Attributes Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key value (always 24 bytes long) 4114 - Refer to [PKCS11-Base] table 11 for footnotes 4115 DES3 keys must always have their parity bits properly set as described in FIPS PUB 46-3 (i.e., each of 4116 the DES keys comprising a DES3 key must have its parity bits properly set). Attempting to create or 4117 unwrap a DES3 key with incorrect parity will return an error. 4118 The following is a sample template for creating a triple-length DES secret key object: 4119 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 4120 CK_KEY_TYPE keyType = CKK_DES3; 4121 CK_UTF8CHAR label[] = “A DES3 secret key object”; 4122 CK_BYTE value[24] = {...}; 4123 CK_BBOOL true = CK_TRUE; 4124 CK_ATTRIBUTE template[] = { 4125 {CKA_CLASS, &class, sizeof(class)}, 4126 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 4127 {CKA_TOKEN, &true, sizeof(true)}, 4128 {CKA_LABEL, label, sizeof(label)-1}, 4129 {CKA_ENCRYPT, &true, sizeof(true)}, 4130 {CKA_VALUE, value, sizeof(value)} 4131 }; 4132 4133 CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three 4134 bytes of the ECB encryption of a single block of null (0x00) bytes, using the default cipher associated with 4135 the key type of the secret key object.
4136 2.18.4 Double-length DES key generation 4137 The double-length DES key generation mechanism, denoted CKM_DES2_KEY_GEN, is a key 4138 generation mechanism for double-length DES keys. The DES keys making up a double-length DES key 4139 both have their parity bits set properly, as specified in FIPS PUB 46-3. 4140 It does not have a parameter. 4141 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4142 key. Other attributes supported by the double-length DES key type (specifically, the flags indicating which 4143 functions the key supports) may be specified in the template for the key, or else are assigned default 4144 initial values.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 113 of 278 4145 Double-length DES keys can be used with all the same mechanisms as triple-DES keys: 4146 CKM_DES3_ECB, CKM_DES3_CBC, CKM_DES3_CBC_PAD, CKM_DES3_MAC_GENERAL, and 4147 CKM_DES3_MAC. Triple-DES encryption with a double-length DES key is equivalent to encryption with 4148 a triple-length DES key with K1=K3 as specified in FIPS PUB 46-3. 4149 When double-length DES keys are generated, it is token-dependent whether or not it is possible for either 4150 of the component DES keys to be “weak” or “semi-weak” keys.
4151 2.18.5 Triple-length DES Order of Operations 4152 Triple-length DES encryptions are carried out as specified in FIPS PUB 46-3: encrypt, decrypt, encrypt. 4153 Decryptions are carried out with the opposite three steps: decrypt, encrypt, decrypt. The mathematical 4154 representations of the encrypt and decrypt operations are as follows: 4155 DES3-E({K1,K2,K3}, P) = E(K3, D(K2, E(K1, P))) 4156 DES3-D({K1,K2,K3}, C) = D(K1, E(K2, D(K3, P)))
4157 2.18.6 Triple-length DES in CBC Mode 4158 Triple-length DES operations in CBC mode, with double or triple-length keys, are performed using outer 4159 CBC as defined in X9.52. X9.52 describes this mode as TCBC. The mathematical representations of the 4160 CBC encrypt and decrypt operations are as follows: 4161 DES3-CBC-E({K1,K2,K3}, P) = E(K3, D(K2, E(K1, P + I))) 4162 DES3-CBC-D({K1,K2,K3}, C) = D(K1, E(K2, D(K3, P))) + I 4163 The value I is either an 8-byte initialization vector or the previous block of cipher text that is added to the 4164 current input block. The addition operation is used is addition modulo-2 (XOR).
4165 2.18.7 DES and Triple length DES in OFB Mode 4166 Table 98, DES and Triple Length DES in OFB Mode Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_DES_OFB64 CKM_DES_OFB8 CKM_DES_CFB64 CKM_DES_CFB8 4167 4168 Cipher DES has a output feedback mode, DES-OFB, denoted CKM_DES_OFB8 and 4169 CKM_DES_OFB64. It is a mechanism for single and multiple-part encryption and decryption with DES. 4170 It has a parameter, an initialization vector for this mode. The initialization vector has the same length as 4171 the block size. 4172 Constraints on key types and the length of data are summarized in the following table: 4173 Table 99, OFB: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 114 of 278 Function Key type Input Output length Comments length C_Encrypt CKK_DES, any same as input length no final part CKK_DES2, CKK_DES3 C_Decrypt CKK_DES, any same as input length no final part CKK_DES2, CKK_DES3 4174 For this mechanism the CK_MECHANISM_INFO structure is as specified for CBC mode.
4175 2.18.8 DES and Triple length DES in CFB Mode 4176 Cipher DES has a cipher feedback mode, DES-CFB, denoted CKM_DES_CFB8 and CKM_DES_CFB64. 4177 It is a mechanism for single and multiple-part encryption and decryption with DES. 4178 It has a parameter, an initialization vector for this mode. The initialization vector has the same length as 4179 the block size. 4180 Constraints on key types and the length of data are summarized in the following table: 4181 Table 100, CFB: Key And Data Length Function Key type Input Output length Comments length C_Encrypt CKK_DES, any same as input length no final part CKK_DES2, CKK_DES3 C_Decrypt CKK_DES, any same as input length no final part CKK_DES2, CKK_DES3 4182 For this mechanism the CK_MECHANISM_INFO structure is as specified for CBC mode.
4183 2.19 Double and Triple-length DES CMAC 4184 Table 101, Double and Triple-length DES CMAC Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_DES3_CMAC_GENERAL CKM_DES3_CMAC 4185 1 SR = SignRecover, VR = VerifyRecover. 4186 4187 The following additional DES3 mechanisms have been added.
4188 2.19.1 Definitions 4189 Mechanisms: 4190 CKM_DES3_CMAC_GENERAL 4191 CKM_DES3_CMAC
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 115 of 278 4192 2.19.2 Mechanism parameters 4193 CKM_DES3_CMAC_GENERAL uses the existing CK_MAC_GENERAL_PARAMS structure. 4194 CKM_DES3_CMAC does not use a mechanism parameter.
4195 2.19.3 General-length DES3-MAC 4196 General-length DES3-CMAC, denoted CKM_DES3_CMAC_GENERAL, is a mechanism for single- and 4197 multiple-part signatures and verification with DES3 or DES2 keys, based on [NIST sp800-38b]. 4198 It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length 4199 desired from the mechanism. 4200 The output bytes from this mechanism are taken from the start of the final DES3 cipher block produced in 4201 the MACing process. 4202 Constraints on key types and the length of data are summarized in the following table: 4203 Table 102, General-length DES3-CMAC: Key And Data Length Function Key type Data length Signature length C_Sign CKK_DES3 any 1-block size, as specified in parameters CKK_DES2 C_Verify CKK_DES3 any 1-block size, as specified in parameters CKK_DES2 4204 Reference [NIST sp800-38b] recommends that the output MAC is not truncated to less than 64 bits 4205 (which means using the entire block for DES). The MAC length must be specified before the 4206 communication starts, and must not be changed during the lifetime of the key. It is the caller’s 4207 responsibility to follow these rules. 4208 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4209 are not used
4210 2.19.4 DES3-CMAC 4211 DES3-CMAC, denoted CKM_DES3_CMAC, is a special case of the general-length DES3-CMAC 4212 mechanism. DES3-MAC always produces and verifies MACs that are a full block size in length, since the 4213 DES3 block length is the minimum output length recommended by [NIST sp800-38b]. 4214 Constraints on key types and the length of data are summarized in the following table: 4215 Table 103, DES3-CMAC: Key And Data Length Function Key type Data length Signature length C_Sign CKK_DES3 any Block size (8 bytes) CKK_DES2 C_Verify CKK_DES3 any Block size (8 bytes) CKK_DES2 4216 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4217 are not used.
4218 2.20 SHA-1 4219 Table 104, SHA-1 Mechanisms vs. Functions
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 116 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_SHA_1 CKM_SHA_1_HMAC_GENERAL CKM_SHA_1_HMAC CKM_SHA1_KEY_DERIVATION CKM_SHA_1_KEY_GEN
4220 2.20.1 Definitions 4221 This section defines the key type “CKK_SHA_1_HMAC” for type CK_KEY_TYPE as used in the 4222 CKA_KEY_TYPE attribute of key objects. 4223 Mechanisms: 4224 CKM_SHA_1 4225 CKM_SHA_1_HMAC 4226 CKM_SHA_1_HMAC_GENERAL 4227 CKM_SHA1_KEY_DERIVATION 4228 CKM_SHA_1_KEY_GEN 4229
4230 2.20.2 SHA-1 digest 4231 The SHA-1 mechanism, denoted CKM_SHA_1, is a mechanism for message digesting, following the 4232 Secure Hash Algorithm with a 160-bit message digest defined in FIPS PUB 180-2. 4233 It does not have a parameter. 4234 Constraints on the length of input and output data are summarized in the following table. For single-part 4235 digesting, the data and the digest may begin at the same location in memory. 4236 Table 105, SHA-1: Data Length Function Input length Digest length C_Digest any 20
4237 2.20.3 General-length SHA-1-HMAC 4238 The general-length SHA-1-HMAC mechanism, denoted CKM_SHA_1_HMAC_GENERAL, is a 4239 mechanism for signatures and verification. It uses the HMAC construction, based on the SHA-1 hash 4240 function. The keys it uses are generic secret keys and CKK_SHA_1_HMAC. 4241 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4242 output. This length should be in the range 1-20 (the output size of SHA-1 is 20 bytes). Signatures 4243 (MACs) produced by this mechanism will be taken from the start of the full 20-byte HMAC output. 4244 Table 106, General-length SHA-1-HMAC: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 117 of 278 Function Key type Data length Signature length C_Sign generic secret any 1-20, depending on parameters CKK_SHA_1_ HMAC C_Verify generic secret any 1-20, depending on parameters CKK_SHA_1_ HMAC
4245 2.20.4 SHA-1-HMAC 4246 The SHA-1-HMAC mechanism, denoted CKM_SHA_1_HMAC, is a special case of the general-length 4247 SHA-1-HMAC mechanism in Section 2.20.3. 4248 It has no parameter, and always produces an output of length 20.
4249 2.20.5 SHA-1 key derivation 4250 SHA-1 key derivation, denoted CKM_SHA1_KEY_DERIVATION, is a mechanism which provides the 4251 capability of deriving a secret key by digesting the value of another secret key with SHA-1. 4252 The value of the base key is digested once, and the result is used to make the value of derived secret 4253 key. 4254 If no length or key type is provided in the template, then the key produced by this mechanism will be a 4255 generic secret key. Its length will be 20 bytes (the output size of SHA-1). 4256 If no key type is provided in the template, but a length is, then the key produced by this mechanism 4257 will be a generic secret key of the specified length. 4258 If no length was provided in the template, but a key type is, then that key type must have a well- 4259 defined length. If it does, then the key produced by this mechanism will be of the type specified in the 4260 template. If it doesn’t, an error will be returned. 4261 If both a key type and a length are provided in the template, the length must be compatible with that 4262 key type. The key produced by this mechanism will be of the specified type and length. 4263 If a DES, DES2, or CDMF key is derived with this mechanism, the parity bits of the key will be set 4264 properly. 4265 If the requested type of key requires more than 20 bytes, such as DES3, an error is generated. 4266 This mechanism has the following rules about key sensitivity and extractability: 4267 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 4268 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 4269 default value. 4270 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 4271 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 4272 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 4273 CKA_SENSITIVE attribute. 4274 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 4275 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 4276 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 4277 value from its CKA_EXTRACTABLE attribute.
4278 2.20.6 SHA-1 HMAC key generation 4279 The SHA-1-HMAC key generation mechanism, denoted CKM_SHA_1_KEY_GEN, is a key generation 4280 mechanism for NIST’s SHA-1-HMAC. 4281 It does not have a parameter.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 118 of 278 4282 The mechanism generates SHA-1-HMAC keys with a particular length in bytes, as specified in the 4283 CKA_VALUE_LEN attribute of the template for the key. 4284 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4285 key. Other attributes supported by the SHA-1-HMAC key type (specifically, the flags indicating which 4286 functions the key supports) may be specified in the template for the key, or else are assigned default 4287 initial values. 4288 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4289 specify the supported range of CKM_SHA_1_HMAC key sizes, in bytes.
4290 2.21 SHA-224 4291 Table 107, SHA-224 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_SHA224 CKM_SHA224_HMAC CKM_SHA224_HMAC_GENERAL CKM_SHA224_RSA_PKCS CKM_SHA224_RSA_PKCS_PSS CKM_SHA224_KEY_DERIVATION CKM_SHA224_KEY_GEN
4292 2.21.1 Definitions 4293 This section defines the key type “CKK_SHA224_HMAC” for type CK_KEY_TYPE as used in the 4294 CKA_KEY_TYPE attribute of key objects. 4295 Mechanisms: 4296 CKM_SHA224 4297 CKM_SHA224_HMAC 4298 CKM_SHA224_HMAC_GENERAL 4299 CKM_SHA224_KEY_DERIVATION 4300 CKM_SHA224_KEY_GEN
4301 2.21.2 SHA-224 digest 4302 The SHA-224 mechanism, denoted CKM_SHA224, is a mechanism for message digesting, following the 4303 Secure Hash Algorithm with a 224-bit message digest defined in 0. 4304 It does not have a parameter. 4305 Constraints on the length of input and output data are summarized in the following table. For single-part 4306 digesting, the data and the digest may begin at the same location in memory. 4307 Table 108, SHA-224: Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 119 of 278 Function Input length Digest length C_Digest any 28
4308 2.21.3 General-length SHA-224-HMAC 4309 The general-length SHA-224-HMAC mechanism, denoted CKM_SHA224_HMAC_GENERAL, is the 4310 same as the general-length SHA-1-HMAC mechanism except that it uses the HMAC construction based 4311 on the SHA-224 hash function and length of the output should be in the range 1-28. The keys it uses are 4312 generic secret keys and CKK_SHA224_HMAC. FIPS-198 compliant tokens may require the key length to 4313 be at least 14 bytes; that is, half the size of the SHA-224 hash output. 4314 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4315 output. This length should be in the range 1-28 (the output size of SHA-224 is 28 bytes). FIPS-198 4316 compliant tokens may constrain the output length to be at least 4 or 14 (half the maximum length). 4317 Signatures (MACs) produced by this mechanism will be taken from the start of the full 28-byte HMAC 4318 output. 4319 Table 109, General-length SHA-224-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret Any 1-28, depending on parameters CKK_SHA224_ HMAC C_Verify generic secret Any 1-28, depending on parameters CKK_SHA224_ HMAC
4320 2.21.4 SHA-224-HMAC 4321 The SHA-224-HMAC mechanism, denoted CKM_SHA224_HMAC, is a special case of the general-length 4322 SHA-224-HMAC mechanism. 4323 It has no parameter, and always produces an output of length 28.
4324 2.21.5 SHA-224 key derivation 4325 SHA-224 key derivation, denoted CKM_SHA224_KEY_DERIVATION, is the same as the SHA-1 key 4326 derivation mechanism in Section 12.21.5 except that it uses the SHA-224 hash function and the relevant 4327 length is 28 bytes.
4328 2.21.6 SHA-224 HMAC key generation 4329 The SHA-224-HMAC key generation mechanism, denoted CKM_SHA224_KEY_GEN, is a key 4330 generation mechanism for NIST’s SHA224-HMAC. 4331 It does not have a parameter. 4332 The mechanism generates SHA224-HMAC keys with a particular length in bytes, as specified in the 4333 CKA_VALUE_LEN attribute of the template for the key. 4334 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4335 key. Other attributes supported by the SHA224-HMAC key type (specifically, the flags indicating which 4336 functions the key supports) may be specified in the template for the key, or else are assigned default 4337 initial values. 4338 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4339 specify the supported range of CKM_SHA224_HMAC key sizes, in bytes.
4340 2.22 SHA-256 4341 Table 110, SHA-256 Mechanisms vs. Functions pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 120 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_SHA256 CKM_SHA256_HMAC_GENERAL CKM_SHA256_HMAC CKM_SHA256_KEY_DERIVATION CKM_SHA256_KEY_GEN
4342 2.22.1 Definitions 4343 This section defines the key type “CKK_SHA256_HMAC” for type CK_KEY_TYPE as used in the 4344 CKA_KEY_TYPE attribute of key objects. 4345 Mechanisms: 4346 CKM_SHA256 4347 CKM_SHA256_HMAC 4348 CKM_SHA256_HMAC_GENERAL 4349 CKM_SHA256_KEY_DERIVATION 4350 CKM_SHA256_KEY_GEN
4351 2.22.2 SHA-256 digest 4352 The SHA-256 mechanism, denoted CKM_SHA256, is a mechanism for message digesting, following the 4353 Secure Hash Algorithm with a 256-bit message digest defined in FIPS PUB 180-2. 4354 It does not have a parameter. 4355 Constraints on the length of input and output data are summarized in the following table. For single-part 4356 digesting, the data and the digest may begin at the same location in memory. 4357 Table 111, SHA-256: Data Length Function Input length Digest length C_Digest any 32
4358 2.22.3 General-length SHA-256-HMAC 4359 The general-length SHA-256-HMAC mechanism, denoted CKM_SHA256_HMAC_GENERAL, is the 4360 same as the general-length SHA-1-HMAC mechanism in Section 2.20.3, except that it uses the HMAC 4361 construction based on the SHA-256 hash function and length of the output should be in the range 1-32. 4362 The keys it uses are generic secret keys and CKK_SHA256_HMAC. FIPS-198 compliant tokens may 4363 require the key length to be at least 16 bytes; that is, half the size of the SHA-256 hash output. 4364 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4365 output. This length should be in the range 1-32 (the output size of SHA-256 is 32 bytes). FIPS-198 4366 compliant tokens may constrain the output length to be at least 4 or 16 (half the maximum length). 4367 Signatures (MACs) produced by this mechanism will be taken from the start of the full 32-byte HMAC 4368 output. 4369 Table 112, General-length SHA-256-HMAC: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 121 of 278 Function Key type Data length Signature length C_Sign generic secret, Any 1-32, depending on parameters CKK_SHA256_ HMAC C_Verify generic secret, Any 1-32, depending on parameters CKK_SHA256_ HMAC
4370 2.22.4 SHA-256-HMAC 4371 The SHA-256-HMAC mechanism, denoted CKM_SHA256_HMAC, is a special case of the general-length 4372 SHA-256-HMAC mechanism in Section 2.22.3. 4373 It has no parameter, and always produces an output of length 32.
4374 2.22.5 SHA-256 key derivation 4375 SHA-256 key derivation, denoted CKM_SHA256_KEY_DERIVATION, is the same as the SHA-1 key 4376 derivation mechanism in Section 2.20.5, except that it uses the SHA-256 hash function and the relevant 4377 length is 32 bytes.
4378 2.22.6 SHA-256 HMAC key generation 4379 The SHA-256-HMAC key generation mechanism, denoted CKM_SHA256_KEY_GEN, is a key 4380 generation mechanism for NIST’s SHA256-HMAC. 4381 It does not have a parameter. 4382 The mechanism generates SHA256-HMAC keys with a particular length in bytes, as specified in the 4383 CKA_VALUE_LEN attribute of the template for the key. 4384 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4385 key. Other attributes supported by the SHA256-HMAC key type (specifically, the flags indicating which 4386 functions the key supports) may be specified in the template for the key, or else are assigned default 4387 initial values. 4388 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4389 specify the supported range of CKM_SHA256_HMAC key sizes, in bytes.
4390 2.23 SHA-384 4391 Table 113, SHA-384 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_SHA384 CKM_SHA384_HMAC_GENERAL CKM_SHA384_HMAC CKM_SHA384_KEY_DERIVATION CKM_SHA384_KEY_GEN
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 122 of 278 4392 2.23.1 Definitions 4393 This section defines the key type “CKK_SHA384_HMAC” for type CK_KEY_TYPE as used in the 4394 CKA_KEY_TYPE attribute of key objects. 4395 CKM_SHA384 4396 CKM_SHA384_HMAC 4397 CKM_SHA384_HMAC_GENERAL 4398 CKM_SHA384_KEY_DERIVATION 4399 CKM_SHA384_KEY_GEN
4400 2.23.2 SHA-384 digest 4401 The SHA-384 mechanism, denoted CKM_SHA384, is a mechanism for message digesting, following the 4402 Secure Hash Algorithm with a 384-bit message digest defined in FIPS PUB 180-2. 4403 It does not have a parameter. 4404 Constraints on the length of input and output data are summarized in the following table. For single-part 4405 digesting, the data and the digest may begin at the same location in memory. 4406 Table 114, SHA-384: Data Length Function Input length Digest length C_Digest any 48
4407 2.23.3 General-length SHA-384-HMAC 4408 The general-length SHA-384-HMAC mechanism, denoted CKM_SHA384_HMAC_GENERAL, is the 4409 same as the general-length SHA-1-HMAC mechanism in Section 2.20.3, except that it uses the HMAC 4410 construction based on the SHA-384 hash function and length of the output should be in the range 1-48. 4411 The keys it uses are generic secret keys and CKK_SHA384_HMAC. FIPS-198 compliant tokens may 4412 require the key length to be at least 24 bytes; that is, half the size of the SHA-384 hash output. 4413 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4414 output. This length should be in the range 0-48 (the output size of SHA-384 is 48 bytes). FIPS-198 4415 compliant tokens may constrain the output length to be at least 4 or 24 (half the maximum length). 4416 Signatures (MACs) produced by this mechanism will be taken from the start of the full 48-byte HMAC 4417 output. 4418 Table 115, General-length SHA-384-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret, Any 1-48, depending on parameters CKK_SHA384_ HMAC C_Verify generic secret, Any 1-48, depending on parameters CKK_SHA384_ HMAC 4419
4420 2.23.4 SHA-384-HMAC 4421 The SHA-384-HMAC mechanism, denoted CKM_SHA384_HMAC, is a special case of the general-length 4422 SHA-384-HMAC mechanism. 4423 It has no parameter, and always produces an output of length 48.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 123 of 278 4424 2.23.5 SHA-384 key derivation 4425 SHA-384 key derivation, denoted CKM_SHA384_KEY_DERIVATION, is the same as the SHA-1 key 4426 derivation mechanism in Section 2.20.5, except that it uses the SHA-384 hash function and the relevant 4427 length is 48 bytes.
4428 2.23.6 SHA-384 HMAC key generation 4429 The SHA-384-HMAC key generation mechanism, denoted CKM_SHA384_KEY_GEN, is a key 4430 generation mechanism for NIST’s SHA384-HMAC. 4431 It does not have a parameter. 4432 The mechanism generates SHA384-HMAC keys with a particular length in bytes, as specified in the 4433 CKA_VALUE_LEN attribute of the template for the key. 4434 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4435 key. Other attributes supported by the SHA384-HMAC key type (specifically, the flags indicating which 4436 functions the key supports) may be specified in the template for the key, or else are assigned default 4437 initial values. 4438 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4439 specify the supported range of CKM_SHA384_HMAC key sizes, in bytes.
4440 2.24 SHA-512 4441 Table 116, SHA-512 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_SHA512 CKM_SHA512_HMAC_GENERAL CKM_SHA512_HMAC CKM_SHA512_KEY_DERIVATION CKM_SHA512_KEY_GEN
4442 2.24.1 Definitions 4443 This section defines the key type “CKK_SHA512_HMAC” for type CK_KEY_TYPE as used in the 4444 CKA_KEY_TYPE attribute of key objects. 4445 Mechanisms: 4446 CKM_SHA512 4447 CKM_SHA512_HMAC 4448 CKM_SHA512_HMAC_GENERAL 4449 CKM_SHA512_KEY_DERIVATION 4450 CKM_SHA512_KEY_GEN
4451 2.24.2 SHA-512 digest 4452 The SHA-512 mechanism, denoted CKM_SHA512, is a mechanism for message digesting, following the 4453 Secure Hash Algorithm with a 512-bit message digest defined in FIPS PUB 180-2. 4454 It does not have a parameter.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 124 of 278 4455 Constraints on the length of input and output data are summarized in the following table. For single-part 4456 digesting, the data and the digest may begin at the same location in memory. 4457 Table 117, SHA-512: Data Length Function Input length Digest length C_Digest any 64
4458 2.24.3 General-length SHA-512-HMAC 4459 The general-length SHA-512-HMAC mechanism, denoted CKM_SHA512_HMAC_GENERAL, is the 4460 same as the general-length SHA-1-HMAC mechanism in Section 2.20.3, except that it uses the HMAC 4461 construction based on the SHA-512 hash function and length of the output should be in the range 1-64. 4462 The keys it uses are generic secret keys and CKK_SHA512_HMAC. FIPS-198 compliant tokens may 4463 require the key length to be at least 32 bytes; that is, half the size of the SHA-512 hash output. 4464 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4465 output. This length should be in the range 0-64 (the output size of SHA-512 is 64 bytes). FIPS-198 4466 compliant tokens may constrain the output length to be at least 4 or 32 (half the maximum length). 4467 Signatures (MACs) produced by this mechanism will be taken from the start of the full 64-byte HMAC 4468 output. 4469 Table 118, General-length SHA-384-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret, Any 1-64, depending on parameters CKK_SHA512_ HMAC C_Verify generic secret, Any 1-64, depending on parameters CKK_SHA512_ HMAC 4470
4471 2.24.4 SHA-512-HMAC 4472 The SHA-512-HMAC mechanism, denoted CKM_SHA512_HMAC, is a special case of the general-length 4473 SHA-512-HMAC mechanism. 4474 It has no parameter, and always produces an output of length 64.
4475 2.24.5 SHA-512 key derivation 4476 SHA-512 key derivation, denoted CKM_SHA512_KEY_DERIVATION, is the same as the SHA-1 key 4477 derivation mechanism in Section 2.20.5, except that it uses the SHA-512 hash function and the relevant 4478 length is 64 bytes.
4479 2.24.6 SHA-512 HMAC key generation 4480 The SHA-512-HMAC key generation mechanism, denoted CKM_SHA512_KEY_GEN, is a key 4481 generation mechanism for NIST’s SHA512-HMAC. 4482 It does not have a parameter. 4483 The mechanism generates SHA512-HMAC keys with a particular length in bytes, as specified in the 4484 CKA_VALUE_LEN attribute of the template for the key. 4485 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4486 key. Other attributes supported by the SHA512-HMAC key type (specifically, the flags indicating which 4487 functions the key supports) may be specified in the template for the key, or else are assigned default 4488 initial values.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 125 of 278 4489 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4490 specify the supported range of CKM_SHA512_HMAC key sizes, in bytes.
4491 2.25 SHA-512/224 4492 Table 119, SHA-512/224 Mechanisms vs. Functions Functions Encryp Sign SR Gen Wrap Mechanism t & & Diges . & Deriv & Verif VR t Unwra e Decryp y 1 Key/ p t Key Pair CKM_SHA512_224 CKM_SHA512_224_HMAC_GENERA L CKM_SHA512_224_HMAC CKM_SHA512_224_KEY_DERIVATIO N CKM_SHA512_224_KEY_GEN
4493 2.25.1 Definitions 4494 This section defines the key type “CKK_SHA512_224_HMAC” for type CK_KEY_TYPE as used in the 4495 CKA_KEY_TYPE attribute of key objects. 4496 Mechanisms: 4497 CKM_SHA512_224 4498 CKM_SHA512_224_HMAC 4499 CKM_SHA512_224_HMAC_GENERAL 4500 CKM_SHA512_224_KEY_DERIVATION 4501 CKM_SHA512_224_KEY_GEN
4502 2.25.2 SHA-512/224 digest 4503 The SHA-512/224 mechanism, denoted CKM_SHA512_224, is a mechanism for message digesting, 4504 following the Secure Hash Algorithm defined in FIPS PUB 180-4, section 5.3.6. It is based on a 512-bit 4505 message digest with a distinct initial hash value and truncated to 224 bits. CKM_SHA512_224 is the 4506 same as CKM_SHA512_T with a parameter value of 224. 4507 It does not have a parameter. 4508 Constraints on the length of input and output data are summarized in the following table. For single-part 4509 digesting, the data and the digest may begin at the same location in memory. 4510 Table 120, SHA-512/224: Data Length Function Input length Digest length C_Digest any 28
4511 2.25.3 General-length SHA-512/224-HMAC 4512 The general-length SHA-512/224-HMAC mechanism, denoted CKM_SHA512_224_HMAC_GENERAL, 4513 is the same as the general-length SHA-1-HMAC mechanism in Section 2.20.3, except that it uses the 4514 HMAC construction based on the SHA-512/224 hash function and length of the output should be in the
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 126 of 278 4515 range 1-28. The keys it uses are generic secret keys and CKK_SHA512_224_HMAC. FIPS-198 4516 compliant tokens may require the key length to be at least 14 bytes; that is, half the size of the SHA- 4517 512/224 hash output. 4518 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4519 output. This length should be in the range 0-28 (the output size of SHA-512/224 is 28 bytes). FIPS-198 4520 compliant tokens may constrain the output length to be at least 4 or 14 (half the maximum length). 4521 Signatures (MACs) produced by this mechanism will be taken from the start of the full 28-byte HMAC 4522 output. 4523 Table 121, General-length SHA-384-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret, Any 1-28, depending on parameters CKK_SHA512_ 224_HMAC C_Verify generic secret, Any 1-28, depending on parameters CKK_SHA512_ 224_HMAC 4524
4525 2.25.4 SHA-512/224-HMAC 4526 The SHA-512-HMAC mechanism, denoted CKM_SHA512_224_HMAC, is a special case of the general- 4527 length SHA-512/224-HMAC mechanism. 4528 It has no parameter, and always produces an output of length 28.
4529 2.25.5 SHA-512/224 key derivation 4530 The SHA-512/224 key derivation, denoted CKM_SHA512_224_KEY_DERIVATION, is the same as the 4531 SHA-512 key derivation mechanism in section 2.25.5, except that it uses the SHA-512/224 hash function 4532 and the relevant length is 28 bytes.
4533 2.25.6 SHA-512/224 HMAC key generation 4534 The SHA-512/224-HMAC key generation mechanism, denoted CKM_SHA512_224_KEY_GEN, is a key 4535 generation mechanism for NIST’s SHA512/224-HMAC. 4536 It does not have a parameter. 4537 The mechanism generates SHA512/224-HMAC keys with a particular length in bytes, as specified in the 4538 CKA_VALUE_LEN attribute of the template for the key. 4539 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4540 key. Other attributes supported by the SHA512/224-HMAC key type (specifically, the flags indicating 4541 which functions the key supports) may be specified in the template for the key, or else are assigned 4542 default initial values. 4543 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4544 specify the supported range of CKM_SHA512_224_HMAC key sizes, in bytes.
4545 2.26 SHA-512/256 4546 Table 122, SHA-512/256 Mechanisms vs. Functions
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 127 of 278 Functions Encryp Sign SR Gen Wrap Mechanism t & & Diges . & Deriv & Verif VR t Unwra e Decryp y 1 Key/ p t Key Pair CKM_SHA512_256 CKM_SHA512_256_HMAC_GENERA L CKM_SHA512_256_HMAC CKM_SHA512_256_KEY_DERIVATIO N CKM_SHA512_256_KEY_GEN
4547 2.26.1 Definitions 4548 This section defines the key type “CKK_SHA512_256_HMAC” for type CK_KEY_TYPE as used in the 4549 CKA_KEY_TYPE attribute of key objects. 4550 Mechanisms: 4551 CKM_SHA512_256 4552 CKM_SHA512_256_HMAC 4553 CKM_SHA512_256_HMAC_GENERAL 4554 CKM_SHA512_256_KEY_DERIVATION 4555 CKM_SHA512_256_KEY_GEN
4556 2.26.2 SHA-512/256 digest 4557 The SHA-512/256 mechanism, denoted CKM_SHA512_256, is a mechanism for message digesting, 4558 following the Secure Hash Algorithm defined in FIPS PUB 180-4, section 5.3.6. It is based on a 512-bit 4559 message digest with a distinct initial hash value and truncated to 256 bits. CKM_SHA512_256 is the 4560 same as CKM_SHA512_T with a parameter value of 256. 4561 It does not have a parameter. 4562 Constraints on the length of input and output data are summarized in the following table. For single-part 4563 digesting, the data and the digest may begin at the same location in memory. 4564 Table 123, SHA-512/256: Data Length Function Input length Digest length C_Digest any 32
4565 2.26.3 General-length SHA-512/256-HMAC 4566 The general-length SHA-512/256-HMAC mechanism, denoted CKM_SHA512_256_HMAC_GENERAL, 4567 is the same as the general-length SHA-1-HMAC mechanism in Section 2.20.3, except that it uses the 4568 HMAC construction based on the SHA-512/256 hash function and length of the output should be in the 4569 range 1-32. The keys it uses are generic secret keys and CKK_SHA512_256_HMAC. FIPS-198 4570 compliant tokens may require the key length to be at least 16 bytes; that is, half the size of the SHA- 4571 512/256 hash output. 4572 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4573 output. This length should be in the range 1-32 (the output size of SHA-512/256 is 32 bytes). FIPS-198 4574 compliant tokens may constrain the output length to be at least 4 or 16 (half the maximum length).
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 128 of 278 4575 Signatures (MACs) produced by this mechanism will be taken from the start of the full 32-byte HMAC 4576 output. 4577 Table 124, General-length SHA-384-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret, Any 1-32, depending on parameters CKK_SHA512_ 256_HMAC C_Verify generic secret, Any 1-32, depending on parameters CKK_SHA512_ 256_HMAC 4578
4579 2.26.4 SHA-512/256-HMAC 4580 The SHA-512-HMAC mechanism, denoted CKM_SHA512_256_HMAC, is a special case of the general- 4581 length SHA-512/256-HMAC mechanism. 4582 It has no parameter, and always produces an output of length 32.
4583 2.26.5 SHA-512/256 key derivation 4584 The SHA-512/256 key derivation, denoted CKM_SHA512_256_KEY_DERIVATION, is the same as the 4585 SHA-512 key derivation mechanism in section 2.25.5, except that it uses the SHA-512/256 hash function 4586 and the relevant length is 32 bytes.
4587 2.26.6 SHA-512/256 HMAC key generation 4588 The SHA-512/256-HMAC key generation mechanism, denoted CKM_SHA512_256_KEY_GEN, is a key 4589 generation mechanism for NIST’s SHA512/256-HMAC. 4590 It does not have a parameter. 4591 The mechanism generates SHA512/256-HMAC keys with a particular length in bytes, as specified in the 4592 CKA_VALUE_LEN attribute of the template for the key. 4593 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4594 key. Other attributes supported by the SHA512/256-HMAC key type (specifically, the flags indicating 4595 which functions the key supports) may be specified in the template for the key, or else are assigned 4596 default initial values. 4597 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4598 specify the supported range of CKM_SHA512_256_HMAC key sizes, in bytes.
4599 2.27 SHA-512/t 4600 Table 125, SHA-512 / t Mechanisms vs. Functions Functions Encryp Sign SR Gen Wrap Mechanism t & & Diges . & Deriv & Verif VR t Unwra e Decryp y 1 Key/ p t Key Pair CKM_SHA512_T CKM_SHA512_T_HMAC_GENERAL CKM_SHA512_T_HMAC
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 129 of 278 Functions Encryp Sign SR Gen Wrap Mechanism t & & Diges . & Deriv & Verif VR t Unwra e Decryp y 1 Key/ p t Key Pair CKM_SHA512_T_KEY_DERIVATIO N CKM_SHA512_T_KEY_GEN
4601 2.27.1 Definitions 4602 This section defines the key type “CKK_SHA512_T_HMAC” for type CK_KEY_TYPE as used in the 4603 CKA_KEY_TYPE attribute of key objects. 4604 Mechanisms: 4605 CKM_SHA512_T 4606 CKM_SHA512_T_HMAC 4607 CKM_SHA512_T_HMAC_GENERAL 4608 CKM_SHA512_T_KEY_DERIVATION 4609 4610 CKK_SHA512_T_KEY_GEN
4611 2.27.2 SHA-512/t digest 4612 The SHA-512/t mechanism, denoted CKM_SHA512_T, is a mechanism for message digesting, following 4613 the Secure Hash Algorithm defined in FIPS PUB 180-4, section 5.3.6. It is based on a 512-bit message 4614 digest with a distinct initial hash value and truncated to t bits. 4615 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the value of t in bits. The length in 4616 bytes of the desired output should be in the range of 0-⌈ t/8⌉, where 0 < t < 512, and t <> 384. 4617 Constraints on the length of input and output data are summarized in the following table. For single-part 4618 digesting, the data and the digest may begin at the same location in memory. 4619 Table 126, SHA-512/256: Data Length Function Input length Digest length C_Digest any ⌈t/8⌉, where 0 < t < 512, and t <> 384
4620 2.27.3 General-length SHA-512/t-HMAC 4621 The general-length SHA-512/t-HMAC mechanism, denoted CKM_SHA512_T_HMAC_GENERAL, is the 4622 same as the general-length SHA-1-HMAC mechanism in Section 2.20.3, except that it uses the HMAC 4623 construction based on the SHA-512/t hash function and length of the output should be in the range 0 – ⌈ 4624 t/8⌉, where 0 < t < 512, and t <> 384.
4625 2.27.4 SHA-512/t-HMAC 4626 The SHA-512/t-HMAC mechanism, denoted CKM_SHA512_T_HMAC, is a special case of the general- 4627 length SHA-512/t-HMAC mechanism.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 130 of 278 4628 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the value of t in bits. The length in 4629 bytes of the desired output should be in the range of 0-⌈t/8⌉, where 0 < t < 512, and t <> 384.
4630 2.27.5 SHA-512/t key derivation 4631 The SHA-512/t key derivation, denoted CKM_SHA512_T_KEY_DERIVATION, is the same as the SHA- 4632 512 key derivation mechanism in section 2.25.5, except that it uses the SHA-512/t hash function and the 4633 relevant length is ⌈t/8⌉ bytes, where 0 < t < 512, and t <> 384.
4634 2.27.6 SHA-512/t HMAC key generation 4635 The SHA-512/t-HMAC key generation mechanism, denoted CKM_SHA512_T_KEY_GEN, is a key 4636 generation mechanism for NIST’s SHA512/t-HMAC. 4637 It does not have a parameter. 4638 The mechanism generates SHA512/t-HMAC keys with a particular length in bytes, as specified in the 4639 CKA_VALUE_LEN attribute of the template for the key. 4640 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4641 key. Other attributes supported by the SHA512/t-HMAC key type (specifically, the flags indicating which 4642 functions the key supports) may be specified in the template for the key, or else are assigned default 4643 initial values. 4644 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4645 specify the supported range of CKM_SHA512_T_HMAC key sizes, in bytes. 4646
4647 2.28 SHA3-224 4648 Table 127, SHA-224 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Diges & Derive Decrypt Verif VR1 t Key/ Unwrap y Key Pair CKM_SHA3_224 CKM_SHA3_224_HMAC CKM_SHA3_224_HMAC_GENERAL CKM_SHA3_224_KEY_DERIVATION CKM_SHA3_224_KEY_GEN
4649 2.28.1 Definitions 4650 Mechanisms: 4651 CKM_SHA3_224 4652 CKM_SHA3_224_HMAC 4653 CKM_SHA3_224_HMAC_GENERAL 4654 CKM_SHA3_224_KEY_DERIVATION 4655 CKM_SHA3_224_KEY_GEN 4656 4657 CKK_SHA3_224_HMAC
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 131 of 278 4658 2.28.2 SHA3-224 digest 4659 The SHA3-224 mechanism, denoted CKM_SHA3_224, is a mechanism for message digesting, following 4660 the Secure Hash 3 Algorithm with a 224-bit message digest defined in FIPS Pub 202. 4661 It does not have a parameter. 4662 Constraints on the length of input and output data are summarized in the following table. For single-part 4663 digesting, the data and the digest may begin at the same location in memory. 4664 Table 128, SHA3-224: Data Length Function Input length Digest length C_Digest any 28
4665 2.28.3 General-length SHA3-224-HMAC 4666 The general-length SHA3-224-HMAC mechanism, denoted CKM_SHA3_224_HMAC_GENERAL, is the 4667 same as the general-length SHA-1-HMAC mechanism in section 2.20.4 except that it uses the HMAC 4668 construction based on the SHA3-224 hash function and length of the output should be in the range 1-28. 4669 The keys it uses are generic secret keys and CKK_SHA3_224_HMAC. FIPS-198 compliant tokens may 4670 require the key length to be at least 14 bytes; that is, half the size of the SHA3-224 hash output. 4671 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4672 output. This length should be in the range 1-28 (the output size of SHA3-224 is 28 bytes). FIPS-198 4673 compliant tokens may constrain the output length to be at least 4 or 14 (half the maximum length). 4674 Signatures (MACs) produced by this mechanism shall be taken from the start of the full 28-byte HMAC 4675 output. 4676 Table 129, General-length SHA3-224-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret or Any 1-28, depending on parameters CKK_SHA3_224_HMAC C_Verify generic secret or Any 1-28, depending on parameters CKK_SHA3_224_HMAC
4677 2.28.4 SHA3-224-HMAC 4678 The SHA3-224-HMAC mechanism, denoted CKM_SHA3_224_HMAC, is a special case of the general- 4679 length SHA3-224-HMAC mechanism. 4680 It has no parameter, and always produces an output of length 28.
4681 2.28.5 SHA3-224 key derivation 4682 SHA-224 key derivation, denoted CKM_SHA3_224_KEY_DERIVATION, is the same as the SHA-1 key 4683 derivation mechanism in Section 2.20.5 except that it uses the SHA3-224 hash function and the relevant 4684 length is 28 bytes.
4685 2.28.6 SHA3-224 HMAC key generation 4686 The SHA3-224-HMAC key generation mechanism, denoted CKM_SHA3_224_KEY_GEN, is a key 4687 generation mechanism for NIST’s SHA3-224-HMAC. 4688 It does not have a parameter. 4689 The mechanism generates SHA3-224-HMAC keys with a particular length in bytes, as specified in the 4690 CKA_VALUE_LEN attribute of the template for the key. 4691 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4692 key. Other attributes supported by the SHA3-224-HMAC key type (specifically, the flags indicating which
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 132 of 278 4693 functions the key supports) may be specified in the template for the key, or else are assigned default 4694 initial values. 4695 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4696 specify the supported range of CKM_SHA3_224_HMAC key sizes, in bytes.
4697 2.29 SHA3-256 4698 Table 130, SHA3-256 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Diges & Derive Decrypt Verif VR1 t Key/ Unwrap y Key Pair CKM_SHA3_256 CKM_SHA3_256_HMAC_GENERAL CKM_SHA3_256_HMAC CKM_SHA3_256_KEY_DERIVATION CKM_SHA3_256_KEY_GEN
4699 2.29.1 Definitions 4700 Mechanisms: 4701 CKM_SHA3_256 4702 CKM_SHA3_256_HMAC 4703 CKM_SHA3_256_HMAC_GENERAL 4704 CKM_SHA3_256_KEY_DERIVATION 4705 CKM_SHA3_256_KEY_GEN 4706 4707 CKK_SHA3_256_HMAC
4708 2.29.2 SHA3-256 digest 4709 The SHA3-256 mechanism, denoted CKM_SHA3_256, is a mechanism for message digesting, following 4710 the Secure Hash 3 Algorithm with a 256-bit message digest defined in FIPS PUB 202. 4711 It does not have a parameter. 4712 Constraints on the length of input and output data are summarized in the following table. For single-part 4713 digesting, the data and the digest may begin at the same location in memory. 4714 Table 131, SHA3-256: Data Length Function Input length Digest length C_Digest any 32
4715 2.29.3 General-length SHA3-256-HMAC 4716 The general-length SHA3-256-HMAC mechanism, denoted CKM_SHA3_256_HMAC_GENERAL, is the 4717 same as the general-length SHA-1-HMAC mechanism in Section 2.20.4, except that it uses the HMAC 4718 construction based on the SHA3-256 hash function and length of the output should be in the range 1-32. 4719 The keys it uses are generic secret keys and CKK_SHA3_256_HMAC. FIPS-198 compliant tokens may 4720 require the key length to be at least 16 bytes; that is, half the size of the SHA3-256 hash output.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 133 of 278 4721 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4722 output. This length should be in the range 1-32 (the output size of SHA3-256 is 32 bytes). FIPS-198 4723 compliant tokens may constrain the output length to be at least 4 or 16 (half the maximum length). 4724 Signatures (MACs) produced by this mechanism shall be taken from the start of the full 32-byte HMAC 4725 output. 4726 Table 132, General-length SHA3-256-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret or Any 1-32, depending on parameters CKK_SHA3_256_HMAC C_Verify generic secret or Any 1-32, depending on parameters CKK_SHA3_256_HMAC
4727 2.29.4 SHA3-256-HMAC 4728 The SHA-256-HMAC mechanism, denoted CKM_SHA3_256_HMAC, is a special case of the general- 4729 length SHA-256-HMAC mechanism in Section 2.22.3. 4730 It has no parameter, and always produces an output of length 32.
4731 2.29.5 SHA3-256 key derivation 4732 SHA-256 key derivation, denoted CKM_SHA3_256_KEY_DERIVATION, is the same as the SHA-1 key 4733 derivation mechanism in Section 2.20.5, except that it uses the SHA3-256 hash function and the relevant 4734 length is 32 bytes.
4735 2.29.6 SHA3-256 HMAC key generation 4736 The SHA3-256-HMAC key generation mechanism, denoted CKM_SHA3_256_KEY_GEN, is a key 4737 generation mechanism for NIST’s SHA3-256-HMAC. 4738 It does not have a parameter. 4739 The mechanism generates SHA3-256-HMAC keys with a particular length in bytes, as specified in the 4740 CKA_VALUE_LEN attribute of the template for the key. 4741 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4742 key. Other attributes supported by the SHA3-256-HMAC key type (specifically, the flags indicating which 4743 functions the key supports) may be specified in the template for the key, or else are assigned default 4744 initial values. 4745 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4746 specify the supported range of CKM_SHA3_256_HMAC key sizes, in bytes. 4747
4748 2.30 SHA3-384 4749 Table 133, SHA3-384 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Diges & Derive Decrypt Verif VR1 t Key/ Unwrap y Key Pair CKM_SHA3_384 CKM_SHA3_384_HMAC_GENERAL CKM_SHA3_384_HMAC
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 134 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Diges & Derive Decrypt Verif VR1 t Key/ Unwrap y Key Pair CKM_SHA3_384_KEY_DERIVATION CKM_SHA3_384_KEY_GEN
4750 2.30.1 Definitions 4751 CKM_SHA3_384 4752 CKM_SHA3_384_HMAC 4753 CKM_SHA3_384_HMAC_GENERAL 4754 CKM_SHA3_384_KEY_DERIVATION 4755 CKM_SHA3_384_KEY_GEN 4756 4757 CKK_SHA3_384_HMAC
4758 2.30.2 SHA3-384 digest 4759 The SHA3-384 mechanism, denoted CKM_SHA3_384, is a mechanism for message digesting, following 4760 the Secure Hash 3 Algorithm with a 384-bit message digest defined in FIPS PUB 202. 4761 It does not have a parameter. 4762 Constraints on the length of input and output data are summarized in the following table. For single-part 4763 digesting, the data and the digest may begin at the same location in memory. 4764 Table 134, SHA3-384: Data Length Function Input length Digest length C_Digest any 48
4765 2.30.3 General-length SHA3-384-HMAC 4766 The general-length SHA3-384-HMAC mechanism, denoted CKM_SHA3_384_HMAC_GENERAL, is the 4767 same as the general-length SHA-1-HMAC mechanism in Section 2.20.4, except that it uses the HMAC 4768 construction based on the SHA-384 hash function and length of the output should be in the range 1- 4769 48.The keys it uses are generic secret keys and CKK_SHA3_384_HMAC. FIPS-198 compliant tokens 4770 may require the key length to be at least 24 bytes; that is, half the size of the SHA3-384 hash output. 4771 4772 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4773 output. This length should be in the range 1-48 (the output size of SHA3-384 is 48 bytes). FIPS-198 4774 compliant tokens may constrain the output length to be at least 4 or 24 (half the maximum length). 4775 Signatures (MACs) produced by this mechanism shall be taken from the start of the full 48-byte HMAC 4776 output. 4777 Table 135, General-length SHA3-384-HMAC: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 135 of 278 Function Key type Data length Signature length C_Sign generic secret or Any 1-48, depending on parameters CKK_SHA3_384_HMAC C_Verify generic secret or Any 1-48, depending on parameters CKK_SHA3_384_HMAC 4778
4779 2.30.4 SHA3-384-HMAC 4780 The SHA3-384-HMAC mechanism, denoted CKM_SHA3_384_HMAC, is a special case of the general- 4781 length SHA3-384-HMAC mechanism. 4782 It has no parameter, and always produces an output of length 48.
4783 2.30.5 SHA3-384 key derivation 4784 SHA3-384 key derivation, denoted CKM_SHA3_384_KEY_DERIVATION, is the same as the SHA-1 key 4785 derivation mechanism in Section 2.20.5, except that it uses the SHA-384 hash function and the relevant 4786 length is 48 bytes.
4787 2.30.6 SHA3-384 HMAC key generation 4788 The SHA3-384-HMAC key generation mechanism, denoted CKM_SHA3_384_KEY_GEN, is a key 4789 generation mechanism for NIST’s SHA3-384-HMAC. 4790 It does not have a parameter. 4791 The mechanism generates SHA3-384-HMAC keys with a particular length in bytes, as specified in the 4792 CKA_VALUE_LEN attribute of the template for the key. 4793 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4794 key. Other attributes supported by the SHA3-384-HMAC key type (specifically, the flags indicating which 4795 functions the key supports) may be specified in the template for the key, or else are assigned default 4796 initial values. 4797 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4798 specify the supported range of CKM_SHA3_384_HMAC key sizes, in bytes.
4799 2.31 SHA3-512 4800 Table 136, SHA-512 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR Key/ Unwrap 1 Key Pair CKM_SHA3_512 CKM_SHA3_512_HMAC_GENERAL CKM_SHA3_512_HMAC CKM_SHA3_512_KEY_DERIVATION CKM_SHA3_512_KEY_GEN
4801 2.31.1 Definitions 4802 CKM_SHA3_512
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 136 of 278 4803 CKM_SHA3_512_HMAC 4804 CKM_SHA3_512_HMAC_GENERAL 4805 CKM_SHA3_512_KEY_DERIVATION 4806 CKM_SHA3_512_KEY_GEN 4807 4808 CKK_SHA3_512_HMAC
4809 2.31.2 SHA3-512 digest 4810 The SHA3-512 mechanism, denoted CKM_SHA3_512, is a mechanism for message digesting, following 4811 the Secure Hash 3 Algorithm with a 512-bit message digest defined in FIPS PUB 202. 4812 It does not have a parameter. 4813 Constraints on the length of input and output data are summarized in the following table. For single-part 4814 digesting, the data and the digest may begin at the same location in memory. 4815 Table 137, SHA3-512: Data Length Function Input length Digest length C_Digest any 64
4816 2.31.3 General-length SHA3-512-HMAC 4817 The general-length SHA3-512-HMAC mechanism, denoted CKM_SHA3_512_HMAC_GENERAL, is the 4818 same as the general-length SHA-1-HMAC mechanism in Section 2.20.4, except that it uses the HMAC 4819 construction based on the SHA3-512 hash function and length of the output should be in the range 1- 4820 64.The keys it uses are generic secret keys and CKK_SHA3_512_HMAC. FIPS-198 compliant tokens 4821 may require the key length to be at least 32 bytes; that is, half the size of the SHA3-512 hash output. 4822 4823 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4824 output. This length should be in the range 1-64 (the output size of SHA3-512 is 64 bytes). FIPS-198 4825 compliant tokens may constrain the output length to be at least 4 or 32 (half the maximum length). 4826 Signatures (MACs) produced by this mechanism shall be taken from the start of the full 64-byte HMAC 4827 output. 4828 Table 138, General-length SHA3-512-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret or Any 1-64, depending on parameters CKK_SHA3_512-HMAC C_Verify generic secret or Any 1-64, depending on parameters CKK_SHA3_512_HMAC 4829
4830 2.31.4 SHA3-512-HMAC 4831 The SHA3-512-HMAC mechanism, denoted CKM_SHA3_512_HMAC, is a special case of the general- 4832 length SHA3-512-HMAC mechanism. 4833 It has no parameter, and always produces an output of length 64.
4834 2.31.5 SHA3-512 key derivation 4835 SHA3-512 key derivation, denoted CKM_SHA3_512_KEY_DERIVATION, is the same as the SHA-1 key 4836 derivation mechanism in Section 2.20.5, except that it uses the SHA-512 hash function and the relevant 4837 length is 64 bytes.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 137 of 278 4838 2.31.6 SHA3-512 HMAC key generation 4839 The SHA3-512-HMAC key generation mechanism, denoted CKM_SHA3_512_KEY_GEN, is a key 4840 generation mechanism for NIST’s SHA3-512-HMAC. 4841 It does not have a parameter. 4842 The mechanism generates SHA3-512-HMAC keys with a particular length in bytes, as specified in the 4843 CKA_VALUE_LEN attribute of the template for the key. 4844 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4845 key. Other attributes supported by the SHA3-512-HMAC key type (specifically, the flags indicating which 4846 functions the key supports) may be specified in the template for the key, or else are assigned default 4847 initial values. 4848 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4849 specify the supported range of CKM_SHA3_512_HMAC key sizes, in bytes.
4850 2.32 SHAKE 4851 Table 139, SHA-512 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_SHAKE_128_KEY_DERIVATION CKM_SHAKE_256_KEY_DERIVATION
4852 2.32.1 Definitions 4853 CKM_SHAKE_128_KEY_DERIVATION 4854 CKM_SHAKE_256_KEY_DERIVATION
4855 2.32.2 SHAKE Key Derivation 4856 SHAKE-128 and SHAKE-256 key derivation, denoted CKM_SHAKE_128_KEY_DERIVATION and 4857 CKM_SHAKE_256_KEY_DERIVATION, implements the SHAKE expansion function defined in FIPS 202 4858 on the input key. 4859 If no length or key type is provided in the template a CKR_INVALID_TEMPLATE error is generated. 4860 If no key type is provided in the template, but a length is, then the key produced by this mechanism 4861 shall be a generic secret key of the specified length. 4862 If no length was provided in the template, but a key type is, then that key type must have a well- 4863 defined length. If it does, then the key produced by this mechanism shall be of the type specified in 4864 the template. If it doesn’t, an error shall be returned. 4865 If both a key type and a length are provided in the template, the length must be compatible with that 4866 key type. The key produced by this mechanism shall be of the specified type and length. 4867 If a DES, DES2, or CDMF key is derived with this mechanism, the parity bits of the key shall be set 4868 properly. 4869 This mechanism has the following rules about key sensitivity and extractability: 4870 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 4871 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 4872 default value. 4873 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 4874 shall as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 138 of 278 4875 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 4876 CKA_SENSITIVE attribute. 4877 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then 4878 the derived key shall, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 4879 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 4880 value from its CKA_EXTRACTABLE attribute. 4881
4882 2.33 Blake2b-160 4883 Table 140, Blake2b-160 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Diges & Derive Decrypt Verif VR1 t Key/ Unwrap y Key Pair CKM_BLAKE2B_160 CKM_BLAKE2B_160_HMAC CKM_BLAKE2B_160_HMAC_GENE RAL CKM_BLAKE2B_160_KEY_DERIVE CKM_BLAKE2B_160_KEY_GEN
4884 2.33.1 Definitions 4885 Mechanisms: 4886 CKM_BLAKE2B_160 4887 CKM_BLAKE2B_160_HMAC 4888 CKM_BLAKE2B_160_HMAC_GENERAL 4889 CKM_BLAKE2B_160_KEY_DERIVE 4890 CKM_BLAKE2B_160_KEY_GEN 4891 CKK_BLAKE2B_160_HMAC
4892 2.33.2 BLAKE2B-160 digest 4893 The BLAKE2B-160 mechanism, denoted CKM_BLAKE2B_160, is a mechanism for message digesting, 4894 following the Blake2b Algorithm with a 160-bit message digest without a key as defined in RFC 7693. 4895 It does not have a parameter. 4896 Constraints on the length of input and output data are summarized in the following table. For single-part 4897 digesting, the data and the digest may begin at the same location in memory. 4898 Table 141, BLAKE2B-160: Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 139 of 278 Function Input length Digest length C_Digest any 20
4899 2.33.3 General-length BLAKE2B-160-HMAC 4900 The general-length BLAKE2B-160-HMAC mechanism, denoted 4901 CKM_BLAKE2B_160_HMAC_GENERAL, is the keyed variant of BLAKE2b-160 and length of the output 4902 should be in the range 1-20. The keys it uses are generic secret keys and CKK_BLAKE2B_160_HMAC. 4903 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4904 output. This length should be in the range 1-20 (the output size of BLAKE2B-160 is 20 bytes). Signatures 4905 (MACs) produced by this mechanism shall be taken from the start of the full 20-byte HMAC output. 4906 Table 142, General-length BLAKE2B-160-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret or Any 1-20, depending on parameters CKK_BLAKE2B_160_H MAC C_Verify generic secret or Any 1-20, depending on parameters CKK_BLAKE2B_160_H MAC
4907 2.33.4 BLAKE2B-160-HMAC 4908 The BLAKE2B-160-HMAC mechanism, denoted CKM_BLAKE2B_160_HMAC, is a special case of the 4909 general-length BLAKE2B-160-HMAC mechanism. 4910 It has no parameter, and always produces an output of length 20.
4911 2.33.5 BLAKE2B-160 key derivation 4912 BLAKE2B-160 key derivation, denoted CKM_BLAKE2B_160_KEY_DERIVE, is the same as the SHA-1 4913 key derivation mechanism in Section 2.20.5 except that it uses the BLAKE2B-160 hash function and the 4914 relevant length is 20 bytes.
4915 2.33.6 BLAKE2B-160 HMAC key generation 4916 The BLAKE2B-160-HMAC key generation mechanism, denoted CKM_BLAKE2B_160_KEY_GEN, is a 4917 key generation mechanism for BLAKE2B-160-HMAC. 4918 It does not have a parameter. 4919 The mechanism generates BLAKE2B-160-HMAC keys with a particular length in bytes, as specified in the 4920 CKA_VALUE_LEN attribute of the template for the key. 4921 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4922 key. Other attributes supported by the BLAKE2B-160-HMAC key type (specifically, the flags indicating 4923 which functions the key supports) may be specified in the template for the key, or else are assigned 4924 default initial values. 4925 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4926 specify the supported range of CKM_BLAKE2B_160_HMAC key sizes, in bytes.
4927 2.34 BLAKE2B-256 4928 Table 143, BLAKE2B-256 Mechanisms vs. Functions
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 140 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Diges & Derive Decrypt Verif VR1 t Key/ Unwrap y Key Pair CKM_BLAKE2B_256 CKM_BLAKE2B_256_HMAC_GENER AL CKM_BLAKE2B_256_HMAC CKM_BLAKE2B_256_KEY_DERIVE CKM_BLAKE2B_256_KEY_GEN
4929 2.34.1 Definitions 4930 Mechanisms: 4931 CKM_BLAKE2B_256 4932 CKM_BLAKE2B_256_HMAC 4933 CKM_BLAKE2B_256_HMAC_GENERAL 4934 CKM_BLAKE2B_256_KEY_DERIVE 4935 CKM_BLAKE2B_256_KEY_GEN 4936 CKK_BLAKE2B_256_HMAC
4937 2.34.2 BLAKE2B-256 digest 4938 The BLAKE2B-256 mechanism, denoted CKM_BLAKE2B_256, is a mechanism for message digesting, 4939 following the Blake2b Algorithm with a 256-bit message digest without a key as defined in RFC 7693. 4940 It does not have a parameter. 4941 Constraints on the length of input and output data are summarized in the following table. For single-part 4942 digesting, the data and the digest may begin at the same location in memory. 4943 Table 144, BLAKE2B-256: Data Length Function Input length Digest length C_Digest any 32
4944 2.34.3 General-length BLAKE2B-256-HMAC 4945 The general-length BLAKE2B-256-HMAC mechanism, denoted 4946 CKM_BLAKE2B_256_HMAC_GENERAL, is the keyed variant of Blake2b-256 and length of the output 4947 should be in the range 1-32. The keys it uses are generic secret keys and CKK_BLAKE2B_256_HMAC. 4948 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4949 output. This length should be in the range 1-32 (the output size of BLAKE2B-256 is 32 bytes). Signatures 4950 (MACs) produced by this mechanism shall be taken from the start of the full 32-byte HMAC output. 4951 Table 145, General-length BLAKE2B-256-HMAC: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 141 of 278 Function Key type Data length Signature length C_Sign generic secret or Any 1-32, depending on parameters CKK_BLAKE2B_256_HM AC C_Verify generic secret or Any 1-32, depending on parameters CKK_BLAKE2B_256_HM AC
4952 2.34.4 BLAKE2B-256-HMAC 4953 The BLAKE2B-256-HMAC mechanism, denoted CKM_BLAKE2B_256_HMAC, is a special case of the 4954 general-length BLAKE2B-256-HMAC mechanism in Section 2.22.3. 4955 It has no parameter, and always produces an output of length 32.
4956 2.34.5 BLAKE2B-256 key derivation 4957 BLAKE2B-256 key derivation, denoted CKM_BLAKE2B_256_KEY_DERIVE, is the same as the SHA-1 4958 key derivation mechanism in Section 2.20.5, except that it uses the BLAKE2B-256 hash function and the 4959 relevant length is 32 bytes.
4960 2.34.6 BLAKE2B-256 HMAC key generation 4961 The BLAKE2B-256-HMAC key generation mechanism, denoted CKM_BLAKE2B_256_KEY_GEN, is a 4962 key generation mechanism for7 BLAKE2B-256-HMAC. 4963 It does not have a parameter. 4964 The mechanism generates BLAKE2B-256-HMAC keys with a particular length in bytes, as specified in the 4965 CKA_VALUE_LEN attribute of the template for the key. 4966 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 4967 key. Other attributes supported by the BLAKE2B-256-HMAC key type (specifically, the flags indicating 4968 which functions the key supports) may be specified in the template for the key, or else are assigned 4969 default initial values. 4970 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 4971 specify the supported range of CKM_BLAKE2B_256_HMAC key sizes, in bytes.
4972 2.35 BLAKE2B-384 4973 Table 146, BLAKE2B-384 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Diges & Derive Decrypt Verif VR1 t Key/ Unwrap y Key Pair CKM_BLAKE2B_384 CKM_BLAKE2B_384_HMAC_GENE RAL CKM_BLAKE2B_384_HMAC CKM_BLAKE2B_384_KEY_DERIVE CKM_BLAKE2B_384_KEY_GEN
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 142 of 278 4974 2.35.1 Definitions 4975 CKM_BLAKE2B_384 4976 CKM_BLAKE2B_384_HMAC 4977 CKM_BLAKE2B_384_HMAC_GENERAL 4978 CKM_BLAKE2B_384_KEY_DERIVE 4979 CKM_BLAKE2B_384_KEY_GEN 4980 CKK_BLAKE2B_384_HMAC
4981 2.35.2 BLAKE2B-384 digest 4982 The BLAKE2B-384 mechanism, denoted CKM_BLAKE2B_384, is a mechanism for message digesting, 4983 following the Blake2b Algorithm with a 384-bit message digest without a key as defined in RFC 7693. 4984 It does not have a parameter. 4985 Constraints on the length of input and output data are summarized in the following table. For single-part 4986 digesting, the data and the digest may begin at the same location in memory. 4987 Table 147, BLAKE2B-384: Data Length Function Input length Digest length C_Digest any 48
4988 2.35.3 General-length BLAKE2B-384-HMAC 4989 The general-length BLAKE2B-384-HMAC mechanism, denoted 4990 CKM_BLAKE2B_384_HMAC_GENERAL, is the keyed variant of the Blake2b-384 hash function and 4991 length of the output should be in the range 1-48.The keys it uses are generic secret keys and 4992 CKK_BLAKE2B_384_HMAC. 4993 4994 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 4995 output. This length should be in the range 1-48 (the output size of BLAKE2B-384 is 48 bytes). Signatures 4996 (MACs) produced by this mechanism shall be taken from the start of the full 48-byte HMAC output. 4997 Table 148, General-length BLAKE2B-384-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret or Any 1-48, depending on parameters CKK_BLAKE2B_384_H MAC C_Verify generic secret or Any 1-48, depending on parameters CKK_BLAKE2B_384_H MAC 4998
4999 2.35.4 BLAKE2B-384-HMAC 5000 The BLAKE2B-384-HMAC mechanism, denoted CKM_BLAKE2B_384_HMAC, is a special case of the 5001 general-length BLAKE2B-384-HMAC mechanism. 5002 It has no parameter, and always produces an output of length 48.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 143 of 278 5003 2.35.5 BLAKE2B-384 key derivation 5004 BLAKE2B-384 key derivation, denoted CKM_BLAKE2B_384_KEY_DERIVE, is the same as the SHA-1 5005 key derivation mechanism in Section 2.20.5, except that it uses the SHA-384 hash function and the 5006 relevant length is 48 bytes.
5007 2.35.6 BLAKE2B-384 HMAC key generation 5008 The BLAKE2B-384-HMAC key generation mechanism, denoted CKM_BLAKE2B_384_KEY_GEN, is a 5009 key generation mechanism for NIST’s BLAKE2B-384-HMAC. 5010 It does not have a parameter. 5011 The mechanism generates BLAKE2B-384-HMAC keys with a particular length in bytes, as specified in the 5012 CKA_VALUE_LEN attribute of the template for the key. 5013 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 5014 key. Other attributes supported by the BLAKE2B-384-HMAC key type (specifically, the flags indicating 5015 which functions the key supports) may be specified in the template for the key, or else are assigned 5016 default initial values. 5017 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5018 specify the supported range of CKM_BLAKE2B_384_HMAC key sizes, in bytes.
5019 2.36 BLAKE2B-512 5020 Table 149, SHA-512 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR Key/ Unwrap 1 Key Pair CKM_BLAKE2B_512 CKM_BLAKE2B_512_HMAC_GENE RAL CKM_BLAKE2B_512_HMAC CKM_BLAKE2B_512_KEY_DERIVE
CKM_BLAKE2B_512_KEY_GEN
5021 2.36.1 Definitions 5022 CKM_BLAKE2B_512 5023 CKM_BLAKE2B_512_HMAC 5024 CKM_BLAKE2B_512_HMAC_GENERAL 5025 CKM_BLAKE2B_512_KEY_DERIVE 5026 CKM_BLAKE2B_512_KEY_GEN 5027 CKK_BLAKE2B_512_HMAC
5028 2.36.2 BLAKE2B-512 digest 5029 The BLAKE2B-512 mechanism, denoted CKM_BLAKE2B_512, is a mechanism for message digesting, 5030 following the Blake2b Algorithm with a 512-bit message digest defined in RFC 7693. 5031 It does not have a parameter.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 144 of 278 5032 Constraints on the length of input and output data are summarized in the following table. For single-part 5033 digesting, the data and the digest may begin at the same location in memory. 5034 Table 150, BLAKE2B-512: Data Length Function Input length Digest length C_Digest any 64
5035 2.36.3 General-length BLAKE2B-512-HMAC 5036 The general-length BLAKE2B-512-HMAC mechanism, denoted 5037 CKM_BLAKE2B_512_HMAC_GENERAL, is the keyed variant of the BLAKE2B-512 hash function and 5038 length of the output should be in the range 1-64.The keys it uses are generic secret keys and 5039 CKK_BLAKE2B_512_HMAC. 5040 5041 It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 5042 output. This length should be in the range 1-64 (the output size of BLAKE2B-512 is 64 bytes). Signatures 5043 (MACs) produced by this mechanism shall be taken from the start of the full 64-byte HMAC output. 5044 Table 151, General-length BLAKE2B-512-HMAC: Key And Data Length Function Key type Data length Signature length C_Sign generic secret or Any 1-64, depending on parameters CKK_BLAKE2B_512- HMAC C_Verify generic secret or Any 1-64, depending on parameters CKK_BLAKE2B_512_HM AC 5045
5046 2.36.4 BLAKE2B-512-HMAC 5047 The BLAKE2B-512-HMAC mechanism, denoted CKM_BLAKE2B_512_HMAC, is a special case of the 5048 general-length BLAKE2B-512-HMAC mechanism. 5049 It has no parameter, and always produces an output of length 64.
5050 2.36.5 BLAKE2B-512 key derivation 5051 BLAKE2B-512 key derivation, denoted CKM_BLAKE2B_512_KEY_DERIVE, is the same as the SHA-1 5052 key derivation mechanism in Section2.20.5, except that it uses the Blake2b-512 hash function and the 5053 relevant length is 64 bytes.
5054 2.36.6 BLAKE2B-512 HMAC key generation 5055 The BLAKE2B-512-HMAC key generation mechanism, denoted CKM_BLAKE2B_512_KEY_GEN, is a 5056 key generation mechanism for NIST’s BLAKE2B-512-HMAC. 5057 It does not have a parameter. 5058 The mechanism generates BLAKE2B-512-HMAC keys with a particular length in bytes, as specified in the 5059 CKA_VALUE_LEN attribute of the template for the key. 5060 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 5061 key. Other attributes supported by the BLAKE2B-512-HMAC key type (specifically, the flags indicating 5062 which functions the key supports) may be specified in the template for the key, or else are assigned 5063 default initial values. 5064 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5065 specify the supported range of CKM_BLAKE2B_512_HMAC key sizes, in bytes.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 145 of 278 5066
5067 2.37 PKCS #5 and PKCS #5-style password-based encryption (PBE) 5068 The mechanisms in this section are for generating keys and IVs for performing password-based 5069 encryption. The method used to generate keys and IVs is specified in PKCS #5. 5070 Table 152, PKCS 5 Mechanisms vs. Functions Functions Encryp Sign SR Gen Wrap Mechanism t & & Diges . & Deriv & Verif VR t Unwra e Decryp y 1 Key/ p t Key Pair CKM_PBE_SHA1_DES3_EDE_CBC CKM_PBE_SHA1_DES2_EDE_CBC CKM_PBA_SHA1_WITH_SHA1_HMA C CKM_PKCS5_PBKD2
5071 2.37.1 Definitions 5072 Mechanisms: 5073 CKM_PBE_SHA1_DES3_EDE_CBC 5074 CKM_PBE_SHA1_DES2_EDE_CBC 5075 CKM_PKCS5_PBKD2 5076 CKM_PBA_SHA1_WITH_SHA1_HMAC
5077 2.37.2 Password-based encryption/authentication mechanism parameters
5078 CK_PBE_PARAMS; CK_PBE_PARAMS_PTR
5079 CK_PBE_PARAMS is a structure which provides all of the necessary information required by the 5080 CKM_PBE mechanisms (see PKCS #5 and PKCS #12 for information on the PBE generation 5081 mechanisms) and the CKM_PBA_SHA1_WITH_SHA1_HMAC mechanism. It is defined as follows: 5082 typedef struct CK_PBE_PARAMS { 5083 CK_BYTE_PTR pInitVector; 5084 CK_UTF8CHAR_PTR pPassword; 5085 CK_ULONG ulPasswordLen; 5086 CK_BYTE_PTR pSalt; 5087 CK_ULONG ulSaltLen; 5088 CK_ULONG ulIteration; 5089 } CK_PBE_PARAMS; 5090 5091 The fields of the structure have the following meanings: 5092 pInitVector pointer to the location that receives the 8-byte initialization vector 5093 (IV), if an IV is required;
5094 pPassword points to the password to be used in the PBE key generation;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 146 of 278 5095 ulPasswordLen length in bytes of the password information;
5096 pSalt points to the salt to be used in the PBE key generation;
5097 ulSaltLen length in bytes of the salt information;
5098 ulIteration number of iterations required for the generation.
5099 CK_PBE_PARAMS_PTR is a pointer to a CK_PBE_PARAMS.
5100 2.37.3 PKCS #5 PBKDF2 key generation mechanism parameters
5101 CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE; 5102 CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE_PTR
5103 CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE is used to indicate the Pseudo-Random 5104 Function (PRF) used to generate key bits using PKCS #5 PBKDF2. It is defined as follows: 5105 typedef CK_ULONG CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE; 5106 5107 The following PRFs are defined in PKCS #5 v2.1. The following table lists the defined functions. 5108 Table 153, PKCS #5 PBKDF2 Key Generation: Pseudo-random functions PRF Identifier Value Parameter Type CKP_PKCS5_PBKD2_HMAC_SHA1 0x00000001UL No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. CKP_PKCS5_PBKD2_HMAC_GOSTR3411 0x00000002UL This PRF uses GOST R34.11-94 hash to produce secret key value. pPrfData should point to DER- encoded OID, indicating GOSTR34.11-94 parameters. ulPrfDataLen holds encoded OID length in bytes. If pPrfData is set to NULL_PTR, then id- GostR3411-94- CryptoProParamSet parameters will be used (RFC 4357, 11.2), and ulPrfDataLen must be 0. CKP_PKCS5_PBKD2_HMAC_SHA224 0x00000003UL No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. CKP_PKCS5_PBKD2_HMAC_SHA256 0x00000004UL No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. CKP_PKCS5_PBKD2_HMAC_SHA384 0x00000005UL No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. CKP_PKCS5_PBKD2_HMAC_SHA512 0x00000006UL No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 147 of 278 CKP_PKCS5_PBKD2_HMAC_SHA512_224 0x00000007UL No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. CKP_PKCS5_PBKD2_HMAC_SHA512_256 0x00000008UL No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. 5109 CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE_PTR is a pointer to a 5110 CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE. 5111
5112 CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE; 5113 CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE_PTR
5114 CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE is used to indicate the source of the salt value when 5115 deriving a key using PKCS #5 PBKDF2. It is defined as follows: 5116 typedef CK_ULONG CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE; 5117 5118 The following salt value sources are defined in PKCS #5 v2.1. The following table lists the defined 5119 sources along with the corresponding data type for the pSaltSourceData field in the 5120 CK_PKCS5_PBKD2_PARAM structure defined below. 5121 Table 154, PKCS #5 PBKDF2 Key Generation: Salt sources Source Identifier Value Data Type CKZ_SALT_SPECIFIED 0x00000001 Array of CK_BYTE containing the value of the salt value. 5122 CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE_PTR is a pointer to a 5123 CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE.
5124 CK_PKCS5_PBKD2_PARAMS; CK_PKCS5_PBKD2_PARAMS_PTR
5125 CK_PKCS5_PBKD2_PARAMS is a structure that provides the parameters to the CKM_PKCS5_PBKD2 5126 mechanism. The structure is defined as follows: 5127 typedef struct CK_PKCS5_PBKD2_PARAMS { 5128 CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE saltSource; 5129 CK_VOID_PTR pSaltSourceData; 5130 CK_ULONG ulSaltSourceDataLen; 5131 CK_ULONG iterations; 5132 CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE prf; 5133 CK_VOID_PTR pPrfData; 5134 CK_ULONG ulPrfDataLen; 5135 CK_UTF8CHAR_PTR pPassword; 5136 CK_ULONG_PTR ulPasswordLen; 5137 } CK_PKCS5_PBKD2_PARAMS; 5138 5139 The fields of the structure have the following meanings: 5140 saltSource source of the salt value
5141 pSaltSourceData data used as the input for the salt source
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 148 of 278 5142 ulSaltSourceDataLen length of the salt source input
5143 iterations number of iterations to perform when generating each block of 5144 random data
5145 prf pseudo-random function used to generate the key
5146 pPrfData data used as the input for PRF in addition to the salt value
5147 ulPrfDataLen length of the input data for the PRF
5148 pPassword points to the password to be used in the PBE key generation
5149 ulPasswordLen length in bytes of the password information
5150 CK_PKCS5_PBKD2_PARAMS_PTR is a pointer to a CK_PKCS5_PBKD2_PARAMS.
5151 2.37.4 PKCS #5 PBKD2 key generation 5152 PKCS #5 PBKDF2 key generation, denoted CKM_PKCS5_PBKD2, is a mechanism used for generating 5153 a secret key from a password and a salt value. This functionality is defined in PKCS#5 as PBKDF2. 5154 It has a parameter, a CK_PKCS5_PBKD2_PARAMS structure. The parameter specifies the salt value 5155 source, pseudo-random function, and iteration count used to generate the new key. 5156 Since this mechanism can be used to generate any type of secret key, new key templates must contain 5157 the CKA_KEY_TYPE and CKA_VALUE_LEN attributes. If the key type has a fixed length the 5158 CKA_VALUE_LEN attribute may be omitted.
5159 2.38 PKCS #12 password-based encryption/authentication 5160 mechanisms 5161 The mechanisms in this section are for generating keys and IVs for performing password-based 5162 encryption or authentication. The method used to generate keys and IVs is based on a method that was 5163 specified in PKCS #12. 5164 We specify here a general method for producing various types of pseudo-random bits from a password, 5165 p; a string of salt bits, s; and an iteration count, c. The “type” of pseudo-random bits to be produced is 5166 identified by an identification byte, ID, the meaning of which will be discussed later. u v u 5167 Let H be a hash function built around a compression function f: Z2 Z2 Z2 (that is, H has a chaining 5168 variable and output of length u bits, and the message input to the compression function of H is v bits). 5169 For MD2 and MD5, u=128 and v=512; for SHA-1, u=160 and v=512. 5170 We assume here that u and v are both multiples of 8, as are the lengths in bits of the password and salt 5171 strings and the number n of pseudo-random bits required. In addition, u and v are of course nonzero. 5172 1. Construct a string, D (the “diversifier”), by concatenating v/8 copies of ID. 5173 2. Concatenate copies of the salt together to create a string S of length vs/v bits (the final copy of the 5174 salt may be truncated to create S). Note that if the salt is the empty string, then so is S. 5175 3. Concatenate copies of the password together to create a string P of length vp/v bits (the final copy 5176 of the password may be truncated to create P). Note that if the password is the empty string, then so 5177 is P. 5178 4. Set I=S||P to be the concatenation of S and P. 5179 5. Set j=n/u. 5180 6. For i=1, 2, …, j, do the following:
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 149 of 278 c th 5181 a. Set Ai=H (D||I), the c hash of D||I. That is, compute the hash of D||I; compute the hash of 5182 that hash; etc.; continue in this fashion until a total of c hashes have been computed, each on 5183 the result of the previous hash.
5184 b. Concatenate copies of Ai to create a string B of length v bits (the final copy of Ai may be 5185 truncated to create B).
5186 c. Treating I as a concatenation I0, I1, …, Ik-1 of v-bit blocks, where k=s/v+p/v, modify I by v 5187 setting Ij=(Ij+B+1) mod 2 for each j. To perform this addition, treat each v-bit block as a 5188 binary number represented most-significant bit first.
5189 7. Concatenate A1, A2, …, Aj together to form a pseudo-random bit string, A. 5190 8. Use the first n bits of A as the output of this entire process. 5191 When the password-based encryption mechanisms presented in this section are used to generate a key 5192 and IV (if needed) from a password, salt, and an iteration count, the above algorithm is used. To 5193 generate a key, the identifier byte ID is set to the value 1; to generate an IV, the identifier byte ID is set to 5194 the value 2. 5195 When the password based authentication mechanism presented in this section is used to generate a key 5196 from a password, salt, and an iteration count, the above algorithm is used. The identifier byte ID is set to 5197 the value 3.
5198 2.38.1 SHA-1-PBE for 3-key triple-DES-CBC 5199 SHA-1-PBE for 3-key triple-DES-CBC, denoted CKM_PBE_SHA1_DES3_EDE_CBC, is a mechanism 5200 used for generating a 3-key triple-DES secret key and IV from a password and a salt value by using the 5201 SHA-1 digest algorithm and an iteration count. The method used to generate the key and IV is described 5202 above. Each byte of the key produced will have its low-order bit adjusted, if necessary, so that a valid 3- 5203 key triple-DES key with proper parity bits is obtained. 5204 It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the 5205 key generation process and the location of the application-supplied buffer which will receive the 8-byte IV 5206 generated by the mechanism. 5207 The key and IV produced by this mechanism will typically be used for performing password-based 5208 encryption.
5209 2.38.2 SHA-1-PBE for 2-key triple-DES-CBC 5210 SHA-1-PBE for 2-key triple-DES-CBC, denoted CKM_PBE_SHA1_DES2_EDE_CBC, is a mechanism 5211 used for generating a 2-key triple-DES secret key and IV from a password and a salt value by using the 5212 SHA-1 digest algorithm and an iteration count. The method used to generate the key and IV is described 5213 above. Each byte of the key produced will have its low-order bit adjusted, if necessary, so that a valid 2- 5214 key triple-DES key with proper parity bits is obtained. 5215 It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the 5216 key generation process and the location of the application-supplied buffer which will receive the 8-byte IV 5217 generated by the mechanism. 5218 The key and IV produced by this mechanism will typically be used for performing password-based 5219 encryption.
5220 2.38.3 SHA-1-PBA for SHA-1-HMAC 5221 SHA-1-PBA for SHA-1-HMAC, denoted CKM_PBA_SHA1_WITH_SHA1_HMAC, is a mechanism used 5222 for generating a 160-bit generic secret key from a password and a salt value by using the SHA-1 digest 5223 algorithm and an iteration count. The method used to generate the key is described above. 5224 It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the 5225 key generation process. The parameter also has a field to hold the location of an application-supplied 5226 buffer which will receive an IV; for this mechanism, the contents of this field are ignored, since 5227 authentication with SHA-1-HMAC does not require an IV.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 150 of 278 5228 The key generated by this mechanism will typically be used for computing a SHA-1 HMAC to perform 5229 password-based authentication (not password-based encryption). At the time of this writing, this is 5230 primarily done to ensure the integrity of a PKCS #12 PDU.
5231 2.39 SSL 5232 Table 155,SSL Mechanisms vs. Functions Functions Encryp Sign SR Gen Wrap Mechanism t & & Diges . & Deriv & Verif VR t Unwra e Decryp y 1 Key p t / Key Pair CKM_SSL3_PRE_MASTER_KEY_GE N CKM_SSL3_MASTER_KEY_DERIVE CKM_SSL3_MASTER_KEY_DERIVE_ DH CKM_SSL3_KEY_AND_MAC_DERIVE CKM_SSL3_MD5_MAC CKM_SSL3_SHA1_MAC
5233 2.39.1 Definitions 5234 Mechanisms: 5235 CKM_SSL3_PRE_MASTER_KEY_GEN 5236 CKM_SSL3_MASTER_KEY_DERIVE 5237 CKM_SSL3_KEY_AND_MAC_DERIVE 5238 CKM_SSL3_MASTER_KEY_DERIVE_DH 5239 CKM_SSL3_MD5_MAC 5240 CKM_SSL3_SHA1_MAC
5241 2.39.2 SSL mechanism parameters
5242 CK_SSL3_RANDOM_DATA
5243 CK_SSL3_RANDOM_DATA is a structure which provides information about the random data of a client 5244 and a server in an SSL context. This structure is used by both the CKM_SSL3_MASTER_KEY_DERIVE 5245 and the CKM_SSL3_KEY_AND_MAC_DERIVE mechanisms. It is defined as follows: 5246 typedef struct CK_SSL3_RANDOM_DATA { 5247 CK_BYTE_PTR pClientRandom; 5248 CK_ULONG ulClientRandomLen; 5249 CK_BYTE_PTR pServerRandom; 5250 CK_ULONG ulServerRandomLen; 5251 } CK_SSL3_RANDOM_DATA; 5252 5253 The fields of the structure have the following meanings:
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 151 of 278 5254 pClientRandom pointer to the client’s random data
5255 ulClientRandomLen length in bytes of the client’s random data
5256 pServerRandom pointer to the server’s random data
5257 ulServerRandomLen length in bytes of the server’s random data
5258 CK_SSL3_MASTER_KEY_DERIVE_PARAMS; 5259 CK_SSL3_MASTER_KEY_DERIVE_PARAMS_PTR
5260 CK_SSL3_MASTER_KEY_DERIVE_PARAMS is a structure that provides the parameters to the 5261 CKM_SSL3_MASTER_KEY_DERIVE mechanism. It is defined as follows: 5262 typedef struct CK_SSL3_MASTER_KEY_DERIVE_PARAMS { 5263 CK_SSL3_RANDOM_DATA RandomInfo; 5264 CK_VERSION_PTR pVersion; 5265 } CK_SSL3_MASTER_KEY_DERIVE_PARAMS; 5266 5267 The fields of the structure have the following meanings: 5268 RandomInfo client’s and server’s random data information.
5269 pVersion pointer to a CK_VERSION structure which receives the SSL 5270 protocol version information
5271 CK_SSL3_MASTER_KEY_DERIVE_PARAMS_PTR is a pointer to a 5272 CK_SSL3_MASTER_KEY_DERIVE_PARAMS.
5273 CK_SSL3_KEY_MAT_OUT; CK_SSL3_KEY_MAT_OUT_PTR
5274 CK_SSL3_KEY_MAT_OUT is a structure that contains the resulting key handles and initialization vectors 5275 after performing a C_DeriveKey function with the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. It 5276 is defined as follows: 5277 typedef struct CK_SSL3_KEY_MAT_OUT { 5278 CK_OBJECT_HANDLE hClientMacSecret; 5279 CK_OBJECT_HANDLE hServerMacSecret; 5280 CK_OBJECT_HANDLE hClientKey; 5281 CK_OBJECT_HANDLE hServerKey; 5282 CK_BYTE_PTR pIVClient; 5283 CK_BYTE_PTR pIVServer; 5284 } CK_SSL3_KEY_MAT_OUT; 5285 5286 The fields of the structure have the following meanings: 5287 hClientMacSecret key handle for the resulting Client MAC Secret key
5288 hServerMacSecret key handle for the resulting Server MAC Secret key
5289 hClientKey key handle for the resulting Client Secret key
5290 hServerKey key handle for the resulting Server Secret key
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 152 of 278 5291 pIVClient pointer to a location which receives the initialization vector (IV) 5292 created for the client (if any)
5293 pIVServer pointer to a location which receives the initialization vector (IV) 5294 created for the server (if any)
5295 CK_SSL3_KEY_MAT_OUT_PTR is a pointer to a CK_SSL3_KEY_MAT_OUT.
5296 CK_SSL3_KEY_MAT_PARAMS; CK_SSL3_KEY_MAT_PARAMS_PTR
5297 CK_SSL3_KEY_MAT_PARAMS is a structure that provides the parameters to the 5298 CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. It is defined as follows: 5299 typedef struct CK_SSL3_KEY_MAT_PARAMS { 5300 CK_ULONG ulMacSizeInBits; 5301 CK_ULONG ulKeySizeInBits; 5302 CK_ULONG ulIVSizeInBits; 5303 CK_BBOOL bIsExport; 5304 CK_SSL3_RANDOM_DATA RandomInfo; 5305 CK_SSL3_KEY_MAT_OUT_PTR pReturnedKeyMaterial; 5306 } CK_SSL3_KEY_MAT_PARAMS; 5307 5308 The fields of the structure have the following meanings: 5309 ulMacSizeInBits the length (in bits) of the MACing keys agreed upon during the 5310 protocol handshake phase
5311 ulKeySizeInBits the length (in bits) of the secret keys agreed upon during the 5312 protocol handshake phase
5313 ulIVSizeInBits the length (in bits) of the IV agreed upon during the protocol 5314 handshake phase. If no IV is required, the length should be set to 0
5315 bIsExport a Boolean value which indicates whether the keys have to be 5316 derived for an export version of the protocol
5317 RandomInfo client’s and server’s random data information.
5318 pReturnedKeyMaterial points to a CK_SSL3_KEY_MAT_OUT structures which receives 5319 the handles for the keys generated and the IVs
5320 CK_SSL3_KEY_MAT_PARAMS_PTR is a pointer to a CK_SSL3_KEY_MAT_PARAMS.
5321 2.39.3 Pre-master key generation 5322 Pre-master key generation in SSL 3.0, denoted CKM_SSL3_PRE_MASTER_KEY_GEN, is a mechanism 5323 which generates a 48-byte generic secret key. It is used to produce the "pre_master" key used in SSL 5324 version 3.0 for RSA-like cipher suites. 5325 It has one parameter, a CK_VERSION structure, which provides the client’s SSL version number. 5326 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 5327 key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may 5328 be specified in the template, or else are assigned default values. 5329 The template sent along with this mechanism during a C_GenerateKey call may indicate that the object 5330 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 153 of 278 5331 attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to 5332 specify any of them. 5333 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5334 both indicate 48 bytes.
5335 2.39.4 Master key derivation 5336 Master key derivation in SSL 3.0, denoted CKM_SSL3_MASTER_KEY_DERIVE, is a mechanism used 5337 to derive one 48-byte generic secret key from another 48-byte generic secret key. It is used to produce 5338 the "master_secret" key used in the SSL protocol from the "pre_master" key. This mechanism returns the 5339 value of the client version, which is built into the "pre_master" key as well as a handle to the derived 5340 "master_secret" key. 5341 It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the 5342 passing of random data to the token as well as the returning of the protocol version number which is part 5343 of the pre-master key. This structure is defined in Section 2.39. 5344 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 5345 key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may 5346 be specified in the template; otherwise they are assigned default values. 5347 The template sent along with this mechanism during a C_DeriveKey call may indicate that the object 5348 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN 5349 attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to 5350 specify any of them. 5351 This mechanism has the following rules about key sensitivity and extractability: 5352 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 5353 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 5354 default value. 5355 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 5356 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 5357 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 5358 CKA_SENSITIVE attribute. 5359 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 5360 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 5361 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 5362 value from its CKA_EXTRACTABLE attribute. 5363 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5364 both indicate 48 bytes. 5365 Note that the CK_VERSION structure pointed to by the CK_SSL3_MASTER_KEY_DERIVE_PARAMS 5366 structure’s pVersion field will be modified by the C_DeriveKey call. In particular, when the call returns, 5367 this structure will hold the SSL version associated with the supplied pre_master key. 5368 Note that this mechanism is only useable for cipher suites that use a 48-byte “pre_master” secret with an 5369 embedded version number. This includes the RSA cipher suites, but excludes the Diffie-Hellman cipher 5370 suites.
5371 2.39.5 Master key derivation for Diffie-Hellman 5372 Master key derivation for Diffie-Hellman in SSL 3.0, denoted CKM_SSL3_MASTER_KEY_DERIVE_DH, 5373 is a mechanism used to derive one 48-byte generic secret key from another arbitrary length generic 5374 secret key. It is used to produce the "master_secret" key used in the SSL protocol from the "pre_master" 5375 key. 5376 It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the 5377 passing of random data to the token. This structure is defined in Section 2.39. The pVersion field of the 5378 structure must be set to NULL_PTR since the version number is not embedded in the "pre_master" key 5379 as it is for RSA-like cipher suites.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 154 of 278 5380 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 5381 key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may 5382 be specified in the template, or else are assigned default values. 5383 The template sent along with this mechanism during a C_DeriveKey call may indicate that the object 5384 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN 5385 attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to 5386 specify any of them. 5387 This mechanism has the following rules about key sensitivity and extractability: 5388 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 5389 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 5390 default value. 5391 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 5392 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 5393 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 5394 CKA_SENSITIVE attribute. 5395 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 5396 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 5397 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 5398 value from its CKA_EXTRACTABLE attribute. 5399 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5400 both indicate 48 bytes. 5401 Note that this mechanism is only useable for cipher suites that do not use a fixed length 48-byte 5402 “pre_master” secret with an embedded version number. This includes the Diffie-Hellman cipher suites, but 5403 excludes the RSA cipher suites.
5404 2.39.6 Key and MAC derivation 5405 Key, MAC and IV derivation in SSL 3.0, denoted CKM_SSL3_KEY_AND_MAC_DERIVE, is a 5406 mechanism used to derive the appropriate cryptographic keying material used by a "CipherSuite" from the 5407 "master_secret" key and random data. This mechanism returns the key handles for the keys generated in 5408 the process, as well as the IVs created. 5409 It has a parameter, a CK_SSL3_KEY_MAT_PARAMS structure, which allows for the passing of random 5410 data as well as the characteristic of the cryptographic material for the given CipherSuite and a pointer to a 5411 structure which receives the handles and IVs which were generated. This structure is defined in Section 5412 2.39. 5413 This mechanism contributes to the creation of four distinct keys on the token and returns two IVs (if IVs 5414 are requested by the caller) back to the caller. The keys are all given an object class of 5415 CKO_SECRET_KEY. 5416 The two MACing keys ("client_write_MAC_secret" and "server_write_MAC_secret") are always given a 5417 type of CKK_GENERIC_SECRET. They are flagged as valid for signing, verification, and derivation 5418 operations. 5419 The other two keys ("client_write_key" and "server_write_key") are typed according to information found 5420 in the template sent along with this mechanism during a C_DeriveKey function call. By default, they are 5421 flagged as valid for encryption, decryption, and derivation operations. 5422 IVs will be generated and returned if the ulIVSizeInBits field of the CK_SSL3_KEY_MAT_PARAMS field 5423 has a nonzero value. If they are generated, their length in bits will agree with the value in the 5424 ulIVSizeInBits field. 5425 All four keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, 5426 CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template 5427 provided to C_DeriveKey may not specify values for any of these attributes which differ from those held 5428 by the base key.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 155 of 278 5429 Note that the CK_SSL3_KEY_MAT_OUT structure pointed to by the CK_SSL3_KEY_MAT_PARAMS 5430 structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the four 5431 key handle fields in the CK_SSL3_KEY_MAT_OUT structure will be modified to hold handles to the 5432 newly-created keys; in addition, the buffers pointed to by the CK_SSL3_KEY_MAT_OUT structure’s 5433 pIVClient and pIVServer fields will have IVs returned in them (if IVs are requested by the caller). 5434 Therefore, these two fields must point to buffers with sufficient space to hold any IVs that will be returned. 5435 This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. 5436 For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result of a 5437 successful completion. However, since the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism returns 5438 all of its key handles in the CK_SSL3_KEY_MAT_OUT structure pointed to by the 5439 CK_SSL3_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey 5440 passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. 5441 If a call to C_DeriveKey with this mechanism fails, then none of the four keys will be created on the 5442 token.
5443 2.39.7 MD5 MACing in SSL 3.0 5444 MD5 MACing in SSL3.0, denoted CKM_SSL3_MD5_MAC, is a mechanism for single- and multiple-part 5445 signatures (data authentication) and verification using MD5, based on the SSL 3.0 protocol. This 5446 technique is very similar to the HMAC technique. 5447 It has a parameter, a CK_MAC_GENERAL_PARAMS, which specifies the length in bytes of the 5448 signatures produced by this mechanism. 5449 Constraints on key types and the length of input and output data are summarized in the following table: 5450 Table 156, MD5 MACing in SSL 3.0: Key And Data Length Function Key type Data length Signature length C_Sign generic secret any 4-8, depending on parameters C_Verify generic secret any 4-8, depending on parameters 5451 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5452 specify the supported range of generic secret key sizes, in bits.
5453 2.39.8 SHA-1 MACing in SSL 3.0 5454 SHA-1 MACing in SSL3.0, denoted CKM_SSL3_SHA1_MAC, is a mechanism for single- and multiple- 5455 part signatures (data authentication) and verification using SHA-1, based on the SSL 3.0 protocol. This 5456 technique is very similar to the HMAC technique. 5457 It has a parameter, a CK_MAC_GENERAL_PARAMS, which specifies the length in bytes of the 5458 signatures produced by this mechanism. 5459 Constraints on key types and the length of input and output data are summarized in the following table: 5460 Table 157, SHA-1 MACing in SSL 3.0: Key And Data Length Function Key type Data Signature length length C_Sign generic secret any 4-8, depending on parameters C_Verify generic secret any 4-8, depending on parameters 5461 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5462 specify the supported range of generic secret key sizes, in bits.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 156 of 278 5463 2.40 TLS 1.2 Mechanisms 5464 Details for TLS 1.2 and its key derivation and MAC mechanisms can be found in [TLS12]. TLS 1.2 5465 mechanisms differ from TLS 1.0 and 1.1 mechanisms in that the base hash used in the underlying TLS 5466 PRF (pseudo-random function) can be negotiated. Therefore each mechanism parameter for the TLS 1.2 5467 mechanisms contains a new value in the parameters structure to specify the hash function. 5468 This section also specifies CKM_TLS12_MAC which should be used in place of CKM_TLS_PRF to 5469 calculate the verify_data in the TLS "finished" message. 5470 This section also specifies CKM_TLS_KDF that can be used in place of CKM_TLS_PRF to implement 5471 key material exporters. 5472 5473 Table 158, TLS 1.2 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_TLS12_MASTER_KEY_DERIVE CKM_TLS12_MASTER_KEY_DERIVE_DH CKM_TLS12_KEY_AND_MAC_DERIVE CKM_TLS12_KEY_SAFE_DERIVE CKM_TLS_KDF CKM_TLS12_MAC CKM_TLS12_KDF
5474 2.40.1 Definitions 5475 Mechanisms: 5476 CKM_TLS12_MASTER_KEY_DERIVE 5477 CKM_TLS12_MASTER_KEY_DERIVE_DH 5478 CKM_TLS12_KEY_AND_MAC_DERIVE 5479 CKM_TLS12_KEY_SAFE_DERIVE 5480 CKM_TLS_KDF 5481 CKM_TLS12_MAC 5482 CKM_TLS12_KDF
5483 2.40.2 TLS 1.2 mechanism parameters
5484 CK_TLS12_MASTER_KEY_DERIVE_PARAMS; 5485 CK_TLS12_MASTER_KEY_DERIVE_PARAMS_PTR
5486 CK_TLS12_MASTER_KEY_DERIVE_PARAMS is a structure that provides the parameters to the 5487 CKM_TLS12_MASTER_KEY_DERIVE mechanism. It is defined as follows: 5488 typedef struct CK_TLS12_MASTER_KEY_DERIVE_PARAMS { 5489 CK_SSL3_RANDOM_DATA RandomInfo; 5490 CK_VERSION_PTR pVersion; 5491 CK_MECHANISM_TYPE prfHashMechanism;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 157 of 278 5492 } CK_TLS12_MASTER_KEY_DERIVE_PARAMS; 5493 5494 The fields of the structure have the following meanings: 5495 RandomInfo client’s and server’s random data information.
5496 pVersion pointer to a CK_VERSION structure which receives the SSL 5497 protocol version information
5498 prfHashMechanism base hash used in the underlying TLS1.2 PRF operation used to 5499 derive the master key.
5500
5501 CK_TLS12_MASTER_KEY_DERIVE_PARAMS_PTR is a pointer to a 5502 CK_TLS12_MASTER_KEY_DERIVE_PARAMS.
5503 CK_TLS12_KEY_MAT_PARAMS; CK_TLS12_KEY_MAT_PARAMS_PTR
5504 CK_TLS12_KEY_MAT_PARAMS is a structure that provides the parameters to the 5505 CKM_TLS12_KEY_AND_MAC_DERIVE mechanism. It is defined as follows: 5506 typedef struct CK_TLS12_KEY_MAT_PARAMS { 5507 CK_ULONG ulMacSizeInBits; 5508 CK_ULONG ulKeySizeInBits; 5509 CK_ULONG ulIVSizeInBits; 5510 CK_BBOOL bIsExport; 5511 CK_SSL3_RANDOM_DATA RandomInfo; 5512 CK_SSL3_KEY_MAT_OUT_PTR pReturnedKeyMaterial; 5513 CK_MECHANISM_TYPE prfHashMechanism; 5514 } CK_TLS12_KEY_MAT_PARAMS; 5515 5516 The fields of the structure have the following meanings: 5517 ulMacSizeInBits the length (in bits) of the MACing keys agreed upon during the 5518 protocol handshake phase. If no MAC key is required, the length 5519 should be set to 0.
5520 ulKeySizeInBits the length (in bits) of the secret keys agreed upon during the 5521 protocol handshake phase
5522 ulIVSizeInBits the length (in bits) of the IV agreed upon during the protocol 5523 handshake phase. If no IV is required, the length should be set to 0
5524 bIsExport must be set to CK_FALSE because export cipher suites must not be 5525 used in TLS 1.1 and later.
5526 RandomInfo client’s and server’s random data information.
5527 pReturnedKeyMaterial points to a CK_SSL3_KEY_MAT_OUT structures which receives 5528 the handles for the keys generated and the IVs
5529 prfHashMechanism base hash used in the underlying TLS1.2 PRF operation used to 5530 derive the master key.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 158 of 278 5531 CK_TLS12_KEY_MAT_PARAMS_PTR is a pointer to a CK_TLS12_KEY_MAT_PARAMS.
5532 CK_TLS_KDF_PARAMS; CK_TLS_KDF_PARAMS_PTR
5533 CK_TLS_KDF_PARAMS is a structure that provides the parameters to the CKM_TLS_KDF mechanism. 5534 It is defined as follows: 5535 typedef struct CK_TLS_KDF_PARAMS { 5536 CK_MECHANISM_TYPE prfMechanism; 5537 CK_BYTE_PTR pLabel; 5538 CK_ULONG ulLabelLength; 5539 CK_SSL3_RANDOM_DATA RandomInfo; 5540 CK_BYTE_PTR pContextData; 5541 CK_ULONG ulContextDataLength; 5542 } CK_TLS_KDF_PARAMS; 5543 5544 The fields of the structure have the following meanings: 5545 prfMechanismthe hash mechanism used in the TLS1.2 PRF construct or CKM_TLS_PRF to use with the 5546 TLS1.0 and 1.1 PRF construct.
5547 pLabela pointer to the label for this key derivation
5548 ulLabelLengthlength of the label in bytes
5549 RandomInfothe random data for the key derivation
5550 pContextDataa pointer to the context data for this key derivation. NULL_PTR if not present
5551 ulContextDataLength length of the context data in bytes. 0 if not present.
5552
5553 CK_TLS_MAC_PARAMS; CK_TLS_MAC_PARAMS_PTR
5554 CK_TLS_MAC_PARAMS is a structure that provides the parameters to the CKM_TLS_MAC 5555 mechanism. It is defined as follows: 5556 typedef struct CK_TLS_MAC_PARAMS { 5557 CK_MECHANISM_TYPE prfMechanism; 5558 CK_ULONG ulMacLength; 5559 CK_ULONG ulServerOrClient; 5560 } CK_TLS_MAC_PARAMS; 5561 5562 The fields of the structure have the following meanings: 5563 prfMechanism the hash mechanism used in the TLS12 PRF construct or 5564 CKM_TLS_PRF to use with the TLS1.0 and 1.1 PRF construct.
5565 ulMacLengththe length of the MAC tag required or offered. Always 12 octets in TLS 1.0 and 1.1. 5566 Generally 12 octets, but may be negotiated to a longer value in 5567 TLS1.2.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 159 of 278 5568 ulServerOrClient 1 to use the label "server finished", 2 to use the label "client 5569 finished". All other values are invalid.
5570 CK_TLS_MAC_PARAMS_PTR is a pointer to a CK_TLS_MAC_PARAMS. 5571
5572 CK_TLS_PRF_PARAMS; CK_TLS_PRF_PARAMS_PTR
5573 CK_TLS_PRF_PARAMS is a structure, which provides the parameters to the CKM_TLS_PRF 5574 mechanism. It is defined as follows: 5575 typedef struct CK_TLS_PRF_PARAMS { 5576 CK_BYTE_PTR pSeed; 5577 CK_ULONG ulSeedLen; 5578 CK_BYTE_PTR pLabel; 5579 CK_ULONG ulLabelLen; 5580 CK_BYTE_PTR pOutput; 5581 CK_ULONG_PTR pulOutputLen; 5582 } CK_TLS_PRF_PARAMS; 5583 5584 The fields of the structure have the following meanings: 5585 pSeed pointer to the input seed
5586 ulSeedLen length in bytes of the input seed
5587 pLabel pointer to the identifying label
5588 ulLabelLen length in bytes of the identifying label
5589 pOutput pointer receiving the output of the operation
5590 pulOutputLen pointer to the length in bytes that the output to be created shall 5591 have, has to hold the desired length as input and will receive the 5592 calculated length as output
5593 CK_TLS_PRF_PARAMS_PTR is a pointer to a CK_TLS_PRF_PARAMS.
5594 2.40.3 TLS MAC 5595 The TLS MAC mechanism is used to generate integrity tags for the TLS "finished" message. It replaces 5596 the use of the CKM_TLS_PRF function for TLS1.0 and 1.1 and that mechanism is deprecated. 5597 CKM_TLS_MAC takes a parameter of CK_TLS_MAC_PARAMS. To use this mechanism with TLS1.0 5598 and TLS1.1, use CKM_TLS_PRF as the value for prfMechanism in place of a hash mechanism. Note: 5599 Although CKM_TLS_PRF is deprecated as a mechanism for C_DeriveKey, the manifest value is retained 5600 for use with this mechanism to indicate the use of the TLS1.0/1.1 pseudo-random function. 5601 In TLS1.0 and 1.1 the "finished" message verify_data (i.e. the output signature from the MAC mechanism) 5602 is always 12 bytes. In TLS1.2 the "finished" message verify_data is a minimum of 12 bytes, defaults to 12 5603 bytes, but may be negotiated to longer length. 5604 Table 159, General-length TLS MAC: Key And Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 160 of 278 Function Key type Data length Signature length C_Sign generic secret any >=12 bytes C_Verify generic secret any >=12 bytes 5605
5606 2.40.4 Master key derivation 5607 Master key derivation in TLS 1.0, denoted CKM_TLS_MASTER_KEY_DERIVE, is a mechanism used to 5608 derive one 48-byte generic secret key from another 48-byte generic secret key. It is used to produce the 5609 "master_secret" key used in the TLS protocol from the "pre_master" key. This mechanism returns the 5610 value of the client version, which is built into the "pre_master" key as well as a handle to the derived 5611 "master_secret" key. 5612 It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the 5613 passing of random data to the token as well as the returning of the protocol version number which is part 5614 of the pre-master key. This structure is defined in Section 2.39. 5615 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 5616 key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may 5617 be specified in the template, or else are assigned default values. 5618 The mechanism also contributes the CKA_ALLOWED_MECHANISMS attribute consisting only of 5619 CKM_TLS12_KEY_AND_MAC_DERIVE, CKM_TLS12_KEY_SAFE_DERIVE, CKM_TLS12_KDF and 5620 CKM_TLS12_MAC. 5621 The template sent along with this mechanism during a C_DeriveKey call may indicate that the object 5622 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN 5623 attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to 5624 specify any of them. 5625 This mechanism has the following rules about key sensitivity and extractability: 5626 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 5627 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 5628 default value. 5629 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 5630 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 5631 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 5632 CKA_SENSITIVE attribute. 5633 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 5634 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 5635 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 5636 value from its CKA_EXTRACTABLE attribute. 5637 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5638 both indicate 48 bytes. 5639 Note that the CK_VERSION structure pointed to by the CK_SSL3_MASTER_KEY_DERIVE_PARAMS 5640 structure’s pVersion field will be modified by the C_DeriveKey call. In particular, when the call returns, 5641 this structure will hold the SSL version associated with the supplied pre_master key. 5642 Note that this mechanism is only useable for cipher suites that use a 48-byte “pre_master” secret with an 5643 embedded version number. This includes the RSA cipher suites, but excludes the Diffie-Hellman cipher 5644 suites.
5645 2.40.5 Master key derivation for Diffie-Hellman 5646 Master key derivation for Diffie-Hellman in TLS 1.0, denoted CKM_TLS_MASTER_KEY_DERIVE_DH, is 5647 a mechanism used to derive one 48-byte generic secret key from another arbitrary length generic secret 5648 key. It is used to produce the "master_secret" key used in the TLS protocol from the "pre_master" key.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 161 of 278 5649 It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the 5650 passing of random data to the token. This structure is defined in Section 2.39. The pVersion field of the 5651 structure must be set to NULL_PTR since the version number is not embedded in the "pre_master" key 5652 as it is for RSA-like cipher suites. 5653 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 5654 key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may 5655 be specified in the template, or else are assigned default values. 5656 The mechanism also contributes the CKA_ALLOWED_MECHANISMS attribute consisting only of 5657 CKM_TLS12_KEY_AND_MAC_DERIVE, CKM_TLS12_KEY_SAFE_DERIVE, CKM_TLS12_KDF and 5658 CKM_TLS12_MAC. 5659 The template sent along with this mechanism during a C_DeriveKey call may indicate that the object 5660 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN 5661 attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to 5662 specify any of them. 5663 This mechanism has the following rules about key sensitivity and extractability: 5664 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 5665 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 5666 default value. 5667 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 5668 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 5669 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 5670 CKA_SENSITIVE attribute. 5671 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 5672 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 5673 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 5674 value from its CKA_EXTRACTABLE attribute. 5675 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5676 both indicate 48 bytes. 5677 Note that this mechanism is only useable for cipher suites that do not use a fixed length 48-byte 5678 “pre_master” secret with an embedded version number. This includes the Diffie-Hellman cipher suites, but 5679 excludes the RSA cipher suites.
5680 2.40.6 Key and MAC derivation 5681 Key, MAC and IV derivation in TLS 1.0, denoted CKM_TLS_KEY_AND_MAC_DERIVE, is a mechanism 5682 used to derive the appropriate cryptographic keying material used by a "CipherSuite" from the 5683 "master_secret" key and random data. This mechanism returns the key handles for the keys generated in 5684 the process, as well as the IVs created. 5685 It has a parameter, a CK_SSL3_KEY_MAT_PARAMS structure, which allows for the passing of random 5686 data as well as the characteristic of the cryptographic material for the given CipherSuite and a pointer to a 5687 structure which receives the handles and IVs which were generated. This structure is defined in Section 5688 2.39. 5689 This mechanism contributes to the creation of four distinct keys on the token and returns two IVs (if IVs 5690 are requested by the caller) back to the caller. The keys are all given an object class of 5691 CKO_SECRET_KEY. 5692 The two MACing keys ("client_write_MAC_secret" and "server_write_MAC_secret") (if present) are 5693 always given a type of CKK_GENERIC_SECRET. They are flagged as valid for signing and verification. 5694 The other two keys ("client_write_key" and "server_write_key") are typed according to information found 5695 in the template sent along with this mechanism during a C_DeriveKey function call. By default, they are 5696 flagged as valid for encryption, decryption, and derivation operations.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 162 of 278 5697 For CKM_TLS12_KEY_AND_MAC_DERIVE, IVs will be generated and returned if the ulIVSizeInBits 5698 field of the CK_SSL3_KEY_MAT_PARAMS field has a nonzero value. If they are generated, their length 5699 in bits will agree with the value in the ulIVSizeInBits field. 5700 5701 Note Well: CKM_TLS12_KEY_AND_MAC_DERIVE produces both private (key) and public (IV) 5702 data. It is possible to "leak" private data by the simple expedient of decreasing the length of 5703 private data requested. E.g. Setting ulMacSizeInBits and ulKeySizeInBits to 0 (or other lengths 5704 less than the key size) will result in the private key data being placed in the destination 5705 designated for the IV's. Repeated calls with the same master key and same RandomInfo but with 5706 differing lengths for the private key material will result in different data being leaked.< 5707 5708 All four keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, 5709 CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template 5710 provided to C_DeriveKey may not specify values for any of these attributes which differ from those held 5711 by the base key. 5712 Note that the CK_SSL3_KEY_MAT_OUT structure pointed to by the CK_SSL3_KEY_MAT_PARAMS 5713 structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the four 5714 key handle fields in the CK_SSL3_KEY_MAT_OUT structure will be modified to hold handles to the 5715 newly-created keys; in addition, the buffers pointed to by the CK_SSL3_KEY_MAT_OUT structure’s 5716 pIVClient and pIVServer fields will have IVs returned in them (if IVs are requested by the caller). 5717 Therefore, these two fields must point to buffers with sufficient space to hold any IVs that will be returned. 5718 This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. 5719 For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result of a 5720 successful completion. However, since the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism returns 5721 all of its key handles in the CK_SSL3_KEY_MAT_OUT structure pointed to by the 5722 CK_SSL3_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey 5723 passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. 5724 If a call to C_DeriveKey with this mechanism fails, then none of the four keys will be created on the 5725 token.
5726 2.40.7 CKM_TLS12_KEY_SAFE_DERIVE 5727 CKM_TLS12_KEY_SAFE_DERIVE is identical to CKM_TLS12_KEY_AND_MAC_DERIVE except that it 5728 shall never produce IV data, and the ulIvSizeInBits field of CK_TLS12_KEY_MAT_PARAMS is ignored 5729 and treated as 0. All of the other conditions and behavior described for 5730 CKM_TLS12_KEY_AND_MAC_DERIVE, with the exception of the black box warning, apply to this 5731 mechanism. 5732 CKM_TLS12_KEY_SAFE_DERIVE is provided as a separate mechanism to allow a client to control the 5733 export of IV material (and possible leaking of key material) through the use of the 5734 CKA_ALLOWED_MECHANISMS key attribute.
5735 2.40.8 Generic Key Derivation using the TLS PRF 5736 CKM_TLS_KDF is the mechanism defined in [RFC 5705]. It uses the TLS key material and TLS PRF 5737 function to produce additional key material for protocols that want to leverage the TLS key negotiation 5738 mechanism. CKM_TLS_KDF has a parameter of CK_TLS_KDF_PARAMS. If the protocol using this 5739 mechanism does not use context information, the pContextData field shall be set to NULL_PTR and the 5740 ulContextDataLength field shall be set to 0. 5741 To use this mechanism with TLS1.0 and TLS1.1, use CKM_TLS_PRF as the value for prfMechanism in 5742 place of a hash mechanism. Note: Although CKM_TLS_PRF is deprecated as a mechanism for 5743 C_DeriveKey, the manifest value is retained for use with this mechanism to indicate the use of the 5744 TLS1.0/1.1 Pseudo-random function.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 163 of 278 5745 This mechanism can be used to derive multiple keys (e.g. similar to 5746 CKM_TLS12_KEY_AND_MAC_DERIVE) by first deriving the key stream as a CKK_GENERIC_SECRET 5747 of the necessary length and doing subsequent derives against that derived key using the 5748 CKM_EXTRACT_KEY_FROM_KEY mechanism to split the key stream into the actual operational keys. 5749 The mechanism should not be used with the labels defined for use with TLS, but the token does not 5750 enforce this behavior. 5751 This mechanism has the following rules about key sensitivity and extractability: 5752 If the original key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, 5753 then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from the 5754 original key.
5755 Similarly, if the original key has its CKA_EXTRACTABLE attribute set to CK_FALSE, so does the 5756 derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either from the 5757 supplied template or from the original key.
5758 The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the original 5759 key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE.
5760 Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 5761 the original key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
5762 2.40.9 Generic Key Derivation using the TLS12 PRF 5763 CKM_TLS12_KDF is the mechanism defined in [RFC 5705]. It uses the TLS key material and TLS PRF 5764 function to produce additional key material for protocols that want to leverage the TLS key negotiation 5765 mechanism. CKM_TLS12_KDF has a parameter of CK_TLS_KDF_PARAMS. If the protocol using this 5766 mechanism does not use context information, the pContextData field shall be set to NULL_PTR and the 5767 ulContextDataLength field shall be set to 0. 5768 To use this mechanism with TLS1.0 and TLS1.1, use CKM_TLS_PRF as the value for prfMechanism in 5769 place of a hash mechanism. Note: Although CKM_TLS_PRF is deprecated as a mechanism for 5770 C_DeriveKey, the manifest value is retained for use with this mechanism to indicate the use of the 5771 TLS1.0/1.1 Pseudo-random function. 5772 This mechanism can be used to derive multiple keys (e.g. similar to 5773 CKM_TLS12_KEY_AND_MAC_DERIVE) by first deriving the key stream as a CKK_GENERIC_SECRET 5774 of the necessary length and doing subsequent derives against that derived key stream using the 5775 CKM_EXTRACT_KEY_FROM_KEY mechanism to split the key stream into the actual operational keys. 5776 The mechanism should not be used with the labels defined for use with TLS, but the token does not 5777 enforce this behavior. 5778 This mechanism has the following rules about key sensitivity and extractability: 5779 If the original key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, 5780 then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from the 5781 original key.
5782 Similarly, if the original key has its CKA_EXTRACTABLE attribute set to CK_FALSE, so does the 5783 derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either from the 5784 supplied template or from the original key.
5785 The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the original 5786 key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE.
5787 Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 5788 the original key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 164 of 278 5789 2.41 WTLS 5790 Details can be found in [WTLS]. 5791 When comparing the existing TLS mechanisms with these extensions to support WTLS one could argue 5792 that there would be no need to have distinct handling of the client and server side of the handshake. 5793 However, since in WTLS the server and client use different sequence numbers, there could be instances 5794 (e.g. when WTLS is used to protect asynchronous protocols) where sequence numbers on the client and 5795 server side differ, and hence this motivates the introduced split. 5796 5797 Table 160, WTLS Mechanisms vs. Functions Functions Encry Sign SR Ge Wrap Mechanism pt & & Dige n. & Deriv & Verif VR st Unwra e Decry y 1 Key p pt / Key Pair CKM_WTLS_PRE_MASTER_KEY_GEN CKM_WTLS_MASTER_KEY_DERIVE CKM_WTLS_MASTER_KEY_DERIVE_DH _ECC CKM_WTLS_SERVER_KEY_AND_MAC_ DERIVE CKM_WTLS_CLIENT_KEY_AND_MAC_D ERIVE CKM_WTLS_PRF
5798 2.41.1 Definitions 5799 Mechanisms: 5800 CKM_WTLS_PRE_MASTER_KEY_GEN 5801 CKM_WTLS_MASTER_KEY_DERIVE 5802 CKM_WTLS_MASTER_KEY_DERIVE_DH_ECC 5803 CKM_WTLS_PRF 5804 CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE 5805 CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE
5806 2.41.2 WTLS mechanism parameters
5807 CK_WTLS_RANDOM_DATA; CK_WTLS_RANDOM_DATA_PTR
5808 CK_WTLS_RANDOM_DATA is a structure, which provides information about the random data of a client 5809 and a server in a WTLS context. This structure is used by the CKM_WTLS_MASTER_KEY_DERIVE 5810 mechanism. It is defined as follows: 5811 typedef struct CK_WTLS_RANDOM_DATA { 5812 CK_BYTE_PTR pClientRandom; 5813 CK_ULONG ulClientRandomLen; 5814 CK_BYTE_PTR pServerRandom;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 165 of 278 5815 CK_ULONG ulServerRandomLen; 5816 } CK_WTLS_RANDOM_DATA; 5817 5818 The fields of the structure have the following meanings: 5819 pClientRandom pointer to the client’s random data
5820 pClientRandomLen length in bytes of the client’s random data
5821 pServerRaondom pointer to the server’s random data
5822 ulServerRandomLen length in bytes of the server’s random data
5823 CK_WTLS_RANDOM_DATA_PTR is a pointer to a CK_WTLS_RANDOM_DATA.
5824 CK_WTLS_MASTER_KEY_DERIVE_PARAMS; 5825 CK_WTLS_MASTER_KEY_DERIVE_PARAMS _PTR
5826 CK_WTLS_MASTER_KEY_DERIVE_PARAMS is a structure, which provides the parameters to the 5827 CKM_WTLS_MASTER_KEY_DERIVE mechanism. It is defined as follows: 5828 typedef struct CK_WTLS_MASTER_KEY_DERIVE_PARAMS { 5829 CK_MECHANISM_TYPE DigestMechanism; 5830 CK_WTLS_RANDOM_DATA RandomInfo; 5831 CK_BYTE_PTR pVersion; 5832 } CK_WTLS_MASTER_KEY_DERIVE_PARAMS; 5833 5834 The fields of the structure have the following meanings: 5835 DigestMechanism the mechanism type of the digest mechanism to be used (possible 5836 types can be found in [WTLS])
5837 RandomInfo Client’s and server’s random data information
5838 pVersion pointer to a CK_BYTE which receives the WTLS protocol version 5839 information
5840 CK_WTLS_MASTER_KEY_DERIVE_PARAMS_PTR is a pointer to a 5841 CK_WTLS_MASTER_KEY_DERIVE_PARAMS.
5842 CK_WTLS_PRF_PARAMS; CK_WTLS_PRF_PARAMS_PTR
5843 CK_WTLS_PRF_PARAMS is a structure, which provides the parameters to the CKM_WTLS_PRF 5844 mechanism. It is defined as follows: 5845 typedef struct CK_WTLS_PRF_PARAMS { 5846 CK_MECHANISM_TYPE DigestMechanism; 5847 CK_BYTE_PTR pSeed; 5848 CK_ULONG ulSeedLen; 5849 CK_BYTE_PTR pLabel; 5850 CK_ULONG ulLabelLen; 5851 CK_BYTE_PTR pOutput; 5852 CK_ULONG_PTR pulOutputLen; 5853 } CK_WTLS_PRF_PARAMS;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 166 of 278 5854 5855 The fields of the structure have the following meanings: 5856 Digest Mechanism the mechanism type of the digest mechanism to be used (possible 5857 types can be found in [WTLS])
5858 pSeed pointer to the input seed
5859 ulSeedLen length in bytes of the input seed
5860 pLabel pointer to the identifying label
5861 ulLabelLen length in bytes of the identifying label
5862 pOutput pointer receiving the output of the operation
5863 pulOutputLen pointer to the length in bytes that the output to be created shall 5864 have, has to hold the desired length as input and will receive the 5865 calculated length as output
5866 CK_WTLS_PRF_PARAMS_PTR is a pointer to a CK_WTLS_PRF_PARAMS.
5867 CK_WTLS_KEY_MAT_OUT; CK_WTLS_KEY_MAT_OUT_PTR
5868 CK_WTLS_KEY_MAT_OUT is a structure that contains the resulting key handles and initialization 5869 vectors after performing a C_DeriveKey function with the 5870 CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE or with the 5871 CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE mechanism. It is defined as follows: 5872 typedef struct CK_WTLS_KEY_MAT_OUT { 5873 CK_OBJECT_HANDLE hMacSecret; 5874 CK_OBJECT_HANDLE hKey; 5875 CK_BYTE_PTR pIV; 5876 } CK_WTLS_KEY_MAT_OUT; 5877 5878 The fields of the structure have the following meanings: 5879 hMacSecret Key handle for the resulting MAC secret key
5880 hKey Key handle for the resulting secret key
5881 pIV Pointer to a location which receives the initialization vector (IV) 5882 created (if any)
5883 CK_WTLS_KEY_MAT_OUT _PTR is a pointer to a CK_WTLS_KEY_MAT_OUT.
5884 CK_WTLS_KEY_MAT_PARAMS; CK_WTLS_KEY_MAT_PARAMS_PTR
5885 CK_WTLS_KEY_MAT_PARAMS is a structure that provides the parameters to the 5886 CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE and the 5887 CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE mechanisms. It is defined as follows: 5888 typedef struct CK_WTLS_KEY_MAT_PARAMS { 5889 CK_MECHANISM_TYPE DigestMechanism; 5890 CK_ULONG ulMacSizeInBits; 5891 CK_ULONG ulKeySizeInBits;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 167 of 278 5892 CK_ULONG ulIVSizeInBits; 5893 CK_ULONG ulSequenceNumber; 5894 CK_BBOOL bIsExport; 5895 CK_WTLS_RANDOM_DATA RandomInfo; 5896 CK_WTLS_KEY_MAT_OUT_PTR pReturnedKeyMaterial; 5897 } CK_WTLS_KEY_MAT_PARAMS; 5898 5899 The fields of the structure have the following meanings: 5900 Digest Mechanism the mechanism type of the digest mechanism to be used (possible 5901 types can be found in [WTLS])
5902 ulMaxSizeInBits the length (in bits) of the MACing key agreed upon during the 5903 protocol handshake phase
5904 ulKeySizeInBits the length (in bits) of the secret key agreed upon during the 5905 handshake phase
5906 ulIVSizeInBits the length (in bits) of the IV agreed upon during the handshake 5907 phase. If no IV is required, the length should be set to 0.
5908 ulSequenceNumber the current sequence number used for records sent by the client 5909 and server respectively
5910 bIsExport a boolean value which indicates whether the keys have to be 5911 derives for an export version of the protocol. If this value is true 5912 (i.e., the keys are exportable) then ulKeySizeInBits is the length of 5913 the key in bits before expansion. The length of the key after 5914 expansion is determined by the information found in the template 5915 sent along with this mechanism during a C_DeriveKey function call 5916 (either the CKA_KEY_TYPE or the CKA_VALUE_LEN attribute).
5917 RandomInfo client’s and server’s random data information
5918 pReturnedKeyMaterial points to a CK_WTLS_KEY_MAT_OUT structure which receives 5919 the handles for the keys generated and the IV
5920 CK_WTLS_KEY_MAT_PARAMS_PTR is a pointer to a CK_WTLS_KEY_MAT_PARAMS.
5921 2.41.3 Pre master secret key generation for RSA key exchange suite 5922 Pre master secret key generation for the RSA key exchange suite in WTLS denoted 5923 CKM_WTLS_PRE_MASTER_KEY_GEN, is a mechanism, which generates a variable length secret key. 5924 It is used to produce the pre master secret key for RSA key exchange suite used in WTLS. This 5925 mechanism returns a handle to the pre master secret key. 5926 It has one parameter, a CK_BYTE, which provides the client’s WTLS version. 5927 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE and CKA_VALUE attributes to the new 5928 key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may 5929 be specified in the template, or else are assigned default values. 5930 The template sent along with this mechanism during a C_GenerateKey call may indicate that the object 5931 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN 5932 attribute indicates the length of the pre master secret key. 5933 For this mechanism, the ulMinKeySize field of the CK_MECHANISM_INFO structure shall indicate 20 5934 bytes.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 168 of 278 5935 2.41.4 Master secret key derivation 5936 Master secret derivation in WTLS, denoted CKM_WTLS_MASTER_KEY_DERIVE, is a mechanism used 5937 to derive a 20 byte generic secret key from variable length secret key. It is used to produce the master 5938 secret key used in WTLS from the pre master secret key. This mechanism returns the value of the client 5939 version, which is built into the pre master secret key as well as a handle to the derived master secret key. 5940 It has a parameter, a CK_WTLS_MASTER_KEY_DERIVE_PARAMS structure, which allows for passing 5941 the mechanism type of the digest mechanism to be used as well as the passing of random data to the 5942 token as well as the returning of the protocol version number which is part of the pre master secret key. 5943 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 5944 key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may 5945 be specified in the template, or else are assigned default values. 5946 The template sent along with this mechanism during a C_DeriveKey call may indicate that the object 5947 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN 5948 attribute has value 20. However, since these facts are all implicit in the mechanism, there is no need to 5949 specify any of them. 5950 This mechanism has the following rules about key sensitivity and extractability: 5951 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be 5952 specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default 5953 value. 5954 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will 5955 as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived 5956 key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute. 5957 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 5958 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, 5959 then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its 5960 CKA_EXTRACTABLE attribute. 5961 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5962 both indicate 20 bytes. 5963 Note that the CK_BYTE pointed to by the CK_WTLS_MASTER_KEY_DERIVE_PARAMS structure’s 5964 pVersion field will be modified by the C_DeriveKey call. In particular, when the call returns, this byte will 5965 hold the WTLS version associated with the supplied pre master secret key. 5966 Note that this mechanism is only useable for key exchange suites that use a 20-byte pre master secret 5967 key with an embedded version number. This includes the RSA key exchange suites, but excludes the 5968 Diffie-Hellman and Elliptic Curve Cryptography key exchange suites.
5969 2.41.5 Master secret key derivation for Diffie-Hellman and Elliptic Curve 5970 Cryptography 5971 Master secret derivation for Diffie-Hellman and Elliptic Curve Cryptography in WTLS, denoted 5972 CKM_WTLS_MASTER_KEY_DERIVE_DH_ECC, is a mechanism used to derive a 20 byte generic 5973 secret key from variable length secret key. It is used to produce the master secret key used in WTLS from 5974 the pre master secret key. This mechanism returns a handle to the derived master secret key. 5975 It has a parameter, a CK_WTLS_MASTER_KEY_DERIVE_PARAMS structure, which allows for the 5976 passing of the mechanism type of the digest mechanism to be used as well as random data to the token. 5977 The pVersion field of the structure must be set to NULL_PTR since the version number is not embedded 5978 in the pre master secret key as it is for RSA-like key exchange suites. 5979 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 5980 key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may 5981 be specified in the template, or else are assigned default values. 5982 The template sent along with this mechanism during a C_DeriveKey call may indicate that the object 5983 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 169 of 278 5984 attribute has value 20. However, since these facts are all implicit in the mechanism, there is no need to 5985 specify any of them. 5986 This mechanism has the following rules about key sensitivity and extractability: 5987 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be 5988 specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default 5989 value. 5990 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will 5991 as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived 5992 key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute. 5993 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 5994 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, 5995 then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its 5996 CKA_EXTRACTABLE attribute. 5997 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 5998 both indicate 20 bytes. 5999 Note that this mechanism is only useable for key exchange suites that do not use a fixed length 20-byte 6000 pre master secret key with an embedded version number. This includes the Diffie-Hellman and Elliptic 6001 Curve Cryptography key exchange suites, but excludes the RSA key exchange suites.
6002 2.41.6 WTLS PRF (pseudorandom function) 6003 PRF (pseudo random function) in WTLS, denoted CKM_WTLS_PRF, is a mechanism used to produce a 6004 securely generated pseudo-random output of arbitrary length. The keys it uses are generic secret keys. 6005 It has a parameter, a CK_WTLS_PRF_PARAMS structure, which allows for passing the mechanism type 6006 of the digest mechanism to be used, the passing of the input seed and its length, the passing of an 6007 identifying label and its length and the passing of the length of the output to the token and for receiving 6008 the output. 6009 This mechanism produces securely generated pseudo-random output of the length specified in the 6010 parameter. 6011 This mechanism departs from the other key derivation mechanisms in Cryptoki in not using the template 6012 sent along with this mechanism during a C_DeriveKey function call, which means the template shall be a 6013 NULL_PTR. For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result 6014 of a successful completion. However, since the CKM_WTLS_PRF mechanism returns the requested 6015 number of output bytes in the CK_WTLS_PRF_PARAMS structure specified as the mechanism 6016 parameter, the parameter phKey passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. 6017 If a call to C_DeriveKey with this mechanism fails, then no output will be generated.
6018 2.41.7 Server Key and MAC derivation 6019 Server key, MAC and IV derivation in WTLS, denoted 6020 CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE, is a mechanism used to derive the appropriate 6021 cryptographic keying material used by a cipher suite from the master secret key and random data. This 6022 mechanism returns the key handles for the keys generated in the process, as well as the IV created. 6023 It has a parameter, a CK_WTLS_KEY_MAT_PARAMS structure, which allows for the passing of the 6024 mechanism type of the digest mechanism to be used, random data, the characteristic of the cryptographic 6025 material for the given cipher suite, and a pointer to a structure which receives the handles and IV which 6026 were generated. 6027 This mechanism contributes to the creation of two distinct keys and returns one IV (if an IV is requested 6028 by the caller) back to the caller. The keys are all given an object class of CKO_SECRET_KEY. 6029 The MACing key (server write MAC secret) is always given a type of CKK_GENERIC_SECRET. It is 6030 flagged as valid for signing, verification and derivation operations.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 170 of 278 6031 The other key (server write key) is typed according to information found in the template sent along with 6032 this mechanism during a C_DeriveKey function call. By default, it is flagged as valid for encryption, 6033 decryption, and derivation operations. 6034 An IV (server write IV) will be generated and returned if the ulIVSizeInBits field of the 6035 CK_WTLS_KEY_MAT_PARAMS field has a nonzero value. If it is generated, its length in bits will agree 6036 with the value in the ulIVSizeInBits field 6037 Both keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, 6038 CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template 6039 provided to C_DeriveKey may not specify values for any of these attributes that differ from those held by 6040 the base key. 6041 Note that the CK_WTLS_KEY_MAT_OUT structure pointed to by the CK_WTLS_KEY_MAT_PARAMS 6042 structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the two key 6043 handle fields in the CK_WTLS_KEY_MAT_OUT structure will be modified to hold handles to the newly- 6044 created keys; in addition, the buffer pointed to by the CK_WTLS_KEY_MAT_OUT structure’s pIV field will 6045 have the IV returned in them (if an IV is requested by the caller). Therefore, this field must point to a 6046 buffer with sufficient space to hold any IV that will be returned. 6047 This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. 6048 For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result of a 6049 successful completion. However, since the CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE 6050 mechanism returns all of its key handles in the CK_WTLS_KEY_MAT_OUT structure pointed to by the 6051 CK_WTLS_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey 6052 passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. 6053 If a call to C_DeriveKey with this mechanism fails, then none of the two keys will be created.
6054 2.41.8 Client key and MAC derivation 6055 Client key, MAC and IV derivation in WTLS, denoted CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE, 6056 is a mechanism used to derive the appropriate cryptographic keying material used by a cipher suite from 6057 the master secret key and random data. This mechanism returns the key handles for the keys generated 6058 in the process, as well as the IV created. 6059 It has a parameter, a CK_WTLS_KEY_MAT_PARAMS structure, which allows for the passing of the 6060 mechanism type of the digest mechanism to be used, random data, the characteristic of the cryptographic 6061 material for the given cipher suite, and a pointer to a structure which receives the handles and IV which 6062 were generated. 6063 This mechanism contributes to the creation of two distinct keys and returns one IV (if an IV is requested 6064 by the caller) back to the caller. The keys are all given an object class of CKO_SECRET_KEY. 6065 The MACing key (client write MAC secret) is always given a type of CKK_GENERIC_SECRET. It is 6066 flagged as valid for signing, verification and derivation operations. 6067 The other key (client write key) is typed according to information found in the template sent along with this 6068 mechanism during a C_DeriveKey function call. By default, it is flagged as valid for encryption, 6069 decryption, and derivation operations. 6070 An IV (client write IV) will be generated and returned if the ulIVSizeInBits field of the 6071 CK_WTLS_KEY_MAT_PARAMS field has a nonzero value. If it is generated, its length in bits will agree 6072 with the value in the ulIVSizeInBits field 6073 Both keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, 6074 CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template 6075 provided to C_DeriveKey may not specify values for any of these attributes that differ from those held by 6076 the base key. 6077 Note that the CK_WTLS_KEY_MAT_OUT structure pointed to by the CK_WTLS_KEY_MAT_PARAMS 6078 structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the two key 6079 handle fields in the CK_WTLS_KEY_MAT_OUT structure will be modified to hold handles to the newly- 6080 created keys; in addition, the buffer pointed to by the CK_WTLS_KEY_MAT_OUT structure’s pIV field will
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 171 of 278 6081 have the IV returned in them (if an IV is requested by the caller). Therefore, this field must point to a 6082 buffer with sufficient space to hold any IV that will be returned. 6083 This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. 6084 For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result of a 6085 successful completion. However, since the CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE mechanism 6086 returns all of its key handles in the CK_WTLS_KEY_MAT_OUT structure pointed to by the 6087 CK_WTLS_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey 6088 passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. 6089 If a call to C_DeriveKey with this mechanism fails, then none of the two keys will be created.
6090 2.42 SP 800-108 Key Derivation 6091 NIST SP800-108 defines three types of key derivation functions (KDF); a Counter Mode KDF, a 6092 Feedback Mode KDF and a Double Pipeline Mode KDF. 6093 This section defines a unique mechanism for each type of KDF. These mechanisms can be used to 6094 derive one or more symmetric keys from a single base symmetric key. 6095 The KDFs defined in SP800-108 are all built upon pseudo random functions (PRF). In general terms, the 6096 PRFs accepts two pieces of input; a base key and some input data. The base key is taken from the 6097 hBaseKey parameter to C_Derive. The input data is constructed from an iteration variable (internally 6098 defined by the KDF/PRF) and the data provided in the CK_SP800_108_PRF_DATA_PARAM array that is 6099 part of the mechanism parameter. 6100 Table 161, SP800-108 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR Key/ Unwrap Key Pair CKM_SP800_108_COUNTER_KDF CKM_SP800_108_FEEDBACK_KDF CKM_SP800_108_DOUBLE_PIPELINE_KDF 6101 6102 For these mechanisms, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO 6103 structure specify the minimum and maximum supported base key size in bits. Note, these mechanisms 6104 support multiple PRF types and key types; as such the values reported by ulMinKeySize and 6105 ulMaxKeySize specify the minimum and maximum supported base key size when all PRF and keys types 6106 are considered. For example, a Cryptoki implementation may support CKK_GENERIC_SECRET keys 6107 that can be as small as 8-bits in length and therefore ulMinKeySize could report 8-bits. However for an 6108 AES-CMAC PRF the base key must be of type CKK_AES and must be either 16-bytes, 24-bytes or 32- 6109 bytes in lengths and therefore the value reported by ulMinKeySize could be misleading. Depending on 6110 the PRF type selected, additional key size restrictions may apply.
6111 2.42.1 Definitions 6112 Mechanisms: 6113 CKM_SP800_108_COUNTER_KDF 6114 CKM_SP800_108_FEEDBACK_KDF 6115 CKM_SP800_108_DOUBLE_PIPELINE_KDF 6116 6117 Data Field Types:
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 172 of 278 6118 CK_SP800_108_ITERATION_VARIABLE 6119 CK_SP800_108_COUNTER 6120 CK_SP800_108_DKM_LENGTH 6121 CK_SP800_108_BYTE_ARRAY 6122 6123 DKM Length Methods: 6124 CK_SP800_108_DKM_LENGTH_SUM_OF_KEYS 6125 CK_SP800_108_DKM_LENGTH_SUM_OF_SEGMENTS
6126 2.42.2 Mechanism Parameters
6127 CK_SP800_108_PRF_TYPE
6128 The CK_SP800_108_PRF_TYPE field of the mechanism parameter is used to specify the type of PRF 6129 that is to be used. It is defined as follows: 6130 typedef CK_MECHANISM_TYPE CK_SP800_108_PRF_TYPE; 6131 The CK_SP800_108_PRF_TYPE field reuses the existing mechanisms definitions. The following table 6132 lists the supported PRF types: 6133 Table 162, SP800-108 Pseudo Random Functions Pseudo Random Function Identifiers CKM_SHA_1_HMAC CKM_SHA224_HMAC CKM_SHA256_HMAC CKM_SHA384_HMAC CKM_SHA512_HMAC CKM_SHA3_224_HMAC CKM_SHA3_256_HMAC CKM_SHA3_384_HMAC CKM_SHA3_512_HMAC CKM_3DES_CMAC CKM_AES_CMAC 6134
6135 CK_PRF_DATA_TYPE
6136 Each mechanism parameter contains an array of CK_PRF_DATA_PARAM structures. The 6137 CK_PRF_DATA_PARAM structure contains CK_PRF_DATA_TYPE field. The CK_PRF_DATA_TYPE 6138 field is used to identify the type of data identified by each CK_PRF_DATA_PARAM element in the array. 6139 Depending on the type of KDF used, some data field types are mandatory, some data field types are 6140 optional and some data field types are not allowed. These requirements are defined on a per-mechanism 6141 basis in the sections below. The CK_PRF_DATA_TYPE is defined as follows: 6142 typedef CK_ULONG CK_PRF_DATA_TYPE; 6143 The following table lists all of the supported data field types: 6144 Table 163, SP800-108 PRF Data Field Types
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 173 of 278 Data Field Identifier Description CK_SP800_108_ITERATION_VARIABLE Identifies the iteration variable defined internally by the KDF. CK_SP800_108_COUNTER Identifies an optional counter value represented as a binary string. Exact formatting of the counter value is defined by the CK_SP800_108_COUNTER_FORMAT structure. The value of the counter is defined by the KDF’s internal loop counter. CK_SP800_108_DKM_LENGTH Identifies the length in bits of the derived keying material (DKM) represented as a binary string. Exact formatting of the length value is defined by the CK_SP800_108_DKM_FORMAT structure. CK_SP800_108_BYTE_ARRAY Identifies a generic byte array of data. This data type can be used to provide “context”, “label”, “separator bytes” as well as any other type of encoding information required by the higher level protocol.
6145
6146 CK_PRF_DATA_PARAM
6147 CK_PRF_DATA_PARAM is used to define a segment of input for the PRF. Each mechanism parameter 6148 supports an array of CK_PRF_DATA_PARAM structures. The CK_PRF_DATA_PARAM is defined as 6149 follows: 6150 typedef struct CK_PRF_DATA_PARAM 6151 { 6152 CK_PRF_DATA_TYPE type; 6153 CK_VOID_PTR pValue; 6154 CK_ULONG ulValueLen; 6155 } CK_PRF_DATA_PARAM; 6156 6157 typedef CK_PRF_DATA_PARAM CK_PTR CK_PRF_DATA_PARAM_PTR 6158 6159 The fields of the CK_PRF_DATA_PARAM structure have the following meaning: 6160 type defines the type of data pointed to by pValue
6161 pValue pointer to the data defined by type
6162 ulValueLen size of the data pointed to by pValue
6163 If the type field of the CK_PRF_DATA_PARAM structure is set to 6164 CK_SP800_108_ITERATION_VARIABLE, then pValue must be set the appropriate value for the KDF’s 6165 iteration variable type. For the Counter Mode KDF, pValue must be assigned a valid 6166 CK_SP800_108_COUNTER_FORMAT_PTR and ulValueLen must be set to 6167 sizeof(CK_SP800_108_COUNTER_FORMAT). For all other KDF types, pValue must be set to 6168 NULL_PTR and ulValueLen must be set to 0. 6169 6170 If the type field of the CK_PRF_DATA_PARAM structure is set to CK_SP800_108_COUNTER, then 6171 pValue must be assigned a valid CK_SP800_108_COUNTER_FORMAT_PTR and ulValueLen must be 6172 set to sizeof(CK_SP800_108_COUNTER_FORMAT). 6173
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 174 of 278 6174 If the type field of the CK_PRF_DATA_PARAM structure is set to CK_SP800_108_DKM_LENGTH then 6175 pValue must be assigned a valid CK_SP800_108_DKM_FORMAT_PTR and ulValueLen must be set to 6176 sizeof(CK_SP800_108_DKM_FORMAT). 6177 6178 If the type field of the CK_PRF_DATA_PARAM structure is set to CK_SP800_108_BYTE_ARRAY, then 6179 pValue must be assigned a valid CK_BYTE_PTR value and ulValueLen must be set to a non-zero length.
6180 CK_SP800_108_COUNTER_FORMAT
6181 CK_SP800_108_COUNTER_FORMAT is used to define the encoding format for a counter value. The 6182 CK_SP800_108_COUNTER_FORMAT is defined as follows: 6183 typedef struct CK_SP800_108_COUNTER_FORMAT 6184 { 6185 CK_BBOOL bLittleEndian; 6186 CK_ULONG ulWidthInBits; 6187 } CK_SP800_108_COUNTER_FORMAT; 6188 6189 typedef CK_SP800_108_COUNTER_FORMAT CK_PTR 6190 CK_SP800_108_COUNTER_FORMAT_PTR 6191 6192 The fields of the CK_SP800_108_COUNTER_FORMAT structure have the following meaning: 6193 bLittleEndian defines if the counter should be represented in Big Endian or Little 6194 Endian format
6195 ulWidthInBits defines the number of bits used to represent the counter value
6196 CK_SP800_108_DKM_LENGTH_METHOD
6197 CK_SP800_108_DKM_LENGTH_METHOD is used to define how the DKM length value is calculated. 6198 The CK_SP800_108_DKM_LENGTH_METHOD type is defined as follows: 6199 typedef CK_ULONG CK_SP800_108_DKM_LENGTH_METHOD; 6200 The following table lists all of the supported DKM Length Methods: 6201 Table 164, SP800-108 DKM Length Methods DKM Length Method Identifier Description CK_SP800_108_DKM_LENGTH_SUM_OF_KEYS Specifies that the DKM length should be set to the sum of the length of all keys derived by this invocation of the KDF. CK_SP800_108_DKM_LENGTH_SUM_OF_SEGMENTS Specifies that the DKM length should be set to the sum of the length of all segments of output produced by the PRF by this invocation of the KDF. 6202
6203 CK_SP800_108_DKM_LENGTH_FORMAT
6204 CK_SP800_108_DKM_LENGTH_FORMAT is used to define the encoding format for the DKM length 6205 value. The CK_SP800_108_DKM_LENGTH_FORMAT is defined as follows: 6206 typedef struct CK_SP800_108_DKM_LENGTH_FORMAT 6207 {
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 175 of 278 6208 CK_SP800_108_DKM_LENGTH_METHOD dkmLengthMethod; 6209 CK_BBOOL bLittleEndian; 6210 CK_ULONG ulWidthInBits; 6211 } CK_SP800_108_DKM_LENGTH_FORMAT; 6212 6213 typedef CK_SP800_108_DKM_LENGTH_FORMAT CK_PTR 6214 CK_SP800_108_DKM_LENGTH_FORMAT_PTR 6215 6216 The fields of the CK_SP800_108_DKM_LENGTH_FORMAT structure have the following meaning: 6217 dkmLengthMethod defines the method used to calculate the DKM length value
6218 bLittleEndian defines if the DKM length value should be represented in Big 6219 Endian or Little Endian format
6220 ulWidthInBits defines the number of bits used to represent the DKM length value
6221 CK_DERIVED_KEY
6222 CK_DERIVED_KEY is used to define an additional key to be derived as well as provide a 6223 CK_OBJECT_HANDLE_PTR to receive the handle for the derived keys. The CK_DERIVED_KEY is 6224 defined as follows: 6225 typedef struct CK_DERIVED_KEY 6226 { 6227 CK_ATTRIBUTE_PTR pTemplate; 6228 CK_ULONG ulAttributeCount; 6229 CK_OBJECT_HANDLE_PTR phKey; 6230 } CK_DERIVED_KEY; 6231 6232 typedef CK_DERIVED_KEY CK_PTR CK_DERIVED_KEY_PTR 6233 6234 The fields of the CK_DERIVED_KEY structure have the following meaning: 6235 pTemplate pointer to a template that defines a key to derive
6236 ulAttributeCount number of attributes in the template pointed to by pTemplate
6237 phKey pointer to receive the handle for a derived key
6238 CK_SP800_108_KDF_PARAMS, CK_SP800_108_KDF_PARAMS_PTR
6239 CK_SP800_108_KDF_PARAMS is a structure that provides the parameters for the 6240 CKM_SP800_108_COUNTER_KDF and CKM_SP800_108_DOUBLE_PIPELINE_KDF mechanisms. 6241 6242 typedef struct CK_SP800_108_KDF_PARAMS 6243 { 6244 CK_PRF_TYPE prfType; 6245 CK_ULONG ulNumberOfDataParams; 6246 CK_PRF_DATA_PARAM_PTR pDataParams; 6247 CK_ULONG ulAdditionalDerivedKeys; 6248 CK_DERIVED_KEY pAdditionalDerivedKeys; 6249 } CK_SP800_108_KDF_PARAMS;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 176 of 278 6250 6251 typedef CK_SP800_108_KDF_PARAMS CK_PTR 6252 CK_SP800_108_KDF_PARAMS_PTR; 6253 6254 The fields of the CK_SP800_108_KDF_PARAMS structure have the following meaning: 6255 prfType type of PRF
6256 ulNumberOfDataParams number of elements in the array pointed to by pDataParams
6257 pDataParams an array of CK_PRF_DATA_PARAM structures. The array defines 6258 input parameters that are used to construct the “data” input to the 6259 PRF.
6260 ulAdditionalDerivedKeys number of additional keys that will be derived and the number of 6261 elements in the array pointed to by pAdditionalDerivedKeys. If 6262 pAdditionalDerivedKeys is set to NULL_PTR, this parameter must 6263 be set to 0.
6264 pAdditionalDerivedKeys an array of CK_DERIVED_KEY structures. If 6265 ulAdditionalDerivedKeys is set to 0, this parameter must be set to 6266 NULL_PTR
6267 CK_SP800_108_FEEDBACK_KDF_PARAMS, 6268 CK_SP800_108_FEEDBACK_KDF_PARAMS_PTR
6269 The CK_SP800_108_FEEDBACK_KDF_PARAMS structure provides the parameters for the 6270 CKM_SP800_108_FEEDBACK_KDF mechanism. It is defined as follows: 6271 typedef struct CK_SP800_108_FEEDBACK_KDF_PARAMS 6272 { 6273 CK_PRF_TYPE prfType; 6274 CK_ULONG ulNumberOfDataParams; 6275 CK_PRF_DATA_PARAM_PTR pDataParams; 6276 CK_ULONG ulIVLen; 6277 CK_BYTE_PTR pIV; 6278 CK_ULONG ulAdditionalDerivedKeys; 6279 CK_DERIVED_KEY pAdditionalDerivedKeys; 6280 } CK_SP800_108_FEEDBACK_KDF_PARAMS; 6281 6282 typedef CK_SP800_108_FEEDBACK_KDF_PARAMS CK_PTR 6283 CK_SP800_108_FEEDBACK_KDF_PARAMS_PTR; 6284 6285 The fields of the CK_SP800_108_FEEDBACK_KDF_PARAMS structure have the following meaning: 6286 prfType type of PRF
6287 ulNumberOfDataParams number of elements in the array pointed to by pDataParams
6288 pDataParams an array of CK_PRF_DATA_PARAM structures. The array defines 6289 input parameters that are used to construct the “data” input to the 6290 PRF.
6291 ulIVLen the length in bytes of the IV. If pIV is set to NULL_PTR, this 6292 parameter must be set to 0. pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 177 of 278 6293 pIV an array of bytes to be used as the IV for the feedback mode KDF. 6294 This parameter is optional and can be set to NULL_PTR. If ulIVLen 6295 is set to 0, this parameter must be set to NULL_PTR.
6296 ulAdditionalDerivedKeys number of additional keys that will be derived and the number of 6297 elements in the array pointed to by pAdditionalDerivedKeys. If 6298 pAdditionalDerivedKeys is set to NULL_PTR, this parameter must 6299 be set to 0.
6300 pAdditionalDerivedKeys an array of CK_DERIVED_KEYS structures. If 6301 ulAdditionalDerivedKeys is set to 0, this parameter must be set to 6302 NULL_PTR.
6303 2.42.3 Counter Mode KDF 6304 The SP800-108 Counter Mode KDF mechanism, denoted CKM_SP800_108_COUNTER_KDF, 6305 represents the KDF defined SP800-108 section 5.1. CKM_SP800_108_COUNTER_KDF is a 6306 mechanism for deriving one or more symmetric keys from a symmetric base key. 6307 It has a parameter, a CK_SP800_108_KDF_PARAMS structure. 6308 The following table lists the data field types that are supported for this KDF type and their meaning: 6309 Table 165, Counter Mode data field requirements Data Field Identifier Description CK_SP800_108_ITERATION_VARIABLE This data field type is mandatory. This data field type identifies the location of the iteration variable in the constructed PRF input data. The iteration variable for this KDF type is a counter. Exact formatting of the counter value is defined by the CK_SP800_108_COUNTER_FORMAT structure. CK_SP800_108_COUNTER This data field type is invalid for this KDF type. CK_SP800_108_DKM_LENGTH This data field type is optional. This data field type identifies the location of the DKM length in the constructed PRF input data. Exact formatting of the DKM length is defined by the CK_SP800_108_DKM_LENGTH_FORMAT structure. If specified, only one instance of this type may be specified. CK_SP800_108_BYTE_ARRAY This data field type is optional. This data field type identifies the location and value of a byte array of data in the constructed PRF input data. This standard does not restrict the number of instances of this data type.
6310 6311 SP800-108 limits the amount of derived keying material that can be produced by a Counter Mode KDF by 6312 limiting the internal loop counter to (2r−1), where “r” is the number of bits used to represent the counter. 6313 Therefore the maximum number of bits that can be produced is (2r−1)h, where “h” is the length in bits of 6314 the output of the selected PRF.
6315 2.42.4 Feedback Mode KDF 6316 The SP800-108 Feedback Mode KDF mechanism, denoted CKM_SP800_108_FEEDBACK_KDF, 6317 represents the KDF defined SP800-108 section 5.2. CKM_SP800_108_FEEDBACK_KDF is a 6318 mechanism for deriving one or more symmetric keys from a symmetric base key. pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 178 of 278 6319 It has a parameter, a CK_SP800_108_FEEDBACK_KDF_PARAMS structure. 6320 The following table lists the data field types that are supported for this KDF type and their meaning: 6321 Table 166, Feedback Mode data field requirements Data Field Identifier Description CK_SP800_108_ITERATION_VARIABLE This data field type is mandatory. This data field type identifies the location of the iteration variable in the constructed PRF input data. The iteration variable is defined as K(i-1) in section 5.2 of SP800-108. The size, format and value of this data input is defined by the internal KDF structure and PRF output. Exact formatting of the counter value is defined by the CK_SP800_108_COUNTER_FORMAT structure. CK_ SP800_108_COUNTER This data field type is optional. This data field type identifies the location of the counter in the constructed PRF input data. Exact formatting of the counter value is defined by the CK_SP800_108_COUNTER_FORMAT structure. If specified, only one instance of this type may be specified. CK_ SP800_108_DKM_LENGTH This data field type is optional. This data field type identifies the location of the DKM length in the constructed PRF input data. Exact formatting of the DKM length is defined by the CK_SP800_108_DKM_LENGTH_FORMAT structure. If specified, only one instance of this type may be specified. CK_ SP800_108_BYTE_ARRAY This data field type is optional. This data field type identifies the location and value of a byte array of data in the constructed PRF input data. This standard does not restrict the number of instances of this data type.
6322 6323 SP800-108 limits the amount of derived keying material that can be produced by a Feedback Mode KDF 6324 by limiting the internal loop counter to (232−1). Therefore the maximum number of bits that can be 6325 produced is (232−1)h, where “h” is the length in bits of the output of the selected PRF.
6326 2.42.5 Double Pipeline Mode KDF 6327 The SP800-108 Double Pipeline Mode KDF mechanism, denoted 6328 CKM_SP800_108_DOUBLE_PIPELINE_KDF, represents the KDF defined SP800-108 section 5.3. 6329 CKM_SP800_108_DOUBLE_PIPELINE_KDF is a mechanism for deriving one or more symmetric keys 6330 from a symmetric base key. 6331 It has a parameter, a CK_SP800_108_KDF_PARAMS structure. 6332 The following table lists the data field types that are supported for this KDF type and their meaning: 6333 Table 167, Double Pipeline Mode data field requirements Data Field Identifier Description CK_SP800_108_ITERATION_VARIABLE This data field type is mandatory.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 179 of 278 This data field type identifies the location of the iteration variable in the constructed PRF input data. The iteration variable is defined as A(i) in section 5.3 of SP800-108. The size, format and value of this data input is defined by the internal KDF structure and PRF output. Exact formatting of the counter value is defined by the CK_SP800_108_COUNTER_FORMAT structure. CK_ SP800_108_COUNTER This data field type is optional. This data field type identifies the location of the counter in the constructed PRF input data. Exact formatting of the counter value is defined by the CK_SP800_108_COUNTER_FORMAT structure. If specified, only one instance of this type may be specified. CK_ SP800_108_DKM_LENGTH This data field type is optional. This data field type identifies the location of the DKM length in the constructed PRF input data. Exact formatting of the DKM length is defined by the CK_SP800_108_DKM_LENGTH_FORMAT structure. If specified, only one instance of this type may be specified. CK_ SP800_108_BYTE_ARRAY This data field type is optional. This data field type identifies the location and value of a byte array of data in the constructed PRF input data. This standard does not restrict the number of instances of this data type.
6334 6335 SP800-108 limits the amount of derived keying material that can be produced by a Double-Pipeline Mode 6336 KDF by limiting the internal loop counter to (232−1). Therefore the maximum number of bits that can be 6337 produced is (232−1)h, where “h” is the length in bits of the output of the selected PRF. 6338 The Double Pipeline KDF requires an internal IV value. The IV is constructed using the same method 6339 used to construct the PRF input data; the data/values identified by the array of CK_PRF_DATA_PARAM 6340 structures are concatenated in to a byte array that is used as the IV. As shown in SP800-108 section 5.3, 6341 the CK_SP800_108_ITERATION_VARIABLE and CK_SP800_108_COUNTER data field types are not 6342 included in IV construction process. All other data field types are included in the construction process.
6343 2.42.6 Deriving Additional Keys 6344 The KDFs defined in this section can be used to derive more than one symmetric key from the base key. 6345 The C_Derive function accepts one CK_ATTRIBUTE_PTR to define a single derived key and one 6346 CK_OBJECT_HANDLE_PTR to receive the handle for the derived key. 6347 To derive additional keys, the mechanism parameter structure can be filled in with one or more 6348 CK_DERIVED_KEY structures. Each structure contains a CK_ATTRIBUTE_PTR to define a derived key 6349 and a CK_OBJECT_HANDLE_PTR to receive the handle for the additional derived keys. The key 6350 defined by the C_Derive function parameters is always derived before the keys defined by the 6351 CK_DERIVED_KEY array that is part of the mechanism parameter. The additional keys that are defined 6352 by the CK_DERIVED_KEY array are derived in the order they are defined in the array. That is to say that 6353 the derived keying material produced by the KDF is processed from left to right, and bytes are assigned 6354 first to the key defined by the C_Derive function parameters, and then bytes are assigned to the keys that 6355 are defined by the CK_DERIVED_KEY array in the order they are defined in the array.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 180 of 278 6356 Each internal iteration of a KDF produces a unique segment of PRF output. Sometimes, a single iteration 6357 will produce enough keying material for the key being derived. Other times, additional internal iterations 6358 are performed to produce multiple segments which are concatenated together to produce enough keying 6359 material for the derived key(s). 6360 When deriving multiple keys, no key can be created using part of a segment that was used for another 6361 key. All keys must be created from disjoint segments. For example, if the parameters are defined such 6362 that a 48-byte key (defined by the C_Derive function parameters) and a 16-byte key (defined by the 6363 content of CK_DERIVED_KEY) are to be derived using CKM_SHA256_HMAC as a PRF, three internal 6364 iterations of the KDF will be performed and three segments of PRF output will be produced. The first 6365 segment and half of the second segment will be used to create the 48-byte key and the third segment will 6366 be used to create the 16-byte key.
3 KDF Segments of Output: 32-byte segment 32-byte segment 32-byte segment
2 Derived Keys: 48-byte key unused 16-byte key unused 6367 6368 6369 In the above example, if the CK_ SP800_108_DKM_LENGTH data field type is specified with method 6370 CK_SP800_108_DKM_LENGTH_SUM_OF_KEYS, then the DKM length value will be 512 bits. If the 6371 CK_ SP800_108_DKM_LENGTH data field type is specified with method 6372 CK_SP800_108_DKM_LENGTH_SUM_OF_SEGMENTS, then the DKM length value will be 768 bits. 6373 When deriving multiple keys, if any of the keys cannot be derived for any reason, none of the keys shall 6374 be derived. If the failure was caused by the content of a specific key’s template (ie the template defined 6375 by the content of pTemplate), the corresponding phKey value will be set to CK_HANDLE_INVALID to 6376 identify the offending template.
6377 2.42.7 Key Derivation Attribute Rules 6378 The CKM_SP800_108_COUNTER_KDF, CKM_SP800_108_FEEDBACK_KDF and 6379 CKM_SP800_108_DOUBLE_PIPELINE_KDF mechanisms have the following rules about key sensitivity 6380 and extractability: 6381 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key(s) can 6382 both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on 6383 some default value. 6384 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 6385 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 6386 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 6387 CKA_SENSITIVE attribute. 6388 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 6389 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 6390 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 6391 value from its CKA_EXTRACTABLE attribute.
6392 2.42.8 Constructing PRF Input Data 6393 SP800-108 defines the PRF input data for each KDF at a high level using terms like “label”, “context”, 6394 “separator”, “counter”…etc. The value, formatting and order of the input data is not strictly defined by 6395 SP800-108, instead it is described as being defined by the “encoding scheme”. 6396 To support any encoding scheme, these mechanisms construct the PRF input data from from the array of 6397 CK_PRF_DATA_PARAM structures in the mechanism parameter. All of the values defined by the 6398 CK_PRF_DATA_PARAM array are concatenated in the order they are defined and passed in to the PRF 6399 as the data parameter.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 181 of 278 6400 2.42.8.1 Sample Counter Mode KDF 6401 SP800-108 section 5.1 outlines a sample Counter Mode KDF which defines the following PRF input: 6402 PRF (KI, [i]2 || Label || 0x00 || Context || [L]2) 6403 Section 5.1 does not define the number of bits used to represent the counter (the “r” value) or the DKM 6404 length (the “L” value), so 16-bits is assumed for both cases. The following sample code shows how to 6405 define this PRF input data using an array of CK_PRF_DATA_PARAM structures. 6406 #define DIM(a) (sizeof((a))/sizeof((a)[0])) 6407 6408 CK_OBJECT_HANDLE hBaseKey; 6409 CK_OBJECT_HANDLE hDerivedKey; 6410 CK_ATTRIBUTE derivedKeyTemplate = { … }; 6411 6412 CK_BYTE baLabel[] = {0xde, 0xad, 0xbe , 0xef}; 6413 CK_ULONG ulLabelLen = sizeof(baLabel); 6414 CK_BYTE baContext[] = {0xfe, 0xed, 0xbe , 0xef}}; 6415 CK_ULONG ulContextLen = sizeof(baContext); 6416 6417 CK_SP800_108_COUNTER_FORMAT counterFormat = { 0, 16}; 6418 CK_SP800_108_DKM_FORMAT dkmFormat = {CK_SP800_108_SUM_OF_KEYS, 0, 16}; 6419 6420 CK_PRF_DATA_PARAM dataParams[] = 6421 { 6422 { CK_SP800_108_ITERATION_VARIABLE, 6423 &counterFormat, sizeof(counterFormat) }, 6424 { CK_SP800_108_BYTE_ARRAY, baLabel, ulLabelLen }, 6425 { CK_SP800_108_BYTE_ARRAY, {0x00}, 1 }, 6426 { CK_SP800_108_BYTE_ARRAY, baContext, ulContextLen }, 6427 { CK_SP800_108_DKM_LENGTH, dkmFormat, sizeof(dkmFormat) } 6428 }; 6429 6430 CK_SP800_108_KDF_PARAMS kdfParams = 6431 { 6432 CK_PRF_AES_CMAC, 6433 DIM(dataParams), 6434 &dataParams, 6435 0, /* no addition derived keys */ 6436 NULL /* no addition derived keys */ 6437 }; 6438 6439 CK_MECHANISM = mechanism 6440 { 6441 CKM_FLEXIBLE_KDF, 6442 &kdfParams, 6443 sizeof(kdfParams) 6444 }; 6445 6446 hBaseKey = GetBaseKeyHandle(.....); 6447 6448 rv = C_DeriveKey( 6449 hSession, 6450 &mechanism, 6451 hBaseKey, 6452 &derivedKeyTemplate, 6453 DIM(derivedKeyTemplate),
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 182 of 278 6454 &hDerivedKey); 6455
6456 2.42.8.2 Sample SCP03 Counter Mode KDF 6457 The SCP03 standard defines a variation of a counter mode KDF which defines the following PRF input: 6458 PRF (KI, Label || 0x00 || [L]2 || [i]2 || Context) 6459 SCP03 defines the number of bits used to represent the counter (the “r” value) and number of bits used to 6460 represent the DKM length (the “L” value) as 16-bits. The following sample code shows how to define this 6461 PRF input data using an array of CK_PRF_DATA_PARAM structures. 6462 #define DIM(a) (sizeof((a))/sizeof((a)[0])) 6463 6464 CK_OBJECT_HANDLE hBaseKey; 6465 CK_OBJECT_HANDLE hDerivedKey; 6466 CK_ATTRIBUTE derivedKeyTemplate = { … }; 6467 6468 CK_BYTE baLabel[] = {0xde, 0xad, 0xbe , 0xef}; 6469 CK_ULONG ulLabelLen = sizeof(baLabel); 6470 CK_BYTE baContext[] = {0xfe, 0xed, 0xbe , 0xef}}; 6471 CK_ULONG ulContextLen = sizeof(baContext); 6472 6473 CK_SP800_108_COUNTER_FORMAT counterFormat = { 0, 16}; 6474 CK_SP800_108_DKM_FORMAT dkmFormat = {CK_SP800_108_SUM_OF_KEYS, 0, 16}; 6475 6476 CK_PRF_DATA_PARAM dataParams[] = 6477 { 6478 { CK_SP800_108_BYTE_ARRAY, baLabel, ulLabelLen }, 6479 { CK_SP800_108_BYTE_ARRAY, {0x00}, 1 }, 6480 { CK_SP800_108_DKM_LENGTH, dkmFormat, sizeof(dkmFormat) }, 6481 { CK_SP800_108_ITERATION_VARIABLE, 6482 &counterFormat, sizeof(counterFormat) }, 6483 { CK_SP800_108_BYTE_ARRAY, baContext, ulContextLen } 6484 }; 6485 6486 CK_SP800_108_KDF_PARAMS kdfParams = 6487 { 6488 CK_PRF_AES_CMAC, 6489 DIM(dataParams), 6490 &dataParams, 6491 0, /* no addition derived keys */ 6492 NULL /* no addition derived keys */ 6493 }; 6494 6495 CK_MECHANISM = mechanism 6496 { 6497 CKM_FLEXIBLE_KDF, 6498 &kdfParams, 6499 sizeof(kdfParams) 6500 }; 6501 6502 hBaseKey = GetBaseKeyHandle(.....); 6503 6504 rv = C_DeriveKey( 6505 hSession, 6506 &mechanism,
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 183 of 278 6507 hBaseKey, 6508 &derivedKeyTemplate, 6509 DIM(derivedKeyTemplate), 6510 &hDerivedKey); 6511
6512 2.42.8.3 Sample Feedback Mode KDF 6513 SP800-108 section 5.2 outlines a sample Feedback Mode KDF which defines the following PRF input: 6514 PRF (KI, K(i-1) {|| [i]2 }|| Label || 0x00 || Context || [L]2)
6515 Section 5.2 does not define the number of bits used to represent the counter (the “r” value) or the DKM 6516 length (the “L” value), so 16-bits is assumed for both cases. The counter is defined as being optional and 6517 is included in this example. The following sample code shows how to define this PRF input data using an 6518 array of CK_PRF_DATA_PARAM structures. 6519 #define DIM(a) (sizeof((a))/sizeof((a)[0])) 6520 6521 CK_OBJECT_HANDLE hBaseKey; 6522 CK_OBJECT_HANDLE hDerivedKey; 6523 CK_ATTRIBUTE derivedKeyTemplate = { … }; 6524 6525 CK_BYTE baFeedbackIV[] = {0x01, 0x02, 0x03 , 0x04}; 6526 CK_ULONG ulFeedbackIVLen = sizeof(baFeedbackIV); 6527 CK_BYTE baLabel[] = {0xde, 0xad, 0xbe , 0xef}; 6528 CK_ULONG ulLabelLen = sizeof(baLabel); 6529 CK_BYTE baContext[] = {0xfe, 0xed, 0xbe , 0xef}}; 6530 CK_ULONG ulContextLen = sizeof(baContext); 6531 6532 CK_SP800_108_COUNTER_FORMAT counterFormat = { 0, 16}; 6533 CK_SP800_108_DKM_FORMAT dkmFormat = {CK_SP800_108_SUM_OF_KEYS, 0, 16}; 6534 6535 CK_PRF_DATA_PARAM dataParams[] = 6536 { 6537 { CK_SP800_108_ITERATION_VARIABLE, 6538 &counterFormat, sizeof(counterFormat) }, 6539 { CK_SP800_108_BYTE_ARRAY, baLabel, ulLabelLen }, 6540 { CK_SP800_108_BYTE_ARRAY, {0x00}, 1 }, 6541 { CK_SP800_108_BYTE_ARRAY, baContext, ulContextLen }, 6542 { CK_SP800_108_DKM_LENGTH, dkmFormat, sizeof(dkmFormat) } 6543 }; 6544 6545 CK_SP800_108_FEEDBACK_KDF_PARAMS kdfParams = 6546 { 6547 CK_PRF_AES_CMAC, 6548 DIM(dataParams), 6549 &dataParams, 6550 ulFeedbackIVLen, 6551 pFeedbackIV, 6552 0, /* no addition derived keys */ 6553 NULL /* no addition derived keys */ 6554 }; 6555 6556 CK_MECHANISM = mechanism 6557 { 6558 CKM_FLEXIBLE_KDF, 6559 &kdfParams,
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 184 of 278 6560 sizeof(kdfParams) 6561 }; 6562 6563 hBaseKey = GetBaseKeyHandle(.....); 6564 6565 rv = C_DeriveKey( 6566 hSession, 6567 &mechanism, 6568 hBaseKey, 6569 &derivedKeyTemplate, 6570 DIM(derivedKeyTemplate), 6571 &hDerivedKey); 6572
6573 2.42.8.4 Sample Double-Pipeline Mode KDF 6574 SP800-108 section 5.3 outlines a sample Double-Pipeline Mode KDF which defines the two following 6575 PRF inputs: 6576 PRF (KI, A(i-1)) 6577 PRF (KI, K(i-1) {|| [i]2 }|| Label || 0x00 || Context || [L]2)
6578 Section 5.3 does not define the number of bits used to represent the counter (the “r” value) or the DKM 6579 length (the “L” value), so 16-bits is assumed for both cases. The counter is defined as being optional so it 6580 is left out in this example. The following sample code shows how to define this PRF input data using an 6581 array of CK_PRF_DATA_PARAM structures. 6582 #define DIM(a) (sizeof((a))/sizeof((a)[0])) 6583 6584 CK_OBJECT_HANDLE hBaseKey; 6585 CK_OBJECT_HANDLE hDerivedKey; 6586 CK_ATTRIBUTE derivedKeyTemplate = { … }; 6587 6588 CK_BYTE baLabel[] = {0xde, 0xad, 0xbe , 0xef}; 6589 CK_ULONG ulLabelLen = sizeof(baLabel); 6590 CK_BYTE baContext[] = {0xfe, 0xed, 0xbe , 0xef}}; 6591 CK_ULONG ulContextLen = sizeof(baContext); 6592 6593 CK_SP800_108_DKM_FORMAT dkmFormat = {CK_SP800_108_SUM_OF_KEYS, 0, 16}; 6594 6595 CK_PRF_DATA_PARAM dataParams[] = 6596 { 6597 { CK_SP800_108_BYTE_ARRAY, baLabel, ulLabelLen }, 6598 { CK_SP800_108_BYTE_ARRAY, {0x00}, 1 }, 6599 { CK_SP800_108_BYTE_ARRAY, baContext, ulContextLen }, 6600 { CK_SP800_108_DKM_LENGTH, dkmFormat, sizeof(dkmFormat) } 6601 }; 6602 6603 CK_SP800_108_KDF_PARAMS kdfParams = 6604 { 6605 CK_PRF_AES_CMAC, 6606 DIM(dataParams), 6607 &dataParams, 6608 0, /* no addition derived keys */ 6609 NULL /* no addition derived keys */ 6610 }; 6611 6612 CK_MECHANISM = mechanism 6613 {
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 185 of 278 6614 CKM_FLEXIBLE_KDF, 6615 &kdfParams, 6616 sizeof(kdfParams) 6617 }; 6618 6619 hBaseKey = GetBaseKeyHandle(.....); 6620 6621 rv = C_DeriveKey( 6622 hSession, 6623 &mechanism, 6624 hBaseKey, 6625 &derivedKeyTemplate, 6626 DIM(derivedKeyTemplate), 6627 &hDerivedKey); 6628
6629 2.43 Miscellaneous simple key derivation mechanisms 6630 Table 168, Miscellaneous simple key derivation Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_CONCATENATE_BASE_AND_KEY CKM_CONCATENATE_BASE_AND_DATA CKM_CONCATENATE_DATA_AND_BASE CKM_XOR_BASE_AND_DATA CKM_EXTRACT_KEY_FROM_KEY
6631 2.43.1 Definitions 6632 Mechanisms: 6633 CKM_CONCATENATE_BASE_AND_DATA 6634 CKM_CONCATENATE_DATA_AND_BASE 6635 CKM_XOR_BASE_AND_DATA 6636 CKM_EXTRACT_KEY_FROM_KEY 6637 CKM_CONCATENATE_BASE_AND_KEY
6638 2.43.2 Parameters for miscellaneous simple key derivation mechanisms
6639 CK_KEY_DERIVATION_STRING_DATA; 6640 CK_KEY_DERIVATION_STRING_DATA_PTR
6641 CK_KEY_DERIVATION_STRING_DATA provides the parameters for the 6642 CKM_CONCATENATE_BASE_AND_DATA, CKM_CONCATENATE_DATA_AND_BASE, and 6643 CKM_XOR_BASE_AND_DATA mechanisms. It is defined as follows: 6644 typedef struct CK_KEY_DERIVATION_STRING_DATA { 6645 CK_BYTE_PTR pData; 6646 CK_ULONG ulLen;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 186 of 278 6647 } CK_KEY_DERIVATION_STRING_DATA; 6648 6649 The fields of the structure have the following meanings: 6650 pData pointer to the byte string
6651 ulLen length of the byte string
6652 CK_KEY_DERIVATION_STRING_DATA_PTR is a pointer to a 6653 CK_KEY_DERIVATION_STRING_DATA.
6654 CK_EXTRACT_PARAMS; CK_EXTRACT_PARAMS_PTR
6655 CK_EXTRACT_PARAMS provides the parameter to the CKM_EXTRACT_KEY_FROM_KEY 6656 mechanism. It specifies which bit of the base key should be used as the first bit of the derived key. It is 6657 defined as follows: 6658 typedef CK_ULONG CK_EXTRACT_PARAMS; 6659 6660 CK_EXTRACT_PARAMS_PTR is a pointer to a CK_EXTRACT_PARAMS.
6661 2.43.3 Concatenation of a base key and another key 6662 This mechanism, denoted CKM_CONCATENATE_BASE_AND_KEY, derives a secret key from the 6663 concatenation of two existing secret keys. The two keys are specified by handles; the values of the keys 6664 specified are concatenated together in a buffer. 6665 This mechanism takes a parameter, a CK_OBJECT_HANDLE. This handle produces the key value 6666 information which is appended to the end of the base key’s value information (the base key is the key 6667 whose handle is supplied as an argument to C_DeriveKey). 6668 For example, if the value of the base key is 0x01234567, and the value of the other key is 0x89ABCDEF, 6669 then the value of the derived key will be taken from a buffer containing the string 0x0123456789ABCDEF. 6670 If no length or key type is provided in the template, then the key produced by this mechanism will be a 6671 generic secret key. Its length will be equal to the sum of the lengths of the values of the two original 6672 keys. 6673 If no key type is provided in the template, but a length is, then the key produced by this mechanism 6674 will be a generic secret key of the specified length. 6675 If no length is provided in the template, but a key type is, then that key type must have a well-defined 6676 length. If it does, then the key produced by this mechanism will be of the type specified in the 6677 template. If it doesn’t, an error will be returned. 6678 If both a key type and a length are provided in the template, the length must be compatible with that 6679 key type. The key produced by this mechanism will be of the specified type and length. 6680 If a DES, DES2, DES3, or CDMF key is derived with this mechanism, the parity bits of the key will be set 6681 properly. 6682 If the requested type of key requires more bytes than are available by concatenating the two original keys’ 6683 values, an error is generated. 6684 This mechanism has the following rules about key sensitivity and extractability: 6685 If either of the two original keys has its CKA_SENSITIVE attribute set to CK_TRUE, so does the 6686 derived key. If not, then the derived key’s CKA_SENSITIVE attribute is set either from the supplied 6687 template or from a default value. 6688 Similarly, if either of the two original keys has its CKA_EXTRACTABLE attribute set to CK_FALSE, 6689 so does the derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either 6690 from the supplied template or from a default value.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 187 of 278 6691 The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if both of the 6692 original keys have their CKA_ALWAYS_SENSITIVE attributes set to CK_TRUE. 6693 Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 6694 both of the original keys have their CKA_NEVER_EXTRACTABLE attributes set to CK_TRUE.
6695 2.43.4 Concatenation of a base key and data 6696 This mechanism, denoted CKM_CONCATENATE_BASE_AND_DATA, derives a secret key by 6697 concatenating data onto the end of a specified secret key. 6698 This mechanism takes a parameter, a CK_KEY_DERIVATION_STRING_DATA structure, which 6699 specifies the length and value of the data which will be appended to the base key to derive another key. 6700 For example, if the value of the base key is 0x01234567, and the value of the data is 0x89ABCDEF, then 6701 the value of the derived key will be taken from a buffer containing the string 0x0123456789ABCDEF. 6702 If no length or key type is provided in the template, then the key produced by this mechanism will be a 6703 generic secret key. Its length will be equal to the sum of the lengths of the value of the original key 6704 and the data. 6705 If no key type is provided in the template, but a length is, then the key produced by this mechanism 6706 will be a generic secret key of the specified length. 6707 If no length is provided in the template, but a key type is, then that key type must have a well-defined 6708 length. If it does, then the key produced by this mechanism will be of the type specified in the 6709 template. If it doesn’t, an error will be returned. 6710 If both a key type and a length are provided in the template, the length must be compatible with that 6711 key type. The key produced by this mechanism will be of the specified type and length. 6712 If a DES, DES2, DES3, or CDMF key is derived with this mechanism, the parity bits of the key will be set 6713 properly. 6714 If the requested type of key requires more bytes than are available by concatenating the original key’s 6715 value and the data, an error is generated. 6716 This mechanism has the following rules about key sensitivity and extractability: 6717 If the base key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, 6718 then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from a 6719 default value. 6720 Similarly, if the base key has its CKA_EXTRACTABLE attribute set to CK_FALSE, so does the 6721 derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either from the 6722 supplied template or from a default value. 6723 The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the base 6724 key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE. 6725 Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 6726 the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
6727 2.43.5 Concatenation of data and a base key 6728 This mechanism, denoted CKM_CONCATENATE_DATA_AND_BASE, derives a secret key by 6729 prepending data to the start of a specified secret key. 6730 This mechanism takes a parameter, a CK_KEY_DERIVATION_STRING_DATA structure, which 6731 specifies the length and value of the data which will be prepended to the base key to derive another key. 6732 For example, if the value of the base key is 0x01234567, and the value of the data is 0x89ABCDEF, then 6733 the value of the derived key will be taken from a buffer containing the string 0x89ABCDEF01234567. 6734 If no length or key type is provided in the template, then the key produced by this mechanism will be a 6735 generic secret key. Its length will be equal to the sum of the lengths of the data and the value of the 6736 original key.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 188 of 278 6737 If no key type is provided in the template, but a length is, then the key produced by this mechanism 6738 will be a generic secret key of the specified length. 6739 If no length is provided in the template, but a key type is, then that key type must have a well-defined 6740 length. If it does, then the key produced by this mechanism will be of the type specified in the 6741 template. If it doesn’t, an error will be returned. 6742 If both a key type and a length are provided in the template, the length must be compatible with that 6743 key type. The key produced by this mechanism will be of the specified type and length. 6744 If a DES, DES2, DES3, or CDMF key is derived with this mechanism, the parity bits of the key will be set 6745 properly. 6746 If the requested type of key requires more bytes than are available by concatenating the data and the 6747 original key’s value, an error is generated. 6748 This mechanism has the following rules about key sensitivity and extractability: 6749 If the base key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, 6750 then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from a 6751 default value. 6752 Similarly, if the base key has its CKA_EXTRACTABLE attribute set to CK_FALSE, so does the 6753 derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either from the 6754 supplied template or from a default value. 6755 The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the base 6756 key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE. 6757 Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 6758 the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
6759 2.43.6 XORing of a key and data 6760 XORing key derivation, denoted CKM_XOR_BASE_AND_DATA, is a mechanism which provides the 6761 capability of deriving a secret key by performing a bit XORing of a key pointed to by a base key handle 6762 and some data. 6763 This mechanism takes a parameter, a CK_KEY_DERIVATION_STRING_DATA structure, which 6764 specifies the data with which to XOR the original key’s value. 6765 For example, if the value of the base key is 0x01234567, and the value of the data is 0x89ABCDEF, then 6766 the value of the derived key will be taken from a buffer containing the string 0x88888888. 6767 If no length or key type is provided in the template, then the key produced by this mechanism will be a 6768 generic secret key. Its length will be equal to the minimum of the lengths of the data and the value of 6769 the original key. 6770 If no key type is provided in the template, but a length is, then the key produced by this mechanism 6771 will be a generic secret key of the specified length. 6772 If no length is provided in the template, but a key type is, then that key type must have a well-defined 6773 length. If it does, then the key produced by this mechanism will be of the type specified in the 6774 template. If it doesn’t, an error will be returned. 6775 If both a key type and a length are provided in the template, the length must be compatible with that 6776 key type. The key produced by this mechanism will be of the specified type and length. 6777 If a DES, DES2, DES3, or CDMF key is derived with this mechanism, the parity bits of the key will be set 6778 properly. 6779 If the requested type of key requires more bytes than are available by taking the shorter of the data and 6780 the original key’s value, an error is generated. 6781 This mechanism has the following rules about key sensitivity and extractability: 6782 If the base key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, 6783 then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from a 6784 default value.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 189 of 278 6785 Similarly, if the base key has its CKA_EXTRACTABLE attribute set to CK_FALSE, so does the 6786 derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either from the 6787 supplied template or from a default value. 6788 The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the base 6789 key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE. 6790 Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 6791 the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
6792 2.43.7 Extraction of one key from another key 6793 Extraction of one key from another key, denoted CKM_EXTRACT_KEY_FROM_KEY, is a mechanism 6794 which provides the capability of creating one secret key from the bits of another secret key. 6795 This mechanism has a parameter, a CK_EXTRACT_PARAMS, which specifies which bit of the original 6796 key should be used as the first bit of the newly-derived key. 6797 We give an example of how this mechanism works. Suppose a token has a secret key with the 4-byte 6798 value 0x329F84A9. We will derive a 2-byte secret key from this key, starting at bit position 21 (i.e., the 6799 value of the parameter to the CKM_EXTRACT_KEY_FROM_KEY mechanism is 21). 6800 1. We write the key’s value in binary: 0011 0010 1001 1111 1000 0100 1010 1001. We regard this 6801 binary string as holding the 32 bits of the key, labeled as b0, b1, …, b31. 6802 2. We then extract 16 consecutive bits (i.e., 2 bytes) from this binary string, starting at bit b21. We 6803 obtain the binary string 1001 0101 0010 0110. 6804 3. The value of the new key is thus 0x9526. 6805 Note that when constructing the value of the derived key, it is permissible to wrap around the end of the 6806 binary string representing the original key’s value. 6807 If the original key used in this process is sensitive, then the derived key must also be sensitive for the 6808 derivation to succeed. 6809 If no length or key type is provided in the template, then an error will be returned. 6810 If no key type is provided in the template, but a length is, then the key produced by this mechanism 6811 will be a generic secret key of the specified length. 6812 If no length is provided in the template, but a key type is, then that key type must have a well-defined 6813 length. If it does, then the key produced by this mechanism will be of the type specified in the 6814 template. If it doesn’t, an error will be returned. 6815 If both a key type and a length are provided in the template, the length must be compatible with that 6816 key type. The key produced by this mechanism will be of the specified type and length. 6817 If a DES, DES2, DES3, or CDMF key is derived with this mechanism, the parity bits of the key will be set 6818 properly. 6819 If the requested type of key requires more bytes than the original key has, an error is generated. 6820 This mechanism has the following rules about key sensitivity and extractability: 6821 If the base key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, 6822 then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from a 6823 default value. 6824 Similarly, if the base key has its CKA_EXTRACTABLE attribute set to CK_FALSE, so does the 6825 derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either from the 6826 supplied template or from a default value. 6827 The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the base 6828 key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE. 6829 Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 6830 the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 190 of 278 6831 2.44 CMS 6832 Table 169, CMS Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_CMS_SIG
6833 2.44.1 Definitions 6834 Mechanisms: 6835 CKM_CMS_SIG
6836 2.44.2 CMS Signature Mechanism Objects 6837 These objects provide information relating to the CKM_CMS_SIG mechanism. CKM_CMS_SIG 6838 mechanism object attributes represent information about supported CMS signature attributes in the token. 6839 They are only present on tokens supporting the CKM_CMS_SIG mechanism, but must be present on 6840 those tokens. 6841 Table 170, CMS Signature Mechanism Object Attributes Attribute Data type Meaning CKA_REQUIRED_CMS_ATTRIBUTE Byte array Attributes the token always will include S in the set of CMS signed attributes CKA_DEFAULT_CMS_ATTRIBUTES Byte array Attributes the token will include in the set of CMS signed attributes in the absence of any attributes specified by the application CKA_SUPPORTED_CMS_ATTRIBUT Byte array Attributes the token may include in the ES set of CMS signed attributes upon request by the application
6842 The contents of each byte array will be a DER-encoded list of CMS Attributes with optional accompanying 6843 values. Any attributes in the list shall be identified with its object identifier, and any values shall be DER- 6844 encoded. The list of attributes is defined in ASN.1 as: 6845 Attributes ::= SET SIZE (1..MAX) OF Attribute 6846 Attribute ::= SEQUENCE { 6847 attrType OBJECT IDENTIFIER, 6848 attrValues SET OF ANY DEFINED BY OBJECT IDENTIFIER 6849 OPTIONAL 6850 } 6851 The client may not set any of the attributes.
6852 2.44.3 CMS mechanism parameters
6853 CK_CMS_SIG_PARAMS, CK_CMS_SIG_PARAMS_PTR 6854 CK_CMS_SIG_PARAMS is a structure that provides the parameters to the CKM_CMS_SIG mechanism. 6855 It is defined as follows: 6856 typedef struct CK_CMS_SIG_PARAMS {
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 191 of 278 6857 CK_OBJECT_HANDLE certificateHandle; 6858 CK_MECHANISM_PTR pSigningMechanism; 6859 CK_MECHANISM_PTR pDigestMechanism; 6860 CK_UTF8CHAR_PTR pContentType; 6861 CK_BYTE_PTR pRequestedAttributes; 6862 CK_ULONG ulRequestedAttributesLen; 6863 CK_BYTE_PTR pRequiredAttributes; 6864 CK_ULONG ulRequiredAttributesLen; 6865 } CK_CMS_SIG_PARAMS; 6866 6867 The fields of the structure have the following meanings: 6868 certificateHandle Object handle for a certificate associated with the signing key. The 6869 token may use information from this certificate to identify the signer 6870 in the SignerInfo result value. CertificateHandle may be NULL_PTR 6871 if the certificate is not available as a PKCS #11 object or if the 6872 calling application leaves the choice of certificate completely to the 6873 token.
6874 pSigningMechanism Mechanism to use when signing a constructed CMS 6875 SignedAttributes value. E.g. CKM_SHA1_RSA_PKCS.
6876 pDigestMechanism Mechanism to use when digesting the data. Value shall be 6877 NULL_PTR when the digest mechanism to use follows from the 6878 pSigningMechanism parameter.
6879 pContentType NULL-terminated string indicating complete MIME Content-type of 6880 message to be signed; or the value NULL_PTR if the message is a 6881 MIME object (which the token can parse to determine its MIME 6882 Content-type if required). Use the value “application/octet-stream“ if 6883 the MIME type for the message is unknown or undefined. Note that 6884 the pContentType string shall conform to the syntax specified in 6885 RFC 2045, i.e. any parameters needed for correct presentation of 6886 the content by the token (such as, for example, a non-default 6887 “charset”) must be present. The token must follow rules and 6888 procedures defined in RFC 2045 when presenting the content.
6889 pRequestedAttributes Pointer to DER-encoded list of CMS Attributes the caller requests to 6890 be included in the signed attributes. Token may freely ignore this list 6891 or modify any supplied values.
6892 ulRequestedAttributesLen Length in bytes of the value pointed to by pRequestedAttributes
6893 pRequiredAttributes Pointer to DER-encoded list of CMS Attributes (with accompanying 6894 values) required to be included in the resulting signed attributes. 6895 Token must not modify any supplied values. If the token does not 6896 support one or more of the attributes, or does not accept provided 6897 values, the signature operation will fail. The token will use its own 6898 default attributes when signing if both the pRequestedAttributes and 6899 pRequiredAttributes field are set to NULL_PTR.
6900 ulRequiredAttributesLen Length in bytes, of the value pointed to by pRequiredAttributes.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 192 of 278 6901 2.44.4 CMS signatures 6902 The CMS mechanism, denoted CKM_CMS_SIG, is a multi-purpose mechanism based on the structures 6903 defined in PKCS #7 and RFC 2630. It supports single- or multiple-part signatures with and without 6904 message recovery. The mechanism is intended for use with, e.g., PTDs (see MeT-PTD) or other capable 6905 tokens. The token will construct a CMS SignedAttributes value and compute a signature on this value. 6906 The content of the SignedAttributes value is decided by the token, however the caller can suggest some 6907 attributes in the parameter pRequestedAttributes. The caller can also require some attributes to be 6908 present through the parameters pRequiredAttributes. The signature is computed in accordance with the 6909 parameter pSigningMechanism. 6910 When this mechanism is used in successful calls to C_Sign or C_SignFinal, the pSignature return value 6911 will point to a DER-encoded value of type SignerInfo. SignerInfo is defined in ASN.1 as follows (for a 6912 complete definition of all fields and types, see RFC 2630): 6913 SignerInfo ::= SEQUENCE { 6914 version CMSVersion, 6915 sid SignerIdentifier, 6916 digestAlgorithm DigestAlgorithmIdentifier, 6917 signedAttrs [0] IMPLICIT SignedAttributes OPTIONAL, 6918 signatureAlgorithm SignatureAlgorithmIdentifier, 6919 signature SignatureValue, 6920 unsignedAttrs [1] IMPLICIT UnsignedAttributes 6921 OPTIONAL } 6922 The certificateHandle parameter, when set, helps the token populate the sid field of the SignerInfo value. 6923 If certificateHandle is NULL_PTR the choice of a suitable certificate reference in the SignerInfo result 6924 value is left to the token (the token could, e.g., interact with the user). 6925 This mechanism shall not be used in calls to C_Verify or C_VerifyFinal (use the pSigningMechanism 6926 mechanism instead). 6927 For the pRequiredAttributes field, the token may have to interact with the user to find out whether to 6928 accept a proposed value or not. The token should never accept any proposed attribute values without 6929 some kind of confirmation from its owner (but this could be through, e.g., configuration or policy settings 6930 and not direct interaction). If a user rejects proposed values, or the signature request as such, the value 6931 CKR_FUNCTION_REJECTED shall be returned. 6932 When possible, applications should use the CKM_CMS_SIG mechanism when generating CMS- 6933 compatible signatures rather than lower-level mechanisms such as CKM_SHA1_RSA_PKCS. This is 6934 especially true when the signatures are to be made on content that the token is able to present to a user. 6935 Exceptions may include those cases where the token does not support a particular signing attribute. Note 6936 however that the token may refuse usage of a particular signature key unless the content to be signed is 6937 known (i.e. the CKM_CMS_SIG mechanism is used). 6938 When a token does not have presentation capabilities, the PKCS #11-aware application may avoid 6939 sending the whole message to the token by electing to use a suitable signature mechanism (e.g. 6940 CKM_RSA_PKCS) as the pSigningMechanism value in the CK_CMS_SIG_PARAMS structure, and 6941 digesting the message itself before passing it to the token. 6942 PKCS #11-aware applications making use of tokens with presentation capabilities, should attempt to 6943 provide messages to be signed by the token in a format possible for the token to present to the user. 6944 Tokens that receive multipart MIME-messages for which only certain parts are possible to present may 6945 fail the signature operation with a return value of CKR_DATA_INVALID, but may also choose to add a 6946 signing attribute indicating which parts of the message were possible to present.
6947 2.45 Blowfish 6948 Blowfish, a secret-key block cipher. It is a Feistel network, iterating a simple encryption function 16 times. 6949 The block size is 64 bits, and the key can be any length up to 448 bits. Although there is a complex
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 193 of 278 6950 initialization phase required before any encryption can take place, the actual encryption of data is very 6951 efficient on large microprocessors. 6952 6953 Table 171, Blowfish Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_BLOWFISH_CBC ✓ ✓ CKM_BLOWFISH_CBC_PAD ✓ ✓
6954 2.45.1 Definitions 6955 This section defines the key type “CKK_BLOWFISH” for type CK_KEY_TYPE as used in the 6956 CKA_KEY_TYPE attribute of key objects. 6957 Mechanisms: 6958 CKM_BLOWFISH_KEY_GEN 6959 CKM_BLOWFISH_CBC 6960 CKM_BLOWFISH_CBC_PAD
6961 2.45.2 BLOWFISH secret key objects 6962 Blowfish secret key objects (object class CKO_SECRET_KEY, key type CKK_BLOWFISH) hold Blowfish 6963 keys. The following table defines the Blowfish secret key object attributes, in addition to the common 6964 attributes defined for this object class: 6965 Table 172, BLOWFISH Secret Key Object Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key value the key can be any length up to 448 bits. Bit length restricted to a byte array. CKA_VALUE_LEN2,3 CK_ULONG Length in bytes of key value 6966 - Refer to [PKCS11-Base] table 11 for footnotes 6967 The following is a sample template for creating an Blowfish secret key object: 6968 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 6969 CK_KEY_TYPE keyType = CKK_BLOWFISH; 6970 CK_UTF8CHAR label[] = “A blowfish secret key object”; 6971 CK_BYTE value[16] = {...}; 6972 CK_BBOOL true = CK_TRUE; 6973 CK_ATTRIBUTE template[] = { 6974 {CKA_CLASS, &class, sizeof(class)}, 6975 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 6976 {CKA_TOKEN, &true, sizeof(true)}, 6977 {CKA_LABEL, label, sizeof(label)-1}, 6978 {CKA_ENCRYPT, &true, sizeof(true)}, 6979 {CKA_VALUE, value, sizeof(value)}
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 194 of 278 6980 };
6981 2.45.3 Blowfish key generation 6982 The Blowfish key generation mechanism, denoted CKM_BLOWFISH_KEY_GEN, is a key generation 6983 mechanism Blowfish. 6984 It does not have a parameter. 6985 The mechanism generates Blowfish keys with a particular length, as specified in the CKA_VALUE_LEN 6986 attribute of the template for the key. 6987 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 6988 key. Other attributes supported by the key type (specifically, the flags indicating which functions the key 6989 supports) may be specified in the template for the key, or else are assigned default initial values. 6990 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 6991 specify the supported range of key sizes in bytes.
6992 2.45.4 Blowfish-CBC 6993 Blowfish-CBC, denoted CKM_BLOWFISH_CBC, is a mechanism for single- and multiple-part encryption 6994 and decryption; key wrapping; and key unwrapping. 6995 It has a parameter, a 8-byte initialization vector. 6996 This mechanism can wrap and unwrap any secret key. For wrapping, the mechanism encrypts the value 6997 of the CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size 6998 minus one null bytes so that the resulting length is a multiple of the block size. The output data is the 6999 same length as the padded input data. It does not wrap the key type, key length, or any other information 7000 about the key; the application must convey these separately. 7001 For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the 7002 CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the 7003 CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the CKA_VALUE 7004 attribute of the new key; other attributes required by the key type must be specified in the template. 7005 Constraints on key types and the length of data are summarized in the following table:
7006 Table 173, BLOWFISH-CBC: Key and Data Length Function Key type Input Length Output Length C_Encrypt BLOWFISH Multiple of block size Same as input length C_Decrypt BLOWFISH Multiple of block size Same as input length C_WrapKey BLOWFISH Any Input length rounded up to multiple of the block size C_UnwrapKey BLOWFISH Multiple of block size Determined by type of key being unwrapped or CKA_VALUE_LEN 7007 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7008 specify the supported range of BLOWFISH key sizes, in bytes.
7009 2.45.5 Blowfish-CBC with PKCS padding 7010 Blowfish-CBC-PAD, denoted CKM_BLOWFISH_CBC_PAD, is a mechanism for single- and multiple-part 7011 encryption and decryption, key wrapping and key unwrapping, cipher-block chaining mode and the block 7012 cipher padding method detailed in PKCS #7. 7013 It has a parameter, a 8-byte initialization vector. 7014 The PKCS padding in this mechanism allows the length of the plaintext value to be recovered from the 7015 ciphertext value. Therefore, when unwrapping keys with this mechanism, no value should be specified for 7016 the CKA_VALUE_LEN attribute.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 195 of 278 7017 The entries in the table below for data length constraints when wrapping and unwrapping keys do not 7018 apply to wrapping and unwrapping private keys. 7019 Constraints on key types and the length of data are summarized in the following table: 7020 7021 Table 174, BLOWFISH-CBC with PKCS Padding: Key and Data Length Function Key type Input Length Output Length C_Encrypt BLOWFISH Any Input length rounded up to multiple of the block size C_Decrypt BLOWFISH Multiple of block size Between 1 and block length block size bytes shorter than input length C_WrapKey BLOWFISH Any Input length rounded up to multiple of the block size C_UnwrapKey BLOWFISH Multiple of block size Between 1 and block length block size bytes shorter than input length
7022 2.46 Twofish 7023 Ref. https://www.schneier.com/twofish.html
7024 2.46.1 Definitions 7025 This section defines the key type “CKK_TWOFISH” for type CK_KEY_TYPE as used in the 7026 CKA_KEY_TYPE attribute of key objects. 7027 Mechanisms: 7028 CKM_TWOFISH_KEY_GEN 7029 CKM_TWOFISH_CBC 7030 CKM_TWOFISH_CBC_PAD 7031
7032 2.46.2 Twofish secret key objects 7033 Twofish secret key objects (object class CKO_SECRET_KEY, key type CKK_TWOFISH) hold Twofish 7034 keys. The following table defines the Twofish secret key object attributes, in addition to the common 7035 attributes defined for this object class: 7036 Table 175, Twofish Secret Key Object Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key value 128-, 192-, or 256-bit key CKA_VALUE_LEN2,3 CK_ULONG Length in bytes of key value 7037 - Refer to [PKCS11-Base] table 11 for footnotes 7038 The following is a sample template for creating an TWOFISH secret key object: 7039 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 7040 CK_KEY_TYPE keyType = CKK_TWOFISH; 7041 CK_UTF8CHAR label[] = “A twofish secret key object”; 7042 CK_BYTE value[16] = {...}; 7043 CK_BBOOL true = CK_TRUE;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 196 of 278 7044 CK_ATTRIBUTE template[] = { 7045 {CKA_CLASS, &class, sizeof(class)}, 7046 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 7047 {CKA_TOKEN, &true, sizeof(true)}, 7048 {CKA_LABEL, label, sizeof(label)-1}, 7049 {CKA_ENCRYPT, &true, sizeof(true)}, 7050 {CKA_VALUE, value, sizeof(value)} 7051 };
7052 2.46.3 Twofish key generation 7053 The Twofish key generation mechanism, denoted CKM_TWOFISH_KEY_GEN, is a key generation 7054 mechanism Twofish. 7055 It does not have a parameter. 7056 The mechanism generates Blowfish keys with a particular length, as specified in the CKA_VALUE_LEN 7057 attribute of the template for the key. 7058 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 7059 key. Other attributes supported by the key type (specifically, the flags indicating which functions the key 7060 supports) may be specified in the template for the key, or else are assigned default initial values. 7061 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7062 specify the supported range of key sizes, in bytes.
7063 2.46.4 Twofish -CBC 7064 Twofish-CBC, denoted CKM_TWOFISH_CBC, is a mechanism for single- and multiple-part encryption 7065 and decryption; key wrapping; and key unwrapping. 7066 It has a parameter, a 16-byte initialization vector.
7067 2.46.5 Twofish-CBC with PKCS padding 7068 Twofish-CBC-PAD, denoted CKM_TWOFISH_CBC_PAD, is a mechanism for single- and multiple-part 7069 encryption and decryption, key wrapping and key unwrapping, cipher-block chaining mode and the block 7070 cipher padding method detailed in PKCS #7. 7071 It has a parameter, a 16-byte initialization vector. 7072 The PKCS padding in this mechanism allows the length of the plaintext value to be recovered from the 7073 ciphertext value. Therefore, when unwrapping keys with this mechanism, no value should be specified for 7074 the CKA_VALUE_LEN attribute.
7075 2.47 CAMELLIA 7076 Camellia is a block cipher with 128-bit block size and 128-, 192-, and 256-bit keys, similar to AES. 7077 Camellia is described e.g. in IETF RFC 3713. 7078 Table 176, Camellia Mechanisms vs. Functions Functions Encryp Sign SR Gen Wrap Mechanism t & & Diges . & Deriv & Verif VR t Unwra e Decryp y 1 Key p t / Key Pair CKM_CAMELLIA_KEY_GEN
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 197 of 278 Functions Encryp Sign SR Gen Wrap Mechanism t & & Diges . & Deriv & Verif VR t Unwra e Decryp y 1 Key p t / Key Pair CKM_CAMELLIA_ECB CKM_CAMELLIA_CBC CKM_CAMELLIA_CBC_PAD CKM_CAMELLIA_MAC_GENERAL CKM_CAMELLIA_MAC CKM_CAMELLIA_ECB_ENCRYPT_DA TA CKM_CAMELLIA_CBC_ENCRYPT_DA TA
7079 2.47.1 Definitions 7080 This section defines the key type “CKK_CAMELLIA” for type CK_KEY_TYPE as used in the 7081 CKA_KEY_TYPE attribute of key objects. 7082 Mechanisms: 7083 CKM_CAMELLIA_KEY_GEN 7084 CKM_CAMELLIA_ECB 7085 CKM_CAMELLIA_CBC 7086 CKM_CAMELLIA_MAC 7087 CKM_CAMELLIA_MAC_GENERAL 7088 CKM_CAMELLIA_CBC_PAD
7089 2.47.2 Camellia secret key objects 7090 Camellia secret key objects (object class CKO_SECRET_KEY, key type CKK_CAMELLIA) hold 7091 Camellia keys. The following table defines the Camellia secret key object attributes, in addition to the 7092 common attributes defined for this object class: 7093 Table 177, Camellia Secret Key Object Attributes Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key value (16, 24, or 32 bytes) CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value 7094 - Refer to [PKCS11-Base] table 11 for footnotes. 7095 The following is a sample template for creating a Camellia secret key object: 7096 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 7097 CK_KEY_TYPE keyType = CKK_CAMELLIA; 7098 CK_UTF8CHAR label[] = “A Camellia secret key object”; 7099 CK_BYTE value[] = {...}; 7100 CK_BBOOL true = CK_TRUE;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 198 of 278 7101 CK_ATTRIBUTE template[] = { 7102 {CKA_CLASS, &class, sizeof(class)}, 7103 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 7104 {CKA_TOKEN, &true, sizeof(true)}, 7105 {CKA_LABEL, label, sizeof(label)-1}, 7106 {CKA_ENCRYPT, &true, sizeof(true)}, 7107 {CKA_VALUE, value, sizeof(value)} 7108 };
7109 2.47.3 Camellia key generation 7110 The Camellia key generation mechanism, denoted CKM_CAMELLIA_KEY_GEN, is a key generation 7111 mechanism for Camellia. 7112 It does not have a parameter. 7113 The mechanism generates Camellia keys with a particular length in bytes, as specified in the 7114 CKA_VALUE_LEN attribute of the template for the key. 7115 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 7116 key. Other attributes supported by the Camellia key type (specifically, the flags indicating which functions 7117 the key supports) may be specified in the template for the key, or else are assigned default initial values. 7118 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7119 specify the supported range of Camellia key sizes, in bytes.
7120 2.47.4 Camellia-ECB 7121 Camellia-ECB, denoted CKM_CAMELLIA_ECB, is a mechanism for single- and multiple-part encryption 7122 and decryption; key wrapping; and key unwrapping, based on Camellia and electronic codebook mode. 7123 It does not have a parameter. 7124 This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 7125 wrap/unwrap every secret key that it supports. For wrapping, the mechanism encrypts the value of the 7126 CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus 7127 one null bytes so that the resulting length is a multiple of the block size. The output data is the same 7128 length as the padded input data. It does not wrap the key type, key length, or any other information about 7129 the key; the application must convey these separately. 7130 For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the 7131 CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the 7132 CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the CKA_VALUE 7133 attribute of the new key; other attributes required by the key type must be specified in the template. 7134 Constraints on key types and the length of data are summarized in the following table: 7135 Table 178, Camellia-ECB: Key and Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 199 of 278 Function Key type Input Output length Comments length C_Encrypt CKK_CAMELLIA multiple of same as input length no final part block size C_Decrypt CKK_CAMELLIA multiple of same as input length no final part block size C_WrapKey CKK_CAMELLIA any input length rounded up to multiple of block size C_UnwrapKey CKK_CAMELLIA multiple of determined by type of block size key being unwrapped or CKA_VALUE_LEN 7136 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7137 specify the supported range of Camellia key sizes, in bytes.
7138 2.47.5 Camellia-CBC 7139 Camellia-CBC, denoted CKM_CAMELLIA_CBC, is a mechanism for single- and multiple-part encryption 7140 and decryption; key wrapping; and key unwrapping, based on Camellia and cipher-block chaining mode. 7141 It has a parameter, a 16-byte initialization vector. 7142 This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 7143 wrap/unwrap every secret key that it supports. For wrapping, the mechanism encrypts the value of the 7144 CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus 7145 one null bytes so that the resulting length is a multiple of the block size. The output data is the same 7146 length as the padded input data. It does not wrap the key type, key length, or any other information about 7147 the key; the application must convey these separately. 7148 For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the 7149 CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the 7150 CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the CKA_VALUE 7151 attribute of the new key; other attributes required by the key type must be specified in the template. 7152 Constraints on key types and the length of data are summarized in the following table: 7153 Table 179, Camellia-CBC: Key and Data Length Function Key type Input Output length Comments length C_Encrypt CKK_CAMELLIA multiple of same as input length no final part block size C_Decrypt CKK_CAMELLIA multiple of same as input length no final part block size C_WrapKey CKK_CAMELLIA any input length rounded up to multiple of the block size C_UnwrapKey CKK_CAMELLIA multiple of determined by type of block size key being unwrapped or CKA_VALUE_LEN 7154 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7155 specify the supported range of Camellia key sizes, in bytes.
7156 2.47.6 Camellia-CBC with PKCS padding 7157 Camellia-CBC with PKCS padding, denoted CKM_CAMELLIA_CBC_PAD, is a mechanism for single- 7158 and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on Camellia; 7159 cipher-block chaining mode; and the block cipher padding method detailed in PKCS #7.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 200 of 278 7160 It has a parameter, a 16-byte initialization vector. 7161 The PKCS padding in this mechanism allows the length of the plaintext value to be recovered from the 7162 ciphertext value. Therefore, when unwrapping keys with this mechanism, no value should be specified 7163 for the CKA_VALUE_LEN attribute. 7164 In addition to being able to wrap and unwrap secret keys, this mechanism can wrap and unwrap RSA, 7165 Diffie-Hellman, X9.42 Diffie-Hellman, EC (also related to ECDSA) and DSA private keys (see Section 7166 TBA for details). The entries in the table below for data length constraints when wrapping and 7167 unwrapping keys do not apply to wrapping and unwrapping private keys. 7168 Constraints on key types and the length of data are summarized in the following table: 7169 Table 180, Camellia-CBC with PKCS Padding: Key and Data Length Function Key type Input Output length length C_Encrypt CKK_CAMELLIA any input length rounded up to multiple of the block size C_Decrypt CKK_CAMELLIA multiple of between 1 and block size block size bytes shorter than input length C_WrapKey CKK_CAMELLIA any input length rounded up to multiple of the block size C_UnwrapKey CKK_CAMELLIA multiple of between 1 and block length block size bytes shorter than input length 7170 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7171 specify the supported range of Camellia key sizes, in bytes. 7172
7173 2.47.7 CAMELLIA with Counter mechanism parameters
7174 CK_CAMELLIA_CTR_PARAMS; CK_CAMELLIA_CTR_PARAMS_PTR
7175 CK_CAMELLIA_CTR_PARAMS is a structure that provides the parameters to the 7176 CKM_CAMELLIA_CTR mechanism. It is defined as follows: 7177 typedef struct CK_CAMELLIA_CTR_PARAMS { 7178 CK_ULONG ulCounterBits; 7179 CK_BYTE cb[16]; 7180 } CK_CAMELLIA_CTR_PARAMS; 7181 7182 ulCounterBits specifies the number of bits in the counter block (cb) that shall be incremented. This 7183 number shall be such that 0 < ulCounterBits <= 128. For any values outside this range the mechanism 7184 shall return CKR_MECHANISM_PARAM_INVALID. 7185 It's up to the caller to initialize all of the bits in the counter block including the counter bits. The counter 7186 bits are the least significant bits of the counter block (cb). They are a big-endian value usually starting 7187 with 1. The rest of ‘cb’ is for the nonce, and maybe an optional IV. 7188 E.g. as defined in [RFC 3686]:
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 201 of 278 7189 0 1 2 3 7190 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 7191 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 7192 | Nonce | 7193 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 7194 | Initialization Vector (IV) | 7195 | | 7196 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 7197 | Block Counter | 7198 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 7199 7200 This construction permits each packet to consist of up to 232-1 blocks = 4,294,967,295 blocks = 7201 68,719,476,720 octets. 7202 CK_CAMELLIA_CTR_PARAMS_PTR is a pointer to a CK_CAMELLIA_CTR_PARAMS. 7203
7204 2.47.8 General-length Camellia-MAC 7205 General-length Camellia -MAC, denoted CKM_CAMELLIA_MAC_GENERAL, is a mechanism for single- 7206 and multiple-part signatures and verification, based on Camellia and data authentication as defined 7207 in.[CAMELLIA] 7208 It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length 7209 desired from the mechanism. 7210 The output bytes from this mechanism are taken from the start of the final Camellia cipher block produced 7211 in the MACing process. 7212 Constraints on key types and the length of data are summarized in the following table: 7213 Table 181, General-length Camellia-MAC: Key and Data Length Function Key type Data Signature length length C_Sign CKK_CAMELLIA any 1-block size, as specified in parameters C_Verify CKK_CAMELLIA any 1-block size, as specified in parameters 7214 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7215 specify the supported range of Camellia key sizes, in bytes.
7216 2.47.9 Camellia-MAC 7217 Camellia-MAC, denoted by CKM_CAMELLIA_MAC, is a special case of the general-length Camellia- 7218 MAC mechanism. Camellia-MAC always produces and verifies MACs that are half the block size in 7219 length. 7220 It does not have a parameter. 7221 Constraints on key types and the length of data are summarized in the following table: 7222 Table 182, Camellia-MAC: Key and Data Length Function Key type Data Signature length length C_Sign CKK_CAMELLIA any ½ block size (8 bytes) C_Verify CKK_CAMELLIA any ½ block size (8 bytes) 7223 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7224 specify the supported range of Camellia key sizes, in bytes.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 202 of 278 7225 2.48 Key derivation by data encryption - Camellia 7226 These mechanisms allow derivation of keys using the result of an encryption operation as the key value. 7227 They are for use with the C_DeriveKey function.
7228 2.48.1 Definitions 7229 Mechanisms: 7230 CKM_CAMELLIA_ECB_ENCRYPT_DATA 7231 CKM_CAMELLIA_CBC_ENCRYPT_DATA 7232 7233 typedef struct CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS { 7234 CK_BYTE iv[16]; 7235 CK_BYTE_PTR pData; 7236 CK_ULONG length; 7237 } CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS; 7238 7239 typedef CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS CK_PTR 7240 CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS_PTR;
7241 2.48.2 Mechanism Parameters 7242 Uses CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS, and CK_KEY_DERIVATION_STRING_DATA. 7243 Table 183, Mechanism Parameters for Camellia-based key derivation CKM_CAMELLIA_ECB_ENCRYPT_DATA Uses CK_KEY_DERIVATION_STRING_DATA structure. Parameter is the data to be encrypted and must be a multiple of 16 long. CKM_CAMELLIA_CBC_ENCRYPT_DATA Uses CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS. Parameter is an 16 byte IV value followed by the data. The data value part must be a multiple of 16 bytes long. 7244
7245 2.49 ARIA 7246 ARIA is a block cipher with 128-bit block size and 128-, 192-, and 256-bit keys, similar to AES. ARIA is 7247 described in NSRI “Specification of ARIA”. 7248 Table 184, ARIA Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_ARIA_KEY_GEN CKM_ARIA_ECB CKM_ARIA_CBC CKM_ARIA_CBC_PAD CKM_ARIA_MAC_GENERAL
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 203 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_ARIA_MAC CKM_ARIA_ECB_ENCRYPT_DATA CKM_ARIA_CBC_ENCRYPT_DATA
7249 2.49.1 Definitions 7250 This section defines the key type “CKK_ARIA” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE 7251 attribute of key objects. 7252 Mechanisms: 7253 CKM_ARIA_KEY_GEN 7254 CKM_ARIA_ECB 7255 CKM_ARIA_CBC 7256 CKM_ARIA_MAC 7257 CKM_ARIA_MAC_GENERAL 7258 CKM_ARIA_CBC_PAD
7259 2.49.2 Aria secret key objects 7260 ARIA secret key objects (object class CKO_SECRET_KEY, key type CKK_ARIA) hold ARIA keys. The 7261 following table defines the ARIA secret key object attributes, in addition to the common attributes defined 7262 for this object class: 7263 Table 185, ARIA Secret Key Object Attributes Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key value (16, 24, or 32 bytes) CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value 7264 - Refer to [PKCS11-Base] table 11 for footnotes. 7265 The following is a sample template for creating an ARIA secret key object: 7266 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 7267 CK_KEY_TYPE keyType = CKK_ARIA; 7268 CK_UTF8CHAR label[] = “An ARIA secret key object”; 7269 CK_BYTE value[] = {...}; 7270 CK_BBOOL true = CK_TRUE; 7271 CK_ATTRIBUTE template[] = { 7272 {CKA_CLASS, &class, sizeof(class)}, 7273 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 7274 {CKA_TOKEN, &true, sizeof(true)}, 7275 {CKA_LABEL, label, sizeof(label)-1}, 7276 {CKA_ENCRYPT, &true, sizeof(true)}, 7277 {CKA_VALUE, value, sizeof(value)} 7278 };
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 204 of 278 7279 2.49.3 ARIA key generation 7280 The ARIA key generation mechanism, denoted CKM_ARIA_KEY_GEN, is a key generation mechanism 7281 for Aria. 7282 It does not have a parameter. 7283 The mechanism generates ARIA keys with a particular length in bytes, as specified in the 7284 CKA_VALUE_LEN attribute of the template for the key. 7285 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 7286 key. Other attributes supported by the ARIA key type (specifically, the flags indicating which functions the 7287 key supports) may be specified in the template for the key, or else are assigned default initial values. 7288 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7289 specify the supported range of ARIA key sizes, in bytes.
7290 2.49.4 ARIA-ECB 7291 ARIA-ECB, denoted CKM_ARIA_ECB, is a mechanism for single- and multiple-part encryption and 7292 decryption; key wrapping; and key unwrapping, based on Aria and electronic codebook mode. 7293 It does not have a parameter. 7294 This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 7295 wrap/unwrap every secret key that it supports. For wrapping, the mechanism encrypts the value of the 7296 CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus 7297 one null bytes so that the resulting length is a multiple of the block size. The output data is the same 7298 length as the padded input data. It does not wrap the key type, key length, or any other information about 7299 the key; the application must convey these separately. 7300 For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the 7301 CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the 7302 CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the CKA_VALUE 7303 attribute of the new key; other attributes required by the key type must be specified in the template. 7304 Constraints on key types and the length of data are summarized in the following table: 7305 Table 186, ARIA-ECB: Key and Data Length Function Key type Input Output length Comments length C_Encrypt CKK_ARIA multiple of same as input length no final part block size C_Decrypt CKK_ARIA multiple of same as input length no final part block size C_WrapKey CKK_ARIA any input length rounded up to multiple of block size C_UnwrapKey CKK_ARIA multiple of determined by type of block size key being unwrapped or CKA_VALUE_LEN
7306 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7307 specify the supported range of ARIA key sizes, in bytes.
7308 2.49.5 ARIA-CBC 7309 ARIA-CBC, denoted CKM_ARIA_CBC, is a mechanism for single- and multiple-part encryption and 7310 decryption; key wrapping; and key unwrapping, based on ARIA and cipher-block chaining mode. 7311 It has a parameter, a 16-byte initialization vector. 7312 This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 7313 wrap/unwrap every secret key that it supports. For wrapping, the mechanism encrypts the value of the pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 205 of 278 7314 CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus 7315 one null bytes so that the resulting length is a multiple of the block size. The output data is the same 7316 length as the padded input data. It does not wrap the key type, key length, or any other information about 7317 the key; the application must convey these separately. 7318 For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the 7319 CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the 7320 CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the CKA_VALUE 7321 attribute of the new key; other attributes required by the key type must be specified in the template. 7322 Constraints on key types and the length of data are summarized in the following table: 7323 Table 187, ARIA-CBC: Key and Data Length Function Key type Input Output length Comments length C_Encrypt CKK_ARIA multiple of same as input length no final part block size C_Decrypt CKK_ARIA multiple of same as input length no final part block size C_WrapKey CKK_ARIA any input length rounded up to multiple of the block size C_UnwrapKey CKK_ARIA multiple of determined by type of block size key being unwrapped or CKA_VALUE_LEN
7324 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7325 specify the supported range of Aria key sizes, in bytes.
7326 2.49.6 ARIA-CBC with PKCS padding 7327 ARIA-CBC with PKCS padding, denoted CKM_ARIA_CBC_PAD, is a mechanism for single- and 7328 multiple-part encryption and decryption; key wrapping; and key unwrapping, based on ARIA; cipher-block 7329 chaining mode; and the block cipher padding method detailed in PKCS #7. 7330 It has a parameter, a 16-byte initialization vector. 7331 The PKCS padding in this mechanism allows the length of the plaintext value to be recovered from the 7332 ciphertext value. Therefore, when unwrapping keys with this mechanism, no value should be specified 7333 for the CKA_VALUE_LEN attribute. 7334 In addition to being able to wrap and unwrap secret keys, this mechanism can wrap and unwrap RSA, 7335 Diffie-Hellman, X9.42 Diffie-Hellman, EC (also related to ECDSA) and DSA private keys (see Section 7336 TBA for details). The entries in the table below for data length constraints when wrapping and 7337 unwrapping keys do not apply to wrapping and unwrapping private keys. 7338 Constraints on key types and the length of data are summarized in the following table: 7339 Table 188, ARIA-CBC with PKCS Padding: Key and Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 206 of 278 Function Key type Input Output length length C_Encrypt CKK_ARIA any input length rounded up to multiple of the block size C_Decrypt CKK_ARIA multiple of between 1 and block size block size bytes shorter than input length C_WrapKey CKK_ARIA any input length rounded up to multiple of the block size C_UnwrapKey CKK_ARIA multiple of between 1 and block length block size bytes shorter than input length 7340 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7341 specify the supported range of ARIA key sizes, in bytes.
7342 2.49.7 General-length ARIA-MAC 7343 General-length ARIA -MAC, denoted CKM_ARIA_MAC_GENERAL, is a mechanism for single- and 7344 multiple-part signatures and verification, based on ARIA and data authentication as defined in [FIPS 113]. 7345 It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length 7346 desired from the mechanism. 7347 The output bytes from this mechanism are taken from the start of the final ARIA cipher block produced in 7348 the MACing process. 7349 Constraints on key types and the length of data are summarized in the following table: 7350 Table 189, General-length ARIA-MAC: Key and Data Length Function Key type Data Signature length length C_Sign CKK_ARIA any 1-block size, as specified in parameters C_Verify CKK_ARIA any 1-block size, as specified in parameters 7351 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7352 specify the supported range of ARIA key sizes, in bytes.
7353 2.49.8 ARIA-MAC 7354 ARIA-MAC, denoted by CKM_ARIA_MAC, is a special case of the general-length ARIA-MAC 7355 mechanism. ARIA-MAC always produces and verifies MACs that are half the block size in length. 7356 It does not have a parameter. 7357 Constraints on key types and the length of data are summarized in the following table: 7358 Table 190, ARIA-MAC: Key and Data Length Function Key type Data Signature length length C_Sign CKK_ARIA any ½ block size (8 bytes) C_Verify CKK_ARIA any ½ block size (8 bytes) 7359 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7360 specify the supported range of ARIA key sizes, in bytes.
7361 2.50 Key derivation by data encryption - ARIA 7362 These mechanisms allow derivation of keys using the result of an encryption operation as the key value. 7363 They are for use with the C_DeriveKey function.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 207 of 278 7364 2.50.1 Definitions 7365 Mechanisms: 7366 CKM_ARIA_ECB_ENCRYPT_DATA 7367 CKM_ARIA_CBC_ENCRYPT_DATA 7368 7369 typedef struct CK_ARIA_CBC_ENCRYPT_DATA_PARAMS { 7370 CK_BYTE iv[16]; 7371 CK_BYTE_PTR pData; 7372 CK_ULONG length; 7373 } CK_ARIA_CBC_ENCRYPT_DATA_PARAMS; 7374 7375 typedef CK_ARIA_CBC_ENCRYPT_DATA_PARAMS CK_PTR 7376 CK_ARIA_CBC_ENCRYPT_DATA_PARAMS_PTR;
7377 2.50.2 Mechanism Parameters 7378 Uses CK_ARIA_CBC_ENCRYPT_DATA_PARAMS, and CK_KEY_DERIVATION_STRING_DATA. 7379 Table 191, Mechanism Parameters for Aria-based key derivation CKM_ARIA_ECB_ENCRYPT_DATA Uses CK_KEY_DERIVATION_STRING_DATA structure. Parameter is the data to be encrypted and must be a multiple of 16 long. CKM_ARIA_CBC_ENCRYPT_DATA Uses CK_ARIA_CBC_ENCRYPT_DATA_PARAMS. Parameter is an 16 byte IV value followed by the data. The data value part must be a multiple of 16 bytes long. 7380
7381 2.51 SEED 7382 SEED is a symmetric block cipher developed by the South Korean Information Security Agency (KISA). It 7383 has a 128-bit key size and a 128-bit block size. 7384 Its specification has been published as Internet [RFC 4269]. 7385 RFCs have been published defining the use of SEED in 7386 TLS ftp://ftp.rfc-editor.org/in-notes/rfc4162.txt 7387 IPsec ftp://ftp.rfc-editor.org/in-notes/rfc4196.txt 7388 CMS ftp://ftp.rfc-editor.org/in-notes/rfc4010.txt 7389 7390 TLS cipher suites that use SEED include: 7391 CipherSuite TLS_RSA_WITH_SEED_CBC_SHA = { 0x00, 7392 0x96}; 7393 CipherSuite TLS_DH_DSS_WITH_SEED_CBC_SHA = { 0x00, 7394 0x97}; 7395 CipherSuite TLS_DH_RSA_WITH_SEED_CBC_SHA = { 0x00, 7396 0x98}; 7397 CipherSuite TLS_DHE_DSS_WITH_SEED_CBC_SHA = { 0x00, 7398 0x99};
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 208 of 278 7399 CipherSuite TLS_DHE_RSA_WITH_SEED_CBC_SHA = { 0x00, 7400 0x9A}; 7401 CipherSuite TLS_DH_anon_WITH_SEED_CBC_SHA = { 0x00, 7402 0x9B}; 7403 7404 As with any block cipher, it can be used in the ECB, CBC, OFB and CFB modes of operation, as well as 7405 in a MAC algorithm such as HMAC. 7406 OIDs have been published for all these uses. A list may be seen at 7407 http://www.alvestrand.no/objectid/1.2.410.200004.1.html 7408 7409 Table 192, SEED Mechanisms vs. Functions Functions Encryp Sign SR Gen Wrap Mechanism t & & Diges . & Deriv & Verif VR t Unwra e Decryp y 1 Key/ p t Key Pair CKM_SEED_KEY_GEN CKM_SEED_ECB CKM_SEED_CBC CKM_SEED_CBC_PAD CKM_SEED_MAC_GENERAL CKM_SEED_MAC CKM_SEED_ECB_ENCRYPT_DATA CKM_SEED_CBC_ENCRYPT_DAT A
7410 2.51.1 Definitions 7411 This section defines the key type “CKK_SEED” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE 7412 attribute of key objects. 7413 Mechanisms: 7414 CKM_SEED_KEY_GEN 7415 CKM_SEED_ECB 7416 CKM_SEED_CBC 7417 CKM_SEED_MAC 7418 CKM_SEED_MAC_GENERAL 7419 CKM_SEED_CBC_PAD 7420 7421 For all of these mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO 7422 are always 16.
7423 2.51.2 SEED secret key objects 7424 SEED secret key objects (object class CKO_SECRET_KEY, key type CKK_SEED) hold SEED keys. 7425 The following table defines the secret key object attributes, in addition to the common attributes defined 7426 for this object class:
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 209 of 278 7427 Table 193, SEED Secret Key Object Attributes Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key value (always 16 bytes long) 7428 - Refer to [PKCS11-Base] table 11 for footnotes. 7429 The following is a sample template for creating a SEED secret key object: 7430 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 7431 CK_KEY_TYPE keyType = CKK_SEED; 7432 CK_UTF8CHAR label[] = “A SEED secret key object”; 7433 CK_BYTE value[] = {...}; 7434 CK_BBOOL true = CK_TRUE; 7435 CK_ATTRIBUTE template[] = { 7436 {CKA_CLASS, &class, sizeof(class)}, 7437 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 7438 {CKA_TOKEN, &true, sizeof(true)}, 7439 {CKA_LABEL, label, sizeof(label)-1}, 7440 {CKA_ENCRYPT, &true, sizeof(true)}, 7441 {CKA_VALUE, value, sizeof(value)} 7442 };
7443 2.51.3 SEED key generation 7444 The SEED key generation mechanism, denoted CKM_SEED_KEY_GEN, is a key generation mechanism 7445 for SEED. 7446 It does not have a parameter. 7447 The mechanism generates SEED keys. 7448 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 7449 key. Other attributes supported by the SEED key type (specifically, the flags indicating which functions 7450 the key supports) may be specified in the template for the key, or else are assigned default initial values.
7451 2.51.4 SEED-ECB 7452 SEED-ECB, denoted CKM_SEED_ECB, is a mechanism for single- and multiple-part encryption and 7453 decryption; key wrapping; and key unwrapping, based on SEED and electronic codebook mode. 7454 It does not have a parameter.
7455 2.51.5 SEED-CBC 7456 SEED-CBC, denoted CKM_SEED_CBC, is a mechanism for single- and multiple-part encryption and 7457 decryption; key wrapping; and key unwrapping, based on SEED and cipher-block chaining mode. 7458 It has a parameter, a 16-byte initialization vector.
7459 2.51.6 SEED-CBC with PKCS padding 7460 SEED-CBC with PKCS padding, denoted CKM_SEED_CBC_PAD, is a mechanism for single- and 7461 multiple-part encryption and decryption; key wrapping; and key unwrapping, based on SEED; cipher- 7462 block chaining mode; and the block cipher padding method detailed in PKCS #7. 7463 It has a parameter, a 16-byte initialization vector.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 210 of 278 7464 2.51.7 General-length SEED-MAC 7465 General-length SEED-MAC, denoted CKM_SEED_MAC_GENERAL, is a mechanism for single- and 7466 multiple-part signatures and verification, based on SEED and data authentication as defined in 0. 7467 It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length 7468 desired from the mechanism. 7469 The output bytes from this mechanism are taken from the start of the final cipher block produced in the 7470 MACing process.
7471 2.51.8 SEED-MAC 7472 SEED-MAC, denoted by CKM_SEED_MAC, is a special case of the general-length SEED-MAC 7473 mechanism. SEED-MAC always produces and verifies MACs that are half the block size in length. 7474 It does not have a parameter.
7475 2.52 Key derivation by data encryption - SEED 7476 These mechanisms allow derivation of keys using the result of an encryption operation as the key value. 7477 They are for use with the C_DeriveKey function.
7478 2.52.1 Definitions 7479 Mechanisms: 7480 CKM_SEED_ECB_ENCRYPT_DATA 7481 CKM_SEED_CBC_ENCRYPT_DATA 7482 7483 typedef struct CK_SEED_CBC_ENCRYPT_DATA_PARAMS 7484 CK_CBC_ENCRYPT_DATA_PARAMS; 7485 7486 typedef CK_CBC_ENCRYPT_DATA_PARAMS CK_PTR 7487 CK_CBC_ENCRYPT_DATA_PARAMS_PTR;
7488 2.52.2 Mechanism Parameters 7489 Table 194, Mechanism Parameters for SEED-based key derivation CKM_SEED_ECB_ENCRYPT_DATA Uses CK_KEY_DERIVATION_STRING_DATA structure. Parameter is the data to be encrypted and must be a multiple of 16 long. CKM_SEED_CBC_ENCRYPT_DATA Uses CK_CBC_ENCRYPT_DATA_PARAMS. Parameter is an 16 byte IV value followed by the data. The data value part must be a multiple of 16 bytes long. 7490
7491 2.53 OTP
7492 2.53.1 Usage overview 7493 OTP tokens represented as PKCS #11 mechanisms may be used in a variety of ways. The usage cases 7494 can be categorized according to the type of sought functionality.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 211 of 278 7495 2.53.2 Case 1: Generation of OTP values
7496 . 7497 Figure 1: Retrieving OTP values through C_Sign 7498 Figure 1Figure 1Error! Reference source not found. shows an integration of PKCS #11 into an 7499 needs to authenticate users holding OTP tokens. In this particular example, a connected hardware token 7500 is used, but a software token is equally possible. The application invokes C_Sign to retrieve the OTP 7501 value from the token. In the example, the application then passes the retrieved OTP value to a client API 7502 that sends it via the network to an authentication server. The client API may implement a standard 7503 authentication protocol such as RADIUS [RFC 2865] or EAP [RFC 3748], or a proprietary protocol such 7504 as that used by RSA Security's ACE/Agent® software.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 212 of 278 7505 2.53.3 Case 2: Verification of provided OTP values
Server Application
C_Verify()
PKCS #11 Library
Internal Token API
Token (or query to authentication server)
7506 7507 Figure 2: Server-side verification of OTP values 7508 Figure 2Figure 2Error! Reference source not found. illustrates the server-side equivalent of the 7509 depicted in Error! Reference source not found.. In this case, a server application invokes C_Verify with 7510 the received OTP value as the signature value to be verified.
7511 2.53.4 Case 3: Generation of OTP keys
Client Application
C_GenerateKey()
PKCS #11 Library
Internal Token API
Token (or software version thereof)
7512 pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 213 of 278 7513 Figure 3: Generation of an OTP key 7514 Figure 3Figure 3Error! Reference source not found. shows an integration of PKCS #11 into an 7515 generates OTP keys. The application invokes C_GenerateKey to generate an OTP key of a particular 7516 type on the token. The key may subsequently be used as a basis to generate OTP values.
7517 2.53.5 OTP objects
7518 2.53.5.1 Key objects 7519 OTP key objects (object class CKO_OTP_KEY) hold secret keys used by OTP tokens. The following 7520 table defines the attributes common to all OTP keys, in addition to the attributes defined for secret keys, 7521 all of which are inherited by this class: 7522 Table 195: Common OTP key attributes
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 214 of 278 Attribute Data type Meaning CKA_OTP_FORMAT CK_ULONG Format of OTP values produced with this key: CK_OTP_FORMAT_DECIMAL = Decimal (default) (UTF8-encoded) CK_OTP_FORMAT_HEXADECIMA L = Hexadecimal (UTF8-encoded) CK_OTP_FORMAT_ALPHANUME RIC = Alphanumeric (UTF8- encoded) CK_OTP_FORMAT_BINARY = Only binary values. CKA_OTP_LENGTH9 CK_ULONG Default length of OTP values (in the CKA_OTP_FORMAT) produced with this key. CKA_OTP_USER_FRIENDLY_MODE9 CK_BBOOL Set to CK_TRUE when the token is capable of returning OTPs suitable for human consumption. See the description of CKF_USER_FRIENDLY_OTP below. CKA_OTP CK_ULONG Parameter requirements when _CHALLENGE_REQUIREMENT9 generating or verifying OTP values with this key: CK_OTP_PARAM_MANDATORY = A challenge must be supplied. CK_OTP_PARAM_OPTIONAL = A challenge may be supplied but need not be. CK_OTP_PARAM_IGNORED = A challenge, if supplied, will be ignored. CKA_OTP_TIME_REQUIREMENT9 CK_ULONG Parameter requirements when generating or verifying OTP values with this key: CK_OTP_PARAM_MANDATORY = A time value must be supplied. CK_OTP_PARAM_OPTIONAL = A time value may be supplied but need not be. CK_OTP_PARAM_IGNORED = A time value, if supplied, will be ignored. CKA_OTP_COUNTER_REQUIREMEN CK_ULONG Parameter requirements when T9 generating or verifying OTP values with this key: CK_OTP_PARAM_MANDATORY = A counter value must be supplied. CK_OTP_PARAM_OPTIONAL = A counter value may be supplied but need not be. CK_OTP_PARAM_IGNORED = A counter value, if supplied, will be ignored. pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 215 of 278 Attribute Data type Meaning CKA_OTP_PIN_REQUIREMENT9 CK_ULONG Parameter requirements when generating or verifying OTP values with this key: CK_OTP_PARAM_MANDATORY = A PIN value must be supplied. CK_OTP_PARAM_OPTIONAL = A PIN value may be supplied but need not be (if not supplied, then library will be responsible for collecting it) CK_OTP_PARAM_IGNORED = A PIN value, if supplied, will be ignored. CKA_OTP_COUNTER Byte array Value of the associated internal counter. Default value is empty (i.e. ulValueLen = 0). CKA_OTP_TIME RFC 2279 Value of the associated internal string UTC time in the form YYYYMMDDhhmmss. Default value is empty (i.e. ulValueLen= 0). CKA_OTP_USER_IDENTIFIER RFC 2279 Text string that identifies a user string associated with the OTP key (may be used to enhance the user experience). Default value is empty (i.e. ulValueLen = 0). CKA_OTP_SERVICE_IDENTIFIER RFC 2279 Text string that identifies a service string that may validate OTPs generated by this key. Default value is empty (i.e. ulValueLen = 0). CKA_OTP_SERVICE_LOGO Byte array Logotype image that identifies a service that may validate OTPs generated by this key. Default value is empty (i.e. ulValueLen = 0). CKA_OTP_SERVICE_LOGO_TYPE RFC 2279 MIME type of the string CKA_OTP_SERVICE_LOGO attribute value. Default value is empty (i.e. ulValueLen = 0). CKA_VALUE1, 4, 6, 7 Byte array Value of the key. CKA_VALUE_LEN2, 3 CK_ULONG Length in bytes of key value. 7523 Refer to [PKCS11-Base] table 11 for footnotes. 7524 Note: A Cryptoki library may support PIN-code caching in order to reduce user interactions. An OTP- 7525 PKCS #11 application should therefore always consult the state of the CKA_OTP_PIN_REQUIREMENT 7526 attribute before each call to C_SignInit, as the value of this attribute may change dynamically. 7527 For OTP tokens with multiple keys, the keys may be enumerated using C_FindObjects. The 7528 CKA_OTP_SERVICE_IDENTIFIER and/or the CKA_OTP_SERVICE_LOGO attribute may be used to 7529 distinguish between keys. The actual choice of key for a particular operation is however application- 7530 specific and beyond the scope of this document. 7531 For all OTP keys, the CKA_ALLOWED_MECHANISMS attribute should be set as required.
7532 2.53.6 OTP-related notifications 7533 This document extends the set of defined notifications as follows: pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 216 of 278 7534 CKN_OTP_CHANGED Cryptoki is informing the application that the OTP for a key on a 7535 connected token just changed. This notification is particularly useful 7536 when applications wish to display the current OTP value for time- 7537 based mechanisms.
7538 2.53.7 OTP mechanisms 7539 The following table shows, for the OTP mechanisms defined in this document, their support by different 7540 cryptographic operations. For any particular token, of course, a particular operation may well support 7541 only a subset of the mechanisms listed. There is also no guarantee that a token that supports one 7542 mechanism for some operation supports any other mechanism for any other operation (or even supports 7543 that same mechanism for any other operation). 7544 Table 196: OTP mechanisms vs. applicable functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_SECURID_KEY_GEN CKM_SECURID CKM_HOTP_KEY_GEN CKM_HOTP CKM_ACTI_KEY_GEN CKM_ACTI 7545 The remainder of this section will present in detail the OTP mechanisms and the parameters that are 7546 supplied to them.
7547 2.53.7.1 OTP mechanism parameters 7548 CK_PARAM_TYPE 7549 CK_PARAM_TYPE is a value that identifies an OTP parameter type. It is defined as follows: 7550 typedef CK_ULONG CK_PARAM_TYPE; 7551 The following CK_PARAM_TYPE types are defined: 7552 Table 197, OTP parameter types
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 217 of 278 Parameter Data type Meaning CK_OTP_PIN RFC 2279 A UTF8 string containing a PIN for use string when computing or verifying PIN-based OTP values. CK_OTP_CHALLENGE Byte array Challenge to use when computing or verifying challenge-based OTP values. CK_OTP_TIME RFC 2279 UTC time value in the form string YYYYMMDDhhmmss to use when computing or verifying time-based OTP values. CK_OTP_COUNTER Byte array Counter value to use when computing or verifying counter-based OTP values. CK_OTP_FLAGS CK_FLAGS Bit flags indicating the characteristics of the sought OTP as defined below. CK_OTP_OUTPUT_LENGTH CK_ULONG Desired output length (overrides any default value). A Cryptoki library will return CKR_MECHANISM_PARAM_INVALID if a provided length value is not supported. CK_OTP_FORMAT CK_ULONG Returned OTP format (allowed values are the same as for CKA_OTP_FORMAT). This parameter is only intended for C_Sign output, see paragraphs below. When not present, the returned OTP format will be the same as the value of the CKA_OTP_FORMAT attribute for the key in question. CK_OTP_VALUE Byte array An actual OTP value. This parameter type is intended for C_Sign output, see paragraphs below. 7553
7554 The following table defines the possible values for the CK_OTP_FLAGS type: 7555 Table 198: OTP Mechanism Flags Bit flag Mask Meaning CKF_NEXT_OTP 0x00000001 True (i.e. set) if the OTP computation shall be for the next OTP, rather than the current one (current being interpreted in the context of the algorithm, e.g. for the current counter value or current time window). A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if the CKF_NEXT_OTP flag is set and the OTP mechanism in question does not support the concept of “next” OTP or the library is not capable of generating the next OTP9.
9 Applications that may need to retrieve the next OTP should be prepared to handle this situation. For example, an application could store the OTP value returned by C_Sign so that, if a next OTP is required, it can compare it to the OTP value returned by subsequent calls to C_Sign should it turn out that the library does not support the CKF_NEXT_OTP flag.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 218 of 278 Bit flag Mask Meaning CKF_EXCLUDE_TIME 0x00000002 True (i.e. set) if the OTP computation must not include a time value. Will have an effect only on mechanisms that do include a time value in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed. CKF_EXCLUDE_COUNTER 0x00000004 True (i.e. set) if the OTP computation must not include a counter value. Will have an effect only on mechanisms that do include a counter value in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed. CKF_EXCLUDE_CHALLENGE 0x00000008 True (i.e. set) if the OTP computation must not include a challenge. Will have an effect only on mechanisms that do include a challenge in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed. CKF_EXCLUDE_PIN 0x00000010 True (i.e. set) if the OTP computation must not include a PIN value. Will have an effect only on mechanisms that do include a PIN in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed. CKF_USER_FRIENDLY_OTP 0x00000020 True (i.e. set) if the OTP returned shall be in a form suitable for human consumption. If this flag is set, and the call is successful, then the returned CK_OTP_VALUE shall be a UTF8-encoded printable string. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if this flag is set when CKA_OTP_USER_FRIENDLY_MODE for the key in question is CK_FALSE. 7556 Note: Even if CKA_OTP_FORMAT is not set to CK_OTP_FORMAT_BINARY, then there may still be 7557 value in setting the CKF_USER_FRIENDLY_OTP flag (assuming CKA_OTP_USER_FRIENDLY_MODE 7558 is CK_TRUE, of course) if the intent is for a human to read the generated OTP value, since it may 7559 become shorter or otherwise better suited for a user. Applications that do not intend to provide a returned 7560 OTP value to a user should not set the CKF_USER_FRIENDLY_OTP flag. 7561 CK_OTP_PARAM; CK_OTP_PARAM_PTR 7562 CK_OTP_PARAM is a structure that includes the type, value, and length of an OTP parameter. It is 7563 defined as follows:
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 219 of 278 7564 typedef struct CK_OTP_PARAM { 7565 CK_PARAM_TYPE type; 7566 CK_VOID_PTR pValue; 7567 CK_ULONG ulValueLen; 7568 } CK_OTP_PARAM; 7569 The fields of the structure have the following meanings: 7570 type the parameter type
7571 pValue pointer to the value of the parameter
7572 ulValueLen length in bytes of the value
7573 If a parameter has no value, then ulValueLen = 0, and the value of pValue is irrelevant. Note that pValue 7574 is a “void” pointer, facilitating the passing of arbitrary values. Both the application and the Cryptoki library 7575 must ensure that the pointer can be safely cast to the expected type (i.e., without word-alignment errors). 7576 CK_OTP_PARAM_PTR is a pointer to a CK_OTP_PARAM. 7577 7578 CK_OTP_PARAMS; CK_OTP_PARAMS_PTR 7579 CK_OTP_PARAMS is a structure that is used to provide parameters for OTP mechanisms in a generic 7580 fashion. It is defined as follows: 7581 typedef struct CK_OTP_PARAMS { 7582 CK_OTP_PARAM_PTR pParams; 7583 CK_ULONG ulCount; 7584 } CK_OTP_PARAMS; 7585 The fields of the structure have the following meanings: 7586 pParams pointer to an array of OTP parameters
7587 ulCount the number of parameters in the array
7588 CK_OTP_PARAMS_PTR is a pointer to a CK_OTP_PARAMS. 7589 7590 When calling C_SignInit or C_VerifyInit with a mechanism that takes a CK_OTP_PARAMS structure as a 7591 parameter, the CK_OTP_PARAMS structure shall be populated in accordance with the 7592 CKA_OTP_X_REQUIREMENT key attributes for the identified key, where X is PIN, CHALLENGE, TIME, 7593 or COUNTER. 7594 For example, if CKA_OTP_TIME_REQUIREMENT = CK_OTP_PARAM_MANDATORY, then the 7595 CK_OTP_TIME parameter shall be present. If CKA_OTP_TIME_REQUIREMENT = 7596 CK_OTP_PARAM_OPTIONAL, then a CK_OTP_TIME parameter may be present. If it is not present, 7597 then the library may collect it (during the C_Sign call). If CKA_OTP_TIME_REQUIREMENT = 7598 CK_OTP_PARAM_IGNORED, then a provided CK_OTP_TIME parameter will always be ignored. 7599 Additionally, a provided CK_OTP_TIME parameter will always be ignored if CKF_EXCLUDE_TIME is set 7600 in a CK_OTP_FLAGS parameter. Similarly, if this flag is set, a library will not attempt to collect the value 7601 itself, and it will also instruct the token not to make use of any internal value, subject to token policies. It is 7602 an error (CKR_MECHANISM_PARAM_INVALID) to set the CKF_EXCLUDE_TIME flag when the 7603 CKA_OTP_TIME_REQUIREMENT attribute is CK_OTP_PARAM_MANDATORY. 7604 The above discussion holds for all CKA_OTP_X_REQUIREMENT attributes (i.e., 7605 CKA_OTP_PIN_REQUIREMENT, CKA_OTP_CHALLENGE_REQURIEMENT, 7606 CKA_OTP_COUNTER_REQUIREMENT, CKA_OTP_TIME_REQUIREMENT). A library may set a 7607 particular CKA_OTP_X_REQUIREMENT attribute to CK_OTP_PARAM_OPTIONAL even if it is required
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 220 of 278 7608 by the mechanism as long as the token (or the library itself) has the capability of providing the value to the 7609 computation. One example of this is a token with an on-board clock. 7610 In addition, applications may use the CK_OTP_FLAGS, the CK_OTP_FORMAT and the 7611 CKA_OTP_LENGTH parameters to set additional parameters. 7612 7613 CK_OTP_SIGNATURE_INFO, CK_OTP_SIGNATURE_INFO_PTR 7614 CK_OTP_SIGNATURE_INFO is a structure that is returned by all OTP mechanisms in successful calls to 7615 C_Sign (C_SignFinal). The structure informs applications of actual parameter values used in particular 7616 OTP computations in addition to the OTP value itself. It is used by all mechanisms for which the key 7617 belongs to the class CKO_OTP_KEY and is defined as follows: 7618 typedef struct CK_OTP_SIGNATURE_INFO { 7619 CK_OTP_PARAM_PTR pParams; 7620 CK_ULONG ulCount; 7621 } CK_OTP_SIGNATURE_INFO; 7622 The fields of the structure have the following meanings: 7623 pParams pointer to an array of OTP parameter values
7624 ulCount the number of parameters in the array
7625 After successful calls to C_Sign or C_SignFinal with an OTP mechanism, the pSignature parameter will 7626 be set to point to a CK_OTP_SIGNATURE_INFO structure. One of the parameters in this structure will be 7627 the OTP value itself, identified with the CK_OTP_VALUE tag. Other parameters may be present for 7628 informational purposes, e.g. the actual time used in the OTP calculation. In order to simplify OTP 7629 validations, authentication protocols may permit authenticating parties to send some or all of these 7630 parameters in addition to OTP values themselves. Applications should therefore check for their presence 7631 in returned CK_OTP_SIGNATURE_INFO values whenever such circumstances apply. 7632 Since C_Sign and C_SignFinal follows the convention described in [PKCS11-Base] Section 5.2 on 7633 producing output, a call to C_Sign (or C_SignFinal) with pSignature set to NULL_PTR will return (in the 7634 pulSignatureLen parameter) the required number of bytes to hold the CK_OTP_SIGNATURE_INFO 7635 structure as well as all the data in all its CK_OTP_PARAM components. If an application allocates a 7636 memory block based on this information, it shall therefore not subsequently de-allocate components of 7637 such a received value but rather de-allocate the complete CK_OTP_PARAMS structure itself. A Cryptoki 7638 library that is called with a non-NULL pSignature pointer will assume that it points to a contiguous 7639 memory block of the size indicated by the pulSignatureLen parameter. 7640 When verifying an OTP value using an OTP mechanism, pSignature shall be set to the OTP value itself, 7641 e.g. the value of the CK_OTP_VALUE component of a CK_OTP_PARAM structure returned by a call to 7642 C_Sign. The CK_OTP_PARAM value supplied in the C_VerifyInit call sets the values to use in the 7643 verification operation. 7644 CK_OTP_SIGNATURE_INFO_PTR points to a CK_OTP_SIGNATURE_INFO.
7645 2.53.8 RSA SecurID
7646 2.53.8.1 RSA SecurID secret key objects 7647 RSA SecurID secret key objects (object class CKO_OTP_KEY, key type CKK_SECURID) hold RSA 7648 SecurID secret keys. The following table defines the RSA SecurID secret key object attributes, in 7649 addition to the common attributes defined for this object class: 7650 Table 199, RSA SecurID secret key object attributes
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 221 of 278 Attribute Data type Meaning CKA_OTP_TIME_INTERVAL1 CK_ULONG Interval between OTP values produced with this key, in seconds. Default is 60. 7651 Refer to [PKCS11-Base] table 11 for footnotes. 7652 The following is a sample template for creating an RSA SecurID secret key object: 7653 CK_OBJECT_CLASS class = CKO_OTP_KEY; 7654 CK_KEY_TYPE keyType = CKK_SECURID; 7655 CK_DATE endDate = {...}; 7656 CK_UTF8CHAR label[] = “RSA SecurID secret key object”; 7657 CK_BYTE keyId[]= {...}; 7658 CK_ULONG outputFormat = CK_OTP_FORMAT_DECIMAL; 7659 CK_ULONG outputLength = 6; 7660 CK_ULONG needPIN = CK_OTP_PARAM_MANDATORY; 7661 CK_ULONG timeInterval = 60; 7662 CK_BYTE value[] = {...}; 7663 CK_BBOOL true = CK_TRUE; 7664 CK_ATTRIBUTE template[] = { 7665 {CKA_CLASS, &class, sizeof(class)}, 7666 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 7667 {CKA_END_DATE, &endDate, sizeof(endDate)}, 7668 {CKA_TOKEN, &true, sizeof(true)}, 7669 {CKA_SENSITIVE, &true, sizeof(true)}, 7670 {CKA_LABEL, label, sizeof(label)-1}, 7671 {CKA_SIGN, &true, sizeof(true)}, 7672 {CKA_VERIFY, &true, sizeof(true)}, 7673 {CKA_ID, keyId, sizeof(keyId)}, 7674 {CKA_OTP_FORMAT, &outputFormat, sizeof(outputFormat)}, 7675 {CKA_OTP_LENGTH, &outputLength, sizeof(outputLength)}, 7676 {CKA_OTP_PIN_REQUIREMENT, &needPIN, sizeof(needPIN)}, 7677 {CKA_OTP_TIME_INTERVAL, &timeInterval, 7678 sizeof(timeInterval)}, 7679 {CKA_VALUE, value, sizeof(value)} 7680 };
7681 2.53.8.2 RSA SecurID key generation 7682 The RSA SecurID key generation mechanism, denoted CKM_SECURID_KEY_GEN, is a key generation 7683 mechanism for the RSA SecurID algorithm. 7684 It does not have a parameter. 7685 The mechanism generates RSA SecurID keys with a particular set of attributes as specified in the 7686 template for the key. 7687 The mechanism contributes at least the CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE_LEN, and 7688 CKA_VALUE attributes to the new key. Other attributes supported by the RSA SecurID key type may be 7689 specified in the template for the key, or else are assigned default initial values 7690 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7691 specify the supported range of SecurID key sizes, in bytes.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 222 of 278 7692 2.53.8.3 SecurID OTP generation and validation 7693 CKM_SECURID is the mechanism for the retrieval and verification of RSA SecurID OTP values. 7694 The mechanism takes a pointer to a CK_OTP_PARAMS structure as a parameter. 7695 When signing or verifying using the CKM_SECURID mechanism, pData shall be set to NULL_PTR and 7696 ulDataLen shall be set to 0.
7697 2.53.8.4 Return values 7698 Support for the CKM_SECURID mechanism extends the set of return values for C_Verify with the 7699 following values: 7700 CKR_NEW_PIN_MODE: The supplied OTP was not accepted and the library requests a new OTP 7701 computed using a new PIN. The new PIN is set through means out of scope for this document. 7702 CKR_NEXT_OTP: The supplied OTP was correct but indicated a larger than normal drift in the 7703 token's internal state (e.g. clock, counter). To ensure this was not due to a temporary problem, the 7704 application should provide the next one-time password to the library for verification.
7705 2.53.9 OATH HOTP
7706 2.53.9.1 OATH HOTP secret key objects 7707 HOTP secret key objects (object class CKO_OTP_KEY, key type CKK_HOTP) hold generic secret keys 7708 and associated counter values. 7709 The CKA_OTP_COUNTER value may be set at key generation; however, some tokens may set it to a 7710 fixed initial value. Depending on the token’s security policy, this value may not be modified and/or may 7711 not be revealed if the object has its CKA_SENSITIVE attribute set to CK_TRUE or its 7712 CKA_EXTRACTABLE attribute set to CK_FALSE. 7713 For HOTP keys, the CKA_OTP_COUNTER value shall be an 8 bytes unsigned integer in big endian (i.e. 7714 network byte order) form. The same holds true for a CK_OTP_COUNTER value in a CK_OTP_PARAM 7715 structure. 7716 The following is a sample template for creating a HOTP secret key object: 7717 CK_OBJECT_CLASS class = CKO_OTP_KEY; 7718 CK_KEY_TYPE keyType = CKK_HOTP; 7719 CK_UTF8CHAR label[] = “HOTP secret key object”; 7720 CK_BYTE keyId[]= {...}; 7721 CK_ULONG outputFormat = CK_OTP_FORMAT_DECIMAL; 7722 CK_ULONG outputLength = 6; 7723 CK_DATE endDate = {...}; 7724 CK_BYTE counterValue[8] = {0}; 7725 CK_BYTE value[] = {...}; 7726 CK_BBOOL true = CK_TRUE; 7727 CK_ATTRIBUTE template[] = { 7728 {CKA_CLASS, &class, sizeof(class)}, 7729 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 7730 {CKA_END_DATE, &endDate, sizeof(endDate)}, 7731 {CKA_TOKEN, &true, sizeof(true)}, 7732 {CKA_SENSITIVE, &true, sizeof(true)}, 7733 {CKA_LABEL, label, sizeof(label)-1}, 7734 {CKA_SIGN, &true, sizeof(true)}, 7735 {CKA_VERIFY, &true, sizeof(true)}, 7736 {CKA_ID, keyId, sizeof(keyId)},
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 223 of 278 7737 {CKA_OTP_FORMAT, &outputFormat, sizeof(outputFormat)}, 7738 {CKA_OTP_LENGTH, &outputLength, sizeof(outputLength)}, 7739 {CKA_OTP_COUNTER, counterValue, sizeof(counterValue)}, 7740 {CKA_VALUE, value, sizeof(value)} 7741 };
7742 2.53.9.2 HOTP key generation 7743 The HOTP key generation mechanism, denoted CKM_HOTP_KEY_GEN, is a key generation mechanism 7744 for the HOTP algorithm. 7745 It does not have a parameter. 7746 The mechanism generates HOTP keys with a particular set of attributes as specified in the template for 7747 the key. 7748 The mechanism contributes at least the CKA_CLASS, CKA_KEY_TYPE, CKA_OTP_COUNTER, 7749 CKA_VALUE and CKA_VALUE_LEN attributes to the new key. Other attributes supported by the HOTP 7750 key type may be specified in the template for the key, or else are assigned default initial values. 7751 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7752 specify the supported range of HOTP key sizes, in bytes.
7753 2.53.9.3 HOTP OTP generation and validation 7754 CKM_HOTP is the mechanism for the retrieval and verification of HOTP OTP values based on the current 7755 internal counter, or a provided counter. 7756 The mechanism takes a pointer to a CK_OTP_PARAMS structure as a parameter. 7757 As for the CKM_SECURID mechanism, when signing or verifying using the CKM_HOTP mechanism, 7758 pData shall be set to NULL_PTR and ulDataLen shall be set to 0. 7759 For verify operations, the counter value CK_OTP_COUNTER must be provided as a CK_OTP_PARAM 7760 parameter to C_VerifyInit. When verifying an OTP value using the CKM_HOTP mechanism, pSignature 7761 shall be set to the OTP value itself, e.g. the value of the CK_OTP_VALUE component of a 7762 CK_OTP_PARAM structure in the case of an earlier call to C_Sign.
7763 2.53.10 ActivIdentity ACTI
7764 2.53.10.1 ACTI secret key objects 7765 ACTI secret key objects (object class CKO_OTP_KEY, key type CKK_ACTI) hold ActivIdentity ACTI 7766 secret keys. 7767 For ACTI keys, the CKA_OTP_COUNTER value shall be an 8 bytes unsigned integer in big endian (i.e. 7768 network byte order) form. The same holds true for the CK_OTP_COUNTER value in the 7769 CK_OTP_PARAM structure. 7770 The CKA_OTP_COUNTER value may be set at key generation; however, some tokens may set it to a 7771 fixed initial value. Depending on the token’s security policy, this value may not be modified and/or may 7772 not be revealed if the object has its CKA_SENSITIVE attribute set to CK_TRUE or its 7773 CKA_EXTRACTABLE attribute set to CK_FALSE. 7774 The CKA_OTP_TIME value may be set at key generation; however, some tokens may set it to a fixed 7775 initial value. Depending on the token’s security policy, this value may not be modified and/or may not be 7776 revealed if the object has its CKA_SENSITIVE attribute set to CK_TRUE or its CKA_EXTRACTABLE 7777 attribute set to CK_FALSE. 7778 The following is a sample template for creating an ACTI secret key object: 7779 CK_OBJECT_CLASS class = CKO_OTP_KEY; 7780 CK_KEY_TYPE keyType = CKK_ACTI; 7781 CK_UTF8CHAR label[] = “ACTI secret key object”;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 224 of 278 7782 CK_BYTE keyId[]= {...}; 7783 CK_ULONG outputFormat = CK_OTP_FORMAT_DECIMAL; 7784 CK_ULONG outputLength = 6; 7785 CK_DATE endDate = {...}; 7786 CK_BYTE counterValue[8] = {0}; 7787 CK_BYTE value[] = {...}; 7788 CK_BBOOL true = CK_TRUE; 7789 CK_ATTRIBUTE template[] = { 7790 {CKA_CLASS, &class, sizeof(class)}, 7791 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 7792 {CKA_END_DATE, &endDate, sizeof(endDate)}, 7793 {CKA_TOKEN, &true, sizeof(true)}, 7794 {CKA_SENSITIVE, &true, sizeof(true)}, 7795 {CKA_LABEL, label, sizeof(label)-1}, 7796 {CKA_SIGN, &true, sizeof(true)}, 7797 {CKA_VERIFY, &true, sizeof(true)}, 7798 {CKA_ID, keyId, sizeof(keyId)}, 7799 {CKA_OTP_FORMAT, &outputFormat, 7800 sizeof(outputFormat)}, 7801 {CKA_OTP_LENGTH, &outputLength, 7802 sizeof(outputLength)}, 7803 {CKA_OTP_COUNTER, counterValue, 7804 sizeof(counterValue)}, 7805 {CKA_VALUE, value, sizeof(value)} 7806 };
7807 2.53.10.2 ACTI key generation 7808 The ACTI key generation mechanism, denoted CKM_ACTI_KEY_GEN, is a key generation mechanism 7809 for the ACTI algorithm. 7810 It does not have a parameter. 7811 The mechanism generates ACTI keys with a particular set of attributes as specified in the template for the 7812 key. 7813 The mechanism contributes at least the CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE and 7814 CKA_VALUE_LEN attributes to the new key. Other attributes supported by the ACTI key type may be 7815 specified in the template for the key, or else are assigned default initial values. 7816 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7817 specify the supported range of ACTI key sizes, in bytes.
7818 2.53.10.3 ACTI OTP generation and validation 7819 CKM_ACTI is the mechanism for the retrieval and verification of ACTI OTP values. 7820 The mechanism takes a pointer to a CK_OTP_PARAMS structure as a parameter. 7821 When signing or verifying using the CKM_ACTI mechanism, pData shall be set to NULL_PTR and 7822 ulDataLen shall be set to 0. 7823 When verifying an OTP value using the CKM_ACTI mechanism, pSignature shall be set to the OTP value 7824 itself, e.g. the value of the CK_OTP_VALUE component of a CK_OTP_PARAM structure in the case of 7825 an earlier call to C_Sign.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 225 of 278 7826 2.54 CT-KIP
7827 2.54.1 Principles of Operation
Server Application Client Application
C_DeriveKey, C_WrapKey, C_Verify
PKCS #11 Library
Internal Token API
Token (or software version thereof) 7828 7829 Figure 4: PKCS #11 and CT-KIP integration 7830 Figure 4Error! Reference source not found. shows an integration of PKCS #11 into an application that 7831 generates cryptographic keys through the use of CT-KIP. The application invokes C_DeriveKey to derive 7832 a key of a particular type on the token. The key may subsequently be used as a basis to e.g., generate 7833 one-time password values. The application communicates with a CT-KIP server that participates in the 7834 key derivation and stores a copy of the key in its database. The key is transferred to the server in 7835 wrapped form, after a call to C_WrapKey. The server authenticates itself to the client and the client 7836 verifies the authentication by calls to C_Verify.
7837 2.54.2 Mechanisms 7838 The following table shows, for the mechanisms defined in this document, their support by different 7839 cryptographic operations. For any particular token, of course, a particular operation may well support 7840 only a subset of the mechanisms listed. There is also no guarantee that a token that supports one 7841 mechanism for some operation supports any other mechanism for any other operation (or even supports 7842 that same mechanism for any other operation). 7843 Table 200: CT-KIP Mechanisms vs. applicable functions
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 226 of 278 Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest & Derive Decrypt Verify VR1 Key/ Unwrap Key Pair CKM_KIP_DERIVE CKM_KIP_WRAP CKM_KIP_MAC 7844 The remainder of this section will present in detail the mechanisms and the parameters that are supplied 7845 to them.
7846 2.54.3 Definitions 7847 Mechanisms: 7848 CKM_KIP_DERIVE 7849 CKM_KIP_WRAP 7850 CKM_KIP_MAC
7851 2.54.4 CT-KIP Mechanism parameters
7852 CK_KIP_PARAMS; CK_KIP_PARAMS_PTR 7853 CK_KIP_PARAMS is a structure that provides the parameters to all the CT-KIP related mechanisms: The 7854 CKM_KIP_DERIVE key derivation mechanism, the CKM_KIP_WRAP key wrap and key unwrap 7855 mechanism, and the CKM_KIP_MAC signature mechanism. The structure is defined as follows: 7856 typedef struct CK_KIP_PARAMS { 7857 CK_MECHANISM_PTR pMechanism; 7858 CK_OBJECT_HANDLE hKey; 7859 CK_BYTE_PTR pSeed; 7860 CK_ULONG ulSeedLen; 7861 } CK_KIP_PARAMS; 7862 The fields of the structure have the following meanings: 7863 pMechanism pointer to the underlying cryptographic mechanism (e.g. AES, SHA- 7864 256), see further 0, Appendix D
7865 hKey handle to a key that will contribute to the entropy of the derived key 7866 (CKM_KIP_DERIVE) or will be used in the MAC operation 7867 (CKM_KIP_MAC)
7868 pSeed pointer to an input seed
7869 ulSeedLen length in bytes of the input seed
7870 CK_KIP_PARAMS_PTR is a pointer to a CK_KIP_PARAMS structure.
7871 2.54.5 CT-KIP key derivation 7872 The CT-KIP key derivation mechanism, denoted CKM_KIP_DERIVE, is a key derivation mechanism that 7873 is capable of generating secret keys of potentially any type, subject to token limitations.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 227 of 278 7874 It takes a parameter of type CK_KIP_PARAMS which allows for the passing of the desired underlying 7875 cryptographic mechanism as well as some other data. In particular, when the hKey parameter is a handle 7876 to an existing key, that key will be used in the key derivation in addition to the hBaseKey of C_DeriveKey. 7877 The pSeed parameter may be used to seed the key derivation operation. 7878 The mechanism derives a secret key with a particular set of attributes as specified in the attributes of the 7879 template for the key. 7880 The mechanism contributes the CKA_CLASS and CKA_VALUE attributes to the new key. Other 7881 attributes supported by the key type may be specified in the template for the key, or else will be assigned 7882 default initial values. Since the mechanism is generic, the CKA_KEY_TYPE attribute should be set in the 7883 template, if the key is to be used with a particular mechanism.
7884 2.54.6 CT-KIP key wrap and key unwrap 7885 The CT-KIP key wrap and unwrap mechanism, denoted CKM_KIP_WRAP, is a key wrap mechanism that 7886 is capable of wrapping and unwrapping generic secret keys. 7887 It takes a parameter of type CK_KIP_PARAMS, which allows for the passing of the desired underlying 7888 cryptographic mechanism as well as some other data. It does not make use of the hKey parameter of 7889 CK_KIP_PARAMS.
7890 2.54.7 CT-KIP signature generation 7891 The CT-KIP signature (MAC) mechanism, denoted CKM_KIP_MAC, is a mechanism used to produce a 7892 message authentication code of arbitrary length. The keys it uses are secret keys. 7893 It takes a parameter of type CK_KIP_PARAMS, which allows for the passing of the desired underlying 7894 cryptographic mechanism as well as some other data. The mechanism does not make use of the pSeed 7895 and the ulSeedLen parameters of CT_KIP_PARAMS. 7896 This mechanism produces a MAC of the length specified by pulSignatureLen parameter in calls to 7897 C_Sign. 7898 If a call to C_Sign with this mechanism fails, then no output will be generated.
7899 2.55 GOST 28147-89 7900 GOST 28147-89 is a block cipher with 64-bit block size and 256-bit keys. 7901 7902 Table 201, GOST 28147-89 Mechanisms vs. Functions
Mechanism Functions
Encrypt Sign SR Gen. Wrap & & & Digest Key/ & Derive Decrypt Verify VR Key Unwrap Pair CKM_GOST28147_KEY_GEN CKM_GOST28147_ECB CKM_GOST28147 CKM_GOST28147_MAC CKM_GOST28147_KEY_WRAP
7903
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 228 of 278 7904 2.55.1 Definitions 7905 This section defines the key type “CKK_GOST28147” for type CK_KEY_TYPE as used in the 7906 CKA_KEY_TYPE attribute of key objects and domain parameter objects. 7907 Mechanisms: 7908 CKM_GOST28147_KEY_GEN 7909 CKM_GOST28147_ECB 7910 CKM_GOST28147 7911 CKM_GOST28147_MAC 7912 CKM_GOST28147_KEY_WRAP
7913 2.55.2 GOST 28147-89 secret key objects 7914 GOST 28147-89 secret key objects (object class CKO_SECRET_KEY, key type CKK_GOST28147) hold 7915 GOST 28147-89 keys. The following table defines the GOST 28147-89 secret key object attributes, in 7916 addition to the common attributes defined for this object class: 7917 Table 202, GOST 28147-89 Secret Key Object Attributes
Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array 32 bytes in little endian order CKA_GOST28147_PARAMS1,3,5 Byte array DER-encoding of the object identifier indicating the data object type of GOST 28147-89. When key is used the domain parameter object of key type CKK_GOST28147 must be specified with the same attribute CKA_OBJECT_ID
7918 Refer to [PKCS11-Base] Table 11 for footnotes 7919 The following is a sample template for creating a GOST 28147-89 secret key object: 7920 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 7921 CK_KEY_TYPE keyType = CKK_GOST28147; 7922 CK_UTF8CHAR label[] = “A GOST 28147-89 secret key object”; 7923 CK_BYTE value[32] = {...}; 7924 CK_BYTE params_oid[] = {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 7925 0x02, 0x1f, 0x00}; 7926 CK_BBOOL true = CK_TRUE; 7927 CK_ATTRIBUTE template[] = { 7928 {CKA_CLASS, &class, sizeof(class)}, 7929 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 7930 {CKA_TOKEN, &true, sizeof(true)}, 7931 {CKA_LABEL, label, sizeof(label)-1}, 7932 {CKA_ENCRYPT, &true, sizeof(true)}, 7933 {CKA_GOST28147_PARAMS, params_oid, sizeof(params_oid)}, 7934 {CKA_VALUE, value, sizeof(value)} 7935 };
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 229 of 278 7936 2.55.3 GOST 28147-89 domain parameter objects 7937 GOST 28147-89 domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type 7938 CKK_GOST28147) hold GOST 28147-89 domain parameters. 7939 The following table defines the GOST 28147-89 domain parameter object attributes, in addition to the 7940 common attributes defined for this object class: 7941 Table 203, GOST 28147-89 Domain Parameter Object Attributes Attribute Data Type Meaning CKA_VALUE1 Byte array DER-encoding of the domain parameters as it was introduced in [4] section 8.1 (type Gost28147-89-ParamSetParameters) CKA_OBJECT_ID1 Byte array DER-encoding of the object identifier indicating the domain parameters 7942 Refer to [PKCS11-Base] Table 11 for footnotes 7943 For any particular token, there is no guarantee that a token supports domain parameters loading up 7944 and/or fetching out. Furthermore, applications, that make direct use of domain parameters objects, should 7945 take in account that CKA_VALUE attribute may be inaccessible. 7946 The following is a sample template for creating a GOST 28147-89 domain parameter object: 7947 CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS; 7948 CK_KEY_TYPE keyType = CKK_GOST28147; 7949 CK_UTF8CHAR label[] = “A GOST 28147-89 cryptographic 7950 parameters object”; 7951 CK_BYTE oid[] = {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 7952 0x1f, 0x00}; 7953 CK_BYTE value[] = { 7954 0x30,0x62,0x04,0x40,0x4c,0xde,0x38,0x9c,0x29,0x89,0xef,0xb6, 7955 0xff,0xeb,0x56,0xc5,0x5e,0xc2,0x9b,0x02,0x98,0x75,0x61,0x3b, 7956 0x11,0x3f,0x89,0x60,0x03,0x97,0x0c,0x79,0x8a,0xa1,0xd5,0x5d, 7957 0xe2,0x10,0xad,0x43,0x37,0x5d,0xb3,0x8e,0xb4,0x2c,0x77,0xe7, 7958 0xcd,0x46,0xca,0xfa,0xd6,0x6a,0x20,0x1f,0x70,0xf4,0x1e,0xa4, 7959 0xab,0x03,0xf2,0x21,0x65,0xb8,0x44,0xd8,0x02,0x01,0x00,0x02, 7960 0x01,0x40,0x30,0x0b,0x06,0x07,0x2a,0x85,0x03,0x02,0x02,0x0e, 7961 0x00,0x05,0x00 7962 }; 7963 CK_BBOOL true = CK_TRUE; 7964 CK_ATTRIBUTE template[] = { 7965 {CKA_CLASS, &class, sizeof(class)}, 7966 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 7967 {CKA_TOKEN, &true, sizeof(true)}, 7968 {CKA_LABEL, label, sizeof(label)-1}, 7969 {CKA_OBJECT_ID, oid, sizeof(oid)}, 7970 {CKA_VALUE, value, sizeof(value)} 7971 };
7972 2.55.4 GOST 28147-89 key generation 7973 The GOST 28147-89 key generation mechanism, denoted CKM_GOST28147_KEY_GEN, is a key 7974 generation mechanism for GOST 28147-89. 7975 It does not have a parameter.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 230 of 278 7976 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 7977 key. Other attributes supported by the GOST 28147-89 key type may be specified for objects of object 7978 class CKO_SECRET_KEY. 7979 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO are not 7980 used.
7981 2.55.5 GOST 28147-89-ECB 7982 GOST 28147-89-ECB, denoted CKM_GOST28147_ECB, is a mechanism for single and multiple-part 7983 encryption and decryption; key wrapping; and key unwrapping, based on GOST 28147-89 and electronic 7984 codebook mode. 7985 It does not have a parameter. 7986 This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 7987 wrap/unwrap every secret key that it supports. 7988 For wrapping (C_WrapKey), the mechanism encrypts the value of the CKA_VALUE attribute of the key 7989 that is wrapped, padded on the trailing end with up to block size so that the resulting length is a multiple 7990 of the block size. 7991 For unwrapping (C_UnwrapKey), the mechanism decrypts the wrapped key, and truncates the result 7992 according to the CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports 7993 it, the CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the 7994 CKA_VALUE attribute of the new key. 7995 Constraints on key types and the length of data are summarized in the following table: 7996 Table 204, GOST 28147-89-ECB: Key and Data Length
Function Key type Input length Output length C_Encrypt CKK_GOST28147 Multiple of Same as input length block size C_Decrypt CKK_GOST28147 Multiple of Same as input length block size C_WrapKey CKK_GOST28147 Input length rounded up to Any multiple of block size C_UnwrapKey CKK_GOST28147 Multiple of Determined by type of key block size being unwrapped
7997 7998 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7999 are not used.
8000 2.55.6 GOST 28147-89 encryption mode except ECB 8001 GOST 28147-89 encryption mode except ECB, denoted CKM_GOST28147, is a mechanism for single 8002 and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on 8003 [GOST 28147-89] and CFB, counter mode, and additional CBC mode defined in [RFC 4357] section 2. 8004 Encryption’s parameters are specified in object identifier of attribute CKA_GOST28147_PARAMS. 8005 It has a parameter, which is an 8-byte initialization vector. This parameter may be omitted then a zero 8006 initialization vector is used. 8007 This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 8008 wrap/unwrap every secret key that it supports. 8009 For wrapping (C_WrapKey), the mechanism encrypts the value of the CKA_VALUE attribute of the key 8010 that is wrapped.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 231 of 278 8011 For unwrapping (C_UnwrapKey), the mechanism decrypts the wrapped key, and contributes the result as 8012 the CKA_VALUE attribute of the new key. 8013 Constraints on key types and the length of data are summarized in the following table: 8014 Table 205, GOST 28147-89 encryption modes except ECB: Key and Data Length
Input Function Key type Output length length
C_Encrypt CKK_GOST28147 Any For counter mode and CFB is the same as input length. For C_Decrypt CKK_GOST28147 Any CBC is the same as input length padded on the trailing end with C_WrapKey CKK_GOST28147 Any up to block size so that the resulting length is a multiple of C_UnwrapKey CKK_GOST28147 Any the block size
8015 8016 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8017 are not used.
8018 2.55.7 GOST 28147-89-MAC 8019 GOST 28147-89-MAC, denoted CKM_GOST28147_MAC, is a mechanism for data integrity and 8020 authentication based on GOST 28147-89 and key meshing algorithms [RFC 4357] section 2.3. 8021 MACing parameters are specified in object identifier of attribute CKA_GOST28147_PARAMS. 8022 The output bytes from this mechanism are taken from the start of the final GOST 28147-89 cipher block 8023 produced in the MACing process. 8024 It has a parameter, which is an 8-byte MAC initialization vector. This parameter may be omitted then a 8025 zero initialization vector is used. 8026 Constraints on key types and the length of data are summarized in the following table: 8027 Table 206, GOST28147-89-MAC: Key and Data Length
Function Key type Data length Signature length C_Sign CKK_GOST28147 Any 4 bytes C_Verify CKK_GOST28147 Any 4 bytes
8028 8029 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8030 are not used. 8031
8032 2.55.8 GOST 28147-89 keys wrapping/unwrapping with GOST 28147-89 8033 GOST 28147-89 keys as a KEK (key encryption keys) for encryption GOST 28147-89 keys, denoted by 8034 CKM_GOST28147_KEY_WRAP, is a mechanism for key wrapping; and key unwrapping, based on 8035 GOST 28147-89. Its purpose is to encrypt and decrypt keys have been generated by key generation 8036 mechanism for GOST 28147-89. 8037 For wrapping (C_WrapKey), the mechanism first computes MAC from the value of the CKA_VALUE 8038 attribute of the key that is wrapped and then encrypts in ECB mode the value of the CKA_VALUE 8039 attribute of the key that is wrapped. The result is 32 bytes of the key that is wrapped and 4 bytes of MAC. 8040 For unwrapping (C_UnwrapKey), the mechanism first decrypts in ECB mode the 32 bytes of the key that 8041 was wrapped and then computes MAC from the unwrapped key. Then compared together 4 bytes MAC
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 232 of 278 8042 has computed and 4 bytes MAC of the input. If these two MACs do not match the wrapped key is 8043 disallowed. The mechanism contributes the result as the CKA_VALUE attribute of the unwrapped key. 8044 It has a parameter, which is an 8-byte MAC initialization vector. This parameter may be omitted then a 8045 zero initialization vector is used. 8046 Constraints on key types and the length of data are summarized in the following table: 8047 Table 207, GOST 28147-89 keys as KEK: Key and Data Length
Function Key type Input length Output length
C_WrapKey CKK_GOST28147 32 bytes 36 bytes C_UnwrapKey CKK_GOST28147 32 bytes 36 bytes
8048 8049 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8050 are not used. 8051
8052 2.56 GOST R 34.11-94 8053 GOST R 34.11-94 is a mechanism for message digesting, following the hash algorithm with 256-bit 8054 message digest defined in [GOST R 34.11-94]. 8055 8056 Table 208, GOST R 34.11-94 Mechanisms vs. Functions
Mechanism Functions
Encrypt Sign SR Gen. Wrap & & & Digest Key/ & Derive Decrypt Verify VR Key Unwrap Pair CKM_GOSTR3411 CKM_GOSTR3411_HMAC
8057
8058 2.56.1 Definitions 8059 This section defines the key type “CKK_GOSTR3411” for type CK_KEY_TYPE as used in the 8060 CKA_KEY_TYPE attribute of domain parameter objects. 8061 Mechanisms: 8062 CKM_GOSTR3411 8063 CKM_GOSTR3411_HMAC
8064 2.56.2 GOST R 34.11-94 domain parameter objects 8065 GOST R 34.11-94 domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type 8066 CKK_GOSTR3411) hold GOST R 34.11-94 domain parameters. 8067 The following table defines the GOST R 34.11-94 domain parameter object attributes, in addition to the 8068 common attributes defined for this object class: 8069 Table 209, GOST R 34.11-94 Domain Parameter Object Attributes
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 233 of 278 Attribute Data Type Meaning CKA_VALUE1 Byte array DER-encoding of the domain parameters as it was introduced in [4] section 8.2 (type GostR3411-94-ParamSetParameters) CKA_OBJECT_ID1 Byte array DER-encoding of the object identifier indicating the domain parameters 8070 Refer to [PKCS11-Base] Table 11 for footnotes 8071 For any particular token, there is no guarantee that a token supports domain parameters loading up 8072 and/or fetching out. Furthermore, applications, that make direct use of domain parameters objects, should 8073 take in account that CKA_VALUE attribute may be inaccessible. 8074 The following is a sample template for creating a GOST R 34.11-94 domain parameter object: 8075 CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS; 8076 CK_KEY_TYPE keyType = CKK_GOSTR3411; 8077 CK_UTF8CHAR label[] = “A GOST R34.11-94 cryptographic 8078 parameters object”; 8079 CK_BYTE oid[] = {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 8080 0x1e, 0x00}; 8081 CK_BYTE value[] = { 8082 0x30,0x64,0x04,0x40,0x4e,0x57,0x64,0xd1,0xab,0x8d,0xcb,0xbf, 8083 0x94,0x1a,0x7a,0x4d,0x2c,0xd1,0x10,0x10,0xd6,0xa0,0x57,0x35, 8084 0x8d,0x38,0xf2,0xf7,0x0f,0x49,0xd1,0x5a,0xea,0x2f,0x8d,0x94, 8085 0x62,0xee,0x43,0x09,0xb3,0xf4,0xa6,0xa2,0x18,0xc6,0x98,0xe3, 8086 0xc1,0x7c,0xe5,0x7e,0x70,0x6b,0x09,0x66,0xf7,0x02,0x3c,0x8b, 8087 0x55,0x95,0xbf,0x28,0x39,0xb3,0x2e,0xcc,0x04,0x20,0x00,0x00, 8088 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, 8089 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, 8090 0x00,0x00,0x00,0x00,0x00,0x00 8091 }; 8092 CK_BBOOL true = CK_TRUE; 8093 CK_ATTRIBUTE template[] = { 8094 {CKA_CLASS, &class, sizeof(class)}, 8095 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 8096 {CKA_TOKEN, &true, sizeof(true)}, 8097 {CKA_LABEL, label, sizeof(label)-1}, 8098 {CKA_OBJECT_ID, oid, sizeof(oid)}, 8099 {CKA_VALUE, value, sizeof(value)} 8100 };
8101 2.56.3 GOST R 34.11-94 digest 8102 GOST R 34.11-94 digest, denoted CKM_GOSTR3411, is a mechanism for message digesting based on 8103 GOST R 34.11-94 hash algorithm [GOST R 34.11-94]. 8104 As a parameter this mechanism utilizes a DER-encoding of the object identifier. A mechanism parameter 8105 may be missed then parameters of the object identifier id-GostR3411-94-CryptoProParamSet [RFC 4357] 8106 (section 11.2) must be used. 8107 Constraints on the length of input and output data are summarized in the following table. For single-part 8108 digesting, the data and the digest may begin at the same location in memory. 8109 Table 210, GOST R 34.11-94: Data Length
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 234 of 278 Function Input length Digest length C_Digest Any 32 bytes 8110 8111 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8112 are not used.
8113 2.56.4 GOST R 34.11-94 HMAC 8114 GOST R 34.11-94 HMAC mechanism, denoted CKM_GOSTR3411_HMAC, is a mechanism for 8115 signatures and verification. It uses the HMAC construction, based on the GOST R 34.11-94 hash 8116 function [GOST R 34.11-94] and core HMAC algorithm [RFC 2104]. The keys it uses are of generic key 8117 type CKK_GENERIC_SECRET or CKK_GOST28147. 8118 To be conformed to GOST R 34.11-94 hash algorithm [GOST R 34.11-94] the block length of core HMAC 8119 algorithm is 32 bytes long (see [RFC 2104] section 2, and [RFC 4357] section 3). 8120 As a parameter this mechanism utilizes a DER-encoding of the object identifier. A mechanism parameter 8121 may be missed then parameters of the object identifier id-GostR3411-94-CryptoProParamSet [RFC 4357] 8122 (section 11.2) must be used. 8123 Signatures (MACs) produced by this mechanism are of 32 bytes long. 8124 Constraints on the length of input and output data are summarized in the following table: 8125 Table 211, GOST R 34.11-94 HMAC: Key And Data Length Function Key type Data length Signature length C_Sign CKK_GENERIC_SECRET or Any 32 byte CKK_GOST28147 C_Verify CKK_GENERIC_SECRET or Any 32 bytes CKK_GOST28147 8126 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8127 are not used.
8128 2.57 GOST R 34.10-2001 8129 GOST R 34.10-2001 is a mechanism for single- and multiple-part signatures and verification, following 8130 the digital signature algorithm defined in [GOST R 34.10-2001]. 8131 8132 Table 212, GOST R34.10-2001 Mechanisms vs. Functions
Mechanism Functions
Encrypt Sign SR Gen. Wrap & & & Digest Key/ & Derive Decrypt Verify VR Key Unwrap Pair CKM_GOSTR3410_KEY_PAIR_GEN CKM_GOSTR3410 1 CKM_GOSTR3410_WITH_GOST3411 CKM_GOSTR3410_KEY_WRAP CKM_GOSTR3410_DERIVE
8133 1 Single-part operations only 8134
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 235 of 278 8135 2.57.1 Definitions 8136 This section defines the key type “CKK_GOSTR3410” for type CK_KEY_TYPE as used in the 8137 CKA_KEY_TYPE attribute of key objects and domain parameter objects. 8138 Mechanisms: 8139 CKM_GOSTR3410_KEY_PAIR_GEN 8140 CKM_GOSTR3410 8141 CKM_GOSTR3410_WITH_GOSTR3411 8142 CKM_GOSTR3410 8143 CKM_GOSTR3410_KEY_WRAP 8144 CKM_GOSTR3410_DERIVE
8145 2.57.2 GOST R 34.10-2001 public key objects 8146 GOST R 34.10-2001 public key objects (object class CKO_PUBLIC_KEY, key type CKK_GOSTR3410) 8147 hold GOST R 34.10-2001 public keys. 8148 The following table defines the GOST R 34.10-2001 public key object attributes, in addition to the 8149 common attributes defined for this object class: 8150 Table 213, GOST R 34.10-2001 Public Key Object Attributes Attribute Data Type Meaning CKA_VALUE1,4 Byte array 64 bytes for public key; 32 bytes for each coordinates X and Y of elliptic curve point P(X, Y) in little endian order 1,3 CKA_GOSTR3410_PARAMS Byte array DER-encoding of the object identifier indicating the data object type of GOST R 34.10-2001. When key is used the domain parameter object of key type CKK_GOSTR3410 must be specified with the same attribute CKA_OBJECT_ID 1,3,8 CKA_GOSTR3411_PARAMS Byte array DER-encoding of the object identifier indicating the data object type of GOST R 34.11-94. When key is used the domain parameter object of key type CKK_GOSTR3411 must be specified with the same attribute CKA_OBJECT_ID 8 CKA_GOST28147_PARAMS Byte array DER-encoding of the object identifier indicating the data object type of GOST 28147-89. When key is used the domain parameter object of key type CKK_GOST28147 must be specified with the same attribute CKA_OBJECT_ID. The attribute value may be omitted 8151 Refer to [PKCS11-Base] Table 11 for footnotes 8152 The following is a sample template for creating an GOST R 34.10-2001 public key object: 8153 CK_OBJECT_CLASS class = CKO_PUBLIC_KEY; 8154 CK_KEY_TYPE keyType = CKK_GOSTR3410;
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 236 of 278 8155 CK_UTF8CHAR label[] = “A GOST R34.10-2001 public key object”; 8156 CK_BYTE gostR3410params_oid[] = 8157 {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x00}; 8158 CK_BYTE gostR3411params_oid[] = 8159 {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1e, 0x00}; 8160 CK_BYTE gost28147params_oid[] = 8161 {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x00}; 8162 CK_BYTE value[64] = {...}; 8163 CK_BBOOL true = CK_TRUE; 8164 CK_ATTRIBUTE template[] = { 8165 {CKA_CLASS, &class, sizeof(class)}, 8166 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 8167 {CKA_TOKEN, &true, sizeof(true)}, 8168 {CKA_LABEL, label, sizeof(label)-1}, 8169 {CKA_GOSTR3410_PARAMS, gostR3410params_oid, 8170 sizeof(gostR3410params_oid)}, 8171 {CKA_GOSTR3411_PARAMS, gostR3411params_oid, 8172 sizeof(gostR3411params_oid)}, 8173 {CKA_GOST28147_PARAMS, gost28147params_oid, 8174 sizeof(gost28147params_oid)}, 8175 {CKA_VALUE, value, sizeof(value)} 8176 };
8177 2.57.3 GOST R 34.10-2001 private key objects 8178 GOST R 34.10-2001 private key objects (object class CKO_PRIVATE_KEY, key type 8179 CKK_GOSTR3410) hold GOST R 34.10-2001 private keys. 8180 The following table defines the GOST R 34.10-2001 private key object attributes, in addition to the 8181 common attributes defined for this object class: 8182 Table 214, GOST R 34.10-2001 Private Key Object Attributes
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 237 of 278 Attribute Data Type Meaning CKA_VALUE1,4,6,7 Byte array 32 bytes for private key in little endian order 1,4,6 CKA_GOSTR3410_PARAMS Byte array DER-encoding of the object identifier indicating the data object type of GOST R 34.10-2001. When key is used the domain parameter object of key type CKK_GOSTR3410 must be specified with the same attribute CKA_OBJECT_ID 1,4,6,8 CKA_GOSTR3411_PARAMS Byte array DER-encoding of the object identifier indicating the data object type of GOST R 34.11-94. When key is used the domain parameter object of key type CKK_GOSTR3411 must be specified with the same attribute CKA_OBJECT_ID 4,6,8 CKA_GOST28147_PARAMS4 Byte array DER-encoding of the object identifier indicating the data object type of GOST 28147-89. When key is used the domain parameter object of key type CKK_GOST28147 must be specified with the same attribute CKA_OBJECT_ID. The attribute value may be omitted
8183 Refer to [PKCS11-Base] Table 11 for footnotes 8184 Note that when generating an GOST R 34.10-2001 private key, the GOST R 34.10-2001 domain 8185 parameters are not specified in the key’s template. This is because GOST R 34.10-2001 private keys are 8186 only generated as part of an GOST R 34.10-2001 key pair, and the GOST R 34.10-2001 domain 8187 parameters for the pair are specified in the template for the GOST R 34.10-2001 public key. 8188 The following is a sample template for creating an GOST R 34.10-2001 private key object: 8189 CK_OBJECT_CLASS class = CKO_PRIVATE_KEY; 8190 CK_KEY_TYPE keyType = CKK_GOSTR3410; 8191 CK_UTF8CHAR label[] = “A GOST R34.10-2001 private key 8192 object”; 8193 CK_BYTE subject[] = {...}; 8194 CK_BYTE id[] = {123}; 8195 CK_BYTE gostR3410params_oid[] = 8196 {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x00}; 8197 CK_BYTE gostR3411params_oid[] = 8198 {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1e, 0x00}; 8199 CK_BYTE gost28147params_oid[] = 8200 {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x00}; 8201 CK_BYTE value[32] = {...}; 8202 CK_BBOOL true = CK_TRUE; 8203 CK_ATTRIBUTE template[] = {
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 238 of 278 8204 {CKA_CLASS, &class, sizeof(class)}, 8205 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 8206 {CKA_TOKEN, &true, sizeof(true)}, 8207 {CKA_LABEL, label, sizeof(label)-1}, 8208 {CKA_SUBJECT, subject, sizeof(subject)}, 8209 {CKA_ID, id, sizeof(id)}, 8210 {CKA_SENSITIVE, &true, sizeof(true)}, 8211 {CKA_SIGN, &true, sizeof(true)}, 8212 {CKA_GOSTR3410_PARAMS, gostR3410params_oid, 8213 sizeof(gostR3410params_oid)}, 8214 {CKA_GOSTR3411_PARAMS, gostR3411params_oid, 8215 sizeof(gostR3411params_oid)}, 8216 {CKA_GOST28147_PARAMS, gost28147params_oid, 8217 sizeof(gost28147params_oid)}, 8218 {CKA_VALUE, value, sizeof(value)} 8219 }; 8220
8221 2.57.4 GOST R 34.10-2001 domain parameter objects 8222 GOST R 34.10-2001 domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type 8223 CKK_GOSTR3410) hold GOST R 34.10-2001 domain parameters. 8224 The following table defines the GOST R 34.10-2001 domain parameter object attributes, in addition to the 8225 common attributes defined for this object class: 8226 Table 215, GOST R 34.10-2001 Domain Parameter Object Attributes Attribute Data Type Meaning CKA_VALUE1 Byte array DER-encoding of the domain parameters as it was introduced in [4] section 8.4 (type GostR3410-2001-ParamSetParameters) CKA_OBJECT_ID1 Byte array DER-encoding of the object identifier indicating the domain parameters 8227 Refer to [PKCS11-Base] Table 11 for footnotes 8228 For any particular token, there is no guarantee that a token supports domain parameters loading up 8229 and/or fetching out. Furthermore, applications, that make direct use of domain parameters objects, should 8230 take in account that CKA_VALUE attribute may be inaccessible. 8231 The following is a sample template for creating a GOST R 34.10-2001 domain parameter object: 8232 CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS; 8233 CK_KEY_TYPE keyType = CKK_GOSTR3410; 8234 CK_UTF8CHAR label[] = “A GOST R34.10-2001 cryptographic 8235 parameters object”; 8236 CK_BYTE oid[] = 8237 {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x00}; 8238 CK_BYTE value[] = { 8239 0x30,0x81,0x90,0x02,0x01,0x07,0x02,0x20,0x5f,0xbf,0xf4,0x98, 8240 0xaa,0x93,0x8c,0xe7,0x39,0xb8,0xe0,0x22,0xfb,0xaf,0xef,0x40, 8241 0x56,0x3f,0x6e,0x6a,0x34,0x72,0xfc,0x2a,0x51,0x4c,0x0c,0xe9, 8242 0xda,0xe2,0x3b,0x7e,0x02,0x21,0x00,0x80,0x00,0x00,0x00,0x00, 8243 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 239 of 278 8244 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, 8245 0x00,0x04,0x31,0x02,0x21,0x00,0x80,0x00,0x00,0x00,0x00,0x00, 8246 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01,0x50,0xfe, 8247 0x8a,0x18,0x92,0x97,0x61,0x54,0xc5,0x9c,0xfc,0x19,0x3a,0xcc, 8248 0xf5,0xb3,0x02,0x01,0x02,0x02,0x20,0x08,0xe2,0xa8,0xa0,0xe6, 8249 0x51,0x47,0xd4,0xbd,0x63,0x16,0x03,0x0e,0x16,0xd1,0x9c,0x85, 8250 0xc9,0x7f,0x0a,0x9c,0xa2,0x67,0x12,0x2b,0x96,0xab,0xbc,0xea, 8251 0x7e,0x8f,0xc8 8252 }; 8253 CK_BBOOL true = CK_TRUE; 8254 CK_ATTRIBUTE template[] = { 8255 {CKA_CLASS, &class, sizeof(class)}, 8256 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 8257 {CKA_TOKEN, &true, sizeof(true)}, 8258 {CKA_LABEL, label, sizeof(label)-1}, 8259 {CKA_OBJECT_ID, oid, sizeof(oid)}, 8260 {CKA_VALUE, value, sizeof(value)} 8261 }; 8262
8263 2.57.5 GOST R 34.10-2001 mechanism parameters 8264 ♦ CK_GOSTR3410_KEY_WRAP_PARAMS 8265 CK_GOSTR3410_KEY_WRAP_PARAMS is a structure that provides the parameters to the 8266 CKM_GOSTR3410_KEY_WRAP mechanism. It is defined as follows: 8267 typedef struct CK_GOSTR3410_KEY_WRAP_PARAMS { 8268 CK_BYTE_PTR pWrapOID; 8269 CK_ULONG ulWrapOIDLen; 8270 CK_BYTE_PTR pUKM; 8271 CK_ULONG ulUKMLen; 8272 CK_OBJECT_HANDLE hKey; 8273 } CK_GOSTR3410_KEY_WRAP_PARAMS; 8274 8275 The fields of the structure have the following meanings:
pWrapOID pointer to a data with DER-encoding of the object identifier indicating the data object type of GOST 28147-89. If pointer takes NULL_PTR value in C_WrapKey operation then parameters are specified in object identifier of attribute CKA_GOSTR3411_PARAMS must be used. For C_UnwrapKey operation the pointer is not used and must take NULL_PTR value anytime
ulWrapOIDLen length of data with DER-encoding of the object identifier indicating the data object type of GOST 28147-89
pUKM pointer to a data with UKM. If pointer takes NULL_PTR value in C_WrapKey operation then random value of UKM will be used. If pointer takes non-NULL_PTR value in C_UnwrapKey operation then the pointer value will be
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 240 of 278 compared with UKM value of wrapped key. If these two values do not match the wrapped key will be rejected
ulUKMLen length of UKM data. If pUKM-pointer is different from NULL_PTR then equal to 8
hKey key handle. Key handle of a sender for C_WrapKey operation. Key handle of a receiver for C_UnwrapKey operation. When key handle takes CK_INVALID_HANDLE value then an ephemeral (one time) key pair of a sender will be used
8276 ♦ CK_GOSTR3410_DERIVE_PARAMS 8277 CK_GOSTR3410_DERIVE_PARAMS is a structure that provides the parameters to the 8278 CKM_GOSTR3410_DERIVE mechanism. It is defined as follows: 8279 typedef struct CK_GOSTR3410_DERIVE_PARAMS { 8280 CK_EC_KDF_TYPE kdf; 8281 CK_BYTE_PTR pPublicData; 8282 CK_ULONG ulPublicDataLen; 8283 CK_BYTE_PTR pUKM; 8284 CK_ULONG ulUKMLen; 8285 } CK_GOSTR3410_DERIVE_PARAMS; 8286 8287 The fields of the structure have the following meanings:
kdf additional key diversification algorithm identifier. Possible values are CKD_NULL and CKD_CPDIVERSIFY_KDF. In case of CKD_NULL, result of the key derivation function described in [RFC 4357], section 5.2 is used directly; In case of CKD_CPDIVERSIFY_KDF, the resulting key value is additionally processed with algorithm from [RFC 4357], section 6.5.
pPublicData1 pointer to data with public key of a receiver
ulPublicDataLen length of data with public key of a receiver (must be 64)
pUKM pointer to a UKM data
ulUKMLen length of UKM data in bytes (must be 8) 8288 8289 1 Public key of a receiver is an octet string of 64 bytes long. The public key octets correspond to the concatenation of X and Y coordinates of a point. Any one of 8290 them is 32 bytes long and represented in little endian order.
8291 2.57.6 GOST R 34.10-2001 key pair generation 8292 The GOST R 34.10-2001 key pair generation mechanism, denoted 8293 CKM_GOSTR3410_KEY_PAIR_GEN, is a key pair generation mechanism for GOST R 34.10-2001. 8294 This mechanism does not have a parameter. 8295 The mechanism generates GOST R 34.10-2001 public/private key pairs with particular 8296 GOST R 34.10-2001 domain parameters, as specified in the CKA_GOSTR3410_PARAMS,
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 241 of 278 8297 CKA_GOSTR3411_PARAMS, and CKA_GOST28147_PARAMS attributes of the template for the public 8298 key. Note that CKA_GOST28147_PARAMS attribute may not be present in the template. 8299 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 8300 public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE, and CKA_GOSTR3410_PARAMS, 8301 CKA_GOSTR3411_PARAMS, CKA_GOST28147_PARAMS attributes to the new private key. 8302 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8303 are not used.
8304 2.57.7 GOST R 34.10-2001 without hashing 8305 The GOST R 34.10-2001 without hashing mechanism, denoted CKM_GOSTR3410, is a mechanism for 8306 single-part signatures and verification for GOST R 34.10-2001. (This mechanism corresponds only to the 8307 part of GOST R 34.10-2001 that processes the 32-bytes hash value; it does not compute the hash value.) 8308 This mechanism does not have a parameter. 8309 For the purposes of these mechanisms, a GOST R 34.10-2001 signature is an octet string of 64 bytes 8310 long. The signature octets correspond to the concatenation of the GOST R 34.10-2001 values s and r’, 8311 both represented as a 32 bytes octet string in big endian order with the most significant byte first [RFC 8312 4490] section 3.2, and [RFC 4491] section 2.2.2. 8313 The input for the mechanism is an octet string of 32 bytes long with digest has computed by means of 8314 GOST R 34.11-94 hash algorithm in the context of signed or should be signed message. 8315 Table 216, GOST R 34.10-2001 without hashing: Key and Data Length Function Key type Input length Output length C_Sign1 CKK_GOSTR3410 32 bytes 64 bytes C_Verify1 CKK_GOSTR3410 32 bytes 64 bytes 8316 1 Single-part operations only. 8317 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8318 are not used.
8319 2.57.8 GOST R 34.10-2001 with GOST R 34.11-94 8320 The GOST R 34.10-2001 with GOST R 34.11-94, denoted CKM_GOSTR3410_WITH_GOSTR3411, is a 8321 mechanism for signatures and verification for GOST R 34.10-2001. This mechanism computes the entire 8322 GOST R 34.10-2001 specification, including the hashing with GOST R 34.11-94 hash algorithm. 8323 As a parameter this mechanism utilizes a DER-encoding of the object identifier indicating 8324 GOST R 34.11-94 data object type. A mechanism parameter may be missed then parameters are 8325 specified in object identifier of attribute CKA_GOSTR3411_PARAMS must be used. 8326 For the purposes of these mechanisms, a GOST R 34.10-2001 signature is an octet string of 64 bytes 8327 long. The signature octets correspond to the concatenation of the GOST R 34.10-2001 values s and r’, 8328 both represented as a 32 bytes octet string in big endian order with the most significant byte first [RFC 8329 4490] section 3.2, and [RFC 4491] section 2.2.2. 8330 The input for the mechanism is signed or should be signed message of any length. Single- and multiple- 8331 part signature operations are available. 8332 Table 217, GOST R 34.10-2001 with GOST R 34.11-94: Key and Data Length Function Key type Input length Output length C_Sign CKK_GOSTR3410 Any 64 bytes C_Verify CKK_GOSTR3410 Any 64 bytes 8333 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8334 are not used.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 242 of 278 8335 2.57.9 GOST 28147-89 keys wrapping/unwrapping with GOST R 34.10-2001 8336 GOST R 34.10-2001 keys as a KEK (key encryption keys) for encryption GOST 28147 keys, denoted by 8337 CKM_GOSTR3410_KEY_WRAP, is a mechanism for key wrapping; and key unwrapping, based on 8338 GOST R 34.10-2001. Its purpose is to encrypt and decrypt keys have been generated by key generation 8339 mechanism for GOST 28147-89. An encryption algorithm from [RFC 4490] (section 5.2) must be used. 8340 Encrypted key is a DER-encoded structure of ASN.1 GostR3410-KeyTransport type [RFC 4490] section 8341 4.2. 8342 It has a parameter, a CK_GOSTR3410_KEY_WRAP_PARAMS structure defined in section 2.57.5. 8343 For unwrapping (C_UnwrapKey), the mechanism decrypts the wrapped key, and contributes the result as 8344 the CKA_VALUE attribute of the new key. 8345 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8346 are not used.
8347 2.57.10 Common key derivation with assistance of GOST R 34.10-2001 keys 8348 Common key derivation, denoted CKM_GOSTR3410_DERIVE, is a mechanism for key derivation with 8349 assistance of GOST R 34.10-2001 private and public keys. The key of the mechanism must be of object 8350 class CKO_DOMAIN_PARAMETERS and key type CKK_GOSTR3410. An algorithm for key derivation 8351 from [RFC 4357] (section 5.2) must be used. 8352 The mechanism contributes the result as the CKA_VALUE attribute of the new private key. All other 8353 attributes must be specified in a template for creating private key object.
8354 2.58 ChaCha20 8355 ChaCha20 is a secret-key stream cipher described in [CHACHA]. 8356 Table 218, ChaCha20 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Key/ & Derive Digest Decrypt Verify 1 Key Unwrap VR Pair CKM_CHACHA20_KEY_GEN ✓ CKM_CHACHA20 ✓ ✓ 8357
8358 2.58.1 Definitions 8359 This section defines the key type “CKK_CHACHA20” for type CK_KEY_TYPE as used in the 8360 CKA_KEY_TYPE attribute of key objects. 8361 Mechanisms: 8362 CKM_CHACHA20_KEY_GEN 8363 CKM_CHACHA20
8364 2.58.2 ChaCha20 secret key objects 8365 ChaCha20 secret key objects (object class CKO_SECRET_KEY, key type CKK_CHACHA) hold 8366 ChaCha20 keys. The following table defines the ChaCha20 secret key object attributes, in addition to the 8367 common attributes defined for this object class: 8368 Table 219, ChaCha20 Secret Key Object
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 243 of 278 Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key length is fixed at 256 bits. Bit length restricted to a byte array. CKA_VALUE_LEN2,3 CK_ULONG Length in bytes of key value 8369 The following is a sample template for creating a ChaCha20 secret key object: 8370 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 8371 CK_KEY_TYPE keyType = CKK_CHACHA20; 8372 CK_UTF8CHAR label[] = “A ChaCha20 secret key object”; 8373 CK_BYTE value[32] = {...}; 8374 CK_BBOOL true = CK_TRUE; 8375 CK_ATTRIBUTE template[] = { 8376 {CKA_CLASS, &class, sizeof(class)}, 8377 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 8378 {CKA_TOKEN, &true, sizeof(true)}, 8379 {CKA_LABEL, label, sizeof(label)-1}, 8380 {CKA_ENCRYPT, &true, sizeof(true)}, 8381 {CKA_VALUE, value, sizeof(value)} 8382 }; 8383 CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first 8384 three bytes of the SHA-1 hash of the ChaCha20 secret key object’s CKA_VALUE attribute.
8385 2.58.3 ChaCha20 mechanism parameters
8386 CK_CHACHA20_PARAMS; CK_CHACHA20_PARAMS_PTR 8387 CK_CHACHA20_PARAMS provides the parameters to the CKM_CHACHA20 mechanism. It is defined 8388 as follows: 8389 typedef struct CK_CHACHA20_PARAMS { 8390 CK_BYTE_PTR pBlockCounter; 8391 CK_ULONG blockCounterBits; 8392 CK_BYTE_PTR pNonce; 8393 CK_ULONG ulNonceBits; 8394 } CK_CHACHA20_PARAMS; 8395 The fields of the structure have the following meanings: 8396 pBlockCounter pointer to block counter
8397 ulblockCounterBits length of block counter in bits (can be either 32 or 64)
8398 pNonce nonce (This should be never re-used with the same key.)
8399 ulNonceBits length of nonce in bits (is 64 for original, 96 for IETF and 192 for 8400 xchacha20 variant)
8401 The block counter is used to address 512 bit blocks in the stream. In certain settings (e.g. disk encryption) 8402 it is necessary to address these blocks in random order, thus this counter is exposed here.
8403 2.58.4 ChaCha20 key generation 8404 The ChaCha20 key generation mechanism, denoted CKM_CHACHA20_KEY_GEN, is a key generation 8405 mechanism for ChaCha20. pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 244 of 278 8406 It does not have a parameter. 8407 The mechanism generates ChaCha20 keys of 256 bits. 8408 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 8409 key. Other attributes supported by the key type (specifically, the flags indicating which functions the key 8410 supports) may be specified in the template for the key, or else are assigned default initial values. 8411 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8412 specify the supported range of key sizes in bytes. As a practical matter, the key size for ChaCha20 is 8413 fixed at 256 bits. 8414
8415 2.58.5 ChaCha20 mechanism 8416 ChaCha20, denoted CKM_CHACHA20, is a mechanism for single and multiple-part encryption and 8417 decryption based on the ChaCha20 stream cipher. It comes in 3 variants, which only differ in the size and 8418 handling of their nonces, affecting the safety of using random nonces and the maximum size that can be 8419 encrypted safely. 8420 Chacha20 has a parameter, CK_CHACHA20_PARAMS, which indicates the nonce and initial block 8421 counter value. 8422 Constraints on key types and the length of input and output data are summarized in the following table: 8423 Table 220, ChaCha20: Key and Data Length
Function Key type Input length Output length Comments
C_Encrypt ChaCha20 Any / only Same as input length No final part up to 256 GB in case of IETF variant
C_Decrypt ChaCha20 Any / only Same as input length No final part up to 256 GB in case of IETF variant
8424 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8425 specify the supported range of ChaCha20 key sizes, in bits. 8426 Table 221, ChaCha20: Nonce and block counter lengths
Variant Nonce Block Maximum message Nonce counter generation
original 64 bit 64 bit Virtually unlimited 1st msg: nonce0=rand om nth msg: noncen-1++ IETF 96 bit 32 bit Max ~256 GB 1st msg: nonce0=rand om nth msg: noncen-1++
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 245 of 278 XChaCha 192 bit 64 bit Virtually unlimited Each nonce 20 can be randomly generated.
8427 Nonces must not ever be reused with the same key. However due to the birthday paradox the first two 8428 variants cannot guarantee that randomly generated nonces are never repeating. Thus the recommended 8429 way to handle this is to generate the first nonce randomly, then increase this for follow-up messages. 8430 Only the last (XChaCha20) has large enough nonces so that it is virtually impossible to trigger with 8431 randomly generated nonces the birthday paradox.
8432 2.59 Salsa20 8433 Salsa20 is a secret-key stream cipher described in [SALSA]. 8434 Table 222, Salsa20 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Key/ & Derive Digest Decrypt Verify 1 Key Unwrap VR Pair CKM_SALSA20_KEY_GEN ✓ CKM_SALSA20 ✓ ✓ 8435
8436 2.59.1 Definitions 8437 This section defines the key type “CKK_SALSA20” and “CKK_SALSA20” for type CK_KEY_TYPE as 8438 used in the CKA_KEY_TYPE attribute of key objects. 8439 Mechanisms: 8440 CKM_SALSA20_KEY_GEN 8441 CKM_SALSA20
8442 2.59.2 Salsa20 secret key objects 8443 Salsa20 secret key objects (object class CKO_SECRET_KEY, key type CKK_SALSA) hold Salsa20 keys. 8444 The following table defines the Salsa20 secret key object attributes, in addition to the common attributes 8445 defined for this object class: 8446 Table 223, ChaCha20 Secret Key Object Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key length is fixed at 256 bits. Bit length restricted to a byte array. CKA_VALUE_LEN2,3 CK_ULONG Length in bytes of key value 8447 The following is a sample template for creating a Salsa20 secret key object: 8448 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 8449 CK_KEY_TYPE keyType = CKK_SALSA20; 8450 CK_UTF8CHAR label[] = “A Salsa20 secret key object”; 8451 CK_BYTE value[32] = {...}; 8452 CK_BBOOL true = CK_TRUE; 8453 CK_ATTRIBUTE template[] = {
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 246 of 278 8454 {CKA_CLASS, &class, sizeof(class)}, 8455 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 8456 {CKA_TOKEN, &true, sizeof(true)}, 8457 {CKA_LABEL, label, sizeof(label)-1}, 8458 {CKA_ENCRYPT, &true, sizeof(true)}, 8459 {CKA_VALUE, value, sizeof(value)} 8460 }; 8461 CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first 8462 three bytes of the SHA-1 hash of the ChaCha20 secret key object’s CKA_VALUE attribute.
8463 2.59.3 Salsa20 mechanism parameters
8464 CK_SALSA20_PARAMS; CK_SALSA_PARAMS_PTR 8465 CK_SALSA20_PARAMS provides the parameters to the CKM_SALSA20 mechanism. It is defined as 8466 follows: 8467 typedef struct CK_SALSA20_PARAMS { 8468 CK_BYTE_PTR pBlockCounter; 8469 CK_BYTE_PTR pNonce; 8470 CK_ULONG ulNonceBits; 8471 } CK_SALSA20_PARAMS; 8472 8473 The fields of the structure have the following meanings: 8474 pBlockCounter pointer to block counter (64 bits)
8475 pNonce nonce
8476 ulNonceBits size of the nonce in bits (64 for classic and 192 for XSalsa20)
8477 The block counter is used to address 512 bit blocks in the stream. In certain settings (e.g. disk encryption) 8478 it is necessary to address these blocks in random order, thus this counter is exposed here.
8479 2.59.4 Salsa20 key generation 8480 The Salsa20 key generation mechanism, denoted CKM_SALSA20_KEY_GEN, is a key generation 8481 mechanism for Salsa20. 8482 It does not have a parameter. 8483 The mechanism generates Salsa20 keys of 256 bits. 8484 The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 8485 key. Other attributes supported by the key type (specifically, the flags indicating which functions the key 8486 supports) may be specified in the template for the key, or else are assigned default initial values. 8487 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8488 specify the supported range of key sizes in bytes. As a practical matter, the key size for Salsa20 is fixed 8489 at 256 bits.
8490 2.59.5 Salsa20 mechanism 8491 Salsa20, denoted CKM_SALSA20, is a mechanism for single and multiple-part encryption and decryption 8492 based on the Salsa20 stream cipher. Salsa20 comes in two variants which only differ in the size and 8493 handling of their nonces, affecting the safety of using random nonces. 8494 Salsa20 has a parameter, CK_SALSA20_PARAMS, which indicates the nonce and initial block counter 8495 value. pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 247 of 278 8496 Constraints on key types and the length of input and output data are summarized in the following table: 8497 Table 224, Salsa20: Key and Data Length
Function Key type Input length Output length Comments
C_Encrypt Salsa20 Any Same as input length No final part
C_Decrypt Salsa20 Any Same as input length No final part 8498 For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 8499 specify the supported range of ChaCha20 key sizes, in bits. 8500 Table 225, Salsa20: Nonce sizes
Variant Nonce Maximum message Nonce generation
original 64 bit Virtually unlimited 1st msg: nonce0=rand om nth msg: noncen-1++ XSalsa20 192 bit Virtually unlimited Each nonce can be randomly generated.
8501 Nonces must not ever be reused with the same key. However due to the birthday paradox the original 8502 variant cannot guarantee that randomly generated nonces are never repeating. Thus the recommended 8503 way to handle this is to generate the first nonce randomly, then increase this for follow-up messages. 8504 Only the XSalsa20 has large enough nonces so that it is virtually impossible to trigger with randomly 8505 generated nonces the birthday paradox.
8506 2.60 Poly1305 8507 Poly1305 is a message authentication code designed by D.J Bernsterin [POLY1305]. Poly1305 takes a 8508 256 bit key and a message and produces a 128 bit tag that is used to verify the message. 8509 Table 226, Poly1305 Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Key/ & Derive Digest Decrypt Verify 1 Key Unwrap VR Pair CKM_POLY1305_KEY_GEN ✓ CKM_POLY1305 ✓
8510 2.60.1 Definitions 8511 This section defines the key type “CKK_POLY1305” for type CK_KEY_TYPE as used in the 8512 CKA_KEY_TYPE attribute of key objects. 8513 Mechanisms: 8514 CKM_POLY1305_KEY_GEN 8515 CKM_POLY1305_MAC
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 248 of 278 8516 2.60.2 Poly1305 secret key objects 8517 Poly1305 secret key objects (object class CKO_SECRET_KEY, key type CKK_POLY1305) hold 8518 Poly1305 keys. The following table defines the Poly1305 secret key object attributes, in addition to the 8519 common attributes defined for this object class: 8520 Table 227, Poly1305 Secret Key Object Attribute Data type Meaning CKA_VALUE1,4,6,7 Byte array Key length is fixed at 256 bits. Bit length restricted to a byte array. CKA_VALUE_LEN2,3 CK_ULONG Length in bytes of key value 8521 The following is a sample template for creating a Poly1305 secret key object: 8522 CK_OBJECT_CLASS class = CKO_SECRET_KEY; 8523 CK_KEY_TYPE keyType = CKK_POLY1305; 8524 CK_UTF8CHAR label[] = “A Poly1305 secret key object”; 8525 CK_BYTE value[32] = {...}; 8526 CK_BBOOL true = CK_TRUE; 8527 CK_ATTRIBUTE template[] = { 8528 {CKA_CLASS, &class, sizeof(class)}, 8529 {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, 8530 {CKA_TOKEN, &true, sizeof(true)}, 8531 {CKA_LABEL, label, sizeof(label)-1}, 8532 {CKA_SIGN, &true, sizeof(true)}, 8533 {CKA_VALUE, value, sizeof(value)} 8534 }; 8535
8536 2.60.3 Poly1305 mechanism 8537 Poly1305, denoted CKM_POLY1305, is a mechanism for producing an output tag based on a 256 bit key 8538 and arbitrary length input. 8539 It has no parameters. 8540 Signatures (MACs) produced by this mechanism will be fixed at 128 bits in size. 8541 Table 228, Poly1305: Key and Data Length
Function Key type Data length Signature Length
C_Sign Poly1305 Any 128 bits
C_Verify Poly1305 Any 128 bits
8542 2.61 Chacha20/Poly1305 and Salsa20/Poly1305 Authenticated 8543 Encryption / Decryption 8544 The stream ciphers Salsa20 and ChaCha20 are normally used in conjunction with the Poly1305 8545 authenticator, in such a construction they also provide Authenticated Encryption with Associated Data 8546 (AEAD). This section defines the combined mechanisms and their usage in an AEAD setting.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 249 of 278 8547 2.61.1 Definitions
8548 Mechanisms: 8549 CKM_CHACHA20_POLY1305 8550 CKM_SALSA20_POLY1305
8551 2.61.2 Usage 8552 Generic ChaCha20, Salsa20, Poly1305 modes are described in [CHACHA], [SALSA] and [POLY1305]. 8553 To set up for ChaCha20/Poly1305 or Salsa20/Poly1305 use the following process. ChaCha20/Poly1305 8554 and Salsa20/Poly1305 both use CK_SALSA20_CHACHA20_POLY1350_PARAM for Encrypt, Decrypt 8555 and CK_SALSA20_CHACHA20_POLY1305_MSG_PARAM for MessageEncrypt, and MessageDecrypt. 8556 Encrypt: 8557 Set the Nonce length ulNonceLen in the parameter block. (this affects which variant of Chacha20 8558 will be used: 64 bits → original, 96 bits → IETF, 192 bits → XChaCha20) 8559 Set the Nonce data pNonce in the parameter block. 8560 Set the AAD data pAAD and size ulAADLen in the parameter block. pAAD may be NULL if 8561 ulAADLen is 0. 8562 Call C_EncryptInit() for CKM_CHACHA20_POLY1305 or CKM_SALSA20_POLY1305 8563 mechanism with parameters and key K. 8564 Call C_Encrypt(), or C_EncryptUpdate()*10 C_EncryptFinal(), for the plaintext obtaining ciphertext 8565 and authentication tag output. 8566 Decrypt: 8567 Set the Nonce length ulNonceLen in the parameter block. (this affects which variant of Chacha20 8568 will be used: 64 bits → original, 96 bits → IETF, 192 bits → XChaCha20) 8569 Set the Nonce data pNonce in the parameter block. 8570 Set the AAD data pAAD and size ulAADLen in the parameter block. pAAD may be NULL if 8571 ulAADLen is 0. 8572 Call C_DecryptInit() for CKM_CHACHA20_POLY1305 or CKM_SALSA20_POLY1305 8573 mechanism with parameters and key K. 8574 Call C_Decrypt(), or C_DecryptUpdate()*1 C_DecryptFinal(), for the ciphertext, including the 8575 appended tag, obtaining plaintext output. Note: since CKM_CHACHA20_POLY1305 and 8576 CKM_SALSA20_POLY1305 are AEAD ciphers, no data should be returned until C_Decrypt() or 8577 C_DecryptFinal(). 8578 MessageEncrypt:: 8579 Set the Nonce length ulNonceLen in the parameter block. (this affects which variant of Chacha20 8580 will be used: 64 bits → original, 96 bits → IETF, 192 bits → XChaCha20) 8581 Set the Nonce data pNonce in the parameter block. 8582 Set pTag to hold the tag data returned from C_EncryptMessage() or the final 8583 C_EncryptMessageNext(). 8584 Call C_MessageEncryptInit() for CKM_CHACHA20_POLY1305 or CKM_SALSA20_POLY1305 8585 mechanism with key K.
10 “*” indicates 0 or more calls may be made as required
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 250 of 278 8586 Call C_EncryptMessage(), or C_EncryptMessageBegin followed by C_EncryptMessageNext()*11. 8587 The mechanism parameter is passed to all three of these functions. 8588 Call C_MessageEncryptFinal() to close the message decryption. 8589 MessageDecrypt: 8590 Set the Nonce length ulNonceLen in the parameter block. (this affects which variant of Chacha20 8591 will be used: 64 bits → original, 96 bits → IETF, 192 bits → XChaCha20) 8592 Set the Nonce data pNonce in the parameter block. 8593 Set the tag data pTag in the parameter block before C_DecryptMessage or the final 8594 C_DecryptMessageNext() 8595 Call C_MessageDecryptInit() for CKM_CHACHA20_POLY1305 or CKM_SALSA20_POLY1305 8596 mechanism with key K. 8597 Call C_DecryptMessage(), or C_DecryptMessageBegin followed by C_DecryptMessageNext()* 12. 8598 The mechanism parameter is passed to all three of these functions. 8599 Call C_MessageDecryptFinal() to close the message decryption 8600 8601 ulNonceLen is the length of the nonce in bits. 8602 In Encrypt and Decrypt the tag is appended to the cipher text. In MessageEncrypt the tag is returned in 8603 the pTag filed of CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS. In MesssageDecrypt the tag is 8604 provided by the pTag field of CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS. The application 8605 must provide 16 bytes of space for the tag. 8606 The key type for K must be compatible with CKM_CHACHA20 or CKM_SALSA20 respectively and the 8607 C_EncryptInit/C_DecryptInit calls shall behave, with respect to K, as if they were called directly with 8608 CKM_CHACHA20 or CKM_SALSA20, K and NULL parameters. 8609 Unlike the atomic Salsa20/ChaCha20 mechanism the AEAD mechanism based on them does not expose 8610 the block counter, as the AEAD construction is based on a message metaphor in which random access is 8611 not needed.
8612 2.61.3 ChaCha20/Poly1305 and Salsa20/Poly1305 Mechanism parameters
8613 CK_SALSA20_CHACHA20_POLY1305_PARAMS; 8614 CK_SALSA20_CHACHA20_POLY1305_PARAMS_PTR 8615 CK_SALSA20_CHACHA20_POLY1305_PARAMS is a structure that provides the parameters to the 8616 CKM_CHACHA20_POLY1305 and CKM_SALSA20_POLY1305 mechanisms. It is defined as follows: 8617 typedef struct CK_SALSA20_CHACHA20_POLY1305_PARAMS { 8618 CK_BYTE_PTR pNonce; 8619 CK_ULONG ulNonceLen; 8620 CK_BYTE_PTR pAAD; 8621 CK_ULONG ulAADLen; 8622 } CK_SALSA20_CHACHA20_POLY1305_PARAMS; 8623 The fields of the structure have the following meanings:
11 “*” indicates 0 or more calls may be made as required
12 “*” indicates 0 or more calls may be made as required
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 251 of 278 8624 pNonce nonce (This should be never re-used with the same key.)
8625 ulNonceLen length of nonce in bits (is 64 for original, 96 for IETF (only for 8626 chacha20) and 192 for xchacha20/xsalsa20 variant)
8627 pAAD pointer to additional authentication data. This data is authenticated 8628 but not encrypted.
8629 ulAADLen length of pAAD in bytes.
8630 CK_SALSA20_CHACHA20_POLY1305_PARAMS_PTR is a pointer to a 8631 CK_SALSA20_CHACHA20_POLY1305_PARAMS.
8632 CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS; 8633 CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS_PTR 8634 CK_CHACHA20POLY1305_PARAMS is a structure that provides the parameters to the CKM_ 8635 CHACHA20_POLY1305 mechanism. It is defined as follows: 8636 typedef struct CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS { 8637 CK_BYTE_PTR pNonce; 8638 CK_ULONG ulNonceLen; 8639 CK_BYTE_PTR pTag; 8640 } CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS; 8641 The fields of the structure have the following meanings: 8642 pNonce pointer to nonce
8643 ulNonceLen length of nonce in bits. The length of the influences which variant of 8644 the ChaCha20 will be used (64 original, 96 IETF(only for 8645 ChaCha20), 192 XChaCha20/XSalsa20)
8646 pTag location of the authentication tag which is returned on 8647 MessageEncrypt, and provided on MessageDecrypt.
8648 CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS_PTR is a pointer to a 8649 CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS.
8650 2.62 HKDF Mechanisms 8651 Details for HKDF key derivation mechanisms can be found in [RFC 5869]. 8652 8653 Table 229, HKDF Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_HKDF_DERIVE CKM_HKDF_DATA CKM_HKDF_KEY_GEN
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 252 of 278 8654 2.62.1 Definitions 8655 Mechanisms: 8656 CKM_HKDF_DERIVE 8657 CKM_HKDF_DATA 8658 CKM_HKDF_KEY_GEN 8659 8660 Key Types: 8661 CKK_HKDF
8662 2.62.2 HKDF mechanism parameters
8663 CK_HKDF_PARAMS; CK_HKDF_PARAMS_PTR 8664 CK_HKDF_PARAMS is a structure that provides the parameters to the CKM_HKDF_DERIVE and 8665 CKM_HKDF_DATA mechanisms. It is defined as follows: 8666 typedef struct CK_HKDF_PARAMS { 8667 CK_BOOL bExtract; 8668 CK_BOOL bExpand; 8669 CK_MECHANISM_TYPE prfHashMechanism; 8670 CK_ULONG ulSaltType; 8671 CK_BYTE_PTR pSalt; 8672 CK_ULONG ulSaltLen; 8673 CK_HANDLE hSaltKey; 8674 CK_BYTE_PTR pInfo; 8675 CK_ULONG ulInfoLen; 8676 } CK_HKDF_PARAMS; 8677 8678 The fields of the structure have the following meanings: 8679 bExtract execute the extract portion of HKDF.
8680 bExpand execute the expand portion of HKDF.
8681 prfHashMechanism base hash used for the HMAC in the underlying HKDF operation.
8682 ulSaltType specifies how the salt for the extract portion of the KDF is supplied.
8683 CKF_HKDF_SALT_NULL no salt is supplied.
8684 CKF_HKDF_SALT_DATA salt is supplied as a data in pSalt with 8685 length ulSaltLen.
8686 CKF_HKDF_SALT_KEY salt is supplied as a key in hSaltKey.
8687 pSalt pointer to the salt.
8688 ulSaltLen length of the salt pointed to in pSalt.
8689 hSaltKey object handle to the salt key.
8690 pInfo info string for the expand stage.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 253 of 278 8691 ulInfoLen length of the info string for the expand stage.
8692
8693 CK_HKDF_PARAMS_PTR is a pointer to a CK_HKDF_PARAMS.
8694 2.62.3 HKDF derive 8695 HKDF derivation implements the HKDF as specified in RFC 5869. The two booleans bExtract and 8696 bExpand control whether the extract section of the HKDF or the expand section of the HKDF is in use. 8697 It has a parameter, a CK_HKDF_PARAMS structure, which allows for the passing of the salt and or the 8698 expansion info. The structure contains the bools bExtract and bExpand which control whether the extract 8699 or expand portions of the HKDF is to be used. This structure is defined in Section 2.62.2. 8700 The input key must be of type CKK_HKDF or CKK_GENERIC_SECRET and the length must be the size 8701 of the underlying hash function specified in prfHashMechanism. The exception is a data object which has 8702 the same size as the underlying hash function, and which may be supplied as an input key. In this case 8703 bExtract should be true and non-null salt should be supplied. 8704 Either bExtract or bExpand must be set to true. If they are both set to true, input key is first extracted then 8705 expanded. The salt is used in the extraction stage. If bExtract is set to true and no salt is given, a ‘zero’ 8706 salt (salt whose length is the same as the underlying hash and values all set to zero) is used as specified 8707 by the RFC. If bExpand is set to true, CKA_VALUE_LEN should be set to the desired key length. If it is 8708 false CKA_VALUE_LEN may be set to the length of the hash, but that is not necessary as the mechanism 8709 will supply this value. The salt should be ignored if bExtract is false. The pInfo should be ignored if 8710 bExpand is set to false. 8711 The mechanism also contributes the CKA_CLASS, and CKA_VALUE attributes to the new key. Other 8712 attributes may be specified in the template, or else are assigned default values. 8713 The template sent along with this mechanism during a C_DeriveKey call may indicate that the object 8714 class is CKO_SECRET_KEY. However, since these facts are all implicit in the mechanism, there is no 8715 need to specify any of them. 8716 This mechanism has the following rules about key sensitivity and extractability: 8717 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both 8718 be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some 8719 default value. 8720 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 8721 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 8722 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 8723 CKA_SENSITIVE attribute. 8724 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the 8725 derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 8726 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 8727 value from its CKA_EXTRACTABLE attribute.
8728 2.62.4 HKDF Data 8729 HKDF Data derive mechanism, denoted CKM_HKDF_DATA, is identical to HKDF Derive except the 8730 output is a CKO_DATA object whose value is the result to the derive operation. Some tokens may restrict 8731 what data may be successfully derived based on the pInfo portion of the CK_HKDF_PARAMS. All tokens 8732 must minimally support bExtract set to true and bInfo values which start with the value “tls1.3 vi”. Future 8733 additional required combinations may be specified in the profile document and applications could then 8734 query the appropriate profile before depending on the mechanism.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 254 of 278 8735 2.62.5 HKDF Key gen 8736 HKDF key gen, denoted CKM_HKDF_KEYGEN generates a new random HKDF key. 8737 CKA_VALUE_LENGTH must be set in the template.
8738 2.63 NULL Mechanism 8739 CKM_NULL is a mechanism used to implement the trivial pass-through function. 8740 8741 Table 230, CKM_NULL Mechanisms vs. Functions Functions Encrypt Sign SR Gen. Wrap Mechanism & & & Digest Key/ & Derive Decrypt Verify VR1 Key Unwrap Pair CKM_NULL
1SR = SignRecover, VR = VerifyRecover
8742
8743 2.63.1 Definitions 8744 Mechanisms: 8745 CKM_NULL
8746 2.63.2 CKM_NULL mechanism parameters 8747 CKM_NULL does not have a parameter. 8748 8749 When used for encrypting / decrypting data, the input data is copied unchanged to the output data. 8750 When used for signing, the input data is copied to the signature. When used for signature verification, it 8751 compares the input data and the signature, and returns CKR_OK (indicating that both are identical) or 8752 CKR_SIGNATURE_INVALID. 8753 When used for digesting data, the input data is copied to the message digest. 8754 When used for wrapping a private or secret key object, the wrapped key will be identical to the key to be 8755 wrapped. When used for unwrapping, a new object with the same value as the wrapped key will be 8756 created. 8757 When used for deriving a key, the derived key has the same value as the base key.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 255 of 278 8758 3 PKCS #11 Implementation Conformance 8759 An implementation is a conforming implementation if it meets the conditions specified in one or more 8760 server profiles specified in [PKCS11-Prof]. 8761 If a PKCS #11 implementation claims support for a particular profile, then the implementation SHALL 8762 conform to all normative statements within the clauses specified for that profile and for any subclauses to 8763 each of those clauses.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 256 of 278 8764 Appendix A. Acknowledgments
8765 The following individuals have participated in the creation of this specification and are gratefully 8766 acknowledged: 8767 Participants: 8768 List needs to be pasted in here 8769 Gil Abel, Athena Smartcard Solutions, Inc. 8770 Warren Armstrong, QuintessenceLabs 8771 Jeff Bartell, Semper Foris Solutions LLC 8772 Peter Bartok, Venafi, Inc. 8773 Anthony Berglas, Cryptsoft 8774 Joseph Brand, Semper Fortis Solutions LLC 8775 Kelley Burgin, National Security Agency 8776 Robert Burns, Thales e-Security 8777 Wan-Teh Chang, Google Inc. 8778 Hai-May Chao, Oracle 8779 Janice Cheng, Vormetric, Inc. 8780 Sangrae Cho, Electronics and Telecommunications Research Institute (ETRI) 8781 Doron Cohen, SafeNet, Inc. 8782 Fadi Cotran, Futurex 8783 Tony Cox, Cryptsoft 8784 Christopher Duane, EMC 8785 Chris Dunn, SafeNet, Inc. 8786 Valerie Fenwick, Oracle 8787 Terry Fletcher, SafeNet, Inc. 8788 Susan Gleeson, Oracle 8789 Sven Gossel, Charismathics 8790 John Green, QuintessenceLabs 8791 Robert Griffin, EMC 8792 Paul Grojean, Individual 8793 Peter Gutmann, Individual 8794 Dennis E. Hamilton, Individual 8795 Thomas Hardjono, M.I.T. 8796 Tim Hudson, Cryptsoft 8797 Gershon Janssen, Individual 8798 Seunghun Jin, Electronics and Telecommunications Research Institute (ETRI) 8799 Wang Jingman, Feitan Technologies 8800 Andrey Jivsov, Symantec Corp. 8801 Mark Joseph, P6R 8802 Stefan Kaesar, Infineon Technologies 8803 Greg Kazmierczak, Wave Systems Corp. 8804 Mark Knight, Thales e-Security
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 257 of 278 8805 Darren Krahn, Google Inc. 8806 Alex Krasnov, Infineon Technologies AG 8807 Dina Kurktchi-Nimeh, Oracle 8808 Mark Lambiase, SecureAuth Corporation 8809 Lawrence Lee, GoTrust Technology Inc. 8810 John Leiseboer, QuintessenceLabs 8811 Sean Leon, Infineon Technologies 8812 Geoffrey Li, Infineon Technologies 8813 Howie Liu, Infineon Technologies 8814 Hal Lockhart, Oracle 8815 Robert Lockhart, Thales e-Security 8816 Dale Moberg, Axway Software 8817 Darren Moffat, Oracle 8818 Valery Osheter, SafeNet, Inc. 8819 Sean Parkinson, EMC 8820 Rob Philpott, EMC 8821 Mark Powers, Oracle 8822 Ajai Puri, SafeNet, Inc. 8823 Robert Relyea, Red Hat 8824 Saikat Saha, Oracle 8825 Subhash Sankuratripati, NetApp 8826 Anthony Scarpino, Oracle 8827 Johann Schoetz, Infineon Technologies AG 8828 Rayees Shamsuddin, Wave Systems Corp. 8829 Radhika Siravara, Oracle 8830 Brian Smith, Mozilla Corporation 8831 David Smith, Venafi, Inc. 8832 Ryan Smith, Futurex 8833 Jerry Smith, US Department of Defense (DoD) 8834 Oscar So, Oracle 8835 Graham Steel, Cryptosense 8836 Michael Stevens, QuintessenceLabs 8837 Michael StJohns, Individual 8838 Jim Susoy, P6R 8839 Sander Temme, Thales e-Security 8840 Kiran Thota, VMware, Inc. 8841 Walter-John Turnes, Gemini Security Solutions, Inc. 8842 Stef Walter, Red Hat 8843 James Wang, Vormetric 8844 Jeff Webb, Dell 8845 Peng Yu, Feitian Technologies 8846 Magda Zdunkiewicz, Cryptsoft
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 258 of 278 8847 Chris Zimman, Individual 8848 8849
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 259 of 278 8850 Appendix B. Manifest Constants
8851 The following definitions can be found in the appropriate computer language files referenced on the title 8852 page of this specification. Also, refer to [PKCS11_BASE] and [PKCS11_HIST] for additional definitions. 8853 8854 /* 8855 * Copyright © Oasis Open 2019. All right reserved. 8856 * OASIS trademark, IPR and other policies apply. 8857 * http://www.oasis-open.org/policies-guidelines/ipr 8858 */ 8859
8860 B.1 Object classes 8861 #define CKO_DATA 0x00000000 8862 #define CKO_CERTIFICATE 0x00000001 8863 #define CKO_PUBLIC_KEY 0x00000002 8864 #define CKO_PRIVATE_KEY 0x00000003 8865 #define CKO_SECRET_KEY 0x00000004 8866 #define CKO_HW_FEATURE 0x00000005 8867 #define CKO_DOMAIN_PARAMETERS 0x00000006 8868 #define CKO_MECHANISM 0x00000007 8869 #define CKO_OTP_KEY 0x00000008 8870 #define CKO_PROFILE 0x00000009 8871 #define CKO_VENDOR_DEFINED 0x80000000
8872 B.2 Key types 8873 #define CKK_RSA 0x00000000 8874 #define CKK_DSA 0x00000001 8875 #define CKK_DH 0x00000002 8876 #define CKK_EC 0x00000003 8877 #define CKK_X9_42_DH 0x00000004 8878 #define CKK_KEA 0x00000005 8879 #define CKK_GENERIC_SECRET 0x00000010 8880 #define CKK_RC2 0x00000011 8881 #define CKK_RC4 0x00000012 8882 #define CKK_DES 0x00000013 8883 #define CKK_DES2 0x00000014 8884 #define CKK_DES3 0x00000015 8885 #define CKK_CAST 0x00000016 8886 #define CKK_CAST3 0x00000017 8887 #define CKK_CAST128 0x00000018 8888 #define CKK_RC5 0x00000019 8889 #define CKK_IDEA 0x0000001A 8890 #define CKK_SKIPJACK 0x0000001B 8891 #define CKK_BATON 0x0000001C
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 260 of 278 8892 #define CKK_JUNIPER 0x0000001D 8893 #define CKK_CDMF 0x0000001E 8894 #define CKK_AES 0x0000001F 8895 #define CKK_BLOWFISH 0x00000020 8896 #define CKK_TWOFISH 0x00000021 8897 #define CKK_SECURID 0x00000022 8898 #define CKK_HOTP 0x00000023 8899 #define CKK_ACTI 0x00000024 8900 #define CKK_CAMELLIA 0x00000025 8901 #define CKK_ARIA 0x00000026 8902 #define CKK_MD5_HMAC 0x00000027 8903 #define CKK_SHA_1_HMAC 0x00000028 8904 #define CKK_RIPEMD128_HMAC 0x00000029 8905 #define CKK_RIPEMD160_HMAC 0x0000002A 8906 #define CKK_SHA256_HMAC 0x0000002B 8907 #define CKK_SHA384_HMAC 0x0000002C 8908 #define CKK_SHA512_HMAC 0x0000002D 8909 #define CKK_SHA224_HMAC 0x0000002E 8910 #define CKK_SEED 0x0000002F 8911 #define CKK_GOSTR3410 0x00000030 8912 #define CKK_GOSTR3411 0x00000031 8913 #define CKK_GOST28147 0x00000032 8914 #define CKK_CHACHA20 0x00000033 8915 #define CKK_POLY1305 0x00000034 8916 #define CKK_AES_XTS 0x00000035 8917 #define CKK_SHA3_224_HMAC 0x00000036 8918 #define CKK_SHA3_256_HMAC 0x00000037 8919 #define CKK_SHA3_384_HMAC 0x00000038 8920 #define CKK_SHA3_512_HMAC 0x00000039 8921 #define CKK_BLAKE2B_160_HMAC 0x0000003a 8922 #define CKK_BLAKE2B_256_HMAC 0x0000003b 8923 #define CKK_BLAKE2B_384_HMAC 0x0000003c 8924 #define CKK_BLAKE2B_512_HMAC 0x0000003d 8925 #define CKK_SALSA20 0x0000003e 8926 #define CKK_X2RATCHET 0x0000003f 8927 #define CKK_EC_EDWARDS 0x00000040 8928 #define CKK_EC_MONTGOMERY 0x00000041 8929 #define CKK_HKDF 0x00000042 8930 #define CKK_VENDOR_DEFINED 0x80000000
8931 B.3 Key derivation functions 8932 #define CKD_NULL 0x00000001 8933 #define CKD_SHA1_KDF 0x00000002 8934 #define CKD_SHA1_KDF_ASN1 0x00000003 8935 #define CKD_SHA1_KDF_CONCATENATE 0x00000004 8936 #define CKD_SHA224_KDF 0x00000005 8937 #define CKD_SHA256_KDF 0x00000006 8938 #define CKD_SHA384_KDF 0x00000007
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 261 of 278 8939 #define CKD_SHA512_KDF 0x00000008 8940 #define CKD_CPDIVERSIFY_KDF 0x00000009 8941 #define CKD_SHA3_224_KDF 0x0000000A 8942 #define CKD_SHA3_256_KDF 0x0000000B 8943 #define CKD_SHA3_384_KDF 0x0000000C 8944 #define CKD_SHA3_512_KDF 0x0000000D 8945 #define CKD_SHA1_KDF_SP800 0x0000000E 8946 #define CKD_SHA224_KDF_SP800 0x0000000F 8947 #define CKD_SHA256_KDF_SP800 0x00000010 8948 #define CKD_SHA384_KDF_SP800 0x00000011 8949 #define CKD_SHA512_KDF_SP800 0x00000012 8950 #define CKD_SHA3_224_KDF_SP800 0x00000013 8951 #define CKD_SHA3_256_KDF_SP800 0x00000014 8952 #define CKD_SHA3_384_KDF_SP800 0x00000015 8953 #define CKD_SHA3_512_KDF_SP800 0x00000016 8954 #define CKD_BLAKE2B_160_KDF 0x00000017 8955 #define CKD_BLAKE2B_256_KDF 0x00000018 8956 #define CKD_BLAKE2B_384_KDF 0x00000019 8957 #define CKD_BLAKE2B_512_KDF 0x0000001A
8958 B.4 Mechanisms 8959 #define CKM_RSA_PKCS_KEY_PAIR_GEN 0x00000000 8960 #define CKM_RSA_PKCS 0x00000001 8961 #define CKM_RSA_9796 0x00000002 8962 #define CKM_RSA_X_509 0x00000003 8963 #define CKM_MD2_RSA_PKCS 0x00000004 8964 #define CKM_MD5_RSA_PKCS 0x00000005 8965 #define CKM_SHA1_RSA_PKCS 0x00000006 8966 #define CKM_RIPEMD128_RSA_PKCS 0x00000007 8967 #define CKM_RIPEMD160_RSA_PKCS 0x00000008 8968 #define CKM_RSA_PKCS_OAEP 0x00000009 8969 #define CKM_RSA_X9_31_KEY_PAIR_GEN 0x0000000A 8970 #define CKM_RSA_X9_31 0x0000000B 8971 #define CKM_SHA1_RSA_X9_31 0x0000000C 8972 #define CKM_RSA_PKCS_PSS 0x0000000D 8973 #define CKM_SHA1_RSA_PKCS_PSS 0x0000000E 8974 #define CKM_DSA_KEY_PAIR_GEN 0x00000010 8975 #define CKM_DSA 0x00000011 8976 #define CKM_DSA_SHA1 0x00000012 8977 #define CKM_DSA_FIPS_G_GEN 0x00000013 8978 #define CKM_DSA_SHA224 0x00000014 8979 #define CKM_DSA_SHA256 0x00000015 8980 #define CKM_DSA_SHA384 0x00000016 8981 #define CKM_DSA_SHA512 0x00000017 8982 #define CKM_DSA_SHA3_224 0x00000018 8983 #define CKM_DSA_SHA3_256 0x00000019 8984 #define CKM_DSA_SHA3_384 0x0000001A 8985 #define CKM_DSA_SHA3_512 0x0000001B
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 262 of 278 8986 #define CKM_DH_PKCS_KEY_PAIR_GEN 0x00000020 8987 #define CKM_DH_PKCS_DERIVE 0x00000021 8988 #define CKM_X9_42_DH_KEY_PAIR_GEN 0x00000030 8989 #define CKM_X9_42_DH_DERIVE 0x00000031 8990 #define CKM_X9_42_DH_HYBRID_DERIVE 0x00000032 8991 #define CKM_X9_42_MQV_DERIVE 0x00000033 8992 #define CKM_SHA256_RSA_PKCS 0x00000040 8993 #define CKM_SHA384_RSA_PKCS 0x00000041 8994 #define CKM_SHA512_RSA_PKCS 0x00000042 8995 #define CKM_SHA256_RSA_PKCS_PSS 0x00000043 8996 #define CKM_SHA384_RSA_PKCS_PSS 0x00000044 8997 #define CKM_SHA512_RSA_PKCS_PSS 0x00000045 8998 #define CKM_SHA224_RSA_PKCS 0x00000046 8999 #define CKM_SHA224_RSA_PKCS_PSS 0x00000047 9000 #define CKM_SHA512_224 0x00000048 9001 #define CKM_SHA512_224_HMAC 0x00000049 9002 #define CKM_SHA512_224_HMAC_GENERAL 0x0000004A 9003 #define CKM_SHA512_224_KEY_DERIVATION 0x0000004B 9004 #define CKM_SHA512_256 0x0000004C 9005 #define CKM_SHA512_256_HMAC 0x0000004D 9006 #define CKM_SHA512_256_HMAC_GENERAL 0x0000004E 9007 #define CKM_SHA512_256_KEY_DERIVATION 0x0000004F 9008 #define CKM_SHA512_T 0x00000050 9009 #define CKM_SHA512_T_HMAC 0x00000051 9010 #define CKM_SHA512_T_HMAC_GENERAL 0x00000052 9011 #define CKM_SHA512_T_KEY_DERIVATION 0x00000053 9012 #define CKM_SHA3_256_RSA_PKCS 0x00000060 9013 #define CKM_SHA3_384_RSA_PKCS 0x00000061 9014 #define CKM_SHA3_512_RSA_PKCS 0x00000062 9015 #define CKM_SHA3_256_RSA_PKCS_PSS 0x00000063 9016 #define CKM_SHA3_384_RSA_PKCS_PSS 0x00000064 9017 #define CKM_SHA3_512_RSA_PKCS_PSS 0x00000065 9018 #define CKM_SHA3_224_RSA_PKCS 0x00000066 9019 #define CKM_SHA3_224_RSA_PKCS_PSS 0x00000067 9020 #define CKM_RC2_KEY_GEN 0x00000100 9021 #define CKM_RC2_ECB 0x00000101 9022 #define CKM_RC2_CBC 0x00000102 9023 #define CKM_RC2_MAC 0x00000103 9024 #define CKM_RC2_MAC_GENERAL 0x00000104 9025 #define CKM_RC2_CBC_PAD 0x00000105 9026 #define CKM_RC4_KEY_GEN 0x00000110 9027 #define CKM_RC4 0x00000111 9028 #define CKM_DES_KEY_GEN 0x00000120 9029 #define CKM_DES_ECB 0x00000121 9030 #define CKM_DES_CBC 0x00000122 9031 #define CKM_DES_MAC 0x00000123 9032 #define CKM_DES_MAC_GENERAL 0x00000124 9033 #define CKM_DES_CBC_PAD 0x00000125
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 263 of 278 9034 #define CKM_DES2_KEY_GEN 0x00000130 9035 #define CKM_DES3_KEY_GEN 0x00000131 9036 #define CKM_DES3_ECB 0x00000132 9037 #define CKM_DES3_CBC 0x00000133 9038 #define CKM_DES3_MAC 0x00000134 9039 #define CKM_DES3_MAC_GENERAL 0x00000135 9040 #define CKM_DES3_CBC_PAD 0x00000136 9041 #define CKM_DES3_CMAC_GENERAL 0x00000137 9042 #define CKM_DES3_CMAC 0x00000138 9043 #define CKM_CDMF_KEY_GEN 0x00000140 9044 #define CKM_CDMF_ECB 0x00000141 9045 #define CKM_CDMF_CBC 0x00000142 9046 #define CKM_CDMF_MAC 0x00000143 9047 #define CKM_CDMF_MAC_GENERAL 0x00000144 9048 #define CKM_CDMF_CBC_PAD 0x00000145 9049 #define CKM_DES_OFB64 0x00000150 9050 #define CKM_DES_OFB8 0x00000151 9051 #define CKM_DES_CFB64 0x00000152 9052 #define CKM_DES_CFB8 0x00000153 9053 #define CKM_MD2 0x00000200 9054 #define CKM_MD2_HMAC 0x00000201 9055 #define CKM_MD2_HMAC_GENERAL 0x00000202 9056 #define CKM_MD5 0x00000210 9057 #define CKM_MD5_HMAC 0x00000211 9058 #define CKM_MD5_HMAC_GENERAL 0x00000212 9059 #define CKM_SHA_1 0x00000220 9060 #define CKM_SHA_1_HMAC 0x00000221 9061 #define CKM_SHA_1_HMAC_GENERAL 0x00000222 9062 #define CKM_RIPEMD128 0x00000230 9063 #define CKM_RIPEMD128_HMAC 0x00000231 9064 #define CKM_RIPEMD128_HMAC_GENERAL 0x00000232 9065 #define CKM_RIPEMD160 0x00000240 9066 #define CKM_RIPEMD160_HMAC 0x00000241 9067 #define CKM_RIPEMD160_HMAC_GENERAL 0x00000242 9068 #define CKM_SHA256 0x00000250 9069 #define CKM_SHA256_HMAC 0x00000251 9070 #define CKM_SHA256_HMAC_GENERAL 0x00000252 9071 #define CKM_SHA224 0x00000255 9072 #define CKM_SHA224_HMAC 0x00000256 9073 #define CKM_SHA224_HMAC_GENERAL 0x00000257 9074 #define CKM_SHA384 0x00000260 9075 #define CKM_SHA384_HMAC 0x00000261 9076 #define CKM_SHA384_HMAC_GENERAL 0x00000262 9077 #define CKM_SHA512 0x00000270 9078 #define CKM_SHA512_HMAC 0x00000271 9079 #define CKM_SHA512_HMAC_GENERAL 0x00000272 9080 #define CKM_SECURID_KEY_GEN 0x00000280 9081 #define CKM_SECURID 0x00000282
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 264 of 278 9082 #define CKM_HOTP_KEY_GEN 0x00000290 9083 #define CKM_HOTP 0x00000291 9084 #define CKM_ACTI 0x000002A0 9085 #define CKM_ACTI_KEY_GEN 0x000002A1 9086 #define CKM_SHA3_256 0x000002B0 9087 #define CKM_SHA3_256_HMAC 0x000002B1 9088 #define CKM_SHA3_256_HMAC_GENERAL 0x000002B2 9089 #define CKM_SHA3_256_KEY_GEN 0x000002B3 9090 #define CKM_SHA3_224 0x000002B5 9091 #define CKM_SHA3_224_HMAC 0x000002B6 9092 #define CKM_SHA3_224_HMAC_GENERAL 0x000002B7 9093 #define CKM_SHA3_224_KEY_GEN 0x000002B8 9094 #define CKM_SHA3_384 0x000002C0 9095 #define CKM_SHA3_384_HMAC 0x000002C1 9096 #define CKM_SHA3_384_HMAC_GENERAL 0x000002C2 9097 #define CKM_SHA3_384_KEY_GEN 0x000002C3 9098 #define CKM_SHA3_512 0x000002D0 9099 #define CKM_SHA3_512_HMAC 0x000002D1 9100 #define CKM_SHA3_512_HMAC_GENERAL 0x000002D2 9101 #define CKM_SHA3_512_KEY_GEN 0x000002D3 9102 #define CKM_CAST_KEY_GEN 0x00000300 9103 #define CKM_CAST_ECB 0x00000301 9104 #define CKM_CAST_CBC 0x00000302 9105 #define CKM_CAST_MAC 0x00000303 9106 #define CKM_CAST_MAC_GENERAL 0x00000304 9107 #define CKM_CAST_CBC_PAD 0x00000305 9108 #define CKM_CAST3_KEY_GEN 0x00000310 9109 #define CKM_CAST3_ECB 0x00000311 9110 #define CKM_CAST3_CBC 0x00000312 9111 #define CKM_CAST3_MAC 0x00000313 9112 #define CKM_CAST3_MAC_GENERAL 0x00000314 9113 #define CKM_CAST3_CBC_PAD 0x00000315 9114 #define CKM_CAST128_KEY_GEN 0x00000320 9115 #define CKM_CAST128_ECB 0x00000321 9116 #define CKM_CAST128_CBC 0x00000322 9117 #define CKM_CAST128_MAC 0x00000323 9118 #define CKM_CAST128_MAC_GENERAL 0x00000324 9119 #define CKM_CAST128_CBC_PAD 0x00000325 9120 #define CKM_RC5_KEY_GEN 0x00000330 9121 #define CKM_RC5_ECB 0x00000331 9122 #define CKM_RC5_CBC 0x00000332 9123 #define CKM_RC5_MAC 0x00000333 9124 #define CKM_RC5_MAC_GENERAL 0x00000334 9125 #define CKM_RC5_CBC_PAD 0x00000335 9126 #define CKM_IDEA_KEY_GEN 0x00000340 9127 #define CKM_IDEA_ECB 0x00000341 9128 #define CKM_IDEA_CBC 0x00000342 9129 #define CKM_IDEA_MAC 0x00000343
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 265 of 278 9130 #define CKM_IDEA_MAC_GENERAL 0x00000344 9131 #define CKM_IDEA_CBC_PAD 0x00000345 9132 #define CKM_GENERIC_SECRET_KEY_GEN 0x00000350 9133 #define CKM_CONCATENATE_BASE_AND_KEY 0x00000360 9134 #define CKM_CONCATENATE_BASE_AND_DATA 0x00000362 9135 #define CKM_CONCATENATE_DATA_AND_BASE 0x00000363 9136 #define CKM_XOR_BASE_AND_DATA 0x00000364 9137 #define CKM_EXTRACT_KEY_FROM_KEY 0x00000365 9138 #define CKM_SSL3_PRE_MASTER_KEY_GEN 0x00000370 9139 #define CKM_SSL3_MASTER_KEY_DERIVE 0x00000371 9140 #define CKM_SSL3_KEY_AND_MAC_DERIVE 0x00000372 9141 #define CKM_SSL3_MASTER_KEY_DERIVE_DH 0x00000373 9142 #define CKM_TLS_PRE_MASTER_KEY_GEN 0x00000374 9143 #define CKM_TLS_MASTER_KEY_DERIVE 0x00000375 9144 #define CKM_TLS_KEY_AND_MAC_DERIVE 0x00000376 9145 #define CKM_TLS_MASTER_KEY_DERIVE_DH 0x00000377 9146 #define CKM_TLS_PRF 0x00000378 9147 #define CKM_SSL3_MD5_MAC 0x00000380 9148 #define CKM_SSL3_SHA1_MAC 0x00000381 9149 #define CKM_MD5_KEY_DERIVATION 0x00000390 9150 #define CKM_MD2_KEY_DERIVATION 0x00000391 9151 #define CKM_SHA1_KEY_DERIVATION 0x00000392 9152 #define CKM_SHA256_KEY_DERIVATION 0x00000393 9153 #define CKM_SHA384_KEY_DERIVATION 0x00000394 9154 #define CKM_SHA512_KEY_DERIVATION 0x00000395 9155 #define CKM_SHA224_KEY_DERIVATION 0x00000396 9156 #define CKM_SHA3_256_KEY_DERIVE 0x00000397 9157 #define CKM_SHA3_224_KEY_DERIVE 0x00000398 9158 #define CKM_SHA3_384_KEY_DERIVE 0x00000399 9159 #define CKM_SHA3_512_KEY_DERIVE 0x0000039A 9160 #define CKM_SHAKE_128_KEY_DERIVE 0x0000039B 9161 #define CKM_SHAKE_256_KEY_DERIVE 0x0000039C 9162 #define CKM_PBE_MD2_DES_CBC 0x000003A0 9163 #define CKM_PBE_MD5_DES_CBC 0x000003A1 9164 #define CKM_PBE_MD5_CAST_CBC 0x000003A2 9165 #define CKM_PBE_MD5_CAST3_CBC 0x000003A3 9166 #define CKM_PBE_MD5_CAST5_CBC 0x000003A4 9167 #define CKM_PBE_MD5_CAST128_CBC 0x000003A4 9168 #define CKM_PBE_SHA1_CAST128_CBC 0x000003A5 9169 #define CKM_PBE_SHA1_RC4_128 0x000003A6 9170 #define CKM_PBE_SHA1_RC4_40 0x000003A7 9171 #define CKM_PBE_SHA1_DES3_EDE_CBC 0x000003A8 9172 #define CKM_PBE_SHA1_DES2_EDE_CBC 0x000003A9 9173 #define CKM_PBE_SHA1_RC2_128_CBC 0x000003AA 9174 #define CKM_PBE_SHA1_RC2_40_CBC 0x000003AB 9175 #define CKM_SP800_108_COUNTER_KDF 0x000003AC 9176 #define CKM_SP800_108_FEEDBACK_KDF 0x000003AD 9177 #define CKM_SP800_108_DOUBLE_PIPELINE_KDF 0x000003AE
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 266 of 278 9178 #define CKM_PKCS5_PBKD2 0x000003B0 9179 #define CKM_PBA_SHA1_WITH_SHA1_HMAC 0x000003C0 9180 #define CKM_WTLS_PRE_MASTER_KEY_GEN 0x000003D0 9181 #define CKM_WTLS_MASTER_KEY_DERIVE 0x000003D1 9182 #define CKM_WTLS_MASTER_KEY_DERIVE_DH_ECC 0x000003D2 9183 #define CKM_WTLS_PRF 0x000003D3 9184 #define CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE 0x000003D4 9185 #define CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE 0x000003D5 9186 #define CKM_TLS12_MAC 0x000003D8 9187 #define CKM_TLS12_KDF 0x000003D9 9188 #define CKM_TLS12_MASTER_KEY_DERIVE 0x000003E0 9189 #define CKM_TLS12_KEY_AND_MAC_DERIVE 0x000003E1 9190 #define CKM_TLS12_MASTER_KEY_DERIVE_DH 0x000003E2 9191 #define CKM_TLS12_KEY_SAFE_DERIVE 0x000003E3 9192 #define CKM_TLS_MAC 0x000003E4 9193 #define CKM_TLS_KDF 0x000003E5 9194 #define CKM_KEY_WRAP_LYNKS 0x00000400 9195 #define CKM_KEY_WRAP_SET_OAEP 0x00000401 9196 #define CKM_CMS_SIG 0x00000500 9197 #define CKM_KIP_DERIVE 0x00000510 9198 #define CKM_KIP_WRAP 0x00000511 9199 #define CKM_KIP_MAC 0x00000512 9200 #define CKM_CAMELLIA_KEY_GEN 0x00000550 9201 #define CKM_CAMELLIA_ECB 0x00000551 9202 #define CKM_CAMELLIA_CBC 0x00000552 9203 #define CKM_CAMELLIA_MAC 0x00000553 9204 #define CKM_CAMELLIA_MAC_GENERAL 0x00000554 9205 #define CKM_CAMELLIA_CBC_PAD 0x00000555 9206 #define CKM_CAMELLIA_ECB_ENCRYPT_DATA 0x00000556 9207 #define CKM_CAMELLIA_CBC_ENCRYPT_DATA 0x00000557 9208 #define CKM_CAMELLIA_CTR 0x00000558 9209 #define CKM_ARIA_KEY_GEN 0x00000560 9210 #define CKM_ARIA_ECB 0x00000561 9211 #define CKM_ARIA_CBC 0x00000562 9212 #define CKM_ARIA_MAC 0x00000563 9213 #define CKM_ARIA_MAC_GENERAL 0x00000564 9214 #define CKM_ARIA_CBC_PAD 0x00000565 9215 #define CKM_ARIA_ECB_ENCRYPT_DATA 0x00000566 9216 #define CKM_ARIA_CBC_ENCRYPT_DATA 0x00000567 9217 #define CKM_SEED_KEY_GEN 0x00000650 9218 #define CKM_SEED_ECB 0x00000651 9219 #define CKM_SEED_CBC 0x00000652 9220 #define CKM_SEED_MAC 0x00000653 9221 #define CKM_SEED_MAC_GENERAL 0x00000654 9222 #define CKM_SEED_CBC_PAD 0x00000655 9223 #define CKM_SEED_ECB_ENCRYPT_DATA 0x00000656 9224 #define CKM_SEED_CBC_ENCRYPT_DATA 0x00000657 9225 #define CKM_SKIPJACK_KEY_GEN 0x00001000
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 267 of 278 9226 #define CKM_SKIPJACK_ECB64 0x00001001 9227 #define CKM_SKIPJACK_CBC64 0x00001002 9228 #define CKM_SKIPJACK_OFB64 0x00001003 9229 #define CKM_SKIPJACK_CFB64 0x00001004 9230 #define CKM_SKIPJACK_CFB32 0x00001005 9231 #define CKM_SKIPJACK_CFB16 0x00001006 9232 #define CKM_SKIPJACK_CFB8 0x00001007 9233 #define CKM_SKIPJACK_WRAP 0x00001008 9234 #define CKM_SKIPJACK_PRIVATE_WRAP 0x00001009 9235 #define CKM_SKIPJACK_RELAYX 0x0000100A 9236 #define CKM_KEA_KEY_PAIR_GEN 0x00001010 9237 #define CKM_KEA_KEY_DERIVE 0x00001011 9238 #define CKM_KEA_DERIVE 0x00001012 9239 #define CKM_FORTEZZA_TIMESTAMP 0x00001020 9240 #define CKM_BATON_KEY_GEN 0x00001030 9241 #define CKM_BATON_ECB128 0x00001031 9242 #define CKM_BATON_ECB96 0x00001032 9243 #define CKM_BATON_CBC128 0x00001033 9244 #define CKM_BATON_COUNTER 0x00001034 9245 #define CKM_BATON_SHUFFLE 0x00001035 9246 #define CKM_BATON_WRAP 0x00001036 9247 #define CKM_EC_KEY_PAIR_GEN 0x00001040 9248 #define CKM_ECDSA 0x00001041 9249 #define CKM_ECDSA_SHA1 0x00001042 9250 #define CKM_ECDSA_SHA224 0x00001043 9251 #define CKM_ECDSA_SHA256 0x00001044 9252 #define CKM_ECDSA_SHA384 0x00001045 9253 #define CKM_ECDSA_SHA512 0x00001046 9254 #define CKM_ECDSA_SHA3_224 0x00001047 9255 #define CKM_ECDSA_SHA3_256 0x00001048 9256 #define CKM_ECDSA_SHA3_384 0x00001049 9257 #define CKM_ECDSA_SHA3_512 0x0000104A 9258 #define CKM_ECDH1_DERIVE 0x00001050 9259 #define CKM_ECDH1_COFACTOR_DERIVE 0x00001051 9260 #define CKM_ECMQV_DERIVE 0x00001052 9261 #define CKM_ECDH_AES_KEY_WRAP 0x00001053 9262 #define CKM_RSA_AES_KEY_WRAP 0x00001054 9263 #define CKM_EC_EDWARDS_KEY_PAIR_GEN 0x00001055 9264 #define CKM_EC_MONTGOMERY_KEY_PAIR_GEN 0x00001056 9265 #define CKM_EDDSA 0x00001057 9266 #define CKM_JUNIPER_KEY_GEN 0x00001060 9267 #define CKM_JUNIPER_ECB128 0x00001061 9268 #define CKM_JUNIPER_CBC128 0x00001062 9269 #define CKM_JUNIPER_COUNTER 0x00001063 9270 #define CKM_JUNIPER_SHUFFLE 0x00001064 9271 #define CKM_JUNIPER_WRAP 0x00001065 9272 #define CKM_FASTHASH 0x00001070 9273 #define CKM_AES_XTS 0x00001071
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 268 of 278 9274 #define CKM_AEX_XTS_KEY_GEN 0x00001072 9275 #define CKM_AES_KEY_GEN 0x00001080 9276 #define CKM_AES_ECB 0x00001081 9277 #define CKM_AES_CBC 0x00001082 9278 #define CKM_AES_MAC 0x00001083 9279 #define CKM_AES_MAC_GENERAL 0x00001084 9280 #define CKM_AES_CBC_PAD 0x00001085 9281 #define CKM_AES_CTR 0x00001086 9282 #define CKM_AES_GCM 0x00001087 9283 #define CKM_AES_CCM 0x00001088 9284 #define CKM_AES_CMAC_GENERAL 0x00001089 9285 #define CKM_AES_CMAC 0x0000108A 9286 #define CKM_AES_CTS 0x0000108B 9287 #define CKM_AES_XCBC_MAC 0x0000108C 9288 #define CKM_AES_XCBC_MAC_96 0x0000108D 9289 #define CKM_AES_GMAC 0x0000108E 9290 #define CKM_BLOWFISH_KEY_GEN 0x00001090 9291 #define CKM_BLOWFISH_CBC 0x00001091 9292 #define CKM_TWOFISH_KEY_GEN 0x00001092 9293 #define CKM_TWOFISH_CBC 0x00001093 9294 #define CKM_BLOWFISH_CBC_PAD 0x00001094 9295 #define CKM_TWOFISH_CBC_PAD 0x00001095 9296 #define CKM_DES_ECB_ENCRYPT_DATA 0x00001100 9297 #define CKM_DES_CBC_ENCRYPT_DATA 0x00001101 9298 #define CKM_DES3_ECB_ENCRYPT_DATA 0x00001102 9299 #define CKM_DES3_CBC_ENCRYPT_DATA 0x00001103 9300 #define CKM_AES_ECB_ENCRYPT_DATA 0x00001104 9301 #define CKM_AES_CBC_ENCRYPT_DATA 0x00001105 9302 #define CKM_GOSTR3410_KEY_PAIR_GEN 0x00001200 9303 #define CKM_GOSTR3410 0x00001201 9304 #define CKM_GOSTR3410_WITH_GOSTR3411 0x00001202 9305 #define CKM_GOSTR3410_KEY_WRAP 0x00001203 9306 #define CKM_GOSTR3410_DERIVE 0x00001204 9307 #define CKM_GOSTR3411 0x00001210 9308 #define CKM_GOSTR3411_HMAC 0x00001211 9309 #define CKM_GOST28147_KEY_GEN 0x00001220 9310 #define CKM_GOST28147_ECB 0x00001221 9311 #define CKM_GOST28147 0x00001222 9312 #define CKM_GOST28147_MAC 0x00001223 9313 #define CKM_GOST28147_KEY_WRAP 0x00001224 9314 #define CKM_CHACHA20_KEY_GEN 0x00001225 9315 #define CKM_CHACHA20 0x00001226 9316 #define CKM_POLY1305_KEY_GEN 0x00001227 9317 #define CKM_POLY1305 0x00001228 9318 #define CKM_DSA_PARAMETER_GEN 0x00002000 9319 #define CKM_DH_PKCS_PARAMETER_GEN 0x00002001 9320 #define CKM_X9_42_DH_PKCS_PARAMETER_GEN 0x00002002 9321 #define CKM_DSA_PROBABLISTIC_PARAMETER_GEN 0x00002003
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 269 of 278 9322 #define CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN 0x00002004 9323 #define CKM_AES_OFB 0x00002104 9324 #define CKM_AES_CFB64 0x00002105 9325 #define CKM_AES_CFB8 0x00002106 9326 #define CKM_AES_CFB128 0x00002107 9327 #define CKM_AES_CFB1 0x00002108 9328 #define CKM_AES_KEY_WRAP 0x00002109 9329 #define CKM_AES_KEY_WRAP_PAD 0x0000210A 9330 #define CKM_AES_KEY_WRAP_KWP 0x0000210B 9331 #define CKM_RSA_PKCS_TPM_1_1 0x00004001 9332 #define CKM_RSA_PKCS_OAEP_TPM_1_1 0x00004002 9333 #define CKM_SHA_1_KEY_GEN 0x00004003 9334 #define CKM_SHA224_KEY_GEN 0x00004004 9335 #define CKM_SHA256_KEY_GEN 0x00004005 9336 #define CKM_SHA384_KEY_GEN 0x00004006 9337 #define CKM_SHA512_KEY_GEN 0x00004007 9338 #define CKM_SHA512_224_KEY_GEN 0x00004008 9339 #define CKM_SHA512_256_KEY_GEN 0x00004009 9340 #define CKM_SHA512_T_KEY_GEN 0x0000400A 9341 #define CKM_NULL 0x0000400B 9342 #define CKM_BLAKE2B_160 0x0000400C 9343 #define CKM_BLAKE2B_160_HMAC 0x0000400D 9344 #define CKM_BLAKE2B_160_HMAC_GENERAL 0x0000400E 9345 #define CKM_BLAKE2B_160_KEY_DERIVE 0x0000400F 9346 #define CKM_BLAKE2B_160_KEY_GEN 0x00004010 9347 #define CKM_BLAKE2B_256 0x00004011 9348 #define CKM_BLAKE2B_256_HMAC 0x00004012 9349 #define CKM_BLAKE2B_256_HMAC_GENERAL 0x00004013 9350 #define CKM_BLAKE2B_256_KEY_DERIVE 0x00004014 9351 #define CKM_BLAKE2B_256_KEY_GEN 0x00004015 9352 #define CKM_BLAKE2B_384 0x00004016 9353 #define CKM_BLAKE2B_384_HMAC 0x00004017 9354 #define CKM_BLAKE2B_384_HMAC_GENERAL 0x00004018 9355 #define CKM_BLAKE2B_384_KEY_DERIVE 0x00004019 9356 #define CKM_BLAKE2B_384_KEY_GEN 0x0000401A 9357 #define CKM_BLAKE2B_512 0x0000401B 9358 #define CKM_BLAKE2B_512_HMAC 0x0000401C 9359 #define CKM_BLAKE2B_512_HMAC_GENERAL 0x0000401D 9360 #define CKM_BLAKE2B_512_KEY_DERIVE 0x0000401E 9361 #define CKM_BLAKE2B_512_KEY_GEN 0x0000401F 9362 #define CKM_SALSA20 0x00004020 9363 #define CKM_CHACHA20_POLY1305 0x00004021 9364 #define CKM_SALSA20_POLY1305 0x00004022 9365 #define CKM_X3DH_INITIALIZE 0x00004023 9366 #define CKM_X3DH_RESPOND 0x00004024 9367 #define CKM_X2RATCHET_INITIALIZE 0x00004025 9368 #define CKM_X2RATCHET_RESPOND 0x00004026 9369 #define CKM_X2RATCHET_ENCRYPT 0x00004027
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 270 of 278 9370 #define CKM_X2RATCHET_DECRYPT 0x00004028 9371 #define CKM_XEDDSA 0x00004029 9372 #define CKM_HKDF_DERIVE 0x0000402A 9373 #define CKM_HKDF_DATA 0x0000402B 9374 #define CKM_HKDF_KEY_GEN 0x0000402C 9375 #define CKM_VENDOR_DEFINED 0x80000000
9376 B.5 Attributes 9377 #define CKA_CLASS 0x00000000 9378 #define CKA_TOKEN 0x00000001 9379 #define CKA_PRIVATE 0x00000002 9380 #define CKA_LABEL 0x00000003 9381 #define CKA_UNIQUE_ID 0x00000004 9382 #define CKA_APPLICATION 0x00000010 9383 #define CKA_VALUE 0x00000011 9384 #define CKA_OBJECT_ID 0x00000012 9385 #define CKA_CERTIFICATE_TYPE 0x00000080 9386 #define CKA_ISSUER 0x00000081 9387 #define CKA_SERIAL_NUMBER 0x00000082 9388 #define CKA_AC_ISSUER 0x00000083 9389 #define CKA_OWNER 0x00000084 9390 #define CKA_ATTR_TYPES 0x00000085 9391 #define CKA_TRUSTED 0x00000086 9392 #define CKA_CERTIFICATE_CATEGORY 0x00000087 9393 #define CKA_JAVA_MIDP_SECURITY_DOMAIN 0x00000088 9394 #define CKA_URL 0x00000089 9395 #define CKA_HASH_OF_SUBJECT_PUBLIC_KEY 0x0000008A 9396 #define CKA_HASH_OF_ISSUER_PUBLIC_KEY 0x0000008B 9397 #define CKA_NAME_HASH_ALGORITHM 0x0000008C 9398 #define CKA_CHECK_VALUE 0x00000090 9399 #define CKA_KEY_TYPE 0x00000100 9400 #define CKA_SUBJECT 0x00000101 9401 #define CKA_ID 0x00000102 9402 #define CKA_SENSITIVE 0x00000103 9403 #define CKA_ENCRYPT 0x00000104 9404 #define CKA_DECRYPT 0x00000105 9405 #define CKA_WRAP 0x00000106 9406 #define CKA_UNWRAP 0x00000107 9407 #define CKA_SIGN 0x00000108 9408 #define CKA_SIGN_RECOVER 0x00000109 9409 #define CKA_VERIFY 0x0000010A 9410 #define CKA_VERIFY_RECOVER 0x0000010B 9411 #define CKA_DERIVE 0x0000010C 9412 #define CKA_START_DATE 0x00000110 9413 #define CKA_END_DATE 0x00000111 9414 #define CKA_MODULUS 0x00000120 9415 #define CKA_MODULUS_BITS 0x00000121 9416 #define CKA_PUBLIC_EXPONENT 0x00000122
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 271 of 278 9417 #define CKA_PRIVATE_EXPONENT 0x00000123 9418 #define CKA_PRIME_1 0x00000124 9419 #define CKA_PRIME_2 0x00000125 9420 #define CKA_EXPONENT_1 0x00000126 9421 #define CKA_EXPONENT_2 0x00000127 9422 #define CKA_COEFFICIENT 0x00000128 9423 #define CKA_PUBLIC_KEY_INFO 0x00000129 9424 #define CKA_PRIME 0x00000130 9425 #define CKA_SUBPRIME 0x00000131 9426 #define CKA_BASE 0x00000132 9427 #define CKA_PRIME_BITS 0x00000133 9428 #define CKA_SUBPRIME_BITS 0x00000134 9429 #define CKA_SUB_PRIME_BITS CKA_SUBPRIME_BITS 9430 #define CKA_VALUE_BITS 0x00000160 9431 #define CKA_VALUE_LEN 0x00000161 9432 #define CKA_EXTRACTABLE 0x00000162 9433 #define CKA_LOCAL 0x00000163 9434 #define CKA_NEVER_EXTRACTABLE 0x00000164 9435 #define CKA_ALWAYS_SENSITIVE 0x00000165 9436 #define CKA_KEY_GEN_MECHANISM 0x00000166 9437 #define CKA_MODIFIABLE 0x00000170 9438 #define CKA_COPYABLE 0x00000171 9439 #define CKA_DESTROYABLE 0x00000172 9440 #define CKA_EC_PARAMS 0x00000180 9441 #define CKA_EC_POINT 0x00000181 9442 #define CKA_WRAP_WITH_TRUSTED 0x00000210 9443 #define CKA_WRAP_TEMPLATE (CKF_ARRAY_ATTRIBUTE|0x00000211) 9444 #define CKA_UNWRAP_TEMPLATE (CKF_ARRAY_ATTRIBUTE|0x00000212) 9445 #define CKA_DERIVE_TEMPLATE (CKF_ARRAY_ATTRIBUTE|0x00000213) 9446 #define CKA_OTP_FORMAT 0x00000220 9447 #define CKA_OTP_LENGTH 0x00000221 9448 #define CKA_OTP_TIME_INTERVAL 0x00000222 9449 #define CKA_OTP_USER_FRIENDLY_MODE 0x00000223 9450 #define CKA_OTP_CHALLENGE_REQUIREMENT 0x00000224 9451 #define CKA_OTP_TIME_REQUIREMENT 0x00000225 9452 #define CKA_OTP_COUNTER_REQUIREMENT 0x00000226 9453 #define CKA_OTP_PIN_REQUIREMENT 0x00000227 9454 #define CKA_OTP_USER_IDENTIFIER 0x0000022A 9455 #define CKA_OTP_SERVICE_IDENTIFIER 0x0000022B 9456 #define CKA_OTP_SERVICE_LOGO 0x0000022C 9457 #define CKA_OTP_SERVICE_LOGO_TYPE 0x0000022D 9458 #define CKA_OTP_COUNTER 0x0000022E 9459 #define CKA_OTP_TIME 0x0000022F 9460 #define CKA_GOSTR3410_PARAMS 0x00000250 9461 #define CKA_GOSTR3411_PARAMS 0x00000251 9462 #define CKA_GOST28147_PARAMS 0x00000252 9463 #define CKA_HW_FEATURE_TYPE 0x00000300 9464 #define CKA_RESET_ON_INIT 0x00000301
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 272 of 278 9465 #define CKA_HAS_RESET 0x00000302 9466 #define CKA_PIXEL_X 0x00000400 9467 #define CKA_PIXEL_Y 0x00000401 9468 #define CKA_RESOLUTION 0x00000402 9469 #define CKA_CHAR_ROWS 0x00000403 9470 #define CKA_CHAR_COLUMNS 0x00000404 9471 #define CKA_COLOR 0x00000405 9472 #define CKA_BITS_PER_PIXEL 0x00000406 9473 #define CKA_CHAR_SETS 0x00000480 9474 #define CKA_ENCODING_METHODS 0x00000481 9475 #define CKA_MIME_TYPES 0x00000482 9476 #define CKA_MECHANISM_TYPE 0x00000500 9477 #define CKA_REQUIRED_CMS_ATTRIBUTES 0x00000501 9478 #define CKA_DEFAULT_CMS_ATTRIBUTES 0x00000502 9479 #define CKA_SUPPORTED_CMS_ATTRIBUTES 0x00000503 9480 #define CKA_ALLOWED_MECHANISMS 9481 (CKF_ARRAY_ATTRIBUTE|0x00000600) 9482 #define CKA_VENDOR_DEFINED 0x80000000
9483 B.6 Attribute constants 9484 #define CK_OTP_FORMAT_DECIMAL 0x00000000 9485 #define CK_OTP_FORMAT_HEXADECIMAL 0x00000001 9486 #define CK_OTP_FORMAT_ALPHANUMERIC 0x00000002 9487 #define CK_OTP_FORMAT_BINARY 0x00000003 9488 9489 #define CK_OTP_PARAM_IGNORED 0x00000000 9490 #define CK_OTP_PARAM_OPTIONAL 0x00000001 9491 #define CK_OTP_PARAM_MANDATORY 0x00000002 9492 9493 #define CK_OTP_VALUE 0x00000000 9494 #define CK_OTP_PIN 0x00000001 9495 #define CK_OTP_CHALLENGE 0x00000002 9496 #define CK_OTP_TIME 0x00000003 9497 #define CK_OTP_COUNTER 0x00000004 9498 #define CK_OTP_FLAGS 0x00000005 9499 #define CK_OTP_OUTPUT_LENGTH 0x00000006 9500 #define CK_OTP_FORMAT 0x00000007
9501 B.7 Other constants 9502 #define CKF_NEXT_OTP 0x00000001 9503 #define CKF_EXCLUDE_TIME 0x00000002 9504 #define CKF_EXCLUDE_COUNTER 0x00000004 9505 #define CKF_EXCLUDE_CHALLENGE 0x00000008 9506 #define CKF_EXCLUDE_PIN 0x00000010 9507 #define CKF_USER_FRIENDLY_OTP 0x00000020 9508 9509 #define CKF_HKDF_SALT_NULL 0x00000001
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 273 of 278 9510 #define CKF_HKDF_SALT_DATA 0x00000002 9511 #define CKF_HKDF_SALT_KEY 0x00000004
9512 B.8 Notifications 9513 #define CKN_OTP_CHANGED 0x00000001
9514 B.9 Return values 9515 #define CKR_OK 0x00000000 9516 #define CKR_CANCEL 0x00000001 9517 #define CKR_HOST_MEMORY 0x00000002 9518 #define CKR_SLOT_ID_INVALID 0x00000003 9519 #define CKR_GENERAL_ERROR 0x00000005 9520 #define CKR_FUNCTION_FAILED 0x00000006 9521 #define CKR_ARGUMENTS_BAD 0x00000007 9522 #define CKR_NO_EVENT 0x00000008 9523 #define CKR_NEED_TO_CREATE_THREADS 0x00000009 9524 #define CKR_CANT_LOCK 0x0000000A 9525 #define CKR_ATTRIBUTE_READ_ONLY 0x00000010 9526 #define CKR_ATTRIBUTE_SENSITIVE 0x00000011 9527 #define CKR_ATTRIBUTE_TYPE_INVALID 0x00000012 9528 #define CKR_ATTRIBUTE_VALUE_INVALID 0x00000013 9529 #define CKR_ACTION_PROHIBITED 0x0000001B 9530 #define CKR_DATA_INVALID 0x00000020 9531 #define CKR_DATA_LEN_RANGE 0x00000021 9532 #define CKR_DEVICE_ERROR 0x00000030 9533 #define CKR_DEVICE_MEMORY 0x00000031 9534 #define CKR_DEVICE_REMOVED 0x00000032 9535 #define CKR_ENCRYPTED_DATA_INVALID 0x00000040 9536 #define CKR_ENCRYPTED_DATA_LEN_RANGE 0x00000041 9537 #define CKR_AEAD_DECRYPT_FAILED 0x00000042 9538 #define CKR_FUNCTION_CANCELED 0x00000050 9539 #define CKR_FUNCTION_NOT_PARALLEL 0x00000051 9540 #define CKR_FUNCTION_NOT_SUPPORTED 0x00000054 9541 #define CKR_KEY_HANDLE_INVALID 0x00000060 9542 #define CKR_KEY_SIZE_RANGE 0x00000062 9543 #define CKR_KEY_TYPE_INCONSISTENT 0x00000063 9544 #define CKR_KEY_NOT_NEEDED 0x00000064 9545 #define CKR_KEY_CHANGED 0x00000065 9546 #define CKR_KEY_NEEDED 0x00000066 9547 #define CKR_KEY_INDIGESTIBLE 0x00000067 9548 #define CKR_KEY_FUNCTION_NOT_PERMITTED 0x00000068 9549 #define CKR_KEY_NOT_WRAPPABLE 0x00000069 9550 #define CKR_KEY_UNEXTRACTABLE 0x0000006A 9551 #define CKR_MECHANISM_INVALID 0x00000070 9552 #define CKR_MECHANISM_PARAM_INVALID 0x00000071 9553 #define CKR_OBJECT_HANDLE_INVALID 0x00000082 9554 #define CKR_OPERATION_ACTIVE 0x00000090
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 274 of 278 9555 #define CKR_OPERATION_NOT_INITIALIZED 0x00000091 9556 #define CKR_PIN_INCORRECT 0x000000A0 9557 #define CKR_PIN_INVALID 0x000000A1 9558 #define CKR_PIN_LEN_RANGE 0x000000A2 9559 #define CKR_PIN_EXPIRED 0x000000A3 9560 #define CKR_PIN_LOCKED 0x000000A4 9561 #define CKR_SESSION_CLOSED 0x000000B0 9562 #define CKR_SESSION_COUNT 0x000000B1 9563 #define CKR_SESSION_HANDLE_INVALID 0x000000B3 9564 #define CKR_SESSION_PARALLEL_NOT_SUPPORTED 0x000000B4 9565 #define CKR_SESSION_READ_ONLY 0x000000B5 9566 #define CKR_SESSION_EXISTS 0x000000B6 9567 #define CKR_SESSION_READ_ONLY_EXISTS 0x000000B7 9568 #define CKR_SESSION_READ_WRITE_SO_EXISTS 0x000000B8 9569 #define CKR_SIGNATURE_INVALID 0x000000C0 9570 #define CKR_SIGNATURE_LEN_RANGE 0x000000C1 9571 #define CKR_TEMPLATE_INCOMPLETE 0x000000D0 9572 #define CKR_TEMPLATE_INCONSISTENT 0x000000D1 9573 #define CKR_TOKEN_NOT_PRESENT 0x000000E0 9574 #define CKR_TOKEN_NOT_RECOGNIZED 0x000000E1 9575 #define CKR_TOKEN_WRITE_PROTECTED 0x000000E2 9576 #define CKR_UNWRAPPING_KEY_HANDLE_INVALID 0x000000F0 9577 #define CKR_UNWRAPPING_KEY_SIZE_RANGE 0x000000F1 9578 #define CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT 0x000000F2 9579 #define CKR_USER_ALREADY_LOGGED_IN 0x00000100 9580 #define CKR_USER_NOT_LOGGED_IN 0x00000101 9581 #define CKR_USER_PIN_NOT_INITIALIZED 0x00000102 9582 #define CKR_USER_TYPE_INVALID 0x00000103 9583 #define CKR_USER_ANOTHER_ALREADY_LOGGED_IN 0x00000104 9584 #define CKR_USER_TOO_MANY_TYPES 0x00000105 9585 #define CKR_WRAPPED_KEY_INVALID 0x00000110 9586 #define CKR_WRAPPED_KEY_LEN_RANGE 0x00000112 9587 #define CKR_WRAPPING_KEY_HANDLE_INVALID 0x00000113 9588 #define CKR_WRAPPING_KEY_SIZE_RANGE 0x00000114 9589 #define CKR_WRAPPING_KEY_TYPE_INCONSISTENT 0x00000115 9590 #define CKR_RANDOM_SEED_NOT_SUPPORTED 0x00000120 9591 #define CKR_RANDOM_NO_RNG 0x00000121 9592 #define CKR_DOMAIN_PARAMS_INVALID 0x00000130 9593 #define CKR_CURVE_NOT_SUPPORTED 0x00000140 9594 #define CKR_BUFFER_TOO_SMALL 0x00000150 9595 #define CKR_SAVED_STATE_INVALID 0x00000160 9596 #define CKR_INFORMATION_SENSITIVE 0x00000170 9597 #define CKR_STATE_UNSAVEABLE 0x00000180 9598 #define CKR_CRYPTOKI_NOT_INITIALIZED 0x00000190 9599 #define CKR_CRYPTOKI_ALREADY_INITIALIZED 0x00000191 9600 #define CKR_MUTEX_BAD 0x000001A0 9601 #define CKR_MUTEX_NOT_LOCKED 0x000001A1 9602 #define CKR_NEW_PIN_MODE 0x000001B0
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 275 of 278 9603 #define CKR_NEXT_OTP 0x000001B1 9604 #define CKR_EXCEEDED_MAX_ITERATIONS 0x000001B5 9605 #define CKR_FIPS_SELF_TEST_FAILED 0x000001B6 9606 #define CKR_LIBRARY_LOAD_FAILED 0x000001B7 9607 #define CKR_PIN_TOO_WEAK 0x000001B8 9608 #define CKR_PUBLIC_KEY_INVALID 0x000001B9 9609 #define CKR_FUNCTION_REJECTED 0x00000200 9610 #define CKR_VENDOR_DEFINED 0x80000000 9611
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 276 of 278 9612 Appendix C. Revision History
Revision Date Editor Changes Made
Wd02 18-Jun-2017 Chris Zimman Initial version incorporating recent changes since 2.41
WD07 16-Oct-2018 Dieter Bong See pkcs11-curr-v3.0-updates-from-wd06-to- wd07.docx
WD08 22-Oct-2018 Dieter Bong Added references [SALSA] to section 1.3 Split GOST Mechanisms vs. Functions table for GOST into separate tables for the respective GOST nnn algorithms. Changed format of Salsa20 to Heading2, making it section 2.59 Removed section B.1 OTP definitions (OTP definitions have become pat of the standard header files and are now covered in B.6 Attribute constants) Copyright updated from “2013” to “2018”
WD09 26-Mar-2019 Daniel Minder Added CKF_EC_CURVENAME to table 34 Changed CK_GCM_AEAD_PARAMS to CK_GCM_MESSAGE_PARAMS Reworked section 2.13 (additional AES mechanisms) during F2F Removed Derive for CKM_AES_GMAC in Table 80 since this is not defined in section 2.13.4 Removed solved comments of Chris typos and formatting Edwards curves and RFC 8410: - Added reference to RFC 8410 at several places in 2.3.5 - 2.3.14 - Clarified that Edwards/Montgomery curves specified with curveName are incompatible with curves specified with oId (since RFC 8410 is designed like this) - Added explanation for CKM_TOKEN_RESOURCE_EXCEEDED error in 2.3.14 - Changed sample template for edwards public key objects in 2.3.5 since the parameter spec was in ecPoint instead of ecParams - Added "allowed key types" table in 2.3.17 - 2.3.20 (they were lost when copying from the proposal), but corrected it for ECDH with cofactor since this is not possible according to RFC8032.
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 277 of 278 Corrected some formatting issues raised by Darren
WD10 29 Apr 2019 Dieter Bong - Updated section Related work - Added Dieter Bong as Editor - Put year 2019 in Copyright - Added section 2.62 HKDF Mechanisms; HKDF constants in Appendix B; RFC5869 in section 1.4 Non-Normative References - Section 2.40: added CKM_NULL, removed CKM_TLS10_MAC_* - Section 2.52.7.1 reference to base specification corrrected - Replaced reference to [PKCS11-Base] table 10 by [PKCS11-Base] table 11 throughout whole document - Removed all occurences of CKK_ECDSA and CKA_ECDSA_PARAMS and added notices that they are deprecated - Removed #define’s for CKA_SECONDARY_AUTH, CKA_AUTH_PIN_FLAGS and CKA_ALWAYS_AUTHENTICATE - Removed #define’s for CAST5 mechanisms
WD10 Rev. 2 7 May 2019 Dieter Bong - Moved CKM_NULL to own section 2.63 - Removed 2 remaining occurences of CKA_ECDSA_PARAMS
WD11 May 28, Tony Cox - Final cleanup of front introductory texts 2019 and links prior to CSPRD
9613
pkcs11-curr-v3.0-wd110-rev2 Working Draft 10 Rev. 21 287 May 2019 Standards Track Draft Copyright © OASIS Open 2019. All Rights Reserved. Page 278 of 278