PKCS #11 Cryptographic Token Interface Current Mechanisms Specification Version 2.40

OASIS Standard

14 April 2015

Specification URIs

This version:

http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/os/pkcs11-curr-v2.40-os.doc (Authoritative)

http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/os/pkcs11-curr-v2.40-os.html

http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/os/pkcs11-curr-v2.40-os.pdf

Previous version:

http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/cs01/pkcs11-curr-v2.40-cs01.doc (Authoritative)

http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/cs01/pkcs11-curr-v2.40-cs01.html

http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/cs01/pkcs11-curr-v2.40-cs01.pdf

Latest version:

http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/pkcs11-curr-v2.40.doc (Authoritative)

http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/pkcs11-curr-v2.40.html

http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/pkcs11-curr-v2.40.pdf

Technical Committee:

OASIS PKCS 11 TC

Chairs:

Robert Griffin (robert.griffin@rsa.com), EMC Corporation

Valerie Fenwick (valerie.fenwick@oracle.com), Oracle

Editors:

Susan Gleeson (susan.gleeson@oracle.com), Oracle

Chris Zimman (chris@wmpp.com), Individual

Related work:

This specification is related to:

·         PKCS #11 Cryptographic Token Interface Base Specification Version 2.40. Edited by Susan Gleeson and Chris Zimman. Latest version. http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html.

·         PKCS #11 Cryptographic Token Interface Profiles Version 2.40. Edited by Tim Hudson. Latest version. http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/pkcs11-profiles-v2.40.html.

·         PKCS #11 Cryptographic Token Interface Historical Mechanisms Specification Version 2.40. Edited by Susan Gleeson and Chris Zimman. Latest version. http://docs.oasis-open.org/pkcs11/pkcs11-hist/v2.40/pkcs11-hist-v2.40.html.

·         PKCS #11 Cryptographic Token Interface Usage Guide Version 2.40. Edited by John Leiseboer and Robert Griffin. Latest version. http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/pkcs11-ug-v2.40.html.

Abstract:

This document defines mechanisms that are anticipated for use with the current version of PKCS #11.

Status:

This document was last revised or approved by the membership of OASIS on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=pkcs11#technical.

TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/pkcs11/.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (https://www.oasis-open.org/committees/pkcs11/ipr.php).

Citation format:

When referencing this specification the following citation format should be used:

[PKCS11-curr-v2.40]

PKCS #11 Cryptographic Token Interface Current Mechanisms Specification Version 2.40. Edited by Susan Gleeson and Chris Zimman. 14 April 2015. OASIS Standard. http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/os/pkcs11-curr-v2.40-os.html. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/pkcs11-curr-v2.40.html.

 

Notices

Copyright © OASIS Open 2015. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.

 

Table of Contents

1        Introduction. 12

1.1 Terminology. 12

1.2 Definitions. 12

1.3 Normative References. 13

1.4 Non-Normative References. 15

2        Mechanisms. 18

2.1 RSA. 18

2.1.1 Definitions. 19

2.1.2 RSA public key objects. 20

2.1.3 RSA private key objects. 20

2.1.4 PKCS #1 RSA key pair generation. 22

2.1.5 X9.31 RSA key pair generation. 23

2.1.6 PKCS #1 v1.5 RSA. 23

2.1.7 PKCS #1 RSA OAEP mechanism parameters. 24

2.1.8 PKCS #1 RSA OAEP. 25

2.1.9 PKCS #1 RSA PSS mechanism parameters. 26

2.1.10 PKCS #1 RSA PSS. 26

2.1.11 ISO/IEC 9796 RSA. 27

2.1.12 X.509 (raw) RSA. 27

2.1.13 ANSI X9.31 RSA. 28

2.1.14 PKCS #1 v1.5 RSA signature with MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512, RIPE-MD 128 or RIPE-MD 160  29

2.1.15 PKCS #1 v1.5 RSA signature with SHA-224. 30

2.1.16 PKCS #1 RSA PSS signature with SHA-224. 30

2.1.17 PKCS #1 RSA PSS signature with SHA-1, SHA-256, SHA-384 or SHA-512. 30

2.1.18 ANSI X9.31 RSA signature with SHA-1. 30

2.1.19 TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA. 31

2.1.20 TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP. 31

2.1.21 RSA AES KEY WRAP. 32

2.1.22 RSA AES KEY WRAP mechanism parameters. 33

2.1.23 FIPS 186-4. 34

2.2 DSA. 34

2.2.1 Definitions. 34

2.2.2 DSA public key objects. 35

2.2.3 DSA Key Restrictions. 36

2.2.4 DSA private key objects. 36

2.2.5 DSA domain parameter objects. 37

2.2.6 DSA key pair generation. 38

2.2.7 DSA domain parameter generation. 38

2.2.8 DSA probabilistic domain parameter generation. 38

2.2.9 DSA Shawe-Taylor domain parameter generation. 39

2.2.10 DSA base domain parameter generation. 39

2.2.11 DSA without hashing. 39

2.2.12 DSA with SHA-1. 40

2.2.13 FIPS 186-4. 40

2.2.14 DSA with SHA-224. 40

2.2.15 DSA with SHA-256. 41

2.2.16 DSA with SHA-384. 41

2.2.17 DSA with SHA-512. 42

2.3 Elliptic Curve. 42

2.3.1 EC Signatures. 43

2.3.2 Definitions. 44

2.3.3 ECDSA public key objects. 44

2.3.4 Elliptic curve private key objects. 45

2.3.5 Elliptic curve key pair generation. 46

2.3.6 ECDSA without hashing. 46

2.3.7 ECDSA with SHA-1. 47

2.3.8 EC mechanism parameters. 47

2.3.9 Elliptic curve Diffie-Hellman key derivation. 50

2.3.10 Elliptic curve Diffie-Hellman with cofactor key derivation. 50

2.3.11 Elliptic curve Menezes-Qu-Vanstone key derivation. 51

2.3.12 ECDH AES KEY WRAP. 51

2.3.13 ECDH AES KEY WRAP mechanism parameters. 53

2.3.14 FIPS 186-4. 53

2.4 Diffie-Hellman. 53

2.4.1 Definitions. 54

2.4.2 Diffie-Hellman public key objects. 54

2.4.3 X9.42 Diffie-Hellman public key objects. 55

2.4.4 Diffie-Hellman private key objects. 56

2.4.5 X9.42 Diffie-Hellman private key objects. 57

2.4.6 Diffie-Hellman domain parameter objects. 58

2.4.7 X9.42 Diffie-Hellman domain parameters objects. 58

2.4.8 PKCS #3 Diffie-Hellman key pair generation. 59

2.4.9 PKCS #3 Diffie-Hellman domain parameter generation. 59

2.4.10 PKCS #3 Diffie-Hellman key derivation. 60

2.4.11 X9.42 Diffie-Hellman mechanism parameters. 60

2.4.12 X9.42 Diffie-Hellman key pair generation. 63

2.4.13 X9.42 Diffie-Hellman domain parameter generation. 64

2.4.14 X9.42 Diffie-Hellman key derivation. 64

2.4.15 X9.42 Diffie-Hellman hybrid key derivation. 64

2.4.16 X9.42 Diffie-Hellman Menezes-Qu-Vanstone key derivation. 65

2.5 Wrapping/unwrapping private keys. 66

2.6 Generic secret key. 68

2.6.1 Definitions. 68

2.6.2 Generic secret key objects. 68

2.6.3 Generic secret key generation. 69

2.7 HMAC mechanisms. 69

2.8 AES. 69

2.8.1 Definitions. 70

2.8.2 AES secret key objects. 70

2.8.3 AES key generation. 71

2.8.4 AES-ECB. 71

2.8.5 AES-CBC. 72

2.8.6 AES-CBC with PKCS padding. 73

2.8.7 AES-OFB. 73

2.8.8 AES-CFB. 74

2.8.9 General-length AES-MAC. 74

2.8.10 AES-MAC. 74

2.8.11 AES-XCBC-MAC. 75

2.8.12 AES-XCBC-MAC-96. 75

2.9 AES with Counter 75

2.9.1 Definitions. 75

2.9.2 AES with Counter mechanism parameters. 76

2.9.3 AES with Counter Encryption / Decryption. 76

2.10 AES CBC with Cipher Text Stealing CTS. 77

2.10.1 Definitions. 77

2.10.2 AES CTS mechanism parameters. 77

2.11 Additional AES Mechanisms. 77

2.11.1 Definitions. 77

2.12 AES-GCM Authenticated Encryption / Decryption. 78

2.12.1 AES-CCM authenticated Encryption / Decryption. 78

2.12.2 AES-GMAC. 79

2.12.3 AES GCM and CCM Mechanism parameters. 80

2.12.4 AES-GCM authenticated Encryption / Decryption. 81

2.12.5 AES-CCM authenticated Encryption / Decryption. 81

2.13 AES CMAC. 82

2.13.1 Definitions. 82

2.13.2 Mechanism parameters. 83

2.13.3 General-length AES-CMAC. 83

2.13.4 AES-CMAC. 83

2.14 AES Key Wrap. 83

2.14.1 Definitions. 84

2.14.2 AES Key Wrap Mechanism parameters. 84

2.14.3 AES Key Wrap. 84

2.15 Key derivation by data encryption – DES & AES. 84

2.15.1 Definitions. 85

2.15.2 Mechanism Parameters. 85

2.15.3 Mechanism Description. 86

2.16 Double and Triple-length DES. 86

2.16.1 Definitions. 86

2.16.2 DES2 secret key objects. 87

2.16.3 DES3 secret key objects. 87

2.16.4 Double-length DES key generation. 88

2.16.5 Triple-length DES Order of Operations. 88

2.16.6 Triple-length DES in CBC Mode. 88

2.16.7 DES and Triple length DES in OFB Mode. 88

2.16.8 DES and Triple length DES in CFB Mode. 89

2.17 Double and Triple-length DES CMAC. 89

2.17.1 Definitions. 90

2.17.2 Mechanism parameters. 90

2.17.3 General-length DES3-MAC. 90

2.17.4 DES3-CMAC. 90

2.18 SHA-1. 91

2.18.1 Definitions. 91

2.18.2 SHA-1 digest 91

2.18.3 General-length SHA-1-HMAC. 92

2.18.4 SHA-1-HMAC. 92

2.18.5 SHA-1 key derivation. 92

2.19 SHA-224. 93

2.19.1 Definitions. 93

2.19.2 SHA-224 digest 93

2.19.3 General-length SHA-224-HMAC. 93

2.19.4 SHA-224-HMAC. 94

2.19.5 SHA-224 key derivation. 94

2.20 SHA-256. 94

2.20.1 Definitions. 94

2.20.2 SHA-256 digest 94

2.20.3 General-length SHA-256-HMAC. 95

2.20.4 SHA-256-HMAC. 95

2.20.5 SHA-256 key derivation. 95

2.21 SHA-384. 95

2.21.1 Definitions. 95

2.21.2 SHA-384 digest 96

2.21.3 General-length SHA-384-HMAC. 96

2.21.4 SHA-384-HMAC. 96

2.21.5 SHA-384 key derivation. 96

2.22 SHA-512. 96

2.22.1 Definitions. 96

2.22.2 SHA-512 digest 97

2.22.3 General-length SHA-512-HMAC. 97

2.22.4 SHA-512-HMAC. 97

2.22.5 SHA-512 key derivation. 97

2.23 SHA-512/224. 97

2.23.1 Definitions. 97

2.23.2 SHA-512/224 digest 98

2.23.3 General-length SHA-512-HMAC. 98

2.23.4 SHA-512/224-HMAC. 98

2.23.5 SHA-512/224 key derivation. 98

2.24 SHA-512/256. 98

2.24.1 Definitions. 99

2.24.2 SHA-512/256 digest 99

2.24.3 General-length SHA-512-HMAC. 99

2.24.4 SHA-512/256-HMAC. 99

2.24.5 SHA-512/256 key derivation. 99

2.25 SHA-512/t 99

2.25.1 Definitions. 100

2.25.2 SHA-512/t digest 100

2.25.3 General-length SHA-512-HMAC. 100

2.25.4 SHA-512/t-HMAC. 100

2.25.5 SHA-512/t key derivation. 101

2.26 PKCS #5 and PKCS #5-style password-based encryption (PBE) 101

2.26.1 Definitions. 101

2.26.2 Password-based encryption/authentication mechanism parameters. 101

2.26.3 PKCS #5 PBKDF2 key generation mechanism parameters. 102

2.26.4 PKCS #5 PBKD2 key generation. 104

2.27 PKCS #12 password-based encryption/authentication mechanisms. 104

2.27.1 SHA-1-PBE for 3-key triple-DES-CBC. 105

2.27.2 SHA-1-PBE for 2-key triple-DES-CBC. 105

2.27.3 SHA-1-PBA for SHA-1-HMAC. 105

2.28 SSL. 106

2.28.1 Definitions. 106

2.28.2 SSL mechanism parameters. 106

2.28.3 Pre-master key generation. 108

2.28.4 Master key derivation. 108

2.28.5 Master key derivation for Diffie-Hellman. 109

2.28.6 Key and MAC derivation. 110

2.28.7 MD5 MACing in SSL 3.0. 111

2.28.8 SHA-1 MACing in SSL 3.0. 111

2.29 TLS 1.2 Mechanisms. 111

2.29.1 Definitions. 112

2.29.2 TLS 1.2 mechanism parameters. 112

2.29.3 TLS MAC. 115

2.29.4 Master key derivation. 115

2.29.5 Master key derivation for Diffie-Hellman. 116

2.29.6 Key and MAC derivation. 117

2.29.7 CKM_TLS12_KEY_SAFE_DERIVE. 117

2.29.8 Generic Key Derivation using the TLS PRF. 118

2.30 WTLS. 118

2.30.1 Definitions. 119

2.30.2 WTLS mechanism parameters. 119

2.30.3 Pre master secret key generation for RSA key exchange suite. 122

2.30.4 Master secret key derivation. 122

2.30.5 Master secret key derivation for Diffie-Hellman and Elliptic Curve Cryptography. 123

2.30.6 WTLS PRF (pseudorandom function) 124

2.30.7 Server Key and MAC derivation. 124

2.30.8 Client key and MAC derivation. 125

2.31 Miscellaneous simple key derivation mechanisms. 126

2.31.1 Definitions. 126

2.31.2 Parameters for miscellaneous simple key derivation mechanisms. 126

2.31.3 Concatenation of a base key and another key. 127

2.31.4 Concatenation of a base key and data. 127

2.31.5 Concatenation of data and a base key. 128

2.31.6 XORing of a key and data. 129

2.31.7 Extraction of one key from another key. 129

2.32 CMS. 130

2.32.1 Definitions. 131

2.32.2 CMS Signature Mechanism Objects. 131

2.32.3 CMS mechanism parameters. 131

2.32.4 CMS signatures. 132

2.33 Blowfish. 133

2.33.1 Definitions. 134

2.33.2 BLOWFISH secret key objects. 134

2.33.3 Blowfish key generation. 135

2.33.4 Blowfish-CBC. 135

2.33.5 Blowfish-CBC with PKCS padding. 135

2.34 Twofish. 136

2.34.1 Definitions. 136

2.34.2 Twofish secret key objects. 136

2.34.3 Twofish key generation. 137

2.34.4 Twofish -CBC. 137

2.34.5 Twofish-CBC with PKCS padding. 137

2.35 CAMELLIA. 137

2.35.1 Definitions. 138

2.35.2 Camellia secret key objects. 138

2.35.3 Camellia key generation. 139

2.35.4 Camellia-ECB. 139

2.35.5 Camellia-CBC. 139

2.35.6 Camellia-CBC with PKCS padding. 140

2.35.7 General-length Camellia-MAC. 141

2.35.8 Camellia-MAC. 141

2.36 Key derivation by data encryption - Camellia. 142

2.36.1 Definitions. 142

2.36.2 Mechanism Parameters. 142

2.37 ARIA. 142

2.37.1 Definitions. 143

2.37.2 Aria secret key objects. 143

2.37.3 ARIA key generation. 144

2.37.4 ARIA-ECB. 144

2.37.5 ARIA-CBC. 144

2.37.6 ARIA-CBC with PKCS padding. 145

2.37.7 General-length ARIA-MAC. 146

2.37.8 ARIA-MAC. 146

2.38 Key derivation by data encryption - ARIA. 146

2.38.1 Definitions. 147

2.38.2 Mechanism Parameters. 147

2.39 SEED.. 147

2.39.1 Definitions. 148

2.39.2 SEED secret key objects. 149

2.39.3 SEED key generation. 149

2.39.4 SEED-ECB. 149

2.39.5 SEED-CBC. 149

2.39.6 SEED-CBC with PKCS padding. 150

2.39.7 General-length SEED-MAC. 150

2.39.8 SEED-MAC. 150

2.40 Key derivation by data encryption - SEED.. 150

2.40.1 Definitions. 150

2.40.2 Mechanism Parameters. 150

2.41 OTP. 151

2.41.1 Usage overview. 151

2.41.2 Case 1: Generation of OTP values. 151

2.41.3 Case 2: Verification of provided OTP values. 152

2.41.4 Case 3: Generation of OTP keys. 152

2.41.5 OTP objects. 153

2.41.6 OTP-related notifications. 155

2.41.7 OTP mechanisms. 156

2.41.8 RSA SecurID.. 161

2.41.9 RSA SecurID key generation. 162

2.41.10 RSA SecurID OTP generation and validation. 162

2.41.11 Return values. 162

2.41.12 OATH HOTP. 162

2.41.13 ActivIdentity ACTI 164

2.41.14 ACTI OTP generation and validation. 165

2.42 CT-KIP. 165

2.42.1 Principles of Operation. 165

2.42.2 Mechanisms. 166

2.42.3 Definitions. 166

2.42.4 CT-KIP Mechanism parameters. 166

2.42.5 CT-KIP key derivation. 167

2.42.6 CT-KIP key wrap and key unwrap. 167

2.42.7 CT-KIP signature generation. 167

2.43 GOST. 167

2.44 GOST 28147-89. 168

2.44.1 Definitions. 168

2.44.2 GOST 28147-89 secret key objects. 168

2.44.3 GOST 28147-89 domain parameter objects. 169

2.44.4 GOST 28147-89 key generation. 170

2.44.5 GOST 28147-89-ECB. 170

2.44.6 GOST 28147-89 encryption mode except ECB. 171

2.44.7 GOST 28147-89-MAC. 171

2.44.8 Definitions. 172

2.44.9 GOST R 34.11-94 domain parameter objects. 173

2.44.10 GOST R 34.11-94 digest 173

2.44.11 GOST R 34.11-94 HMAC. 174

2.45 GOST R 34.10-2001. 174

2.45.1 Definitions. 174

2.45.2 GOST R 34.10-2001 public key objects. 175

2.45.3 GOST R 34.10-2001 private key objects. 176

2.45.4 GOST R 34.10-2001 domain parameter objects. 178

2.45.5 GOST R 34.10-2001 mechanism parameters. 179

2.45.6 GOST R 34.10-2001 key pair generation. 181

2.45.7 GOST R 34.10-2001 without hashing. 181

2.45.8 GOST R 34.10-2001 with GOST R 34.11-94. 181

2.45.9 GOST 28147-89 keys wrapping/unwrapping with GOST R 34.10-2001. 182

3        PKCS #11 Implementation Conformance. 183

Appendix A.       Acknowledgments. 184

Appendix B.       Manifest Constants. 187

B.1 OTP Definitions. 187

B.2 Object classes. 187

B.3 Key types. 187

B.4 Mechanisms. 188

B.5 Attributes. 195

B.6 Attribute constants. 197

B.7 Other constants. 197

B.8 Notifications. 198

B.9 Return values. 198

Appendix C.       Revision History. 201

 

 


1      Introduction

This document defines mechanisms that are anticipated to be used with the current version of PKCS #11.

All text is normative unless otherwise labeled.

1.1 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119]

1.2 Definitions

For the purposes of this standard, the following definitions apply. Please refer to the [PKCS#11-Base] for further definitions:

                                         AES       Advanced Encryption Standard, as defined in FIPS PUB 197.

                               CAMELLIA       The Camellia encryption algorithm, as defined in RFC 3713.

                               BLOWFISH       The Blowfish Encryption Algorithm of Bruce Schneier, www.schneier.com.

                                         CBC       Cipher-Block Chaining mode, as defined in FIPS PUB 81.

                                       CDMF       Commercial Data Masking Facility, a block encipherment method specified by International Business Machines Corporation and based on DES.

                                       CMAC       Cipher-based Message Authenticate Code as defined in [NIST sp800-38b] and [RFC 4493].

                                         CMS       Cryptographic Message Syntax (see RFC 2630)

                                     CT-KIP       Cryptographic Token Key Initialization Protocol (as defined in [[CT-KIP])

                                         DES       Data Encryption Standard, as defined in FIPS PUB 46-3.

                                         DSA       Digital Signature Algorithm, as defined in FIPS PUB 186-2.

                                            EC       Elliptic Curve

                                         ECB       Electronic Codebook mode, as defined in FIPS PUB 81.

                                       ECDH       Elliptic Curve Diffie-Hellman.

                                     ECDSA       Elliptic Curve DSA, as in ANSI X9.62.

                                    ECMQV       Elliptic Curve Menezes-Qu-Vanstone

                        GOST 28147-89        The encryption algorithm, as defined in Part 2 [GOST 28147-89] and [RFC 4357] [RFC 4490], and RFC [4491].

                      GOST R 34.11-94       Hash algorithm, as defined in [GOST R 34.11-94] and [RFC 4357], [RFC 4490], and [RFC 4491].

                   GOST R 34.10-2001       The digital signature algorithm, as defined in [GOST R 34.10-2001] and [RFC 4357], [RFC 4490], and [RFC 4491].

                                             IV       Initialization Vector.

                                         MAC       Message Authentication Code.

                                         MQV       Menezes-Qu-Vanstone

                                       OAEP       Optimal Asymmetric Encryption Padding for RSA.

                                       PKCS       Public-Key Cryptography Standards.

                                          PRF       Pseudo random function.

                                          PTD       Personal Trusted Device, as defined in MeT-PTD

                                         RSA       The RSA public-key cryptosystem.

                                       SHA-1       The (revised) Secure Hash Algorithm with a 160-bit message digest, as defined in FIPS PUB 180-2.

                                   SHA-224       The Secure Hash Algorithm with a 224-bit message digest, as defined in RFC 3874. Also defined in FIPS PUB 180-2 with Change Notice 1.

                                   SHA-256       The Secure Hash Algorithm with a 256-bit message digest, as defined in FIPS PUB 180-2.

                                   SHA-384       The Secure Hash Algorithm with a 384-bit message digest, as defined in FIPS PUB 180-2.

                                   SHA-512       The Secure Hash Algorithm with a 512-bit message digest, as defined in FIPS PUB 180-2.

                                          SSL       The Secure Sockets Layer 3.0 protocol.

                                           SO       A Security Officer user.

                                          TLS       Transport Layer Security.

                                         WIM       Wireless Identification Module.

                                       WTLS       Wireless Transport Layer Security.

 

1.3 Normative References

[ARIA]                    National Security Research Institute, Korea, “Block Cipher Algorithm ARIA”,
URL:
http://tools.ietf.org/html/rfc5794

[BLOWFISH]           B. Schneier. Description of a New Variable-Length Key, 64-Bit Block Cipher (Blowfish), December 1993.
URL:  https://www.schneier.com/paper-blowfish-fse.html

[CAMELLIA]           M. Matsui, J. Nakajima, S. Moriai. A Description of the Camellia Encryption Algorithm, April 2004.
URL: http://www.ietf.org/rfc/rfc3713.txt

[CDMF]                   Johnson, D.B  The Commercial Data Masking Facility (CDMF) data privacy algorithm, March 1994.
URL: http://ieeexplore.ieee.org/xpl/articleDetails.jsp?arnumber=5389557

[DH]                        W. Diffie, M. Hellman.  New Directions in Cryptography.  Nov, 1976.
URL:  http://www-ee.stanford.edu/~hellman/publications/24.pdf

[FIPS PUB 81]        NIST.  FIPS 81: DES Modes of Operation.  December 1980.

URL:  http://csrc.nist.gov/publications/fips/fips81/fips81.htm

[FIPS PUB 186-4]    NIST.  FIPS 186-4:  Digital Signature Standard.  July 2013.
URL: 
http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf

[FIPS PUB 197]       NIST.  FIPS 197:  Advanced Encryption Standard.  November 26, 2001.
URL:  http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf

[GOST]                   V. Dolmatov, A. Degtyarev.  GOST R. 34.11-2012:  Hash Function. August 2013.
URL: 
http://tools.ietf.org/html/rfc6986

[MD2]                     B. Kaliski.  RSA Laboratories.  The MD2 Message-Digest Algorithm. April, 1992.
URL:  http://tools.ietf.org/html/rfc1319

[MD5]                     RSA Data Security.  R. Rivest.  The MD5 Message-Digest Algorithm. April, 1992.
URL:  http://tools.ietf.org/html/rfc1319

[OAEP]                   M. Bellare, P. Rogaway.  Optimal Asymmetric Encryption – How to Encrypt with RSA.  Nov 19, 1995.
URL:  http://cseweb.ucsd.edu/users/mihir/papers/oae.pdf

[PKCS #11-Base]    PKCS #11 Cryptographic Token Interface Base Specification Version 2.40. Edited by Susan Gleeson and Chris Zimman. 14 April 2015. OASIS Standard. http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html.

 [PKCS #11-Hist]    PKCS #11 Cryptographic Token Interface Historical Mechanisms Specification Version 2.40. Edited by Susan Gleeson and Chris Zimman. 14 April 2015. OASIS Standard. http://docs.oasis-open.org/pkcs11/pkcs11-hist/v2.40/os/pkcs11-hist-v2.40-os.html. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-hist/v2.40/pkcs11-hist-v2.40.html.

 [PKCS #11-Prof]    PKCS #11 Cryptographic Token Interface Profiles Version 2.40. Edited by Tim Hudson. 14 April 2015. OASIS Standard. http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/os/pkcs11-profiles-v2.40-os.html. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/pkcs11-profiles-v2.40.html.

 [RFC2119]              Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997.
URL:  http://www.ietf.org/rfc/rfc2119.txt.

[RIPEMD]               H. Dobbertin, A. Bosselaers, B. Preneel.  The hash function RIPEMD-160, Feb 13, 2012.
URL:  http://homes.esat.kuleuven.be/~bosselae/ripemd160.html

[SEED]                   KISA.  SEED 128 Algorithm Specification.  Sep 2003.
URL: http://seed.kisa.or.kr/html/egovframework/iwt/ds/ko/ref/%5B2%5D_SEED+128_Specification_english_M.pdf

[SHA-1]                   NIST.  FIPS 180-4:  Secure Hash Standard.  March 2012.
URL:  http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf

[SHA-2]                   NIST.  FIPS 180-4:  Secure Hash Standard.  March 2012.
URL:  http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf

[TWOFISH]             B. Schneier, J. Kelsey, D. Whiting, C. Hall, N. Ferguson. Twofish: A 128-Bit Block Cipher.  June 15, 1998.
URL:  https://www.schneier.com/paper-twofish-paper.pdf

1.4 Non-Normative References

[CAP-1.2]                Common Alerting Protocol Version 1.2.  01 July 2010. OASIS Standard.
URL: http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html

[AES KEYWRAP]    AES Key Wrap Specification (Draft)
URL:
http://csrc.nist.gov/groups/ST/toolkit/documents/kms/key-wrap.pdf.

[ANSI C]                 ANSI/ISO.  American National Standard for Programming Languages – C.  1990.

[ANSI X9.31]           Accredited Standards Committee X9.  Digital Signatures Using Reversible Public Key Cryptography for the Financial Services Industry (rDSA).  1998.

[ANSI X9.42]           Accredited Standards Committee X9.  Public Key Cryptography for the Financial Services Industry: Agreement of Symmetric Keys Using Discrete Logarithm Cryptography.   2003.

[ANSI X9.62]           Accredited Standards Committee X9.  Public Key Cryptography for the Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA).  1998.

[ANSI X9.63]           Accredited Standards Committee X9.  Public Key Cryptography for the Financial Services Industry: Key Agreement and Key Transport Using Elliptic Curve Cryptography.  2001.
URL:  http://webstore.ansi.org/RecordDetail.aspx?sku=X9.63-2011

[CT-KIP]                 RSA Laboratories. Cryptographic Token Key Initialization Protocol. Version 1.0, December 2005.
URL: ftp://ftp.rsasecurity.com/pub/otps/ct-kip/ct-kip-v1-0.pdf.

[CC/PP]                  CCPP-STRUCT-VOCAB, G. Klyne, F. Reynolds, C. , H. Ohto, J. Hjelm, M. H. Butler, L. Tran, Editors, W3C Recommendation, 15 January 2004,
URL:  http://www.w3.org/TR/2004/REC-CCPP-struct-vocab-20040115/
Latest version available at http://www.w3.org/TR/CCPP-struct-vocab/ 

[NIST AES CTS]     National Institute of Standards and Technology, Addendum to NIST Special Publication 800-38A, “Recommendation for Block Cipher Modes of Operation:  Three Variants of Ciphertext Stealing for CBC Mode”
URL: http://csrc.nist.gov/publications/nistpubs/800-38a/addendum-to-nist_sp800-38A.pdf

[PKCS #11-UG]       PKCS #11 Cryptographic Token Interface Usage Guide Version 2.40. Edited by John Leiseboer and Robert Griffin. 16 November 2014. OASIS Committee Note 02. http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/cn02/pkcs11-ug-v2.40-cn02.html. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/pkcs11-ug-v2.40.html.

 [RFC 2865]             Rigney et al, “Remote Authentication Dial In User Service (RADIUS)”, IETF RFC2865, June 2000.
URL:
http://www.ietf.org/rfc/rfc2865.txt.

[RFC 3394]              J. Schaad, R. Housley, Advanced Encryption Standard (AES) Key Wrap Algorithm, September 2002.
URL:  http://www.ietf.org/rfc/rfc3394.txt.

[RFC 3686]              Housley, “Using Advanced Encryption Standard (AES) Counter Mode With IPsec Encapsulating Security Payload (ESP),” IETF RFC 3686, January 2004.
URL:
http://www.ietf.org/rfc/rfc3686.txt.

[RFC 3717]              Matsui, et al, ”A Description of the Camellia Encryption Algorithm,” IETF RFC 3717, April 2004.
URL:
http://www.ietf.org/rfc/rfc3713.txt.

[RFC 3610]              Whiting, D., Housley, R., and N. Ferguson, “Counter with CBC-MAC (CCM)", IETF RFC 3610, September 2003.
URL:
http://www.ietf.org/rfc/rfc3610.txt

[RFC 3874]              Smit et al, “A 224-bit One-way Hash Function: SHA-224,” IETF RFC 3874, June 2004.
URL: http://www.ietf.org/rfc/rfc3874.txt.

[RFC 3748]              Aboba et al, “Extensible Authentication Protocol (EAP)”, IETF RFC 3748, June 2004.
URL:
http://www.ietf.org/rfc/rfc3748.txt.

[RFC 4269]               South Korean Information Security Agency (KISA) “The SEED Encryption Algorithm”, December 2005.
URL:  ftp://ftp.rfc-editor.org/in-notes/rfc4269.txt

[RFC 4309]              Housley, R., “Using Advanced Encryption Standard (AES) CCM Mode with IPsec Encapsulating Security Payload (ESP),” IETF RFC 4309, December 2005.
URL: http://www.ietf.org/rfc/rfc4309.txt

[RFC 4357]              V. Popov, I. Kurepkin, S. Leontiev “Additional Cryptographic Algorithms for Use with GOST 28147-89, GOST R 34.10-94, GOST R 34.10-2001, and GOST R 34.11-94 Algorithms”, January 2006.

[RFC 4490]              S. Leontiev, Ed. G. Chudov, Ed.  “Using the GOST 28147-89, GOST R 34.11-94,GOST R 34.10-94, and GOST R 34.10-2001 Algorithms with Cryptographic Message Syntax (CMS)”, May 2006.

[RFC 4491]               S. Leontiev, Ed., D. Shefanovski, Ed., “Using the GOST R 34.10-94, GOST R 34.10-2001, and GOST R 34.11-94 Algorithms with the Internet X.509 Public Key Infrastructure Certificate and CRL Profile”, May 2006.

[RFC 4493]              J. Song et al.  RFC 4493: The AES-CMAC Algorithm.  June 2006.
URL: http://www.ietf.org/rfc/rfc4493.txt

[SEC 1]                   Standards for Efficient Cryptography Group (SECG).  Standards for Efficient Cryptography (SEC) 1: Elliptic Curve Cryptography.  Version 1.0, September 20, 2000.

[SEC 2]                   Standards for Efficient Cryptography Group (SECG).  Standards for Efficient Cryptography (SEC) 2: Recommended Elliptic Curve Domain Parameters.  Version 1.0, September 20, 2000.

[TLS]                      [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. http://www.ietf.org/rfc/rfc2246.txt, superseded by [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.1", RFC 4346, April 2006. http://www.ietf.org/rfc/rfc4346.txt, which was superseded by [5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008.
URL: http://www.ietf.org/rfc/rfc5246.txt

[WIM]                     WAP. Wireless Identity Module. — WAP-260-WIM-20010712-a. July 2001.
URL: http://technical.openmobilealliance.org/tech/affiliates/LicenseAgreement.asp?DocName=/wap/wap-260-wim-20010712-a.pdf

[WPKI]                    Wireless Application Protocol: Public Key Infrastructure Definition. — WAP-217-WPKI-20010424-a. April 2001.
URL: 
http://technical.openmobilealliance.org/tech/affiliates/LicenseAgreement.asp?DocName=/wap/wap-217-wpki-20010424-a.pdf

[WTLS]                   WAP. Wireless Transport Layer Security Version — WAP-261-WTLS-20010406-a. April 2001.
URL: http://technical.openmobilealliance.org/tech/affiliates/LicenseAgreement.asp?DocName=/wap/wap-261-wtls-20010406-a.pdf

[X.500]                    ITU-T. Information Technology — Open Systems Interconnection — The Directory: Overview of Concepts, Models and Services.  February 2001. Identical to ISO/IEC 9594-1

[X.509]                    ITU-T. Information Technology — Open Systems Interconnection — The Directory: Public-key and Attribute Certificate Frameworks.  March 2000. Identical to ISO/IEC 9594-8

[X.680]                    ITU-T. Information Technology — Abstract Syntax Notation One (ASN.1): Specification of Basic Notation.  July 2002. Identical to ISO/IEC 8824-1

[X.690]                    ITU-T. Information Technology — ASN.1 Encoding Rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER).  July 2002. Identical to ISO/IEC 8825-1

 

2      Mechanisms

A mechanism specifies precisely how a certain cryptographic process is to be performed.  PKCS #11 implementations MAY use one of more mechanisms defined in this document.

The following table shows which Cryptoki mechanisms are supported by different cryptographic operations.  For any particular token, of course, a particular operation may well support only a subset of the mechanisms listed.  There is also no guarantee that a token which supports one mechanism for some operations supports any other mechanism for any other operation (or even supports that same mechanism for any other operation).  For example, even if a token is able to create RSA digital signatures with the CKM_RSA_PKCS mechanism, it may or may not be the case that the same token can also perform RSA encryption with CKM_RSA_PKCS.

Each mechanism description is be preceded by a table, of the following format, mapping mechanisms to API functions.

 

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

 

 

 

 

 

 

 

 

1 SR = SignRecover, VR = VerifyRecover.

2 Single-part operations only.

3 Mechanism can only be used for wrapping, not unwrapping.

The remainder of this section will present in detail the mechanisms supported by Cryptoki and the parameters which are supplied to them.

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 meaning for that particular mechanism.

2.1 RSA

Table 1, Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

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

 

ü

 

 

 

 

 

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

 

 

 

 

ü

 

2.1.1 Definitions

This section defines the RSA key type “CKK_RSA” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of RSA key objects.

Mechanisms:

CKM_RSA_PKCS_KEY_PAIR_GEN     

CKM_RSA_PKCS                  

CKM_RSA_9796                  

CKM_RSA_X_509                 

CKM_MD2_RSA_PKCS              

CKM_MD5_RSA_PKCS              

CKM_SHA1_RSA_PKCS             

CKM_SHA224_RSA_PKCS       

CKM_SHA256_RSA_PKCS           

CKM_SHA384_RSA_PKCS           

CKM_SHA512_RSA_PKCS           

CKM_RIPEMD128_RSA_PKCS        

CKM_RIPEMD160_RSA_PKCS        

CKM_RSA_PKCS_OAEP             

CKM_RSA_X9_31_KEY_PAIR_GEN    

CKM_RSA_X9_31                 

CKM_SHA1_RSA_X9_31            

CKM_RSA_PKCS_PSS              

CKM_SHA1_RSA_PKCS_PSS         

CKM_SHA224_RSA_PKCS_PSS       

CKM_SHA256_RSA_PKCS_PSS       

CKM_SHA512_RSA_PKCS_PSS       

CKM_SHA384_RSA_PKCS_PSS

CKM_RSA_PKCS_TPM_1_1     

CKM_RSA_PKCS_OAEP_TPM_1_1

CKM_RSA_AES_KEY_WRAP­­­­

 

2.1.2 RSA public key objects

RSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_RSA) hold RSA public keys.  The following table defines the RSA public key object attributes, in addition to the common attributes defined for this object class:

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

- Refer to [PKCS #11-Base] table 10 for footnotes

Depending on the token, there may be limits on the length of key components. See PKCS #1 for more information on RSA keys. 

The following is a sample template for creating an RSA public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;

CK_KEY_TYPE keyType = CKK_RSA;

CK_UTF8CHAR label[] = “An RSA public key object”;

CK_BYTE modulus[] = {...};

CK_BYTE exponent[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

   {CKA_CLASS, &class, sizeof(class)},

   {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

   {CKA_TOKEN, &true, sizeof(true)},

   {CKA_LABEL, label, sizeof(label)-1},

   {CKA_WRAP, &true, sizeof(true)},

   {CKA_ENCRYPT, &true, sizeof(true)},

   {CKA_MODULUS, modulus, sizeof(modulus)},

   {CKA_PUBLIC_EXPONENT, exponent, sizeof(exponent)}

};

2.1.3 RSA private key objects

RSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_RSA) hold RSA private keys.  The following table defines the RSA private key object attributes, in addition to the common attributes defined for this object class:

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 

- Refer to [PKCS #11-Base]  table 10 for footnotes

Depending on the token, there may be limits on the length of the key components.  See PKCS #1 for more information on RSA keys.

Tokens vary in what they actually store for RSA private keys.  Some tokens store all of the above attributes, which can assist in performing rapid RSA computations.  Other tokens might store only the CKA_MODULUS and CKA_PRIVATE_EXPONENT values.  Effective with version 2.40, tokens MUST also store CKA_PUBLIC_EXPONENT.  This permits the retrieval of sufficient data to reconstitute the associated public key.

Because of this, Cryptoki is flexible in dealing with RSA private key objects.  When a token generates an RSA private key, it stores whichever of the fields in Table 3 it keeps track of.  Later, if an application asks for the values of the key’s various attributes, Cryptoki supplies values only for attributes whose values it can obtain (i.e., if Cryptoki is asked for the value of an attribute it cannot obtain, the request fails).  Note that a Cryptoki implementation may or may not be able and/or willing to supply various attributes of RSA private keys which are not actually stored on the token.  E.g., if a particular token stores values only for the CKA_PRIVATE_EXPONENT, CKA_PRIME_1, and CKA_PRIME_2 attributes, then Cryptoki is certainly able to report values for all the attributes above (since they can all be computed efficiently from these three values).  However, a Cryptoki implementation may or may not actually do this extra computation.  The only attributes from Table 3 for which a Cryptoki implementation is required to be able to return values are CKA_MODULUS and CKA_PRIVATE_EXPONENT.

If an RSA private key object is created on a token, and more attributes from Table 3 are supplied to the object creation call than are supported by the token, the extra attributes are likely to be thrown away.  If an attempt is made to create an RSA private key object on a token with insufficient attributes for that particular token, then the object creation call fails and returns CKR_TEMPLATE_INCOMPLETE.

Note that when generating an RSA private key, there is no CKA_MODULUS_BITS attribute specified.  This is because RSA private keys are only generated as part of an RSA key pair, and the CKA_MODULUS_BITS attribute for the pair is specified in the template for the RSA public key.

The following is a sample template for creating an RSA private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;

CK_KEY_TYPE keyType = CKK_RSA;

CK_UTF8CHAR label[] = “An RSA private key object”;

CK_BYTE subject[] = {...};

CK_BYTE id[] = {123};

CK_BYTE modulus[] = {...};

CK_BYTE publicExponent[] = {...};

CK_BYTE privateExponent[] = {...};

CK_BYTE prime1[] = {...};

CK_BYTE prime2[] = {...};

CK_BYTE exponent1[] = {...};

CK_BYTE exponent2[] = {...};

CK_BYTE coefficient[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_SUBJECT, subject, sizeof(subject)},

  {CKA_ID, id, sizeof(id)},

  {CKA_SENSITIVE, &true, sizeof(true)},

  {CKA_DECRYPT, &true, sizeof(true)},

  {CKA_SIGN, &true, sizeof(true)},

  {CKA_MODULUS, modulus, sizeof(modulus)},

  {CKA_PUBLIC_EXPONENT, publicExponent, sizeof(publicExponent)},

  {CKA_PRIVATE_EXPONENT, privateExponent, sizeof(privateExponent)},

  {CKA_PRIME_1, prime1, sizeof(prime1)},

  {CKA_PRIME_2, prime2, sizeof(prime2)},

  {CKA_EXPONENT_1, exponent1, sizeof(exponent1)},

  {CKA_EXPONENT_2, exponent2, sizeof(exponent2)},

  {CKA_COEFFICIENT, coefficient, sizeof(coefficient)}

};

2.1.4 PKCS #1 RSA key pair generation

The PKCS #1 RSA key pair generation mechanism, denoted CKM_RSA_PKCS_KEY_PAIR_GEN, is a key pair generation mechanism based on the RSA public-key cryptosystem, as defined in PKCS #1.

It does not have a parameter.

The mechanism generates RSA public/private key pairs with a particular modulus length in bits and public exponent, as specified in the CKA_MODULUS_BITS and CKA_PUBLIC_EXPONENT attributes of the template for the public key. The  CKA_PUBLIC_EXPONENT  may  be  omitted  in which case the mechanism  shall  supply  the  public  exponent attribute using the default value  of  0x10001 (65537). Specific implementations may use a random value or an alternative default if 0x10001 cannot be used by the token.

Note:  Implementations  strictly  compliant  with  version  2.11  or prior versions  may  generate  an  error  if  this  attribute is omitted from the template.  Experience has shown that many implementations of 2.11 and prior did  allow  the  CKA_PUBLIC_EXPONENT  attribute  to  be  omitted  from the template, and behaved as described above. The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_MODULUS, and CKA_PUBLIC_EXPONENT attributes to the new public key.  CKA_PUBLIC_EXPONENT will  be  copied  from  the template if supplied. CKR_TEMPLATE_INCONSISTENT shall  be  returned  if the implementation cannot use the supplied exponent value. It contributes the CKA_CLASS and CKA_KEY_TYPE attributes to the new private key; it may also contribute some of the following attributes to the new private key: CKA_MODULUS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT_2, CKA_COEFFICIENT.  Other attributes supported by the RSA public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.5 X9.31 RSA key pair generation

The X9.31 RSA key pair generation mechanism, denoted CKM_RSA_X9_31_KEY_PAIR_GEN, is a key pair generation mechanism based on the RSA public-key cryptosystem, as defined in X9.31.

It does not have a parameter.

The mechanism generates RSA public/private key pairs with a particular modulus length in bits and public exponent, as specified in the CKA_MODULUS_BITS and CKA_PUBLIC_EXPONENT attributes of the template for the public key.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_MODULUS, and CKA_PUBLIC_EXPONENT attributes to the new public key.  It contributes the CKA_CLASS and CKA_KEY_TYPE attributes to the new private key; it may also contribute some of the following attributes to the new private key: CKA_MODULUS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT_2, CKA_COEFFICIENT.  Other attributes supported by the RSA public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, or else are assigned default initial values. Unlike the CKM_RSA_PKCS_KEY_PAIR_GEN mechanism, this mechanism is guaranteed to generate p and q values, CKA_PRIME_1 and CKA_PRIME_2 respectively, that meet the strong primes requirement of X9.31.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.6 PKCS #1 v1.5 RSA

The PKCS #1 v1.5 RSA mechanism, denoted CKM_RSA_PKCS, is a multi-purpose mechanism based on the RSA public-key cryptosystem and the block formats initially defined in PKCS #1 v1.5.  It supports single-part encryption and decryption; single-part signatures and verification with and without message recovery; key wrapping; and key unwrapping.  This mechanism corresponds only to the part of PKCS #1 v1.5 that involves RSA; it does not compute a message digest or a DigestInfo encoding as specified for the md2withRSAEncryption and md5withRSAEncryption algorithms in PKCS #1 v1.5 .

This mechanism does not have a parameter.

This mechanism can wrap and unwrap any secret key of appropriate length.  Of course, a particular token may not be able to wrap/unwrap every appropriate-length secret key that it supports.  For wrapping, the “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping.  The mechanism does not wrap the key type or any other information about the key, except the key length; the application must convey these separately.  In particular, the mechanism contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes to the recovered key during unwrapping; other attributes must be specified in the template.

Constraints on key types and the length of the data are summarized in the following table.  For encryption, decryption, signatures and signature verification, the input and output data may begin at the same location in memory.  In the table, k is the length in bytes of the RSA modulus.

Table 4, PKCS #1 v1.5 RSA: Key And Data Length

Function

Key type

Input length

Output length

Comments

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

1 Single-part operations only.

2 Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.7 PKCS #1 RSA OAEP mechanism parameters

¨      CK_RSA_PKCS_MGF_TYPE; CK_RSA_PKCS_MGF_TYPE_PTR

CK_RSA_PKCS_MGF_TYPE  is used to indicate the Message Generation Function (MGF) applied to a message block when formatting a message block for the PKCS #1 OAEP encryption scheme or the PKCS #1 PSS signature scheme. It is defined as follows:

typedef CK_ULONG CK_RSA_PKCS_MGF_TYPE;

 

The following MGFs are defined in PKCS #1. The following table lists the defined functions.

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

CK_RSA_PKCS_MGF_TYPE_PTR is a pointer to a CK_RSA_PKCS_ MGF_TYPE.

¨      CK_RSA_PKCS_OAEP_SOURCE_TYPE; CK_RSA_PKCS_OAEP_SOURCE_TYPE_PTR

CK_RSA_PKCS_OAEP_SOURCE_TYPE  is used to indicate the source of the encoding parameter when formatting a message block for the PKCS #1 OAEP encryption scheme. It is defined as follows:

typedef CK_ULONG CK_RSA_PKCS_OAEP_SOURCE_TYPE;

 

The following encoding parameter sources are defined in PKCS #1. The following table lists the defined sources along with the corresponding data type for the pSourceData field in the CK_RSA_PKCS_OAEP_PARAMS structure defined below.

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.

CK_RSA_PKCS_OAEP_SOURCE_TYPE_PTR is a pointer to a CK_RSA_PKCS_OAEP_SOURCE_TYPE.

¨      CK_RSA_PKCS_OAEP_PARAMS; CK_RSA_PKCS_OAEP_PARAMS_PTR

CK_RSA_PKCS_OAEP_PARAMS is a structure that provides the parameters to the CKM_RSA_PKCS_OAEP mechanism.  The structure is defined as follows:

typedef struct CK_RSA_PKCS_OAEP_PARAMS {

   CK_MECHANISM_TYPE hashAlg;

   CK_RSA_PKCS_MGF_TYPE mgf;

   CK_RSA_PKCS_OAEP_SOURCE_TYPE source;

   CK_VOID_PTR pSourceData;

   CK_ULONG ulSourceDataLen;

} CK_RSA_PKCS_OAEP_PARAMS;

 

The fields of the structure have the following meanings:

                                    hashAlg       mechanism ID of the message digest algorithm used to calculate the digest of the encoding parameter

                                           mgf       mask generation function to use on the encoded block

                                      source       source of the encoding parameter

                             pSourceData       data used as the input for the encoding parameter source

                       ulSourceDataLen       length of the encoding parameter source input

CK_RSA_PKCS_OAEP_PARAMS_PTR is a pointer to a CK_RSA_PKCS_OAEP_PARAMS.

2.1.8 PKCS #1 RSA OAEP

The PKCS #1 RSA OAEP mechanism, denoted CKM_RSA_PKCS_OAEP, is a multi-purpose mechanism based on the RSA public-key cryptosystem and the OAEP block format defined in PKCS #1.  It supports single-part encryption and decryption; key wrapping; and key unwrapping.

It has a parameter, a CK_RSA_PKCS_OAEP_PARAMS structure.

This mechanism can wrap and unwrap any secret key of appropriate length.  Of course, a particular token may not be able to wrap/unwrap every appropriate-length secret key that it supports.  For wrapping, the “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping.  The mechanism does not wrap the key type or any other information about the key, except the key length; the application must convey these separately.  In particular, the mechanism contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes to the recovered key during unwrapping; other attributes must be specified in the template.

Constraints on key types and the length of the data are summarized in the following table.  For encryption and decryption, the input and output data may begin at the same location in memory.  In the table, k is the length in bytes of the RSA modulus, and hLen is the output length of the message digest algorithm specified by the hashAlg field of the CK_RSA_PKCS_OAEP_PARAMS structure.

Table 7, 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

1 Single-part operations only.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.9 PKCS #1 RSA PSS mechanism parameters

¨      CK_RSA_PKCS_PSS_PARAMS; CK_RSA_PKCS_PSS_PARAMS_PTR

CK_RSA_PKCS_PSS_PARAMS is a structure that provides the parameters to the CKM_RSA_PKCS_PSS mechanism.  The structure is defined as follows:

typedef struct CK_RSA_PKCS_PSS_PARAMS {

   CK_MECHANISM_TYPE hashAlg;

   CK_RSA_PKCS_MGF_TYPE mgf;

   CK_ULONG sLen;

} CK_RSA_PKCS_PSS_PARAMS;

 

The fields of the structure have the following meanings:

                                    hashAlg       hash algorithm used in the PSS encoding; if the signature mechanism does not include message hashing, then this value must be the mechanism used by the application to generate the message hash; if the signature mechanism includes hashing, then this value must match the hash algorithm indicated by the signature mechanism

                                           mgf       mask generation function to use on the encoded block

                                         sLen       length, in bytes, of the salt value used in the PSS encoding; typical values are the length of the message hash and zero

CK_RSA_PKCS_PSS_PARAMS_PTR is a pointer to a CK_RSA_PKCS_PSS_PARAMS.

2.1.10 PKCS #1 RSA PSS

The PKCS #1 RSA PSS mechanism, denoted CKM_RSA_PKCS_PSS, is a mechanism based on the RSA public-key cryptosystem and the PSS block format defined in PKCS #1.  It supports single-part signature generation and verification without message recovery. This mechanism corresponds only to the part of PKCS #1 that involves block formatting and RSA, given a hash value; it does not compute a hash value on the message to be signed.

It has a parameter, a CK_RSA_PKCS_PSS_PARAMS structure. The sLen field must be less than or 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 in bytes of the RSA modulus, except if the length in bits of the RSA modulus is one more than a multiple of 8, in which case k* is one less than the length in bytes of the RSA modulus.

Constraints on key types and the length of the data are summarized in the following table.  In the table, k is the length in bytes of the RSA.

Table 8, 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

1 Single-part operations only.

2 Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.11 ISO/IEC 9796 RSA

The ISO/IEC 9796 RSA mechanism, denoted CKM_RSA_9796, is a mechanism for single-part signatures and verification with and without message recovery based on the RSA public-key cryptosystem and the block formats defined in ISO/IEC 9796 and its annex A.

This mechanism processes only byte strings, whereas ISO/IEC 9796 operates on bit strings.  Accordingly, the following transformations are performed:

·         Data is converted between byte and bit string formats by interpreting the most-significant bit of the leading byte of the byte string as the leftmost bit of the bit string, and the least-significant bit of the trailing byte of the byte string as the rightmost bit of the bit string (this assumes the length in bits of the data is a multiple of 8).

·         A signature is converted from a bit string to a byte string by padding the bit string on the left with 0 to 7 zero bits so that the resulting length in bits is a multiple of 8, and converting the resulting bit string as above; it is converted from a byte string to a bit string by converting the byte string as above, and removing bits from the left so that the resulting length in bits is the same as that of the RSA modulus.

This mechanism does not have a parameter.

Constraints on key types and the length of input and output data are summarized in the following table.  In the table, k is the length in bytes of the RSA modulus.

Table 9, ISO/IEC 9796 RSA: Key And Data Length

Function

Key type

Input length

Output 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û

1 Single-part operations only.

2 Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.12 X.509 (raw) RSA

The X.509 (raw) RSA mechanism, denoted CKM_RSA_X_509, is a multi-purpose mechanism based on the RSA public-key cryptosystem. It supports single-part encryption and decryption; single-part signatures and verification with and without message recovery; key wrapping; and key unwrapping.  All these operations are based on so-called “raw” RSA, as assumed in X.509.

“Raw” RSA as defined here encrypts a byte string by converting it to an integer, most-significant byte first, applying “raw” RSA exponentiation, and converting the result to a byte string, most-significant byte first.  The input string, considered as an integer, must be less than the modulus; the output string is also less than the modulus.

This mechanism does not have a parameter.

This mechanism can wrap and unwrap any secret key of appropriate length.  Of course, a particular token may not be able to wrap/unwrap every appropriate-length secret key that it supports.  For wrapping, the “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping.  The mechanism does not wrap the key type, key length, or any other information about the key; the application must convey these separately, and supply them when unwrapping the key.

Unfortunately, X.509 does not specify how to perform padding for RSA encryption.  For this mechanism, padding should be performed by prepending plaintext data with 0-valued bytes.  In effect, to encrypt the sequence of plaintext bytes b1 b2 … bn (n £ k), Cryptoki forms P=2n-1b1+2n-2b2+…+bn.  This number must be less than the RSA modulus.  The k-byte ciphertext (k is the length in bytes of the RSA modulus) is produced by raising P to the RSA public exponent modulo the RSA modulus.  Decryption of a k-byte ciphertext C is accomplished by raising C to the RSA private exponent modulo the RSA modulus, and returning the resulting value as a sequence of exactly k bytes.  If the resulting plaintext is to be used to produce an unwrapped key, then however many bytes are specified in the template for the length of the key are taken from the end of this sequence of bytes.

Technically, the above procedures may differ very slightly from certain details of what is specified in X.509.

Executing cryptographic operations using this mechanism can result in the error returns CKR_DATA_INVALID (if plaintext is supplied which has the same length as the RSA modulus and is numerically at least as large as the modulus) and CKR_ENCRYPTED_DATA_INVALID (if ciphertext is supplied which has the same length as the RSA modulus and is numerically at least as large as the modulus).

Constraints on key types and the length of input and output data are summarized in the following table.  In the table, k is the length in bytes of the RSA modulus.

Table 10, X.509 (Raw) RSA: Key And Data Length

Function

Key type

Input length

Output 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)

1 Single-part operations only.

2 Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

This mechanism is intended for compatibility with applications that do not follow the PKCS #1 or ISO/IEC 9796 block formats.

2.1.13 ANSI X9.31 RSA

The ANSI X9.31 RSA mechanism, denoted CKM_RSA_X9_31, is a mechanism for single-part signatures and verification without message recovery based on the RSA public-key cryptosystem and the block formats defined in ANSI X9.31.

This mechanism applies the header and padding fields of the hash encapsulation. The trailer field must be applied by the application.

This mechanism processes only byte strings, whereas ANSI X9.31 operates on bit strings.  Accordingly, the following transformations are performed:

·         Data is converted between byte and bit string formats by interpreting the most-significant bit of the leading byte of the byte string as the leftmost bit of the bit string, and the least-significant bit of the trailing byte of the byte string as the rightmost bit of the bit string (this assumes the length in bits of the data is a multiple of 8).

·         A signature is converted from a bit string to a byte string by padding the bit string on the left with 0 to 7 zero bits so that the resulting length in bits is a multiple of 8, and converting the resulting bit string as above; it is converted from a byte string to a bit string by converting the byte string as above, and removing bits from the left so that the resulting length in bits is the same as that of the RSA modulus.

This mechanism does not have a parameter.

Constraints on key types and the length of input and output data are summarized in the following table.  In the table, k is the length in bytes of the RSA modulus. For all operations, the k value must be at least 128 and a multiple of 32 as specified in ANSI X9.31.

Table 11, ANSI X9.31 RSA: Key And Data Length

Function

Key type

Input length

Output length

C_Sign1

RSA private key

£ k-2

k

C_Verify1

RSA public key

£ k-2, k2

N/A

1 Single-part operations only.

2 Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.14 PKCS #1 v1.5 RSA signature with MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512, RIPE-MD 128 or RIPE-MD 160

The PKCS #1 v1.5 RSA signature with MD2 mechanism, denoted CKM_MD2_RSA_PKCS, performs single- and multiple-part digital signatures and verification operations without message recovery.  The operations performed are as described initially in PKCS #1 v1.5 with the object identifier md2WithRSAEncryption, and as in the scheme RSASSA-PKCS1-v1_5 in the current version of PKCS #1, where the underlying hash function is MD2.

Similarly, the PKCS #1 v1.5 RSA signature with MD5 mechanism, denoted CKM_MD5_RSA_PKCS, performs the same operations described in PKCS #1 with the object identifier md5WithRSAEncryption.  The PKCS #1 v1.5 RSA signature with SHA-1 mechanism, denoted CKM_SHA1_RSA_PKCS, performs the same operations, except that it uses the hash function SHA-1 with object identifier sha1WithRSAEncryption.

Likewise, the PKCS #1 v1.5 RSA signature with SHA-256, SHA-384, and SHA-512 mechanisms, denoted CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, and CKM_SHA512_RSA_PKCS respectively, perform the same operations using the SHA-256, SHA-384 and SHA-512 hash functions with the object identifiers sha256WithRSAEncryption, sha384WithRSAEncryption and sha512WithRSAEncryption respectively.

The PKCS #1 v1.5 RSA signature with RIPEMD-128 or RIPEMD-160, denoted CKM_RIPEMD128_RSA_PKCS and CKM_RIPEMD160_RSA_PKCS respectively, perform the same operations using the RIPE-MD 128 and RIPE-MD 160 hash functions.

None of these mechanisms has a parameter.

Constraints on key types and the length of the data for these mechanisms are summarized in the following table.  In the table, k is the length in bytes of the RSA modulus.  For the PKCS #1 v1.5 RSA signature with MD2 and PKCS #1 v1.5 RSA signature with MD5 mechanisms, k must be at least 27; for the PKCS #1 v1.5 RSA signature with SHA-1 mechanism, k must be at least 31, and so on for other underlying hash functions, where the minimum is always 11 bytes more than the length of the hash value.

Table 12, 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

2 Data length, signature length.

For these mechanisms, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.15 PKCS #1 v1.5 RSA signature with SHA-224

The PKCS #1 v1.5 RSA signature with SHA-224 mechanism, denoted CKM_SHA224_RSA_PKCS, performs similarly as the other CKM_SHAX_RSA_PKCS mechanisms but uses the SHA-224 hash function.

2.1.16 PKCS #1 RSA PSS signature with SHA-224

The PKCS #1 RSA PSS signature with SHA-224 mechanism, denoted CKM_SHA224_RSA_PKCS_PSS, performs similarly as the other CKM_SHAX_RSA_PSS mechanisms but uses the SHA-224 hash function.

2.1.17 PKCS #1 RSA PSS signature with SHA-1, SHA-256, SHA-384 or SHA-512

The PKCS #1 RSA PSS signature with SHA-1 mechanism, denoted CKM_SHA1_RSA_PKCS_PSS, performs single- and multiple-part digital signatures and verification operations without message recovery.  The operations performed are as described in PKCS #1 with the object identifier id-RSASSA-PSS, i.e., as in the scheme RSASSA-PSS in PKCS #1 where the underlying hash function is SHA-1.

The PKCS #1 RSA PSS signature with SHA-256, SHA-384, and SHA-512 mechanisms, denoted CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, and CKM_SHA512_RSA_PKCS_PSS respectively, perform the same operations using the SHA-256, SHA-384 and SHA-512 hash functions.

The mechanisms have a parameter, a CK_RSA_PKCS_PSS_PARAMS structure. The sLen field must 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 bytes of the RSA modulus, except if the length in bits of the RSA modulus is one more than a multiple of 8, in which case k* is one less than the length in bytes of the RSA modulus.

Constraints on key types and the length of the data are summarized in the following table.  In the table, k is the length in bytes of the RSA modulus.

Table 13, 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

2 Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.18 ANSI X9.31 RSA signature with SHA-1

The ANSI X9.31 RSA signature with SHA-1 mechanism, denoted CKM_SHA1_RSA_X9_31, performs single- and multiple-part digital signatures and verification operations without message recovery.  The operations performed are as described in ANSI X9.31.

This mechanism does not have a parameter.

Constraints on key types and the length of the data for these mechanisms are summarized in the following table.  In the table, k is the length in bytes of the RSA modulus. For all operations, the k value must be at least 128 and a multiple of 32 as specified in ANSI X9.31.

Table 14, 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

2 Data length, signature length.

For these mechanisms, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.19 TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA

The TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA mechanism, denoted CKM_RSA_PKCS_TPM_1_1, is a multi-use mechanism based on the RSA public-key cryptosystem and the block formats initially defined in PKCS #1 v1.5, with additional formatting rules defined in TCPA TPM Specification Version 1.1b.  Additional formatting rules remained the same in TCG TPM Specification 1.2  The mechanism supports single-part encryption and decryption; key wrapping; and key unwrapping. 

This mechanism does not have a parameter. It differs from the standard PKCS#1 v1.5 RSA encryption mechanism in that the plaintext is wrapped in a TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1.2) structure before being submitted to the PKCS#1 v1.5 encryption process. On encryption, the version field of the TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1.2) structure must contain 0x01, 0x01, 0x00, 0x00. On decryption, any structure of the form 0x01, 0x01, 0xXX, 0xYY may be accepted.

This mechanism can wrap and unwrap any secret key of appropriate length.  Of course, a particular token may not be able to wrap/unwrap every appropriate-length secret key that it supports.  For wrapping, the “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping.  The mechanism does not wrap the key type or any other information about the key, except the key length; the application must convey these separately.  In particular, the mechanism contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes to the recovered key during unwrapping; other attributes must be specified in the template.

Constraints on key types and the length of the data are summarized in the following table.  For encryption and decryption, the input and output data may begin at the same location in memory.  In the table, k is the length in bytes of the RSA modulus.

Table 15, TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA: Key And Data Length

Function

Key type

Input length

Output 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

1 Single-part operations only.

 

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.20 TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP

The TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP mechanism, denoted CKM_RSA_PKCS_OAEP_TPM_1_1, is a multi-purpose mechanism based on the RSA public-key cryptosystem and the OAEP block format defined in PKCS #1, with additional formatting defined in TCPA TPM Specification Version 1.1b.  Additional formatting rules remained the same in TCG TPM Specification 1.2.  The mechanism supports single-part encryption and decryption; key wrapping; and key unwrapping. 

This mechanism does not have a parameter. It differs from the standard PKCS#1 OAEP RSA encryption mechanism in that the plaintext is wrapped in a TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1.2) structure before being submitted to the encryption process and that all of the values of the parameters that are passed to a standard CKM_RSA_PKCS_OAEP operation are fixed. On encryption, the version field of the TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1.2) structure must contain 0x01, 0x01, 0x00, 0x00. On decryption, any structure of the form 0x01, 0x01, 0xXX, 0xYY may be accepted.

This mechanism can wrap and unwrap any secret key of appropriate length.  Of course, a particular token may not be able to wrap/unwrap every appropriate-length secret key that it supports.  For wrapping, the “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping.  The mechanism does not wrap the key type or any other information about the key, except the key length; the application must convey these separately.  In particular, the mechanism contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes to the recovered key during unwrapping; other attributes must be specified in the template.

Constraints on key types and the length of the data are summarized in the following table.  For encryption and decryption, the input and output data may begin at the same location in memory.  In the table, k is the length in bytes of the RSA modulus.

Table 16, 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

1 Single-part operations only.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

2.1.21 RSA AES KEY WRAP

 

The RSA AES key wrap mechanism, denoted CKM_RSA_AES_KEY_WRAP , is a mechanism based on the RSA public-key cryptosystem and the AES key wrap mechanism.  It supports single-part key wrapping; and key unwrapping.

It has a parameter, a CK_RSA_AES_KEY_WRAP_PARAMS structure.

The mechanism can wrap and unwrap a target asymmetric key of any length and type using an RSA key.

-          A temporary AES key is used for wrapping the target key using CKM_AES_KEY_WRAP_PAD mechanism.

-          The temporary AES key is wrapped with the wrapping RSA key using CKM_RSA_PKCS_OAEP mechanism.

 

For wrapping, the mechanism -                

 

The recommended format for an asymmetric target key being wrapped is as a PKCS8 PrivateKeyInfo

 

The use of Attributes in the PrivateKeyInfo structure  is OPTIONAL.  In case of conflicts between the object attribute template, and Attributes in the PrivateKeyInfo structure, an error  should be thrown

 

For unwrapping, the mechanism -

Table 17, CKM_RSA_AES_KEY_WRAP Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

 CKM_RSA_AES_KEY_WRAP

 

 

 

 

 

ü

 

1SR = SignRecover, VR = VerifyRecover

2.1.22 RSA AES KEY WRAP mechanism parameters

¨       CK_RSA_AES_KEY_WRAP_PARAMS; CK_RSA_AES_KEY_WRAP_PARAMS_PTR

CK_RSA_AES_KEY_WRAP_PARAMS is a structure that provides the parameters to the CKM_RSA_AES_KEY_WRAP mechanism.  It is defined as follows:

 

typedef struct CK_RSA_AES_KEY_WRAP_PARAMS {

  CK_ULONG                                        ulAESKeyBits;

  CK_RSA_PKCS_OAEP_PARAMS_PTR     pOAEPParams;

} CK_RSA_AES_KEY_WRAP_PARAMS;

The fields of the structure have the following meanings:

           ulAESKeyBits       length of the temporary AES key in bits. Can be only 128, 192 or 256.

           pOAEPParams     pointer to the parameters of the temporary AES key wrapping. See also the description of PKCS #1 RSA OAEP mechanism parameters.

CK_RSA_AES_KEY_WRAP_PARAMS_PTR  is a pointer to a CK_RSA_AES_KEY_WRAP_PARAMS.

2.1.23 FIPS 186-4

When CKM_RSA_PKCS is operated in FIPS mode, the length of the modulus SHALL only be 1024, 2048, or 3072 bits.

2.2 DSA

Table 18, DSA Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

CKM_DSA_KEY_PAIR_GEN

 

 

 

 

ü

 

 

CKM_DSA_PARAMETER_GEN

 

 

 

 

ü

 

 

CKM_DSA_PROBABALISTIC_PARAMETER_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

 

ü

 

 

 

 

 

2.2.1 Definitions

This section defines the key type “CKK_DSA” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of DSA key objects.

Mechanisms:

CKM_DSA_KEY_PAIR_GEN

CKM_DSA

CKM_DSA_SHA1

CKM_DSA_SHA224

CKM_DSA_SHA256

CKM_DSA_SHA384

CKM_DSA_SHA512

CKM_DSA_PARAMETER_GEN

CKM_DSA_PROBABLISTIC_PARAMETER_GEN

CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN

CKM_DSA_FIPS_G_GEN

 

·              CK_DSA_PARAMETER_GEN_PARAM

 

CK_DSA_PARAMETER_GEN_PARAM is a structure which provides and returns parameters for the NIST FIPS 186-4 parameter generating algorithms.

 

typedef struct CK_DSA_PARAMETER_GEN_PARAM {

CK_MECHANISM_TYPE hash;

CK_BYTE_PTR            pSeed;

CK_ULONG                  ulSeedLen;

CK_ULONG                  ulIndex;

};

 

The fields of the structure have the following meanings:

hash       Mechanism value for the base hash used in PQG generation, Valid values are CKM_SHA1, CKM_SHA224, CKM_SHA256, CKM_SHA384, CKM_SHA512.

pSeed      Seed value used to generate PQ and G. This value is returned by CKM_DSA_PROBABLISTIC_PARAMETER_GEN, CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN, and passed into CKM_DSA_FIPS_G_GEN.

                ulSeedLen     Length of seed value.

                     ulIndex     Index value for generating G. Input for CKM_DSA_FIPS_G_GEN. Ignored by CKM_DSA_PROBABALISTIC_PARAMETER_GEN and CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN.

2.2.2 DSA public key objects

DSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_DSA) hold DSA public keys.  The following table defines the DSA public key object attributes, in addition to the common attributes defined for this object class:

Table 19, 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

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA domain parameters”.  See FIPS PUB 186-4 for more information on DSA keys.

The following is a sample template for creating a DSA public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;

CK_KEY_TYPE keyType = CKK_DSA;

CK_UTF8CHAR label[] = “A DSA public key object”;

CK_BYTE prime[] = {...};

CK_BYTE subprime[] = {...};

CK_BYTE base[] = {...};

CK_BYTE value[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_PRIME, prime, sizeof(prime)},

  {CKA_SUBPRIME, subprime, sizeof(subprime)},

  {CKA_BASE, base, sizeof(base)},

  {CKA_VALUE, value, sizeof(value)}

};

 

2.2.3 DSA Key Restrictions

FIPS PUB 186-4 specifies permitted combinations of prime and sub-prime lengths.  They are:

Earlier versions of FIPS 186 permitted smaller prime lengths, and those are included here for backwards compatibility.       An implementation that is compliant to FIPS 186-4 does not permit the use of primes of any length less than 1024 bits.

2.2.4 DSA private key objects

DSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_DSA) hold DSA private keys.  The following table defines the DSA private key object attributes, in addition to the common attributes defined for this object class:

Table 20, 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

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA domain parameters”.  See FIPS PUB 186-4 for more information on DSA keys.

Note that when generating a DSA private key, the DSA domain parameters are not specified in the key’s template.  This is because DSA private keys are only generated as part of a DSA key pair, and the DSA domain parameters for the pair are specified in the template for the DSA public key.

The following is a sample template for creating a DSA private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;

CK_KEY_TYPE keyType = CKK_DSA;

CK_UTF8CHAR label[] = “A DSA private key object”;

CK_BYTE subject[] = {...};

CK_BYTE id[] = {123};

CK_BYTE prime[] = {...};

CK_BYTE subprime[] = {...};

CK_BYTE base[] = {...};

CK_BYTE value[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_SUBJECT, subject, sizeof(subject)},

  {CKA_ID, id, sizeof(id)},

  {CKA_SENSITIVE, &true, sizeof(true)},

  {CKA_SIGN, &true, sizeof(true)},

  {CKA_PRIME, prime, sizeof(prime)},

  {CKA_SUBPRIME, subprime, sizeof(subprime)},

  {CKA_BASE, base, sizeof(base)},

  {CKA_VALUE, value, sizeof(value)}

};

2.2.5 DSA domain parameter objects

DSA domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type CKK_DSA) hold DSA domain parameters.  The following table defines the DSA domain parameter object attributes, in addition to the common attributes defined for this object class:

Table 21, 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.

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA domain parameters”.  See FIPS PUB 186-4 for more information on DSA domain parameters.

To ensure backwards compatibility, if CKA_SUBPRIME_BITS is not specified for a call to C_GenerateKey, it takes on a default based on the value of CKA_PRIME_BITS as follows:

 

The following is a sample template for creating a DSA domain parameter object:

CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS;

CK_KEY_TYPE keyType = CKK_DSA;

CK_UTF8CHAR label[] = “A DSA domain parameter object”;

CK_BYTE prime[] = {...};

CK_BYTE subprime[] = {...};

CK_BYTE base[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_PRIME, prime, sizeof(prime)},

  {CKA_SUBPRIME, subprime, sizeof(subprime)},

  {CKA_BASE, base, sizeof(base)},

};

2.2.6 DSA key pair generation

The DSA key pair generation mechanism, denoted CKM_DSA_KEY_PAIR_GEN, is a key pair generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 186-2.

This mechanism does not have a parameter.

The mechanism generates DSA public/private key pairs with a particular prime, subprime and base, as specified in the CKA_PRIME, CKA_SUBPRIME, and CKA_BASE attributes of the template for the public key.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_BASE, and CKA_VALUE attributes to the new private key. Other attributes supported by the DSA public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.

2.2.7 DSA domain parameter generation

The DSA domain parameter generation mechanism, denoted CKM_DSA_PARAMETER_GEN, is a domain parameter generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 186-2.

This mechanism does not have a parameter.

The mechanism generates DSA domain parameters with a particular prime length in bits, as specified in the CKA_PRIME_BITS attribute of the template.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_BASE and CKA_PRIME_BITS attributes to the new object. Other attributes supported by the DSA domain parameter types may also be specified in the template, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.

2.2.8 DSA probabilistic domain parameter generation

The DSA probabilistic domain parameter generation mechanism, denoted CKM_DSA_PROBABLISTIC_PARAMETER_GEN, is a domain parameter generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 186-4, section Appendix A.1.1 Generation and Validation of Probable Primes..

This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash and returns the seed (pSeed) and the length (ulSeedLen).

The mechanism generates DSA the prime and subprime domain parameters with a particular prime length in bits, as specified in the CKA_PRIME_BITS attribute of the template and the subprime length as specified in the CKA_SUBPRIME_BITS attribute of the template.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_PRIME_BITS, and CKA_SUBPRIME_BITS attributes to the new object. CKA_BASE is not set by this call. Other attributes supported by the DSA domain parameter types may also be specified in the template, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.

2.2.9 DSA Shawe-Taylor domain parameter generation

The DSA Shawe-Taylor domain parameter generation mechanism, denoted CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN, is a domain parameter generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 186-4, section Appendix A.1.2 Construction and Validation of Provable Primes p and q.

This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash and returns the seed (pSeed) and the length (ulSeedLen).

The mechanism generates DSA the prime and subprime domain parameters with a particular prime length in bits, as specified in the CKA_PRIME_BITS attribute of the template and the subprime length as specified in the CKA_SUBPRIME_BITS attribute of the template.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_PRIME_BITS, and CKA_SUBPRIME_BITS attributes to the new object. CKA_BASE is not set by this call. Other attributes supported by the DSA domain parameter types may also be specified in the template, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.

2.2.10 DSA base domain parameter generation

The DSA base domain parameter generation mechanism, denoted CKM_DSA_FIPS_G_GEN, is a base parameter generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 186-4, section Appendix A.2 Generation of Generator G.

This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash  the seed (pSeed) and the length (ulSeedLen) and the index value.

The mechanism generates the DSA base with the domain parameter specified in the CKA_PRIME and CKA_SUBPRIME attributes of the template.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_BASE attributes to the new object. Other attributes supported by the DSA domain parameter types may also be specified in the template, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.

2.2.11 DSA without hashing

The DSA without hashing mechanism, denoted CKM_DSA, is a mechanism for single-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-2. (This mechanism corresponds only to the part of DSA that processes the 20-byte hash value; it does not compute the hash value.)

For the purposes of this mechanism, a DSA signature is a 40-byte string, corresponding to the concatenation of the DSA values r and s, each represented most-significant byte first.

It does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 22, DSA: Key And Data Length

Function

Key type

Input length

Output length

C_Sign1

DSA private key

20, 28, 32, 48, or 64 bits

2*length of subprime

C_Verify1

DSA public key

(20, 28, 32, 48, or 64 bits), (2*length of subprime)2

N/A

1 Single-part operations only.

2 Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.

2.2.12 DSA with SHA-1

The DSA with SHA-1 mechanism, denoted CKM_DSA_SHA1, is a mechanism for single- and multiple-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-2.  This mechanism computes the entire DSA specification, including the hashing with SHA-1.

For the purposes of this mechanism, a DSA signature is a 40-byte string, corresponding to the concatenation of the DSA values r and s, each represented most-significant byte first.

This mechanism does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 23, 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, 2*subprime length2

N/A

2 Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.

2.2.13 FIPS 186-4

When CKM_DSA is operated in FIPS mode, only the following bit lengths of p and q, represented by L and N, SHALL be used:

L = 1024, N = 160

L = 2048, N = 224

L = 2048, N = 256

L = 3072, N = 256

 

2.2.14 DSA with SHA-224

The DSA with SHA-1 mechanism, denoted CKM_DSA_SHA224, is a mechanism for single- and multiple-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-4.  This mechanism computes the entire DSA specification, including the hashing with SHA-224.

For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented most-significant byte first.

This mechanism does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 24, 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, 2*subprime length2

N/A

2 Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.

2.2.15 DSA with SHA-256

The DSA with SHA-1 mechanism, denoted CKM_DSA_SHA256, is a mechanism for single- and multiple-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-4.  This mechanism computes the entire DSA specification, including the hashing with SHA-256.

For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented most-significant byte first.

This mechanism does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 25, 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, 2*subprime length2

N/A

2 Data length, signature length.

2.2.16 DSA with SHA-384

The DSA with SHA-1 mechanism, denoted CKM_DSA_SHA384, is a mechanism for single- and multiple-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-4.  This mechanism computes the entire DSA specification, including the hashing with SHA-384.

For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented most-significant byte first.

This mechanism does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 26, DSA with SHA-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, 2*subprime length2

N/A

2 Data length, signature length.

2.2.17 DSA with SHA-512

The DSA with SHA-1 mechanism, denoted CKM_DSA_SHA512, is a mechanism for single- and multiple-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186-4.  This mechanism computes the entire DSA specification, including the hashing with SHA-512.

For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented most-significant byte first.

This mechanism does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 27, 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, 2*subprime length2

N/A

2 Data length, signature length.

2.3 Elliptic Curve

The Elliptic Curve (EC) cryptosystem (also related to ECDSA) in this document is the one described in the ANSI X9.62 and X9.63 standards developed by the ANSI X9F1 working group.

 

Table 28, Elliptic Curve Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

CKM_EC_KEY_PAIR_GEN (CKM_ECDSA_KEY_PAIR_GEN)

 

 

 

 

ü

 

 

CKM_ECDSA

 

ü2

 

 

 

 

 

CKM_ECDSA_SHA1

 

ü

 

 

 

 

 

CKM_ECDH1_DERIVE

 

 

 

 

 

 

ü

CKM_ECDH1_COFACTOR_DERIVE

 

 

 

 

 

 

ü

CKM_ECMQV_DERIVE

 

 

 

 

 

 

ü

CKM_ECDH_AES_KEY_WRAP

 

 

 

 

 

ü

 

 

Table 29, 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_NAMEDCURVE

0x00800000UL

True if the mechanism can be used with EC domain parameters of the choice namedCurve

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

In these standards, there are two different varieties of EC defined:

1.     EC using a field with an odd prime number of elements (i.e. the finite field Fp).

2.     EC using a field of characteristic two (i.e. the finite field F2m).

An EC key in Cryptoki contains information about which variety of EC it is suited for.  It is preferable that a Cryptoki library, which can perform EC mechanisms, be capable of performing operations with the two varieties of EC, however this is not required.  The CK_MECHANISM_INFO structure CKF_EC_F_P flag identifies a Cryptoki library supporting EC keys over Fp whereas the CKF_EC_F_2M flag identifies a Cryptoki library supporting EC keys over F2m.  A Cryptoki library that can perform EC mechanisms must set either or both of these flags for each EC mechanism.

In these specifications there are also three representation methods to define the domain parameters for an EC key.  Only the ecParameters and the namedCurve choices are supported in Cryptoki.  The CK_MECHANISM_INFO structure CKF_EC_ECPARAMETERS flag identifies a Cryptoki library supporting the ecParameters choice whereas the CKF_EC_NAMEDCURVE flag identifies a Cryptoki library supporting the namedCurve choice.  A Cryptoki library that can perform EC mechanisms must set either or both of these flags for each EC mechanism.

In these specifications, an EC public key (i.e. EC point Q) or the base point G when the ecParameters choice is used can be represented as an octet string of the uncompressed form or the compressed form.  The CK_MECHANISM_INFO structure CKF_EC_UNCOMPRESS flag identifies a Cryptoki library supporting the uncompressed form whereas the CKF_EC_COMPRESS flag identifies a Cryptoki library supporting the compressed form.  A Cryptoki library that can perform EC mechanisms must set either or both of these flags for each EC mechanism.

Note that an implementation of a Cryptoki library supporting EC with only one variety, one representation of domain parameters or one form may encounter difficulties achieving interoperability with other implementations.

If an attempt to create, generate, derive or unwrap an EC key of an unsupported curve is made, the attempt should fail with the error code CKR_CURVE_NOT_SUPPORTED.  If an attempt to create, generate, derive, or unwrap an EC key with invalid or of an unsupported representation of domain parameters is made, that attempt should fail with the error code CKR_DOMAIN_PARAMS_INVALID.  If an attempt to create, generate, derive, or unwrap an EC key of an unsupported form is made, that attempt should fail with the error code CKR_TEMPLATE_INCONSISTENT.

2.3.1 EC Signatures

For the purposes of these mechanisms, an ECDSA signature is an octet string of even length which is at most two times nLen octets, where nLen is the length in octets of the base point order n. The signature octets correspond to the concatenation of the ECDSA values r and s, both represented as an octet string of equal length of at most nLen with the most significant byte first. If r and s have different octet length, the shorter of both must be padded with leading zero octets such that both have the same octet length. Loosely spoken, the first half of the signature is r and the second half is s. For signatures created by a token, the resulting signature is always of length 2nLen. For signatures passed to a token for verification, the signature may have a shorter length but must be composed as specified before.

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 length of n will be used. Any truncation is done by the token.

Note: For applications, it is recommended to encode the signature as an octet string of length two times nLen if possible. This ensures that the application works with PKCS#11 modules which have been implemented based on an older version of this document. Older versions required all signatures to have length two times nLen. It may be impossible to encode the signature with the maximum length of two times nLen if the application just gets the integer values of r and s (i.e. without leading zeros), but does not know the base point order n, because r and s can have any value between zero and the base point order n.

2.3.2 Definitions

This section defines the key type “CKK_ECDSA” and “CKK_EC” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.

Mechanisms:

Note: CKM_ECDSA_KEY_PAIR_GEN is deprecated in v2.11

CKM_ECDSA_KEY_PAIR_GEN        

CKM_EC_KEY_PAIR_GEN           

CKM_ECDSA                     

CKM_ECDSA_SHA1                 

CKM_ECDH1_DERIVE              

CKM_ECDH1_COFACTOR_DERIVE     

CKM_ECMQV_DERIVE

CKM_ECDH_AES_KEY_WRAP             

 

CKD_NULL

CKD_SHA1_KDF

2.3.3 ECDSA public key objects

EC (also related to ECDSA) public key objects (object class CKO_PUBLIC_KEY, key type CKK_EC or CKK_ECDSA) hold EC public keys.  The following table defines the EC public key object attributes, in addition to the common attributes defined for this object class:

Table 30, Elliptic Curve Public Key Object Attributes

Attribute

Data type

Meaning

CKA_EC_PARAMS1,3 (CKA_ECDSA_PARAMS)

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

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_EC_PARAMS or CKA_ECDSA_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI X9.62 as a choice of three parameter representation methods with the following syntax:

Parameters ::= CHOICE {

  ecParameters  ECParameters,

  namedCurve    CURVES.&id({CurveNames}),

  implicitlyCA  NULL

}

 

This allows detailed specification of all required values using choice ecParameters, the use of a namedCurve as an object identifier substitute for a particular set of elliptic curve domain parameters, or implicitlyCA to indicate that the domain parameters are explicitly defined elsewhere.  The use of a namedCurve is recommended over the choice ecParameters.  The choice implicitlyCA must not be used in Cryptoki.

The following is a sample template for creating an EC (ECDSA) public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;

CK_KEY_TYPE keyType = CKK_EC;

CK_UTF8CHAR label[] = “An EC public key object”;

CK_BYTE ecParams[] = {...};

CK_BYTE ecPoint[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_EC_PARAMS, ecParams, sizeof(ecParams)},

  {CKA_EC_POINT, ecPoint, sizeof(ecPoint)}

};

2.3.4 Elliptic curve private key objects

EC (also related to ECDSA) private key objects (object class CKO_PRIVATE_KEY, key type CKK_EC or CKK_ECDSA) hold EC private keys.  See Section 2.3 for more information about EC.  The following table defines the EC private key object attributes, in addition to the common attributes defined for this object class:

Table 31, Elliptic Curve Private Key Object Attributes

Attribute

Data type

Meaning

CKA_EC_PARAMS1,4,6 (CKA_ECDSA_PARAMS)

Byte array

DER-encoding of an ANSI X9.62 Parameters value

CKA_VALUE1,4,6,7

Big integer

ANSI X9.62 private value d

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_EC_PARAMS or CKA_ECDSA_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI X9.62 as a choice of three parameter representation methods with the following syntax:

Parameters ::= CHOICE {

  ecParameters  ECParameters,

  namedCurve    CURVES.&id({CurveNames}),

  implicitlyCA  NULL

}

 

This allows detailed specification of all required values using choice ecParameters, the use of a namedCurve as an object identifier substitute for a particular set of elliptic curve domain parameters, or implicitlyCA to indicate that the domain parameters are explicitly defined elsewhere.  The use of a namedCurve is recommended over the choice ecParameters.  The choice implicitlyCA must not be used in Cryptoki.

Note that when generating an EC private key, the EC domain parameters are not specified in the key’s template.  This is because EC private keys are only generated as part of an EC key pair, and the EC domain parameters for the pair are specified in the template for the EC public key.

The following is a sample template for creating an EC (ECDSA) private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;

CK_KEY_TYPE keyType = CKK_EC;

CK_UTF8CHAR label[] = “An EC private key object”;

CK_BYTE subject[] = {...};

CK_BYTE id[] = {123};

CK_BYTE ecParams[] = {...};

CK_BYTE value[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_SUBJECT, subject, sizeof(subject)},

  {CKA_ID, id, sizeof(id)},

  {CKA_SENSITIVE, &true, sizeof(true)},

  {CKA_DERIVE, &true, sizeof(true)},

  {CKA_EC_PARAMS, ecParams, sizeof(ecParams)},

  {CKA_VALUE, value, sizeof(value)}

};

2.3.5 Elliptic curve key pair generation

The EC (also related to ECDSA) key pair generation mechanism, denoted CKM_EC_KEY_PAIR_GEN or CKM_ECDSA_KEY_PAIR_GEN, is a key pair generation mechanism for EC.

This mechanism does not have a parameter.

The mechanism generates EC public/private key pairs with particular EC domain parameters, as specified in the CKA_EC_PARAMS or CKA_ECDSA_PARAMS attribute of the template for the public key.  Note that this version of Cryptoki does not include a mechanism for generating these EC domain parameters.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_EC_POINT attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_EC_PARAMS or CKA_ECDSA_PARAMS and CKA_VALUE attributes to the new private key.  Other attributes supported by the EC public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively.  For example, if a Cryptoki library supports only ECDSA using a field of characteristic 2 which has between 2200 and 2300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2200 consists of a 1 bit followed by 200 0 bits.  It is therefore a 201-bit number.  Similarly, 2300 is a 301-bit number).

2.3.6 ECDSA without hashing

Refer section 2.3.1 for signature encoding.

The ECDSA without hashing mechanism, denoted CKM_ECDSA, is a mechanism for single-part signatures and verification for ECDSA.  (This mechanism corresponds only to the part of ECDSA that processes the hash value, which should not be longer than 1024 bits; it does not compute the hash value.)

This mechanism does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 32, ECDSA: 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

1 Single-part operations only.

2 Data length, signature length.

3 Input the entire raw digest. Internally, this will be truncated to the appropriate number of bits.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively.  For example, if a Cryptoki library supports only ECDSA using a field of characteristic 2 which has between 2200 and 2300 elements (inclusive), then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2200 consists of a 1 bit followed by 200 0 bits.  It is therefore a 201-bit number.  Similarly, 2300 is a 301-bit number).

2.3.7 ECDSA with SHA-1

Refer to section 2.3.1 for signature encoding.

The ECDSA with SHA-1 mechanism, denoted CKM_ECDSA_SHA1, is a mechanism for single- and multiple-part signatures and verification for ECDSA.  This mechanism computes the entire ECDSA specification, including the hashing with SHA-1.

This mechanism does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 33, ECDSA with SHA-1: 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

2 Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively.  For example, if a Cryptoki library supports only ECDSA using a field of characteristic 2 which has between 2200 and 2300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2200 consists of a 1 bit followed by 200 0 bits.  It is therefore a 201-bit number.  Similarly, 2300 is a 301-bit number).

2.3.8 EC mechanism parameters

¨       CK_EC_KDF_TYPE, CK_EC_KDF_TYPE_PTR

CK_EC_KDF_TYPE is used to indicate the Key Derivation Function (KDF) applied to derive keying data from a shared secret.  The key derivation function will be used by the EC key agreement schemes.  It is defined as follows:

typedef CK_ULONG CK_EC_KDF_TYPE;

 

The following table lists the defined functions.

Table 34, EC: Key Derivation Functions

Source Identifier

CKD_NULL

CKD_SHA1_KDF

CKD_SHA224_KDF

CKD_SHA256_KDF

CKD_SHA384_KDF

CKD_SHA512_KDF

The key derivation function CKD_NULL produces a raw shared secret value without applying any key derivation function whereas the key derivation function CKD_SHA1_KDF, which is based on SHA-1, derives keying data from the shared secret value as defined in ANSI X9.63.

CK_EC_KDF_TYPE_PTR is a pointer to a CK_EC_KDF_TYPE.

¨       CK_ECDH1_DERIVE_PARAMS, CK_ECDH1_DERIVE_PARAMS_PTR

CK_ECDH1_DERIVE_PARAMS is a structure that provides the parameters for the CKM_ECDH1_DERIVE and CKM_ECDH1_COFACTOR_DERIVE key derivation mechanisms, where each party contributes one key pair.  The structure is defined as follows:

typedef struct CK_ECDH1_DERIVE_PARAMS {

   CK_EC_KDF_TYPE kdf;

   CK_ULONG ulSharedDataLen;

   CK_BYTE_PTR pSharedData;

   CK_ULONG ulPublicDataLen;

   CK_BYTE_PTR pPublicData;

} CK_ECDH1_DERIVE_PARAMS;

 

The fields of the structure have the following meanings:

                                            kdf       key derivation function used on the shared secret value

                       ulSharedDataLen       the length in bytes of the shared info

                             pSharedData       some data shared between the two parties

                         ulPublicDataLen       the length in bytes of the other party’s EC public key

                              pPublicData[1]       pointer to other party’s EC public key value. A token MUST be able to accept this value encoded as a raw octet string (as per section A.5.2 of [ANSI X9.62]).  A token MAY, in addition, support accepting this value as a DER-encoded ECPoint (as per section E.6 of [ANSI X9.62]) i.e. the same as a CKA_EC_POINT encoding.  The calling application is responsible for converting the offered public key to the compressed or uncompressed forms of these encodings if the token does not support the offered form.

With the key derivation function CKD_NULL, pSharedData must be NULL and ulSharedDataLen must be zero.  With the key derivation function CKD_SHA1_KDF, an optional pSharedData may be supplied, which consists of some data shared by the two parties intending to share the shared secret.  Otherwise, pSharedData must be NULL and ulSharedDataLen must be zero.

CK_ECDH1_DERIVE_PARAMS_PTR is a pointer to a CK_ECDH1_DERIVE_PARAMS.

 

¨       CK_ECMQV _DERIVE_PARAMS, CK_ECMQV_DERIVE_PARAMS_PTR

CK_ECMQV_DERIVE_PARAMS is a structure that provides the parameters to the CKM_ECMQV_DERIVE key derivation mechanism, where each party contributes two key pairs.  The structure is defined as follows:

typedef struct CK_ECMQV_DERIVE_PARAMS {

   CK_EC_KDF_TYPE kdf;

   CK_ULONG ulSharedDataLen;

   CK_BYTE_PTR pSharedData;

   CK_ULONG ulPublicDataLen;

   CK_BYTE_PTR pPublicData;

   CK_ULONG ulPrivateDataLen;

   CK_OBJECT_HANDLE hPrivateData;

   CK_ULONG ulPublicDataLen2;

   CK_BYTE_PTR pPublicData2;

   CK_OBJECT_HANDLE publicKey;

} CK_ECMQV_DERIVE_PARAMS;

 

The fields of the structure have the following meanings:

                                            kdf       key derivation function used on the shared secret value

                       ulSharedDataLen       the length in bytes of the shared info

                             pSharedData       some data shared between the two parties

                         ulPublicDataLen       the length in bytes of the other party’s first EC public key

                               pPublicData       pointer to other party’s first EC public key value. Encoding rules are as per pPublicData  of CK_ECDH1_DERIVE_PARAMS

                       ulPrivateDataLen       the length in bytes of the second EC private key

                             hPrivateData       key handle for second EC private key value

                       ulPublicDataLen2       the length in bytes of the other party’s second EC public key

                             pPublicData2       pointer to other party’s second EC public key value. Encoding rules are as per pPublicData  of CK_ECDH1_DERIVE_PARAMS

                                  publicKey       Handle to the first party’s ephemeral public key

With the key derivation function CKD_NULL, pSharedData must be NULL and ulSharedDataLen must be zero.  With the key derivation function CKD_SHA1_KDF, an optional pSharedData may be supplied, which consists of some data shared by the two parties intending to share the shared secret.  Otherwise, pSharedData must be NULL and ulSharedDataLen must be zero.

CK_ECMQV_DERIVE_PARAMS_PTR is a pointer to a CK_ECMQV_DERIVE_PARAMS.

2.3.9 Elliptic curve Diffie-Hellman key derivation

The elliptic curve Diffie-Hellman (ECDH) key derivation mechanism, denoted CKM_ECDH1_DERIVE, is a mechanism for key derivation based on the Diffie-Hellman version of the elliptic curve key agreement scheme, as defined in ANSI X9.63, where each party contributes one key pair all using the same EC domain parameters.

It has a parameter, a CK_ECDH1_DERIVE_PARAMS structure.

This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template.  (The truncation removes bytes from the leading end of the secret value.)  The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.

This mechanism has the following rules about key sensitivity and extractability:

·         The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE.  If omitted, these attributes each take on some default value.

·         If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well.  If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.

·         Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too.  If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively.  For example, if a Cryptoki library supports only EC using a field of characteristic 2 which has between 2200 and 2300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2200 consists of a 1 bit followed by 200 0 bits.  It is therefore a 201-bit number.  Similarly, 2300 is a 301-bit number).

2.3.10 Elliptic curve Diffie-Hellman with cofactor key derivation

The elliptic curve Diffie-Hellman (ECDH) with cofactor key derivation mechanism, denoted CKM_ECDH1_COFACTOR_DERIVE, is a mechanism for key derivation based on the cofactor Diffie-Hellman version of the elliptic curve key agreement scheme, as defined in ANSI X9.63, where each party contributes one key pair all using the same EC domain parameters.  Cofactor multiplication is computationally efficient and helps to prevent security problems like small group attacks.

It has a parameter, a CK_ECDH1_DERIVE_PARAMS structure.

This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template.  (The truncation removes bytes from the leading end of the secret value.)  The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.

This mechanism has the following rules about key sensitivity and extractability:

·         The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE.  If omitted, these attributes each take on some default value.

·         If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well.  If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.

·         Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too.  If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively.  For example, if a Cryptoki library supports only EC using a field of characteristic 2 which has between 2200 and 2300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2200 consists of a 1 bit followed by 200 0 bits.  It is therefore a 201-bit number.  Similarly, 2300 is a 301-bit number).

2.3.11 Elliptic curve Menezes-Qu-Vanstone key derivation

The elliptic curve Menezes-Qu-Vanstone (ECMQV) key derivation mechanism, denoted CKM_ECMQV_DERIVE, is a mechanism for key derivation based the MQV version of the elliptic curve key agreement scheme, as defined in ANSI X9.63, where each party contributes two key pairs all using the same EC domain parameters.

It has a parameter, a CK_ECMQV_DERIVE_PARAMS structure.

This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template.  (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.

This mechanism has the following rules about key sensitivity and extractability:

·         The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE.  If omitted, these attributes each take on some default value.

·         If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well.  If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.

·         Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too.  If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively.  For example, if a Cryptoki library supports only EC using a field of characteristic 2 which has between 2200 and 2300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2200 consists of a 1 bit followed by 200 0 bits.  It is therefore a 201-bit number.  Similarly, 2300 is a 301-bit number).

2.3.12 ECDH AES KEY WRAP

The ECDH AES KEY WRAP mechanism, denoted CKM_ECDH_AES_KEY_WRAP, is a mechanism based on elliptic curve public-key crypto-system and the AES key wrap mechanism.  It supports single-part key wrapping; and key unwrapping. 

It has a parameter, a CK_ECDH_AES_KEY_WRAP_PARAMS structure.

 

The mechanism can wrap and un-wrap an asymmetric target key of any length and type using an EC key.

-          A temporary AES key is derived from a temporary EC key and the wrapping EC key using the CKM_ECDH1_DERIVE mechanism.

-          The derived AES key is used for wrapping the target key using the CKM_AES_KEY_WRAP_PAD mechanism.

 

For wrapping, the mechanism -                

 

The recommended format for an asymmetric target key being wrapped is as a PKCS8 PrivateKeyInfo

 

The use of Attributes in the PrivateKeyInfo structure  is OPTIONAL.  In case of conflicts between the object attribute template, and Attributes in the PrivateKeyInfo structure, an error should be thrown.

 

For unwrapping, the mechanism -

Note: since the transport key and the wrapping EC key share the same domain, the length of the public key material of the transport key is the same length of the public key material of the unwrapping EC key.

 

Table 35, CKM_ECDH_AES_KEY_WRAP Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

CKM_ECDH_AES_KEY_WRAP

 

 

 

 

 

ü

 

1SR = SignRecover, VR = VerifyRecover

 

 

2.3.13 ECDH AES KEY WRAP mechanism parameters

¨       CK_ECDH_AES_KEY_WRAP_PARAMS; CK_ECDH_AES_KEY_WRAP_PARAMS_PTR

CK_ECDH_AES_KEY_WRAP_PARAMS is a structure that provides the parameters to the CKM_ECDH_AES_KEY_WRAP mechanism.  It is defined as follows:

 

typedef struct CK_ECDH_AES_KEY_WRAP_PARAMS {

CK_ULONG                         ulAESKeyBits;

CK_EC_KDF_TYPE                kdf;

CK_ULONG                               ulSharedDataLen;

CK_BYTE_PTR                        pSharedData;

} CK_ECDH_AES_KEY_WRAP_PARAMS;

 

The fields of the structure have the following meanings:

 

ulAESKeyBits length of the temporary AES key in bits. Can be only 128, 192 or 256.

Kdf               key derivation function used on the shared secret value to generate AES key.

ulSharedDataLen the length in bytes of the shared info

pSharedData Some data shared between the two parties

 

CK_ECDH_AES_KEY_WRAP_PARAMS_PTR is a pointer to a CK_ECDH_AES_KEY_WRAP_PARAMS.

 

2.3.14 FIPS 186-4

When CKM_ECDSA is operated in FIPS mode, the curves SHALL either be NIST recommended curves (with a fixed set of domain parameters) or curves with domain parameters generated as specified by ANSI X9.64. The NIST recommended curves are:

 

P-192, P-224, P-256, P-384, P-521

K-163, B-163, K-233, B-233

K-283, B-283, K-409, B-409

K-571, B-571

 

2.4 Diffie-Hellman

Table 36, Diffie-Hellman Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

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

 

 

 

 

 

 

ü

2.4.1 Definitions

This section defines the key type “CKK_DH” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of [DH] key objects.

Mechanisms:

CKM_DH_PKCS_KEY_PAIR_GEN       

CKM_DH_PKCS_DERIVE            

CKM_X9_42_DH_KEY_PAIR_GEN     

CKM_X9_42_DH_DERIVE           

CKM_X9_42_DH_HYBRID_DERIVE    

CKM_X9_42_MQV_DERIVE          

CKM_DH_PKCS_PARAMETER_GEN     

CKM_X9_42_DH_PARAMETER_GEN    

2.4.2 Diffie-Hellman public key objects

Diffie-Hellman public key objects (object class CKO_PUBLIC_KEY, key type CKK_DH) hold Diffie-Hellman public keys.  The following table defines the Diffie-Hellman public key object attributes, in addition to the common attributes defined for this object class:

Table 37, 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

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_PRIME and CKA_BASE attribute values are collectively the “Diffie-Hellman domain parameters”.  Depending on the token, there may be limits on the length of the key components. See PKCS #3 for more information on Diffie-Hellman keys.

The following is a sample template for creating a Diffie-Hellman public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;

CK_KEY_TYPE keyType = CKK_DH;

CK_UTF8CHAR label[] = “A Diffie-Hellman public key object”;

CK_BYTE prime[] = {...};

CK_BYTE base[] = {...};

CK_BYTE value[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_PRIME, prime, sizeof(prime)},

  {CKA_BASE, base, sizeof(base)},

  {CKA_VALUE, value, sizeof(value)}

};

2.4.3 X9.42 Diffie-Hellman public key objects

X9.42 Diffie-Hellman public key objects (object class CKO_PUBLIC_KEY, key type CKK_X9_42_DH) hold X9.42 Diffie-Hellman public keys.  The following table defines the X9.42 Diffie-Hellman public key object attributes, in addition to the common attributes defined for this object class:

Table 38, 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

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_PRIME, CKA_BASE and CKA_SUBPRIME attribute values are collectively the “X9.42 Diffie-Hellman domain parameters”.  See the ANSI X9.42 standard for more information on X9.42 Diffie-Hellman keys.

The following is a sample template for creating a X9.42 Diffie-Hellman public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;

CK_KEY_TYPE keyType = CKK_X9_42_DH;

CK_UTF8CHAR label[] = “A X9.42 Diffie-Hellman public key object”;

CK_BYTE prime[] = {...};

CK_BYTE base[] = {...};

CK_BYTE subprime[] = {...};

CK_BYTE value[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_PRIME, prime, sizeof(prime)},

  {CKA_BASE, base, sizeof(base)},

  {CKA_SUBPRIME, subprime, sizeof(subprime)},

  {CKA_VALUE, value, sizeof(value)}

};

2.4.4 Diffie-Hellman private key objects

Diffie-Hellman private key objects (object class CKO_PRIVATE_KEY, key type CKK_DH) hold Diffie-Hellman private keys.  The following table defines the Diffie-Hellman private key object attributes, in addition to the common attributes defined for this object class:

Table 39, 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

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_PRIME and CKA_BASE attribute values are collectively the “Diffie-Hellman domain parameters”.  Depending on the token, there may be limits on the length of the key components.  See PKCS #3 for more information on Diffie-Hellman keys.

Note that when generating a Diffie-Hellman private key, the Diffie-Hellman parameters are not specified in the key’s template.  This is because Diffie-Hellman private keys are only generated as part of a Diffie-Hellman key pair, and the Diffie-Hellman parameters for the pair are specified in the template for the Diffie-Hellman public key.

The following is a sample template for creating a Diffie-Hellman private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;

CK_KEY_TYPE keyType = CKK_DH;

CK_UTF8CHAR label[] = “A Diffie-Hellman private key object”;

CK_BYTE subject[] = {...};

CK_BYTE id[] = {123};

CK_BYTE prime[] = {...};

CK_BYTE base[] = {...};

CK_BYTE value[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_SUBJECT, subject, sizeof(subject)},

  {CKA_ID, id, sizeof(id)},

  {CKA_SENSITIVE, &true, sizeof(true)},

  {CKA_DERIVE, &true, sizeof(true)},

  {CKA_PRIME, prime, sizeof(prime)},

  {CKA_BASE, base, sizeof(base)},

  {CKA_VALUE, value, sizeof(value)}

};

2.4.5 X9.42 Diffie-Hellman private key objects

X9.42 Diffie-Hellman private key objects (object class CKO_PRIVATE_KEY, key type CKK_X9_42_DH) hold X9.42 Diffie-Hellman private keys.  The following table defines the X9.42 Diffie-Hellman private key object attributes, in addition to the common attributes defined for this object class:

Table 40, 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

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_PRIME, CKA_BASE and CKA_SUBPRIME attribute values are collectively the “X9.42 Diffie-Hellman domain parameters”.  Depending on the token, there may be limits on the length of the key components.  See the ANSI X9.42 standard for more information on X9.42 Diffie-Hellman keys.

Note that when generating a X9.42 Diffie-Hellman private key, the X9.42 Diffie-Hellman domain parameters are not specified in the key’s template.  This is because X9.42 Diffie-Hellman private keys are only generated as part of a X9.42 Diffie-Hellman key pair, and the X9.42 Diffie-Hellman domain parameters for the pair are specified in the template for the X9.42 Diffie-Hellman public key.

The following is a sample template for creating a X9.42 Diffie-Hellman private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;

CK_KEY_TYPE keyType = CKK_X9_42_DH;

CK_UTF8CHAR label[] = “A X9.42 Diffie-Hellman private key object”;

CK_BYTE subject[] = {...};

CK_BYTE id[] = {123};

CK_BYTE prime[] = {...};

CK_BYTE base[] = {...};

CK_BYTE subprime[] = {...};

CK_BYTE value[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_SUBJECT, subject, sizeof(subject)},

  {CKA_ID, id, sizeof(id)},

  {CKA_SENSITIVE, &true, sizeof(true)},

  {CKA_DERIVE, &true, sizeof(true)},

  {CKA_PRIME, prime, sizeof(prime)},

  {CKA_BASE, base, sizeof(base)},

  {CKA_SUBPRIME, subprime, sizeof(subprime)},

  {CKA_VALUE, value, sizeof(value)}

};

2.4.6 Diffie-Hellman domain parameter objects

Diffie-Hellman domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type CKK_DH) hold Diffie-Hellman domain parameters.  The following table defines the Diffie-Hellman domain parameter object attributes, in addition to the common attributes defined for this object class:

Table 41, 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.

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_PRIME and CKA_BASE attribute values are collectively the “Diffie-Hellman domain parameters”.  Depending on the token, there may be limits on the length of the key components. See PKCS #3 for more information on Diffie-Hellman domain parameters.

The following is a sample template for creating a Diffie-Hellman domain parameter object:

CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS;

CK_KEY_TYPE keyType = CKK_DH;

CK_UTF8CHAR label[] = “A Diffie-Hellman domain parameters object”;

CK_BYTE prime[] = {...};

CK_BYTE base[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_PRIME, prime, sizeof(prime)},

  {CKA_BASE, base, sizeof(base)},

};

2.4.7 X9.42 Diffie-Hellman domain parameters objects

X9.42 Diffie-Hellman domain parameters objects (object class CKO_DOMAIN_PARAMETERS, key type CKK_X9_42_DH) hold X9.42 Diffie-Hellman domain parameters.  The following table defines the X9.42 Diffie-Hellman domain parameters object attributes, in addition to the common attributes defined for this object class:

Table 42, 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.

- Refer to [PKCS #11-Base]  table 10 for footnotes

The CKA_PRIME, CKA_BASE and CKA_SUBPRIME attribute values are collectively the “X9.42 Diffie-Hellman domain parameters”.  Depending on the token, there may be limits on the length of the domain parameters components.  See the ANSI X9.42 standard for more information on X9.42 Diffie-Hellman domain parameters.

The following is a sample template for creating a X9.42 Diffie-Hellman domain parameters object:

CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS;

CK_KEY_TYPE keyType = CKK_X9_42_DH;

CK_UTF8CHAR label[] = “A X9.42 Diffie-Hellman domain parameters object”;

CK_BYTE prime[] = {...};

CK_BYTE base[] = {...};

CK_BYTE subprime[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_PRIME, prime, sizeof(prime)},

  {CKA_BASE, base, sizeof(base)},

  {CKA_SUBPRIME, subprime, sizeof(subprime)},

};

2.4.8 PKCS #3 Diffie-Hellman key pair generation

The PKCS #3 Diffie-Hellman key pair generation mechanism, denoted CKM_DH_PKCS_KEY_PAIR_GEN, is a key pair generation mechanism based on Diffie-Hellman key agreement, as defined in PKCS #3.  This is what PKCS #3 calls “phase I”.  It does not have a parameter.

The mechanism generates Diffie-Hellman public/private key pairs with a particular prime and base, as specified in the CKA_PRIME and CKA_BASE attributes of the template for the public key. If the CKA_VALUE_BITS attribute of the private key is specified, the mechanism limits the length in bits of the private value, as described in PKCS #3. 

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, and CKA_VALUE (and the CKA_VALUE_BITS attribute, if it is not already provided in the template) attributes to the new private key; other attributes required by the Diffie-Hellman public and private key types must be specified in the templates.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of Diffie-Hellman prime sizes, in bits.

2.4.9 PKCS #3 Diffie-Hellman domain parameter generation

The PKCS #3 Diffie-Hellman domain parameter generation mechanism, denoted CKM_DH_PKCS_PARAMETER_GEN, is a domain parameter generation mechanism based on Diffie-Hellman key agreement, as defined in PKCS #3.

It does not have a parameter.

The mechanism generates Diffie-Hellman domain parameters with a particular prime length in bits, as specified in the CKA_PRIME_BITS attribute of the template.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, and CKA_PRIME_BITS attributes to the new object. Other attributes supported by the Diffie-Hellman domain parameter types may also be specified in the template, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of Diffie-Hellman prime sizes, in bits.

2.4.10 PKCS #3 Diffie-Hellman key derivation

The PKCS #3 Diffie-Hellman key derivation mechanism, denoted CKM_DH_PKCS_DERIVE, is a mechanism for key derivation based on Diffie-Hellman key agreement, as defined in PKCS #3. This is what PKCS #3 calls “phase II”.

It has a parameter, which is the public value of the other party in the key agreement protocol, represented as a Cryptoki “Big integer” (i.e., a sequence of bytes, most-significant byte first).

This mechanism derives a secret key from a Diffie-Hellman private key and the public value of the other party.  It computes a Diffie-Hellman secret value from the public value and private key according to PKCS #3, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.

This mechanism has the following rules about key sensitivity and extractability[2]:

·         The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE.  If omitted, these attributes each take on some default value.

·         If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well.  If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.

·         Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too.  If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of Diffie-Hellman prime sizes, in bits.

2.4.11 X9.42 Diffie-Hellman mechanism parameters

¨       CK_X9_42_DH_KDF_TYPE, CK_X9_42_DH_KDF_TYPE_PTR

CK_X9_42_DH_KDF_TYPE is used to indicate the Key Derivation Function (KDF) applied to derive keying data from a shared secret.  The key derivation function will be used by the X9.42 Diffie-Hellman key agreement schemes.  It is defined as follows:

typedef CK_ULONG CK_X9_42_DH_KDF_TYPE;

 

The following table lists the defined functions.

Table 43, X9.42 Diffie-Hellman Key Derivation Functions

Source Identifier

CKD_NULL

CKD_SHA1_KDF_ASN1

CKD_SHA1_KDF_CONCATENATE

The key derivation function CKD_NULL produces a raw shared secret value without applying any key derivation function whereas the key derivation functions CKD_SHA1_KDF_ASN1 and CKD_SHA1_KDF_CONCATENATE, which are both based on SHA-1, derive keying data from the shared secret value as defined in the ANSI X9.42 standard.

CK_X9_42_DH_KDF_TYPE_PTR is a pointer to a CK_X9_42_DH_KDF_TYPE.

¨    CK_X9_42_DH1_DERIVE_PARAMS, CK_X9_42_DH1_DERIVE_PARAMS_PTR

CK_X9_42_DH1_DERIVE_PARAMS is a structure that provides the parameters to the CKM_X9_42_DH_DERIVE key derivation mechanism, where each party contributes one key pair.  The structure is defined as follows:

typedef struct CK_X9_42_DH1_DERIVE_PARAMS {

   CK_X9_42_DH_KDF_TYPE kdf;

   CK_ULONG ulOtherInfoLen;

   CK_BYTE_PTR pOtherInfo;

   CK_ULONG ulPublicDataLen;

   CK_BYTE_PTR pPublicData;

} CK_X9_42_DH1_DERIVE_PARAMS;

 

The fields of the structure have the following meanings:

                                            kdf       key derivation function used on the shared secret value

                           ulOtherInfoLen       the length in bytes of the other info

                                 pOtherInfo       some data shared between the two parties

                         ulPublicDataLen       the length in bytes of the other party’s X9.42 Diffie-Hellman public key

                               pPublicData       pointer to other party’s X9.42 Diffie-Hellman public key value

With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero.  With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by the two parties intending to share the shared secret.  With the key derivation function CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some data shared by the two parties intending to share the shared secret.  Otherwise, pOtherInfo must be NULL and ulOtherInfoLen must be zero.

CK_X9_42_DH1_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_DH1_DERIVE_PARAMS.

·         CK_X9_42_DH2_DERIVE_PARAMS, CK_X9_42_DH2_DERIVE_PARAMS_PTR

CK_X9_42_DH2_DERIVE_PARAMS is a structure that provides the parameters to the CKM_X9_42_DH_HYBRID_DERIVE and CKM_X9_42_MQV_DERIVE key derivation mechanisms, where each party contributes two key pairs.  The structure is defined as follows:

typedef struct CK_X9_42_DH2_DERIVE_PARAMS {

   CK_X9_42_DH_KDF_TYPE kdf;

   CK_ULONG ulOtherInfoLen;

   CK_BYTE_PTR pOtherInfo;

   CK_ULONG ulPublicDataLen;

   CK_BYTE_PTR pPublicData;

   CK_ULONG ulPrivateDataLen;

   CK_OBJECT_HANDLE hPrivateData;

   CK_ULONG ulPublicDataLen2;

   CK_BYTE_PTR pPublicData2;

} CK_X9_42_DH2_DERIVE_PARAMS;

 

The fields of the structure have the following meanings:

                                            kdf       key derivation function used on the shared secret value

                           ulOtherInfoLen       the length in bytes of the other info

                                 pOtherInfo       some data shared between the two parties

                         ulPublicDataLen       the length in bytes of the other party’s first X9.42 Diffie-Hellman public key

                               pPublicData       pointer to other party’s first X9.42 Diffie-Hellman public key value

                       ulPrivateDataLen       the length in bytes of the second X9.42 Diffie-Hellman private key

                             hPrivateData       key handle for second X9.42 Diffie-Hellman private key value

                       ulPublicDataLen2       the length in bytes of the other party’s second X9.42 Diffie-Hellman public key

                             pPublicData2       pointer to other party’s second X9.42 Diffie-Hellman public key value

With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero.  With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by the two parties intending to share the shared secret.  With the key derivation function CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some data shared by the two parties intending to share the shared secret.  Otherwise, pOtherInfo must be NULL and ulOtherInfoLen must be zero.

CK_X9_42_DH2_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_DH2_DERIVE_PARAMS.

·         CK_X9_42_MQV_DERIVE_PARAMS, CK_X9_42_MQV_DERIVE_PARAMS_PTR

CK_X9_42_MQV_DERIVE_PARAMS is a structure that provides the parameters to the CKM_X9_42_MQV_DERIVE key derivation mechanism, where each party contributes two key pairs.  The structure is defined as follows:

typedef struct CK_X9_42_MQV_DERIVE_PARAMS {

   CK_X9_42_DH_KDF_TYPE kdf;

   CK_ULONG ulOtherInfoLen;

   CK_BYTE_PTR pOtherInfo;

   CK_ULONG ulPublicDataLen;

   CK_BYTE_PTR pPublicData;

   CK_ULONG ulPrivateDataLen;

   CK_OBJECT_HANDLE hPrivateData;

   CK_ULONG ulPublicDataLen2;

   CK_BYTE_PTR pPublicData2;

   CK_OBJECT_HANDLE publicKey;

} CK_X9_42_MQV_DERIVE_PARAMS;

 

The fields of the structure have the following meanings:

                                            kdf       key derivation function used on the shared secret value

                           ulOtherInfoLen       the length in bytes of the other info

                                 pOtherInfo       some data shared between the two parties

                         ulPublicDataLen       the length in bytes of the other party’s first X9.42 Diffie-Hellman public key

                               pPublicData       pointer to other party’s first X9.42 Diffie-Hellman public key value

                       ulPrivateDataLen       the length in bytes of the second X9.42 Diffie-Hellman private key

                             hPrivateData       key handle for second X9.42 Diffie-Hellman private key value

                       ulPublicDataLen2       the length in bytes of the other party’s second X9.42 Diffie-Hellman public key

                             pPublicData2       pointer to other party’s second X9.42 Diffie-Hellman public key value

                                  publicKey       Handle to the first party’s ephemeral public key

With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero.  With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by the two parties intending to share the shared secret.  With the key derivation function CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some data shared by the two parties intending to share the shared secret.  Otherwise, pOtherInfo must be NULL and ulOtherInfoLen must be zero.

CK_X9_42_MQV_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_MQV_DERIVE_PARAMS.

2.4.12 X9.42 Diffie-Hellman key pair generation

The X9.42 Diffie-Hellman key pair generation mechanism, denoted CKM_X9_42_DH_KEY_PAIR_GEN, is a key pair generation mechanism based on Diffie-Hellman key agreement, as defined in the ANSI X9.42 standard.

It does not have a parameter.

The mechanism generates X9.42 Diffie-Hellman public/private key pairs with a particular prime, base and subprime, as specified in the CKA_PRIME, CKA_BASE and CKA_SUBPRIME attributes of the template for the public key.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, CKA_SUBPRIME, and CKA_VALUE attributes to the new private key; other attributes required by the X9.42 Diffie-Hellman public and private key types must be specified in the templates.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.

2.4.13 X9.42 Diffie-Hellman domain parameter generation

The X9.42 Diffie-Hellman domain parameter generation mechanism, denoted CKM_X9_42_DH_PARAMETER_GEN, is a domain parameters generation mechanism based on X9.42 Diffie-Hellman key agreement, as defined in the ANSI X9.42 standard.

It does not have a parameter.

The mechanism generates X9.42 Diffie-Hellman domain parameters with particular prime and subprime length in bits, as specified in the CKA_PRIME_BITS and CKA_SUBPRIME_BITS attributes of the template for the domain parameters.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, CKA_SUBPRIME, CKA_PRIME_BITS and CKA_SUBPRIME_BITS attributes to the new object.  Other attributes supported by the X9.42 Diffie-Hellman domain parameter types may also be specified in the template for the domain parameters, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits.

2.4.14 X9.42 Diffie-Hellman key derivation

The X9.42 Diffie-Hellman key derivation mechanism, denoted CKM_X9_42_DH_DERIVE, is a mechanism for key derivation based on the Diffie-Hellman key agreement scheme, as defined in the ANSI X9.42 standard, where each party contributes one key pair, all using the same X9.42 Diffie-Hellman domain parameters.

It has a parameter, a CK_X9_42_DH1_DERIVE_PARAMS structure.

This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template.  (The truncation removes bytes from the leading end of the secret value.)  The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. Note that in order to validate this mechanism it may be required to use the CKA_VALUE attribute as the key of a general-length MAC mechanism (e.g. CKM_SHA_1_HMAC_GENERAL) over some test data.

This mechanism has the following rules about key sensitivity and extractability:

·         The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE.  If omitted, these attributes each take on some default value.

·         If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well.  If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.

·         Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too.  If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.

2.4.15 X9.42 Diffie-Hellman hybrid key derivation

The X9.42 Diffie-Hellman hybrid key derivation mechanism, denoted CKM_X9_42_DH_HYBRID_DERIVE, is a mechanism for key derivation based on the Diffie-Hellman hybrid key agreement scheme, as defined in the ANSI X9.42 standard, where each party contributes two key pair, all using the same X9.42 Diffie-Hellman domain parameters.

It has a parameter, a CK_X9_42_DH2_DERIVE_PARAMS structure.

This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template.  (The truncation removes bytes from the leading end of the secret value.)  The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. Note that in order to validate this mechanism it may be required to use the CKA_VALUE attribute as the key of a general-length MAC mechanism (e.g. CKM_SHA_1_HMAC_GENERAL) over some test data.

This mechanism has the following rules about key sensitivity and extractability:

·         The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE.  If omitted, these attributes each take on some default value.

·         If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well.  If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.

·         Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too.  If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.

2.4.16 X9.42 Diffie-Hellman Menezes-Qu-Vanstone key derivation

The X9.42 Diffie-Hellman Menezes-Qu-Vanstone (MQV) key derivation mechanism, denoted CKM_X9_42_MQV_DERIVE, is a mechanism for key derivation based the MQV scheme, as defined in the ANSI X9.42 standard, where each party contributes two key pairs, all using the same X9.42 Diffie-Hellman domain parameters.

It has a parameter, a CK_X9_42_MQV_DERIVE_PARAMS structure.

This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template.  (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. Note that in order to validate this mechanism it may be required to use the CKA_VALUE attribute as the key of a general-length MAC mechanism (e.g. CKM_SHA_1_HMAC_GENERAL) over some test data.

This mechanism has the following rules about key sensitivity and extractability:

·         The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE.  If omitted, these attributes each take on some default value.

·         If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well.  If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.

·         Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too.  If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.

2.5 Wrapping/unwrapping private keys

Cryptoki Versions 2.01 and up allow the use of secret keys for wrapping and unwrapping RSA private keys, Diffie-Hellman private keys, X9.42 Diffie-Hellman private keys, EC (also related to ECDSA) private keys and DSA private keys.  For wrapping, a private key is BER-encoded according to PKCS #8’s PrivateKeyInfo ASN.1 type.  PKCS #8 requires an algorithm identifier for the type of the private key.  The object identifiers for the required algorithm identifiers are as follows:

rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1 }

 

dhKeyAgreement OBJECT IDENTIFIER ::= { pkcs-3 1 }

 

dhpublicnumber OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) ansi-x942(10046) number-type(2) 1 }

 

id-ecPublicKey OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) ansi-x9-62(10045) publicKeyType(2) 1 }

 

id-dsa OBJECT IDENTIFIER ::= {

  iso(1) member-body(2) us(840) x9-57(10040) x9cm(4) 1 }

 

where

pkcs-1 OBJECT IDENTIFIER ::= {

  iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 1 }

 

pkcs-3 OBJECT IDENTIFIER ::= {

  iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 3 }

 

These parameters for the algorithm identifiers have the following types, respectively:

NULL

 

DHParameter ::= SEQUENCE {

  prime              INTEGER,  -- p

  base               INTEGER,  -- g

  privateValueLength INTEGER OPTIONAL

}

 

DomainParameters ::= SEQUENCE {

  prime              INTEGER,  -- p

  base               INTEGER,  -- g

  subprime           INTEGER,  -- q

  cofactor           INTEGER OPTIONAL,  -- j

  validationParms    ValidationParms OPTIONAL

}

 

ValidationParms ::= SEQUENCE {

  Seed          BIT STRING, -- seed

  PGenCounter   INTEGER     -- parameter verification

}

 

Parameters ::= CHOICE {

  ecParameters  ECParameters,

  namedCurve    CURVES.&id({CurveNames}),

  implicitlyCA  NULL

}

 

Dss-Parms ::= SEQUENCE {

  p INTEGER,

  q INTEGER,

  g INTEGER

}

 

For the X9.42 Diffie-Hellman domain parameters, the cofactor and the validationParms optional fields should not be used when wrapping or unwrapping X9.42 Diffie-Hellman private keys since their values are not stored within the token.

For the EC domain parameters, the use of namedCurve is recommended over the choice ecParameters.  The choice implicitlyCA must not be used in Cryptoki.

Within the PrivateKeyInfo type:

·         RSA private keys are BER-encoded according to PKCS #1’s RSAPrivateKey ASN.1 type.  This type requires values to be present for all the attributes specific to Cryptoki’s RSA private key objects.  In other words, if a Cryptoki library does not have values for an RSA private key’s CKA_MODULUS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT2, and CKA_COEFFICIENT values, it must not create an RSAPrivateKey BER-encoding of the key, and so it must not prepare it for wrapping.

·         Diffie-Hellman private keys are represented as BER-encoded ASN.1 type INTEGER.

·         X9.42 Diffie-Hellman private keys are represented as BER-encoded ASN.1 type INTEGER.

·         EC (also related with ECDSA) private keys are BER-encoded according to SECG SEC 1 ECPrivateKey ASN.1 type:

ECPrivateKey ::= SEQUENCE {

   Version      INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),

   privateKey   OCTET STRING,

   parameters   [0] Parameters OPTIONAL,

   publicKey    [1] BIT STRING OPTIONAL

}

 

Since the EC domain parameters are placed in the PKCS #8’s privateKeyAlgorithm field, the optional parameters field in an ECPrivateKey must be omitted.  A Cryptoki application must be able to unwrap an ECPrivateKey that contains the optional publicKey field; however, what is done with this publicKey field is outside the scope of Cryptoki.

·         DSA private keys are represented as BER-encoded ASN.1 type INTEGER.

Once a private key has been BER-encoded as a PrivateKeyInfo type, the resulting string of bytes is encrypted with the secret key.  This encryption must be done in CBC mode with PKCS padding.

Unwrapping a wrapped private key undoes the above procedure.  The CBC-encrypted ciphertext is decrypted, and the PKCS padding is removed.  The data thereby obtained are parsed as a PrivateKeyInfo type, and the wrapped key is produced.  An error will result if the original wrapped key does not decrypt properly, or if the decrypted unpadded data does not parse properly, or its type does not match the key type specified in the template for the new key.  The unwrapping mechanism contributes only those attributes specified in the PrivateKeyInfo type to the newly-unwrapped key; other attributes must be specified in the template, or will take their default values.

Earlier drafts of PKCS #11 Version 2.0 and Version 2.01 used the object identifier

DSA OBJECT IDENTIFIER ::= { algorithm 12 }

algorithm OBJECT IDENTIFIER ::= {

  iso(1) identifier-organization(3) oiw(14) secsig(3) algorithm(2) }

 

with associated parameters

DSAParameters ::= SEQUENCE {

  prime1 INTEGER,  -- modulus p

  prime2 INTEGER,  -- modulus q

  base INTEGER  -- base g

}

 

for wrapping DSA private keys.  Note that although the two structures for holding DSA domain parameters appear identical when instances of them are encoded, the two corresponding object identifiers are different.

2.6 Generic secret key

Table 44, Generic Secret Key Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

CKM_GENERIC_SECRET_KEY_GEN

 

 

 

 

ü

 

 

2.6.1 Definitions

This section defines the key type “CKK_GENERIC_SECRET” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.

Mechanisms:

CKM_GENERIC_SECRET_KEY_GEN

2.6.2 Generic secret key objects

Generic secret key objects (object class CKO_SECRET_KEY, key type CKK_GENERIC_SECRET) hold generic secret keys. These keys do not support encryption or decryption; however, other keys can be derived from them and they can be used in HMAC operations. The following table defines the generic secret key object attributes, in addition to the common attributes defined for this object class:

These key types are used in several of the mechanisms described in this section.

Table 45, 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

- Refer to [PKCS #11-Base]  table 10 for footnotes

The following is a sample template for creating a generic secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;

CK_KEY_TYPE keyType = CKK_GENERIC_SECRET;

CK_UTF8CHAR label[] = “A generic secret key object”;

CK_BYTE value[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_DERIVE, &true, sizeof(true)},

  {CKA_VALUE, value, sizeof(value)}

};

 

CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three bytes of the SHA-1 hash of the generic secret key object’s CKA_VALUE attribute.

2.6.3 Generic secret key generation

The generic secret key generation mechanism, denoted CKM_GENERIC_SECRET_KEY_GEN, is used to generate generic secret keys. The generated keys take on any attributes provided in the template passed to the C_GenerateKey call, and the CKA_VALUE_LEN attribute specifies the length of the key to be generated.

It does not have a parameter.

The template supplied must specify a value for the CKA_VALUE_LEN attribute.  If the template specifies an object type and a class, they must have the following values:

   CK_OBJECT_CLASS = CKO_SECRET_KEY;

   CK_KEY_TYPE = CKK_GENERIC_SECRET;

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of key sizes, in bits.

2.7 HMAC mechanisms

Refer to RFC2104 and FIPS 198 for HMAC algorithm description.. The HMAC secret key shall correspond to the PKCS11 generic secret key type or the mechanism specific key types (see mechanism definition). Such keys, for use with HMAC operations can be created using C_CreateObject or C_GenerateKey.

The RFC also specifies test vectors for the various hash function based HMAC mechanisms described in the respective hash mechanism descriptions. The RFC should be consulted to obtain these test vectors.

2.8 AES

For the Advanced Encryption Standard (AES) see [FIPS PUB 197].

Table 46, AES Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

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

 

ü

 

 

 

 

 

2.8.1 Definitions

This section defines the key type “CKK_AES” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.

Mechanisms:

CKM_AES_KEY_GEN               

CKM_AES_ECB                   

CKM_AES_CBC                   

CKM_AES_MAC                    

CKM_AES_MAC_GENERAL           

CKM_AES_CBC_PAD

CKM_AES_OFB

CKM_AES_CFB64

CKM_AES_CFB8

CKM_AES_CFB128

CKM_AES_CFB1

CKM_AES_XCBC_MAC

CKM_AES_XCBC_MAC_96

2.8.2 AES secret key objects

AES secret key objects (object class CKO_SECRET_KEY, key type CKK_AES) hold AES keys.  The following table defines the AES secret key object attributes, in addition to the common attributes defined for this object class:

Table 47, AES 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

- Refer to [PKCS #11-Base]  table 10 for footnotes

The following is a sample template for creating an AES secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;

CK_KEY_TYPE keyType = CKK_AES;

CK_UTF8CHAR label[] = “An AES secret key object”;

CK_BYTE value[] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_ENCRYPT, &true, sizeof(true)},

  {CKA_VALUE, value, sizeof(value)}

};

 

CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three bytes of the ECB encryption of a single block of null (0x00) bytes, using the default cipher associated with the key type of the secret key object.

2.8.3 AES key generation

The AES key generation mechanism, denoted CKM_AES_KEY_GEN, is a key generation mechanism for NIST’s Advanced Encryption Standard.

It does not have a parameter.

The mechanism generates AES keys with a particular length in bytes, as specified in the CKA_VALUE_LEN attribute of the template for the key.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key. Other attributes supported by the AES key type (specifically, the flags indicating which functions the key supports) may be specified in the template for the key, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

2.8.4 AES-ECB

AES-ECB, denoted CKM_AES_ECB, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on NIST Advanced Encryption Standard and electronic codebook mode.

It does not have a parameter.

This mechanism can wrap and unwrap any secret key.  Of course, a particular token may not be able to wrap/unwrap every secret key that it supports.  For wrapping, the mechanism encrypts the value of the CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus one null bytes so that the resulting length is a multiple of the block size. The output data is the same length as the padded input data. It does not wrap the key type, key length, or any other information about the key; the application must convey these separately.

For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the CKA_VALUE_LEN attribute of the template.  The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.

Constraints on key types and the length of data are summarized in the following table:

Table  48, AES-ECB: Key And Data Length

Function

Key type

Input length

Output length

Comments

C_Encrypt

AES

multiple of block size

same as input length

no final part

C_Decrypt

AES

multiple of block size

same as input length

no final part

C_WrapKey

AES

any

input length rounded up to multiple of block size

 

C_UnwrapKey

AES

multiple of block size

determined by type of key being unwrapped or CKA_VALUE_LEN

 

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

2.8.5 AES-CBC

AES-CBC, denoted CKM_AES_CBC, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on NIST’s Advanced Encryption Standard and cipher-block chaining mode.

It has a parameter, a 16-byte initialization vector.

This mechanism can wrap and unwrap any secret key.  Of course, a particular token may not be able to wrap/unwrap every secret key that it supports.  For wrapping, the mechanism encrypts the value of the CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus one null bytes so that the resulting length is a multiple of the block size. The output data is the same length as the padded input data. It does not wrap the key type, key length, or any other information about the key; the application must convey these separately.

For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the CKA_VALUE_LEN attribute of the template.  The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.

Constraints on key types and the length of data are summarized in the following table:

Table 49, AES-CBC: Key And Data Length

Function

Key type

Input length

Output length

Comments

C_Encrypt

AES

multiple of block size

same as input length

no final part

C_Decrypt

AES

multiple of block size

same as input length

no final part

C_WrapKey

AES

any

input length rounded up to multiple of the block size

 

C_UnwrapKey

AES

multiple of block size

determined by type of key being unwrapped or CKA_VALUE_LEN

 

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

2.8.6 AES-CBC with PKCS padding

AES-CBC with PKCS padding, denoted CKM_AES_CBC_PAD, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on NIST’s Advanced Encryption Standard; cipher-block chaining mode; and the block cipher padding method detailed in PKCS #7.

It has a parameter, a 16-byte initialization vector.

The PKCS padding in this mechanism allows the length of the plaintext value to be recovered from the ciphertext value.  Therefore, when unwrapping keys with this mechanism, no value should be specified for the CKA_VALUE_LEN attribute.

In addition to being able to wrap and unwrap secret keys, this mechanism can wrap and unwrap RSA, Diffie-Hellman, X9.42 Diffie-Hellman, EC (also related to ECDSA) and DSA private keys (see Section 2.5 for details).  The entries in the table below for data length constraints when wrapping and unwrapping keys do not apply to wrapping and unwrapping private keys.

Constraints on key types and the length of data are summarized in the following table:

Table 50, AES-CBC with PKCS Padding: Key And Data Length

Function

Key type

Input length

Output length

C_Encrypt

AES

any

input length rounded up to multiple of the block size

C_Decrypt

AES

multiple of block size

between 1 and block size bytes shorter than input length

C_WrapKey

AES

any

input length rounded up to multiple of the block size

C_UnwrapKey

AES

multiple of block size

between 1 and block length bytes shorter than input length

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

2.8.7 AES-OFB

AES-OFB, denoted CKM_AES_OFB. It is a mechanism for single and multiple-part encryption and decryption with AES. AES-OFB mode is described in [NIST sp800-38a].

It has a parameter, an initialization vector for this mode. The initialization vector has the same length as the block size.

Constraints on key types and the length of data are summarized in the following table:

Table 51, AES-OFB: Key And Data Length

Function

Key type

Input length

Output length

Comments

C_Encrypt

AES

any

same as input length

no final part

C_Decrypt

AES

any

same as input length

no final part

For this mechanism the CK_MECHANISM_INFO structure is as specified for CBC mode.

2.8.8 AES-CFB

Cipher AES has a cipher feedback mode, AES-CFB, denoted CKM_AES_CFB8, CKM_AES_CFB64, and CKM_AES_CFB128. It is a mechanism for single and multiple-part encryption and decryption with AES. AES-OFB mode is described [NIST sp800-38a].

It has a parameter, an initialization vector for this mode. The initialization vector has the same length as the block size.

Constraints on key types and the length of data are summarized in the following table:

Table 52, AES-CFB: Key And Data Length

Function

Key type

Input length

Output length

Comments

C_Encrypt

AES

any

same as input length

no final part

C_Decrypt

AES

any

same as input length

no final part

For this mechanism the CK_MECHANISM_INFO structure is as specified for CBC mode.

2.8.9 General-length AES-MAC

General-length AES-MAC, denoted CKM_AES_MAC_GENERAL, is a mechanism for single- and multiple-part signatures and verification, based on NIST Advanced Encryption Standard as defined in FIPS PUB 197 and data authentication as defined in FIPS PUB 113.

It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length desired from the mechanism.

The output bytes from this mechanism are taken from the start of the final AES cipher block produced in the MACing process.

Constraints on key types and the length of data are summarized in the following table:

Table 53, General-length AES-MAC: Key And Data Length

Function

Key type

Data length

Signature length

C_Sign

AES

any

0-block size, as specified in parameters

C_Verify

AES

any

0-block size, as specified in parameters

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

2.8.10 AES-MAC

AES-MAC, denoted by CKM_AES_MAC, is a special case of the general-length AES-MAC mechanism. AES-MAC always produces and verifies MACs that are half the block size in length.

It does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 54, 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)

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

2.8.11 AES-XCBC-MAC

AES-XCBC-MAC, denoted CKM_AES_XCBC_MAC, is a mechanism for single and multiple part signatures and verification; based on NIST’s Advanced Encryption Standard and [RFC 3566].

It does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 55, 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

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

2.8.12 AES-XCBC-MAC-96

AES-XCBC-MAC-96, denoted CKM_AES_XCBC_MAC-96, is a mechanism for single and multiple part signatures and verification; based on NIST’s Advanced Encryption Standard and [RFC 3566].

It does not have a parameter.

Constraints on key types and the length of data are summarized in the following table:

Table 56, 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

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

 

2.9 AES with Counter

Table 57, AES with Counter Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

CKM_AES_CTR

ü

 

 

 

 

ü

 

2.9.1 Definitions

Mechanisms:

CKM_AES_CTR                    

2.9.2 AES with Counter mechanism parameters

¨      CK_AES_CTR_PARAMS; CK_AES_CTR_PARAMS_PTR

CK_AES_CTR_PARAMS is a structure that provides the parameters to the CKM_AES_CTR mechanism.  It is defined as follows:

typedef struct CK_AES_CTR_PARAMS {

        CK_ULONG ulCounterBits;

        CK_BYTE cb[16];

} CK_AES_CTR_PARAMS;

 

ulCounterBits specifies the number of bits in the counter block (cb) that shall be incremented. This number  shall be such that 0 < ulCounterBits <= 128. For any values outside this range the mechanism shall return CKR_MECHANISM_PARAM_INVALID.

It's up to the caller to initialize all of the bits in the counter block including the counter bits. The counter bits are the least significant bits of the counter block (cb). They are a big-endian value usually starting with 1. The rest of ‘cb’ is for the nonce, and maybe an optional IV.

E.g. as defined in [RFC 3686]:

    0                   1                   2                   3
    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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                            Nonce                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                  Initialization Vector (IV)                   |
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                         Block Counter                         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

 

This construction permits each packet to consist of up to 232-1 blocks  =  4,294,967,295 blocks = 68,719,476,720 octets.

CK_AES_CTR_PARAMS_PTR is a pointer to a CK_AES_CTR_PARAMS.

2.9.3 AES with Counter Encryption / Decryption

Generic AES counter mode is described in NIST Special Publication 800-38A and in RFC 3686. These describe encryption using a counter block which may include a nonce to guarantee uniqueness of the counter block. Since the nonce is not incremented, the mechanism parameter must specify the number of counter bits in the counter block.

The block counter is incremented by 1 after each block of plaintext is processed. There is no support for any other increment functions in this mechanism.

If an attempt to encrypt/decrypt is made which will cause an overflow of the counter block’s counter bits, then the mechanism shall return CKR_DATA_LEN_RANGE. Note that the mechanism should allow the final post increment of the counter to overflow (if it implements it this way) but not allow any further processing after this point. E.g. if ulCounterBits = 2 and the counter bits start as 1 then only 3 blocks of data can be processed.

 

2.10 AES CBC with Cipher Text Stealing CTS

Ref [NIST AES CTS]

This mode allows unpadded data that has length that is not a multiple of the block size to be encrypted to the same length of cipher text.

Table 58, AES CBC with Cipher Text Stealing CTS Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

CKM_AES_CTS

ü

 

 

 

 

ü

 

2.10.1 Definitions

Mechanisms:

CKM_AES_CTS                    

2.10.2 AES CTS mechanism parameters

It has a parameter, a 16-byte initialization vector.

Table 59, AES-CTS: Key And Data Length

Function

Key type

Input length

Output length

Comments

C_Encrypt

AES

Any, ≥ block size (16 bytes)

same as input length

no final part

C_Decrypt

AES

any, ≥ block size (16 bytes)

same as input length

no final part

2.11 Additional AES Mechanisms

Table 60, Additional AES Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

CKM_AES_GCM

ü

 

 

 

 

ü

 

CKM_AES_CCM

ü

 

 

 

 

ü

 

CKM_AES_GMAC

 

ü

 

 

 

 

ü

 

2.11.1 Definitions

Mechanisms:

CKM_AES_GCM

CKM_AES_CCM

CKM_AES_GMAC

 

2.12 AES-GCM Authenticated Encryption / Decryption

Generic GCM mode is described in [GCM]. To set up for AES-GCM use the following process, where K (key) and AAD (additional authenticated data) are as described in [GCM].

Encrypt:

Decrypt:

In pIv the least significant bit of the initialization vector is the rightmost bit. ulIvLen is the length of the initialization vector in bytes.

The tag is appended to the cipher text and the least significant bit of the tag is the rightmost bit and the tag bits are the rightmost ulTagBits bits.

The key type for K must be compatible with CKM_AES_ECB and the C_EncryptInit/C_DecryptInit calls shall behave, with respect to K, as if they were called directly with CKM_AES_ECB, K and NULL parameters.

2.12.1 AES-CCM authenticated Encryption / Decryption

For IPsec (RFC 4309) and also for use in ZFS encryption.  Generic CCM mode is described in [RFC 3610].

To set up for AES-CCM use the following process, where K (key), nonce and additional authenticated data are as described in [RFC 3610].

Encrypt:

Decrypt:

The key type for K must be compatible with CKM_AES_ECB and the C_EncryptInit/C_DecryptInit calls shall behave, with respect to K, as if they were called directly with CKM_AES_ECB, K and NULL parameters.

2.12.2 AES-GMAC

AES-GMAC, denoted CKM_AES_GMAC, is a mechanism for single and multiple-part signatures and verification.  It is described in NIST Special Publication 800-38D [GMAC].  GMAC is a special case of GCM that authenticates only the Additional Authenticated Data (AAD) part of the GCM mechanism parameters.  When HMAC is used with C_Sign or C_Verify, pData points to the AAD.  HMAC does not use plaintext or ciphertext.

The signature produced by HMAC, also referred to as a Tag, is 16 bytes long.

Its single mechanism parameter is a 12 byte initialization vector (IV).

Constraints on key types and the length of data are summarized in the following table:

Table 61, AES-GMAC: Key And Data Length

Function

Key type

Data length

Signature length

C_Sign

CKK_AES

< 2^64

16 bytes

C_Verify

CKK_AES

< 2^64

16 bytes

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

2.12.3 AES GCM and CCM Mechanism parameters

¨      CK_GCM_PARAMS; CK_GCM_PARAMS_PTR

CK_GCM_PARAMS is a structure that provides the parameters to the CKM_AES_GCM mechanism.  It is defined as follows:

typedef struct CK_GCM_PARAMS {

  CK_BYTE_PTR pIv;

  CK_ULONG ulIvLen;

  CK_BYTE_PTR pAAD;

  CK_ULONG ulAADLen;

  CK_ULONG ulTagBits;

} CK_GCM_PARAMS;

The fields of the structure have the following meanings:

                                            pIv       pointer to initialization vector

                                      ulIvLen       length of initialization vector in bytes. The length of the initialization vector can be any number between 1 and 256. 96-bit (12 byte) IV values can be processed more efficiently, so that length is recommended for situations in which efficiency is critical.

                                        pAAD       pointer to additional authentication data. This data is authenticated but not encrypted.

                                  ulAADLen       length of pAAD in bytes.

                                  ulTagBits       length of authentication tag (output following cipher text) in bits. Can be any value between 0 and 128.                              

CK_GCM_PARAMS_PTR is a pointer to a CK_GCM_PARAMS.

¨      CK_CCM_PARAMS; CK_CCM_PARAMS_PTR

CK_CCM_PARAMS is a structure that provides the parameters to the CKM_AES_CCM mechanism.  It is defined as follows:

typedef struct CK_CCM_PARAMS {

   CK_ULONG ulDataLen; /*plaintext or ciphertext*/

   CK_BYTE_PTR pNonce;

   CK_ULONG ulNonceLen;

   CK_BYTE_PTR pAAD;

   CK_ULONG ulAADLen;

   CK_ULONG ulMACLen;

} CK_CCM_PARAMS;

The fields of the structure have the following meanings, where L is the size in bytes of the data length’s length (2 < L < 8):

                                  ulDataLen       length of the data where 0 <= ulDataLen < 28L.

                                     pNonce       the nonce.

                               ulNonceLen       length of pNonce (<= 15-L) in bytes.

                                        pAAD       Additional authentication data. This data is authenticated but not encrypted.

                                  ulAADLen       length of pAuthData in bytes.

                                 ulMACLen       length of the MAC (output following cipher text) in bytes. Valid values are 4, 6, 8, 10, 12, 14, and 16.

CK_CCM_PARAMS_PTR is a pointer to a CK_CCM_PARAMS.

2.12.4 AES-GCM authenticated Encryption / Decryption

Generic GCM mode is described in [GCM]. To set up for AES-GCM use the following process, where K (key) and AAD (additional authenticated data) are as described in [GCM].

Encrypt:

Decrypt:

In pIv the least significant bit of the initialization vector is the rightmost bit. ulIvLen is the length of the initialization vector in bytes.

The tag is appended to the cipher text and the least significant bit of the tag is the rightmost bit and the tag bits are the rightmost ulTagBits bits.

The key type for K must be compatible with CKM_AES_ECB and the C_EncryptInit/C_DecryptInit calls shall behave, with respect to K, as if they were called directly with CKM_AES_ECB, K and NULL parameters.

2.12.5 AES-CCM authenticated Encryption / Decryption

For IPsec (RFC 4309) and also for use in ZFS encryption. Generic CCM mode is described in [RFC 3610].

To set up for AES-CCM use the following process, where K (key), nonce and additional authenticated data are as described in [RFC 3610].

Encrypt:

Decrypt:

The key type for K must be compatible with CKM_AES_ECB and the C_EncryptInit/C_DecryptInit calls shall behave, with respect to K, as if they were called directly with CKM_AES_ECB, K and NULL parameters.

2.13 AES CMAC

Table 62, Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

CKM_AES_CMAC_GENERAL

 

ü

 

 

 

 

 

CKM_AES_CMAC

 

ü

 

 

 

 

 

1 SR = SignRecover, VR = VerifyRecover.

2.13.1 Definitions

Mechanisms:

CKM_AES_CMAC_GENERAL                   

CKM_AES_CMAC                   

2.13.2 Mechanism parameters

CKM_AES_CMAC_GENERAL uses the existing CK_MAC_GENERAL_PARAMS structure. CKM_AES_CMAC does not use a mechanism parameter.

2.13.3 General-length AES-CMAC

General-length AES-CMAC, denoted CKM_AES_CMAC_GENERAL, is a mechanism for single- and multiple-part signatures and verification, based on [NIST SP800-38B] and [RFC 4493].

It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length desired from the mechanism.

The output bytes from this mechanism are taken from the start of the final AES cipher block produced in the MACing process.

Constraints on key types and the length of data are summarized in the following table:

Table 63, General-length AES-CMAC: Key And Data Length

Function

Key type

Data length

Signature length

C_Sign

CKK_AES

any

0-block size, as specified in parameters

C_Verify

CKK_AES

any

0-block size, as specified in parameters

References [NIST SP800-38B] and [RFC 4493] recommend that the output MAC is not truncated to less than 64 bits. The MAC length must be specified before the communication starts, and must not be changed during the lifetime of the key. It is the caller’s responsibility to follow these rules.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

2.13.4 AES-CMAC

AES-CMAC, denoted CKM_AES_CMAC, is a special case of the general-length AES-CMAC mechanism. AES-MAC always produces and verifies MACs that are a full block size in length, the default output length specified by [RFC 4493].

Constraints on key types and the length of data are summarized in the following table:

Table 64, AES-CMAC: Key And Data Length

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)

References [NIST SP800-38B] and [RFC 4493] recommend that the output MAC is not truncated to less than 64 bits. The MAC length must be specified before the communication starts, and must not be changed during the lifetime of the key. It is the caller’s responsibility to follow these rules.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.

2.14 AES Key Wrap

Table 65, AES Key Wrap Mechanisms vs. Functions

 

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

CKM_AES_KEY_WRAP

 

 

 

 

 

ü

 

CKM_AES_KEY_WRAP_PAD

ü

 

 

 

 

 

 

1SR = SignRecover, VR = VerifyRecover

2.14.1 Definitions

Mechanisms:

CKM_AES_KEY_WRAP

CKM_AES_KEY_WRAP_PAD

2.14.2 AES Key Wrap Mechanism parameters

The mechanisms will accept an optional mechanism parameter as the Initialization vector which, if present, must be a fixed size array of 8 bytes, and, if NULL, will use the default initial value defined in Section 2.2.3.1 of [AES KEYWRAP].

The type of this parameter is CK_BYTE_PTR and the pointer points to the array of 8 bytes to be used as the initial value. The length shall be either 0 and the pointer NULL, or 8, and the pointer non-NULL.

2.14.3 AES Key Wrap

The mechanisms support only single-part operations, single part wrapping and unwrapping, and single-part encryption and decryption.

The CKM_AES_KEY_WRAP mechanism can wrap a key of any length. A key whose length is not a multiple of the AES Key Wrap block size (8 bytes) will be zero padded to fit. The CKM_AES_KEY_WRAP mechanism can only encrypt a block of data whose size is an exact multiple of the AES Key Wrap algorithm block size.

The CKM_AES_KEY_WRAP_PAD mechanism can wrap a key or block of data of any length.  It does the usual padding of inputs (keys or data blocks) that are not multiples of the AES Key Wrap algorithm block size, always producing wrapped output that is larger than the input key/data to be wrapped. This padding is done by the token before being passed to the AES key wrap algorithm, which adds an 8 byte AES Key Wrap algorithm block of data.

2.15 Key derivation by data encryption – DES & AES

These mechanisms allow derivation of keys using the result of an encryption operation as the key value. They are for use with the C_DeriveKey function.

Table 66, Key derivation by data encryption Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

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

 

 

 

 

 

 

ü

2.15.1 Definitions

Mechanisms:

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

 

typedef struct CK_DES_CBC_ENCRYPT_DATA_PARAMS {

  CK_BYTE      iv[8];

  CK_BYTE_PTR  pData;

  CK_ULONG     length;

} CK_DES_CBC_ENCRYPT_DATA_PARAMS;

typedef CK_DES_CBC_ENCRYPT_DATA_PARAMS CK_PTR CK_DES_CBC_ENCRYPT_DATA_PARAMS_PTR;

 

typedef struct CK_AES_CBC_ENCRYPT_DATA_PARAMS {

  CK_BYTE      iv[16];

  CK_BYTE_PTR  pData;

  CK_ULONG     length;

} CK_AES_CBC_ENCRYPT_DATA_PARAMS;

typedef CK_AES_CBC_ENCRYPT_DATA_PARAMS CK_PTR

CK_AES_CBC_ENCRYPT_DATA_PARAMS_PTR;

2.15.2 Mechanism Parameters

Uses CK_KEY_DERIVATION_STRING_DATA as defined in section 2.31.2

Table 67, Mechanism Parameters

CKM_DES_ECB_ENCRYPT_DATA
CKM_DES3_ECB_ENCRYPT_DATA

Uses CK_KEY_DERIVATION_STRING_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

CKM_DES3_CBC_ENCRYPT_DATA

Uses CK_DES_CBC_ENCRYPT_DATA_PARAMS. 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.

2.15.3 Mechanism Description

The mechanisms will function by performing the encryption over the data provided using the base key. The resulting cipher text shall be used to create the key value of the resulting key. If not all the cipher text is used then the part discarded will be from the trailing end (least significant bytes) of the cipher text data. The derived key shall be defined by the attribute template supplied but constrained by the length of cipher text available for the key value and other normal PKCS11 derivation constraints.

Attribute template handling, attribute defaulting and key value preparation will operate as per the SHA-1 Key Derivation mechanism in section 2.18.5.

If the data is too short to make the requested key then the mechanism returns CKR_DATA_LEN_RANGE.

2.16 Double and Triple-length DES

Table 68, Double and Triple-Length DES Mechanisms vs. Functions

 

Functions

 

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

 

Digest

Gen.

 Key/

Key

Pair

Wrap

&

Unwrap

 

Derive

CKM_DES2_KEY_GEN

 

 

 

 

ü

 

 

CKM_DES3_KEY_GEN

 

 

 

 

ü

 

 

CKM_DES3_ECB

ü

 

 

 

 

ü

 

CKM_DES3_CBC

ü

 

 

 

 

ü

 

CKM_DES3_CBC_PAD

ü

 

 

 

 

ü

 

CKM_DES3_MAC_GENERAL

 

ü

 

 

 

 

 

CKM_DES3_MAC

 

ü

 

 

 

 

 

2.16.1 Definitions

This section defines the key type “CKK_DES2” and “CKK_DES3” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.

Mechanisms:

CKM_DES2_KEY_GEN              

CKM_DES3_KEY_GEN              

CKM_DES3_ECB                  

CKM_DES3_CBC                  

CKM_DES3_MAC                  

CKM_DES3_MAC_GENERAL          

CKM_DES3_CBC_PAD              

2.16.2 DES2 secret key objects

DES2 secret key objects (object class CKO_SECRET_KEY, key type CKK_DES2) hold double-length DES keys.  The following table defines the DES2 secret key object attributes, in addition to the common attributes defined for this object class:

Table 69, DES2 Secret Key Object Attributes

Attribute

Data type

Meaning

CKA_VALUE1,4,6,7

Byte array

Key value (always 16 bytes long)

- Refer to [PKCS #11-Base]  table 10 for footnotes

DES2 keys must always have their parity bits properly set as described in FIPS PUB 46-3 (i.e., each of the DES keys comprising a DES2 key must have its parity bits properly set).  Attempting to create or unwrap a DES2 key with incorrect parity will return an error.

The following is a sample template for creating a double-length DES secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;

CK_KEY_TYPE keyType = CKK_DES2;

CK_UTF8CHAR label[] = “A DES2 secret key object”;

CK_BYTE value[16] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_ENCRYPT, &true, sizeof(true)},

  {CKA_VALUE, value, sizeof(value)}

};

 

CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three bytes of the ECB encryption of a single block of null (0x00) bytes, using the default cipher associated with the key type of the secret key object.

2.16.3 DES3 secret key objects

DES3 secret key objects (object class CKO_SECRET_KEY, key type CKK_DES3) hold triple-length DES keys.  The following table defines the DES3 secret key object attributes, in addition to the common attributes defined for this object class:

Table 70, DES3 Secret Key Object Attributes

Attribute

Data type

Meaning

CKA_VALUE1,4,6,7

Byte array

Key value (always 24 bytes long)

- Refer to [PKCS #11-Base]  table 10 for footnotes

DES3 keys must always have their parity bits properly set as described in FIPS PUB 46-3 (i.e., each of the DES keys comprising a DES3 key must have its parity bits properly set).  Attempting to create or unwrap a DES3 key with incorrect parity will return an error.

The following is a sample template for creating a triple-length DES secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;

CK_KEY_TYPE keyType = CKK_DES3;

CK_UTF8CHAR label[] = “A DES3 secret key object”;

CK_BYTE value[24] = {...};

CK_BBOOL true = CK_TRUE;

CK_ATTRIBUTE template[] = {

  {CKA_CLASS, &class, sizeof(class)},

  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},

  {CKA_TOKEN, &true, sizeof(true)},

  {CKA_LABEL, label, sizeof(label)-1},

  {CKA_ENCRYPT, &true, sizeof(true)},

  {CKA_VALUE, value, sizeof(value)}

};

 

CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three bytes of the ECB encryption of a single block of null (0x00) bytes, using the default cipher associated with the key type of the secret key object.

2.16.4 Double-length DES key generation

The double-length DES key generation mechanism, denoted CKM_DES2_KEY_GEN, is a key generation mechanism for double-length DES keys.  The DES keys making up a double-length DES key both have their parity bits set properly, as specified in FIPS PUB 46-3.

It does not have a parameter.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key. Other attributes supported by the double-length DES key type (specifically, the flags indicating which functions the key supports) may be specified in the template for the key, or else are assigned default initial values.

Double-length DES keys can be used with all the same mechanisms as triple-DES keys: CKM_DES3_ECB, CKM_DES3_CBC, CKM_DES3_CBC_PAD, CKM_DES3_MAC_GENERAL, and CKM_DES3_MAC.  Triple-DES encryption with a double-length DES key is equivalent to encryption with a triple-length DES key with K1=K3 as specified in FIPS PUB 46-3.

When double-length DES keys are generated, it is token-dependent whether or not it is possible for either of the component DES keys to be “weak” or “semi-weak” keys.

2.16.5 Triple-length DES Order of Operations

Triple-length DES encryptions are carried out as specified in FIPS PUB 46-3: encrypt, decrypt, encrypt. Decryptions are carried out with the opposite three steps: decrypt, encrypt, decrypt. The mathematical representations of the encrypt and decrypt operations are as follows:

DES3-E({K1,K2,K3}, P) = E(K3, D(K2, E(K1, P)))

DES3-D({K1,K2,K3}, C) = D(K1, E(K2, D(K3, P)))