PKCS #11 Base Specification Version 3

pkcs11-spec-v3.1-wd04 Working Draft 04 2 June 2021 Standards Track Draft Copyright © OASIS Open 2021. All Rights Reserved. Page 1 of 426

PKCS #11 Specification Version 3.1

Working Draft 0304

4 2 March June 2021

Technical Committee: OASIS PKCS 11 TC

Chairs: Tony Cox ([email protected]), Cryptsoft Pty Ltd Robert Relyea ([email protected]), Red Hat

Editors: Dieter Bong ([email protected]), Utimaco IS GmbH Tony Cox ([email protected]), Cryptsoft Pty Ltd

Additional artifacts: This prose specification is one component of a Work Product that also includes:

PKCS #11 header files: https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/include/pkcs11-v3.0/

Related work: This specification replaces or supersedes:

PKCS #11 Cryptographic Token Interface Base Specification Version 3.0. Edited by Chris Zimman and Dieter Bong. Latest version: https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/pkcs11-base-v3.0.html.

This specification is related to:

PKCS #11 Cryptographic Token Interface Profiles Version 3.1. Edited by Tim Hudson. Latest stage. <URL>.

Abstract: This document defines data types, functions and other basic components of the PKCS #11 Cryptoki interface.

Status: This Working Draft (WD) has been produced by one or more TC Members; it has not yet been voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Draft.

This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. 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 TC's web page (https://www.oasis-open.org/committees/pkcs11/ipr.php).

Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.

URI patterns: Initial publication URI: https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.1/csprd01/pkcs11-base-v3.1-csprd01.docx Permanent "Latest version" URI: https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.1/pkcs11-base-v3.1.docx

https://www.oasis-open.org/committees/pkcs11/

mailto:[email protected]

https://cryptsoft.com/


http://www.redhat.com/


https://hsm.utimaco.com/


https://cryptsoft.com/

https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/include/pkcs11-v3.0/

https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/pkcs11-base-v3.0.html

https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/pkcs11-base-v3.0.html

https://www.oasis-open.org/policies-guidelines/oasis-defined-terms-2017-05-26#dWorkingDraft

https://www.oasis-open.org/policies-guidelines/tc-process#committeeDraft

https://www.oasis-open.org/policies-guidelines/tc-process#standApprovProcess

https://www.oasis-open.org/policies-guidelines/ipr#RF-on-RAND-Mode

https://www.oasis-open.org/policies-guidelines/ipr

https://www.oasis-open.org/committees/pkcs11/ipr.php


https://www.oasis-open.org/policies-guidelines/tc-process#wpComponentsCompLang


Citation format:

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

[PKCS11-Spec-v3.1]

PKCS #11 Cryptographic Token Interface Base Specification Version 3.1. Dieter Bong and Tony Cox.

<Date>. OASIS Standard. <URL> Latest stage: <URL>.

Copyright © OASIS Open 2020. 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.



Table of Contents

1 Introduction ......................................................................................................................................... 18

1.1 IPR Policy ......................................................................................................................................... 18

1.2 Terminology ...................................................................................................................................... 18

1.1 Definitions .................................................................................................................................. 18

1.2 Symbols and abbreviations........................................................................................................ 20

1.3 Normative References ............................................................................................................... 22

1.4 Non-Normative References ....................................................................................................... 25

2 Platform- and compiler-dependent directives for C or C++ ................................................................ 28

2.1 Structure packing .............................................................................................................................. 28

2.2 Pointer-related macros ..................................................................................................................... 28

3 General data types ............................................................................................................................. 30

3.1 General information .......................................................................................................................... 30

3.2 Slot and token types ......................................................................................................................... 31

3.3 Session types ................................................................................................................................... 36

3.4 Object types ...................................................................................................................................... 38

3.5 Data types for mechanisms .............................................................................................................. 42

3.6 Function types .................................................................................................................................. 44

3.7 Locking-related types ........................................................................................................................ 49

4 Objects ............................................................................................................................................... 53

4.1 Creating, modifying, and copying objects ......................................................................................... 54

4.1.1 Creating objects ........................................................................................................................ 54

4.1.2 Modifying objects ....................................................................................................................... 55

4.1.3 Copying objects ......................................................................................................................... 55

4.2 Common attributes ........................................................................................................................... 56

4.3 Hardware Feature Objects ................................................................................................................ 56

4.3.1 Definitions .................................................................................................................................. 56

4.3.2 Overview .................................................................................................................................... 56

4.3.3 Clock .......................................................................................................................................... 57 4.3.3.1 Definition ............................................................................................................................................ 57 4.3.3.2 Description ......................................................................................................................................... 57

4.3.4 Monotonic Counter Objects ....................................................................................................... 57 4.3.4.1 Definition ............................................................................................................................................ 57 4.3.4.2 Description ......................................................................................................................................... 57

4.3.5 User Interface Objects ............................................................................................................... 57 4.3.5.1 Definition ............................................................................................................................................ 57 4.3.5.2 Description ......................................................................................................................................... 58

4.4 Storage Objects ................................................................................................................................ 58

4.4.1 The CKA_UNIQUE_ID attribute ................................................................................................ 59

4.5 Data objects ...................................................................................................................................... 60

4.5.1 Definitions .................................................................................................................................. 60

4.5.2 Overview .................................................................................................................................... 60

4.6 Certificate objects ............................................................................................................................. 60

4.6.1 Definitions .................................................................................................................................. 60

4.6.2 Overview .................................................................................................................................... 60


4.6.3 X.509 public key certificate objects ........................................................................................... 61

4.6.4 WTLS public key certificate objects........................................................................................... 63

4.6.5 X.509 attribute certificate objects .............................................................................................. 64

4.7 Key objects ....................................................................................................................................... 65

4.7.1 Definitions .................................................................................................................................. 65

4.7.2 Overview .................................................................................................................................... 65

4.8 Public key objects ............................................................................................................................. 66

4.9 Private key objects ............................................................................................................................ 68

4.9.1 RSA private key objects .......................................................... Error! Bookmark not defined.70

4.10 Secret key objects ...................................................................................................................... 7071

4.11 Domain parameter objects.......................................................................................................... 7273

4.11.1 Definitions ............................................................................................................................ 7273

4.11.2 Overview .............................................................................................................................. 7273

4.12 Mechanism objects ..................................................................................................................... 7374

4.12.1 Definitions ............................................................................................................................ 7374

4.12.2 Overview .............................................................................................................................. 7374

4.13 Profile objects ............................................................................................................................. 7374

4.13.1 Definitions ............................................................................................................................ 7374

4.13.2 Overview .............................................................................................................................. 7374

5 Functions ............................................................................................................................................ 75

5.1 Function return values ...................................................................................................................... 78

5.1.1 Universal Cryptoki function return values .................................................................................. 79

5.1.2 Cryptoki function return values for functions that use a session handle ................................... 79

5.1.3 Cryptoki function return values for functions that use a token .................................................. 80

5.1.4 Special return value for application-supplied callbacks ............................................................ 80

5.1.5 Special return values for mutex-handling functions .................................................................. 80

5.1.6 All other Cryptoki function return values ................................................................................... 80

5.1.7 More on relative priorities of Cryptoki errors ............................................................................. 85

5.1.8 Error code “gotchas” .................................................................................................................. 86

5.2 Conventions for functions returning output in a variable-length buffer ............................................. 86

5.3 Disclaimer concerning sample code ................................................................................................. 87

5.4 General-purpose functions ............................................................................................................... 87

5.4.1 C_Initialize ................................................................................................................................. 87

5.4.2 C_Finalize .................................................................................................................................. 88

5.4.3 C_GetInfo .............................................................................................................................. 8988

5.4.4 C_GetFunctionList ..................................................................................................................... 89

5.4.5 C_GetInterfaceList .................................................................................................................... 90

5.4.6 C_GetInterface .......................................................................................................................... 91

5.5 Slot and token management functions ............................................................................................. 93

5.5.1 C_GetSlotList ............................................................................................................................ 93

5.5.2 C_GetSlotInfo ............................................................................................................................ 95

5.5.3 C_GetTokenInfo ........................................................................................................................ 95

5.5.4 C_WaitForSlotEvent .................................................................................................................. 96

5.5.5 C_GetMechanismList ................................................................................................................ 97

5.5.6 C_GetMechanismInfo ................................................................................................................ 98

5.5.7 C_InitToken ........................................................................................................................... 9998


5.5.8 C_InitPIN ................................................................................................................................. 100

5.5.9 C_SetPIN ................................................................................................................................. 101

5.6 Session management functions................................................................................................ 102101

5.6.1 C_OpenSession ...................................................................................................................... 102

5.6.2 C_CloseSession ...................................................................................................................... 103

5.6.3 C_CloseAllSessions ................................................................................................................ 104

5.6.4 C_GetSessionInfo ................................................................................................................... 104

5.6.5 C_SessionCancel .................................................................................................................... 105

5.6.6 C_GetOperationState .............................................................................................................. 106

5.6.7 C_SetOperationState .............................................................................................................. 107

5.6.8 C_Login ................................................................................................................................... 109

5.6.9 C_LoginUser............................................................................................................................ 110

5.6.10 C_Logout ............................................................................................................................... 111

5.7 Object management functions ........................................................................................................ 112

5.7.1 C_CreateObject ....................................................................................................................... 112

5.7.2 C_CopyObject ......................................................................................................................... 114

5.7.3 C_DestroyObject ..................................................................................................................... 116

5.7.4 C_GetObjectSize ..................................................................................................................... 116

5.7.5 C_GetAttributeValue ............................................................................................................... 117

5.7.6 C_SetAttributeValue ................................................................................................................ 119

5.7.7 C_FindObjectsInit .................................................................................................................... 120

5.7.8 C_FindObjects ......................................................................................................................... 121

5.7.9 C_FindObjectsFinal ................................................................................................................. 121

5.8 Encryption functions ....................................................................................................................... 122

5.8.1 C_EncryptInit ........................................................................................................................... 122

5.8.2 C_Encrypt ................................................................................................................................ 122

5.8.3 C_EncryptUpdate .................................................................................................................... 123

5.8.4 C_EncryptFinal ........................................................................................................................ 123

5.9 Message-based encryption functions ............................................................................................. 125

5.9.1 C_MessageEncryptInit ............................................................................................................ 125

5.9.2 C_EncryptMessage ................................................................................................................. 126

5.9.3 C_EncryptMessageBegin ........................................................................................................ 127

5.9.4 C_EncryptMessageNext .......................................................................................................... 127

5.9.5 C_ MessageEncryptFinal ........................................................................................................ 128

5.10 Decryption functions ..................................................................................................................... 130

5.10.1 C_DecryptInit ......................................................................................................................... 130

5.10.2 C_Decrypt.............................................................................................................................. 131

5.10.3 C_DecryptUpdate .................................................................................................................. 131

5.10.4 C_DecryptFinal ...................................................................................................................... 132

5.11 Message-based decryption functions ........................................................................................... 134

5.11.1 C_MessageDecryptInit .......................................................................................................... 134

5.11.2 C_DecryptMessage ............................................................................................................... 134

5.11.3 C_DecryptMessageBegin ...................................................................................................... 135

5.11.4 C_DecryptMessageNext ....................................................................................................... 136

5.11.5 C_MessageDecryptFinal ....................................................................................................... 136

5.12 Message digesting functions ........................................................................................................ 137


5.12.1 C_DigestInit ........................................................................................................................... 137

5.12.2 C_Digest ................................................................................................................................ 137

5.12.3 C_DigestUpdate .................................................................................................................... 138

5.12.4 C_DigestKey.......................................................................................................................... 138

5.12.5 C_DigestFinal ........................................................................................................................ 139

5.13 Signing and MACing functions...................................................................................................... 140

5.13.1 C_SignInit .............................................................................................................................. 140

5.13.2 C_Sign ................................................................................................................................... 140

5.13.3 C_SignUpdate ....................................................................................................................... 141

5.13.4 C_SignFinal ........................................................................................................................... 141

5.13.5 C_SignRecoverInit ................................................................................................................ 142

5.13.6 C_SignRecover ..................................................................................................................... 143

5.14 Message-based signing and MACing functions ........................................................................... 144

5.14.1 C_MessageSignInit ............................................................................................................... 144

5.14.2 C_SignMessage .................................................................................................................... 145

5.14.3 C_SignMessageBegin ........................................................................................................... 145

5.14.4 C_SignMessageNext ............................................................................................................. 146

5.14.5 C_MessageSignFinal ............................................................................................................ 147

5.15 Functions for verifying signatures and MACs ............................................................................... 147

5.15.1 C_VerifyInit ............................................................................................................................ 147

5.15.2 C_Verify ................................................................................................................................. 148

5.15.3 C_VerifyUpdate ..................................................................................................................... 148

5.15.4 C_VerifyFinal ......................................................................................................................... 149

5.15.5 C_VerifyRecoverInit .............................................................................................................. 149

5.15.6 C_VerifyRecover ................................................................................................................... 150

5.16 Message-based functions for verifying signatures and MACs ..................................................... 151

5.16.1 C_MessageVerifyInit ............................................................................................................. 151

5.16.2 C_VerifyMessage .................................................................................................................. 152

5.16.3 C_VerifyMessageBegin ......................................................................................................... 152

5.16.4 C_VerifyMessageNext ........................................................................................................... 153

5.16.5 C_MessageVerifyFinal .......................................................................................................... 154

5.17 Dual-function cryptographic functions .......................................................................................... 154

5.17.1 C_DigestEncryptUpdate ........................................................................................................ 154

5.17.2 C_DecryptDigestUpdate ........................................................................................................ 157

5.17.3 C_SignEncryptUpdate ........................................................................................................... 159

5.17.4 C_DecryptVerifyUpdate ......................................................................................................... 162

5.18 Key management functions .......................................................................................................... 165

5.18.1 C_GenerateKey ..................................................................................................................... 165

5.18.2 C_GenerateKeyPair .............................................................................................................. 166

5.18.3 C_WrapKey ........................................................................................................................... 168

5.18.4 C_UnwrapKey ....................................................................................................................... 169

5.18.5 C_DeriveKey ......................................................................................................................... 171

5.19 Random number generation functions ......................................................................................... 173

5.19.1 C_SeedRandom .................................................................................................................... 173

5.19.2 C_GenerateRandom ............................................................................................................. 173

5.20 Parallel function management functions ....................................................................................... 174


5.20.1 C_GetFunctionStatus ............................................................................................................ 174

5.20.2 C_CancelFunction ................................................................................................................. 174

5.21 Callback functions ......................................................................................................................... 174

5.21.1 Surrender callbacks ............................................................................................................... 174

5.21.2 Vendor-defined callbacks ...................................................................................................... 175

6 Mechanisms ..................................................................................................................................... 176

6.1 RSA ................................................................................................................................................. 176

6.1.1 Definitions ................................................................................................................................ 176

6.1.2 RSA public key objects ............................................................................................................ 177

6.1.3 RSA private key objects .......................................................................................................... 178

6.1.4 PKCS #1 RSA key pair generation ......................................................................................... 180

6.1.5 X9.31 RSA key pair generation ............................................................................................... 180

6.1.6 PKCS #1 v1.5 RSA ................................................................................................................. 181

6.1.7 PKCS #1 RSA OAEP mechanism parameters ....................................................................... 181

6.1.8 PKCS #1 RSA OAEP .............................................................................................................. 183

6.1.9 PKCS #1 RSA PSS mechanism parameters .......................................................................... 183

6.1.10 PKCS #1 RSA PSS ............................................................................................................... 184

6.1.11 ISO/IEC 9796 RSA ................................................................................................................ 184

6.1.12 X.509 (raw) RSA ................................................................................................................... 185

6.1.13 ANSI X9.31 RSA ................................................................................................................... 186

6.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 ................................................................................................................. 187

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

6.1.16 PKCS #1 RSA PSS signature with SHA-224 ........................................................................ 187

6.1.17 PKCS #1 RSA PSS signature with SHA-1, SHA-256, SHA-384 or SHA-512 ................. 188187

6.1.18 PKCS #1 v1.5 RSA signature with SHA3 .............................................................................. 188

6.1.19 PKCS #1 RSA PSS signature with SHA3 ............................................................................. 188

6.1.20 ANSI X9.31 RSA signature with SHA-1 ................................................................................ 188

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

6.1.22 TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP ...................................................................... 189

6.1.23 RSA AES KEY WRAP ........................................................................................................... 190

6.1.24 RSA AES KEY WRAP mechanism parameters .................................................................... 191

6.1.25 FIPS 186-4 ...................................................................................................................... 192191

6.2 DSA ........................................................................................................................................... 192191

6.2.1 Definitions ................................................................................................................................ 192

6.2.2 DSA public key objects ............................................................................................................ 193

6.2.3 DSA Key Restrictions .............................................................................................................. 194

6.2.4 DSA private key objects .......................................................................................................... 194

6.2.5 DSA domain parameter objects .............................................................................................. 195

6.2.6 DSA key pair generation ......................................................................................................... 196

6.2.7 DSA domain parameter generation ......................................................................................... 196

6.2.8 DSA probabilistic domain parameter generation..................................................................... 196

6.2.9 DSA Shawe-Taylor domain parameter generation ................................................................. 197

6.2.10 DSA base domain parameter generation .............................................................................. 197

6.2.11 DSA without hashing ............................................................................................................. 197

6.2.12 DSA with SHA-1 .................................................................................................................... 198


6.2.13 FIPS 186-4 ............................................................................................................................ 198

6.2.14 DSA with SHA-224 .......................................................................................................... 199198

6.2.15 DSA with SHA-256 ................................................................................................................ 199

6.2.16 DSA with SHA-384 ................................................................................................................ 199

6.2.17 DSA with SHA-512 ................................................................................................................ 200

6.2.18 DSA with SHA3-224 .............................................................................................................. 200

6.2.19 DSA with SHA3-256 .............................................................................................................. 201

6.2.20 DSA with SHA3-384 .............................................................................................................. 201

6.2.21 DSA with SHA3-512 .............................................................................................................. 201

6.3 Elliptic Curve ................................................................................................................................... 202

6.3.1 EC Signatures ......................................................................................................................... 204

6.3.2 Definitions ................................................................................................................................ 204

6.3.3 ECDSA public key objects ....................................................................................................... 205

6.3.4 Elliptic curve private key objects ............................................................................................. 206

6.3.5 Edwards Elliptic curve public key objects ................................................................................ 207

6.3.6 Edwards Elliptic curve private key objects .............................................................................. 208

6.3.7 Montgomery Elliptic curve public key objects .......................................................................... 209

6.3.8 Montgomery Elliptic curve private key objects ........................................................................ 210

6.3.9 Elliptic curve key pair generation............................................................................................. 211

6.3.10 Edwards Elliptic curve key pair generation ........................................................................... 212

6.3.11 Montgomery Elliptic curve key pair generation ..................................................................... 212

6.3.12 ECDSA without hashing ........................................................................................................ 213

6.3.13 ECDSA with hashing ............................................................................................................. 213

6.3.14 EdDSA ................................................................................................................................... 214

6.3.15 XEdDSA ................................................................................................................................ 214

6.3.16 EC mechanism parameters ................................................................................................... 215

6.3.17 Elliptic curve Diffie-Hellman key derivation ........................................................................... 220

6.3.18 Elliptic curve Diffie-Hellman with cofactor key derivation ...................................................... 220

6.3.19 Elliptic curve Menezes-Qu-Vanstone key derivation ............................................................. 221

6.3.20 ECDH AES KEY WRAP ........................................................................................................ 222

6.3.21 ECDH AES KEY WRAP mechanism parameters ................................................................. 223

6.3.22 FIPS 186-4 ............................................................................................................................ 224

6.4 Diffie-Hellman ................................................................................................................................. 224

6.4.1 Definitions ................................................................................................................................ 224

6.4.2 Diffie-Hellman public key objects ............................................................................................ 225

6.4.3 X9.42 Diffie-Hellman public key objects .................................................................................. 225

6.4.4 Diffie-Hellman private key objects ........................................................................................... 226

6.4.5 X9.42 Diffie-Hellman private key objects ................................................................................ 227

6.4.6 Diffie-Hellman domain parameter objects ............................................................................... 228

6.4.7 X9.42 Diffie-Hellman domain parameters objects ................................................................... 228

6.4.8 PKCS #3 Diffie-Hellman key pair generation .......................................................................... 229

6.4.9 PKCS #3 Diffie-Hellman domain parameter generation ......................................................... 230

6.4.10 PKCS #3 Diffie-Hellman key derivation ................................................................................. 230

6.4.11 X9.42 Diffie-Hellman mechanism parameters ....................................................................... 231

6.4.12 X9.42 Diffie-Hellman key pair generation .............................................................................. 233

6.4.13 X9.42 Diffie-Hellman domain parameter generation ............................................................. 234


6.4.14 X9.42 Diffie-Hellman key derivation ...................................................................................... 234

6.4.15 X9.42 Diffie-Hellman hybrid key derivation ........................................................................... 235

6.4.16 X9.42 Diffie-Hellman Menezes-Qu-Vanstone key derivation ................................................ 235

6.5 Extended Triple Diffie-Hellman (x3dh) ............................................................................................ 236

6.5.1 Definitions ................................................................................................................................ 236

6.5.2 Extended Triple Diffie-Hellman key objects ............................................................................ 236

6.5.3 Initiating an Extended Triple Diffie-Hellman key exchange ..................................................... 236

6.5.4 Responding to an Extended Triple Diffie-Hellman key exchange ........................................... 237

6.5.5 Extended Triple Diffie-Hellman parameters ............................................................................ 238

6.6 Double Ratchet ............................................................................................................................... 239

6.6.1 Definitions ................................................................................................................................ 239

6.6.2 Double Ratchet secret key objects .......................................................................................... 239

6.6.3 Double Ratchet key derivation ................................................................................................ 240

6.6.4 Double Ratchet Encryption mechanism .................................................................................. 241

6.6.5 Double Ratchet parameters .................................................................................................... 242

6.7 Wrapping/unwrapping private keys ................................................................................................ 242

6.8 Generic secret key .......................................................................................................................... 244

6.8.1 Definitions ................................................................................................................................ 245

6.8.2 Generic secret key objects ...................................................................................................... 245

6.8.3 Generic secret key generation ................................................................................................ 246

6.9 HMAC mechanisms ........................................................................................................................ 246

6.9.1 General block cipher mechanism parameters ......................................................................... 246

6.10 AES ............................................................................................................................................... 246

6.10.1 Definitions .............................................................................................................................. 247

6.10.2 AES secret key objects ......................................................................................................... 247

6.10.3 AES key generation ............................................................................................................... 248

6.10.4 AES-ECB ............................................................................................................................... 248

6.10.5 AES-CBC ............................................................................................................................... 249

6.10.6 AES-CBC with PKCS padding .............................................................................................. 249

6.10.7 AES-OFB ............................................................................................................................... 250

6.10.8 AES-CFB ............................................................................................................................... 250

6.10.9 General-length AES-MAC ..................................................................................................... 251

6.10.10 AES-MAC ............................................................................................................................ 251

6.10.11 AES-XCBC-MAC ................................................................................................................. 251

6.10.12 AES-XCBC-MAC-96 ............................................................................................................ 252

6.11 AES with Counter ......................................................................................................................... 252

6.11.1 Definitions .............................................................................................................................. 252

6.11.2 AES with Counter mechanism parameters ........................................................................... 252

6.11.3 AES with Counter Encryption / Decryption ............................................................................ 253

6.12 AES CBC with Cipher Text Stealing CTS ..................................................................................... 253

6.12.1 Definitions .............................................................................................................................. 253

6.12.2 AES CTS mechanism parameters ........................................................................................ 254

6.13 Additional AES Mechanisms ........................................................................................................ 254

6.13.1 Definitions .............................................................................................................................. 254

6.13.2 AES-GCM Authenticated Encryption / Decryption ................................................................ 254

6.13.3 AES-CCM authenticated Encryption / Decryption ................................................................. 256


6.13.4 AES-GMAC ........................................................................................................................... 258

6.13.5 AES GCM and CCM Mechanism parameters ................................................................. 259258

6.14 AES CMAC ................................................................................................................................... 261

6.14.1 Definitions .............................................................................................................................. 261

6.14.2 Mechanism parameters ................................................................................................... 262261

6.14.3 General-length AES-CMAC ................................................................................................... 262

6.14.4 AES-CMAC............................................................................................................................ 262

6.15 AES XTS ....................................................................................................................................... 262

6.15.1 Definitions .............................................................................................................................. 263

6.15.2 AES-XTS secret key objects ................................................................................................. 263

6.15.3 AES-XTS key generation ...................................................................................................... 263

6.15.4 AES-XTS ............................................................................................................................... 263

6.16 AES Key Wrap ........................................................................................................................ 264263

6.16.1 Definitions .............................................................................................................................. 264

6.16.2 AES Key Wrap Mechanism parameters ................................................................................ 264

6.16.3 AES Key Wrap ...................................................................................................................... 264

6.17 Key derivation by data encryption – DES & AES ......................................................................... 265

6.17.1 Definitions .............................................................................................................................. 265

6.17.2 Mechanism Parameters ........................................................................................................ 266

6.17.3 Mechanism Description ......................................................................................................... 266

6.18 Double and Triple-length DES ................................................................................................ 267266

6.18.1 Definitions .............................................................................................................................. 267

6.18.2 DES2 secret key objects ....................................................................................................... 267

6.18.3 DES3 secret key objects ....................................................................................................... 268

6.18.4 Double-length DES key generation ................................................................................. 269268

6.18.5 Triple-length DES Order of Operations ................................................................................. 269

6.18.6 Triple-length DES in CBC Mode ........................................................................................... 269

6.18.7 DES and Triple length DES in OFB Mode ............................................................................ 269

6.18.8 DES and Triple length DES in CFB Mode ............................................................................. 270

6.19 Double and Triple-length DES CMAC .......................................................................................... 270

6.19.1 Definitions .............................................................................................................................. 270

6.19.2 Mechanism parameters ................................................................................................... 271270

6.19.3 General-length DES3-MAC ................................................................................................... 271

6.19.4 DES3-CMAC ......................................................................................................................... 271

6.20 SHA-1 ........................................................................................................................................... 271

6.20.1 Definitions .............................................................................................................................. 272

6.20.2 SHA-1 digest ......................................................................................................................... 272

6.20.3 General-length SHA-1-HMAC ............................................................................................... 272

6.20.4 SHA-1-HMAC ........................................................................................................................ 273

6.20.5 SHA-1 key derivation ............................................................................................................. 273

6.20.6 SHA-1 HMAC key generation................................................................................................ 273

6.21 SHA-224 ....................................................................................................................................... 274

6.21.1 Definitions .............................................................................................................................. 274

6.21.2 SHA-224 digest ..................................................................................................................... 274

6.21.3 General-length SHA-224-HMAC ........................................................................................... 275

6.21.4 SHA-224-HMAC .................................................................................................................... 275


6.21.5 SHA-224 key derivation ......................................................................................................... 275

6.21.6 SHA-224 HMAC key generation............................................................................................ 275

6.22 SHA-256 ....................................................................................................................................... 276

6.22.1 Definitions .............................................................................................................................. 276

6.22.2 SHA-256 digest ..................................................................................................................... 276


6.22.4 SHA-256-HMAC .................................................................................................................... 277



6.23 SHA-384 ....................................................................................................................................... 277

6.23.1 Definitions .............................................................................................................................. 277

6.23.2 SHA-384 digest ..................................................................................................................... 278


6.23.4 SHA-384-HMAC .................................................................................................................... 278



6.24 SHA-512 ....................................................................................................................................... 279

6.24.1 Definitions .............................................................................................................................. 279

6.24.2 SHA-512 digest ..................................................................................................................... 279


6.24.4 SHA-512-HMAC .................................................................................................................... 280



6.25 SHA-512/224 ................................................................................................................................ 281

6.25.1 Definitions .............................................................................................................................. 281

6.25.2 SHA-512/224 digest .............................................................................................................. 281

6.25.3 General-length SHA-512/224-HMAC .................................................................................... 281

6.25.4 SHA-512/224-HMAC ............................................................................................................. 282

6.25.5 SHA-512/224 key derivation.................................................................................................. 282

6.25.6 SHA-512/224 HMAC key generation .................................................................................... 282

6.26 SHA-512/256 ................................................................................................................................ 282

6.26.1 Definitions .............................................................................................................................. 283

6.26.2 SHA-512/256 digest .............................................................................................................. 283

6.26.3 General-length SHA-512/256-HMAC .................................................................................... 283

6.26.4 SHA-512/256-HMAC ............................................................................................................. 284

6.26.5 SHA-512/256 key derivation.................................................................................................. 284

6.26.6 SHA-512/256 HMAC key generation .................................................................................... 284

6.27 SHA-512/t ..................................................................................................................................... 284

6.27.1 Definitions .............................................................................................................................. 285

6.27.2 SHA-512/t digest ................................................................................................................... 285

6.27.3 General-length SHA-512/t-HMAC ......................................................................................... 285

6.27.4 SHA-512/t-HMAC .................................................................................................................. 285

6.27.5 SHA-512/t key derivation ....................................................................................................... 285

6.27.6 SHA-512/t HMAC key generation ......................................................................................... 285

6.28 SHA3-224 ..................................................................................................................................... 286

6.28.1 Definitions .............................................................................................................................. 286


6.28.2 SHA3-224 digest ................................................................................................................... 286

6.28.3 General-length SHA3-224-HMAC ......................................................................................... 287

6.28.4 SHA3-224-HMAC .................................................................................................................. 287

6.28.5 SHA3-224 key derivation ....................................................................................................... 287

6.28.6 SHA3-224 HMAC key generation ......................................................................................... 287

6.29 SHA3-256 ..................................................................................................................................... 287

6.29.1 Definitions .............................................................................................................................. 288

6.29.2 SHA3-256 digest ................................................................................................................... 288


6.29.4 SHA3-256-HMAC .................................................................................................................. 289



6.30 SHA3-384 ..................................................................................................................................... 289

6.30.1 Definitions .............................................................................................................................. 289

6.30.2 SHA3-384 digest ................................................................................................................... 290


6.30.4 SHA3-384-HMAC .................................................................................................................. 290



6.31 SHA3-512 ..................................................................................................................................... 291

6.31.1 Definitions .............................................................................................................................. 291

6.31.2 SHA3-512 digest ................................................................................................................... 291


6.31.4 SHA3-512-HMAC .................................................................................................................. 292



6.32 SHAKE .......................................................................................................................................... 293

6.32.1 Definitions .............................................................................................................................. 293

6.32.2 SHAKE Key Derivation .......................................................................................................... 293

6.33 Blake2b-160 .................................................................................................................................. 293

6.33.1 Definitions .............................................................................................................................. 294

6.33.2 BLAKE2B-160 digest ............................................................................................................. 294

6.33.3 General-length BLAKE2B-160-HMAC .................................................................................. 294

6.33.4 BLAKE2B-160-HMAC ........................................................................................................... 295

6.33.5 BLAKE2B-160 key derivation ................................................................................................ 295

6.33.6 BLAKE2B-160 HMAC key generation ................................................................................... 295

6.34 BLAKE2B-256 ............................................................................................................................... 295

6.34.1 Definitions .............................................................................................................................. 296

6.34.2 BLAKE2B-256 digest ............................................................................................................. 296


6.34.4 BLAKE2B-256-HMAC ........................................................................................................... 296



6.35 BLAKE2B-384 ............................................................................................................................... 297

6.35.1 Definitions .............................................................................................................................. 297

6.35.2 BLAKE2B-384 digest ............................................................................................................. 297



6.35.4 BLAKE2B-384-HMAC ........................................................................................................... 298



6.36 BLAKE2B-512 ......................................................................................................................... 298299

6.36.1 Definitions .............................................................................................................................. 299

6.36.2 BLAKE2B-512 digest ............................................................................................................. 299


6.36.4 BLAKE2B-512-HMAC ........................................................................................................... 300



6.37 PKCS #5 and PKCS #5-style password-based encryption (PBE)................................................ 300

6.37.1 Definitions .............................................................................................................................. 301

6.37.2 Password-based encryption/authentication mechanism parameters.................................... 301

6.37.3 PKCS #5 PBKDF2 key generation mechanism parameters ................................................. 301

6.37.4 PKCS #5 PBKD2 key generation .......................................................................................... 303

6.38 PKCS #12 password-based encryption/authentication mechanisms ........................................... 304

6.38.1 SHA-1-PBE for 3-key triple-DES-CBC .................................................................................. 304

6.38.2 SHA-1-PBE for 2-key triple-DES-CBC .................................................................................. 305

6.38.3 SHA-1-PBA for SHA-1-HMAC ............................................................................................... 305

6.39 SSL ............................................................................................................................................... 305

6.39.1 Definitions .............................................................................................................................. 306

6.39.2 SSL mechanism parameters ................................................................................................. 306

6.39.3 Pre-master key generation .................................................................................................... 308

6.39.4 Master key derivation ............................................................................................................ 308

6.39.5 Master key derivation for Diffie-Hellman ............................................................................... 309

6.39.6 Key and MAC derivation ........................................................................................................ 310

6.39.7 MD5 MACing in SSL 3.0 ....................................................................................................... 310

6.39.8 SHA-1 MACing in SSL 3.0 .................................................................................................... 311

6.40 TLS 1.2 Mechanisms .................................................................................................................... 311

6.40.1 Definitions .............................................................................................................................. 312

6.40.2 TLS 1.2 mechanism parameters ........................................................................................... 312

6.40.3 TLS MAC ............................................................................................................................... 315

6.40.4 Master key derivation ............................................................................................................ 315

6.40.5 Master key derivation for Diffie-Hellman ............................................................................... 316

6.40.6 Key and MAC derivation ........................................................................................................ 317

6.40.7 CKM_TLS12_KEY_SAFE_DERIVE ...................................................................................... 317

6.40.8 Generic Key Derivation using the TLS PRF .......................................................................... 318

6.40.9 Generic Key Derivation using the TLS12 PRF ...................................................................... 318

6.41 WTLS ............................................................................................................................................ 319

6.41.1 Definitions .............................................................................................................................. 319

6.41.2 WTLS mechanism parameters .............................................................................................. 320

6.41.3 Pre master secret key generation for RSA key exchange suite ............................................ 322

6.41.4 Master secret key derivation ................................................................................................. 323

6.41.5 Master secret key derivation for Diffie-Hellman and Elliptic Curve Cryptography ................ 323

6.41.6 WTLS PRF (pseudorandom function) ................................................................................... 324


6.41.7 Server Key and MAC derivation ............................................................................................ 324

6.41.8 Client key and MAC derivation .............................................................................................. 325

6.42 SP 800-108 Key Derivation .......................................................................................................... 326

6.42.1 Definitions .............................................................................................................................. 326


6.42.3 Counter Mode KDF ............................................................................................................... 332

6.42.4 Feedback Mode KDF ............................................................................................................ 332

6.42.5 Double Pipeline Mode KDF ................................................................................................... 333

6.42.6 Deriving Additional Keys ....................................................................................................... 334

6.42.7 Key Derivation Attribute Rules .............................................................................................. 335

6.42.8 Constructing PRF Input Data ................................................................................................ 335 6.42.8.1 Sample Counter Mode KDF ........................................................................................................... 335 6.42.8.2 Sample SCP03 Counter Mode KDF ............................................................................................... 336 6.42.8.3 Sample Feedback Mode KDF ........................................................................................................ 337 6.42.8.4 Sample Double-Pipeline Mode KDF .............................................................................................. 339

6.43 Miscellaneous simple key derivation mechanisms ....................................................................... 340

6.43.1 Definitions .............................................................................................................................. 340

6.43.2 Parameters for miscellaneous simple key derivation mechanisms ....................................... 340

6.43.3 Concatenation of a base key and another key ...................................................................... 341

6.43.4 Concatenation of a base key and data .................................................................................. 341

6.43.5 Concatenation of data and a base key .................................................................................. 342

6.43.6 XORing of a key and data ..................................................................................................... 343

6.43.7 Extraction of one key from another key ................................................................................. 344

6.44 CMS .............................................................................................................................................. 344

6.44.1 Definitions .............................................................................................................................. 345

6.44.2 CMS Signature Mechanism Objects ..................................................................................... 345

6.44.3 CMS mechanism parameters ................................................................................................ 345

6.44.4 CMS signatures ..................................................................................................................... 346

6.45 Blowfish......................................................................................................................................... 347

6.45.1 Definitions .............................................................................................................................. 348

6.45.2 BLOWFISH secret key objects .............................................................................................. 348

6.45.3 Blowfish key generation ........................................................................................................ 349

6.45.4 Blowfish-CBC ........................................................................................................................ 349

6.45.5 Blowfish-CBC with PKCS padding ........................................................................................ 349

6.46 Twofish .......................................................................................................................................... 350

6.46.1 Definitions .............................................................................................................................. 350

6.46.2 Twofish secret key objects .................................................................................................... 350

6.46.3 Twofish key generation ......................................................................................................... 351

6.46.4 Twofish -CBC ........................................................................................................................ 351

6.46.5 Twofish-CBC with PKCS padding ......................................................................................... 351

6.47 CAMELLIA .................................................................................................................................... 351

6.47.1 Definitions .............................................................................................................................. 352

6.47.2 Camellia secret key objects ................................................................................................... 352

6.47.3 Camellia key generation ........................................................................................................ 353

6.47.4 Camellia-ECB ........................................................................................................................ 353

6.47.5 Camellia-CBC ........................................................................................................................ 354

6.47.6 Camellia-CBC with PKCS padding ....................................................................................... 354


6.47.7 CAMELLIA with Counter mechanism parameters................................................................. 355

6.47.8 General-length Camellia-MAC .............................................................................................. 356

6.47.9 Camellia-MAC ....................................................................................................................... 356

6.48 Key derivation by data encryption - Camellia ............................................................................... 356

6.48.1 Definitions .............................................................................................................................. 356


6.49 ARIA .............................................................................................................................................. 357

6.49.1 Definitions .............................................................................................................................. 357

6.49.2 Aria secret key objects .......................................................................................................... 358

6.49.3 ARIA key generation ............................................................................................................. 358

6.49.4 ARIA-ECB .............................................................................................................................. 358

6.49.5 ARIA-CBC ............................................................................................................................. 359

6.49.6 ARIA-CBC with PKCS padding ............................................................................................. 360

6.49.7 General-length ARIA-MAC .................................................................................................... 360

6.49.8 ARIA-MAC ............................................................................................................................. 361

6.50 Key derivation by data encryption - ARIA ..................................................................................... 361

6.50.1 Definitions .............................................................................................................................. 361


6.51 SEED ............................................................................................................................................ 362

6.51.1 Definitions .............................................................................................................................. 363

6.51.2 SEED secret key objects ....................................................................................................... 363

6.51.3 SEED key generation ............................................................................................................ 364

6.51.4 SEED-ECB ............................................................................................................................ 364

6.51.5 SEED-CBC ............................................................................................................................ 364

6.51.6 SEED-CBC with PKCS padding ............................................................................................ 364

6.51.7 General-length SEED-MAC ................................................................................................... 364

6.51.8 SEED-MAC............................................................................................................................ 364

6.52 Key derivation by data encryption - SEED ................................................................................... 365

6.52.1 Definitions .............................................................................................................................. 365


6.53 OTP ............................................................................................................................................... 365

6.53.1 Usage overview ..................................................................................................................... 365

6.53.2 Case 1: Generation of OTP values ....................................................................................... 366

6.53.3 Case 2: Verification of provided OTP values ........................................................................ 367

6.53.4 Case 3: Generation of OTP keys .......................................................................................... 367

6.53.5 OTP objects ........................................................................................................................... 368 6.53.5.1 Key objects .................................................................................................................................... 368

6.53.6 OTP-related notifications ....................................................................................................... 371

6.53.7 OTP mechanisms .................................................................................................................. 371 6.53.7.1 OTP mechanism parameters ......................................................................................................... 371

6.53.8 RSA SecurID ......................................................................................................................... 375 6.53.8.1 RSA SecurID secret key objects .................................................................................................... 375 6.53.8.2 RSA SecurID key generation ......................................................................................................... 376 6.53.8.3 SecurID OTP generation and validation ......................................................................................... 376 6.53.8.4 Return values ................................................................................................................................. 377

6.53.9 OATH HOTP.......................................................................................................................... 377 6.53.9.1 OATH HOTP secret key objects .................................................................................................... 377


6.53.9.2 HOTP key generation .................................................................................................................... 378 6.53.9.3 HOTP OTP generation and validation ............................................................................................ 378

6.53.10 ActivIdentity ACTI ................................................................................................................ 378 6.53.10.1 ACTI secret key objects ............................................................................................................... 378 6.53.10.2 ACTI key generation .................................................................................................................... 379 6.53.10.3 ACTI OTP generation and validation ........................................................................................... 379

6.54 CT-KIP .......................................................................................................................................... 380

6.54.1 Principles of Operation .......................................................................................................... 380

6.54.2 Mechanisms .......................................................................................................................... 380

6.54.3 Definitions .............................................................................................................................. 381

6.54.4 CT-KIP Mechanism parameters ............................................................................................ 381

6.54.5 CT-KIP key derivation ........................................................................................................... 381

6.54.6 CT-KIP key wrap and key unwrap ......................................................................................... 382

6.54.7 CT-KIP signature generation ................................................................................................. 382

6.55 GOST 28147-89 ........................................................................................................................... 382

6.55.1 Definitions .............................................................................................................................. 382

6.55.2 GOST 28147-89 secret key objects ...................................................................................... 383

6.55.3 GOST 28147-89 domain parameter objects ......................................................................... 383

6.55.4 GOST 28147-89 key generation ........................................................................................... 384

6.55.5 GOST 28147-89-ECB ........................................................................................................... 385

6.55.6 GOST 28147-89 encryption mode except ECB .................................................................... 385

6.55.7 GOST 28147-89-MAC ........................................................................................................... 386

6.55.8 GOST 28147-89 keys wrapping/unwrapping with GOST 28147-89 ..................................... 386

6.56 GOST R 34.11-94 ......................................................................................................................... 387

6.56.1 Definitions .............................................................................................................................. 387

6.56.2 GOST R 34.11-94 domain parameter objects ....................................................................... 387

6.56.3 GOST R 34.11-94 digest ....................................................................................................... 388

6.56.4 GOST R 34.11-94 HMAC ...................................................................................................... 389

6.57 GOST R 34.10-2001 ..................................................................................................................... 389

6.57.1 Definitions .............................................................................................................................. 389

6.57.2 GOST R 34.10-2001 public key objects ................................................................................ 390

6.57.3 GOST R 34.10-2001 private key objects .............................................................................. 391

6.57.4 GOST R 34.10-2001 domain parameter objects................................................................... 392

6.57.5 GOST R 34.10-2001 mechanism parameters ....................................................................... 394

6.57.6 GOST R 34.10-2001 key pair generation .............................................................................. 395

6.57.7 GOST R 34.10-2001 without hashing ................................................................................... 395

6.57.8 GOST R 34.10-2001 with GOST R 34.11-94 ........................................................................ 396

6.57.9 GOST 28147-89 keys wrapping/unwrapping with GOST R 34.10-2001 .............................. 396

6.57.10 Common key derivation with assistance of GOST R 34.10-2001 keys .............................. 396

6.58 ChaCha20 ..................................................................................................................................... 397

6.58.1 Definitions .............................................................................................................................. 397

6.58.2 ChaCha20 secret key objects ............................................................................................... 397

6.58.3 ChaCha20 mechanism parameters ...................................................................................... 398

6.58.4 ChaCha20 key generation ..................................................................................................... 398

6.58.5 ChaCha20 mechanism .......................................................................................................... 398

6.59 Salsa20 ......................................................................................................................................... 399

6.59.1 Definitions .............................................................................................................................. 400


6.59.2 Salsa20 secret key objects .................................................................................................... 400

6.59.3 Salsa20 mechanism parameters ........................................................................................... 401

6.59.4 Salsa20 key generation ......................................................................................................... 401

6.59.5 Salsa20 mechanism .............................................................................................................. 401

6.60 Poly1305 ....................................................................................................................................... 402

6.60.1 Definitions .............................................................................................................................. 402

6.60.2 Poly1305 secret key objects .................................................................................................. 402

6.60.3 Poly1305 mechanism ............................................................................................................ 403

6.61 Chacha20/Poly1305 and Salsa20/Poly1305 Authenticated Encryption / Decryption................... 403

6.61.1 Definitions .............................................................................................................................. 404

6.61.2 Usage .................................................................................................................................... 404

6.61.3 ChaCha20/Poly1305 and Salsa20/Poly1305 Mechanism parameters ................................. 405

6.62 HKDF Mechanisms ....................................................................................................................... 406

6.62.1 Definitions ........................................................................................................................ 407406

6.62.2 HKDF mechanism parameters .............................................................................................. 407

6.62.3 HKDF derive .................................................................................................................... 408407

6.62.4 HKDF Data ............................................................................................................................ 408

6.62.5 HKDF Key gen ...................................................................................................................... 408

6.63 NULL Mechanism ......................................................................................................................... 408

6.63.1 Definitions .............................................................................................................................. 409

6.63.2 CKM_NULL mechanism parameters .................................................................................... 409

6.64 IKE Mechanisms ........................................................................................................................... 409

6.64.1 Definitions .............................................................................................................................. 409

6.64.2 IKE mechanism parameters .................................................................................................. 410

6.64.3 IKE PRF DERIVE .................................................................................................................. 412

6.64.4 IKEv1 PRF DERIVE .............................................................................................................. 413

6.64.5 IKEv2 PRF PLUS DERIVE .................................................................................................... 413

6.64.6 IKEv1 Extended Derive ......................................................................................................... 414

6.65 HSS ............................................................................................................................................... 414

6.65.1 Definitions ........................................................................................................................ 415414

6.65.2 HSS public key objects .......................................................................................................... 415

6.65.3 HSS private key objects .................................................................................................. 420417

6.65.4 HSS key pair generation ................................................................................................. 421418

6.65.5 HSS without hashing ....................................................................................................... 422418

7 PKCS #11 Implementation Conformance .................................................................................. 423419

7.1 PKCS#11 Consumer Implementation Conformance ................................................................ 423419

7.2 PKCS#11 Provider Implementation Conformance ................................................................... 423419

Appendix A. Acknowledgments ..................................................................................................... 424420

Appendix B. Manifest constants .................................................................................................... 425421

Appendix C. Revision History ........................................................................................................ 426422


1 Introduction 1

This document describes the basic PKCS#11 token interface and token behavior. 2

The PKCS#11 standard specifies an application programming interface (API), called “Cryptoki,” for 3 devices that hold cryptographic information and perform cryptographic functions. Cryptoki follows a 4 simple object based approach, addressing the goals of technology independence (any kind of device) and 5 resource sharing (multiple applications accessing multiple devices), presenting to applications a common, 6 logical view of the device called a “cryptographic token”. 7

This document specifies the data types and functions available to an application requiring cryptographic 8 services using the ANSI C programming language. The supplier of a Cryptoki library implementation 9 typically provides these data types and functions via ANSI C header files. Generic ANSI C header files 10 for Cryptoki are available from the PKCS#11 web page. This document and up-to-date errata for Cryptoki 11 will also be available from the same place. 12

Additional documents may provide a generic, language-independent Cryptoki interface and/or bindings 13 between Cryptoki and other programming languages. 14

Cryptoki isolates an application from the details of the cryptographic device. The application does not 15 have to change to interface to a different type of device or to run in a different environment; thus, the 16 application is portable. How Cryptoki provides this isolation is beyond the scope of this document, 17 although some conventions for the support of multiple types of device will be addressed here and 18 possibly in a separate document. 19

Details of cryptographic mechanisms (algorithms) may be found in the associated PKCS#11 Mechanisms 20 documents. 21

1.1 IPR Policy 22

This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode 23 chosen when the Technical Committee was established. For information on whether any patents have 24 been disclosed that may be essential to implementing this specification, and any offers of patent licensing 25 terms, please refer to the Intellectual Property Rights section of the TC's web page (https://www.oasis-26 open.org/committees/pkcs11/ipr.php). 27

1.2 Terminology 28

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 29 NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described 30 in [RFC2119] and [RFC8174] when, and only when, they appear in all capitals, as shown here. 31

1.1 Definitions 32

For the purposes of this standard, the following definitions apply: 33

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

API Application programming interface. 35

Application Any computer program that calls the Cryptoki interface. 36

ASN.1 Abstract Syntax Notation One, as defined in X.680. 37

Attribute A characteristic of an object. 38

BER Basic Encoding Rules, as defined in X.690. 39

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

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

https://www.oasis-open.org/policies-guidelines/ipr#RF-on-RAND-Mode




http://www.schneier.com/


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

Certificate A signed message binding a subject name and a public key, or a 44 subject name and a set of attributes. 45

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

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

CMS Cryptographic Message Syntax (see RFC 5652) 51

Cryptographic Device A device storing cryptographic information and possibly performing 52 cryptographic functions. May be implemented as a smart card, 53 smart disk, PCMCIA card, or with some other technology, including 54 software-only. 55

Cryptoki The Cryptographic Token Interface defined in this standard. 56

Cryptoki library A library that implements the functions specified in this standard. 57

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

DER Distinguished Encoding Rules, as defined in X.690. 60

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

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

EC Elliptic Curve 63

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

ECDH Elliptic Curve Diffie-Hellman. 65

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

ECMQV Elliptic Curve Menezes-Qu-Vanstone 67

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

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

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

IV Initialization Vector. 74

MAC Message Authentication Code. 75

Mechanism A process for implementing a cryptographic operation. 76

MQV Menezes-Qu-Vanstone 77

OAEP Optimal Asymmetric Encryption Padding for RSA. 78

Object An item that is stored on a token. May be data, a certificate, or a 79 key. 80

PIN Personal Identification Number. 81

PKCS Public-Key Cryptography Standards. 82

PRF Pseudo random function. 83

PTD Personal Trusted Device, as defined in MeT-PTD 84


RSA The RSA public-key cryptosystem. 85

Reader The means by which information is exchanged with a device. 86

Session A logical connection between an application and a token. 87

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

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

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



Slot A logical reader that potentially contains a token. 99

SSL The Secure Sockets Layer 3.0 protocol. 100

Subject Name The X.500 distinguished name of the entity to which a key is 101 assigned. 102

SO A Security Officer user. 103

TLS Transport Layer Security. 104

Token The logical view of a cryptographic device defined by Cryptoki. 105

User The person using an application that interfaces to Cryptoki. 106

UTF-8 Universal Character Set (UCS) transformation format (UTF) that 107 represents ISO 10646 and UNICODE strings with a variable number 108 of octets. 109

WTLS Wireless Transport Layer Security. 110

1.2 Symbols and abbreviations 111

The following symbols are used in this standard: 112

Table 1, Symbols 113

Symbol Definition

N/A Not applicable

R/O Read-only

R/W Read/write

The following prefixes are used in this standard: 114

Table 2, Prefixes 115

Prefix Description

C_ Function

CK_ Data type or general constant

CKA_ Attribute


Prefix Description

CKC_ Certificate type

CKD_ Key derivation function

CKF_ Bit flag

CKG_ Mask generation function

CKH_ Hardware feature type

CKK_ Key type

CKM_ Mechanism type

CKN_ Notification

CKO_ Object class

CKP_ Pseudo-random function

CKS_ Session state

CKR_ Return value

CKU_ User type

CKZ_ Salt/Encoding parameter source

h a handle

ul a CK_ULONG

p a pointer

pb a pointer to a CK_BYTE

ph a pointer to a handle

pul a pointer to a CK_ULONG

116

Cryptoki is based on ANSI C types, and defines the following data types: 117

118

/* an unsigned 8-bit value */ 119 typedef unsigned char CK_BYTE; 120 121 /* an unsigned 8-bit character */ 122 typedef CK_BYTE CK_CHAR; 123 124 /* an 8-bit UTF-8 character */ 125 typedef CK_BYTE CK_UTF8CHAR; 126 127 /* a BYTE-sized Boolean flag */ 128 typedef CK_BYTE CK_BBOOL; 129 130 /* an unsigned value, at least 32 bits long */ 131 typedef unsigned long int CK_ULONG; 132 133 /* a signed value, the same size as a CK_ULONG */ 134 typedef long int CK_LONG; 135 136 /* at least 32 bits; each bit is a Boolean flag */ 137 typedef CK_ULONG CK_FLAGS; 138 139

Cryptoki also uses pointers to some of these data types, as well as to the type void, which are 140 implementation-dependent. These pointer types are: 141

CK_BYTE_PTR /* Pointer to a CK_BYTE */ 142 CK_CHAR_PTR /* Pointer to a CK_CHAR */ 143 CK_UTF8CHAR_PTR /* Pointer to a CK_UTF8CHAR */ 144 CK_ULONG_PTR /* Pointer to a CK_ULONG */ 145


CK_VOID_PTR /* Pointer to a void */ 146 147

Cryptoki also defines a pointer to a CK_VOID_PTR, which is implementation-dependent: 148

CK_VOID_PTR_PTR /* Pointer to a CK_VOID_PTR */ 149 150

In addition, Cryptoki defines a C-style NULL pointer, which is distinct from any valid pointer: 151

NULL_PTR /* A NULL pointer */ 152 153

It follows that many of the data and pointer types will vary somewhat from one environment to another 154 (e.g., a CK_ULONG will sometimes be 32 bits, and sometimes perhaps 64 bits). However, these details 155 should not affect an application, assuming it is compiled with Cryptoki header files consistent with the 156 Cryptoki library to which the application is linked. 157

All numbers and values expressed in this document are decimal, unless they are preceded by “0x”, in 158 which case they are hexadecimal values. 159

The CK_CHAR data type holds characters from the following table, taken from ANSI C: 160

Table 3, Character Set 161

Category Characters

Letters A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z

Numbers 0 1 2 3 4 5 6 7 8 9

Graphic characters ! “ # % & ‘ ( ) * + , - . / : ; < = > ? [ \ ] ^ _ { | } ~

Blank character ‘ ‘

The CK_UTF8CHAR data type holds UTF-8 encoded Unicode characters as specified in RFC2279. UTF-162 8 allows internationalization while maintaining backward compatibility with the Local String definition of 163 PKCS #11 version 2.01. 164

In Cryptoki, the CK_BBOOL data type is a Boolean type that can be true or false. A zero value means 165 false, and a nonzero value means true. Similarly, an individual bit flag, CKF_..., can also be set (true) or 166 unset (false). For convenience, Cryptoki defines the following macros for use with values of type 167 CK_BBOOL: 168

#define CK_FALSE 0 169 #define CK_TRUE 1 170 171

For backwards compatibility, header files for this version of Cryptoki also define TRUE and FALSE as 172 (CK_DISABLE_TRUE_FALSE may be set by the application vendor): 173

#ifndef CK_DISABLE_TRUE_FALSE 174 #ifndef FALSE 175 #define FALSE CK_FALSE 176 #endif 177 178 #ifndef TRUE 179 #define TRUE CK_TRUE 180 #endif 181 #endif 182 183

1.3 Normative References 184

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

http://tools.ietf.org/html/rfc5794


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

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

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

[CHACHA] D. Bernstein, ChaCha, a variant of Salsa20, Jan 2008. 196 URL: http://cr.yp.to/chacha/chacha-20080128.pdf 197

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

[FIPS PUB 46-3] NIST. FIPS 46-3: Data Encryption Standard. October 1999. 200 URL: http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf 201

[FIPS PUB 81] NIST. FIPS 81: DES Modes of Operation. December 1980. 202 URL: http://csrc.nist.gov/publications/fips/fips81/fips81.htm 203

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

[FIPS SP 800-56A] NIST. Special Publication 800-56A Revision 2: Recommendation for Pair-Wise 206 Key Establishment Schemes Using Discrete Logarithm Cryptography, May 2013. 207 URL: http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar2.pdf 208

[FIPS SP 800-108] NIST. Special Publication 800-108 (Revised): Recommendation for Key 209 Derivation Using Pseudorandom Functions, October 2009. 210 URL: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-211 108.pdf 212

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

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

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

[NIST 802-208] NIST Special Publication 800-208: Recommendation for Stateful Hash-Based 219 Signature Schemes, October 2020. 220 URL: https://csrc.nist.gov/publications/detail/sp/800-208/final 221

[OAEP] M. Bellare, P. Rogaway. Optimal Asymmetric Encryption – How to Encrypt with 222 RSA. Nov 19, 1995. 223

[PKCS11-Hist] PKCS #11 Cryptographic Token Interface Historical Mechanisms Specification 224 Version 3.1. Edited by Dieter Bong and Tony Cox. Latest stage: <URL> 225

[PKCS11-Prof] PKCS #11 Cryptographic Token Interface Profiles Version 2.40. Edited by Tim 226 Hudson. 14 April 2015. OASIS Standard. Latest Stage: <URL>. 227

[PKCS #1] RSA Laboratories. RSA Cryptography Standard. v2.1, June 14, 2002. 228 URL: https://tools.ietf.org/html/rfc8017 229

[PKCS #3] RSA Laboratories. Diffie-Hellman Key-Agreement Standard. v1.4, November 230 1993. 231 URL: ftp://ftp.rsasecurity.com/pub/pkcs/doc/pkcs-3.doc 232

[PKCS #5] RSA Laboratories. Password-Based Encryption Standard. v2.0, March 25, 1999 233 URL: https://tools.ietf.org/html/rfc8018 234

[PKCS #7] RSA Laboratories. Cryptographic Message Syntax Standard. v1.5, November 235 1993 236 URL : https://tools.ietf.org/html/rfc2315 237

Formatted: German (Germany)

Field Code Changed



https://www.schneier.com/paper-blowfish-fse.html

http://www.ietf.org/rfc/rfc3713.txt

http://ieeexplore.ieee.org/xpl/articleDetails.jsp?arnumber=5389557

http://cr.yp.to/chacha/chacha-20080128.pdf

http://www-ee.stanford.edu/~hellman/publications/24.pdf

http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf

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

http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf

http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar2.pdf

https://tools.ietf.org/html/rfc6986



https://csrc.nist.gov/publications/detail/sp/800-208/final


[PKCS #8] RSA Laboratories. Private-Key Information Syntax Standard. v1.2, November 238 1993. 239 URL: https://tools.ietf.org/html/rfc5958 240

[PKCS #12] RSA Laboratories. Personal Information Exchange Syntax Standard. v1.0, 241 June 1999. 242 URL: https://tools.ietf.org/html/rfc7292 243

[POLY1305] D.J. Bernstein. The Poly1305-AES message-authentication code. Jan 2005. 244

URL: https://cr.yp.to/mac/poly1305-20050329.pdf 245

[RFC 2409] D. Harkins, D.Carrel. RFC 2409: The Internet Key Exchange (IKE), November 246 1998. 247 URL: https://tools.ietf.org/html/rfc2409 248

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

[RFC 2279] F. Yergeau. RFC 2279: UTF-8, a transformation format of ISO 10646 Alis 252 Technologies, January 1998. 253 URL: http://www.ietf.org/rfc/rfc2279.txt 254

[RFC 2534] Masinter, L., Wing, D., Mutz, A., and K. Holtman. RFC 2534: Media Features for 255 Display, Print, and Fax. March 1999. 256 URL: http://www.ietf.org/rfc/rfc2534.txt 257

[RFC 5652] R. Housley. RFC 5652: Cryptographic Message Syntax. Septmber 2009. URL: 258 http://www.ietf.org/rfc/rfc5652.txt 259

[RFC 5707] Rescorla, E., “The Keying Material Exporters for Transport Layer Security (TLS)”, 260 RFC 5705, March 2010. 261 URL: http://www.ietf.org/rfc/rfc5705.txt 262

[RFC 5996] C. Kaufman, P. Hoffman, Y. Nir, P. Eronen. RFC 5996: Internet Key Exchange 263 Protocol Version 2 (IKEv2), September 2010. 264 URL: https://tools.ietf.org/html/rfc5996 265

[RFC 8554] D. McGrew, m. Curcio, S. Fluhrer. RFC 8554: Leighton-Micali Hash-Based 266 Signatures, April 2019. 267 URL: https://tools.ietf.org/html/rfc8554 268

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

[SALSA] D. Bernstein, ChaCha, a variant of Salsa20, Jan 2008. 272 URL: http://cr.yp.to/chacha/chacha-20080128.pdf 273

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

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

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

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

[TLS12] [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) 286 Protocol Version 1.2", RFC 5246, August 2008. 287 URL: http://www.ietf.org/rfc/rfc5246.txt 288

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



https://cr.yp.to/mac/poly1305-20050329.pdf



http://ietf.org/rfc/rfc2279.txt





http://homes.esat.kuleuven.be/~bosselae/ripemd160.html

http://cr.yp.to/chacha/chacha-20080128.pdf

http://seed.kisa.or.kr/html/egovframework/iwt/ds/ko/ref/%5B2%5D_SEED+128_Specification_english_M.pdf

http://seed.kisa.or.kr/html/egovframework/iwt/ds/ko/ref/%5B2%5D_SEED+128_Specification_english_M.pdf

http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf

http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf

https://www.schneier.com/paper-twofish-paper.pdf


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

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

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

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

303

1.4 Non-Normative References 304

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

[AES KEYWRAP] National Institute of Standards and Technology, NIST Special Publication 800-307 38F, Recommendation for Block Cipher Modes of Operation: Methods for Key 308 Wrapping, December 2012, 309 http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf 310

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

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

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

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

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

[BRAINPOOL] ECC Brainpool Standard Curves and Curve Generation, v1.0, 19.10.2005 323 URL: http://www.ecc-brainpool.org 324

[CC/PP] W3C. Composite Capability/Preference Profiles (CC/PP): Structure and 325 Vocabularies. World Wide Web Consortium, January 2004. 326 URL: http://www.w3.org/TR/CCPP-struct-vocab/ 327

[CDPD] Ameritech Mobile Communications et al. Cellular Digital Packet Data System 328 Specifications: Part 406: Airlink Security. 1993. 329

[CT-KIP] RSA Laboratories. Cryptographic Token Key Initialization Protocol. Version 1.0, 330 December 2005. 331

[GCS-API] X/Open Company Ltd. Generic Cryptographic Service API (GCS-API), Base - 332 Draft 2. February 14, 1995. 333

[ISO/IEC 7816-1] ISO. Information Technology — Identification Cards — Integrated Circuit(s) with 334 Contacts — Part 1: Physical Characteristics. 1998. 335

[ISO/IEC 7816-4] ISO. Information Technology — Identification Cards — Integrated Circuit(s) with 336 Contacts — Part 4: Interindustry Commands for Interchange. 1995. 337

[ISO/IEC 8824-1] ISO. Information Technology-- Abstract Syntax Notation One (ASN.1): 338 Specification of Basic Notation. 2002. 339

[ISO/IEC 8825-1] ISO. Information Technology—ASN.1 Encoding Rules: Specification of Basic 340 Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished 341 Encoding Rules (DER). 2002. 342

http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html

http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf

http://webstore.ansi.org/RecordDetail.aspx?sku=X9.63-2011

http://www.w3.org/TR/CCPP-struct-vocab/


[ISO/IEC 9594-1] ISO. Information Technology — Open Systems Interconnection — The Directory: 343 Overview of Concepts, Models and Services. 2001. 344

[ISO/IEC 9594-8] ISO. Information Technology — Open Systems Interconnection — The Directory: 345 Public-key and Attribute Certificate Frameworks. 2001 346

[ISO/IEC 9796-2] ISO. Information Technology — Security Techniques — Digital Signature 347 Scheme Giving Message Recovery — Part 2: Integer factorization based 348 mechanisms. 2002. 349

[Java MIDP] Java Community Process. Mobile Information Device Profile for Java 2 Micro 350 Edition. November 2002. 351 URL: http://jcp.org/jsr/detail/118.jsp 352

[LEGIFRANCE] Avis relatif aux paramètres de courbes elliptiques définis par l'Etat français 353 (Publication of elliptic curve parameters by the French state) 354 URL: 355 https://www.legifrance.gouv.fr/affichTexte.do?cidTexte=JORFTEXT00002466881356 6 357

[MeT-PTD] MeT. MeT PTD Definition – Personal Trusted Device Definition, Version 1.0, 358 February 2003. 359 URL: http://www.mobiletransaction.org 360

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

[PCMCIA] Personal Computer Memory Card International Association. PC Card Standard, 366 Release 2.1,. July 1993. 367

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

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

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

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

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

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

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

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

[RFC 4357] V. Popov, I. Kurepkin, S. Leontiev “Additional Cryptographic Algorithms for Use 392 with GOST 28147-89, GOST R 34.10-94, GOST R 34.10-2001, and GOST R 393 34.11-94 Algorithms”, January 2006. 394 URL: http://www.ietf.org/rfc/rfc4357.txt 395

http://jcp.org/jsr/detail/118.jsp

http://www.mobiletransaction.org/

http://csrc.nist.gov/publications/nistpubs/800-38a/addendum-to-nist_sp800-38A.pdf

http://csrc.nist.gov/publications/nistpubs/800-38a/addendum-to-nist_sp800-38A.pdf







https://ftp.rfc-editor.org/in-notes/rfc4269.txt




[RFC 4490] S. Leontiev, Ed. G. Chudov, Ed. “Using the GOST 28147-89, GOST R 34.11-396 94,GOST R 34.10-94, and GOST R 34.10-2001 Algorithms with Cryptographic 397 Message Syntax (CMS)”, May 2006. 398 URL: http://www.ietf.org/rfc/rfc4490.txt 399

[RFC 4491] S. Leontiev, Ed., D. Shefanovski, Ed., “Using the GOST R 34.10-94, GOST R 400 34.10-2001, and GOST R 34.11-94 Algorithms with the Internet X.509 Public Key 401 Infrastructure Certificate and CRL Profile”, May 2006. 402 URL: http://www.ietf.org/rfc/rfc4491.txt 403

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

[RFC 5705] Rescorla, E., “The Keying Material Exporters for Transport Layer Security (TLS)”, 406 RFC 5705, March 2010. 407 URL: http://www.ietf.org/rfc/rfc5705.txt 408

[RFC 5869] H. Krawczyk, P. Eronen, “HMAC-based Extract-and-Expand Key Derivation 409 Function (HKDF)“, May 2010 410 URL: http://www.ietf.org/rfc/rfc5869.txt 411

[RFC 7539] Y Nir, A. Langley. RFC 7539: ChaCha20 and Poly1305 for IETF Protocols, May 412 2015 413 URL: https://tools.ietf.org/rfc/rfc7539.txt 414

[RFC 7748] Aboba et al, “Elliptic Curves for Security”, IETF RFC 7748, January 2016 415 URL: https://tools.ietf.org/html/rfc7748 416

[RFC 8032] Aboba et al, “Edwards-Curve Digital Signature Algorithm (EdDSA)”, IETF RFC 417 8032, January 2017 418 URL: https://tools.ietf.org/html/rfc8032 419

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

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

[WTLS] WAP. Wireless Transport Layer Security Version — WAP-261-WTLS-20010406-426 a. April 2001. 427 URL: http://openmobilealliance.org/tech/affiliates/wap/wap-261-wtls-20010406-428 a.pdf 429

[XEDDSA] The XEdDSA and VXEdDSA Signature Schemes - Revision 1, 2016-10-20, 430 Trevor Perrin (editor) 431 URL: https://signal.org/docs/specifications/xeddsa/ 432

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

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

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

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





https://tools.ietf.org/rfc/rfc7539.txt


http://openmobilealliance.org/tech/affiliates/wap/wap-261-wtls-20010406-a.pdf

http://openmobilealliance.org/tech/affiliates/wap/wap-261-wtls-20010406-a.pdf

https://signal.org/docs/specifications/xeddsa/


2 Platform- and compiler-dependent directives for C 444

or C++ 445

There is a large array of Cryptoki-related data types that are defined in the Cryptoki header files. Certain 446 packing and pointer-related aspects of these types are platform and compiler-dependent; these aspects 447 are therefore resolved on a platform-by-platform (or compiler-by-compiler) basis outside of the Cryptoki 448 header files by means of preprocessor directives. 449

This means that when writing C or C++ code, certain preprocessor directives MUST be issued before 450 including a Cryptoki header file. These directives are described in the remainder of this section. 451

Plattform specific implementation hints can be found in the pkcs11.h header file. 452

2.1 Structure packing 453

Cryptoki structures are packed to occupy as little space as is possible. Cryptoki structures SHALL be 454 packed with 1-byte alignment. 455

2.2 Pointer-related macros 456

Because different platforms and compilers have different ways of dealing with different types of pointers, 457 the following 6 macros SHALL be set outside the scope of Cryptoki: 458

CK_PTR 459

CK_PTR is the “indirection string” a given platform and compiler uses to make a pointer to an object. It is 460

used in the following fashion: 461

typedef CK_BYTE CK_PTR CK_BYTE_PTR; 462

CK_DECLARE_FUNCTION 463

CK_DECLARE_FUNCTION(returnType, name), when followed by a parentheses-enclosed 464

list of arguments and a semicolon, declares a Cryptoki API function in a Cryptoki library. returnType is 465

the return type of the function, and name is its name. It SHALL be used in the following fashion: 466

CK_DECLARE_FUNCTION(CK_RV, C_Initialize)( 467 CK_VOID_PTR pReserved 468 ); 469

CK_DECLARE_FUNCTION_POINTER 470

CK_DECLARE_FUNCTION_POINTER(returnType, name), when followed by a 471

parentheses-enclosed list of arguments and a semicolon, declares a variable or type which is a pointer to 472 a Cryptoki API function in a Cryptoki library. returnType is the return type of the function, and name is its 473 name. It SHALL be used in either of the following fashions to define a function pointer variable, 474 myC_Initialize, which can point to a C_Initialize function in a Cryptoki library (note that neither of the 475 following code snippets actually assigns a value to myC_Initialize): 476

CK_DECLARE_FUNCTION_POINTER(CK_RV, myC_Initialize)( 477 CK_VOID_PTR pReserved 478 ); 479 480

or: 481


typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, myC_InitializeType)( 482 CK_VOID_PTR pReserved 483 ); 484 myC_InitializeType myC_Initialize; 485

CK_CALLBACK_FUNCTION 486

CK_CALLBACK_FUNCTION(returnType, name), when followed by a parentheses-enclosed 487

list of arguments and a semicolon, declares a variable or type which is a pointer to an application callback 488 function that can be used by a Cryptoki API function in a Cryptoki library. returnType is the return type of 489 the function, and name is its name. It SHALL be used in either of the following fashions to define a 490 function pointer variable, myCallback, which can point to an application callback which takes arguments 491 args and returns a CK_RV (note that neither of the following code snippets actually assigns a value to 492 myCallback): 493

CK_CALLBACK_FUNCTION(CK_RV, myCallback)(args); 494 495

or: 496

typedef CK_CALLBACK_FUNCTION(CK_RV, myCallbackType)(args); 497 myCallbackType myCallback; 498

NULL_PTR 499

NULL_PTR is the value of a NULL pointer. In any ANSI C environment—and in many others as well—500

NULL_PTR SHALL be defined simply as 0. 501


3 General data types 502

The general Cryptoki data types are described in the following subsections. The data types for holding 503 parameters for various mechanisms, and the pointers to those parameters, are not described here; these 504 types are described with the information on the mechanisms themselves, in Section 12.6. 505

A C or C++ source file in a Cryptoki application or library can define all these types (the types described 506 here and the types that are specifically used for particular mechanism parameters) by including the top-507 level Cryptoki include file, pkcs11.h. pkcs11.h, in turn, includes the other Cryptoki include files, pkcs11t.h 508 and pkcs11f.h. A source file can also include just pkcs11t.h (instead of pkcs11.h); this defines most (but 509 not all) of the types specified here. 510

When including either of these header files, a source file MUST specify the preprocessor directives 511 indicated in Section 2. 512

3.1 General information 513

Cryptoki represents general information with the following types: 514

CK_VERSION; CK_VERSION_PTR 515

CK_VERSION is a structure that describes the version of a Cryptoki interface, a Cryptoki library, or an 516 SSL or TLS implementation, or the hardware or firmware version of a slot or token. It is defined as 517 follows: 518

typedef struct CK_VERSION { 519 CK_BYTE major; 520 CK_BYTE minor; 521 } CK_VERSION; 522 523

The fields of the structure have the following meanings: 524

major major version number (the integer portion of the version) 525

minor minor version number (the hundredths portion of the version) 526

Example: For version 1.0, major = 1 and minor = 0. For version 2.10, major = 2 and minor = 10. Table 527

4Table 4 below lists the major and minor version values for the officially published Cryptoki specifications. 528

Table 4, Major and minor version values for published Cryptoki specifications 529

Version major minor

1.0 0x01 0x00

2.01 0x02 0x01

2.10 0x02 0x0a

2.11 0x02 0x0b

2.20 0x02 0x14

2.30 0x02 0x1e

2.40 0x02 0x28

3.0 0x03 0x00

Minor revisions of the Cryptoki standard are always upwardly compatible within the same major version 530 number. 531

CK_VERSION_PTR is a pointer to a CK_VERSION. 532


CK_INFO; CK_INFO_PTR 533

CK_INFO provides general information about Cryptoki. It is defined as follows: 534

typedef struct CK_INFO { 535 CK_VERSION cryptokiVersion; 536 CK_UTF8CHAR manufacturerID[32]; 537 CK_FLAGS flags; 538 CK_UTF8CHAR libraryDescription[32]; 539 CK_VERSION libraryVersion; 540 } CK_INFO; 541 542


cryptokiVersion Cryptoki interface version number, for compatibility with future 544 revisions of this interface 545

manufacturerID ID of the Cryptoki library manufacturer. MUST be padded with the 546 blank character (‘ ‘). Should not be null-terminated. 547

flags bit flags reserved for future versions. MUST be zero for this version 548

libraryDescription character-string description of the library. MUST be padded with the 549 blank character (‘ ‘). Should not be null-terminated. 550

libraryVersion Cryptoki library version number 551

For libraries written to this document, the value of cryptokiVersion should match the version of this 552 specification; the value of libraryVersion is the version number of the library software itself. 553

CK_INFO_PTR is a pointer to a CK_INFO. 554

CK_NOTIFICATION 555

CK_NOTIFICATION holds the types of notifications that Cryptoki provides to an application. It is defined 556 as follows: 557

typedef CK_ULONG CK_NOTIFICATION; 558 559

For this version of Cryptoki, the following types of notifications are defined: 560

CKN_SURRENDER 561 562

The notifications have the following meanings: 563

CKN_SURRENDER Cryptoki is surrendering the execution of a function executing in a 564 session so that the application may perform other operations. After 565 performing any desired operations, the application should indicate 566 to Cryptoki whether to continue or cancel the function (see Section 567 5.21.1). 568

3.2 Slot and token types 569

Cryptoki represents slot and token information with the following types: 570

CK_SLOT_ID; CK_SLOT_ID_PTR 571

CK_SLOT_ID is a Cryptoki-assigned value that identifies a slot. It is defined as follows: 572

typedef CK_ULONG CK_SLOT_ID; 573 574


A list of CK_SLOT_IDs is returned by C_GetSlotList. A priori, any value of CK_SLOT_ID can be a valid 575 slot identifier—in particular, a system may have a slot identified by the value 0. It need not have such a 576 slot, however. 577

CK_SLOT_ID_PTR is a pointer to a CK_SLOT_ID. 578

CK_SLOT_INFO; CK_SLOT_INFO_PTR 579

CK_SLOT_INFO provides information about a slot. It is defined as follows: 580

typedef struct CK_SLOT_INFO { 581 CK_UTF8CHAR slotDescription[64]; 582 CK_UTF8CHAR manufacturerID[32]; 583 CK_FLAGS flags; 584 CK_VERSION hardwareVersion; 585 CK_VERSION firmwareVersion; 586 } CK_SLOT_INFO; 587 588


slotDescription character-string description of the slot. MUST be padded with the 590 blank character (‘ ‘). MUST NOT be null-terminated. 591

manufacturerID ID of the slot manufacturer. MUST be padded with the blank 592 character (‘ ‘). MUST NOT be null-terminated. 593

flags bits flags that provide capabilities of the slot. The flags are defined 594 below 595

hardwareVersion version number of the slot’s hardware 596

firmwareVersion version number of the slot’s firmware 597

The following table defines the flags field: 598

Table 5, Slot Information Flags 599

Bit Flag Mask Meaning

CKF_TOKEN_PRESENT 0x00000001 True if a token is present in the slot (e.g., a device is in the reader)

CKF_REMOVABLE_DEVICE 0x00000002 True if the reader supports removable devices

CKF_HW_SLOT 0x00000004 True if the slot is a hardware slot, as opposed to a software slot implementing a “soft token”

For a given slot, the value of the CKF_REMOVABLE_DEVICE flag never changes. In addition, if this flag 600 is not set for a given slot, then the CKF_TOKEN_PRESENT flag for that slot is always set. That is, if a 601

slot does not support a removable device, then that slot always has a token in it. 602

CK_SLOT_INFO_PTR is a pointer to a CK_SLOT_INFO. 603

CK_TOKEN_INFO; CK_TOKEN_INFO_PTR 604

CK_TOKEN_INFO provides information about a token. It is defined as follows: 605

typedef struct CK_TOKEN_INFO { 606 CK_UTF8CHAR label[32]; 607 CK_UTF8CHAR manufacturerID[32]; 608 CK_UTF8CHAR model[16]; 609



CK_CHAR serialNumber[16]; 610 CK_FLAGS flags; 611 CK_ULONG ulMaxSessionCount; 612 CK_ULONG ulSessionCount; 613 CK_ULONG ulMaxRwSessionCount; 614 CK_ULONG ulRwSessionCount; 615 CK_ULONG ulMaxPinLen; 616 CK_ULONG ulMinPinLen; 617 CK_ULONG ulTotalPublicMemory; 618 CK_ULONG ulFreePublicMemory; 619 CK_ULONG ulTotalPrivateMemory; 620 CK_ULONG ulFreePrivateMemory; 621 CK_VERSION hardwareVersion; 622 CK_VERSION firmwareVersion; 623 CK_CHAR utcTime[16]; 624 } CK_TOKEN_INFO; 625 626


label application-defined label, assigned during token initialization. MUST 628 be padded with the blank character (‘ ‘). MUST NOT be null-629 terminated. 630

manufacturerID ID of the device manufacturer. MUST be padded with the blank 631 character (‘ ‘). MUST NOT be null-terminated. 632

model model of the device. MUST be padded with the blank character (‘ ‘). 633 MUST NOT be null-terminated. 634

serialNumber character-string serial number of the device. MUST be padded with 635 the blank character (‘ ‘). MUST NOT be null-terminated. 636

flags bit flags indicating capabilities and status of the device as defined 637 below 638

ulMaxSessionCount maximum number of sessions that can be opened with the token at 639 one time by a single application (see CK_TOKEN_INFO Note 640 below) 641

ulSessionCount number of sessions that this application currently has open with the 642 token (see CK_TOKEN_INFO Note below) 643

ulMaxRwSessionCount maximum number of read/write sessions that can be opened with 644 the token at one time by a single application (see 645 CK_TOKEN_INFO Note below) 646

ulRwSessionCount number of read/write sessions that this application currently has 647 open with the token (see CK_TOKEN_INFO Note below) 648

ulMaxPinLen maximum length in bytes of the PIN 649

ulMinPinLen minimum length in bytes of the PIN 650

ulTotalPublicMemory the total amount of memory on the token in bytes in which public 651 objects may be stored (see CK_TOKEN_INFO Note below) 652

ulFreePublicMemory the amount of free (unused) memory on the token in bytes for public 653 objects (see CK_TOKEN_INFO Note below) 654

ulTotalPrivateMemory the total amount of memory on the token in bytes in which private 655 objects may be stored (see CK_TOKEN_INFO Note below) 656

ulFreePrivateMemory the amount of free (unused) memory on the token in bytes for 657 private objects (see CK_TOKEN_INFO Note below) 658

hardwareVersion version number of hardware 659


firmwareVersion version number of firmware 660

utcTime current time as a character-string of length 16, represented in the 661 format YYYYMMDDhhmmssxx (4 characters for the year; 2 662 characters each for the month, the day, the hour, the minute, and 663 the second; and 2 additional reserved ‘0’ characters). The value of 664 this field only makes sense for tokens equipped with a clock, as 665 indicated in the token information flags (see below) 666


Table 6, Token Information Flags 668


CKF_RNG 0x00000001 True if the token has its own random number generator

CKF_WRITE_PROTECTED 0x00000002 True if the token is write-protected (see below)

CKF_LOGIN_REQUIRED 0x00000004 True if there are some cryptographic functions that a user MUST be logged in to perform

CKF_USER_PIN_INITIALIZED 0x00000008 True if the normal user’s PIN has been initialized

CKF_RESTORE_KEY_NOT_NEEDED 0x00000020 True if a successful save of a session’s cryptographic operations state always contains all keys needed to restore the state of the session

CKF_CLOCK_ON_TOKEN 0x00000040 True if token has its own hardware clock

CKF_PROTECTED_AUTHENTICATION_PATH

0x00000100 True if token has a “protected authentication path”, whereby a user can log into the token without passing a PIN through the Cryptoki library

CKF_DUAL_CRYPTO_OPERATIONS 0x00000200 True if a single session with the token can perform dual cryptographic operations (see Section 5.14)

CKF_TOKEN_INITIALIZED 0x00000400 True if the token has been initialized using C_InitToken or an equivalent mechanism outside the scope of this standard. Calling C_InitToken when this flag is set will cause the token to be reinitialized.

CKF_SECONDARY_AUTHENTICATION 0x00000800 True if the token supports secondary authentication for private key objects. (Deprecated; new implementations MUST NOT set this flag)



CKF_USER_PIN_COUNT_LOW 0x00010000 True if an incorrect user login PIN has been entered at least once since the last successful authentication.

CKF_USER_PIN_FINAL_TRY 0x00020000 True if supplying an incorrect user PIN will cause it to become locked.

CKF_USER_PIN_LOCKED 0x00040000 True if the user PIN has been locked. User login to the token is not possible.

CKF_USER_PIN_TO_BE_CHANGED 0x00080000 True if the user PIN value is the default value set by token initialization or manufacturing, or the PIN has been expired by the card.

CKF_SO_PIN_COUNT_LOW 0x00100000 True if an incorrect SO login PIN has been entered at least once since the last successful authentication.

CKF_SO_PIN_FINAL_TRY 0x00200000 True if supplying an incorrect SO PIN will cause it to become locked.

CKF_SO_PIN_LOCKED 0x00400000 True if the SO PIN has been locked. SO login to the token is not possible.

CKF_SO_PIN_TO_BE_CHANGED 0x00800000 True if the SO PIN value is the default value set by token initialization or manufacturing, or the PIN has been expired by the card.

CKF_ERROR_STATE

0x01000000 True if the token failed a FIPS 140-2 self-test and entered an error state.

Exactly what the CKF_WRITE_PROTECTED flag means is not specified in Cryptoki. An application may 669 be unable to perform certain actions on a write-protected token; these actions can include any of the 670 following, among others: 671

Creating/modifying/deleting any object on the token. 672

Creating/modifying/deleting a token object on the token. 673

Changing the SO’s PIN. 674

Changing the normal user’s PIN. 675

The token may change the value of the CKF_WRITE_PROTECTED flag depending on the session state 676 to implement its object management policy. For instance, the token may set the 677 CKF_WRITE_PROTECTED flag unless the session state is R/W SO or R/W User to implement a policy 678 that does not allow any objects, public or private, to be created, modified, or deleted unless the user has 679 successfully called C_Login. 680

The CKF_USER_PIN_COUNT_LOW, CKF_USER_PIN_COUNT_LOW, CKF_USER_PIN_FINAL_TRY, 681 and CKF_SO_PIN_FINAL_TRY flags may always be set to false if the token does not support the 682

functionality or will not reveal the information because of its security policy. 683

The CKF_USER_PIN_TO_BE_CHANGED and CKF_SO_PIN_TO_BE_CHANGED flags may always be 684 set to false if the token does not support the functionality. If a PIN is set to the default value, or has 685


expired, the appropriate CKF_USER_PIN_TO_BE_CHANGED or CKF_SO_PIN_TO_BE_CHANGED 686 flag is set to true. When either of these flags are true, logging in with the corresponding PIN will succeed, 687 but only the C_SetPIN function can be called. Calling any other function that required the user to be 688 logged in will cause CKR_PIN_EXPIRED to be returned until C_SetPIN is called successfully. 689

CK_TOKEN_INFO Note: The fields ulMaxSessionCount, ulSessionCount, ulMaxRwSessionCount, 690 ulRwSessionCount, ulTotalPublicMemory, ulFreePublicMemory, ulTotalPrivateMemory, and 691 ulFreePrivateMemory can have the special value CK_UNAVAILABLE_INFORMATION, which means that 692 the token and/or library is unable or unwilling to provide that information. In addition, the fields 693 ulMaxSessionCount and ulMaxRwSessionCount can have the special value 694 CK_EFFECTIVELY_INFINITE, which means that there is no practical limit on the number of sessions 695 (resp. R/W sessions) an application can have open with the token. 696

It is important to check these fields for these special values. This is particularly true for 697 CK_EFFECTIVELY_INFINITE, since an application seeing this value in the ulMaxSessionCount or 698 ulMaxRwSessionCount field would otherwise conclude that it can’t open any sessions with the token, 699 which is far from being the case. 700

The upshot of all this is that the correct way to interpret (for example) the ulMaxSessionCount field is 701 something along the lines of the following: 702

CK_TOKEN_INFO info; 703 . 704 . 705 if ((CK_LONG) info.ulMaxSessionCount 706 == CK_UNAVAILABLE_INFORMATION) { 707 /* Token refuses to give value of ulMaxSessionCount */ 708 . 709 . 710 } else if (info.ulMaxSessionCount == CK_EFFECTIVELY_INFINITE) { 711 /* Application can open as many sessions as it wants */ 712 . 713 . 714 } else { 715 /* ulMaxSessionCount really does contain what it should */ 716 . 717 . 718 } 719 720

CK_TOKEN_INFO_PTR is a pointer to a CK_TOKEN_INFO. 721

3.3 Session types 722

Cryptoki represents session information with the following types: 723

CK_SESSION_HANDLE; CK_SESSION_HANDLE_PTR 724

CK_SESSION_HANDLE is a Cryptoki-assigned value that identifies a session. It is defined as follows: 725

typedef CK_ULONG CK_SESSION_HANDLE; 726 727

Valid session handles in Cryptoki always have nonzero values. For developers’ convenience, Cryptoki 728 defines the following symbolic value: 729

CK_INVALID_HANDLE 730 731

CK_SESSION_HANDLE_PTR is a pointer to a CK_SESSION_HANDLE. 732


CK_USER_TYPE 733

CK_USER_TYPE holds the types of Cryptoki users described in [PKCS11-UG] and, in addition, a 734

context-specific type described in Section 4.9. It is defined as follows: 735

typedef CK_ULONG CK_USER_TYPE; 736 737

For this version of Cryptoki, the following types of users are defined: 738

CKU_SO 739 CKU_USER 740 CKU_CONTEXT_SPECIFIC 741

CK_STATE 742

CK_STATE holds the session state, as described in [PKCS11-UG]. It is defined as follows: 743

typedef CK_ULONG CK_STATE; 744 745

For this version of Cryptoki, the following session states are defined: 746

CKS_RO_PUBLIC_SESSION 747 CKS_RO_USER_FUNCTIONS 748 CKS_RW_PUBLIC_SESSION 749 CKS_RW_USER_FUNCTIONS 750 CKS_RW_SO_FUNCTIONS 751

CK_SESSION_INFO; CK_SESSION_INFO_PTR 752

CK_SESSION_INFO provides information about a session. It is defined as follows: 753

typedef struct CK_SESSION_INFO { 754 CK_SLOT_ID slotID; 755 CK_STATE state; 756 CK_FLAGS flags; 757 CK_ULONG ulDeviceError; 758 } CK_SESSION_INFO; 759 760

761


slotID ID of the slot that interfaces with the token 763

state the state of the session 764

flags bit flags that define the type of session; the flags are defined below 765

ulDeviceError an error code defined by the cryptographic device. Used for errors 766 not covered by Cryptoki. 767


Table 7, Session Information Flags 769



CKF_RW_SESSION 0x00000002 True if the session is read/write; false if the session is read-only

CKF_SERIAL_SESSION 0x00000004 This flag is provided for backward compatibility, and should always be set to true

CK_SESSION_INFO_PTR is a pointer to a CK_SESSION_INFO. 770

3.4 Object types 771

Cryptoki represents object information with the following types: 772

CK_OBJECT_HANDLE; CK_OBJECT_HANDLE_PTR 773

CK_OBJECT_HANDLE is a token-specific identifier for an object. It is defined as follows: 774

typedef CK_ULONG CK_OBJECT_HANDLE; 775 776

When an object is created or found on a token by an application, Cryptoki assigns it an object handle for 777 that application’s sessions to use to access it. A particular object on a token does not necessarily have a 778 handle which is fixed for the lifetime of the object; however, if a particular session can use a particular 779 handle to access a particular object, then that session will continue to be able to use that handle to 780 access that object as long as the session continues to exist, the object continues to exist, and the object 781 continues to be accessible to the session. 782

Valid object handles in Cryptoki always have nonzero values. For developers’ convenience, Cryptoki 783 defines the following symbolic value: 784

CK_INVALID_HANDLE 785 786

CK_OBJECT_HANDLE_PTR is a pointer to a CK_OBJECT_HANDLE. 787

CK_OBJECT_CLASS; CK_OBJECT_CLASS_PTR 788

CK_OBJECT_CLASS is a value that identifies the classes (or types) of objects that Cryptoki recognizes. 789

It is defined as follows: 790

typedef CK_ULONG CK_OBJECT_CLASS; 791 792

Object classes are defined with the objects that use them. The type is specified on an object through the 793 CKA_CLASS attribute of the object. 794

Vendor defined values for this type may also be specified. 795

CKO_VENDOR_DEFINED 796 797

Object classes CKO_VENDOR_DEFINED and above are permanently reserved for token vendors. For 798

interoperability, vendors should register their object classes through the PKCS process. 799

CK_OBJECT_CLASS_PTR is a pointer to a CK_OBJECT_CLASS. 800

CK_HW_FEATURE_TYPE 801

CK_HW_FEATURE_TYPE is a value that identifies a hardware feature type of a device. It is defined as 802

follows: 803

typedef CK_ULONG CK_HW_FEATURE_TYPE; 804


805

Hardware feature types are defined with the objects that use them. The type is specified on an object 806 through the CKA_HW_FEATURE_TYPE attribute of the object. 807


CKH_VENDOR_DEFINED 809 810

Feature types CKH_VENDOR_DEFINED and above are permanently reserved for token vendors. For 811 interoperability, vendors should register their feature types through the PKCS process. 812

CK_KEY_TYPE 813

CK_KEY_TYPE is a value that identifies a key type. It is defined as follows: 814

typedef CK_ULONG CK_KEY_TYPE; 815 816

Key types are defined with the objects and mechanisms that use them. The key type is specified on an 817 object through the CKA_KEY_TYPE attribute of the object. 818


CKK_VENDOR_DEFINED 820 821

Key types CKK_VENDOR_DEFINED and above are permanently reserved for token vendors. For 822 interoperability, vendors should register their key types through the PKCS process. 823

CK_CERTIFICATE_TYPE 824

CK_CERTIFICATE_TYPE is a value that identifies a certificate type. It is defined as follows: 825

typedef CK_ULONG CK_CERTIFICATE_TYPE; 826 827

Certificate types are defined with the objects and mechanisms that use them. The certificate type is 828 specified on an object through the CKA_CERTIFICATE_TYPE attribute of the object. 829


CKC_VENDOR_DEFINED 831 832

Certificate types CKC_VENDOR_DEFINED and above are permanently reserved for token vendors. For 833 interoperability, vendors should register their certificate types through the PKCS process. 834

CK_CERTIFICATE_CATEGORY 835

CK_CERTIFICATE_CATEGORY is a value that identifies a certificate category. It is defined as follows: 836

typedef CK_ULONG CK_CERTIFICATE_CATEGORY; 837 838

For this version of Cryptoki, the following certificate categories are defined: 839


Constant Value Meaning

CK_CERTIFICATE_CATEGORY_UNSPECIFIED 0x00000000UL No category specified

CK_CERTIFICATE_CATEGORY_TOKEN_USER 0x00000001UL Certificate belongs to owner of the token

CK_CERTIFICATE_CATEGORY_AUTHORITY 0x00000002UL Certificate belongs to a certificate authority

CK_CERTIFICATE_CATEGORY_OTHER_ENTITY 0x00000003UL Certificate belongs to an end entity (i.e.: not a CA)

CK_ATTRIBUTE_TYPE 840

CK_ATTRIBUTE_TYPE is a value that identifies an attribute type. It is defined as follows: 841

typedef CK_ULONG CK_ATTRIBUTE_TYPE; 842 843

Attributes are defined with the objects and mechanisms that use them. Attributes are specified on an 844 object as a list of type, length value items. These are often specified as an attribute template. 845


CKA_VENDOR_DEFINED 847 848

Attribute types CKA_VENDOR_DEFINED and above are permanently reserved for token vendors. For 849 interoperability, vendors should register their attribute types through the PKCS process. 850

CK_ATTRIBUTE; CK_ATTRIBUTE_PTR 851

CK_ATTRIBUTE is a structure that includes the type, value, and length of an attribute. It is defined as 852

follows: 853

typedef struct CK_ATTRIBUTE { 854 CK_ATTRIBUTE_TYPE type; 855 CK_VOID_PTR pValue; 856 CK_ULONG ulValueLen; 857 } CK_ATTRIBUTE; 858 859


type the attribute type 861

pValue pointer to the value of the attribute 862

ulValueLen length in bytes of the value 863

If an attribute has no value, then ulValueLen = 0, and the value of pValue is irrelevant. An array of 864 CK_ATTRIBUTEs is called a “template” and is used for creating, manipulating and searching for objects. 865 The order of the attributes in a template never matters, even if the template contains vendor-specific 866 attributes. Note that pValue is a “void” pointer, facilitating the passing of arbitrary values. Both the 867 application and Cryptoki library MUST ensure that the pointer can be safely cast to the expected type 868 (i.e., without word-alignment errors). 869

870

The constant CK_UNAVAILABLE_INFORMATION is used in the ulValueLen field to denote an invalid or 871 unavailable value. See C_GetAttributeValue for further details. 872

873

CK_ATTRIBUTE_PTR is a pointer to a CK_ATTRIBUTE. 874


CK_DATE 875

CK_DATE is a structure that defines a date. It is defined as follows: 876

typedef struct CK_DATE { 877 CK_CHAR year[4]; 878 CK_CHAR month[2]; 879 CK_CHAR day[2]; 880 } CK_DATE; 881 882


year the year (“1900” - “9999”) 884

month the month (“01” - “12”) 885

day the day (“01” - “31”) 886

The fields hold numeric characters from the character set in Table 3Table 3, not the literal byte values. 887

When a Cryptoki object carries an attribute of this type, and the default value of the attribute is specified 888 to be "empty," then Cryptoki libraries SHALL set the attribute's ulValueLen to 0. 889

Note that implementations of previous versions of Cryptoki may have used other methods to identify an 890 "empty" attribute of type CK_DATE, and applications that needs to interoperate with these libraries 891 therefore have to be flexible in what they accept as an empty value. 892

CK_PROFILE_ID; CK_PROFILE_ID_PTR 893

CK_PROFILE_ID is an unsigend ulong value represting a specific token profile. It is defined as follows: 894

typedef CK_ULONG CK_PROFILE_ID; 895 896

Profiles are defines in the PKCS #11 Cryptographic Token Interface Profiles document. s. ID's greater 897 than 0xffffffff may cause compatibility issues on platforms that have CK_ULONG values of 32 bits, and 898 should be avoided. 899


CKP_VENDOR_DEFINED 901 902

Profile IDs CKP_VENDOR_DEFINED and above are permanently reserved for token vendors. For 903 interoperability, vendors should register their object classes through the PKCS process. 904

905

Valid Profile IDs in Cryptoki always have nonzero values. For developers’ convenience, Cryptoki defines 906

the following symbolic value: 907

CKP_INVALID_ID 908

CK_PROFILE_ID_PTR is a pointer to a CK_PROFILE_ID. 909

CK_JAVA_MIDP_SECURITY_DOMAIN 910

CK_JAVA_MIDP_SECURITY_DOMAIN is a value that identifies the Java MIDP security domain of a 911 certificate. It is defined as follows: 912

typedef CK_ULONG CK_JAVA_MIDP_SECURITY_DOMAIN; 913


For this version of Cryptoki, the following security domains are defined. See the Java MIDP specification 914 for further information: 915

Constant Value Meaning

CK_SECURITY_DOMAIN_UNSPECIFIED 0x00000000UL No domain specified

CK_SECURITY_DOMAIN_MANUFACTURER 0x00000001UL Manufacturer protection domain

CK_SECURITY_DOMAIN_OPERATOR 0x00000002UL Operator protection domain

CK_SECURITY_DOMAIN_THIRD_PARTY 0x00000003UL Third party protection domain

916

3.5 Data types for mechanisms 917

Cryptoki supports the following types for describing mechanisms and parameters to them: 918

CK_MECHANISM_TYPE; CK_MECHANISM_TYPE_PTR 919

CK_MECHANISM_TYPE is a value that identifies a mechanism type. It is defined as follows: 920

typedef CK_ULONG CK_MECHANISM_TYPE; 921 922

Mechanism types are defined with the objects and mechanism descriptions that use them. 923


CKM_VENDOR_DEFINED 925 926

Mechanism types CKM_VENDOR_DEFINED and above are permanently reserved for token vendors. 927 For interoperability, vendors should register their mechanism types through the PKCS process. 928

CK_MECHANISM_TYPE_PTR is a pointer to a CK_MECHANISM_TYPE. 929

CK_MECHANISM; CK_MECHANISM_PTR 930

CK_MECHANISM is a structure that specifies a particular mechanism and any parameters it requires. It 931

is defined as follows: 932

typedef struct CK_MECHANISM { 933 CK_MECHANISM_TYPE mechanism; 934 CK_VOID_PTR pParameter; 935 CK_ULONG ulParameterLen; 936 } CK_MECHANISM; 937 938


mechanism the type of mechanism 940

pParameter pointer to the parameter if required by the mechanism 941

ulParameterLen length in bytes of the parameter 942

Note that pParameter is a “void” pointer, facilitating the passing of arbitrary values. Both the application 943 and the Cryptoki library MUST ensure that the pointer can be safely cast to the expected type (i.e., 944

without word-alignment errors). 945

CK_MECHANISM_PTR is a pointer to a CK_MECHANISM. 946


CK_MECHANISM_INFO; CK_MECHANISM_INFO_PTR 947

CK_MECHANISM_INFO is a structure that provides information about a particular mechanism. It is 948

defined as follows: 949

typedef struct CK_MECHANISM_INFO { 950 CK_ULONG ulMinKeySize; 951 CK_ULONG ulMaxKeySize; 952 CK_FLAGS flags; 953 } CK_MECHANISM_INFO; 954 955


ulMinKeySize the minimum size of the key for the mechanism (whether this is 957 measured in bits or in bytes is mechanism-dependent) 958

ulMaxKeySize the maximum size of the key for the mechanism (whether this is 959 measured in bits or in bytes is mechanism-dependent) 960

flags bit flags specifying mechanism capabilities 961

For some mechanisms, the ulMinKeySize and ulMaxKeySize fields have meaningless values. 962


Table 8, Mechanism Information Flags 964


CKF_HW 0x00000001 True if the mechanism is performed by the device; false if the mechanism is performed in software

CKF_MESSAGE_ENCRYPT 0x00000002 True if the mechanism can be used with C_MessageEncryptInit

CKF_MESSAGE_DECRYPT 0x00000004 True if the mechanism can be used with C_MessageDecryptInit

CKF_MESSAGE_SIGN 0x00000008 True if the mechanism can be used with C_MessageSignInit

CKF_MESSAGE_VERIFY 0x00000010 True if the mechanism can be used with C_MessageVerifyInit

CKF_MULTI_MESSAGE 0x00000020 True if the mechanism can be used with C_*MessageBegin. One of CKF_MESSAGE_* flag must also be set.

CKF_FIND_OBJECTS 0x00000040 This flag can be passed in as a parameter to C_SessionCancel to cancel an active object search operation. Any other use of this flag is outside the scope of this standard.

CKF_ENCRYPT 0x00000100 True if the mechanism can be used with C_EncryptInit

CKF_DECRYPT 0x00000200 True if the mechanism can be used with C_DecryptInit

CKF_DIGEST 0x00000400 True if the mechanism can be used with C_DigestInit

CKF_SIGN 0x00000800 True if the mechanism can be used with C_SignInit

CKF_SIGN_RECOVER 0x00001000 True if the mechanism can be used with



C_SignRecoverInit

CKF_VERIFY 0x00002000 True if the mechanism can be used with C_VerifyInit

CKF_VERIFY_RECOVER 0x00004000 True if the mechanism can be used with C_VerifyRecoverInit

CKF_GENERATE 0x00008000 True if the mechanism can be used with C_GenerateKey

CKF_GENERATE_KEY_PAIR 0x00010000 True if the mechanism can be used with C_GenerateKeyPair

CKF_WRAP 0x00020000 True if the mechanism can be used with C_WrapKey

CKF_UNWRAP 0x00040000 True if the mechanism can be used with C_UnwrapKey

CKF_DERIVE 0x00080000 True if the mechanism can be used with C_DeriveKey

CKF_EXTENSION 0x80000000 True if there is an extension to the flags; false if no extensions. MUST be false for this version.

CK_MECHANISM_INFO_PTR is a pointer to a CK_MECHANISM_INFO. 965

3.6 Function types 966

Cryptoki represents information about functions with the following data types: 967

CK_RV 968

CK_RV is a value that identifies the return value of a Cryptoki function. It is defined as follows: 969

typedef CK_ULONG CK_RV; 970 971


CKR_VENDOR_DEFINED 973 974

Section 5.1 defines the meaning of each CK_RV value. Return values CKR_VENDOR_DEFINED and 975 above are permanently reserved for token vendors. For interoperability, vendors should register their 976 return values through the PKCS process. 977

CK_NOTIFY 978

CK_NOTIFY is the type of a pointer to a function used by Cryptoki to perform notification callbacks. It is 979


typedef CK_CALLBACK_FUNCTION(CK_RV, CK_NOTIFY)( 981 CK_SESSION_HANDLE hSession, 982 CK_NOTIFICATION event, 983 CK_VOID_PTR pApplication 984 ); 985 986

The arguments to a notification callback function have the following meanings: 987

hSession The handle of the session performing the callback 988


event The type of notification callback 989

pApplication An application-defined value. This is the same value as was passed 990 to C_OpenSession to open the session performing the callback 991

CK_C_XXX 992

Cryptoki also defines an entire family of other function pointer types. For each function C_XXX in the 993 Cryptoki API (see Section 4.12 for detailed information about each of them), Cryptoki defines a type 994 CK_C_XXX, which is a pointer to a function with the same arguments and return value as C_XXX has. 995 An appropriately-set variable of type CK_C_XXX may be used by an application to call the Cryptoki 996 function C_XXX. 997

CK_FUNCTION_LIST; CK_FUNCTION_LIST_PTR; 998

CK_FUNCTION_LIST_PTR_PTR 999

CK_FUNCTION_LIST is a structure which contains a Cryptoki version and a function pointer to each 1000

function in the Cryptoki API. It is defined as follows: 1001

typedef struct CK_FUNCTION_LIST { 1002 CK_VERSION version; 1003 CK_C_Initialize C_Initialize; 1004 CK_C_Finalize C_Finalize; 1005 CK_C_GetInfo C_GetInfo; 1006 CK_C_GetFunctionList C_GetFunctionList; 1007 CK_C_GetSlotList C_GetSlotList; 1008 CK_C_GetSlotInfo C_GetSlotInfo; 1009 CK_C_GetTokenInfo C_GetTokenInfo; 1010 CK_C_GetMechanismList C_GetMechanismList; 1011 CK_C_GetMechanismInfo C_GetMechanismInfo; 1012 CK_C_InitToken C_InitToken; 1013 CK_C_InitPIN C_InitPIN; 1014 CK_C_SetPIN C_SetPIN; 1015 CK_C_OpenSession C_OpenSession; 1016 CK_C_CloseSession C_CloseSession; 1017 CK_C_CloseAllSessions C_CloseAllSessions; 1018 CK_C_GetSessionInfo C_GetSessionInfo; 1019 1020 CK_C_GetOperationState C_GetOperationState; 1021 CK_C_SetOperationState C_SetOperationState; 1022 CK_C_Login C_Login; 1023 CK_C_Logout C_Logout; 1024 CK_C_CreateObject C_CreateObject; 1025 CK_C_CopyObject C_CopyObject; 1026 CK_C_DestroyObject C_DestroyObject; 1027 CK_C_GetObjectSize C_GetObjectSize; 1028 CK_C_GetAttributeValue C_GetAttributeValue; 1029 CK_C_SetAttributeValue C_SetAttributeValue; 1030 CK_C_FindObjectsInit C_FindObjectsInit; 1031 CK_C_FindObjects C_FindObjects; 1032 CK_C_FindObjectsFinal C_FindObjectsFinal; 1033 CK_C_EncryptInit C_EncryptInit; 1034 CK_C_Encrypt C_Encrypt; 1035 CK_C_EncryptUpdate C_EncryptUpdate; 1036 CK_C_EncryptFinal C_EncryptFinal; 1037 CK_C_DecryptInit C_DecryptInit; 1038 CK_C_Decrypt C_Decrypt; 1039 CK_C_DecryptUpdate C_DecryptUpdate; 1040 CK_C_DecryptFinal C_DecryptFinal; 1041 CK_C_DigestInit C_DigestInit; 1042 CK_C_Digest C_Digest; 1043 CK_C_DigestUpdate C_DigestUpdate; 1044





CK_C_DigestKey C_DigestKey; 1045 CK_C_DigestFinal C_DigestFinal; 1046 CK_C_SignInit C_SignInit; 1047 CK_C_Sign C_Sign; 1048 CK_C_SignUpdate C_SignUpdate; 1049 CK_C_SignFinal C_SignFinal; 1050 CK_C_SignRecoverInit C_SignRecoverInit; 1051 CK_C_SignRecover C_SignRecover; 1052 CK_C_VerifyInit C_VerifyInit; 1053 CK_C_Verify C_Verify; 1054 CK_C_VerifyUpdate C_VerifyUpdate; 1055 CK_C_VerifyFinal C_VerifyFinal; 1056 CK_C_VerifyRecoverInit C_VerifyRecoverInit; 1057 CK_C_VerifyRecover C_VerifyRecover; 1058 CK_C_DigestEncryptUpdate C_DigestEncryptUpdate; 1059 CK_C_DecryptDigestUpdate C_DecryptDigestUpdate; 1060 CK_C_SignEncryptUpdate C_SignEncryptUpdate; 1061 CK_C_DecryptVerifyUpdate C_DecryptVerifyUpdate; 1062 CK_C_GenerateKey C_GenerateKey; 1063 CK_C_GenerateKeyPair C_GenerateKeyPair; 1064 CK_C_WrapKey C_WrapKey; 1065 CK_C_UnwrapKey C_UnwrapKey; 1066 CK_C_DeriveKey C_DeriveKey; 1067 CK_C_SeedRandom C_SeedRandom; 1068 CK_C_GenerateRandom C_GenerateRandom; 1069 CK_C_GetFunctionStatus C_GetFunctionStatus; 1070 CK_C_CancelFunction C_CancelFunction; 1071 CK_C_WaitForSlotEvent C_WaitForSlotEvent; 1072 } CK_FUNCTION_LIST; 1073 1074

Each Cryptoki library has a static CK_FUNCTION_LIST structure, and a pointer to it (or to a copy of it 1075 which is also owned by the library) may be obtained by the C_GetFunctionList function (see Section 1076 5.2). The value that this pointer points to can be used by an application to quickly find out where the 1077 executable code for each function in the Cryptoki API is located. Every function in the Cryptoki API 1078 MUST have an entry point defined in the Cryptoki library’s CK_FUNCTION_LIST structure. If a particular 1079 function in the Cryptoki API is not supported by a library, then the function pointer for that function in the 1080 library’s CK_FUNCTION_LIST structure should point to a function stub which simply returns 1081

CKR_FUNCTION_NOT_SUPPORTED. 1082

In this structure ‘version’ is the cryptoki specification version number. The major and minor versions must 1083 be set to 0x02 and 0x28 indicating a version 2.40 compatible structure. The updated function list table for 1084 this version of the specification may be returned via C_GetInterfaceList or C_GetInterface. 1085

1086

An application may or may not be able to modify a Cryptoki library’s static CK_FUNCTION_LIST 1087

structure. Whether or not it can, it should never attempt to do so. 1088

PKCS #11 modules must not add new functions at the end of the CK_FUNCTION_LIST that are not 1089 contained within the defined structure. If a PKCS#11 module needs to define additional functions, they 1090 should be placed within a vendor defined interface returned via C_GetInterfaceList or C_GetInterface. 1091

CK_FUNCTION_LIST_PTR is a pointer to a CK_FUNCTION_LIST. 1092

CK_FUNCTION_LIST_PTR_PTR is a pointer to a CK_FUNCTION_LIST_PTR. 1093

1094



CK_FUNCTION_LIST_3_0; CK_FUNCTION_LIST_3_0_PTR; 1095

CK_FUNCTION_LIST_3_0_PTR_PTR 1096

CK_FUNCTION_LIST_3_0 is a structure which contains the same function pointers as in 1097 CK_FUNCTION_LIST and additional functions added to the end of the structure that were defined in 1098 Cryptoki version 3.0. It is defined as follows: 1099

typedef struct CK_FUNCTION_LIST_3_0 { 1100 CK_VERSION version; 1101 CK_C_Initialize C_Initialize; 1102 CK_C_Finalize C_Finalize; 1103 CK_C_GetInfo C_GetInfo; 1104 CK_C_GetFunctionList C_GetFunctionList; 1105 CK_C_GetSlotList C_GetSlotList; 1106 CK_C_GetSlotInfo C_GetSlotInfo; 1107 CK_C_GetTokenInfo C_GetTokenInfo; 1108 CK_C_GetMechanismList C_GetMechanismList; 1109 CK_C_GetMechanismInfo C_GetMechanismInfo; 1110 CK_C_InitToken C_InitToken; 1111 CK_C_InitPIN C_InitPIN; 1112 CK_C_SetPIN C_SetPIN; 1113 CK_C_OpenSession C_OpenSession; 1114 CK_C_CloseSession C_CloseSession; 1115 CK_C_CloseAllSessions C_CloseAllSessions; 1116 CK_C_GetSessionInfo C_GetSessionInfo; 1117 CK_C_GetOperationState C_GetOperationState; 1118 CK_C_SetOperationState C_SetOperationState; 1119 CK_C_Login C_Login; 1120 CK_C_Logout C_Logout; 1121 CK_C_CreateObject C_CreateObject; 1122 CK_C_CopyObject C_CopyObject; 1123 CK_C_DestroyObject C_DestroyObject; 1124 CK_C_GetObjectSize C_GetObjectSize; 1125 CK_C_GetAttributeValue C_GetAttributeValue; 1126 CK_C_SetAttributeValue C_SetAttributeValue; 1127 CK_C_FindObjectsInit C_FindObjectsInit; 1128 CK_C_FindObjects C_FindObjects; 1129 CK_C_FindObjectsFinal C_FindObjectsFinal; 1130 CK_C_EncryptInit C_EncryptInit; 1131 CK_C_Encrypt C_Encrypt; 1132 CK_C_EncryptUpdate C_EncryptUpdate; 1133 CK_C_EncryptFinal C_EncryptFinal; 1134 CK_C_DecryptInit C_DecryptInit; 1135 CK_C_Decrypt C_Decrypt; 1136 CK_C_DecryptUpdate C_DecryptUpdate; 1137 CK_C_DecryptFinal C_DecryptFinal; 1138 CK_C_DigestInit C_DigestInit; 1139 CK_C_Digest C_Digest; 1140 CK_C_DigestUpdate C_DigestUpdate; 1141 CK_C_DigestKey C_DigestKey; 1142 CK_C_DigestFinal C_DigestFinal; 1143 CK_C_SignInit C_SignInit; 1144 CK_C_Sign C_Sign; 1145 CK_C_SignUpdate C_SignUpdate; 1146 CK_C_SignFinal C_SignFinal; 1147 CK_C_SignRecoverInit C_SignRecoverInit; 1148 CK_C_SignRecover C_SignRecover; 1149 CK_C_VerifyInit C_VerifyInit; 1150 CK_C_Verify C_Verify; 1151 CK_C_VerifyUpdate C_VerifyUpdate; 1152 CK_C_VerifyFinal C_VerifyFinal; 1153 CK_C_VerifyRecoverInit C_VerifyRecoverInit; 1154 CK_C_VerifyRecover C_VerifyRecover; 1155





CK_C_DigestEncryptUpdate C_DigestEncryptUpdate; 1156 CK_C_DecryptDigestUpdate C_DecryptDigestUpdate; 1157 CK_C_SignEncryptUpdate C_SignEncryptUpdate; 1158 CK_C_DecryptVerifyUpdate C_DecryptVerifyUpdate; 1159 CK_C_GenerateKey C_GenerateKey; 1160 CK_C_GenerateKeyPair C_GenerateKeyPair; 1161 CK_C_WrapKey C_WrapKey; 1162 CK_C_UnwrapKey C_UnwrapKey; 1163 CK_C_DeriveKey C_DeriveKey; 1164 CK_C_SeedRandom C_SeedRandom; 1165 CK_C_GenerateRandom C_GenerateRandom; 1166 CK_C_GetFunctionStatus C_GetFunctionStatus; 1167 CK_C_CancelFunction C_CancelFunction; 1168 CK_C_WaitForSlotEvent C_WaitForSlotEvent; 1169 CK_C_GetInterfaceList C_GetInterfaceList; 1170 CK_C_GetInterface C_GetInterface; 1171 CK_C_LoginUser C_LoginUser; 1172 CK_C_SessionCancel C_SessionCancel; 1173 CK_C_MessageEncryptInit C_MessageEncryptInit; 1174 CK_C_EncryptMessage C_EncryptMessage; 1175 CK_C_EncryptMessageBegin C_EncryptMessageBegin; 1176 CK_C_EncryptMessageNext C_EncryptMessageNext; 1177 CK_C_MessageEncryptFinal C_MessageEncryptFinal; 1178 CK_C_MessageDecryptInit C_MessageDecryptInit; 1179 CK_C_DecryptMessage C_DecryptMessage; 1180 CK_C_DecryptMessageBegin C_DecryptMessageBegin; 1181 CK_C_DecryptMessageNext C_DecryptMessageNext; 1182 CK_C_MessageDecryptFinal C_MessageDecryptFinal; 1183 CK_C_MessageSignInit C_MessageSignInit; 1184 CK_C_SignMessage C_SignMessage; 1185 CK_C_SignMessageBegin C_SignMessageBegin; 1186 CK_C_SignMessageNext C_SignMessageNext; 1187 CK_C_MessageSignFinal C_MessageSignFinal; 1188 CK_C_MessageVerifyInit C_MessageVerifyInit; 1189 CK_C_VerifyMessage C_VerifyMessage; 1190 CK_C_VerifyMessageBegin C_VerifyMessageBegin; 1191 CK_C_VerifyMessageNext C_VerifyMessageNext; 1192 CK_C_MessageVerifyFinal C_MessageVerifyFinal; 1193 } CK_FUNCTION_LIST_3_0; 1194 1195

For a general description of CK_FUNCTION_LIST_3_0 see CK_FUNCTION_LIST. 1196

In this structure, version is the cryptoki specification version number. It should match the value of 1197 cryptokiVersion returned in the CK_INFO structure, but must be 3.0 at minimum. 1198

This function list may be returned via C_GetInterfaceList or C_GetInterface 1199

CK_FUNCTION_LIST_3_0_PTR is a pointer to a CK_FUNCTION_LIST_3_0. 1200

CK_FUNCTION_LIST_3_0_PTR_PTR is a pointer to a CK_FUNCTION_LIST_3_0_PTR. 1201

CK_INTERFACE; CK_INTERFACE_PTR; CK_INTERFACE_PTR_PTR 1202

CK_INTERFACE is a structure which contains an interface name with a function list and flag. 1203


typedef struct CK_INTERFACE { 1205 CK_UTF8CHAR_PTR pInterfaceName; 1206 CK_VOID_PTR pFunctionList; 1207 CK_FLAGS flags; 1208 } CK_INTERFACE; 1209

1210






pInterfaceName the name of the interface 1212

pFunctionList the interface function list which must always begin with a 1213 CK_VERSION structure as the first field 1214

flags bit flags specifying interface capabilities 1215

The interface name “PKCS 11” is reserved for use by interfaces defined within the cryptoki specification. 1216

Interfaces starting with the string: “Vendor ” are reserved for vendor use and will not oetherwise be 1217 defined as interfaces in the PKCS #11 specification. Vendors should supply new functions with interface 1218 names of “Vendor {vendor name}”. For example “Vendor ACME Inc”. 1219

1220


Table 9, CK_INTERFACE Flags 1222


CKF_INTERFACE_FORK_SAFE 0x00000001 The returned interface will have fork tolerant semantics. When the application forks, each process will get its own copy of all session objects, session states, login states, and encryption states. Each process will also maintain access to token objects with their previously supplied handles.

1223

CK_INTERFACE_PTR is a pointer to a CK_INTERFACE. 1224

CK_INTERFACE_PTR_PTR is a pointer to a CK_INTERFACE_PTR. 1225

3.7 Locking-related types 1226

The types in this section are provided solely for applications which need to access Cryptoki from multiple 1227 threads simultaneously. Applications which will not do this need not use any of these types. 1228

CK_CREATEMUTEX 1229

CK_CREATEMUTEX is the type of a pointer to an application-supplied function which creates a new 1230

mutex object and returns a pointer to it. It is defined as follows: 1231

typedef CK_CALLBACK_FUNCTION(CK_RV, CK_CREATEMUTEX)( 1232 CK_VOID_PTR_PTR ppMutex 1233 ); 1234 1235

Calling a CK_CREATEMUTEX function returns the pointer to the new mutex object in the location pointed 1236 to by ppMutex. Such a function should return one of the following values: 1237

CKR_OK, CKR_GENERAL_ERROR 1238 CKR_HOST_MEMORY 1239


CK_DESTROYMUTEX 1240

CK_DESTROYMUTEX is the type of a pointer to an application-supplied function which destroys an 1241

existing mutex object. It is defined as follows: 1242

typedef CK_CALLBACK_FUNCTION(CK_RV, CK_DESTROYMUTEX)( 1243 CK_VOID_PTR pMutex 1244 ); 1245 1246

The argument to a CK_DESTROYMUTEX function is a pointer to the mutex object to be destroyed. Such 1247 a function should return one of the following values: 1248

CKR_OK, CKR_GENERAL_ERROR 1249 CKR_HOST_MEMORY 1250 CKR_MUTEX_BAD 1251

CK_LOCKMUTEX and CK_UNLOCKMUTEX 1252

CK_LOCKMUTEX is the type of a pointer to an application-supplied function which locks an existing 1253 mutex object. CK_UNLOCKMUTEX is the type of a pointer to an application-supplied function which 1254

unlocks an existing mutex object. The proper behavior for these types of functions is as follows: 1255

If a CK_LOCKMUTEX function is called on a mutex which is not locked, the calling thread obtains a 1256 lock on that mutex and returns. 1257

If a CK_LOCKMUTEX function is called on a mutex which is locked by some thread other than the 1258 calling thread, the calling thread blocks and waits for that mutex to be unlocked. 1259

If a CK_LOCKMUTEX function is called on a mutex which is locked by the calling thread, the 1260 behavior of the function call is undefined. 1261

If a CK_UNLOCKMUTEX function is called on a mutex which is locked by the calling thread, that 1262 mutex is unlocked and the function call returns. Furthermore: 1263

o If exactly one thread was blocking on that particular mutex, then that thread stops blocking, 1264 obtains a lock on that mutex, and its CK_LOCKMUTEX call returns. 1265

o If more than one thread was blocking on that particular mutex, then exactly one of the 1266 blocking threads is selected somehow. That lucky thread stops blocking, obtains a lock on 1267 the mutex, and its CK_LOCKMUTEX call returns. All other threads blocking on that particular 1268 mutex continue to block. 1269

If a CK_UNLOCKMUTEX function is called on a mutex which is not locked, then the function call 1270 returns the error code CKR_MUTEX_NOT_LOCKED. 1271

If a CK_UNLOCKMUTEX function is called on a mutex which is locked by some thread other than the 1272 calling thread, the behavior of the function call is undefined. 1273

CK_LOCKMUTEX is defined as follows: 1274

typedef CK_CALLBACK_FUNCTION(CK_RV, CK_LOCKMUTEX)( 1275 CK_VOID_PTR pMutex 1276 ); 1277 1278

The argument to a CK_LOCKMUTEX function is a pointer to the mutex object to be locked. Such a 1279 function should return one of the following values: 1280

CKR_OK, CKR_GENERAL_ERROR 1281 CKR_HOST_MEMORY, 1282 CKR_MUTEX_BAD 1283 1284

CK_UNLOCKMUTEX is defined as follows: 1285


typedef CK_CALLBACK_FUNCTION(CK_RV, CK_UNLOCKMUTEX)( 1286 CK_VOID_PTR pMutex 1287 ); 1288 1289

The argument to a CK_UNLOCKMUTEX function is a pointer to the mutex object to be unlocked. Such a 1290 function should return one of the following values: 1291

CKR_OK, CKR_GENERAL_ERROR 1292 CKR_HOST_MEMORY 1293 CKR_MUTEX_BAD 1294 CKR_MUTEX_NOT_LOCKED 1295

CK_C_INITIALIZE_ARGS; CK_C_INITIALIZE_ARGS_PTR 1296

CK_C_INITIALIZE_ARGS is a structure containing the optional arguments for the C_Initialize function. 1297 For this version of Cryptoki, these optional arguments are all concerned with the way the library deals 1298 with threads. CK_C_INITIALIZE_ARGS is defined as follows: 1299

typedef struct CK_C_INITIALIZE_ARGS { 1300 CK_CREATEMUTEX CreateMutex; 1301 CK_DESTROYMUTEX DestroyMutex; 1302 CK_LOCKMUTEX LockMutex; 1303 CK_UNLOCKMUTEX UnlockMutex; 1304 CK_FLAGS flags; 1305 CK_VOID_PTR pReserved; 1306 } CK_C_INITIALIZE_ARGS; 1307 1308


CreateMutex pointer to a function to use for creating mutex objects 1310

DestroyMutex pointer to a function to use for destroying mutex objects 1311

LockMutex pointer to a function to use for locking mutex objects 1312

UnlockMutex pointer to a function to use for unlocking mutex objects 1313

flags bit flags specifying options for C_Initialize; the flags are defined 1314 below 1315

pReserved reserved for future use. Should be NULL_PTR for this version of 1316 Cryptoki 1317


Table 10, C_Initialize Parameter Flags 1319



CKF_LIBRARY_CANT_CREATE_OS_THREADS 0x00000001 True if application threads which are executing calls to the library may not use native operating system calls to spawn new threads; false if they may

CKF_OS_LOCKING_OK 0x00000002 True if the library can use the native operation system threading model for locking; false otherwise

CK_C_INITIALIZE_ARGS_PTR is a pointer to a CK_C_INITIALIZE_ARGS. 1320


4 Objects 1321

Cryptoki recognizes a number of classes of objects, as defined in the CK_OBJECT_CLASS data type. 1322 An object consists of a set of attributes, each of which has a given value. Each attribute that an object 1323 possesses has precisely one value. The following figure illustrates the high-level hierarchy of the 1324 Cryptoki objects and some of the attributes they support: 1325

Object

Class

Storage Token Private Label Modifiable

Hardware feature

Feature type

Mechanism

Mechanism type

Data Application Object Identifier Value Certificate

Key

Domain parameters

Mechanism type

Profile

Profile ID

1326

Figure 1, Object Attribute Hierarchy 1327

Cryptoki provides functions for creating, destroying, and copying objects in general, and for obtaining and 1328 modifying the values of their attributes. Some of the cryptographic functions (e.g., C_GenerateKey) also 1329

create key objects to hold their results. 1330

Objects are always “well-formed” in Cryptoki—that is, an object always contains all required attributes, 1331 and the attributes are always consistent with one another from the time the object is created. This 1332 contrasts with some object-based paradigms where an object has no attributes other than perhaps a 1333 class when it is created, and is uninitialized for some time. In Cryptoki, objects are always initialized. 1334

Tables throughout most of Section 4 define each Cryptoki attribute in terms of the data type of the 1335 attribute value and the meaning of the attribute, which may include a default initial value. Some of the 1336 data types are defined explicitly by Cryptoki (e.g., CK_OBJECT_CLASS). Attribute values may also take 1337

the following types: 1338

Byte array an arbitrary string (array) of CK_BYTEs 1339

Big integer a string of CK_BYTEs representing an unsigned integer of arbitrary 1340 size, most-significant byte first (e.g., the integer 32768 is 1341 represented as the 2-byte string 0x80 0x00) 1342

Local string an unpadded string of CK_CHARs (see Table 3Table 3) with no 1343 null-termination 1344

RFC2279 string an unpadded string of CK_UTF8CHARs with no null-termination 1345

Formatted: Check spelling andgrammar


A token can hold several identical objects, i.e., it is permissible for two or more objects to have exactly the 1346

same values for all their attributes. 1347

In most cases each type of object in the Cryptoki specification possesses a completely well-defined set of 1348 Cryptoki attributes. Some of these attributes possess default values, and need not be specified when 1349 creating an object; some of these default values may even be the empty string (“”). Nonetheless, the 1350 object possesses these attributes. A given object has a single value for each attribute it possesses, even 1351 if the attribute is a vendor-specific attribute whose meaning is outside the scope of Cryptoki. 1352

In addition to possessing Cryptoki attributes, objects may possess additional vendor-specific attributes 1353 whose meanings and values are not specified by Cryptoki. 1354

4.1 Creating, modifying, and copying objects 1355

All Cryptoki functions that create, modify, or copy objects take a template as one of their arguments, 1356 where the template specifies attribute values. Cryptographic functions that create objects (see Section 1357 5.18) may also contribute some additional attribute values themselves; which attributes have values 1358 contributed by a cryptographic function call depends on which cryptographic mechanism is being 1359 performed (see [PKCS11-Curr] and [PKCS11-Hist] for specification of mechanisms for PKCS #11). In 1360 any case, all the required attributes supported by an object class that do not have default values MUST 1361 be specified when an object is created, either in the template or by the function itself. 1362

4.1.1 Creating objects 1363

Objects may be created with the Cryptoki functions C_CreateObject (see Section 5.7), C_GenerateKey, 1364 C_GenerateKeyPair, C_UnwrapKey, and C_DeriveKey (see Section 5.18). In addition, copying an 1365 existing object (with the function C_CopyObject) also creates a new object, but we consider this type of 1366

object creation separately in Section 4.1.3. 1367

Attempting to create an object with any of these functions requires an appropriate template to be 1368 supplied. 1369

1. If the supplied template specifies a value for an invalid attribute, then the attempt should fail with the 1370 error code CKR_ATTRIBUTE_TYPE_INVALID. An attribute is valid if it is either one of the attributes 1371 described in the Cryptoki specification or an additional vendor-specific attribute supported by the 1372 library and token. 1373

2. If the supplied template specifies an invalid value for a valid attribute, then the attempt should fail with 1374 the error code CKR_ATTRIBUTE_VALUE_INVALID. The valid values for Cryptoki attributes are 1375 described in the Cryptoki specification. 1376

3. If the supplied template specifies a value for a read-only attribute, then the attempt should fail with the 1377 error code CKR_ATTRIBUTE_READ_ONLY. Whether or not a given Cryptoki attribute is read-only is 1378 explicitly stated in the Cryptoki specification; however, a particular library and token may be even 1379 more restrictive than Cryptoki specifies. In other words, an attribute which Cryptoki says is not read-1380 only may nonetheless be read-only under certain circumstances (i.e., in conjunction with some 1381 combinations of other attributes) for a particular library and token. Whether or not a given non-1382 Cryptoki attribute is read-only is obviously outside the scope of Cryptoki. 1383

4. If the attribute values in the supplied template, together with any default attribute values and any 1384 attribute values contributed to the object by the object-creation function itself, are insufficient to fully 1385 specify the object to create, then the attempt should fail with the error code 1386 CKR_TEMPLATE_INCOMPLETE. 1387

5. If the attribute values in the supplied template, together with any default attribute values and any 1388 attribute values contributed to the object by the object-creation function itself, are inconsistent, then 1389 the attempt should fail with the error code CKR_TEMPLATE_INCONSISTENT. A set of attribute 1390 values is inconsistent if not all of its members can be satisfied simultaneously by the token, although 1391 each value individually is valid in Cryptoki. One example of an inconsistent template would be using a 1392


template which specifies two different values for the same attribute. Another example would be trying 1393 to create a secret key object with an attribute which is appropriate for various types of public keys or 1394 private keys, but not for secret keys. A final example would be a template with an attribute that 1395 violates some token specific requirement. Note that this final example of an inconsistent template is 1396 token-dependent—on a different token, such a template might not be inconsistent. 1397

6. If the supplied template specifies the same value for a particular attribute more than once (or the 1398 template specifies the same value for a particular attribute that the object-creation function itself 1399 contributes to the object), then the behavior of Cryptoki is not completely specified. The attempt to 1400 create an object can either succeed—thereby creating the same object that would have been created 1401 if the multiply-specified attribute had only appeared once—or it can fail with error code 1402 CKR_TEMPLATE_INCONSISTENT. Library developers are encouraged to make their libraries 1403 behave as though the attribute had only appeared once in the template; application developers are 1404 strongly encouraged never to put a particular attribute into a particular template more than once. 1405

If more than one of the situations listed above applies to an attempt to create an object, then the error 1406 code returned from the attempt can be any of the error codes from above that applies. 1407

4.1.2 Modifying objects 1408

Objects may be modified with the Cryptoki function C_SetAttributeValue (see Section 5.7). The 1409 template supplied to C_SetAttributeValue can contain new values for attributes which the object already 1410

possesses; values for attributes which the object does not yet possess; or both. 1411

Some attributes of an object may be modified after the object has been created, and some may not. In 1412 addition, attributes which Cryptoki specifies are modifiable may actually not be modifiable on some 1413 tokens. That is, if a Cryptoki attribute is described as being modifiable, that really means only that it is 1414 modifiable insofar as the Cryptoki specification is concerned. A particular token might not actually 1415 support modification of some such attributes. Furthermore, whether or not a particular attribute of an 1416 object on a particular token is modifiable might depend on the values of certain attributes of the object. 1417 For example, a secret key object’s CKA_SENSITIVE attribute can be changed from CK_FALSE to 1418

CK_TRUE, but not the other way around. 1419

All the scenarios in Section 4.1.1—and the error codes they return—apply to modifying objects with 1420 C_SetAttributeValue, except for the possibility of a template being incomplete. 1421

4.1.3 Copying objects 1422

Unless an object's CKA_COPYABLE (see Table 17Table 17) attribute is set to CK_FALSE, it may be 1423 copied with the Cryptoki function C_CopyObject (see Section 5.7). In the process of copying an object, 1424 C_CopyObject also modifies the attributes of the newly-created copy according to an application-1425 supplied template. 1426

The Cryptoki attributes which can be modified during the course of a C_CopyObject operation are the 1427 same as the Cryptoki attributes which are described as being modifiable, plus the four special attributes 1428 CKA_TOKEN, CKA_PRIVATE, CKA_MODIFIABLE and CKA_DESTROYABLE. To be more precise, 1429 these attributes are modifiable during the course of a C_CopyObject operation insofar as the Cryptoki 1430 specification is concerned. A particular token might not actually support modification of some such 1431 attributes during the course of a C_CopyObject operation. Furthermore, whether or not a particular 1432 attribute of an object on a particular token is modifiable during the course of a C_CopyObject operation 1433 might depend on the values of certain attributes of the object. For example, a secret key object’s 1434 CKA_SENSITIVE attribute can be changed from CK_FALSE to CK_TRUE during the course of a 1435 C_CopyObject operation, but not the other way around. 1436

If the CKA_COPYABLE attribute of the object to be copied is set to CK_FALSE, C_CopyObject returns 1437 CKR_ACTION_PROHIBITED. Otherwise, the scenarios described in 10.1.1 - and the error codes they 1438 return - apply to copying objects with C_CopyObject, except for the possibility of a template being 1439 incomplete. 1440


4.2 Common attributes 1441

Table 11, Common footnotes for object attribute tables 1442

1 MUST be specified when object is created with C_CreateObject. 2 MUST not be specified when object is created with C_CreateObject.

3 MUST be specified when object is generated with C_GenerateKey or C_GenerateKeyPair.

4 MUST not be specified when object is generated with C_GenerateKey or

C_GenerateKeyPair. 5 MUST be specified when object is unwrapped with C_UnwrapKey.

6 MUST not be specified when object is unwrapped with C_UnwrapKey.

7 Cannot be revealed if object has its CKA_SENSITIVE attribute set to CK_TRUE or its

CKA_EXTRACTABLE attribute set to CK_FALSE. 8 May be modified after object is created with a C_SetAttributeValue call, or in the process of

copying object with a C_CopyObject call. However, it is possible that a particular token may not permit modification of the attribute during the course of a C_CopyObject call. 9 Default value is token-specific, and may depend on the values of other attributes.

10 Can only be set to CK_TRUE by the SO user.

11 Attribute cannot be changed once set to CK_TRUE. It becomes a read only attribute.

12 Attribute cannot be changed once set to CK_FALSE. It becomes a read only attribute.

1443

Table 12, Common Object Attributes 1444

Attribute Data Type Meaning

CKA_CLASS1 CK_OBJECT_CLASS Object class (type)

Refer to Table 11Table 11 for footnotes 1445

The above table defines the attributes common to all objects. 1446

4.3 Hardware Feature Objects 1447

4.3.1 Definitions 1448

This section defines the object class CKO_HW_FEATURE for type CK_OBJECT_CLASS as used in the 1449 CKA_CLASS attribute of objects. 1450

4.3.2 Overview 1451

Hardware feature objects (CKO_HW_FEATURE) represent features of the device. They provide an easily 1452

expandable method for introducing new value-based features to the Cryptoki interface. 1453

When searching for objects using C_FindObjectsInit and C_FindObjects, hardware feature objects are 1454 not returned unless the CKA_CLASS attribute in the template has the value CKO_HW_FEATURE. This 1455 protects applications written to previous versions of Cryptoki from finding objects that they do not 1456 understand. 1457

Table 13, Hardware Feature Common Attributes 1458


CKA_HW_FEATURE_TYPE1 CK_HW_FEATURE_TYPE Hardware feature (type)

- Refer to Table 11Table 11 for footnotes 1459


4.3.3 Clock 1460

4.3.3.1 Definition 1461

The CKA_HW_FEATURE_TYPE attribute takes the value CKH_CLOCK of type 1462 CK_HW_FEATURE_TYPE. 1463

4.3.3.2 Description 1464

Clock objects represent real-time clocks that exist on the device. This represents the same clock source 1465 as the utcTime field in the CK_TOKEN_INFO structure. 1466

Table 14, Clock Object Attributes 1467


CKA_VALUE CK_CHAR[16] Current time as a character-string of length 16, represented in the format YYYYMMDDhhmmssxx (4 characters for the year; 2 characters each for the month, the day, the hour, the minute, and the second; and 2 additional reserved ‘0’ characters).

The CKA_VALUE attribute may be set using the C_SetAttributeValue function if permitted by the 1468 device. The session used to set the time MUST be logged in. The device may require the SO to be the 1469 user logged in to modify the time value. C_SetAttributeValue will return the error 1470

CKR_USER_NOT_LOGGED_IN to indicate that a different user type is required to set the value. 1471

4.3.4 Monotonic Counter Objects 1472


The CKA_HW_FEATURE_TYPE attribute takes the value CKH_MONOTONIC_COUNTER of type 1474 CK_HW_FEATURE_TYPE. 1475


Monotonic counter objects represent hardware counters that exist on the device. The counter is 1477 guaranteed to increase each time its value is read, but not necessarily by one. This might be used by an 1478 application for generating serial numbers to get some assurance of uniqueness per token. 1479

Table 15, Monotonic Counter Attributes 1480


CKA_RESET_ON_INIT1 CK_BBOOL The value of the counter will reset to a

previously returned value if the token is initialized using C_InitToken.

CKA_HAS_RESET1 CK_BBOOL The value of the counter has been reset at

least once at some point in time.

CKA_VALUE1 Byte Array The current version of the monotonic counter.

The value is returned in big endian order.

1Read Only 1481

The CKA_VALUE attribute may not be set by the client. 1482

4.3.5 User Interface Objects 1483


The CKA_HW_FEATURE_TYPE attribute takes the value CKH_USER_INTERFACE of type 1485 CK_HW_FEATURE_TYPE. 1486



User interface objects represent the presentation capabilities of the device. 1488

Table 16, User Interface Object Attributes 1489

Attribute Data type Meaning

CKA_PIXEL_X CK_ULONG Screen resolution (in pixels) in X-axis (e.g. 1280)

CKA_PIXEL_Y CK_ULONG Screen resolution (in pixels) in Y-axis (e.g. 1024)

CKA_RESOLUTION CK_ULONG DPI, pixels per inch

CKA_CHAR_ROWS CK_ULONG For character-oriented displays; number of character rows (e.g. 24)

CKA_CHAR_COLUMNS CK_ULONG For character-oriented displays: number of character columns (e.g. 80). If display is of proportional-font type, this is the width of the display in “em”-s (letter “M”), see CC/PP Struct.

CKA_COLOR CK_BBOOL Color support

CKA_BITS_PER_PIXEL CK_ULONG The number of bits of color or grayscale information per pixel.

CKA_CHAR_SETS RFC 2279 string

String indicating supported character sets, as defined by IANA MIBenum sets (www.iana.org). Supported character sets are separated with “;”. E.g. a token supporting iso-8859-1 and US-ASCII would set the attribute value to “4;3”.

CKA_ENCODING_METHODS RFC 2279 string

String indicating supported content transfer encoding methods, as defined by IANA (www.iana.org). Supported methods are separated with “;”. E.g. a token supporting 7bit, 8bit and base64 could set the attribute value to “7bit;8bit;base64”.

CKA_MIME_TYPES RFC 2279 string

String indicating supported (presentable) MIME-types, as defined by IANA (www.iana.org). Supported types are separated with “;”. E.g. a token supporting MIME types "a/b", "a/c" and "a/d" would set the attribute value to “a/b;a/c;a/d”.

The selection of attributes, and associated data types, has been done in an attempt to stay as aligned 1490 with RFC 2534 and CC/PP Struct as possible. The special value CK_UNAVAILABLE_INFORMATION 1491 may be used for CK_ULONG-based attributes when information is not available or applicable. 1492

None of the attribute values may be set by an application. 1493

The value of the CKA_ENCODING_METHODS attribute may be used when the application needs to 1494

send MIME objects with encoded content to the token. 1495

4.4 Storage Objects 1496

This is not an object class; hence no CKO_ definition is required. It is a category of object classes with 1497 common attributes for the object classes that follow. 1498

http://www.iana.org/




Table 17, Common Storage Object Attributes 1499


CKA_TOKEN CK_BBOOL CK_TRUE if object is a token object; CK_FALSE if object is a session object. Default is CK_FALSE.

CKA_PRIVATE CK_BBOOL CK_TRUE if object is a private object; CK_FALSE if object is a public object. Default value is token-specific, and may depend on the values of other attributes of the object.

CKA_MODIFIABLE CK_BBOOL CK_TRUE if object can be modified Default is CK_TRUE.

CKA_LABEL RFC2279 string Description of the object (default empty).

CKA_COPYABLE CK_BBOOL CK_TRUE if object can be copied using C_CopyObject. Defaults to CK_TRUE. Can’t be set to TRUE once it is set to FALSE.

CKA_DESTROYABLE CK_BBOOL CK_TRUE if the object can be destroyed using C_DestroyObject. Default is CK_TRUE.

CKA_UNIQUE_ID246

RFC2279 string The unique identifier assigned to the object.

Only the CKA_LABEL attribute can be modified after the object is created. (The CKA_TOKEN, 1500 CKA_PRIVATE, and CKA_MODIFIABLE attributes can be changed in the process of copying an object, 1501

however.) 1502

The CKA_TOKEN attribute identifies whether the object is a token object or a session object. 1503

When the CKA_PRIVATE attribute is CK_TRUE, a user may not access the object until the user has 1504

been authenticated to the token. 1505

The value of the CKA_MODIFIABLE attribute determines whether or not an object is read-only. 1506

The CKA_LABEL attribute is intended to assist users in browsing. 1507

The value of the CKA_COPYABLE attribute determines whether or not an object can be copied. This 1508 attribute can be used in conjunction with CKA_MODIFIABLE to prevent changes to the permitted usages 1509 of keys and other objects. 1510

The value of the CKA_DESTROYABLE attribute determines whether the object can be destroyed using 1511 C_DestroyObject. 1512

4.4.1 The CKA_UNIQUE_ID attribute 1513

Any time a new object is created, a value for CKA_UNIQUE_ID MUST be generated by the token and 1514 stored with the object. The specific algorithm used to generate unique ID values for objects is token-1515 specific, but values generated MUST be unique across all objects visible to any particular session, and 1516 SHOULD be unique across all objects created by the token. Reinitializing the token, such as by calling 1517 C_InitToken, MAY cause reuse of CKA_UNIQUE_ID values. 1518

Any attempt to modify the CKA_UNIQUE_ID attribute of an existing object or to specify the value of the 1519 CKA_UNIQUE_ID attribute in the template for an operation that creates one or more objects MUST fail. 1520 Operations failing for this reason return the error code CKR_ATTRIBUTE_READ_ONLY. 1521

1522


4.5 Data objects 1523


This section defines the object class CKO_DATA for type CK_OBJECT_CLASS as used in the 1525 CKA_CLASS attribute of objects. 1526

4.5.2 Overview 1527

Data objects (object class CKO_DATA) hold information defined by an application. Other than providing 1528 access to it, Cryptoki does not attach any special meaning to a data object. The following table lists the 1529 attributes supported by data objects, in addition to the common attributes defined for this object class: 1530

Table 18, Data Object Attributes 1531


CKA_APPLICATION RFC2279 string

Description of the application that manages the object (default empty)

CKA_OBJECT_ID Byte Array DER-encoding of the object identifier indicating the data object type (default empty)

CKA_VALUE Byte array Value of the object (default empty)

The CKA_APPLICATION attribute provides a means for applications to indicate ownership of the data 1532 objects they manage. Cryptoki does not provide a means of ensuring that only a particular application has 1533 access to a data object, however. 1534

The CKA_OBJECT_ID attribute provides an application independent and expandable way to indicate the 1535 type of the data object value. Cryptoki does not provide a means of insuring that the data object identifier 1536 matches the data value. 1537

The following is a sample template containing attributes for creating a data object: 1538

CK_OBJECT_CLASS class = CKO_DATA; 1539 CK_UTF8CHAR label[] = “A data object”; 1540 CK_UTF8CHAR application[] = “An application”; 1541 CK_BYTE data[] = “Sample data”; 1542 CK_BBOOL true = CK_TRUE; 1543 CK_ATTRIBUTE template[] = { 1544 {CKA_CLASS, &class, sizeof(class)}, 1545 {CKA_TOKEN, &true, sizeof(true)}, 1546 {CKA_LABEL, label, sizeof(label)-1}, 1547 {CKA_APPLICATION, application, sizeof(application)-1}, 1548 {CKA_VALUE, data, sizeof(data)} 1549 }; 1550

1551

4.6 Certificate objects 1552


This section defines the object class CKO_CERTIFICATE for type CK_OBJECT_CLASS as used in the 1554 CKA_CLASS attribute of objects. 1555

4.6.2 Overview 1556

Certificate objects (object class CKO_CERTIFICATE) hold public-key or attribute certificates. Other than 1557 providing access to certificate objects, Cryptoki does not attach any special meaning to certificates. The 1558 following table defines the common certificate object attributes, in addition to the common attributes 1559 defined for this object class: 1560


Table 19, Common Certificate Object Attributes 1561


CKA_CERTIFICATE_TYPE1 CK_CERTIFICATE_TYPE Type of certificate

CKA_TRUSTED10

CK_BBOOL The certificate can be trusted for the application that it was created.

CKA_CERTIFICATE_CATEGORY

CKA_CERTIFICATE_CATEGORY

(default CK_CERTIFICATE_CATEGORY_UNSPECIFIED)

CKA_CHECK_VALUE Byte array Checksum

CKA_START_DATE CK_DATE Start date for the certificate (default empty)

CKA_END_DATE CK_DATE End date for the certificate (default empty)

CKA_PUBLIC_KEY_INFO Byte Array DER-encoding of the SubjectPublicKeyInfo for the public key contained in this certificate (default empty)


Cryptoki does not enforce the relationship of the CKA_PUBLIC_KEY_INFO to the public key in the 1563 certificate, but does recommend that the key be extracted from the certificate to create this value. 1564

The CKA_CERTIFICATE_TYPE attribute may not be modified after an object is created. This version of 1565 Cryptoki supports the following certificate types: 1566

X.509 public key certificate 1567

WTLS public key certificate 1568

X.509 attribute certificate 1569

The CKA_TRUSTED attribute cannot be set to CK_TRUE by an application. It MUST be set by a token 1570

initialization application or by the token’s SO. Trusted certificates cannot be modified. 1571

The CKA_CERTIFICATE_CATEGORY attribute is used to indicate if a stored certificate is a user 1572 certificate for which the corresponding private key is available on the token (“token user”), a CA certificate 1573 (“authority”), or another end-entity certificate (“other entity”). This attribute may not be modified after an 1574 object is created. 1575

The CKA_CERTIFICATE_CATEGORY and CKA_TRUSTED attributes will together be used to map to 1576 the categorization of the certificates. 1577

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

The CKA_START_DATE and CKA_END_DATE attributes are for reference only; Cryptoki does not 1580 attach any special meaning to them. When present, the application is responsible to set them to values 1581 that match the certificate’s encoded “not before” and “not after” fields (if any). 1582

4.6.3 X.509 public key certificate objects 1583

X.509 certificate objects (certificate type CKC_X_509) hold X.509 public key certificates. The following 1584 table defines the X.509 certificate object attributes, in addition to the common attributes defined for this 1585 object class: 1586

Table 20, X.509 Certificate Object Attributes 1587



CKA_SUBJECT1 Byte array DER-encoding of the certificate

subject name

CKA_ID Byte array Key identifier for public/private key pair (default empty)

CKA_ISSUER Byte array DER-encoding of the certificate issuer name (default empty)

CKA_SERIAL_NUMBER Byte array DER-encoding of the certificate serial number (default empty)

CKA_VALUE2 Byte array BER-encoding of the certificate

CKA_URL3 RFC2279

string If not empty this attribute gives the URL where the complete certificate can be obtained (default empty)

CKA_HASH_OF_SUBJECT_PUBLIC_KEY

4

Byte array Hash of the subject public key (default empty). Hash algorithm is defined by CKA_NAME_HASH_ALGORITHM

CKA_HASH_OF_ISSUER_PUBLIC_KEY

4

Byte array Hash of the issuer public key (default empty). Hash algorithm is defined by CKA_NAME_HASH_ALGORITHM

CKA_JAVA_MIDP_SECURITY_DOMAIN

CK_JAVA_MIDP_SECURITY_DOMAIN

Java MIDP security domain. (default CK_SECURITY_DOMAIN_UNSPECIFIED)

CKA_NAME_HASH_ALGORITHM

CK_MECHANISM_TYPE

Defines the mechanism used to calculate CKA_HASH_OF_SUBJECT_PUBLIC_KEY and CKA_HASH_OF_ISSUER_PUBLIC_KEY. If the attribute is not present then the type defaults to SHA-1.

1MUST be specified when the object is created.

1588

2MUST be specified when the object is created. MUST be non-empty if CKA_URL is empty. 1589

3MUST be non-empty if CKA_VALUE is empty. 1590

4Can only be empty if CKA_URL is empty. 1591

Only the CKA_ID, CKA_ISSUER, and CKA_SERIAL_NUMBER attributes may be modified after the 1592

object is created. 1593

The CKA_ID attribute is intended as a means of distinguishing multiple public-key/private-key pairs held 1594 by the same subject (whether stored in the same token or not). (Since the keys are distinguished by 1595 subject name as well as identifier, it is possible that keys for different subjects may have the same 1596 CKA_ID value without introducing any ambiguity.) 1597

It is intended in the interests of interoperability that the subject name and key identifier for a certificate will 1598 be the same as those for the corresponding public and private keys (though it is not required that all be 1599 stored in the same token). However, Cryptoki does not enforce this association, or even the uniqueness 1600 of the key identifier for a given subject; in particular, an application may leave the key identifier empty. 1601

The CKA_ISSUER and CKA_SERIAL_NUMBER attributes are for compatibility with PKCS #7 and 1602 Privacy Enhanced Mail (RFC1421). Note that with the version 3 extensions to X.509 certificates, the key 1603 identifier may be carried in the certificate. It is intended that the CKA_ID value be identical to the key 1604

identifier in such a certificate extension, although this will not be enforced by Cryptoki. 1605


The CKA_URL attribute enables the support for storage of the URL where the certificate can be found 1606 instead of the certificate itself. Storage of a URL instead of the complete certificate is often used in mobile 1607 environments. 1608

The CKA_HASH_OF_SUBJECT_PUBLIC_KEY and CKA_HASH_OF_ISSUER_PUBLIC_KEY 1609 attributes are used to store the hashes of the public keys of the subject and the issuer. They are 1610 particularly important when only the URL is available to be able to correlate a certificate with a private key 1611 and when searching for the certificate of the issuer. The hash algorithm is defined by 1612 CKA_NAME_HASH_ALGORITHM. 1613

The CKA_JAVA_MIDP_SECURITY_DOMAIN attribute associates a certificate with a Java MIDP security 1614

domain. 1615

The following is a sample template for creating an X.509 certificate object: 1616

CK_OBJECT_CLASS class = CKO_CERTIFICATE; 1617 CK_CERTIFICATE_TYPE certType = CKC_X_509; 1618 CK_UTF8CHAR label[] = “A certificate object”; 1619 CK_BYTE subject[] = {...}; 1620 CK_BYTE id[] = {123}; 1621 CK_BYTE certificate[] = {...}; 1622 CK_BBOOL true = CK_TRUE; 1623 CK_ATTRIBUTE template[] = { 1624 {CKA_CLASS, &class, sizeof(class)}, 1625 {CKA_CERTIFICATE_TYPE, &certType, sizeof(certType)}; 1626 {CKA_TOKEN, &true, sizeof(true)}, 1627 {CKA_LABEL, label, sizeof(label)-1}, 1628 {CKA_SUBJECT, subject, sizeof(subject)}, 1629 {CKA_ID, id, sizeof(id)}, 1630 {CKA_VALUE, certificate, sizeof(certificate)} 1631 }; 1632

4.6.4 WTLS public key certificate objects 1633

WTLS certificate objects (certificate type CKC_WTLS) hold WTLS public key certificates. The following 1634 table defines the WTLS certificate object attributes, in addition to the common attributes defined for this 1635 object class. 1636

Table 21: WTLS Certificate Object Attributes 1637


CKA_SUBJECT1 Byte array WTLS-encoding (Identifier type) of

the certificate subject

CKA_ISSUER Byte array WTLS-encoding (Identifier type) of the certificate issuer (default empty)

CKA_VALUE2 Byte array WTLS-encoding of the certificate

CKA_URL3 RFC2279

string If not empty this attribute gives the URL where the complete certificate can be obtained

CKA_HASH_OF_SUBJECT_PUBLIC_KEY

4

Byte array SHA-1 hash of the subject public key (default empty). Hash algorithm is defined by CKA_NAME_HASH_ALGORITHM

CKA_HASH_OF_ISSUER_PUBLIC_KEY

4

Byte array SHA-1 hash of the issuer public key (default empty). Hash algorithm is defined by CKA_NAME_HASH_ALGORITHM

CKA_NAME_HASH_ALGORITHM

CK_MECHANISM_TYPE

Defines the mechanism used to calculate CKA_HASH_OF_SUBJECT_PUBLIC



_KEY and CKA_HASH_OF_ISSUER_PUBLIC_KEY. If the attribute is not present then the type defaults to SHA-1.

1MUST be specified when the object is created. Can only be empty if CKA_VALUE is empty. 1638

2MUST be specified when the object is created. MUST be non-empty if CKA_URL is empty. 1639

3MUST be non-empty if CKA_VALUE is empty. 1640

4Can only be empty if CKA_URL is empty. 1641

1642

Only the CKA_ISSUER attribute may be modified after the object has been created. 1643

The encoding for the CKA_SUBJECT, CKA_ISSUER, and CKA_VALUE attributes can be found in 1644

[WTLS]. 1645

The CKA_URL attribute enables the support for storage of the URL where the certificate can be found 1646 instead of the certificate itself. Storage of a URL instead of the complete certificate is often used in mobile 1647 environments. 1648

The CKA_HASH_OF_SUBJECT_PUBLIC_KEY and CKA_HASH_OF_ISSUER_PUBLIC_KEY 1649 attributes are used to store the hashes of the public keys of the subject and the issuer. They are 1650 particularly important when only the URL is available to be able to correlate a certificate with a private key 1651 and when searching for the certificate of the issuer. The hash algorithm is defined by 1652 CKA_NAME_HASH_ALGORITHM. 1653

The following is a sample template for creating a WTLS certificate object: 1654

CK_OBJECT_CLASS class = CKO_CERTIFICATE; 1655 CK_CERTIFICATE_TYPE certType = CKC_WTLS; 1656 CK_UTF8CHAR label[] = “A certificate object”; 1657 CK_BYTE subject[] = {...}; 1658 CK_BYTE certificate[] = {...}; 1659 CK_BBOOL true = CK_TRUE; 1660 CK_ATTRIBUTE template[] = 1661 { 1662 {CKA_CLASS, &class, sizeof(class)}, 1663 {CKA_CERTIFICATE_TYPE, &certType, sizeof(certType)}; 1664 {CKA_TOKEN, &true, sizeof(true)}, 1665 {CKA_LABEL, label, sizeof(label)-1}, 1666 {CKA_SUBJECT, subject, sizeof(subject)}, 1667 {CKA_VALUE, certificate, sizeof(certificate)} 1668 }; 1669

4.6.5 X.509 attribute certificate objects 1670

X.509 attribute certificate objects (certificate type CKC_X_509_ATTR_CERT) hold X.509 attribute 1671 certificates. The following table defines the X.509 attribute certificate object attributes, in addition to the 1672 common attributes defined for this object class: 1673


Table 22, X.509 Attribute Certificate Object Attributes 1674


CKA_OWNER1 Byte Array DER-encoding of the attribute certificate's subject

field. This is distinct from the CKA_SUBJECT attribute contained in CKC_X_509 certificates because the ASN.1 syntax and encoding are different.

CKA_AC_ISSUER Byte Array DER-encoding of the attribute certificate's issuer field. This is distinct from the CKA_ISSUER attribute contained in CKC_X_509 certificates because the ASN.1 syntax and encoding are different. (default empty)

CKA_SERIAL_NUMBER Byte Array DER-encoding of the certificate serial number. (default empty)

CKA_ATTR_TYPES Byte Array BER-encoding of a sequence of object identifier values corresponding to the attribute types contained in the certificate. When present, this field offers an opportunity for applications to search for a particular attribute certificate without fetching and parsing the certificate itself. (default empty)

CKA_VALUE1 Byte Array BER-encoding of the certificate.

1MUST be specified when the object is created 1675

Only the CKA_AC_ISSUER, CKA_SERIAL_NUMBER and CKA_ATTR_TYPES attributes may be 1676

modified after the object is created. 1677

The following is a sample template for creating an X.509 attribute certificate object: 1678

CK_OBJECT_CLASS class = CKO_CERTIFICATE; 1679 CK_CERTIFICATE_TYPE certType = CKC_X_509_ATTR_CERT; 1680 CK_UTF8CHAR label[] = "An attribute certificate object"; 1681 CK_BYTE owner[] = {...}; 1682 CK_BYTE certificate[] = {...}; 1683 CK_BBOOL true = CK_TRUE; 1684 CK_ATTRIBUTE template[] = { 1685 {CKA_CLASS, &class, sizeof(class)}, 1686 {CKA_CERTIFICATE_TYPE, &certType, sizeof(certType)}; 1687 {CKA_TOKEN, &true, sizeof(true)}, 1688 {CKA_LABEL, label, sizeof(label)-1}, 1689 {CKA_OWNER, owner, sizeof(owner)}, 1690 {CKA_VALUE, certificate, sizeof(certificate)} 1691 }; 1692

4.7 Key objects 1693


There is no CKO_ definition for the base key object class, only for the key types derived from it. 1695

This section defines the object class CKO_PUBLIC_KEY, CKO_PRIVATE_KEY and 1696 CKO_SECRET_KEY for type CK_OBJECT_CLASS as used in the CKA_CLASS attribute of objects. 1697

4.7.2 Overview 1698

Key objects hold encryption or authentication keys, which can be public keys, private keys, or secret 1699 keys. The following common footnotes apply to all the tables describing attributes of keys: 1700

The following table defines the attributes common to public key, private key and secret key classes, in 1701 addition to the common attributes defined for this object class: 1702


Table 23, Common Key Attributes 1703


CKA_KEY_TYPE1,5

CK_KEY_TYPE Type of key

CKA_ID8 Byte array Key identifier for key (default empty)

CKA_START_DATE8 CK_DATE Start date for the key (default empty)

CKA_END_DATE8 CK_DATE End date for the key (default empty)

CKA_DERIVE8 CK_BBOOL CK_TRUE if key supports key derivation

(i.e., if other keys can be derived from this one (default CK_FALSE)

CKA_LOCAL2,4,6

CK_BBOOL CK_TRUE only if key was either

generated locally (i.e., on the token) with a C_GenerateKey or C_GenerateKeyPair call

created with a C_CopyObject call as a copy of a key which had its CKA_LOCAL attribute set to CK_TRUE

CKA_KEY_GEN_ MECHANISM

2,4,6

CK_MECHANISM_TYPE

Identifier of the mechanism used to generate the key material.

CKA_ALLOWED_MECHANISMS

CK_MECHANISM_TYPE _PTR, pointer to a CK_MECHANISM_TYPE array

A list of mechanisms allowed to be used with this key. The number of mechanisms in the array is the ulValueLen component of the attribute divided by the size

of CK_MECHANISM_TYPE.


The CKA_ID field is intended to distinguish among multiple keys. In the case of public and private keys, 1705 this field assists in handling multiple keys held by the same subject; the key identifier for a public key and 1706 its corresponding private key should be the same. The key identifier should also be the same as for the 1707 corresponding certificate, if one exists. Cryptoki does not enforce these associations, however. (See 1708 Section 04.6 for further commentary.) 1709

In the case of secret keys, the meaning of the CKA_ID attribute is up to the application. 1710

Note that the CKA_START_DATE and CKA_END_DATE attributes are for reference only; Cryptoki does 1711 not attach any special meaning to them. In particular, it does not restrict usage of a key according to the 1712 dates; doing this is up to the application. 1713

The CKA_DERIVE attribute has the value CK_TRUE if and only if it is possible to derive other keys from 1714

the key. 1715

The CKA_LOCAL attribute has the value CK_TRUE if and only if the value of the key was originally 1716 generated on the token by a C_GenerateKey or C_GenerateKeyPair call. 1717

The CKA_KEY_GEN_MECHANISM attribute identifies the key generation mechanism used to generate 1718 the key material. It contains a valid value only if the CKA_LOCAL attribute has the value CK_TRUE. If 1719 CKA_LOCAL has the value CK_FALSE, the value of the attribute is 1720

CK_UNAVAILABLE_INFORMATION. 1721

4.8 Public key objects 1722

Public key objects (object class CKO_PUBLIC_KEY) hold public keys. The following table defines the 1723 attributes common to all public keys, in addition to the common attributes defined for this object class: 1724


Table 24, Common Public Key Attributes 1725


CKA_SUBJECT8 Byte array DER-encoding of the key subject

name (default empty)

CKA_ENCRYPT8 CK_BBOOL CK_TRUE if key supports

encryption9

CKA_VERIFY8 CK_BBOOL CK_TRUE if key supports verification

where the signature is an appendix to the data

9

CKA_VERIFY_RECOVER8 CK_BBOOL CK_TRUE if key supports verification

where the data is recovered from the signature

9

CKA_WRAP8 CK_BBOOL CK_TRUE if key supports wrapping

(i.e., can be used to wrap other keys)

9

CKA_TRUSTED10

CK_BBOOL The key can be trusted for the application that it was created.

The wrapping key can be used to wrap keys with CKA_WRAP_WITH_TRUSTED set to CK_TRUE.

CKA_WRAP_TEMPLATE CK_ATTRIBUTE_PTR For wrapping keys. The attribute template to match against any keys wrapped using this wrapping key. Keys that do not match cannot be wrapped. The number of attributes in the array is the ulValueLen component of the attribute divided by the size of CK_ATTRIBUTE.

CKA_PUBLIC_KEY_INFO Byte array DER-encoding of the SubjectPublicKeyInfo for this public key. (MAY be empty, DEFAULT derived from the underlying public key data)


It is intended in the interests of interoperability that the subject name and key identifier for a public key will 1727 be the same as those for the corresponding certificate and private key. However, Cryptoki does not 1728 enforce this, and it is not required that the certificate and private key also be stored on the token. 1729

To map between ISO/IEC 9594-8 (X.509) keyUsage flags for public keys and the PKCS #11 attributes for 1730

public keys, use the following table. 1731


Table 25, Mapping of X.509 key usage flags to Cryptoki attributes for public keys 1732

Key usage flags for public keys in X.509 public key certificates

Corresponding cryptoki attributes for public keys.

dataEncipherment CKA_ENCRYPT

digitalSignature, keyCertSign, cRLSign CKA_VERIFY

digitalSignature, keyCertSign, cRLSign CKA_VERIFY_RECOVER

keyAgreement CKA_DERIVE

keyEncipherment CKA_WRAP

nonRepudiation CKA_VERIFY

nonRepudiation CKA_VERIFY_RECOVER

The value of the CKA_PUBLIC_KEY_INFO attribute is the DER encoded value of SubjectPublicKeyInfo: 1733

SubjectPublicKeyInfo ::= SEQUENCE { 1734

algorithm AlgorithmIdentifier, 1735

subjectPublicKey BIT_STRING } 1736

The encodings for the subjectPublicKey field are specified in the description of the public key types in the 1737 appropriate [PKCS11-Curr] document for the key types defined within this specification. 1738

4.9 Private key objects 1739

Private key objects (object class CKO_PRIVATE_KEY) hold private keys. The following table defines the 1740 attributes common to all private keys, in addition to the common attributes defined for this object class: 1741

Table 26, Common Private Key Attributes 1742


CKA_SUBJECT8 Byte array DER-encoding of certificate

subject name (default empty)

CKA_SENSITIVE8,11

CK_BBOOL CK_TRUE if key is sensitive9

CKA_DECRYPT8 CK_BBOOL CK_TRUE if key supports

decryption9

CKA_SIGN8 CK_BBOOL CK_TRUE if key supports

signatures where the signature is an appendix to the data

9

CKA_SIGN_RECOVER8 CK_BBOOL CK_TRUE if key supports

signatures where the data can be recovered from the signature

9

CKA_UNWRAP8 CK_BBOOL CK_TRUE if key supports

unwrapping (i.e., can be used to unwrap other keys)

9

CKA_EXTRACTABLE8,12

CK_BBOOL CK_TRUE if key is extractable and can be wrapped

9

CKA_ALWAYS_SENSITIVE2,4,6

CK_BBOOL CK_TRUE if key has always had the CKA_SENSITIVE attribute set to CK_TRUE

CKA_NEVER_EXTRACTABLE2,4,6

CK_BBOOL CK_TRUE if key has never had the CKA_EXTRACTABLE attribute set to CK_TRUE

CKA_WRAP_WITH_TRUSTED11

CK_BBOOL CK_TRUE if the key can only be wrapped with a wrapping key that has CKA_TRUSTED set to CK_TRUE.



Default is CK_FALSE.

CKA_UNWRAP_TEMPLATE CK_ATTRIBUTE_PTR For wrapping keys. The attribute template to apply to any keys unwrapped using this wrapping key. Any user supplied template is applied after this template as if the object has already been created. The number of attributes in the array is the ulValueLen component of the attribute divided by the size of

CK_ATTRIBUTE.

CKA_ALWAYS_AUTHENTICATE CK_BBOOL If CK_TRUE, the user has to supply the PIN for each use (sign or decrypt) with the key. Default is CK_FALSE.

CKA_PUBLIC_KEY_INFO8 Byte Array DER-encoding of the

SubjectPublicKeyInfo for the associated public key (MAY be empty; DEFAULT derived from the underlying private key data; MAY be manually set for specific key types; if set; MUST be consistent with the underlying private key data)

CKA_DERIVE_TEMPLATE CK_ATTRIBUTE_PTR For deriving keys. The attribute template to match against any keys derived using this derivation key. Any user supplied template is applied after this template as if the object has already been created. The number of attributes in the array is the ulValueLen component of the attribute divided by the size of CK_ATTRIBUTE.


It is intended in the interests of interoperability that the subject name and key identifier for a private key 1744 will be the same as those for the corresponding certificate and public key. However, this is not enforced 1745 by Cryptoki, and it is not required that the certificate and public key also be stored on the token. 1746

If the CKA_SENSITIVE attribute is CK_TRUE, or if the CKA_EXTRACTABLE attribute is CK_FALSE, 1747 then certain attributes of the private key cannot be revealed in plaintext outside the token. Which 1748 attributes these are is specified for each type of private key in the attribute table in the section describing 1749 that type of key. 1750

The CKA_ALWAYS_AUTHENTICATE attribute can be used to force re-authentication (i.e. force the user 1751 to provide a PIN) for each use of a private key. “Use” in this case means a cryptographic operation such 1752 as sign or decrypt. This attribute may only be set to CK_TRUE when CKA_PRIVATE is also CK_TRUE. 1753

Re-authentication occurs by calling C_Login with userType set to CKU_CONTEXT_SPECIFIC 1754 immediately after a cryptographic operation using the key has been initiated (e.g. after C_SignInit). In 1755 this call, the actual user type is implicitly given by the usage requirements of the active key. If C_Login 1756 returns CKR_OK the user was successfully authenticated and this sets the active key in an authenticated 1757 state that lasts until the cryptographic operation has successfully or unsuccessfully been completed (e.g. 1758


by C_Sign, C_SignFinal,..). A return value CKR_PIN_INCORRECT from C_Login means that the user 1759 was denied permission to use the key and continuing the cryptographic operation will result in a behavior 1760 as if C_Login had not been called. In both of these cases the session state will remain the same, 1761 however repeated failed re-authentication attempts may cause the PIN to be locked. C_Login returns in 1762 this case CKR_PIN_LOCKED and this also logs the user out from the token. Failing or omitting to re-1763 authenticate when CKA_ALWAYS_AUTHENTICATE is set to CK_TRUE will result in 1764 CKR_USER_NOT_LOGGED_IN to be returned from calls using the key. C_Login will return 1765 CKR_OPERATION_NOT_INITIALIZED, but the active cryptographic operation will not be affected, if an 1766 attempt is made to re-authenticate when CKA_ALWAYS_AUTHENTICATE is set to CK_FALSE. 1767

The CKA_PUBLIC_KEY_INFO attribute represents the public key associated with this private key. The 1768 data it represents may either be stored as part of the private key data, or regenerated as needed from the 1769 private key. 1770

If this attribute is supplied as part of a template for C_CreateObject, C_CopyObject or 1771 C_SetAttributeValue for a private key, the token MUST verify correspondence between the private key 1772 data and the public key data as supplied in CKA_PUBLIC_KEY_INFO. This can be done either by 1773 deriving a public key from the private key and comparing the values, or by doing a sign and verify 1774 operation. If there is a mismatch, the command SHALL return CKR_ATTRIBUTE_VALUE_INVALID. A 1775 token MAY choose not to support the CKA_PUBLIC_KEY_INFO attribute for commands which create 1776 new private keys. If it does not support the attribute, the command SHALL return 1777 CKR_ATTRIBUTE_TYPE_INVALID. 1778

As a general guideline, private keys of any type SHOULD store sufficient information to retrieve the public 1779 key information. In particular, the RSA private key description has been modified in <this version>PKCS 1780 #11 V2.40 to add the CKA_PUBLIC_EXPONENT to the list of attributes required for an RSA private key. 1781 All other private key types described in this specification contain sufficient information to recover the 1782 associated public key. 1783

4.10 Secret key objects 1784

Secret key objects (object class CKO_SECRET_KEY) hold secret keys. The following table defines the 1785

attributes common to all secret keys, in addition to the common attributes defined for this object class: 1786

Table 27, Common Secret Key Attributes 1787


CKA_SENSITIVE8,11

CK_BBOOL CK_TRUE if object is sensitive (default CK_FALSE)

CKA_ENCRYPT8 CK_BBOOL CK_TRUE if key supports

encryption9

CKA_DECRYPT8 CK_BBOOL CK_TRUE if key supports

decryption9

CKA_SIGN8 CK_BBOOL CK_TRUE if key supports

signatures (i.e., authentication codes) where the signature is an appendix to the data

9

CKA_VERIFY8 CK_BBOOL CK_TRUE if key supports

verification (i.e., of authentication codes) where the signature is an appendix to the data

9

CKA_WRAP8 CK_BBOOL CK_TRUE if key supports

wrapping (i.e., can be used to wrap other keys)

9

CKA_UNWRAP8 CK_BBOOL CK_TRUE if key supports

unwrapping (i.e., can be used to unwrap other keys)

9

CKA_EXTRACTABLE8,12

CK_BBOOL CK_TRUE if key is extractable



and can be wrapped 9

CKA_ALWAYS_SENSITIVE2,4,6

CK_BBOOL CK_TRUE if key has always had the CKA_SENSITIVE attribute set to CK_TRUE

CKA_NEVER_EXTRACTABLE2,4,6

CK_BBOOL CK_TRUE if key has never had the CKA_EXTRACTABLE attribute set to CK_TRUE

CKA_CHECK_VALUE Byte array Key checksum

CKA_WRAP_WITH_TRUSTED11

CK_BBOOL CK_TRUE if the key can only be wrapped with a wrapping key that has CKA_TRUSTED set to CK_TRUE.

Default is CK_FALSE.

CKA_TRUSTED10

CK_BBOOL The wrapping key can be used to wrap keys with CKA_WRAP_WITH_TRUSTED set to CK_TRUE.

CKA_WRAP_TEMPLATE CK_ATTRIBUTE_PTR For wrapping keys. The attribute template to match against any keys wrapped using this wrapping key. Keys that do not match cannot be wrapped. The number of attributes in the array is the

ulValueLen component of the attribute divided by the size of

CK_ATTRIBUTE

CKA_UNWRAP_TEMPLATE CK_ATTRIBUTE_PTR For wrapping keys. The attribute template to apply to any keys unwrapped using this wrapping key. Any user supplied template is applied after this template as if the object has already been created. The number of attributes in the array is the ulValueLen component of the attribute divided by the size of

CK_ATTRIBUTE.

A_DERIVE_TEMPLATE CK_ATTRIBUTE_PTR For deriving keys. The attribute template to match against any keys derived using this derivation key. Any user supplied template is applied after this template as if the object has already been created. The number of attributes in the array is the ulValueLen component of the attribute divided by the size of CK_ATTRIBUTE.


If the CKA_SENSITIVE attribute is CK_TRUE, or if the CKA_EXTRACTABLE attribute is CK_FALSE, 1789 then certain attributes of the secret key cannot be revealed in plaintext outside the token. Which 1790


attributes these are is specified for each type of secret key in the attribute table in the section describing 1791 that type of key. 1792

The key check value (KCV) attribute for symmetric key objects to be called CKA_CHECK_VALUE, of 1793 type byte array, length 3 bytes, operates like a fingerprint, or checksum of the key. They are intended to 1794 be used to cross-check symmetric keys against other systems where the same key is shared, and as a 1795 validity check after manual key entry or restore from backup. Refer to object definitions of specific key 1796 types for KCV algorithms. 1797

Properties: 1798

1. For two keys that are cryptographically identical the value of this attribute should be identical. 1799

2. CKA_CHECK_VALUE should not be usable to obtain any part of the key value. 1800

3. Non-uniqueness. Two different keys can have the same CKA_CHECK_VALUE. This is unlikely 1801 (the probability can easily be calculated) but possible. 1802

The attribute is optional, but if supported, regardless of how the key object is created or derived, the value 1803 of the attribute is always supplied. It SHALL be supplied even if the encryption operation for the key is 1804 forbidden (i.e. when CKA_ENCRYPT is set to CK_FALSE). 1805

If a value is supplied in the application template (allowed but never necessary) then, if supported, it MUST 1806 match what the library calculates it to be or the library returns a CKR_ATTRIBUTE_VALUE_INVALID. If 1807 the library does not support the attribute then it should ignore it. Allowing the attribute in the template this 1808 way does no harm and allows the attribute to be treated like any other attribute for the purposes of key 1809 wrap and unwrap where the attributes are preserved also. 1810

The generation of the KCV may be prevented by the application supplying the attribute in the template as 1811 a no-value (0 length) entry. The application can query the value at any time like any other attribute using 1812 C_GetAttributeValue. C_SetAttributeValue may be used to destroy the attribute, by supplying no-value. 1813

Unless otherwise specified for the object definition, the value of this attribute is derived from the key 1814 object by taking the first three bytes of an encryption of a single block of null (0x00) bytes, using the 1815 default cipher and mode (e.g. ECB) associated with the key type of the secret key object. 1816

4.11 Domain parameter objects 1817


This section defines the object class CKO_DOMAIN_PARAMETERS for type CK_OBJECT_CLASS as 1819 used in the CKA_CLASS attribute of objects. 1820

4.11.2 Overview 1821

This object class was created to support the storage of certain algorithm's extended parameters. DSA 1822 and DH both use domain parameters in the key-pair generation step. In particular, some libraries support 1823 the generation of domain parameters (originally out of scope for PKCS11) so the object class was added. 1824

To use a domain parameter object you MUST extract the attributes into a template and supply them (still 1825 in the template) to the corresponding key-pair generation function. 1826

Domain parameter objects (object class CKO_DOMAIN_PARAMETERS) hold public domain parameters. 1827

The following table defines the attributes common to domain parameter objects in addition to the common 1828 attributes defined for this object class: 1829

Table 28, Common Domain Parameter Attributes 1830



CKA_KEY_TYPE1 CK_KEY_TYPE Type of key the domain parameters can be

used to generate.

CKA_LOCAL2,4

CK_BBOOL CK_TRUE only if domain parameters were either

generated locally (i.e., on the token) with a C_GenerateKey

created with a C_CopyObject call as a copy of domain parameters which had its CKA_LOCAL attribute set to CK_TRUE


The CKA_LOCAL attribute has the value CK_TRUE if and only if the values of the domain parameters 1832 were originally generated on the token by a C_GenerateKey call. 1833

4.12 Mechanism objects 1834


This section defines the object class CKO_MECHANISM for type CK_OBJECT_CLASS as used in the 1836 CKA_CLASS attribute of objects. 1837


Mechanism objects provide information about mechanisms supported by a device beyond that given by 1839 the CK_MECHANISM_INFO structure. 1840

When searching for objects using C_FindObjectsInit and C_FindObjects, mechanism objects are not 1841 returned unless the CKA_CLASS attribute in the template has the value CKO_MECHANISM. This 1842 protects applications written to previous versions of Cryptoki from finding objects that they do not 1843 understand. 1844

Table 29, Common Mechanism Attributes 1845


CKA_MECHANISM_TYPE CK_MECHANISM_TYPE The type of mechanism object

The CKA_MECHANISM_TYPE attribute may not be set. 1846

1847

4.13 Profile objects 1848


This section defines the object class CKO_PROFILE for type CK_OBJECT_CLASS as used in the 1850 CKA_CLASS attribute of objects. 1851


Profile objects (object class CKO_PROFILE) describe which PKCS #11 profiles the token implements. 1853 Profiles are defined in the OASIS PKCS #11 Cryptographic Token Interface Profiles document. A given 1854 token can contain more than one profile ID. The following table lists the attributes supported by profile 1855 objects, in addition to the common attributes defined for this object class: 1856

Table 30, Profile Object Attributes 1857



CKA_PROFILE_ID CK_PROFILE_ID ID of the supported profile.

The CKA_PROFILE_ID attribute identifies a profile that the token supports. 1858


5 Functions 1859

Cryptoki's functions are organized into the following categories: 1860

general-purpose functions (4 functions) 1861

slot and token management functions (9 functions) 1862

session management functions (8 functions) 1863

object management functions (9 functions) 1864

encryption functions (4 functions) 1865

message-based encryption functions (5 functions) 1866

decryption functions (4 functions) 1867

message digesting functions (5 functions) 1868

signing and MACing functions (6 functions) 1869

functions for verifying signatures and MACs (6 functions) 1870

dual-purpose cryptographic functions (4 functions) 1871

key management functions (5 functions) 1872

random number generation functions (2 functions) 1873

parallel function management functions (2 functions) 1874

1875

In addition to these functions, Cryptoki can use application-supplied callback functions to notify an 1876 application of certain events, and can also use application-supplied functions to handle mutex objects for 1877 safe multi-threaded library access. 1878

The Cryptoki API functions are presented in the following table: 1879

Table 31, Summary of Cryptoki Functions 1880

Category Function Description

General C_Initialize initializes Cryptoki

purpose functions

C_Finalize clean up miscellaneous Cryptoki-associated resources

C_GetInfo obtains general information about Cryptoki

C_GetFunctionList obtains entry points of Cryptoki library functions

C_GetInterfaceList obtains list of interfaces supported by Cryptoki library

C_GetInterface obtains interface specific entry points to Cryptoki library functions

Slot and token C_GetSlotList obtains a list of slots in the system

management C_GetSlotInfo obtains information about a particular slot

functions C_GetTokenInfo obtains information about a particular token

C_WaitForSlotEvent waits for a slot event (token insertion, removal, etc.) to occur

C_GetMechanismList obtains a list of mechanisms supported by a token

C_GetMechanismInfo obtains information about a particular mechanism



C_InitToken initializes a token

C_InitPIN initializes the normal user’s PIN

C_SetPIN modifies the PIN of the current user

Session management functions

C_OpenSession opens a connection between an application and a particular token or sets up an application callback for token insertion

C_CloseSession closes a session

C_CloseAllSessions closes all sessions with a token

C_GetSessionInfo obtains information about the session

C_SessionCancel terminates active session based operations

C_GetOperationState obtains the cryptographic operations state of a session

C_SetOperationState sets the cryptographic operations state of a session

C_Login logs into a token

C_LoginUser logs into a token with explicit user name

C_Logout logs out from a token

Object C_CreateObject creates an object

management C_CopyObject creates a copy of an object

functions C_DestroyObject destroys an object

C_GetObjectSize obtains the size of an object in bytes

C_GetAttributeValue obtains an attribute value of an object

C_SetAttributeValue modifies an attribute value of an object

C_FindObjectsInit initializes an object search operation

C_FindObjects continues an object search operation

C_FindObjectsFinal finishes an object search operation

Encryption C_EncryptInit initializes an encryption operation

functions C_Encrypt encrypts single-part data

C_EncryptUpdate continues a multiple-part encryption operation

C_EncryptFinal finishes a multiple-part encryption operation

Message-based Encryption Functions

C_MessageEncryptInit initializes a message-based encryption process

C_EncryptMessage encrypts a single-part message

C_EncryptMessageBegin begins a multiple-part message encryption operation

C_EncryptMessageNext continues or finishes a multiple-part message encryption operation

C_MessageEncryptFinal finishes a message-based encryption process

Decryption C_DecryptInit initializes a decryption operation

Functions C_Decrypt decrypts single-part encrypted data

C_DecryptUpdate continues a multiple-part decryption operation

C_DecryptFinal finishes a multiple-part decryption operation

Message-based

Decryption

Functions

C_MessageDecryptInit initializes a message decryption operation

C_DecryptMessage decrypts single-part data

C_DecryptMessageBegin starts a multiple-part message decryption operation



C_DecryptMessageNext Continues and finishes a multiple-part message decryption operation

C_MessageDecryptFinal finishes a message decryption operation

Message C_DigestInit initializes a message-digesting operation

Digesting C_Digest digests single-part data

Functions C_DigestUpdate continues a multiple-part digesting operation

C_DigestKey digests a key

C_DigestFinal finishes a multiple-part digesting operation

Signing C_SignInit initializes a signature operation

and MACing C_Sign signs single-part data

functions C_SignUpdate continues a multiple-part signature operation

C_SignFinal finishes a multiple-part signature operation

C_SignRecoverInit initializes a signature operation, where the data can be recovered from the signature

C_SignRecover signs single-part data, where the data can be recovered from the signature

Message-based Signature functions

C_MessageSignInit initializes a message signature operation

C_SignMessage signs single-part data

C_SignMessageBegin starts a multiple-part message signature operation

C_SignMessageNext continues and finishes a multiple-part message signature operation

C_MessageSignFinal finishes a message signature operation

Functions for verifying

C_VerifyInit initializes a verification operation

signatures C_Verify verifies a signature on single-part data

and MACs C_VerifyUpdate continues a multiple-part verification operation

C_VerifyFinal finishes a multiple-part verification operation

C_VerifyRecoverInit initializes a verification operation where the data is recovered from the signature

C_VerifyRecover verifies a signature on single-part data, where the data is recovered from the signature

Message-based Functions for verifying signatures and MACs

C_MessageVerifyInit initializes a message verification operation

C_VerifyMessage verifies single-part data

C_VerifyMessageBegin starts a multiple-part message verification operation

C_VerifyMessageNext continues and finishes a multiple-part message verification operation

C_MessageVerifyFinal finishes a message verification operation

Dual-purpose cryptographic

C_DigestEncryptUpdate continues simultaneous multiple-part digesting and encryption operations

functions C_DecryptDigestUpdate continues simultaneous multiple-part decryption and digesting operations

C_SignEncryptUpdate continues simultaneous multiple-part signature and encryption operations

C_DecryptVerifyUpdate continues simultaneous multiple-part decryption and verification operations



Key C_GenerateKey generates a secret key

management C_GenerateKeyPair generates a public-key/private-key pair

functions C_WrapKey wraps (encrypts) a key

C_UnwrapKey unwraps (decrypts) a key

C_DeriveKey derives a key from a base key

Random number generation

C_SeedRandom mixes in additional seed material to the random number generator

functions C_GenerateRandom generates random data

Parallel function management

C_GetFunctionStatus legacy function which always returns CKR_FUNCTION_NOT_PARALLEL

functions C_CancelFunction legacy function which always returns CKR_FUNCTION_NOT_PARALLEL

Callback function application-supplied function to process notifications from Cryptoki

1881

Execution of a Cryptoki function call is in general an all-or-nothing affair, i.e., a function call accomplishes 1882

either its entire goal, or nothing at all. 1883

If a Cryptoki function executes successfully, it returns the value CKR_OK. 1884

If a Cryptoki function does not execute successfully, it returns some value other than CKR_OK, and 1885 the token is in the same state as it was in prior to the function call. If the function call was supposed 1886 to modify the contents of certain memory addresses on the host computer, these memory addresses 1887 may have been modified, despite the failure of the function. 1888

In unusual (and extremely unpleasant!) circumstances, a function can fail with the return value 1889 CKR_GENERAL_ERROR. When this happens, the token and/or host computer may be in an 1890 inconsistent state, and the goals of the function may have been partially achieved. 1891

There are a small number of Cryptoki functions whose return values do not behave precisely as 1892 described above; these exceptions are documented individually with the description of the functions 1893 themselves. 1894

A Cryptoki library need not support every function in the Cryptoki API. However, even an unsupported 1895 function MUST have a “stub” in the library which simply returns the value 1896 CKR_FUNCTION_NOT_SUPPORTED. The function’s entry in the library’s CK_FUNCTION_LIST 1897 structure (as obtained by C_GetFunctionList) should point to this stub function (see Section 3.6). 1898

5.1 Function return values 1899

The Cryptoki interface possesses a large number of functions and return values. In Section 5.1, we 1900 enumerate the various possible return values for Cryptoki functions; most of the remainder of Section 5.1 1901 details the behavior of Cryptoki functions, including what values each of them may return. 1902

Because of the complexity of the Cryptoki specification, it is recommended that Cryptoki applications 1903 attempt to give some leeway when interpreting Cryptoki functions’ return values. We have attempted to 1904 specify the behavior of Cryptoki functions as completely as was feasible; nevertheless, there are 1905 presumably some gaps. For example, it is possible that a particular error code which might apply to a 1906 particular Cryptoki function is unfortunately not actually listed in the description of that function as a 1907 possible error code. It is conceivable that the developer of a Cryptoki library might nevertheless permit 1908 his/her implementation of that function to return that error code. It would clearly be somewhat ungraceful 1909 if a Cryptoki application using that library were to terminate by abruptly dumping core upon receiving that 1910 error code for that function. It would be far preferable for the application to examine the function’s return 1911 value, see that it indicates some sort of error (even if the application doesn’t know precisely what kind of 1912 error), and behave accordingly. 1913


See Section 5.1.8 for some specific details on how a developer might attempt to make an application that 1914 accommodates a range of behaviors from Cryptoki libraries. 1915

5.1.1 Universal Cryptoki function return values 1916

Any Cryptoki function can return any of the following values: 1917

CKR_GENERAL_ERROR: Some horrible, unrecoverable error has occurred. In the worst case, it is 1918 possible that the function only partially succeeded, and that the computer and/or token is in an 1919 inconsistent state. 1920

CKR_HOST_MEMORY: The computer that the Cryptoki library is running on has insufficient memory 1921 to perform the requested function. 1922

CKR_FUNCTION_FAILED: The requested function could not be performed, but detailed information 1923 about why not is not available in this error return. If the failed function uses a session, it is possible 1924 that the CK_SESSION_INFO structure that can be obtained by calling C_GetSessionInfo will hold 1925 useful information about what happened in its ulDeviceError field. In any event, although the function 1926 call failed, the situation is not necessarily totally hopeless, as it is likely to be when 1927 CKR_GENERAL_ERROR is returned. Depending on what the root cause of the error actually was, it 1928 is possible that an attempt to make the exact same function call again would succeed. 1929

CKR_OK: The function executed successfully. Technically, CKR_OK is not quite a “universal” return 1930 value; in particular, the legacy functions C_GetFunctionStatus and C_CancelFunction (see Section 1931 5.20) cannot return CKR_OK. 1932

The relative priorities of these errors are in the order listed above, e.g., if either of 1933 CKR_GENERAL_ERROR or CKR_HOST_MEMORY would be an appropriate error return, then 1934 CKR_GENERAL_ERROR should be returned. 1935

5.1.2 Cryptoki function return values for functions that use a session 1936

handle 1937

Any Cryptoki function that takes a session handle as one of its arguments (i.e., any Cryptoki function 1938 except for C_Initialize, C_Finalize, C_GetInfo, C_GetFunctionList, C_GetSlotList, C_GetSlotInfo, 1939 C_GetTokenInfo, C_WaitForSlotEvent, C_GetMechanismList, C_GetMechanismInfo, C_InitToken, 1940

C_OpenSession, and C_CloseAllSessions) can return the following values: 1941

CKR_SESSION_HANDLE_INVALID: The specified session handle was invalid at the time that the 1942 function was invoked. Note that this can happen if the session’s token is removed before the function 1943

invocation, since removing a token closes all sessions with it. 1944

CKR_DEVICE_REMOVED: The token was removed from its slot during the execution of the function. 1945

CKR_SESSION_CLOSED: The session was closed during the execution of the function. Note that, 1946 as stated in [PKCS11-UG], the behavior of Cryptoki is undefined if multiple threads of an application 1947 attempt to access a common Cryptoki session simultaneously. Therefore, there is actually no 1948 guarantee that a function invocation could ever return the value CKR_SESSION_CLOSED. An 1949 example of multiple threads accessing a common session simultaneously is where one thread is 1950 using a session when another thread closes that same session. 1951

The relative priorities of these errors are in the order listed above, e.g., if either of 1952 CKR_SESSION_HANDLE_INVALID or CKR_DEVICE_REMOVED would be an appropriate error return, 1953 then CKR_SESSION_HANDLE_INVALID should be returned. 1954

In practice, it is often not crucial (or possible) for a Cryptoki library to be able to make a distinction 1955 between a token being removed before a function invocation and a token being removed during a 1956

function execution. 1957


5.1.3 Cryptoki function return values for functions that use a token 1958

Any Cryptoki function that uses a particular token (i.e., any Cryptoki function except for C_Initialize, 1959 C_Finalize, C_GetInfo, C_GetFunctionList, C_GetSlotList, C_GetSlotInfo, or C_WaitForSlotEvent) 1960

can return any of the following values: 1961

CKR_DEVICE_MEMORY: The token does not have sufficient memory to perform the requested 1962 function. 1963

CKR_DEVICE_ERROR: Some problem has occurred with the token and/or slot. This error code can 1964 be returned by more than just the functions mentioned above; in particular, it is possible for 1965 C_GetSlotInfo to return CKR_DEVICE_ERROR. 1966

CKR_TOKEN_NOT_PRESENT: The token was not present in its slot at the time that the function was 1967 invoked. 1968

CKR_DEVICE_REMOVED: The token was removed from its slot during the execution of the function. 1969

The relative priorities of these errors are in the order listed above, e.g., if either of 1970 CKR_DEVICE_MEMORY or CKR_DEVICE_ERROR would be an appropriate error return, then 1971 CKR_DEVICE_MEMORY should be returned. 1972

In practice, it is often not critical (or possible) for a Cryptoki library to be able to make a distinction 1973 between a token being removed before a function invocation and a token being removed during a 1974

function execution. 1975

5.1.4 Special return value for application-supplied callbacks 1976

There is a special-purpose return value which is not returned by any function in the actual Cryptoki API, 1977 but which may be returned by an application-supplied callback function. It is: 1978

CKR_CANCEL: When a function executing in serial with an application decides to give the application 1979 a chance to do some work, it calls an application-supplied function with a CKN_SURRENDER 1980 callback (see Section 5.21). If the callback returns the value CKR_CANCEL, then the function aborts 1981 and returns CKR_FUNCTION_CANCELED. 1982

5.1.5 Special return values for mutex-handling functions 1983

There are two other special-purpose return values which are not returned by any actual Cryptoki 1984 functions. These values may be returned by application-supplied mutex-handling functions, and they may 1985 safely be ignored by application developers who are not using their own threading model. They are: 1986

CKR_MUTEX_BAD: This error code can be returned by mutex-handling functions that are passed a 1987 bad mutex object as an argument. Unfortunately, it is possible for such a function not to recognize a 1988 bad mutex object. There is therefore no guarantee that such a function will successfully detect bad 1989 mutex objects and return this value. 1990

CKR_MUTEX_NOT_LOCKED: This error code can be returned by mutex-unlocking functions. It 1991 indicates that the mutex supplied to the mutex-unlocking function was not locked. 1992

5.1.6 All other Cryptoki function return values 1993

Descriptions of the other Cryptoki function return values follow. Except as mentioned in the descriptions 1994 of particular error codes, there are in general no particular priorities among the errors listed below, i.e., if 1995 more than one error code might apply to an execution of a function, then the function may return any 1996 applicable error code. 1997

CKR_ACTION_PROHIBITED: This value can only be returned by C_CopyObject, 1998 C_SetAttributeValue and C_DestroyObject. It denotes that the action may not be taken, either 1999 because of underlying policy restrictions on the token, or because the object has the relevant 2000 CKA_COPYABLE, CKA_MODIFIABLE or CKA_DESTROYABLE policy attribute set to CK_FALSE. 2001

CKR_ARGUMENTS_BAD: This is a rather generic error code which indicates that the arguments 2002 supplied to the Cryptoki function were in some way not appropriate. 2003


CKR_ATTRIBUTE_READ_ONLY: An attempt was made to set a value for an attribute which may not 2004 be set by the application, or which may not be modified by the application. See Section 4.1 for more 2005 information. 2006

CKR_ATTRIBUTE_SENSITIVE: An attempt was made to obtain the value of an attribute of an object 2007 which cannot be satisfied because the object is either sensitive or un-extractable. 2008

CKR_ATTRIBUTE_TYPE_INVALID: An invalid attribute type was specified in a template. See 2009 Section 4.1 for more information. 2010

CKR_ATTRIBUTE_VALUE_INVALID: An invalid value was specified for a particular attribute in a 2011 template. See Section 4.1 for more information. 2012

CKR_BUFFER_TOO_SMALL: The output of the function is too large to fit in the supplied buffer. 2013

CKR_CANT_LOCK: This value can only be returned by C_Initialize. It means that the type of locking 2014 requested by the application for thread-safety is not available in this library, and so the application 2015 cannot make use of this library in the specified fashion. 2016

CKR_CRYPTOKI_ALREADY_INITIALIZED: This value can only be returned by C_Initialize. It 2017 means that the Cryptoki library has already been initialized (by a previous call to C_Initialize which 2018 did not have a matching C_Finalize call). 2019

CKR_CRYPTOKI_NOT_INITIALIZED: This value can be returned by any function other than 2020 C_Initialize, C_GetFunctionList, C_GetInterfaceList and C_GetInterface. It indicates that the 2021 function cannot be executed because the Cryptoki library has not yet been initialized by a call to 2022 C_Initialize. 2023

CKR_CURVE_NOT_SUPPORTED: This curve is not supported by this token. Used with Elliptic 2024 Curve mechanisms. 2025

CKR_DATA_INVALID: The plaintext input data to a cryptographic operation is invalid. This return 2026 value has lower priority than CKR_DATA_LEN_RANGE. 2027

CKR_DATA_LEN_RANGE: The plaintext input data to a cryptographic operation has a bad length. 2028 Depending on the operation’s mechanism, this could mean that the plaintext data is too short, too 2029 long, or is not a multiple of some particular block size. This return value has higher priority than 2030 CKR_DATA_INVALID. 2031

CKR_DOMAIN_PARAMS_INVALID: Invalid or unsupported domain parameters were supplied to the 2032 function. Which representation methods of domain parameters are supported by a given mechanism 2033 can vary from token to token. 2034

CKR_ENCRYPTED_DATA_INVALID: The encrypted input to a decryption operation has been 2035 determined to be invalid ciphertext. This return value has lower priority than 2036 CKR_ENCRYPTED_DATA_LEN_RANGE. 2037

CKR_ENCRYPTED_DATA_LEN_RANGE: The ciphertext input to a decryption operation has been 2038 determined to be invalid ciphertext solely on the basis of its length. Depending on the operation’s 2039 mechanism, this could mean that the ciphertext is too short, too long, or is not a multiple of some 2040 particular block size. This return value has higher priority than CKR_ENCRYPTED_DATA_INVALID. 2041

CKR_EXCEEDED_MAX_ITERATIONS: An iterative algorithm (for key pair generation, domain 2042 parameter generation etc.) failed because we have exceeded the maximum number of iterations. 2043 This error code has precedence over CKR_FUNCTION_FAILED. Examples of iterative algorithms 2044 include DSA signature generation (retry if either r = 0 or s = 0) and generation of DSA primes p and q 2045 specified in FIPS 186-4. 2046

CKR_FIPS_SELF_TEST_FAILED: A FIPS 140-2 power-up self-test or conditional self-test failed. 2047 The token entered an error state. Future calls to cryptographic functions on the token will return 2048 CKR_GENERAL_ERROR. CKR_FIPS_SELF_TEST_FAILED has a higher precedence over 2049 CKR_GENERAL_ERROR. This error may be returned by C_Initialize, if a power-up self-test failed, 2050 by C_GenerateRandom or C_SeedRandom, if the continuous random number generator test failed, 2051 or by C_GenerateKeyPair, if the pair-wise consistency test failed. 2052


CKR_FUNCTION_CANCELED: The function was canceled in mid-execution. This happens to a 2053 cryptographic function if the function makes a CKN_SURRENDER application callback which returns 2054 CKR_CANCEL (see CKR_CANCEL). It also happens to a function that performs PIN entry through a 2055 protected path. The method used to cancel a protected path PIN entry operation is device dependent. 2056

CKR_FUNCTION_NOT_PARALLEL: There is currently no function executing in parallel in the 2057 specified session. This is a legacy error code which is only returned by the legacy functions 2058 C_GetFunctionStatus and C_CancelFunction. 2059

CKR_FUNCTION_NOT_SUPPORTED: The requested function is not supported by this Cryptoki 2060 library. Even unsupported functions in the Cryptoki API should have a “stub” in the library; this stub 2061 should simply return the value CKR_FUNCTION_NOT_SUPPORTED. 2062

CKR_FUNCTION_REJECTED: The signature request is rejected by the user. 2063

CKR_INFORMATION_SENSITIVE: The information requested could not be obtained because the 2064 token considers it sensitive, and is not able or willing to reveal it. 2065

CKR_KEY_CHANGED: This value is only returned by C_SetOperationState. It indicates that one of 2066

the keys specified is not the same key that was being used in the original saved session. 2067

CKR_KEY_FUNCTION_NOT_PERMITTED: An attempt has been made to use a key for a 2068 cryptographic purpose that the key’s attributes are not set to allow it to do. For example, to use a key 2069 for performing encryption, that key MUST have its CKA_ENCRYPT attribute set to CK_TRUE (the 2070 fact that the key MUST have a CKA_ENCRYPT attribute implies that the key cannot be a private 2071

key). This return value has lower priority than CKR_KEY_TYPE_INCONSISTENT. 2072

CKR_KEY_HANDLE_INVALID: The specified key handle is not valid. It may be the case that the 2073 specified handle is a valid handle for an object which is not a key. We reiterate here that 0 is never a 2074 valid key handle. 2075

CKR_KEY_INDIGESTIBLE: This error code can only be returned by C_DigestKey. It indicates that 2076 the value of the specified key cannot be digested for some reason (perhaps the key isn’t a secret key, 2077 or perhaps the token simply can’t digest this kind of key). 2078

CKR_KEY_NEEDED: This value is only returned by C_SetOperationState. It indicates that the 2079 session state cannot be restored because C_SetOperationState needs to be supplied with one or 2080

more keys that were being used in the original saved session. 2081

CKR_KEY_NOT_NEEDED: An extraneous key was supplied to C_SetOperationState. For 2082 example, an attempt was made to restore a session that had been performing a message digesting 2083 operation, and an encryption key was supplied. 2084

CKR_KEY_NOT_WRAPPABLE: Although the specified private or secret key does not have its 2085 CKA_EXTRACTABLE attribute set to CK_FALSE, Cryptoki (or the token) is unable to wrap the key as 2086 requested (possibly the token can only wrap a given key with certain types of keys, and the wrapping 2087 key specified is not one of these types). Compare with CKR_KEY_UNEXTRACTABLE. 2088

CKR_KEY_SIZE_RANGE: Although the requested keyed cryptographic operation could in principle 2089 be carried out, this Cryptoki library (or the token) is unable to actually do it because the supplied key‘s 2090 size is outside the range of key sizes that it can handle. 2091

CKR_KEY_TYPE_INCONSISTENT: The specified key is not the correct type of key to use with the 2092 specified mechanism. This return value has a higher priority than 2093 CKR_KEY_FUNCTION_NOT_PERMITTED. 2094

CKR_KEY_UNEXTRACTABLE: The specified private or secret key can’t be wrapped because its 2095 CKA_EXTRACTABLE attribute is set to CK_FALSE. Compare with CKR_KEY_NOT_WRAPPABLE. 2096

CKR_LIBRARY_LOAD_FAILED: The Cryptoki library could not load a dependent shared library. 2097

CKR_MECHANISM_INVALID: An invalid mechanism was specified to the cryptographic operation. 2098 This error code is an appropriate return value if an unknown mechanism was specified or if the 2099 mechanism specified cannot be used in the selected token with the selected function. 2100


CKR_MECHANISM_PARAM_INVALID: Invalid parameters were supplied to the mechanism specified 2101 to the cryptographic operation. Which parameter values are supported by a given mechanism can 2102 vary from token to token. 2103

CKR_NEED_TO_CREATE_THREADS: This value can only be returned by C_Initialize. It is 2104

returned when two conditions hold: 2105

1. The application called C_Initialize in a way which tells the Cryptoki library that application 2106 threads executing calls to the library cannot use native operating system methods to spawn new 2107 threads. 2108

2. The library cannot function properly without being able to spawn new threads in the above 2109 fashion. 2110

CKR_NO_EVENT: This value can only be returned by C_WaitForSlotEvent. It is returned when 2111 C_WaitForSlotEvent is called in non-blocking mode and there are no new slot events to return. 2112

CKR_OBJECT_HANDLE_INVALID: The specified object handle is not valid. We reiterate here that 0 2113 is never a valid object handle. 2114

CKR_OPERATION_ACTIVE: There is already an active operation (or combination of active 2115 operations) which prevents Cryptoki from activating the specified operation. For example, an active 2116 object-searching operation would prevent Cryptoki from activating an encryption operation with 2117 C_EncryptInit. Or, an active digesting operation and an active encryption operation would prevent 2118 Cryptoki from activating a signature operation. Or, on a token which doesn’t support simultaneous 2119 dual cryptographic operations in a session (see the description of the 2120 CKF_DUAL_CRYPTO_OPERATIONS flag in the CK_TOKEN_INFO structure), an active signature 2121 operation would prevent Cryptoki from activating an encryption operation. 2122

CKR_OPERATION_NOT_INITIALIZED: There is no active operation of an appropriate type in the 2123 specified session. For example, an application cannot call C_Encrypt in a session without having 2124 called C_EncryptInit first to activate an encryption operation. 2125

CKR_PIN_EXPIRED: The specified PIN has expired, and the requested operation cannot be carried 2126 out unless C_SetPIN is called to change the PIN value. Whether or not the normal user’s PIN on a 2127 token ever expires varies from token to token. 2128

CKR_PIN_INCORRECT: The specified PIN is incorrect, i.e., does not match the PIN stored on the 2129 token. More generally-- when authentication to the token involves something other than a PIN-- the 2130 attempt to authenticate the user has failed. 2131

CKR_PIN_INVALID: The specified PIN has invalid characters in it. This return code only applies to 2132 functions which attempt to set a PIN. 2133

CKR_PIN_LEN_RANGE: The specified PIN is too long or too short. This return code only applies to 2134 functions which attempt to set a PIN. 2135

CKR_PIN_LOCKED: The specified PIN is “locked”, and cannot be used. That is, because some 2136 particular number of failed authentication attempts has been reached, the token is unwilling to permit 2137 further attempts at authentication. Depending on the token, the specified PIN may or may not remain 2138 locked indefinitely. 2139

CKR_PIN_TOO_WEAK: The specified PIN is too weak so that it could be easy to guess. If the PIN is 2140 too short, CKR_PIN_LEN_RANGE should be returned instead. This return code only applies to 2141 functions which attempt to set a PIN. 2142

CKR_PUBLIC_KEY_INVALID: The public key fails a public key validation. For example, an EC 2143 public key fails the public key validation specified in Section 5.2.2 of ANSI X9.62. This error code may 2144 be returned by C_CreateObject, when the public key is created, or by C_VerifyInit or 2145 C_VerifyRecoverInit, when the public key is used. It may also be returned by C_DeriveKey, in 2146 preference to CKR_MECHANISM_PARAM_INVALID, if the other party's public key specified in the 2147 mechanism's parameters is invalid. 2148

CKR_RANDOM_NO_RNG: This value can be returned by C_SeedRandom and 2149 C_GenerateRandom. It indicates that the specified token doesn’t have a random number generator. 2150

This return value has higher priority than CKR_RANDOM_SEED_NOT_SUPPORTED. 2151


CKR_RANDOM_SEED_NOT_SUPPORTED: This value can only be returned by C_SeedRandom. 2152 It indicates that the token’s random number generator does not accept seeding from an application. 2153 This return value has lower priority than CKR_RANDOM_NO_RNG. 2154

CKR_SAVED_STATE_INVALID: This value can only be returned by C_SetOperationState. It 2155 indicates that the supplied saved cryptographic operations state is invalid, and so it cannot be 2156 restored to the specified session. 2157

CKR_SESSION_COUNT: This value can only be returned by C_OpenSession. It indicates that the 2158 attempt to open a session failed, either because the token has too many sessions already open, or 2159 because the token has too many read/write sessions already open. 2160

CKR_SESSION_EXISTS: This value can only be returned by C_InitToken. It indicates that a 2161

session with the token is already open, and so the token cannot be initialized. 2162

CKR_SESSION_PARALLEL_NOT_SUPPORTED: The specified token does not support parallel 2163 sessions. This is a legacy error code—in Cryptoki Version 2.01 and up, no token supports parallel 2164 sessions. CKR_SESSION_PARALLEL_NOT_SUPPORTED can only be returned by 2165 C_OpenSession, and it is only returned when C_OpenSession is called in a particular [deprecated] 2166

way. 2167

CKR_SESSION_READ_ONLY: The specified session was unable to accomplish the desired action 2168 because it is a read-only session. This return value has lower priority than 2169 CKR_TOKEN_WRITE_PROTECTED. 2170

CKR_SESSION_READ_ONLY_EXISTS: A read-only session already exists, and so the SO cannot 2171 be logged in. 2172

CKR_SESSION_READ_WRITE_SO_EXISTS: A read/write SO session already exists, and so a 2173 read-only session cannot be opened. 2174

CKR_SIGNATURE_LEN_RANGE: The provided signature/MAC can be seen to be invalid solely on 2175 the basis of its length. This return value has higher priority than CKR_SIGNATURE_INVALID. 2176

CKR_SIGNATURE_INVALID: The provided signature/MAC is invalid. This return value has lower 2177 priority than CKR_SIGNATURE_LEN_RANGE. 2178

CKR_SLOT_ID_INVALID: The specified slot ID is not valid. 2179

CKR_STATE_UNSAVEABLE: The cryptographic operations state of the specified session cannot be 2180 saved for some reason (possibly the token is simply unable to save the current state). This return 2181 value has lower priority than CKR_OPERATION_NOT_INITIALIZED. 2182

CKR_TEMPLATE_INCOMPLETE: The template specified for creating an object is incomplete, and 2183 lacks some necessary attributes. See Section 4.1 for more information. 2184

CKR_TEMPLATE_INCONSISTENT: The template specified for creating an object has conflicting 2185 attributes. See Section 4.1 for more information. 2186

CKR_TOKEN_NOT_RECOGNIZED: The Cryptoki library and/or slot does not recognize the token in 2187 the slot. 2188

CKR_TOKEN_WRITE_PROTECTED: The requested action could not be performed because the 2189 token is write-protected. This return value has higher priority than CKR_SESSION_READ_ONLY. 2190

CKR_UNWRAPPING_KEY_HANDLE_INVALID: This value can only be returned by C_UnwrapKey. 2191

It indicates that the key handle specified to be used to unwrap another key is not valid. 2192

CKR_UNWRAPPING_KEY_SIZE_RANGE: This value can only be returned by C_UnwrapKey. It 2193 indicates that although the requested unwrapping operation could in principle be carried out, this 2194 Cryptoki library (or the token) is unable to actually do it because the supplied key’s size is outside the 2195 range of key sizes that it can handle. 2196

CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT: This value can only be returned by 2197 C_UnwrapKey. It indicates that the type of the key specified to unwrap another key is not consistent 2198 with the mechanism specified for unwrapping. 2199


CKR_USER_ALREADY_LOGGED_IN: This value can only be returned by C_Login. It indicates that 2200 the specified user cannot be logged into the session, because it is already logged into the session. 2201 For example, if an application has an open SO session, and it attempts to log the SO into it, it will 2202 receive this error code. 2203

CKR_USER_ANOTHER_ALREADY_LOGGED_IN: This value can only be returned by C_Login. It 2204 indicates that the specified user cannot be logged into the session, because another user is already 2205 logged into the session. For example, if an application has an open SO session, and it attempts to 2206 log the normal user into it, it will receive this error code. 2207

CKR_USER_NOT_LOGGED_IN: The desired action cannot be performed because the appropriate 2208 user (or an appropriate user) is not logged in. One example is that a session cannot be logged out 2209 unless it is logged in. Another example is that a private object cannot be created on a token unless 2210 the session attempting to create it is logged in as the normal user. A final example is that 2211 cryptographic operations on certain tokens cannot be performed unless the normal user is logged in. 2212

CKR_USER_PIN_NOT_INITIALIZED: This value can only be returned by C_Login. It indicates that 2213 the normal user’s PIN has not yet been initialized with C_InitPIN. 2214

CKR_USER_TOO_MANY_TYPES: An attempt was made to have more distinct users simultaneously 2215 logged into the token than the token and/or library permits. For example, if some application has an 2216 open SO session, and another application attempts to log the normal user into a session, the attempt 2217 may return this error. It is not required to, however. Only if the simultaneous distinct users cannot be 2218 supported does C_Login have to return this value. Note that this error code generalizes to true multi-2219

user tokens. 2220

CKR_USER_TYPE_INVALID: An invalid value was specified as a CK_USER_TYPE. Valid types are 2221 CKU_SO, CKU_USER, and CKU_CONTEXT_SPECIFIC. 2222

CKR_WRAPPED_KEY_INVALID: This value can only be returned by C_UnwrapKey. It indicates 2223 that the provided wrapped key is not valid. If a call is made to C_UnwrapKey to unwrap a particular 2224 type of key (i.e., some particular key type is specified in the template provided to C_UnwrapKey), 2225 and the wrapped key provided to C_UnwrapKey is recognizably not a wrapped key of the proper 2226 type, then C_UnwrapKey should return CKR_WRAPPED_KEY_INVALID. This return value has 2227 lower priority than CKR_WRAPPED_KEY_LEN_RANGE. 2228

CKR_WRAPPED_KEY_LEN_RANGE: This value can only be returned by C_UnwrapKey. It 2229 indicates that the provided wrapped key can be seen to be invalid solely on the basis of its length. 2230 This return value has higher priority than CKR_WRAPPED_KEY_INVALID. 2231

CKR_WRAPPING_KEY_HANDLE_INVALID: This value can only be returned by C_WrapKey. It 2232 indicates that the key handle specified to be used to wrap another key is not valid. 2233

CKR_WRAPPING_KEY_SIZE_RANGE: This value can only be returned by C_WrapKey. It indicates 2234 that although the requested wrapping operation could in principle be carried out, this Cryptoki library 2235 (or the token) is unable to actually do it because the supplied wrapping key’s size is outside the range 2236 of key sizes that it can handle. 2237

CKR_WRAPPING_KEY_TYPE_INCONSISTENT: This value can only be returned by C_WrapKey. It 2238 indicates that the type of the key specified to wrap another key is not consistent with the mechanism 2239 specified for wrapping. 2240

CKR_OPERATION_CANCEL_FAILED: This value can only be returned by C_SessionCancel. It 2241 means that one or more of the requested operations could not be cancelled for implementation or 2242 vendor-specific reasons. 2243

5.1.7 More on relative priorities of Cryptoki errors 2244

In general, when a Cryptoki call is made, error codes from Section 5.1.1 (other than CKR_OK) take 2245 precedence over error codes from Section 5.1.2, which take precedence over error codes from Section 2246 5.1.3, which take precedence over error codes from Section 5.1.6. One minor implication of this is that 2247 functions that use a session handle (i.e., most functions!) never return the error code 2248 CKR_TOKEN_NOT_PRESENT (they return CKR_SESSION_HANDLE_INVALID instead). Other than 2249


these precedences, if more than one error code applies to the result of a Cryptoki call, any of the 2250 applicable error codes may be returned. Exceptions to this rule will be explicitly mentioned in the 2251 descriptions of functions. 2252

5.1.8 Error code “gotchas” 2253

Here is a short list of a few particular things about return values that Cryptoki developers might want to be 2254 aware of: 2255

1. As mentioned in Sections 5.1.2 and 5.1.3, a Cryptoki library may not be able to make a distinction 2256 between a token being removed before a function invocation and a token being removed during a 2257

function invocation. 2258

2. As mentioned in Section 5.1.2, an application should never count on getting a 2259 CKR_SESSION_CLOSED error. 2260

3. The difference between CKR_DATA_INVALID and CKR_DATA_LEN_RANGE can be somewhat 2261 subtle. Unless an application needs to be able to distinguish between these return values, it is best to 2262 always treat them equivalently. 2263

4. Similarly, the difference between CKR_ENCRYPTED_DATA_INVALID and 2264 CKR_ENCRYPTED_DATA_LEN_RANGE, and between CKR_WRAPPED_KEY_INVALID and 2265 CKR_WRAPPED_KEY_LEN_RANGE, can be subtle, and it may be best to treat these return values 2266 equivalently. 2267

5. Even with the guidance of Section 4.1, it can be difficult for a Cryptoki library developer to know which 2268 of CKR_ATTRIBUTE_VALUE_INVALID, CKR_TEMPLATE_INCOMPLETE, or 2269 CKR_TEMPLATE_INCONSISTENT to return. When possible, it is recommended that application 2270 developers be generous in their interpretations of these error codes. 2271

5.2 Conventions for functions returning output in a variable-length 2272

buffer 2273

A number of the functions defined in Cryptoki return output produced by some cryptographic mechanism. 2274 The amount of output returned by these functions is returned in a variable-length application-supplied 2275 buffer. An example of a function of this sort is C_Encrypt, which takes some plaintext as an argument, 2276 and outputs a buffer full of ciphertext. 2277

These functions have some common calling conventions, which we describe here. Two of the arguments 2278 to the function are a pointer to the output buffer (say pBuf) and a pointer to a location which will hold the 2279 length of the output produced (say pulBufLen). There are two ways for an application to call such a 2280

function: 2281

1. If pBuf is NULL_PTR, then all that the function does is return (in *pulBufLen) a number of bytes which 2282 would suffice to hold the cryptographic output produced from the input to the function. This number 2283 may somewhat exceed the precise number of bytes needed, but should not exceed it by a large 2284 amount. CKR_OK is returned by the function. 2285

2. If pBuf is not NULL_PTR, then *pulBufLen MUST contain the size in bytes of the buffer pointed to by 2286 pBuf. If that buffer is large enough to hold the cryptographic output produced from the input to the 2287 function, then that cryptographic output is placed there, and CKR_OK is returned by the function and 2288 *pulBufLen is set to the exact number of bytes returned. If the buffer is not large enough, then 2289 CKR_BUFFER_TOO_SMALL is returned and *pulBufLen is set to at least the number of bytes 2290

needed to hold the cryptographic output produced from the input to the function. 2291

NOTE: This is a change from previous specs. The problem addressed by this change is that the 2292 specification doesn’t require that the operation be finalized when this error occurs and, in some decrypt 2293 cases, it is impossible for the token todoesn’t know how big a buffer is needed until the decrypt operation 2294 completes. The act of doing decrypt can mess up the internal encryption state. Many tokens already 2295 implement thethis relaxed behavior specified in this version, and, tokens which implement athe more 2296 precise behavior are still compliant. A potentialThe one corner case is an applicationapplications using a 2297 token that knows exactly how big the output of the decryption operation will be is (through some out of 2298 band means). In this case, the application), could now get a CKR_BUFFER_TOO_SMALL errorreturned 2299


when it supplied a buffer exactly big enough to hold the decrypted value when it may previously have 2300 succeeded. 2301

All functions which use the above convention will explicitly say so. 2302

Cryptographic functions which return output in a variable-length buffer should always return as much 2303 output as can be computed from what has been passed in to them thus far. As an example, consider a 2304 session which is performing a multiple-part decryption operation with DES in cipher-block chaining mode 2305 with PKCS padding. Suppose that, initially, 8 bytes of ciphertext are passed to the C_DecryptUpdate 2306 function. The block size of DES is 8 bytes, but the PKCS padding makes it unclear at this stage whether 2307 the ciphertext was produced from encrypting a 0-byte string, or from encrypting some string of length at 2308 least 8 bytes. Hence the call to C_DecryptUpdate should return 0 bytes of plaintext. If a single 2309 additional byte of ciphertext is supplied by a subsequent call to C_DecryptUpdate, then that call should 2310

return 8 bytes of plaintext (one full DES block). 2311

5.3 Disclaimer concerning sample code 2312

For the remainder of this section, we enumerate the various functions defined in Cryptoki. Most functions 2313 will be shown in use in at least one sample code snippet. For the sake of brevity, sample code will 2314 frequently be somewhat incomplete. In particular, sample code will generally ignore possible error 2315 returns from C library functions, and also will not deal with Cryptoki error returns in a realistic fashion. 2316

5.4 General-purpose functions 2317

Cryptoki provides the following general-purpose functions: 2318

5.4.1 C_Initialize 2319

CK_DECLARE_FUNCTION(CK_RV, C_Initialize) { 2320

CK_VOID_PTR pInitArgs 2321

); 2322

C_Initialize initializes the Cryptoki library. pInitArgs either has the value NULL_PTR or points to a 2323 CK_C_INITIALIZE_ARGS structure containing information on how the library should deal with multi-2324 threaded access. If an application will not be accessing Cryptoki through multiple threads simultaneously, 2325 it can generally supply the value NULL_PTR to C_Initialize (the consequences of supplying this value will 2326

be explained below). 2327

If pInitArgs is non-NULL_PTR, C_Initialize should cast it to a CK_C_INITIALIZE_ARGS_PTR and then 2328 dereference the resulting pointer to obtain the CK_C_INITIALIZE_ARGS fields CreateMutex, 2329 DestroyMutex, LockMutex, UnlockMutex, flags, and pReserved. For this version of Cryptoki, the value of 2330 pReserved thereby obtained MUST be NULL_PTR; if it’s not, then C_Initialize should return with the 2331

value CKR_ARGUMENTS_BAD. 2332

If the CKF_LIBRARY_CANT_CREATE_OS_THREADS flag in the flags field is set, that indicates that 2333 application threads which are executing calls to the Cryptoki library are not permitted to use the native 2334 operation system calls to spawn off new threads. In other words, the library’s code may not create its 2335 own threads. If the library is unable to function properly under this restriction, C_Initialize should return 2336

with the value CKR_NEED_TO_CREATE_THREADS. 2337

A call to C_Initialize specifies one of four different ways to support multi-threaded access via the value of 2338 the CKF_OS_LOCKING_OK flag in the flags field and the values of the CreateMutex, DestroyMutex, 2339 LockMutex, and UnlockMutex function pointer fields: 2340

1. If the flag isn’t set, and the function pointer fields aren’t supplied (i.e., they all have the value 2341 NULL_PTR), that means that the application won’t be accessing the Cryptoki library from multiple 2342

threads simultaneously. 2343

2. If the flag is set, and the function pointer fields aren’t supplied (i.e., they all have the value 2344 NULL_PTR), that means that the application will be performing multi-threaded Cryptoki access, and 2345


the library needs to use the native operating system primitives to ensure safe multi-threaded access. 2346 If the library is unable to do this, C_Initialize should return with the value CKR_CANT_LOCK. 2347

3. If the flag isn’t set, and the function pointer fields are supplied (i.e., they all have non-NULL_PTR 2348 values), that means that the application will be performing multi-threaded Cryptoki access, and the 2349 library needs to use the supplied function pointers for mutex-handling to ensure safe multi-threaded 2350 access. If the library is unable to do this, C_Initialize should return with the value 2351

CKR_CANT_LOCK. 2352

4. If the flag is set, and the function pointer fields are supplied (i.e., they all have non-NULL_PTR 2353 values), that means that the application will be performing multi-threaded Cryptoki access, and the 2354 library needs to use either the native operating system primitives or the supplied function pointers for 2355 mutex-handling to ensure safe multi-threaded access. If the library is unable to do this, C_Initialize 2356

should return with the value CKR_CANT_LOCK. 2357

If some, but not all, of the supplied function pointers to C_Initialize are non-NULL_PTR, then C_Initialize 2358

should return with the value CKR_ARGUMENTS_BAD. 2359

A call to C_Initialize with pInitArgs set to NULL_PTR is treated like a call to C_Initialize with pInitArgs 2360 pointing to a CK_C_INITIALIZE_ARGS which has the CreateMutex, DestroyMutex, LockMutex, 2361 UnlockMutex, and pReserved fields set to NULL_PTR, and has the flags field set to 0. 2362

C_Initialize should be the first Cryptoki call made by an application, except for calls to 2363 C_GetFunctionList, C_GetInterfaceList, or C_GetInterface. What this function actually does is 2364 implementation-dependent; typically, it might cause Cryptoki to initialize its internal memory buffers, or 2365 any other resources it requires. 2366

If several applications are using Cryptoki, each one should call C_Initialize. Every call to C_Initialize 2367 should (eventually) be succeeded by a single call to C_Finalize. See [PKCS11-UG] for further details. 2368

Return values: CKR_ARGUMENTS_BAD, CKR_CANT_LOCK, 2369 CKR_CRYPTOKI_ALREADY_INITIALIZED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 2370 CKR_HOST_MEMORY, CKR_NEED_TO_CREATE_THREADS, CKR_OK. 2371

Example: see C_GetInfo. 2372

5.4.2 C_Finalize 2373

CK_DECLARE_FUNCTION(CK_RV, C_Finalize)( 2374

CK_VOID_PTR pReserved 2375

); 2376

C_Finalize is called to indicate that an application is finished with the Cryptoki library. It should be the 2377 last Cryptoki call made by an application. The pReserved parameter is reserved for future versions; for 2378 this version, it should be set to NULL_PTR (if C_Finalize is called with a non-NULL_PTR value for 2379 pReserved, it should return the value CKR_ARGUMENTS_BAD. 2380

If several applications are using Cryptoki, each one should call C_Finalize. Each application’s call to 2381 C_Finalize should be preceded by a single call to C_Initialize; in between the two calls, an application 2382 can make calls to other Cryptoki functions. See [PKCS11-UG] for further details. 2383

Despite the fact that the parameters supplied to C_Initialize can in general allow for safe multi-threaded 2384 access to a Cryptoki library, the behavior of C_Finalize is nevertheless undefined if it is called by an 2385 application while other threads of the application are making Cryptoki calls. The exception to this 2386 exceptional behavior of C_Finalize occurs when a thread calls C_Finalize while another of the 2387 application’s threads is blocking on Cryptoki’s C_WaitForSlotEvent function. When this happens, the 2388 blocked thread becomes unblocked and returns the value CKR_CRYPTOKI_NOT_INITIALIZED. See 2389 C_WaitForSlotEvent for more information. 2390

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 2391 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK. 2392

Example: see C_GetInfo. 2393


5.4.3 C_GetInfo 2394

CK_DECLARE_FUNCTION(CK_RV, C_GetInfo)( 2395

CK_INFO_PTR pInfo 2396

); 2397

C_GetInfo returns general information about Cryptoki. pInfo points to the location that receives the 2398

information. 2399

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 2400 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK. 2401

Example: 2402

CK_INFO info; 2403

CK_RV rv; 2404

CK_C_INITIALIZE_ARGS InitArgs; 2405

2406

InitArgs.CreateMutex = &MyCreateMutex; 2407

InitArgs.DestroyMutex = &MyDestroyMutex; 2408

InitArgs.LockMutex = &MyLockMutex; 2409

InitArgs.UnlockMutex = &MyUnlockMutex; 2410

InitArgs.flags = CKF_OS_LOCKING_OK; 2411

InitArgs.pReserved = NULL_PTR; 2412

2413

rv = C_Initialize((CK_VOID_PTR)&InitArgs); 2414

assert(rv == CKR_OK); 2415

2416

rv = C_GetInfo(&info); 2417


if(info.cryptokiVersion.major == 2) { 2419

/* Do lots of interesting cryptographic things with the token */ 2420

. 2421

. 2422

} 2423

2424

rv = C_Finalize(NULL_PTR); 2425


5.4.4 C_GetFunctionList 2427

CK_DECLARE_FUNCTION(CK_RV, C_GetFunctionList)( 2428

CK_FUNCTION_LIST_PTR_PTR ppFunctionList 2429

); 2430

C_GetFunctionList obtains a pointer to the Cryptoki library’s list of function pointers. ppFunctionList 2431 points to a value which will receive a pointer to the library’s CK_FUNCTION_LIST structure, which in turn 2432 contains function pointers for all the Cryptoki API routines in the library. The pointer thus obtained may 2433 point into memory which is owned by the Cryptoki library, and which may or may not be writable. 2434

Whether or not this is the case, no attempt should be made to write to this memory. 2435


C_GetFunctionList, C_GetInterfaceList, and C_GetInterface are the only Cryptoki functions which an 2436 application may call before calling C_Initialize. It is provided to make it easier and faster for applications 2437

to use shared Cryptoki libraries and to use more than one Cryptoki library simultaneously. 2438

Return values: CKR_ARGUMENTS_BAD, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 2439 CKR_HOST_MEMORY, CKR_OK. 2440

Example: 2441

CK_FUNCTION_LIST_PTR pFunctionList; 2442

CK_C_Initialize pC_Initialize; 2443

CK_RV rv; 2444

2445

/* It’s OK to call C_GetFunctionList before calling C_Initialize */ 2446

rv = C_GetFunctionList(&pFunctionList); 2447


pC_Initialize = pFunctionList -> C_Initialize; 2449

2450

/* Call the C_Initialize function in the library */ 2451

rv = (*pC_Initialize)(NULL_PTR); 2452

5.4.5 C_GetInterfaceList 2453

CK_DECLARE_FUNCTION(CK_RV, C_GetInterfaceList)( 2454

CK_INTERFACE_PTR pInterfaceList, 2455

CK_ULONG_PTR pulCount 2456

); 2457

C_GetInterfaceList is used to obtain a list of interfaces supported by a Cryptoki library. pulCount points 2458

to the location that receives the number of interfaces. 2459

There are two ways for an application to call C_GetInterfaceList: 2460

1. If pInterfaceList is NULL_PTR, then all that C_GetInterfaceList does is return (in *pulCount) the 2461 number of interfaces, without actually returning a list of interfaces. The contents of *pulCount on 2462 entry to C_GetInterfaceList has no meaning in this case, and the call returns the value CKR_OK. 2463

2. If pIntrerfaceList is not NULL_PTR, then *pulCount MUST contain the size (in terms of 2464 CK_INTERFACE elements) of the buffer pointed to by pInterfaceList. If that buffer is large enough to 2465 hold the list of interfaces, then the list is returned in it, and CKR_OK is returned. If not, then the call 2466 to C_GetInterfaceList returns the value CKR_BUFFER_TOO_SMALL. In either case, the value 2467 *pulCount is set to hold the number of interfaces. 2468

Because C_GetInterfaceList does not allocate any space of its own, an application will often call 2469 C_GetInterfaceList twice. However, this behavior is by no means required. 2470

C_GetInterfaceList obtains (in *pFunctionList of each interface) a pointer to the Cryptoki library’s list of 2471 function pointers. The pointer thus obtained may point into memory which is owned by the Cryptoki 2472 library, and which may or may not be writable. Whether or not this is the case, no attempt should be 2473

made to write to this memory. The same caveat applies to the interface names returned. 2474

2475



Return values: CKR_BUFFER_TOO_SMALL, CKR_ARGUMENTS_BAD, CKR_FUNCTION_FAILED, 2479 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK. 2480

Example: 2481


CK_ULONG ulCount=0; 2482

CK_INTERFACE_PTR interfaceList=NULL; 2483

CK_RV rv; 2484

int I; 2485

2486

/* get number of interfaces */ 2487

rv = C_GetInterfaceList(NULL,&ulCount); 2488

if (rv == CKR_OK) { 2489

/* get copy of interfaces */ 2490

interfaceList = (CK_INTERFACE_PTR)malloc(ulCount*sizeof(CK_INTERFACE)); 2491

rv = C_GetInterfaceList(interfaceList,&ulCount); 2492

for(i=0;i<ulCount;i++) { 2493

printf("interface %s version %d.%d funcs %p flags 0x%lu\n", 2494

interfaceList[i].pInterfaceName, 2495

((CK_VERSION *)interfaceList[i].pFunctionList)->major, 2496

((CK_VERSION *)interfaceList[i].pFunctionList)->minor, 2497

interfaceList[i].pFunctionList, 2498

interfaceList[i].flags); 2499

} 2500

} 2501

2502

5.4.6 C_GetInterface 2503

CK_DECLARE_FUNCTION(CK_RV,C_GetInterface)( 2504

CK_UTF8CHAR_PTR pInterfaceName, 2505

CK_VERSION_PTR pVersion, 2506

CK_INTERFACE_PTR_PTR ppInterface, 2507

CK_FLAGS flags 2508

); 2509

C_GetInterface is used to obtain an interface supported by a Cryptoki library. pInterfaceName specifies 2510 the name of the interface, pVersion specifies the interface version, ppInterface points to the location that 2511 receives the interface, flags specifies the required interface flags. 2512

There are multiple ways for an application to specify a particular interface when calling C_GetInterface: 2513

1. If pInterfaceName is not NULL_PTR, the name of the interface returned must match. If 2514 pInterfaceName is NULL_PTR, the cryptoki library can return a default interface of its choice 2515

2. If pVersion is not NULL_PTR, the version of the interface returned must match. If pVersion is 2516

NULL_PTR, the cryptoki library can return an interface of any version 2517

3. If flags is non-zero, the interface returned must match all of the supplied flag values (but may include 2518 additional flags not specified). If flags is 0, the cryptoki library can return an interface with any flags 2519

C_GetInterface obtains (in *pFunctionList of each interface) a pointer to the Cryptoki library’s list of 2520 function pointers. The pointer thus obtained may point into memory which is owned by the Cryptoki 2521 library, and which may or may not be writable. Whether or not this is the case, no attempt should be 2522 made to write to this memory. The same caveat applies to the interface names returned. 2523




Return values: CKR_BUFFER_TOO_SMALL, CKR_ARGUMENTS_BAD, CKR_FUNCTION_FAILED, 2527 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK. 2528

Example: 2529

CK_INTERFACE_PTR interface; 2530

CK_RV rv; 2531

CK_VERSION version; 2532

CK_FLAGS flags=CKF_ INTERFACE_FORK_SAFE; 2533

2534

/* get default interface */ 2535

rv = C_GetInterface(NULL,NULL,&interface,flags); 2536

if (rv == CKR_OK) { 2537


interface->pInterfaceName, 2539

((CK_VERSION *)interface->pFunctionList)->major, 2540

((CK_VERSION *)interface->pFunctionList)->minor, 2541

interface->pFunctionList, 2542

interface->flags); 2543

} 2544

2545

/* get default standard interface */ 2546

rv = C_GetInterface((CK_UTF8CHAR_PTR)"PKCS 11",NULL,&interface,flags); 2547

if (rv == CKR_OK) { 2548


interface->pInterfaceName, 2550

((CK_VERSION *)interface->pFunctionList)->major, 2551

((CK_VERSION *)interface->pFunctionList)->minor, 2552

interface->pFunctionList, 2553

interface->flags); 2554

} 2555

2556

/* get specific standard version interface */ 2557

version.major=3; 2558

version.minor=0; 2559

rv = C_GetInterface((CK_UTF8CHAR_PTR)"PKCS 11",&version,&interface,flags); 2560

if (rv == CKR_OK) { 2561

CK_FUNCTION_LIST_3_0_PTR pkcs11=interface->pFunctionList; 2562

2563

/* ... use the new functions */ 2564

pkcs11->C_LoginUser(hSession,userType,pPin,ulPinLen, 2565 pUsername,ulUsernameLen); 2566

} 2567


2568

/* get specific vendor version interface */ 2569

version.major=1; 2570

version.minor=0; 2571

rv = C_GetInterface((CK_UTF8CHAR_PTR) 2572

"Vendor VendorName",&version,&interface,flags); 2573

if (rv == CKR_OK) { 2574

CK_FUNCTION_LIST_VENDOR_1_0_PTR pkcs11=interface->pFunctionList; 2575

2576

/* ... use vendor specific functions */ 2577

pkcs11->C_VendorFunction1(param1,param2,param3); 2578

} 2579

2580

5.5 Slot and token management functions 2581

Cryptoki provides the following functions for slot and token management: 2582

5.5.1 C_GetSlotList 2583

CK_DECLARE_FUNCTION(CK_RV, C_GetSlotList)( 2584

CK_BBOOL tokenPresent, 2585

CK_SLOT_ID_PTR pSlotList, 2586


); 2588

C_GetSlotList is used to obtain a list of slots in the system. tokenPresent indicates whether the list 2589 obtained includes only those slots with a token present (CK_TRUE), or all slots (CK_FALSE); pulCount 2590

points to the location that receives the number of slots. 2591

There are two ways for an application to call C_GetSlotList: 2592

1. If pSlotList is NULL_PTR, then all that C_GetSlotList does is return (in *pulCount) the number of 2593 slots, without actually returning a list of slots. The contents of the buffer pointed to by pulCount on 2594 entry to C_GetSlotList has no meaning in this case, and the call returns the value CKR_OK. 2595

2. If pSlotList is not NULL_PTR, then *pulCount MUST contain the size (in terms of CK_SLOT_ID 2596 elements) of the buffer pointed to by pSlotList. If that buffer is large enough to hold the list of slots, 2597 then the list is returned in it, and CKR_OK is returned. If not, then the call to C_GetSlotList returns 2598 the value CKR_BUFFER_TOO_SMALL. In either case, the value *pulCount is set to hold the number 2599

of slots. 2600

Because C_GetSlotList does not allocate any space of its own, an application will often call 2601 C_GetSlotList twice (or sometimes even more times—if an application is trying to get a list of all slots 2602 with a token present, then the number of such slots can (unfortunately) change between when the 2603 application asks for how many such slots there are and when the application asks for the slots 2604 themselves). However, multiple calls to C_GetSlotList are by no means required. 2605

All slots which C_GetSlotList reports MUST be able to be queried as valid slots by C_GetSlotInfo. 2606 Furthermore, the set of slots accessible through a Cryptoki library is checked at the time that 2607 C_GetSlotList, for list length prediction (NULL pSlotList argument) is called. If an application calls 2608 C_GetSlotList with a non-NULL pSlotList, and then the user adds or removes a hardware device, the 2609 changed slot list will only be visible and effective if C_GetSlotList is called again with NULL. Even if C_ 2610 GetSlotList is successfully called this way, it may or may not be the case that the changed slot list will be 2611


successfully recognized depending on the library implementation. On some platforms, or earlier PKCS11 2612 compliant libraries, it may be necessary to successfully call C_Initialize or to restart the entire system. 2613

2614

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 2615 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 2616 CKR_HOST_MEMORY, CKR_OK. 2617

Example: 2618

CK_ULONG ulSlotCount, ulSlotWithTokenCount; 2619

CK_SLOT_ID_PTR pSlotList, pSlotWithTokenList; 2620

CK_RV rv; 2621

2622

/* Get list of all slots */ 2623

rv = C_GetSlotList(CK_FALSE, NULL_PTR, &ulSlotCount); 2624

if (rv == CKR_OK) { 2625

pSlotList = 2626

(CK_SLOT_ID_PTR) malloc(ulSlotCount*sizeof(CK_SLOT_ID)); 2627

rv = C_GetSlotList(CK_FALSE, pSlotList, &ulSlotCount); 2628

if (rv == CKR_OK) { 2629

/* Now use that list of all slots */ 2630

. 2631

. 2632

} 2633

2634

free(pSlotList); 2635

} 2636

2637

/* Get list of all slots with a token present */ 2638

pSlotWithTokenList = (CK_SLOT_ID_PTR) malloc(0); 2639

ulSlotWithTokenCount = 0; 2640

while (1) { 2641

rv = C_GetSlotList( 2642

CK_TRUE, pSlotWithTokenList, &ulSlotWithTokenCount); 2643

if (rv != CKR_BUFFER_TOO_SMALL) 2644

break; 2645

pSlotWithTokenList = realloc( 2646

pSlotWithTokenList, 2647

ulSlotWithTokenList*sizeof(CK_SLOT_ID)); 2648

} 2649

2650

if (rv == CKR_OK) { 2651

/* Now use that list of all slots with a token present */ 2652

. 2653

. 2654


} 2655

2656

free(pSlotWithTokenList); 2657

5.5.2 C_GetSlotInfo 2658

CK_DECLARE_FUNCTION(CK_RV, C_GetSlotInfo)( 2659

CK_SLOT_ID slotID, 2660

CK_SLOT_INFO_PTR pInfo 2661

); 2662

C_GetSlotInfo obtains information about a particular slot in the system. slotID is the ID of the slot; pInfo 2663

points to the location that receives the slot information. 2664

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 2665 CKR_DEVICE_ERROR, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, 2666 CKR_OK, CKR_SLOT_ID_INVALID. 2667

Example: see C_GetTokenInfo. 2668

5.5.3 C_GetTokenInfo 2669

CK_DECLARE_FUNCTION(CK_RV, C_GetTokenInfo)( 2670


CK_TOKEN_INFO_PTR pInfo 2672

); 2673

C_GetTokenInfo obtains information about a particular token in the system. slotID is the ID of the 2674 token’s slot; pInfo points to the location that receives the token information. 2675

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 2676 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 2677 CKR_HOST_MEMORY, CKR_OK, CKR_SLOT_ID_INVALID, CKR_TOKEN_NOT_PRESENT, 2678 CKR_TOKEN_NOT_RECOGNIZED, CKR_ARGUMENTS_BAD. 2679

Example: 2680

CK_ULONG ulCount; 2681

CK_SLOT_ID_PTR pSlotList; 2682

CK_SLOT_INFO slotInfo; 2683

CK_TOKEN_INFO tokenInfo; 2684

CK_RV rv; 2685

2686

rv = C_GetSlotList(CK_FALSE, NULL_PTR, &ulCount); 2687

if ((rv == CKR_OK) && (ulCount > 0)) { 2688

pSlotList = (CK_SLOT_ID_PTR) malloc(ulCount*sizeof(CK_SLOT_ID)); 2689

rv = C_GetSlotList(CK_FALSE, pSlotList, &ulCount); 2690


2692

/* Get slot information for first slot */ 2693

rv = C_GetSlotInfo(pSlotList[0], &slotInfo); 2694


2696


/* Get token information for first slot */ 2697

rv = C_GetTokenInfo(pSlotList[0], &tokenInfo); 2698

if (rv == CKR_TOKEN_NOT_PRESENT) { 2699

. 2700

. 2701

} 2702

. 2703

. 2704

free(pSlotList); 2705

} 2706

5.5.4 C_WaitForSlotEvent 2707

CK_DECLARE_FUNCTION(CK_RV, C_WaitForSlotEvent)( 2708

CK_FLAGS flags, 2709

CK_SLOT_ID_PTR pSlot, 2710

CK_VOID_PTR pReserved 2711

); 2712

C_WaitForSlotEvent waits for a slot event, such as token insertion or token removal, to occur. flags 2713 determines whether or not the C_WaitForSlotEvent call blocks (i.e., waits for a slot event to occur); pSlot 2714 points to a location which will receive the ID of the slot that the event occurred in. pReserved is reserved 2715

for future versions; for this version of Cryptoki, it should be NULL_PTR. 2716

At present, the only flag defined for use in the flags argument is CKF_DONT_BLOCK: 2717

Internally, each Cryptoki application has a flag for each slot which is used to track whether or not any 2718 unrecognized events involving that slot have occurred. When an application initially calls C_Initialize, 2719 every slot’s event flag is cleared. Whenever a slot event occurs, the flag corresponding to the slot in 2720 which the event occurred is set. 2721

If C_WaitForSlotEvent is called with the CKF_DONT_BLOCK flag set in the flags argument, and some 2722 slot’s event flag is set, then that event flag is cleared, and the call returns with the ID of that slot in the 2723 location pointed to by pSlot. If more than one slot’s event flag is set at the time of the call, one such slot 2724

is chosen by the library to have its event flag cleared and to have its slot ID returned. 2725

If C_WaitForSlotEvent is called with the CKF_DONT_BLOCK flag set in the flags argument, and no 2726 slot’s event flag is set, then the call returns with the value CKR_NO_EVENT. In this case, the contents of 2727 the location pointed to by pSlot when C_WaitForSlotEvent are undefined. 2728

If C_WaitForSlotEvent is called with the CKF_DONT_BLOCK flag clear in the flags argument, then the 2729 call behaves as above, except that it will block. That is, if no slot’s event flag is set at the time of the call, 2730 C_WaitForSlotEvent will wait until some slot’s event flag becomes set. If a thread of an application has 2731 a C_WaitForSlotEvent call blocking when another thread of that application calls C_Finalize, the 2732 C_WaitForSlotEvent call returns with the value CKR_CRYPTOKI_NOT_INITIALIZED. 2733

Although the parameters supplied to C_Initialize can in general allow for safe multi-threaded access to a 2734 Cryptoki library, C_WaitForSlotEvent is exceptional in that the behavior of Cryptoki is undefined if 2735 multiple threads of a single application make simultaneous calls to C_WaitForSlotEvent. 2736

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 2737 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_NO_EVENT, 2738 CKR_OK. 2739

Example: 2740

CK_FLAGS flags = 0; 2741

CK_SLOT_ID slotID; 2742


CK_SLOT_INFO slotInfo; 2743

CK_RV rv; 2744

. 2745

. 2746

/* Block and wait for a slot event */ 2747

rv = C_WaitForSlotEvent(flags, &slotID, NULL_PTR); 2748


2750

/* See what’s up with that slot */ 2751

rv = C_GetSlotInfo(slotID, &slotInfo); 2752


2754

5.5.5 C_GetMechanismList 2755

CK_DECLARE_FUNCTION(CK_RV, C_GetMechanismList)( 2756


CK_MECHANISM_TYPE_PTR pMechanismList, 2758


); 2760

C_GetMechanismList is used to obtain a list of mechanism types supported by a token. SlotID is the ID 2761 of the token’s slot; pulCount points to the location that receives the number of mechanisms. 2762

There are two ways for an application to call C_GetMechanismList: 2763

1. If pMechanismList is NULL_PTR, then all that C_GetMechanismList does is return (in *pulCount) 2764 the number of mechanisms, without actually returning a list of mechanisms. The contents of 2765 *pulCount on entry to C_GetMechanismList has no meaning in this case, and the call returns the 2766 value CKR_OK. 2767

2. If pMechanismList is not NULL_PTR, then *pulCount MUST contain the size (in terms of 2768 CK_MECHANISM_TYPE elements) of the buffer pointed to by pMechanismList. If that buffer is large 2769 enough to hold the list of mechanisms, then the list is returned in it, and CKR_OK is returned. If not, 2770 then the call to C_GetMechanismList returns the value CKR_BUFFER_TOO_SMALL. In either 2771 case, the value *pulCount is set to hold the number of mechanisms. 2772

Because C_GetMechanismList does not allocate any space of its own, an application will often call 2773 C_GetMechanismList twice. However, this behavior is by no means required. 2774

Return values: CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, 2775 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 2776 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, 2777 CKR_SLOT_ID_INVALID, CKR_TOKEN_NOT_PRESENT, CKR_TOKEN_NOT_RECOGNIZED, 2778 CKR_ARGUMENTS_BAD. 2779

Example: 2780



CK_MECHANISM_TYPE_PTR pMechanismList; 2783

CK_RV rv; 2784

2785

. 2786

. 2787


rv = C_GetMechanismList(slotID, NULL_PTR, &ulCount); 2788

if ((rv == CKR_OK) && (ulCount > 0)) { 2789

pMechanismList = 2790

(CK_MECHANISM_TYPE_PTR) 2791

malloc(ulCount*sizeof(CK_MECHANISM_TYPE)); 2792

rv = C_GetMechanismList(slotID, pMechanismList, &ulCount); 2793

if (rv == CKR_OK) { 2794

. 2795

. 2796

} 2797

free(pMechanismList); 2798

} 2799

5.5.6 C_GetMechanismInfo 2800

CK_DECLARE_FUNCTION(CK_RV, C_GetMechanismInfo)( 2801


CK_MECHANISM_TYPE type, 2803

CK_MECHANISM_INFO_PTR pInfo 2804

); 2805

C_GetMechanismInfo obtains information about a particular mechanism possibly supported by a token. 2806 slotID is the ID of the token’s slot; type is the type of mechanism; pInfo points to the location that receives 2807 the mechanism information. 2808

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 2809 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 2810 CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_OK, CKR_SLOT_ID_INVALID, 2811 CKR_TOKEN_NOT_PRESENT, CKR_TOKEN_NOT_RECOGNIZED, CKR_ARGUMENTS_BAD. 2812

Example: 2813


CK_MECHANISM_INFO info; 2815

CK_RV rv; 2816

2817

. 2818

. 2819

/* Get information about the CKM_MD2 mechanism for this token */ 2820

rv = C_GetMechanismInfo(slotID, CKM_MD2, &info); 2821

if (rv == CKR_OK) { 2822

if (info.flags & CKF_DIGEST) { 2823

. 2824

. 2825

} 2826

} 2827


5.5.7 C_InitToken 2828

CK_DECLARE_FUNCTION(CK_RV, C_InitToken)( 2829


CK_UTF8CHAR_PTR pPin, 2831

CK_ULONG ulPinLen, 2832

CK_UTF8CHAR_PTR pLabel 2833

); 2834

C_InitToken initializes a token. slotID is the ID of the token’s slot; pPin points to the SO’s initial PIN 2835 (which need not be null-terminated); ulPinLen is the length in bytes of the PIN; pLabel points to the 32-2836 byte label of the token (which MUST be padded with blank characters, and which MUST not be null-2837 terminated). This standard allows PIN values to contain any valid UTF8 character, but the token may 2838 impose subset restrictions. 2839

If the token has not been initialized (i.e. new from the factory), then the pPin parameter becomes the 2840 initial value of the SO PIN. If the token is being reinitialized, the pPin parameter is checked against the 2841 existing SO PIN to authorize the initialization operation. In both cases, the SO PIN is the value pPin after 2842 the function completes successfully. If the SO PIN is lost, then the card MUST be reinitialized using a 2843 mechanism outside the scope of this standard. The CKF_TOKEN_INITIALIZED flag in the 2844 CK_TOKEN_INFO structure indicates the action that will result from calling C_InitToken. If set, the token 2845 will be reinitialized, and the client MUST supply the existing SO password in pPin. 2846

When a token is initialized, all objects that can be destroyed are destroyed (i.e., all except for 2847 “indestructible” objects such as keys built into the token). Also, access by the normal user is disabled 2848 until the SO sets the normal user’s PIN. Depending on the token, some “default” objects may be created, 2849 and attributes of some objects may be set to default values. 2850

If the token has a “protected authentication path”, as indicated by the 2851 CKF_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means 2852 that there is some way for a user to be authenticated to the token without having the application send a 2853 PIN through the Cryptoki library. One such possibility is that the user enters a PIN on a PINpad on the 2854 token itself, or on the slot device. To initialize a token with such a protected authentication path, the pPin 2855 parameter to C_InitToken should be NULL_PTR. During the execution of C_InitToken, the SO’s PIN will 2856

be entered through the protected authentication path. 2857

If the token has a protected authentication path other than a PINpad, then it is token-dependent whether 2858 or not C_InitToken can be used to initialize the token. 2859

A token cannot be initialized if Cryptoki detects that any application has an open session with it; when a 2860 call to C_InitToken is made under such circumstances, the call fails with error CKR_SESSION_EXISTS. 2861 Unfortunately, it may happen when C_InitToken is called that some other application does have an open 2862 session with the token, but Cryptoki cannot detect this, because it cannot detect anything about other 2863 applications using the token. If this is the case, then the consequences of the C_InitToken call are 2864 undefined. 2865

The C_InitToken function may not be sufficient to properly initialize complex tokens. In these situations, 2866 an initialization mechanism outside the scope of Cryptoki MUST be employed. The definition of “complex 2867 token” is product specific. 2868

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 2869 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 2870 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_PIN_INCORRECT, 2871 CKR_PIN_LOCKED, CKR_SESSION_EXISTS, CKR_SLOT_ID_INVALID, 2872 CKR_TOKEN_NOT_PRESENT, CKR_TOKEN_NOT_RECOGNIZED, 2873 CKR_TOKEN_WRITE_PROTECTED, CKR_ARGUMENTS_BAD. 2874

Example: 2875


CK_UTF8CHAR pin[] = {“MyPIN”}; 2877


CK_UTF8CHAR label[32]; 2878

CK_RV rv; 2879

2880

. 2881

. 2882

memset(label, ‘ ’, sizeof(label)); 2883

memcpy(label, “My first token”, strlen(“My first token”)); 2884

rv = C_InitToken(slotID, pin, strlen(pin), label); 2885

if (rv == CKR_OK) { 2886

. 2887

. 2888

} 2889

5.5.8 C_InitPIN 2890

CK_DECLARE_FUNCTION(CK_RV, C_InitPIN)( 2891 CK_SESSION_HANDLE hSession, 2892 CK_UTF8CHAR_PTR pPin, 2893 CK_ULONG ulPinLen 2894 ); 2895

C_InitPIN initializes the normal user’s PIN. hSession is the session’s handle; pPin points to the normal 2896 user’s PIN; ulPinLen is the length in bytes of the PIN. This standard allows PIN values to contain any 2897

valid UTF8 character, but the token may impose subset restrictions. 2898

C_InitPIN can only be called in the “R/W SO Functions” state. An attempt to call it from a session in any 2899

other state fails with error CKR_USER_NOT_LOGGED_IN. 2900

If the token has a “protected authentication path”, as indicated by the 2901 CKF_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means 2902 that there is some way for a user to be authenticated to the token without having to send a PIN through 2903 the Cryptoki library. One such possibility is that the user enters a PIN on a PIN pad on the token itself, or 2904 on the slot device. To initialize the normal user’s PIN on a token with such a protected authentication 2905 path, the pPin parameter to C_InitPIN should be NULL_PTR. During the execution of C_InitPIN, the SO 2906

will enter the new PIN through the protected authentication path. 2907

If the token has a protected authentication path other than a PIN pad, then it is token-dependent whether 2908 or not C_InitPIN can be used to initialize the normal user’s token access. 2909

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 2910 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 2911 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_PIN_INVALID, 2912 CKR_PIN_LEN_RANGE, CKR_SESSION_CLOSED, CKR_SESSION_READ_ONLY, 2913 CKR_SESSION_HANDLE_INVALID, CKR_TOKEN_WRITE_PROTECTED, 2914 CKR_USER_NOT_LOGGED_IN, CKR_ARGUMENTS_BAD. 2915

Example: 2916

CK_SESSION_HANDLE hSession; 2917

CK_UTF8CHAR newPin[]= {“NewPIN”}; 2918

CK_RV rv; 2919

2920

rv = C_InitPIN(hSession, newPin, sizeof(newPin)-1); 2921

if (rv == CKR_OK) { 2922

. 2923


. 2924

} 2925

5.5.9 C_SetPIN 2926

CK_DECLARE_FUNCTION(CK_RV, C_SetPIN)( 2927 CK_SESSION_HANDLE hSession, 2928 CK_UTF8CHAR_PTR pOldPin, 2929 CK_ULONG ulOldLen, 2930 CK_UTF8CHAR_PTR pNewPin, 2931 CK_ULONG ulNewLen 2932 ); 2933

C_SetPIN modifies the PIN of the user that is currently logged in, or the CKU_USER PIN if the session is 2934 not logged in. hSession is the session’s handle; pOldPin points to the old PIN; ulOldLen is the length in 2935 bytes of the old PIN; pNewPin points to the new PIN; ulNewLen is the length in bytes of the new PIN. This 2936 standard allows PIN values to contain any valid UTF8 character, but the token may impose subset 2937 restrictions. 2938

C_SetPIN can only be called in the “R/W Public Session” state, “R/W SO Functions” state, or “R/W User 2939 Functions” state. An attempt to call it from a session in any other state fails with error 2940 CKR_SESSION_READ_ONLY. 2941

If the token has a “protected authentication path”, as indicated by the 2942 CKF_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means 2943 that there is some way for a user to be authenticated to the token without having to send a PIN through 2944 the Cryptoki library. One such possibility is that the user enters a PIN on a PIN pad on the token itself, or 2945 on the slot device. To modify the current user’s PIN on a token with such a protected authentication path, 2946 the pOldPin and pNewPin parameters to C_SetPIN should be NULL_PTR. During the execution of 2947 C_SetPIN, the current user will enter the old PIN and the new PIN through the protected authentication 2948 path. It is not specified how the PIN pad should be used to enter two PINs; this varies. 2949

If the token has a protected authentication path other than a PIN pad, then it is token-dependent whether 2950 or not C_SetPIN can be used to modify the current user’s PIN. 2951

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 2952 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 2953 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_PIN_INCORRECT, 2954 CKR_PIN_INVALID, CKR_PIN_LEN_RANGE, CKR_PIN_LOCKED, CKR_SESSION_CLOSED, 2955 CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, 2956 CKR_TOKEN_WRITE_PROTECTED, CKR_ARGUMENTS_BAD. 2957

Example: 2958


CK_UTF8CHAR oldPin[] = {“OldPIN”}; 2960

CK_UTF8CHAR newPin[] = {“NewPIN”}; 2961

CK_RV rv; 2962

2963

rv = C_SetPIN( 2964

hSession, oldPin, sizeof(oldPin)-1, newPin, sizeof(newPin)-1); 2965

if (rv == CKR_OK) { 2966

. 2967

. 2968

} 2969


5.6 Session management functions 2970

A typical application might perform the following series of steps to make use of a token (note that there 2971 are other reasonable sequences of events that an application might perform): 2972

1. Select a token. 2973

2. Make one or more calls to C_OpenSession to obtain one or more sessions with the token. 2974

3. Call C_Login to log the user into the token. Since all sessions an application has with a token have a 2975 shared login state, C_Login only needs to be called for one of the sessions. 2976

4. Perform cryptographic operations using the sessions with the token. 2977

5. Call C_CloseSession once for each session that the application has with the token, or call 2978 C_CloseAllSessions to close all the application’s sessions simultaneously. 2979

As has been observed, an application may have concurrent sessions with more than one token. It is also 2980 possible for a token to have concurrent sessions with more than one application. 2981

Cryptoki provides the following functions for session management: 2982

5.6.1 C_OpenSession 2983

CK_DECLARE_FUNCTION(CK_RV, C_OpenSession)( 2984 CK_SLOT_ID slotID, 2985 CK_FLAGS flags, 2986 CK_VOID_PTR pApplication, 2987 CK_NOTIFY Notify, 2988 CK_SESSION_HANDLE_PTR phSession 2989 ); 2990

C_OpenSession opens a session between an application and a token in a particular slot. slotID is the 2991 slot’s ID; flags indicates the type of session; pApplication is an application-defined pointer to be passed to 2992 the notification callback; Notify is the address of the notification callback function (see Section 5.21); 2993 phSession points to the location that receives the handle for the new session. 2994

When opening a session with C_OpenSession, the flags parameter consists of the logical OR of zero or 2995 more bit flags defined in the CK_SESSION_INFO data type. For legacy reasons, the 2996 CKF_SERIAL_SESSION bit MUST always be set; if a call to C_OpenSession does not have this bit set, 2997 the call should return unsuccessfully with the error code 2998 CKR_SESSION_PARALLEL_NOT_SUPPORTED. 2999

There may be a limit on the number of concurrent sessions an application may have with the token, which 3000 may depend on whether the session is “read-only” or “read/write”. An attempt to open a session which 3001 does not succeed because there are too many existing sessions of some type should return 3002 CKR_SESSION_COUNT. 3003

If the token is write-protected (as indicated in the CK_TOKEN_INFO structure), then only read-only 3004

sessions may be opened with it. 3005

If the application calling C_OpenSession already has a R/W SO session open with the token, then any 3006 attempt to open a R/O session with the token fails with error code 3007 CKR_SESSION_READ_WRITE_SO_EXISTS (see [PKCS11-UG] for further details). 3008

The Notify callback function is used by Cryptoki to notify the application of certain events. If the 3009 application does not wish to support callbacks, it should pass a value of NULL_PTR as the Notify 3010

parameter. See Section 5.21 for more information about application callbacks. 3011

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 3012 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3013 CKR_HOST_MEMORY, CKR_OK, CKR_SESSION_COUNT, 3014 CKR_SESSION_PARALLEL_NOT_SUPPORTED, CKR_SESSION_READ_WRITE_SO_EXISTS, 3015 CKR_SLOT_ID_INVALID, CKR_TOKEN_NOT_PRESENT, CKR_TOKEN_NOT_RECOGNIZED, 3016 CKR_TOKEN_WRITE_PROTECTED, CKR_ARGUMENTS_BAD. 3017

Example: see C_CloseSession. 3018


5.6.2 C_CloseSession 3019

CK_DECLARE_FUNCTION(CK_RV, C_CloseSession)( 3020 CK_SESSION_HANDLE hSession 3021 ); 3022

C_CloseSession closes a session between an application and a token. hSession is the session’s 3023

handle. 3024

When a session is closed, all session objects created by the session are destroyed automatically, even if 3025 the application has other sessions “using” the objects (see [PKCS11-UG] for further details). 3026

If this function is successful and it closes the last session between the application and the token, the login 3027 state of the token for the application returns to public sessions. Any new sessions to the token opened by 3028 the application will be either R/O Public or R/W Public sessions. 3029

Depending on the token, when the last open session any application has with the token is closed, the 3030 token may be “ejected” from its reader (if this capability exists). 3031

Despite the fact this C_CloseSession is supposed to close a session, the return value 3032 CKR_SESSION_CLOSED is an error return. It actually indicates the (probably somewhat unlikely) event 3033 that while this function call was executing, another call was made to C_CloseSession to close this 3034 particular session, and that call finished executing first. Such uses of sessions are a bad idea, and 3035 Cryptoki makes little promise of what will occur in general if an application indulges in this sort of 3036 behavior. 3037

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 3038 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3039 CKR_HOST_MEMORY, CKR_OK, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 3040

Example: 3041


CK_BYTE application; 3043

CK_NOTIFY MyNotify; 3044


CK_RV rv; 3046

3047

. 3048

. 3049

application = 17; 3050

MyNotify = &EncryptionSessionCallback; 3051

rv = C_OpenSession( 3052

slotID, CKF_SERIAL_SESSION | CKF_RW_SESSION, 3053

(CK_VOID_PTR) &application, MyNotify, 3054

&hSession); 3055

if (rv == CKR_OK) { 3056

. 3057

. 3058

C_CloseSession(hSession); 3059

} 3060


5.6.3 C_CloseAllSessions 3061

CK_DECLARE_FUNCTION(CK_RV, C_CloseAllSessions)( 3062 CK_SLOT_ID slotID 3063 ); 3064

C_CloseAllSessions closes all sessions an application has with a token. slotID specifies the token’s slot. 3065

When a session is closed, all session objects created by the session are destroyed automatically. 3066

After successful execution of this function, the login state of the token for the application returns to public 3067 sessions. Any new sessions to the token opened by the application will be either R/O Public or R/W 3068 Public sessions. 3069

Depending on the token, when the last open session any application has with the token is closed, the 3070 token may be “ejected” from its reader (if this capability exists). 3071

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 3072 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3073 CKR_HOST_MEMORY, CKR_OK, CKR_SLOT_ID_INVALID, CKR_TOKEN_NOT_PRESENT. 3074

Example: 3075


CK_RV rv; 3077

3078

. 3079

. 3080

rv = C_CloseAllSessions(slotID); 3081

5.6.4 C_GetSessionInfo 3082

CK_DECLARE_FUNCTION(CK_RV, C_GetSessionInfo)( 3083 CK_SESSION_HANDLE hSession, 3084 CK_SESSION_INFO_PTR pInfo 3085 ); 3086

C_GetSessionInfo obtains information about a session. hSession is the session’s handle; pInfo points to 3087

the location that receives the session information. 3088

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 3089 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3090 CKR_HOST_MEMORY, CKR_OK, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 3091 CKR_ARGUMENTS_BAD. 3092

Example: 3093


CK_SESSION_INFO info; 3095

CK_RV rv; 3096

3097

. 3098

. 3099

rv = C_GetSessionInfo(hSession, &info); 3100

if (rv == CKR_OK) { 3101

if (info.state == CKS_RW_USER_FUNCTIONS) { 3102

. 3103

. 3104


} 3105

. 3106

. 3107

} 3108

5.6.5 C_SessionCancel 3109

CK_DECLARE_FUNCTION(CK_RV, C_SessionCancel)( 3110 CK_SESSION_HANDLE hSession 3111 CK_FLAGS flags 3112 ); 3113

C_SessionCancel terminates active session based operations. hSession is the session’s handle; flags 3114

indicates the operations to cancel. 3115

To identify which operation(s) should be terminated, the flags parameter should be assigned the logical 3116 bitwise OR of one or more of the bit flags defined in the CK_MECHANISM_INFO structure. 3117

If no flags are set, the session state will not be modified and CKR_OK will be returned. 3118

If a flag is set for an operation that has not been initialized in the session, the operation flag will be 3119 ignored and C_SessionCancel will behave as if the operation flag was not set. 3120

If any of the operations indicated by the flags parameter cannot be cancelled, 3121 CKR_OPERATION_CANCEL_FAILED must be returned. If multiple operation flags were set and 3122 CKR_OPERATION_CANCEL_FAILED is returned, this function does not provide any information about 3123 which operation(s) could not be cancelled. If an application desires to know if any single operation could 3124 not be cancelled, the application should not call C_SessionCancel with multiple flags set. 3125

If C_SessionCancel is called from an application callback (see Section 5.16),5.21), no action will be 3126

taken by the library and CKR_FUNCTION_FAILED must be returned. 3127

If C_SessionCancel is used to cancel one half of a dual-function operation, the remaining operation 3128 should still be left in an active state. However, it is expected that some Cryptoki implementations may not 3129 support this and return CKR_OPERATION_CANCEL_FAILED unless flags for both operations are 3130 provided. 3131

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 3132 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3133 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_CANCEL_FAILED, 3134 CKR_TOKEN_NOT_PRESENT. 3135

Example: 3136


CK_RV rv; 3138

3139

rv = C_EncryptInit(hSession, &mechanism, hKey); 3140

if (rv != CKR_OK) 3141

{ 3142

. 3143

. 3144

} 3145

3146

rv = C_SessionCancel (hSession, CKF_ENCRYPT); 3147


{ 3149

. 3150


. 3151

} 3152

3153



{ 3156

. 3157

. 3158

} 3159

3160

3161 3162 3163 Below are modifications to existing API descriptions to allow an alternate method of cancelling individual 3164 operations. The additional text is highlighted. 3165

5.6.6 C_GetOperationState 3166

CK_DECLARE_FUNCTION(CK_RV, C_GetOperationState)( 3167 CK_SESSION_HANDLE hSession, 3168 CK_BYTE_PTR pOperationState, 3169 CK_ULONG_PTR pulOperationStateLen 3170 ); 3171

C_GetOperationState obtains a copy of the cryptographic operations state of a session, encoded as a 3172 string of bytes. hSession is the session’s handle; pOperationState points to the location that receives the 3173 state; pulOperationStateLen points to the location that receives the length in bytes of the state. 3174

Although the saved state output by C_GetOperationState is not really produced by a “cryptographic 3175 mechanism”, C_GetOperationState nonetheless uses the convention described in Section 5.2 on 3176

producing output. 3177

Precisely what the “cryptographic operations state” this function saves is varies from token to token; 3178 however, this state is what is provided as input to C_SetOperationState to restore the cryptographic 3179

activities of a session. 3180

Consider a session which is performing a message digest operation using SHA-1 (i.e., the session is 3181 using the CKM_SHA_1 mechanism). Suppose that the message digest operation was initialized 3182 properly, and that precisely 80 bytes of data have been supplied so far as input to SHA-1. The 3183 application now wants to “save the state” of this digest operation, so that it can continue it later. In this 3184 particular case, since SHA-1 processes 512 bits (64 bytes) of input at a time, the cryptographic 3185 operations state of the session most likely consists of three distinct parts: the state of SHA-1’s 160-bit 3186 internal chaining variable; the 16 bytes of unprocessed input data; and some administrative data 3187 indicating that this saved state comes from a session which was performing SHA-1 hashing. Taken 3188 together, these three pieces of information suffice to continue the current hashing operation at a later 3189 time. 3190

Consider next a session which is performing an encryption operation with DES (a block cipher with a 3191 block size of 64 bits) in CBC (cipher-block chaining) mode (i.e., the session is using the CKM_DES_CBC 3192 mechanism). Suppose that precisely 22 bytes of data (in addition to an IV for the CBC mode) have been 3193 supplied so far as input to DES, which means that the first two 8-byte blocks of ciphertext have already 3194 been produced and output. In this case, the cryptographic operations state of the session most likely 3195 consists of three or four distinct parts: the second 8-byte block of ciphertext (this will be used for cipher-3196 block chaining to produce the next block of ciphertext); the 6 bytes of data still awaiting encryption; some 3197 administrative data indicating that this saved state comes from a session which was performing DES 3198


encryption in CBC mode; and possibly the DES key being used for encryption (see C_SetOperationState 3199

for more information on whether or not the key is present in the saved state). 3200

If a session is performing two cryptographic operations simultaneously (see Section 5.14), then the 3201 cryptographic operations state of the session will contain all the necessary information to restore both 3202 operations. 3203

An attempt to save the cryptographic operations state of a session which does not currently have some 3204 active savable cryptographic operation(s) (encryption, decryption, digesting, signing without message 3205 recovery, verification without message recovery, or some legal combination of two of these) should fail 3206 with the error CKR_OPERATION_NOT_INITIALIZED. 3207

An attempt to save the cryptographic operations state of a session which is performing an appropriate 3208 cryptographic operation (or two), but which cannot be satisfied for any of various reasons (certain 3209 necessary state information and/or key information can’t leave the token, for example) should fail with the 3210 error CKR_STATE_UNSAVEABLE. 3211

Return values: CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, 3212 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 3213 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, 3214 CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 3215 CKR_STATE_UNSAVEABLE, CKR_ARGUMENTS_BAD. 3216

Example: see C_SetOperationState. 3217

5.6.7 C_SetOperationState 3218

CK_DECLARE_FUNCTION(CK_RV, C_SetOperationState)( 3219 CK_SESSION_HANDLE hSession, 3220 CK_BYTE_PTR pOperationState, 3221 CK_ULONG ulOperationStateLen, 3222 CK_OBJECT_HANDLE hEncryptionKey, 3223 CK_OBJECT_HANDLE hAuthenticationKey 3224 ); 3225

C_SetOperationState restores the cryptographic operations state of a session from a string of bytes 3226 obtained with C_GetOperationState. hSession is the session’s handle; pOperationState points to the 3227 location holding the saved state; ulOperationStateLen holds the length of the saved state; 3228 hEncryptionKey holds a handle to the key which will be used for an ongoing encryption or decryption 3229 operation in the restored session (or 0 if no encryption or decryption key is needed, either because no 3230 such operation is ongoing in the stored session or because all the necessary key information is present in 3231 the saved state); hAuthenticationKey holds a handle to the key which will be used for an ongoing 3232 signature, MACing, or verification operation in the restored session (or 0 if no such key is needed, either 3233 because no such operation is ongoing in the stored session or because all the necessary key information 3234 is present in the saved state). 3235

The state need not have been obtained from the same session (the “source session”) as it is being 3236 restored to (the “destination session”). However, the source session and destination session should have 3237 a common session state (e.g., CKS_RW_USER_FUNCTIONS), and should be with a common token. 3238 There is also no guarantee that cryptographic operations state may be carried across logins, or across 3239 different Cryptoki implementations. 3240

If C_SetOperationState is supplied with alleged saved cryptographic operations state which it can 3241 determine is not valid saved state (or is cryptographic operations state from a session with a different 3242 session state, or is cryptographic operations state from a different token), it fails with the error 3243 CKR_SAVED_STATE_INVALID. 3244

Saved state obtained from calls to C_GetOperationState may or may not contain information about keys 3245 in use for ongoing cryptographic operations. If a saved cryptographic operations state has an ongoing 3246 encryption or decryption operation, and the key in use for the operation is not saved in the state, then it 3247 MUST be supplied to C_SetOperationState in the hEncryptionKey argument. If it is not, then 3248 C_SetOperationState will fail and return the error CKR_KEY_NEEDED. If the key in use for the 3249


operation is saved in the state, then it can be supplied in the hEncryptionKey argument, but this is not 3250

required. 3251

Similarly, if a saved cryptographic operations state has an ongoing signature, MACing, or verification 3252 operation, and the key in use for the operation is not saved in the state, then it MUST be supplied to 3253 C_SetOperationState in the hAuthenticationKey argument. If it is not, then C_SetOperationState will 3254 fail with the error CKR_KEY_NEEDED. If the key in use for the operation is saved in the state, then it can 3255 be supplied in the hAuthenticationKey argument, but this is not required. 3256

If an irrelevant key is supplied to C_SetOperationState call (e.g., a nonzero key handle is submitted in 3257 the hEncryptionKey argument, but the saved cryptographic operations state supplied does not have an 3258 ongoing encryption or decryption operation, then C_SetOperationState fails with the error 3259

CKR_KEY_NOT_NEEDED. 3260

If a key is supplied as an argument to C_SetOperationState, and C_SetOperationState can somehow 3261 detect that this key was not the key being used in the source session for the supplied cryptographic 3262 operations state (it may be able to detect this if the key or a hash of the key is present in the saved state, 3263 for example), then C_SetOperationState fails with the error CKR_KEY_CHANGED. 3264

An application can look at the CKF_RESTORE_KEY_NOT_NEEDED flag in the flags field of the 3265 CK_TOKEN_INFO field for a token to determine whether or not it needs to supply key handles to 3266 C_SetOperationState calls. If this flag is true, then a call to C_SetOperationState never needs a key 3267 handle to be supplied to it. If this flag is false, then at least some of the time, C_SetOperationState 3268 requires a key handle, and so the application should probably always pass in any relevant key handles 3269

when restoring cryptographic operations state to a session. 3270

C_SetOperationState can successfully restore cryptographic operations state to a session even if that 3271 session has active cryptographic or object search operations when C_SetOperationState is called (the 3272

ongoing operations are abruptly cancelled). 3273

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 3274 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3275 CKR_HOST_MEMORY, CKR_KEY_CHANGED, CKR_KEY_NEEDED, CKR_KEY_NOT_NEEDED, 3276 CKR_OK, CKR_SAVED_STATE_INVALID, CKR_SESSION_CLOSED, 3277 CKR_SESSION_HANDLE_INVALID, CKR_ARGUMENTS_BAD. 3278

Example: 3279


CK_MECHANISM digestMechanism; 3281

CK_BYTE_PTR pState; 3282

CK_ULONG ulStateLen; 3283

CK_BYTE data1[] = {0x01, 0x03, 0x05, 0x07}; 3284

CK_BYTE data2[] = {0x02, 0x04, 0x08}; 3285

CK_BYTE data3[] = {0x10, 0x0F, 0x0E, 0x0D, 0x0C}; 3286

CK_BYTE pDigest[20]; 3287

CK_ULONG ulDigestLen; 3288

CK_RV rv; 3289

3290

. 3291

. 3292

/* Initialize hash operation */ 3293

rv = C_DigestInit(hSession, &digestMechanism); 3294


3296

/* Start hashing */ 3297




rv = C_DigestUpdate(hSession, data1, sizeof(data1)); 3298


3300

/* Find out how big the state might be */ 3301

rv = C_GetOperationState(hSession, NULL_PTR, &ulStateLen); 3302


3304

/* Allocate some memory and then get the state */ 3305

pState = (CK_BYTE_PTR) malloc(ulStateLen); 3306

rv = C_GetOperationState(hSession, pState, &ulStateLen); 3307

3308

/* Continue hashing */ 3309



3312

/* Restore state. No key handles needed */ 3313

rv = C_SetOperationState(hSession, pState, ulStateLen, 0, 0); 3314


3316

/* Continue hashing from where we saved state */ 3317



3320

/* Conclude hashing operation */ 3321

ulDigestLen = sizeof(pDigest); 3322

rv = C_DigestFinal(hSession, pDigest, &ulDigestLen); 3323

if (rv == CKR_OK) { 3324

/* pDigest[] now contains the hash of 0x01030507100F0E0D0C */ 3325

. 3326

. 3327

} 3328

5.6.8 C_Login 3329

CK_DECLARE_FUNCTION(CK_RV, C_Login)( 3330 CK_SESSION_HANDLE hSession, 3331 CK_USER_TYPE userType, 3332 CK_UTF8CHAR_PTR pPin, 3333 CK_ULONG ulPinLen 3334 ); 3335

C_Login logs a user into a token. hSession is a session handle; userType is the user type; pPin points to 3336 the user’s PIN; ulPinLen is the length of the PIN. This standard allows PIN values to contain any valid 3337 UTF8 character, but the token may impose subset restrictions. 3338

When the user type is either CKU_SO or CKU_USER, if the call succeeds, each of the application's 3339 sessions will enter either the "R/W SO Functions" state, the "R/W User Functions" state, or the "R/O User 3340 Functions" state. If the user type is CKU_CONTEXT_SPECIFIC, the behavior of C_Login depends on the 3341



context in which it is called. Improper use of this user type will result in a return value 3342 CKR_OPERATION_NOT_INITIALIZED.. 3343

If the token has a “protected authentication path”, as indicated by the 3344 CKF_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means 3345 that there is some way for a user to be authenticated to the token without having to send a PIN through 3346 the Cryptoki library. One such possibility is that the user enters a PIN on a PIN pad on the token itself, or 3347 on the slot device. Or the user might not even use a PIN—authentication could be achieved by some 3348 fingerprint-reading device, for example. To log into a token with a protected authentication path, the pPin 3349 parameter to C_Login should be NULL_PTR. When C_Login returns, whatever authentication method 3350 supported by the token will have been performed; a return value of CKR_OK means that the user was 3351 successfully authenticated, and a return value of CKR_PIN_INCORRECT means that the user was 3352 denied access. 3353

If there are any active cryptographic or object finding operations in an application’s session, and then 3354 C_Login is successfully executed by that application, it may or may not be the case that those operations 3355

are still active. Therefore, before logging in, any active operations should be finished. 3356

If the application calling C_Login has a R/O session open with the token, then it will be unable to log the 3357 SO into a session (see [PKCS11-UG] for further details). An attempt to do this will result in the error code 3358

CKR_SESSION_READ_ONLY_EXISTS. 3359

C_Login may be called repeatedly, without intervening C_Logout calls, if (and only if) a key with the 3360 CKA_ALWAYS_AUTHENTICATE attribute set to CK_TRUE exists, and the user needs to do 3361 cryptographic operation on this key. See further Section 4.9. 3362

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 3363 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 3364 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3365 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_PIN_INCORRECT, 3366 CKR_PIN_LOCKED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 3367 CKR_SESSION_READ_ONLY_EXISTS, CKR_USER_ALREADY_LOGGED_IN, 3368 CKR_USER_ANOTHER_ALREADY_LOGGED_IN, CKR_USER_PIN_NOT_INITIALIZED, 3369 CKR_USER_TOO_MANY_TYPES, CKR_USER_TYPE_INVALID. 3370

Example: see C_Logout. 3371

5.6.9 C_LoginUser 3372

CK_DECLARE_FUNCTION(CK_RV, C_LoginUser)( 3373 CK_SESSION_HANDLE hSession, 3374 CK_USER_TYPE userType, 3375 CK_UTF8CHAR_PTR pPin, 3376 CK_ULONG ulPinLen, 3377 CK_UTF8CHAR_PTR pUsername, 3378 CK_ULONG ulUsernameLen 3379 ); 3380

C_LoginUser logs a user into a token. hSession is a session handle; userType is the user type; pPin 3381 points to the user’s PIN; ulPinLen is the length of the PIN, pUsername points to the user name, 3382 ulUsernameLen is the length of the user name. This standard allows PIN and user name values to 3383 contain any valid UTF8 character, but the token may impose subset restrictions. 3384

When the user type is either CKU_SO or CKU_USER, if the call succeeds, each of the application's 3385 sessions will enter either the "R/W SO Functions" state, the "R/W User Functions" state, or the "R/O User 3386 Functions" state. If the user type is CKU_CONTEXT_SPECIFIC, the behavior of C_LoginUser depends 3387 on the context in which it is called. Improper use of this user type will result in a return value 3388 CKR_OPERATION_NOT_INITIALIZED. 3389

If the token has a “protected authentication path”, as indicated by the 3390 CKF_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means 3391 that there is some way for a user to be authenticated to the token without having to send a PIN through 3392 the Cryptoki library. One such possibility is that the user enters a PIN on a PIN pad on the token itself, or 3393


on the slot device. The user might not even use a PIN—authentication could be achieved by some 3394 fingerprint-reading device, for example. To log into a token with a protected authentication path, the pPin 3395 parameter to C_LoginUser should be NULL_PTR. When C_LoginUser returns, whatever authentication 3396 method supported by the token will have been performed; a return value of CKR_OK means that the user 3397 was successfully authenticated, and a return value of CKR_PIN_INCORRECT means that the user was 3398 denied access. 3399

If there are any active cryptographic or object finding operations in an application’s session, and then 3400 C_LoginUser is successfully executed by that application, it may or may not be the case that those 3401

operations are still active. Therefore, before logging in, any active operations should be finished. 3402

If the application calling C_LoginUser has a R/O session open with the token, then it will be unable to log 3403 the SO into a session (see [PKCS11-UG] for further details). An attempt to do this will result in the error 3404 code CKR_SESSION_READ_ONLY_EXISTS. 3405

C_LoginUser may be called repeatedly, without intervening C_Logout calls, if (and only if) a key with the 3406 CKA_ALWAYS_AUTHENTICATE attribute set to CK_TRUE exists, and the user needs to do 3407 cryptographic operation on this key. See further Section 4.9. 3408

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 3409 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 3410 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3411 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_PIN_INCORRECT, 3412 CKR_PIN_LOCKED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 3413 CKR_SESSION_READ_ONLY_EXISTS, CKR_USER_ALREADY_LOGGED_IN, 3414 CKR_USER_ANOTHER_ALREADY_LOGGED_IN, CKR_USER_PIN_NOT_INITIALIZED, 3415 CKR_USER_TOO_MANY_TYPES, CKR_USER_TYPE_INVALID. 3416

Example: 3417


CK_UTF8CHAR userPin[] = {“MyPIN”}; 3419

CK_UTF8CHAR userName[] = {“MyUserName”}; 3420

CK_RV rv; 3421

3422

rv = C_LoginUser(hSession, CKU_USER, userPin, sizeof(userPin)-1, userName, 3423

sizeof(userName)-1); 3424

if (rv == CKR_OK) { 3425

. 3426

. 3427

rv = C_Logout(hSession); 3428

if (rv == CKR_OK) { 3429

. 3430

. 3431

} 3432

} 3433

5.6.10 C_Logout 3434

CK_DECLARE_FUNCTION(CK_RV, C_Logout)( 3435 CK_SESSION_HANDLE hSession 3436 ); 3437

C_Logout logs a user out from a token. hSession is the session’s handle. 3438

Depending on the current user type, if the call succeeds, each of the application’s sessions will enter 3439 either the “R/W Public Session” state or the “R/O Public Session” state. 3440


When C_Logout successfully executes, any of the application’s handles to private objects become invalid 3441 (even if a user is later logged back into the token, those handles remain invalid). In addition, all private 3442 session objects from sessions belonging to the application are destroyed. 3443

If there are any active cryptographic or object-finding operations in an application’s session, and then 3444 C_Logout is successfully executed by that application, it may or may not be the case that those 3445 operations are still active. Therefore, before logging out, any active operations should be finished. 3446

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 3447 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3448 CKR_HOST_MEMORY, CKR_OK, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 3449 CKR_USER_NOT_LOGGED_IN. 3450

Example: 3451


CK_UTF8CHAR userPin[] = {“MyPIN”}; 3453

CK_RV rv; 3454

3455

rv = C_Login(hSession, CKU_USER, userPin, sizeof(userPin)-1); 3456

if (rv == CKR_OK) { 3457

. 3458

. 3459

rv = C_Logout(hSession); 3460

if (rv == CKR_OK) { 3461

. 3462

. 3463

} 3464

} 3465

5.7 Object management functions 3466

Cryptoki provides the following functions for managing objects. Additional functions provided specifically 3467 for managing key objects are described in Section 5.18. 3468

5.7.1 C_CreateObject 3469

CK_DECLARE_FUNCTION(CK_RV, C_CreateObject)( 3470 CK_SESSION_HANDLE hSession, 3471 CK_ATTRIBUTE_PTR pTemplate, 3472 CK_ULONG ulCount, 3473 CK_OBJECT_HANDLE_PTR phObject 3474 ); 3475

C_CreateObject creates a new object. hSession is the session’s handle; pTemplate points to the object’s 3476 template; ulCount is the number of attributes in the template; phObject points to the location that receives 3477

the new object’s handle. 3478

If a call to C_CreateObject cannot support the precise template supplied to it, it will fail and return without 3479

creating any object. 3480

If C_CreateObject is used to create a key object, the key object will have its CKA_LOCAL attribute set to 3481 CK_FALSE. If that key object is a secret or private key then the new key will have the 3482 CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, and the CKA_NEVER_EXTRACTABLE 3483

attribute set to CK_FALSE. 3484

Only session objects can be created during a read-only session. Only public objects can be created 3485 unless the normal user is logged in. 3486


Whenever an object is created, a value for CKA_UNIQUE_ID is generated and assigned to the new 3487 object (See Section 4.4.1). 3488

Return values: CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, 3489 CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, 3490 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, 3491 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, 3492 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, 3493 CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 3494 CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT, 3495 CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN. 3496

Example: 3497


CK_OBJECT_HANDLE 3499

hData, 3500

hCertificate, 3501

hKey; 3502

CK_OBJECT_CLASS 3503

dataClass = CKO_DATA, 3504

certificateClass = CKO_CERTIFICATE, 3505

keyClass = CKO_PUBLIC_KEY; 3506

CK_KEY_TYPE keyType = CKK_RSA; 3507

CK_UTF8CHAR application[] = {“My Application”}; 3508

CK_BYTE dataValue[] = {...}; 3509

CK_BYTE subject[] = {...}; 3510

CK_BYTE id[] = {...}; 3511

CK_BYTE certificateValue[] = {...}; 3512

CK_BYTE modulus[] = {...}; 3513

CK_BYTE exponent[] = {...}; 3514

CK_BBOOL true = CK_TRUE; 3515

CK_ATTRIBUTE dataTemplate[] = { 3516

{CKA_CLASS, &dataClass, sizeof(dataClass)}, 3517

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

{CKA_APPLICATION, application, sizeof(application)-1}, 3519

{CKA_VALUE, dataValue, sizeof(dataValue)} 3520

}; 3521

CK_ATTRIBUTE certificateTemplate[] = { 3522

{CKA_CLASS, &certificateClass, sizeof(certificateClass)}, 3523


{CKA_SUBJECT, subject, sizeof(subject)}, 3525

{CKA_ID, id, sizeof(id)}, 3526

{CKA_VALUE, certificateValue, sizeof(certificateValue)} 3527

}; 3528

CK_ATTRIBUTE keyTemplate[] = { 3529

{CKA_CLASS, &keyClass, sizeof(keyClass)}, 3530

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


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

{CKA_MODULUS, modulus, sizeof(modulus)}, 3533

{CKA_PUBLIC_EXPONENT, exponent, sizeof(exponent)} 3534

}; 3535

CK_RV rv; 3536

3537

. 3538

. 3539

/* Create a data object */ 3540

rv = C_CreateObject(hSession, dataTemplate, 4, &hData); 3541

if (rv == CKR_OK) { 3542

. 3543

. 3544

} 3545

3546

/* Create a certificate object */ 3547

rv = C_CreateObject( 3548

hSession, certificateTemplate, 5, &hCertificate); 3549

if (rv == CKR_OK) { 3550

. 3551

. 3552

} 3553

3554

/* Create an RSA public key object */ 3555

rv = C_CreateObject(hSession, keyTemplate, 5, &hKey); 3556

if (rv == CKR_OK) { 3557

. 3558

. 3559

} 3560

5.7.2 C_CopyObject 3561

CK_DECLARE_FUNCTION(CK_RV, C_CopyObject)( 3562 CK_SESSION_HANDLE hSession, 3563 CK_OBJECT_HANDLE hObject, 3564 CK_ATTRIBUTE_PTR pTemplate, 3565 CK_ULONG ulCount, 3566 CK_OBJECT_HANDLE_PTR phNewObject 3567 ); 3568

C_CopyObject copies an object, creating a new object for the copy. hSession is the session’s handle; 3569 hObject is the object’s handle; pTemplate points to the template for the new object; ulCount is the number 3570 of attributes in the template; phNewObject points to the location that receives the handle for the copy of 3571

the object. 3572

The template may specify new values for any attributes of the object that can ordinarily be modified (e.g., 3573 in the course of copying a secret key, a key’s CKA_EXTRACTABLE attribute may be changed from 3574 CK_TRUE to CK_FALSE, but not the other way around. If this change is made, the new key’s 3575 CKA_NEVER_EXTRACTABLE attribute will have the value CK_FALSE. Similarly, the template may 3576


specify that the new key’s CKA_SENSITIVE attribute be CK_TRUE; the new key will have the same 3577 value for its CKA_ALWAYS_SENSITIVE attribute as the original key). It may also specify new values of 3578 the CKA_TOKEN and CKA_PRIVATE attributes (e.g., to copy a session object to a token object). If the 3579 template specifies a value of an attribute which is incompatible with other existing attributes of the object, 3580 the call fails with the return code CKR_TEMPLATE_INCONSISTENT. 3581

If a call to C_CopyObject cannot support the precise template supplied to it, it will fail and return without 3582 creating any object. If the object indicated by hObject has its CKA_COPYABLE attribute set to 3583 CK_FALSE, C_CopyObject will return CKR_ACTION_PROHIBITED. 3584

Whenever an object is copied, a new value for CKA_UNIQUE_ID is generated and assigned to the new 3585 object (See Section 4.4.1). 3586

Only session objects can be created during a read-only session. Only public objects can be created 3587 unless the normal user is logged in. 3588

Return values: , CKR_ACTION_PROHIBITED, CKR_ARGUMENTS_BAD, 3589 CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, 3590 CKR_ATTRIBUTE_VALUE_INVALID, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, 3591 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, 3592 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OBJECT_HANDLE_INVALID, CKR_OK, 3593 CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 3594 CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCONSISTENT, 3595 CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN. 3596

Example: 3597


CK_OBJECT_HANDLE hKey, hNewKey; 3599

CK_OBJECT_CLASS keyClass = CKO_SECRET_KEY; 3600

CK_KEY_TYPE keyType = CKK_DES; 3601

CK_BYTE id[] = {...}; 3602

CK_BYTE keyValue[] = {...}; 3603

CK_BBOOL false = CK_FALSE; 3604


CK_ATTRIBUTE keyTemplate[] = { 3606



{CKA_TOKEN, &false, sizeof(false)}, 3609


{CKA_VALUE, keyValue, sizeof(keyValue)} 3611

}; 3612

CK_ATTRIBUTE copyTemplate[] = { 3613

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

}; 3615

CK_RV rv; 3616

3617

. 3618

. 3619

/* Create a DES secret key session object */ 3620

rv = C_CreateObject(hSession, keyTemplate, 5, &hKey); 3621

if (rv == CKR_OK) { 3622


/* Create a copy which is a token object */ 3623

rv = C_CopyObject(hSession, hKey, copyTemplate, 1, &hNewKey); 3624

. 3625

. 3626

} 3627

5.7.3 C_DestroyObject 3628

CK_DECLARE_FUNCTION(CK_RV, C_DestroyObject)( 3629 CK_SESSION_HANDLE hSession, 3630 CK_OBJECT_HANDLE hObject 3631 ); 3632

C_DestroyObject destroys an object. hSession is the session’s handle; and hObject is the object’s 3633

handle. 3634

Only session objects can be destroyed during a read-only session. Only public objects can be destroyed 3635 unless the normal user is logged in. 3636

Certain objects may not be destroyed. Calling C_DestroyObject on such objects will result in the 3637 CKR_ACTION_PROHIBITED error code. An application can consult the object's CKA_DESTROYABLE 3638 attribute to determine if an object may be destroyed or not. 3639

Return values: CKR_ACTION_PROHIBITED, CKR_CRYPTOKI_NOT_INITIALIZED, 3640 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 3641 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, 3642 CKR_OBJECT_HANDLE_INVALID, CKR_OK, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, 3643 CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, 3644 CKR_TOKEN_WRITE_PROTECTED. 3645

Example: see C_GetObjectSize. 3646

5.7.4 C_GetObjectSize 3647

CK_DECLARE_FUNCTION(CK_RV, C_GetObjectSize)( 3648 CK_SESSION_HANDLE hSession, 3649 CK_OBJECT_HANDLE hObject, 3650 CK_ULONG_PTR pulSize 3651 ); 3652

C_GetObjectSize gets the size of an object in bytes. hSession is the session’s handle; hObject is the 3653 object’s handle; pulSize points to the location that receives the size in bytes of the object. 3654

Cryptoki does not specify what the precise meaning of an object’s size is. Intuitively, it is some measure 3655 of how much token memory the object takes up. If an application deletes (say) a private object of size S, 3656 it might be reasonable to assume that the ulFreePrivateMemory field of the token’s CK_TOKEN_INFO 3657

structure increases by approximately S. 3658

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 3659 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 3660 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, 3661 CKR_INFORMATION_SENSITIVE, CKR_OBJECT_HANDLE_INVALID, CKR_OK, 3662 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 3663

Example: 3664


CK_OBJECT_HANDLE hObject; 3666

CK_OBJECT_CLASS dataClass = CKO_DATA; 3667

CK_UTF8CHAR application[] = {“My Application”}; 3668


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


CK_ATTRIBUTE template[] = { 3671

{CKA_CLASS, &dataClass, sizeof(dataClass)}, 3672


{CKA_APPLICATION, application, sizeof(application)-1}, 3674

{CKA_VALUE, value, sizeof(value)} 3675

}; 3676

CK_ULONG ulSize; 3677

CK_RV rv; 3678

3679

. 3680

. 3681

rv = C_CreateObject(hSession, template, 4, &hObject); 3682

if (rv == CKR_OK) { 3683

rv = C_GetObjectSize(hSession, hObject, &ulSize); 3684

if (rv != CKR_INFORMATION_SENSITIVE) { 3685

. 3686

. 3687

} 3688

3689

rv = C_DestroyObject(hSession, hObject); 3690

. 3691

. 3692

} 3693

5.7.5 C_GetAttributeValue 3694

CK_DECLARE_FUNCTION(CK_RV, C_GetAttributeValue)( 3695 CK_SESSION_HANDLE hSession, 3696 CK_OBJECT_HANDLE hObject, 3697 CK_ATTRIBUTE_PTR pTemplate, 3698 CK_ULONG ulCount 3699 ); 3700

C_GetAttributeValue obtains the value of one or more attributes of an object. hSession is the session’s 3701 handle; hObject is the object’s handle; pTemplate points to a template that specifies which attribute 3702 values are to be obtained, and receives the attribute values; ulCount is the number of attributes in the 3703

template. 3704

For each (type, pValue, ulValueLen) triple in the template, C_GetAttributeValue performs the following 3705

algorithm: 3706

1. If the specified attribute (i.e., the attribute specified by the type field) for the object cannot be revealed 3707 because the object is sensitive or unextractable, then the ulValueLen field in that triple is modified to 3708 hold the value CK_UNAVAILABLE_INFORMATION. 3709

2. Otherwise, if the specified value for the object is invalid (the object does not possess such an 3710 attribute), then the ulValueLen field in that triple is modified to hold the value 3711 CK_UNAVAILABLE_INFORMATION. 3712


3. Otherwise, if the pValue field has the value NULL_PTR, then the ulValueLen field is modified to hold 3713

the exact length of the specified attribute for the object. 3714

4. Otherwise, if the length specified in ulValueLen is large enough to hold the value of the specified 3715 attribute for the object, then that attribute is copied into the buffer located at pValue, and the 3716 ulValueLen field is modified to hold the exact length of the attribute. 3717

5. Otherwise, the ulValueLen field is modified to hold the value CK_UNAVAILABLE_INFORMATION. 3718

If case 1 applies to any of the requested attributes, then the call should return the value 3719 CKR_ATTRIBUTE_SENSITIVE. If case 2 applies to any of the requested attributes, then the call should 3720 return the value CKR_ATTRIBUTE_TYPE_INVALID. If case 5 applies to any of the requested attributes, 3721 then the call should return the value CKR_BUFFER_TOO_SMALL. As usual, if more than one of these 3722 error codes is applicable, Cryptoki may return any of them. Only if none of them applies to any of the 3723 requested attributes will CKR_OK be returned. 3724

In the special case of an attribute whose value is an array of attributes, for example 3725 CKA_WRAP_TEMPLATE, where it is passed in with pValue not NULL, the length specified in ulValueLen 3726 MUST be large enough to hold all attributes in the array. If the pValue of elements within the array is 3727 NULL_PTR then the ulValueLen of elements within the array will be set to the required length. If the 3728 pValue of elements within the array is not NULL_PTR, then the ulValueLen element of attributes within 3729 the array MUST reflect the space that the corresponding pValue points to, and pValue is filled in if there is 3730 sufficient room. Therefore it is important to initialize the contents of a buffer before calling 3731 C_GetAttributeValue to get such an array value. Note that the type element of attributes within the array 3732 MUST be ignored on input and MUST be set on output. If any ulValueLen within the array isn't large 3733 enough, it will be set to CK_UNAVAILABLE_INFORMATION and the function will return 3734 CKR_BUFFER_TOO_SMALL, as it does if an attribute in the pTemplate argument has ulValueLen too 3735 small. Note that any attribute whose value is an array of attributes is identifiable by virtue of the attribute 3736 type having the CKF_ARRAY_ATTRIBUTE bit set. 3737

Note that the error codes CKR_ATTRIBUTE_SENSITIVE, CKR_ATTRIBUTE_TYPE_INVALID, and 3738 CKR_BUFFER_TOO_SMALL do not denote true errors for C_GetAttributeValue. If a call to 3739 C_GetAttributeValue returns any of these three values, then the call MUST nonetheless have processed 3740 every attribute in the template supplied to C_GetAttributeValue. Each attribute in the template whose 3741 value can be returned by the call to C_GetAttributeValue will be returned by the call to 3742 C_GetAttributeValue. 3743

Return values: CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_SENSITIVE, 3744 CKR_ATTRIBUTE_TYPE_INVALID, CKR_BUFFER_TOO_SMALL, 3745 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 3746 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3747 CKR_HOST_MEMORY, CKR_OBJECT_HANDLE_INVALID, CKR_OK, CKR_SESSION_CLOSED, 3748 CKR_SESSION_HANDLE_INVALID. 3749

Example: 3750



CK_BYTE_PTR pModulus, pExponent; 3753


{CKA_MODULUS, NULL_PTR, 0}, 3755

{CKA_PUBLIC_EXPONENT, NULL_PTR, 0} 3756

}; 3757

CK_RV rv; 3758

3759

. 3760

. 3761

rv = C_GetAttributeValue(hSession, hObject, template, 2); 3762


if (rv == CKR_OK) { 3763

pModulus = (CK_BYTE_PTR) malloc(template[0].ulValueLen); 3764

template[0].pValue = pModulus; 3765

/* template[0].ulValueLen was set by C_GetAttributeValue */ 3766

3767

pExponent = (CK_BYTE_PTR) malloc(template[1].ulValueLen); 3768

template[1].pValue = pExponent; 3769

/* template[1].ulValueLen was set by C_GetAttributeValue */ 3770

3771

rv = C_GetAttributeValue(hSession, hObject, template, 2); 3772

if (rv == CKR_OK) { 3773

. 3774

. 3775

} 3776

free(pModulus); 3777

free(pExponent); 3778

} 3779

5.7.6 C_SetAttributeValue 3780

CK_DECLARE_FUNCTION(CK_RV, C_SetAttributeValue)( 3781 CK_SESSION_HANDLE hSession, 3782 CK_OBJECT_HANDLE hObject, 3783 CK_ATTRIBUTE_PTR pTemplate, 3784 CK_ULONG ulCount 3785 ); 3786

C_SetAttributeValue modifies the value of one or more attributes of an object. hSession is the session’s 3787 handle; hObject is the object’s handle; pTemplate points to a template that specifies which attribute 3788 values are to be modified and their new values; ulCount is the number of attributes in the template. 3789

Certain objects may not be modified. Calling C_SetAttributeValue on such objects will result in the 3790 CKR_ACTION_PROHIBITED error code. An application can consult the object's CKA_MODIFIABLE 3791 attribute to determine if an object may be modified or not. 3792

Only session objects can be modified during a read-only session. 3793

The template may specify new values for any attributes of the object that can be modified. If the template 3794 specifies a value of an attribute which is incompatible with other existing attributes of the object, the call 3795 fails with the return code CKR_TEMPLATE_INCONSISTENT. 3796

Not all attributes can be modified; see Section 4.1.2 for more details. 3797

Return values: CKR_ACTION_PROHIBITED, CKR_ARGUMENTS_BAD, 3798 CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, 3799 CKR_ATTRIBUTE_VALUE_INVALID, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, 3800 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, 3801 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OBJECT_HANDLE_INVALID, CKR_OK, 3802 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, 3803 CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, 3804 CKR_USER_NOT_LOGGED_IN. 3805

Example: 3806




CK_UTF8CHAR label[] = {“New label”}; 3809


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

}; 3812

CK_RV rv; 3813

3814

. 3815

. 3816

rv = C_SetAttributeValue(hSession, hObject, template, 1); 3817

if (rv == CKR_OK) { 3818

. 3819

. 3820

} 3821

5.7.7 C_FindObjectsInit 3822

CK_DECLARE_FUNCTION(CK_RV, C_FindObjectsInit)( 3823 CK_SESSION_HANDLE hSession, 3824 CK_ATTRIBUTE_PTR pTemplate, 3825 CK_ULONG ulCount 3826 ); 3827

C_FindObjectsInit initializes a search for token and session objects that match a template. hSession is 3828 the session’s handle; pTemplate points to a search template that specifies the attribute values to match; 3829 ulCount is the number of attributes in the search template. The matching criterion is an exact byte-for-3830 byte match with all attributes in the template. To find all objects, set ulCount to 0. 3831

After calling C_FindObjectsInit, the application may call C_FindObjects one or more times to obtain 3832 handles for objects matching the template, and then eventually call C_FindObjectsFinal to finish the 3833 active search operation. At most one search operation may be active at a given time in a given session. 3834

The object search operation will only find objects that the session can view. For example, an object 3835 search in an “R/W Public Session” will not find any private objects (even if one of the attributes in the 3836 search template specifies that the search is for private objects). 3837

If a search operation is active, and objects are created or destroyed which fit the search template for the 3838 active search operation, then those objects may or may not be found by the search operation. Note that 3839 this means that, under these circumstances, the search operation may return invalid object handles. 3840

Even though C_FindObjectsInit can return the values CKR_ATTRIBUTE_TYPE_INVALID and 3841 CKR_ATTRIBUTE_VALUE_INVALID, it is not required to. For example, if it is given a search template 3842 with nonexistent attributes in it, it can return CKR_ATTRIBUTE_TYPE_INVALID, or it can initialize a 3843 search operation which will match no objects and return CKR_OK. 3844

If the CKA_UNIQUE_ID attribute is present in the search template, either zero or one objects will be 3845 found, since at most one object can have any particular CKA_UNIQUE_ID value. 3846

Return values: CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_TYPE_INVALID, 3847 CKR_ATTRIBUTE_VALUE_INVALID, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, 3848 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, 3849 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_ACTIVE, 3850 CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 3851

Example: see C_FindObjectsFinal. 3852


5.7.8 C_FindObjects 3853

CK_DECLARE_FUNCTION(CK_RV, C_FindObjects)( 3854 CK_SESSION_HANDLE hSession, 3855 CK_OBJECT_HANDLE_PTR phObject, 3856 CK_ULONG ulMaxObjectCount, 3857 CK_ULONG_PTR pulObjectCount 3858 ); 3859

C_FindObjects continues a search for token and session objects that match a template, obtaining 3860 additional object handles. hSession is the session’s handle; phObject points to the location that receives 3861 the list (array) of additional object handles; ulMaxObjectCount is the maximum number of object handles 3862 to be returned; pulObjectCount points to the location that receives the actual number of object handles 3863

returned. 3864

If there are no more objects matching the template, then the location that pulObjectCount points to 3865

receives the value 0. 3866

The search MUST have been initialized with C_FindObjectsInit. 3867

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 3868 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 3869 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, 3870 CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 3871

Example: see C_FindObjectsFinal. 3872

5.7.9 C_FindObjectsFinal 3873

CK_DECLARE_FUNCTION(CK_RV, C_FindObjectsFinal)( 3874 CK_SESSION_HANDLE hSession 3875 ); 3876

C_FindObjectsFinal terminates a search for token and session objects. hSession is the session’s 3877

handle. 3878

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 3879 CKR_DEVICE_REMOVED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3880 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 3881 CKR_SESSION_HANDLE_INVALID. 3882

Example: 3883



CK_ULONG ulObjectCount; 3886

CK_RV rv; 3887

3888

. 3889

. 3890

rv = C_FindObjectsInit(hSession, NULL_PTR, 0); 3891


while (1) { 3893

rv = C_FindObjects(hSession, &hObject, 1, &ulObjectCount); 3894

if (rv != CKR_OK || ulObjectCount == 0) 3895

break; 3896

. 3897

. 3898


} 3899

3900

rv = C_FindObjectsFinal(hSession); 3901


5.8 Encryption functions 3903

Cryptoki provides the following functions for encrypting data: 3904

5.8.1 C_EncryptInit 3905

CK_DECLARE_FUNCTION(CK_RV, C_EncryptInit)( 3906 CK_SESSION_HANDLE hSession, 3907 CK_MECHANISM_PTR pMechanism, 3908 CK_OBJECT_HANDLE hKey 3909 ); 3910

C_EncryptInit initializes an encryption operation. hSession is the session’s handle; pMechanism points 3911 to the encryption mechanism; hKey is the handle of the encryption key. 3912

The CKA_ENCRYPT attribute of the encryption key, which indicates whether the key supports 3913

encryption, MUST be CK_TRUE. 3914

After calling C_EncryptInit, the application can either call C_Encrypt to encrypt data in a single part; or 3915 call C_EncryptUpdate zero or more times, followed by C_EncryptFinal, to encrypt data in multiple parts. 3916 The encryption operation is active until the application uses a call to C_Encrypt or C_EncryptFinal to 3917 actually obtain the final piece of ciphertext. To process additional data (in single or multiple parts), the 3918 application MUST call C_EncryptInit again. 3919

C_EncryptInit can be called with pMechanism set to NULL_PTR to terminate an active encryption 3920 operation. If an active operation operations cannot be cancelled, CKR_OPERATION_CANCEL_FAILED 3921 must be returned. 3922

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 3923 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 3924 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, 3925 CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, 3926 CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, 3927 CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, 3928 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 3929 CKR_OPERATION_CANCEL_FAILED. 3930

Example: see C_EncryptFinal. 3931

5.8.2 C_Encrypt 3932

CK_DECLARE_FUNCTION(CK_RV, C_Encrypt)( 3933 CK_SESSION_HANDLE hSession, 3934 CK_BYTE_PTR pData, 3935 CK_ULONG ulDataLen, 3936 CK_BYTE_PTR pEncryptedData, 3937 CK_ULONG_PTR pulEncryptedDataLen 3938 ); 3939

C_Encrypt encrypts single-part data. hSession is the session’s handle; pData points to the data; 3940 ulDataLen is the length in bytes of the data; pEncryptedData points to the location that receives the 3941 encrypted data; pulEncryptedDataLen points to the location that holds the length in bytes of the encrypted 3942

data. 3943

C_Encrypt uses the convention described in Section 5.2 on producing output. 3944


The encryption operation MUST have been initialized with C_EncryptInit. A call to C_Encrypt always 3945 terminates the active encryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a 3946 successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the 3947 ciphertext. 3948

C_Encrypt cannot be used to terminate a multi-part operation, and MUST be called after C_EncryptInit 3949 without intervening C_EncryptUpdate calls. 3950

For some encryption mechanisms, the input plaintext data has certain length constraints (either because 3951 the mechanism can only encrypt relatively short pieces of plaintext, or because the mechanism’s input 3952 data MUST consist of an integral number of blocks). If these constraints are not satisfied, then 3953 C_Encrypt will fail with return code CKR_DATA_LEN_RANGE. 3954

The plaintext and ciphertext can be in the same place, i.e., it is OK if pData and pEncryptedData point to 3955

the same location. 3956

For most mechanisms, C_Encrypt is equivalent to a sequence of C_EncryptUpdate operations followed 3957 by C_EncryptFinal. 3958

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 3959 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, 3960 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 3961 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 3962 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 3963 CKR_SESSION_HANDLE_INVALID. 3964

Example: see C_EncryptFinal for an example of similar functions. 3965

5.8.3 C_EncryptUpdate 3966

CK_DECLARE_FUNCTION(CK_RV, C_EncryptUpdate)( 3967 CK_SESSION_HANDLE hSession, 3968 CK_BYTE_PTR pPart, 3969 CK_ULONG ulPartLen, 3970 CK_BYTE_PTR pEncryptedPart, 3971 CK_ULONG_PTR pulEncryptedPartLen 3972 ); 3973

C_EncryptUpdate continues a multiple-part encryption operation, processing another data part. 3974 hSession is the session’s handle; pPart points to the data part; ulPartLen is the length of the data part; 3975 pEncryptedPart points to the location that receives the encrypted data part; pulEncryptedPartLen points 3976

to the location that holds the length in bytes of the encrypted data part. 3977

C_EncryptUpdate uses the convention described in Section 5.2 on producing output. 3978

The encryption operation MUST have been initialized with C_EncryptInit. This function may be called 3979 any number of times in succession. A call to C_EncryptUpdate which results in an error other than 3980 CKR_BUFFER_TOO_SMALL terminates the current encryption operation. 3981

The plaintext and ciphertext can be in the same place, i.e., it is OK if pPart and pEncryptedPart point to 3982 the same location. 3983

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 3984 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, 3985 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, 3986 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, 3987 CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 3988

Example: see C_EncryptFinal. 3989

5.8.4 C_EncryptFinal 3990

CK_DECLARE_FUNCTION(CK_RV, C_EncryptFinal)( 3991 CK_SESSION_HANDLE hSession, 3992 CK_BYTE_PTR pLastEncryptedPart, 3993


CK_ULONG_PTR pulLastEncryptedPartLen 3994 ); 3995

C_EncryptFinal finishes a multiple-part encryption operation. hSession is the session’s handle; 3996 pLastEncryptedPart points to the location that receives the last encrypted data part, if any; 3997 pulLastEncryptedPartLen points to the location that holds the length of the last encrypted data part. 3998

C_EncryptFinal uses the convention described in Section 5.2 on producing output. 3999

The encryption operation MUST have been initialized with C_EncryptInit. A call to C_EncryptFinal 4000 always terminates the active encryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a 4001 successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the 4002

ciphertext. 4003

For some multi-part encryption mechanisms, the input plaintext data has certain length constraints, 4004 because the mechanism’s input data MUST consist of an integral number of blocks. If these constraints 4005 are not satisfied, then C_EncryptFinal will fail with return code CKR_DATA_LEN_RANGE. 4006


Example: 4012

#define PLAINTEXT_BUF_SZ 200 4013

#define CIPHERTEXT_BUF_SZ 256 4014

4015

CK_ULONG firstPieceLen, secondPieceLen; 4016


CK_OBJECT_HANDLE hKey; 4018

CK_BYTE iv[8]; 4019

CK_MECHANISM mechanism = { 4020

CKM_DES_CBC_PAD, iv, sizeof(iv) 4021

}; 4022

CK_BYTE data[PLAINTEXT_BUF_SZ]; 4023

CK_BYTE encryptedData[CIPHERTEXT_BUF_SZ]; 4024

CK_ULONG ulEncryptedData1Len; 4025



CK_RV rv; 4028

4029

. 4030

. 4031

firstPieceLen = 90; 4032

secondPieceLen = PLAINTEXT_BUF_SZ-firstPieceLen; 4033


if (rv == CKR_OK) { 4035

/* Encrypt first piece */ 4036

ulEncryptedData1Len = sizeof(encryptedData); 4037

rv = C_EncryptUpdate( 4038

hSession, 4039


&data[0], firstPieceLen, 4040

&encryptedData[0], &ulEncryptedData1Len); 4041

if (rv != CKR_OK) { 4042

. 4043

. 4044

} 4045

4046

/* Encrypt second piece */ 4047

ulEncryptedData2Len = sizeof(encryptedData)-ulEncryptedData1Len; 4048


hSession, 4050

&data[firstPieceLen], secondPieceLen, 4051

&encryptedData[ulEncryptedData1Len], &ulEncryptedData2Len); 4052

if (rv != CKR_OK) { 4053

. 4054

. 4055

} 4056

4057

/* Get last little encrypted bit */ 4058

ulEncryptedData3Len = 4059

sizeof(encryptedData)-ulEncryptedData1Len-ulEncryptedData2Len; 4060

rv = C_EncryptFinal( 4061

hSession, 4062

&encryptedData[ulEncryptedData1Len+ulEncryptedData2Len], 4063

&ulEncryptedData3Len); 4064

if (rv != CKR_OK) { 4065

. 4066

. 4067

} 4068

} 4069

5.9 Message-based encryption functions 4070

Message-based encryption refers to the process of encrypting multiple messages using the same 4071 encryption mechanism and encryption key. The encryption mechanism can be either an authenticated 4072 encryption with associated data (AEAD) algorithm or a pure encryption algorithm. 4073

Cryptoki provides the following functions for message-based encryption: 4074

5.9.1 C_MessageEncryptInit 4075

CK_DECLARE_FUNCTION(CK_RV, C_MessageEncryptInit)( 4076 CK_SESSION_HANDLE hSession, 4077 CK_MECHANISM_PTR pMechanism, 4078 CK_OBJECT_HANDLE hKey 4079 ); 4080


C_MessageEncryptInit prepares a session for one or more encryption operations that use the same 4081 encryption mechanism and encryption key. hSession is the session’s handle; pMechanism points to the 4082 encryption mechanism; hKey is the handle of the encryption key. 4083

The CKA_ENCRYPT attribute of the encryption key, which indicates whether the key supports encryption, 4084 MUST be CK_TRUE. 4085

After calling C_MessageEncryptInit, the application can either call C_EncryptMessage to encrypt a 4086 message in a single part, or call C_EncryptMessageBegin, followed by C_EncryptMessageNext one or 4087 more times, to encrypt a message in multiple parts. This may be repeated several times. The message-4088 based encryption process is active until the application calls C_MessageEncryptFinal to finish the 4089

message-based encryption process. 4090

C_MessageEncryptInit can be called with pMechanism set to NULL_PTR to terminate a message-based 4091 encryption process. If a multi-part message encryption operation is active, it will also be terminated. If an 4092 active operation has been initialized and it cannot be cancelled, CKR_OPERATION_CANCEL_FAILED 4093 must be returned. 4094

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 4095 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 4096 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, 4097 CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, 4098 CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, 4099 CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, 4100 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 4101 CKR_OPERATION_CANCEL_FAILED. 4102

5.9.2 C_EncryptMessage 4103

CK_DECLARE_FUNCTION(CK_RV, C_EncryptMessage)( 4104 CK_SESSION_HANDLE hSession, 4105 CK_VOID_PTR pParameter, 4106 CK_ULONG ulParameterLen, 4107 CK_BYTE_PTR pAssociatedData, 4108 CK_ULONG ulAssociatedDataLen, 4109 CK_BYTE_PTR pPlaintext, 4110 CK_ULONG ulPlaintextLen, 4111 CK_BYTE_PTR pCiphertext, 4112 CK_ULONG_PTR pulCiphertextLen 4113 ); 4114

C_EncryptMessage encrypts a message in a single part. hSession is the session’s handle; pParameter 4115 and ulParameterLen specify any mechanism-specific parameters for the message encryption operation; 4116 pAssociatedData and ulAssociatedDataLen specify the associated data for an AEAD mechanism; 4117 pPlaintext points to the plaintext data; ulPlaintextLen is the length in bytes of the plaintext data; 4118 pCiphertext points to the location that receives the encrypted data; pulCiphertextLen points to the location 4119

that holds the length in bytes of the encrypted data. 4120

Typically, pParameter is an initialization vector (IV) or nonce. Depending on the mechanism parameter 4121 passed to C_MessageEncryptInit, pParameter may be either an input or an output parameter. For 4122 example, if the mechanism parameter specifies an IV generator mechanism, the IV generated by the IV 4123 generator will be output to the pParameter buffer. 4124

If the encryption mechanism is not AEAD, pAssociatedData and ulAssociatedDataLen are not used and 4125

should be set to (NULL, 0). 4126

C_EncryptMessage uses the convention described in Section 5.2 on producing output. 4127

The message-based encryption process MUST have been initialized with C_MessageEncryptInit. A call 4128 to C_EncryptMessage begins and terminates a message encryption operation. 4129

C_EncryptMessage cannot be called in the middle of a multi-part message encryption operation. 4130


For some encryption mechanisms, the input plaintext data has certain length constraints (either because 4131 the mechanism can only encrypt relatively short pieces of plaintext, or because the mechanism’s input 4132 data MUST consist of an integral number of blocks). If these constraints are not satisfied, then 4133 C_EncryptMessage will fail with return code CKR_DATA_LEN_RANGE. The plaintext and ciphertext can 4134 be in the same place, i.e., it is OK if pPlaintext and pCiphertext point to the same location. 4135

For most mechanisms, C_EncryptMessage is equivalent to C_EncryptMessageBegin followed by a 4136 sequence of C_EncryptMessageNext operations. 4137

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 4138 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, 4139 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4140 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4141 CKR_HOST_MEMORY, CKR_OK, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 4142

5.9.3 C_EncryptMessageBegin 4143

CK_DECLARE_FUNCTION(CK_RV, C_EncryptMessageBegin)( 4144 CK_SESSION_HANDLE hSession, 4145 CK_VOID_PTR pParameter, 4146 CK_ULONG ulParameterLen, 4147 CK_BYTE_PTR pAssociatedData, 4148 CK_ULONG ulAssociatedDataLen 4149

); 4150

C_EncryptMessageBegin begins a multiple-part message encryption operation. hSession is the 4151 session’s handle; pParameter and ulParameterLen specify any mechanism-specific parameters for the 4152 message encryption operation; pAssociatedData and ulAssociatedDataLen specify the associated data 4153

for an AEAD mechanism. 4154

Typically, pParameter is an initialization vector (IV) or nonce. Depending on the mechanism parameter 4155 passed to C_MessageEncryptInit, pParameter may be either an input or an output parameter. For 4156 example, if the mechanism parameter specifies an IV generator mechanism, the IV generated by the IV 4157 generator will be output to the pParameter buffer. 4158

If the mechanism is not AEAD, pAssociatedData and ulAssociatedDataLen are not used and should be 4159 set to (NULL, 0). 4160

After calling C_EncryptMessageBegin, the application should call C_EncryptMessageNext one or 4161 more times to encrypt the message in multiple parts. The message encryption operation is active until the 4162 application uses a call to C_EncryptMessageNext with flags=CKF_END_OF_MESSAGE to actually 4163 obtain the final piece of ciphertext. To process additional messages (in single or multiple parts), the 4164 application MUST call C_EncryptMessage or C_EncryptMessageBegin again. 4165

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 4166 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 4167 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_ACTIVE, 4168 CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 4169 CKR_USER_NOT_LOGGED_IN. 4170

5.9.4 C_EncryptMessageNext 4171

CK_DECLARE_FUNCTION(CK_RV, C_EncryptMessageNext)( 4172 CK_SESSION_HANDLE hSession, 4173 CK_VOID_PTR pParameter, 4174 CK_ULONG ulParameterLen, 4175 CK_BYTE_PTR pPlaintextPart, 4176 CK_ULONG ulPlaintextPartLen, 4177 CK_BYTE_PTR pCiphertextPart, 4178 CK_ULONG_PTR pulCiphertextPartLen, 4179 CK_FLAGS flags 4180


); 4181

C_EncryptMessageNext continues a multiple-part message encryption operation, processing another 4182 message part. hSession is the session’s handle; pParameter and ulParameterLen specify any 4183 mechanism-specific parameters for the message encryption operation; pPlaintextPart points to the 4184 plaintext message part; ulPlaintextPartLen is the length of the plaintext message part; pCiphertextPart 4185 points to the location that receives the encrypted message part; pulCiphertextPartLen points to the 4186 location that holds the length in bytes of the encrypted message part; flags is set to 0 if there is more 4187 plaintext data to follow, or set to CKF_END_OF_MESSAGE if this is the last plaintext part. 4188

Typically, pParameter is an initialization vector (IV) or nonce. Depending on the mechanism parameter 4189 passed to C_EncryptMessageNext, pParameter may be either an input or an output parameter. For 4190 example, if the mechanism parameter specifies an IV generator mechanism, the IV generated by the IV 4191 generator will be output to the pParameter buffer. 4192

C_EncryptMessageNext uses the convention described in Section 5.2 on producing output. 4193

The message encryption operation MUST have been started with C_EncryptMessageBegin. This 4194 function may be called any number of times in succession. A call to C_EncryptMessageNext with flags=0 4195 which results in an error other than CKR_BUFFER_TOO_SMALL terminates the current message 4196 encryption operation. A call to C_EncryptMessageNext with flags=CKF_END_OF_MESSAGE always 4197 terminates the active message encryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a 4198 successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the 4199

ciphertext. 4200

Although the last C_EncryptMessageNext call ends the encryption of a message, it does not finish the 4201 message-based encryption process. Additional C_EncryptMessage or C_EncryptMessageBegin and 4202 C_EncryptMessageNext calls may be made on the session. 4203

The plaintext and ciphertext can be in the same place, i.e., it is OK if pPlaintextPart and pCiphertextPart 4204 point to the same location. 4205

For some multi-part encryption mechanisms, the input plaintext data has certain length constraints, 4206 because the mechanism’s input data MUST consist of an integral number of blocks. If these constraints 4207 are not satisfied when the final message part is supplied (i.e., with flags=CKF_END_OF_MESSAGE), 4208 then C_EncryptMessageNext will fail with return code CKR_DATA_LEN_RANGE. 4209


5.9.5 C_ MessageEncryptFinal 4215

CK_DECLARE_FUNCTION(CK_RV, C_EncryptMessageNext)( 4216 CK_SESSION_HANDLE hSession 4217 ); 4218

C_MessageEncryptFinal finishes a message-based encryption process. hSession is the session’s 4219

handle. 4220

The message-based encryption process MUST have been initialized with C_MessageEncryptInit. 4221

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 4222 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4223 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4224

CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 4225 CKR_SESSION_HANDLE_INVALID. 4226

Example: 4227


#define AUTH_BUF_SZ 100 4229



4231



CK_BYTE iv[] = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 }; 4234

CK_BYTE tag[16]; 4235

CK_GCM_MESSAGE_PARAMS gcmParams = { 4236

iv, 4237

sizeof(iv) * 8, 4238

0, 4239

CKG_NO_GENERATE, 4240

tag, 4241

sizeof(tag) * 8 4242

}; 4243


CKM_AES_GCM, &gcmParams, sizeof(gcmParams) 4245

}; 4246

CK_BYTE data[2][PLAINTEXT_BUF_SZ]; 4247

CK_BYTE auth[2][AUTH_BUF_SZ]; 4248

CK_BYTE encryptedData[2][CIPHERTEXT_BUF_SZ]; 4249

CK_ULONG ulEncryptedDataLen, ulFirstEncryptedDataLen; 4250

CK_ULONG firstPieceLen = PLAINTEXT_BUF_SZ / 2; 4251

4252

/* error handling is omitted for better readability */ 4253

. 4254

. 4255

C_MessageEncryptInit(hSession, &mechanism, hKey); 4256

/* encrypt message en bloc with given IV */ 4257

ulEncryptedDataLen = sizeof(encryptedData[0]); 4258

C_EncryptMessage(hSession, 4259

&gcmParams, sizeof(gcmParams), 4260

&auth[0][0], sizeof(auth[0]), 4261

&data[0][0], sizeof(data[0]), 4262

&encryptedData[0][0], &ulEncryptedDataLen); 4263

/* iv and tag are set now for message */ 4264

4265

/* encrypt message in two steps with generated IV */ 4266

gcmParams.ivGenerator = CKG_GENERATE; 4267

C_EncryptMessageBegin(hSession, 4268


&auth[1][0], sizeof(auth[1]) 4270

); 4271

/* encrypt first piece */ 4272


ulFirstEncryptedDataLen = sizeof(encryptedData[1]); 4273

C_EncryptMessageNext(hSession, 4274


&data[1][0], firstPieceLen, 4276

&encryptedData[1][0], &ulFirstEncryptedDataLen, 4277

0 4278

); 4279

/* encrypt second piece */ 4280

ulEncryptedDataLen = sizeof(encryptedData[1]) - ulFirstEncryptedDataLen; 4281

C_EncryptMessageNext(hSession, 4282


&data[1][firstPieceLen], sizeof(data[1])-firstPieceLen, 4284

&encryptedData[1][ulFirstEncryptedDataLen], &ulEncryptedDataLen, 4285

CKF_END_OF_MESSAGE 4286

); 4287

/* tag is set now for message */ 4288

4289

/* finalize */ 4290

C_MessageEncryptFinal(hSession); 4291

5.10 Decryption functions 4292

Cryptoki provides the following functions for decrypting data: 4293

5.10.1 C_DecryptInit 4294

CK_DECLARE_FUNCTION(CK_RV, C_DecryptInit)( 4295 CK_SESSION_HANDLE hSession, 4296 CK_MECHANISM_PTR pMechanism, 4297 CK_OBJECT_HANDLE hKey 4298 ); 4299

C_DecryptInit initializes a decryption operation. hSession is the session’s handle; pMechanism points to 4300 the decryption mechanism; hKey is the handle of the decryption key. 4301

The CKA_DECRYPT attribute of the decryption key, which indicates whether the key supports 4302 decryption, MUST be CK_TRUE. 4303

After calling C_DecryptInit, the application can either call C_Decrypt to decrypt data in a single part; or 4304 call C_DecryptUpdate zero or more times, followed by C_DecryptFinal, to decrypt data in multiple parts. 4305 The decryption operation is active until the application uses a call to C_Decrypt or C_DecryptFinal to 4306 actually obtain the final piece of plaintext. To process additional data (in single or multiple parts), the 4307 application MUST call C_DecryptInit again. 4308

C_DecryptInit can be called with pMechanism set to NULL_PTR to terminate an active decryption 4309 operation. If an active operation cannot be cancelled, CKR_OPERATION_CANCEL_FAILED must be 4310 returned. 4311

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 4312 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4313 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4314 CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, 4315 CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, 4316 CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, 4317


CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 4318 CKR_OPERATION_CANCEL_FAILED. 4319

Example: see C_DecryptFinal. 4320

5.10.2 C_Decrypt 4321

CK_DECLARE_FUNCTION(CK_RV, C_Decrypt)( 4322 CK_SESSION_HANDLE hSession, 4323 CK_BYTE_PTR pEncryptedData, 4324 CK_ULONG ulEncryptedDataLen, 4325 CK_BYTE_PTR pData, 4326 CK_ULONG_PTR pulDataLen 4327 ); 4328

C_Decrypt decrypts encrypted data in a single part. hSession is the session’s handle; pEncryptedData 4329 points to the encrypted data; ulEncryptedDataLen is the length of the encrypted data; pData points to the 4330 location that receives the recovered data; pulDataLen points to the location that holds the length of the 4331

recovered data. 4332

C_Decrypt uses the convention described in Section 5.2 on producing output. 4333

The decryption operation MUST have been initialized with C_DecryptInit. A call to C_Decrypt always 4334 terminates the active decryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a 4335 successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the 4336

plaintext. 4337

C_Decrypt cannot be used to terminate a multi-part operation, and MUST be called after C_DecryptInit 4338 without intervening C_DecryptUpdate calls. 4339

The ciphertext and plaintext can be in the same place, i.e., it is OK if pEncryptedData and pData point to 4340


If the input ciphertext data cannot be decrypted because it has an inappropriate length, then either 4342 CKR_ENCRYPTED_DATA_INVALID or CKR_ENCRYPTED_DATA_LEN_RANGE may be returned. 4343

For most mechanisms, C_Decrypt is equivalent to a sequence of C_DecryptUpdate operations followed 4344 by C_DecryptFinal. 4345

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 4346 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 4347 CKR_DEVICE_REMOVED, CKR_ENCRYPTED_DATA_INVALID, 4348 CKR_ENCRYPTED_DATA_LEN_RANGE, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 4349 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 4350 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN. 4351

Example: see C_DecryptFinal for an example of similar functions. 4352

5.10.3 C_DecryptUpdate 4353

CK_DECLARE_FUNCTION(CK_RV, C_DecryptUpdate)( 4354 CK_SESSION_HANDLE hSession, 4355 CK_BYTE_PTR pEncryptedPart, 4356 CK_ULONG ulEncryptedPartLen, 4357 CK_BYTE_PTR pPart, 4358 CK_ULONG_PTR pulPartLen 4359 ); 4360

C_DecryptUpdate continues a multiple-part decryption operation, processing another encrypted data 4361 part. hSession is the session’s handle; pEncryptedPart points to the encrypted data part; 4362 ulEncryptedPartLen is the length of the encrypted data part; pPart points to the location that receives the 4363 recovered data part; pulPartLen points to the location that holds the length of the recovered data part. 4364

C_DecryptUpdate uses the convention described in Section 5.2 on producing output. 4365


The decryption operation MUST have been initialized with C_DecryptInit. This function may be called 4366 any number of times in succession. A call to C_DecryptUpdate which results in an error other than 4367

CKR_BUFFER_TOO_SMALL terminates the current decryption operation. 4368

The ciphertext and plaintext can be in the same place, i.e., it is OK if pEncryptedPart and pPart point to 4369



Example: See C_DecryptFinal. 4377

5.10.4 C_DecryptFinal 4378

CK_DECLARE_FUNCTION(CK_RV, C_DecryptFinal)( 4379 CK_SESSION_HANDLE hSession, 4380 CK_BYTE_PTR pLastPart, 4381 CK_ULONG_PTR pulLastPartLen 4382 ); 4383

C_DecryptFinal finishes a multiple-part decryption operation. hSession is the session’s handle; 4384 pLastPart points to the location that receives the last recovered data part, if any; pulLastPartLen points to 4385 the location that holds the length of the last recovered data part. 4386

C_DecryptFinal uses the convention described in Section 5.2 on producing output. 4387

The decryption operation MUST have been initialized with C_DecryptInit. A call to C_DecryptFinal 4388 always terminates the active decryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a 4389 successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the 4390

plaintext. 4391



Example: 4400



4403

CK_ULONG firstEncryptedPieceLen, secondEncryptedPieceLen; 4404



CK_BYTE iv[8]; 4407


CKM_DES_CBC_PAD, iv, sizeof(iv) 4409

}; 4410

CK_BYTE data[PLAINTEXT_BUF_SZ]; 4411

CK_BYTE encryptedData[CIPHERTEXT_BUF_SZ]; 4412


CK_ULONG ulData1Len, ulData2Len, ulData3Len; 4413

CK_RV rv; 4414

4415

. 4416

. 4417

firstEncryptedPieceLen = 90; 4418

secondEncryptedPieceLen = CIPHERTEXT_BUF_SZ-firstEncryptedPieceLen; 4419

rv = C_DecryptInit(hSession, &mechanism, hKey); 4420

if (rv == CKR_OK) { 4421

/* Decrypt first piece */ 4422

ulData1Len = sizeof(data); 4423

rv = C_DecryptUpdate( 4424

hSession, 4425

&encryptedData[0], firstEncryptedPieceLen, 4426

&data[0], &ulData1Len); 4427

if (rv != CKR_OK) { 4428

. 4429

. 4430

} 4431

4432

/* Decrypt second piece */ 4433

ulData2Len = sizeof(data)-ulData1Len; 4434


hSession, 4436

&encryptedData[firstEncryptedPieceLen], 4437

secondEncryptedPieceLen, 4438

&data[ulData1Len], &ulData2Len); 4439

if (rv != CKR_OK) { 4440

. 4441

. 4442

} 4443

4444

/* Get last little decrypted bit */ 4445

ulData3Len = sizeof(data)-ulData1Len-ulData2Len; 4446

rv = C_DecryptFinal( 4447

hSession, 4448

&data[ulData1Len+ulData2Len], &ulData3Len); 4449

if (rv != CKR_OK) { 4450

. 4451

. 4452

} 4453

} 4454


5.11 Message-based decryption functions 4455

Message-based decryption refers to the process of decrypting multiple encrypted messages using the 4456 same decryption mechanism and decryption key. The decryption mechanism can be either an 4457 authenticated encryption with associated data (AEAD) algorithm or a pure encryption algorithm. 4458

Cryptoki provides the following functions for message-based decryption. 4459

5.11.1 C_MessageDecryptInit 4460

CK_DECLARE_FUNCTION(CK_RV, C_MessageDecryptInit)( 4461 CK_SESSION_HANDLE hSession, 4462 CK_MECHANISM_PTR pMechanism, 4463 CK_OBJECT_HANDLE hKey 4464 ); 4465

C_MessageDecryptInit initializes a message-based decryption process, preparing a session for one or 4466 more decryption operations that use the same decryption mechanism and decryption key. hSession is 4467 the session’s handle; pMechanism points to the decryption mechanism; hKey is the handle of the 4468

decryption key. 4469

The CKA_DECRYPT attribute of the decryption key, which indicates whether the key supports decryption, 4470 MUST be CK_TRUE. 4471

After calling C_MessageDecryptInit, the application can either call C_DecryptMessage to decrypt an 4472 encrypted message in a single part; or call C_DecryptMessageBegin, followed by 4473 C_DecryptMessageNext one or more times, to decrypt an encrypted message in multiple parts. This 4474 may be repeated several times. The message-based decryption process is active until the application 4475 uses a call to C_MessageDecryptFinal to finish the message-based decryption process. 4476

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 4477 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4478 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4479 CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, 4480 CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, 4481 CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, 4482 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 4483 CKR_OPERATION_CANCEL_FAILED. 4484

5.11.2 C_DecryptMessage 4485

CK_DECLARE_FUNCTION(CK_RV, C_DecryptMessage)( 4486 CK_SESSION_HANDLE hSession, 4487 CK_VOID_PTR pParameter, 4488 CK_ULONG ulParameterLen, 4489 CK_BYTE_PTR pAssociatedData, 4490 CK_ULONG ulAssociatedDataLen, 4491 CK_BYTE_PTR pCiphertext, 4492 CK_ULONG ulCiphertextLen, 4493 CK_BYTE_PTR pPlaintext, 4494 CK_ULONG_PTR pulPlaintextLen 4495 ); 4496

C_DecryptMessage decrypts an encrypted message in a single part. hSession is the session’s handle; 4497 pParameter and ulParameterLen specify any mechanism-specific parameters for the message decryption 4498 operation; pAssociatedData and ulAssociatedDataLen specify the associated data for an AEAD 4499 mechanism; pCiphertext points to the encrypted message; ulCiphertextLen is the length of the encrypted 4500 message; pPlaintext points to the location that receives the recovered message; pulPlaintextLen points to 4501

the location that holds the length of the recovered message. 4502


Typically, pParameter is an initialization vector (IV) or nonce. Unlike the pParameter parameter of 4503 C_EncryptMessage, pParameter is always an input parameter. 4504

If the decryption mechanism is not AEAD, pAssociatedData and ulAssociatedDataLen are not used and 4505


C_DecryptMessage uses the convention described in Section 5.2 on producing output. 4507

The message-based decryption process MUST have been initialized with C_MessageDecryptInit. A call 4508 to C_DecryptMessage begins and terminates a message decryption operation. 4509

C_DecryptMessage cannot be called in the middle of a multi-part message decryption operation. 4510

The ciphertext and plaintext can be in the same place, i.e., it is OK if pCiphertext and pPlaintext point to 4511



If the decryption mechanism is an AEAD algorithm and the authenticity of the associated data or 4515 ciphertext cannot be verified, then CKR_AEAD_DECRYPT_FAILED is returned. 4516

For most mechanisms, C_DecryptMessage is equivalent to C_DecryptMessageBegin followed by a 4517 sequence of C_DecryptMessageNext operations. 4518

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 4519 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 4520 CKR_DEVICE_REMOVED, CKR_ENCRYPTED_DATA_INVALID, 4521 CKR_ENCRYPTED_DATA_LEN_RANGE, CKR_AEAD_DECRYPT_FAILED, 4522 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4523 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 4524 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 4525 CKR_OPERATION_CANCEL_FAILED. 4526

5.11.3 C_DecryptMessageBegin 4527

CK_DECLARE_FUNCTION(CK_RV, C_DecryptMessageBegin)( 4528 CK_SESSION_HANDLE hSession, 4529 CK_VOID_PTR pParameter, 4530 CK_ULONG ulParameterLen, 4531 CK_BYTE_PTR pAssociatedData, 4532 CK_ULONG ulAssociatedDataLen 4533 ); 4534

C_DecryptMessageBegin begins a multiple-part message decryption operation. hSession is the 4535 session’s handle; pParameter and ulParameterLen specify any mechanism-specific parameters for the 4536 message decryption operation; pAssociatedData and ulAssociatedDataLen specify the associated data 4537

for an AEAD mechanism. 4538

Typically, pParameter is an initialization vector (IV) or nonce. Unlike the pParameter parameter of 4539 C_EncryptMessageBegin, pParameter is always an input parameter. 4540

If the decryption mechanism is not AEAD, pAssociatedData and ulAssociatedDataLen are not used and 4541


After calling C_DecryptMessageBegin, the application should call C_DecryptMessageNext one or 4543 more times to decrypt the encrypted message in multiple parts. The message decryption operation is 4544 active until the application uses a call to C_DecryptMessageNext with flags=CKF_END_OF_MESSAGE 4545 to actually obtain the final piece of plaintext. To process additional encrypted messages (in single or 4546 multiple parts), the application MUST call C_DecryptMessage or C_DecryptMessageBegin again. 4547

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 4548 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4549 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4550 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, 4551 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN. 4552


5.11.4 C_DecryptMessageNext 4553

CK_DECLARE_FUNCTION(CK_RV, C_DecryptMessageNext)( 4554 CK_SESSION_HANDLE hSession, 4555 CK_VOID_PTR pParameter, 4556 CK_ULONG ulParameterLen, 4557 CK_BYTE_PTR pCiphertextPart, 4558 CK_ULONG ulCiphertextPartLen, 4559 CK_BYTE_PTR pPlaintextPart, 4560 CK_ULONG_PTR pulPlaintextPartLen, 4561 CK_FLAGS flags 4562 ); 4563

C_DecryptMessageNext continues a multiple-part message decryption operation, processing another 4564 encrypted message part. hSession is the session’s handle; pParameter and ulParameterLen specify any 4565 mechanism-specific parameters for the message decryption operation; pCiphertextPart points to the 4566 encrypted message part; ulCiphertextPartLen is the length of the encrypted message part; pPlaintextPart 4567 points to the location that receives the recovered message part; pulPlaintextPartLen points to the location 4568 that holds the length of the recovered message part; flags is set to 0 if there is more ciphertext data to 4569 follow, or set to CKF_END_OF_MESSAGE if this is the last ciphertext part. 4570

Typically, pParameter is an initialization vector (IV) or nonce. Unlike the pParameter parameter of 4571 C_EncryptMessageNext, pParameter is always an input parameter. 4572

C_DecryptMessageNext uses the convention described in Section 5.2 on producing output. 4573

The message decryption operation MUST have been started with C_DecryptMessageBegin. This 4574 function may be called any number of times in succession. A call to C_DecryptMessageNext with 4575 flags=0 which results in an error other than CKR_BUFFER_TOO_SMALL terminates the current message 4576 decryption operation. A call to C_DecryptMessageNext with flags=CKF_END_OF_MESSAGE always 4577 terminates the active message decryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a 4578 successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the 4579 plaintext. 4580

The ciphertext and plaintext can be in the same place, i.e., it is OK if pCiphertextPart and pPlaintextPart 4581

point to the same location. 4582

Although the last C_DecryptMessageNext call ends the decryption of a message, it does not finish the 4583 message-based decryption process. Additional C_DecryptMessage or C_DecryptMessageBegin and 4584 C_DecryptMessageNext calls may be made on the session. 4585

If the input ciphertext data cannot be decrypted because it has an inappropriate length, then either 4586 CKR_ENCRYPTED_DATA_INVALID or CKR_ENCRYPTED_DATA_LEN_RANGE may be returned by 4587 the last C_DecryptMessageNext call. 4588

If the decryption mechanism is an AEAD algorithm and the authenticity of the associated data or 4589 ciphertext cannot be verified, then CKR_AEAD_DECRYPT_FAILED is returned by the last 4590 C_DecryptMessageNext call. 4591

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 4592 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 4593 CKR_DEVICE_REMOVED, CKR_ENCRYPTED_DATA_INVALID, 4594 CKR_ENCRYPTED_DATA_LEN_RANGE, CKR_AEAD_DECRYPT_FAILED, 4595 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4596 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 4597 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN. 4598

5.11.5 C_MessageDecryptFinal 4599

CK_DECLARE_FUNCTION(CK_RV, C_MessageDecryptFinal)( 4600 CK_SESSION_HANDLE hSession 4601 ); 4602


C_MessageDecryptFinal finishes a message-based decryption process. hSession is the session’s 4603

handle. 4604

The message-based decryption process MUST have been initialized with C_MessageDecryptInit. 4605

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 4606 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4607 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4608 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 4609 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN. 4610

5.12 Message digesting functions 4611

Cryptoki provides the following functions for digesting data: 4612

5.12.1 C_DigestInit 4613

CK_DECLARE_FUNCTION(CK_RV, C_DigestInit)( 4614 CK_SESSION_HANDLE hSession, 4615 CK_MECHANISM_PTR pMechanism 4616 ); 4617

C_DigestInit initializes a message-digesting operation. hSession is the session’s handle; pMechanism 4618

points to the digesting mechanism. 4619

After calling C_DigestInit, the application can either call C_Digest to digest data in a single part; or call 4620 C_DigestUpdate zero or more times, followed by C_DigestFinal, to digest data in multiple parts. The 4621 message-digesting operation is active until the application uses a call to C_Digest or C_DigestFinal to 4622 actually obtain the message digest. To process additional data (in single or multiple parts), the 4623 application MUST call C_DigestInit again. 4624

C_DigestInit can be called with pMechanism set to NULL_PTR to terminate an active message-digesting 4625 operation. If an operation has been initialized and it cannot be cancelled, 4626 CKR_OPERATION_CANCEL_FAILED must be returned. 4627

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 4628 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4629 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4630 CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, 4631 CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, 4632 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 4633 CKR_OPERATION_CANCEL_FAILED. 4634

Example: see C_DigestFinal. 4635

5.12.2 C_Digest 4636

CK_DECLARE_FUNCTION(CK_RV, C_Digest)( 4637 CK_SESSION_HANDLE hSession, 4638 CK_BYTE_PTR pData, 4639 CK_ULONG ulDataLen, 4640 CK_BYTE_PTR pDigest, 4641 CK_ULONG_PTR pulDigestLen 4642 ); 4643

C_Digest digests data in a single part. hSession is the session’s handle, pData points to the data; 4644 ulDataLen is the length of the data; pDigest points to the location that receives the message digest; 4645 pulDigestLen points to the location that holds the length of the message digest. 4646

C_Digest uses the convention described in Section 5.2 on producing output. 4647

The digest operation MUST have been initialized with C_DigestInit. A call to C_Digest always 4648 terminates the active digest operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful 4649


call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the message 4650

digest. 4651

C_Digest cannot be used to terminate a multi-part operation, and MUST be called after C_DigestInit 4652 without intervening C_DigestUpdate calls. 4653

The input data and digest output can be in the same place, i.e., it is OK if pData and pDigest point to the 4654

same location. 4655

C_Digest is equivalent to a sequence of C_DigestUpdate operations followed by C_DigestFinal. 4656

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 4657 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 4658 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 4659 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 4660 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 4661

Example: see C_DigestFinal for an example of similar functions. 4662

5.12.3 C_DigestUpdate 4663

CK_DECLARE_FUNCTION(CK_RV, C_DigestUpdate)( 4664 CK_SESSION_HANDLE hSession, 4665 CK_BYTE_PTR pPart, 4666 CK_ULONG ulPartLen 4667 ); 4668

C_DigestUpdate continues a multiple-part message-digesting operation, processing another data part. 4669 hSession is the session’s handle, pPart points to the data part; ulPartLen is the length of the data part. 4670

The message-digesting operation MUST have been initialized with C_DigestInit. Calls to this function 4671 and C_DigestKey may be interspersed any number of times in any order. A call to C_DigestUpdate 4672

which results in an error terminates the current digest operation. 4673

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 4674 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4675 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4676 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 4677 CKR_SESSION_HANDLE_INVALID. 4678


5.12.4 C_DigestKey 4680

CK_DECLARE_FUNCTION(CK_RV, C_DigestKey)( 4681 CK_SESSION_HANDLE hSession, 4682 CK_OBJECT_HANDLE hKey 4683 ); 4684

C_DigestKey continues a multiple-part message-digesting operation by digesting the value of a secret 4685 key. hSession is the session’s handle; hKey is the handle of the secret key to be digested. 4686

The message-digesting operation MUST have been initialized with C_DigestInit. Calls to this function 4687 and C_DigestUpdate may be interspersed any number of times in any order. 4688

If the value of the supplied key cannot be digested purely for some reason related to its length, 4689 C_DigestKey should return the error code CKR_KEY_SIZE_RANGE. 4690

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 4691 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 4692 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_HANDLE_INVALID, 4693 CKR_KEY_INDIGESTIBLE, CKR_KEY_SIZE_RANGE, CKR_OK, 4694 CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 4695



5.12.5 C_DigestFinal 4697

CK_DECLARE_FUNCTION(CK_RV, C_DigestFinal)( 4698 CK_SESSION_HANDLE hSession, 4699 CK_BYTE_PTR pDigest, 4700 CK_ULONG_PTR pulDigestLen 4701 ); 4702

C_DigestFinal finishes a multiple-part message-digesting operation, returning the message digest. 4703 hSession is the session’s handle; pDigest points to the location that receives the message digest; 4704 pulDigestLen points to the location that holds the length of the message digest. 4705

C_DigestFinal uses the convention described in Section 5.2 on producing output. 4706

The digest operation MUST have been initialized with C_DigestInit. A call to C_DigestFinal always 4707 terminates the active digest operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful 4708 call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the message 4709 digest. 4710

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 4711 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 4712 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 4713 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 4714 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 4715

Example: 4716




CKM_MD5, NULL_PTR, 0 4720

}; 4721

CK_BYTE data[] = {...}; 4722

CK_BYTE digest[16]; 4723


CK_RV rv; 4725

4726

. 4727

. 4728

rv = C_DigestInit(hSession, &mechanism); 4729

if (rv != CKR_OK) { 4730

. 4731

. 4732

} 4733

4734

rv = C_DigestUpdate(hSession, data, sizeof(data)); 4735

if (rv != CKR_OK) { 4736

. 4737

. 4738

} 4739

4740

rv = C_DigestKey(hSession, hKey); 4741



if (rv != CKR_OK) { 4742

. 4743

. 4744

} 4745

4746

ulDigestLen = sizeof(digest); 4747

rv = C_DigestFinal(hSession, digest, &ulDigestLen); 4748

. 4749

. 4750

5.13 Signing and MACing functions 4751

Cryptoki provides the following functions for signing data (for the purposes of Cryptoki, these operations 4752 also encompass message authentication codes). 4753

5.13.1 C_SignInit 4754

CK_DECLARE_FUNCTION(CK_RV, C_SignInit)( 4755 CK_SESSION_HANDLE hSession, 4756 CK_MECHANISM_PTR pMechanism, 4757 CK_OBJECT_HANDLE hKey 4758 ); 4759

C_SignInit initializes a signature operation, where the signature is an appendix to the data. hSession is 4760 the session’s handle; pMechanism points to the signature mechanism; hKey is the handle of the signature 4761

key. 4762

The CKA_SIGN attribute of the signature key, which indicates whether the key supports signatures with 4763

appendix, MUST be CK_TRUE. 4764

After calling C_SignInit, the application can either call C_Sign to sign in a single part; or call 4765 C_SignUpdate one or more times, followed by C_SignFinal, to sign data in multiple parts. The signature 4766 operation is active until the application uses a call to C_Sign or C_SignFinal to actually obtain the 4767 signature. To process additional data (in single or multiple parts), the application MUST call C_SignInit 4768

again. 4769

C_SignInit can be called with pMechanism set to NULL_PTR to terminate an active signature operation. 4770 If an operation has been initialized and it cannot be cancelled, CKR_OPERATION_CANCEL_FAILED 4771 must be returned. 4772

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 4773 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4774 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4775 CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED,CKR_KEY_HANDLE_INVALID, 4776 CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, 4777 CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, 4778 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 4779 CKR_OPERATION_CANCEL_FAILED. 4780

Example: see C_SignFinal. 4781

5.13.2 C_Sign 4782

CK_DECLARE_FUNCTION(CK_RV, C_Sign)( 4783 CK_SESSION_HANDLE hSession, 4784 CK_BYTE_PTR pData, 4785 CK_ULONG ulDataLen, 4786 CK_BYTE_PTR pSignature, 4787



CK_ULONG_PTR pulSignatureLen 4788 ); 4789

C_Sign signs data in a single part, where the signature is an appendix to the data. hSession is the 4790 session’s handle; pData points to the data; ulDataLen is the length of the data; pSignature points to the 4791 location that receives the signature; pulSignatureLen points to the location that holds the length of the 4792

signature. 4793

C_Sign uses the convention described in Section 5.2 on producing output. 4794

The signing operation MUST have been initialized with C_SignInit. A call to C_Sign always terminates 4795 the active signing operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., 4796

one which returns CKR_OK) to determine the length of the buffer needed to hold the signature. 4797

C_Sign cannot be used to terminate a multi-part operation, and MUST be called after C_SignInit without 4798 intervening C_SignUpdate calls. 4799

For most mechanisms, C_Sign is equivalent to a sequence of C_SignUpdate operations followed by 4800 C_SignFinal. 4801

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 4802 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, 4803 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4804 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4805 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 4806 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, CKR_FUNCTION_REJECTED, 4807 CKR_TOKEN_RESOURCE_EXCEEDED. 4808

Example: see C_SignFinal for an example of similar functions. 4809

5.13.3 C_SignUpdate 4810

CK_DECLARE_FUNCTION(CK_RV, C_SignUpdate)( 4811 CK_SESSION_HANDLE hSession, 4812 CK_BYTE_PTR pPart, 4813 CK_ULONG ulPartLen 4814 ); 4815

C_SignUpdate continues a multiple-part signature operation, processing another data part. hSession is 4816 the session’s handle, pPart points to the data part; ulPartLen is the length of the data part. 4817

The signature operation MUST have been initialized with C_SignInit. This function may be called any 4818 number of times in succession. A call to C_SignUpdate which results in an error terminates the current 4819

signature operation. 4820

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 4821 CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 4822 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 4823 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 4824 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 4825 CKR_TOKEN_RESOURCE_EXCEEDED. 4826

Example: see C_SignFinal. 4827

5.13.4 C_SignFinal 4828

CK_DECLARE_FUNCTION(CK_RV, C_SignFinal)( 4829 CK_SESSION_HANDLE hSession, 4830 CK_BYTE_PTR pSignature, 4831 CK_ULONG_PTR pulSignatureLen 4832 ); 4833


C_SignFinal finishes a multiple-part signature operation, returning the signature. hSession is the 4834 session’s handle; pSignature points to the location that receives the signature; pulSignatureLen points to 4835

the location that holds the length of the signature. 4836

C_SignFinal uses the convention described in Section 5.2 on producing output. 4837

The signing operation MUST have been initialized with C_SignInit. A call to C_SignFinal always 4838 terminates the active signing operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful 4839 call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the signature. 4840

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 4841 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, 4842 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, 4843 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, 4844 CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 4845 CKR_USER_NOT_LOGGED_IN, CKR_FUNCTION_REJECTED, 4846 CKR_TOKEN_RESOURCE_EXCEEDED. 4847

Example: 4848




CKM_DES_MAC, NULL_PTR, 0 4852

}; 4853

CK_BYTE data[] = {...}; 4854

CK_BYTE mac[4]; 4855

CK_ULONG ulMacLen; 4856

CK_RV rv; 4857

4858

. 4859

. 4860

rv = C_SignInit(hSession, &mechanism, hKey); 4861

if (rv == CKR_OK) { 4862

rv = C_SignUpdate(hSession, data, sizeof(data)); 4863

. 4864

. 4865

ulMacLen = sizeof(mac); 4866

rv = C_SignFinal(hSession, mac, &ulMacLen); 4867

. 4868

. 4869

} 4870

5.13.5 C_SignRecoverInit 4871

CK_DECLARE_FUNCTION(CK_RV, C_SignRecoverInit)( 4872 CK_SESSION_HANDLE hSession, 4873 CK_MECHANISM_PTR pMechanism, 4874 CK_OBJECT_HANDLE hKey 4875 ); 4876



C_SignRecoverInit initializes a signature operation, where the data can be recovered from the signature. 4877 hSession is the session’s handle; pMechanism points to the structure that specifies the signature 4878 mechanism; hKey is the handle of the signature key. 4879

The CKA_SIGN_RECOVER attribute of the signature key, which indicates whether the key supports 4880

signatures where the data can be recovered from the signature, MUST be CK_TRUE. 4881

After calling C_SignRecoverInit, the application may call C_SignRecover to sign in a single part. The 4882 signature operation is active until the application uses a call to C_SignRecover to actually obtain the 4883 signature. To process additional data in a single part, the application MUST call C_SignRecoverInit 4884

again. 4885

C_SignRecoverInit can be called with pMechanism set to NULL_PTR to terminate an active signature 4886 with data recovery operation. If an active operation has been initialized and it cannot be cancelled, 4887 CKR_OPERATION_CANCEL_FAILED must be returned. 4888


Example: see C_SignRecover. 4897

5.13.6 C_SignRecover 4898

CK_DECLARE_FUNCTION(CK_RV, C_SignRecover)( 4899 CK_SESSION_HANDLE hSession, 4900 CK_BYTE_PTR pData, 4901 CK_ULONG ulDataLen, 4902 CK_BYTE_PTR pSignature, 4903 CK_ULONG_PTR pulSignatureLen 4904 ); 4905

C_SignRecover signs data in a single operation, where the data can be recovered from the signature. 4906 hSession is the session’s handle; pData points to the data; uLDataLen is the length of the data; 4907 pSignature points to the location that receives the signature; pulSignatureLen points to the location that 4908

holds the length of the signature. 4909

C_SignRecover uses the convention described in Section 5.2 on producing output. 4910

The signing operation MUST have been initialized with C_SignRecoverInit. A call to C_SignRecover 4911 always terminates the active signing operation unless it returns CKR_BUFFER_TOO_SMALL or is a 4912 successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the 4913

signature. 4914

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 4915 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, 4916 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4917 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4918 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 4919 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 4920 CKR_TOKEN_RESOURCE_EXCEEDED. 4921

Example: 4922




CKM_RSA_9796, NULL_PTR, 0 4926


}; 4927

CK_BYTE data[] = {...}; 4928

CK_BYTE signature[128]; 4929

CK_ULONG ulSignatureLen; 4930

CK_RV rv; 4931

4932

. 4933

. 4934

rv = C_SignRecoverInit(hSession, &mechanism, hKey); 4935

if (rv == CKR_OK) { 4936

ulSignatureLen = sizeof(signature); 4937

rv = C_SignRecover( 4938

hSession, data, sizeof(data), signature, &ulSignatureLen); 4939

if (rv == CKR_OK) { 4940

. 4941

. 4942

} 4943

} 4944

4945

5.14 Message-based signing and MACing functions 4946

Message-based signature refers to the process of signing multiple messages using the same signature 4947 mechanism and signature key. 4948

Cryptoki provides the following functions for for signing messages (for the purposes of Cryptoki, these 4949 operations also encompass message authentication codes). 4950

5.14.1 C_MessageSignInit 4951

CK_DECLARE_FUNCTION(CK_RV, C_MessageSignInit)( 4952

CK_SESSION_HANDLE hSession, 4953

CK_MECHANISM_PTR pMechanism, 4954

CK_OBJECT_HANDLE hKey 4955

); 4956

C_MessageSignInit initializes a message-based signature process, preparing a session for one or more 4957 signature operations (where the signature is an appendix to the data) that use the same signature 4958 mechanism and signature key. hSession is the session’s handle; pMechanism points to the signature 4959 mechanism; hKey is the handle of the signature key. 4960

The CKA_SIGN attribute of the signature key, which indicates whether the key supports signatures with 4961

appendix, MUST be CK_TRUE. 4962

After calling C_MessageSignInit, the application can either call C_SignMessage to sign a message in a 4963 single part; or call C_SignMessageBegin, followed by C_SignMessageNext one or more times, to sign 4964 a message in multiple parts. This may be repeated several times. The message-based signature process 4965 is active until the application calls C_MessageSignFinal to finish the message-based signature process. 4966

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 4967 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 4968 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 4969


CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED,CKR_KEY_HANDLE_INVALID, 4970 CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, 4971 CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, 4972 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN. 4973

5.14.2 C_SignMessage 4974

CK_DECLARE_FUNCTION(CK_RV, C_SignMessage)( 4975


CK_VOID_PTR pParameter, 4977

CK_ULONG ulParameterLen, 4978

CK_BYTE_PTR pData, 4979

CK_ULONG ulDataLen, 4980

CK_BYTE_PTR pSignature, 4981

CK_ULONG_PTR pulSignatureLen 4982

); 4983

C_SignMessage signs a message in a single part, where the signature is an appendix to the message. 4984 C_MessageSignInit must previously been called on the session. hSession is the session’s handle; 4985 pParameter and ulParameterLen specify any mechanism-specific parameters for the message signature 4986 operation; pData points to the data; ulDataLen is the length of the data; pSignature points to the location 4987 that receives the signature; pulSignatureLen points to the location that holds the length of the signature. 4988

Depending on the mechanism parameter passed to C_MessageSignInit, pParameter may be either an 4989

input or an output parameter. 4990

C_SignMessage uses the convention described in Section 5.2 on producing output. 4991

The message-based signing process MUST have been initialized with C_MessageSignInit. A call to 4992 C_SignMessage begins and terminates a message signing operation unless it returns 4993 CKR_BUFFER_TOO_SMALL to determine the length of the buffer needed to hold the signature, or is a 4994 successful call (i.e., one which returns CKR_OK). 4995

C_SignMessage cannot be called in the middle of a multi-part message signing operation. 4996

C_SignMessage does not finish the message-based signing process. Additional C_SignMessage or 4997 C_SignMessageBegin and C_SignMessageNext calls may be made on the session. 4998

For most mechanisms, C_SignMessage is equivalent to C_SignMessageBegin followed by a sequence 4999 of C_SignMessageNext operations. 5000

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 5001 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, 5002 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 5003 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 5004 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 5005 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, CKR_FUNCTION_REJECTED, 5006 CKR_TOKEN_RESOURCE_EXCEEDED. 5007

5.14.3 C_SignMessageBegin 5008

CK_DECLARE_FUNCTION(CK_RV, C_SignMessageBegin)( 5009



CK_ULONG ulParameterLen 5012

); 5013

C_SignMessageBegin begins a multiple-part message signature operation, where the signature is an 5014 appendix to the message. C_MessageSignInit must previously been called on the session. hSession is 5015


the session’s handle; pParameter and ulParameterLen specify any mechanism-specific parameters for 5016

the message signature operation. 5017

Depending on the mechanism parameter passed to C_MessageSignInit, pParameter may be either an 5018

input or an output parameter. 5019

After calling C_SignMessageBegin, the application should call C_SignMessageNext one or more times 5020 to sign the message in multiple parts. The message signature operation is active until the application 5021 uses a call to C_SignMessageNext with a non-NULL pulSignatureLen to actually obtain the signature. 5022 To process additional messages (in single or multiple parts), the application MUST call C_SignMessage 5023 or C_SignMessageBegin again. 5024

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 5025 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 5026 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 5027 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, 5028 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 5029 CKR_TOKEN_RESOURCE_EXCEEDED. 5030

5.14.4 C_SignMessageNext 5031

CK_DECLARE_FUNCTION(CK_RV, C_SignMessageNext)( 5032




CK_BYTE_PTR pDataPart, 5036

CK_ULONG ulDataPartLen, 5037


CK_ULONG_PTR pulSignatureLen 5039

); 5040

C_SignMessageNext continues a multiple-part message signature operation, processing another data 5041 part, or finishes a multiple-part message signature operation, returning the signature. hSession is the 5042 session’s handle, pDataPart points to the data part; pParameter and ulParameterLen specify any 5043 mechanism-specific parameters for the message signature operation; ulDataPartLen is the length of the 5044 data part; pSignature points to the location that receives the signature; pulSignatureLen points to the 5045

location that holds the length of the signature. 5046

The pulSignatureLen argument is set to NULL if there is more data part to follow, or set to a non-NULL 5047

value (to receive the signature length) if this is the last data part. 5048

C_SignMessageNext uses the convention described in Section 5.2 on producing output. 5049

The message signing operation MUST have been started with C_SignMessageBegin. This function may 5050 be called any number of times in succession. A call to C_SignMessageNext with a NULL 5051 pulSignatureLen which results in an error terminates the current message signature operation. A call to 5052 C_SignMessageNext with a non-NULL pulSignatureLen always terminates the active message signing 5053 operation unless it returns CKR_BUFFER_TOO_SMALL to determine the length of the buffer needed to 5054 hold the signature, or is a successful call (i.e., one which returns CKR_OK). 5055

Although the last C_SignMessageNext call ends the signing of a message, it does not finish the 5056 message-based signing process. Additional C_SignMessage or C_SignMessageBegin and 5057 C_SignMessageNext calls may be made on the session. 5058

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 5059 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, 5060 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, 5061 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, 5062 CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 5063


CKR_USER_NOT_LOGGED_IN, CKR_FUNCTION_REJECTED, 5064 CKR_TOKEN_RESOURCE_EXCEEDED. 5065

5.14.5 C_MessageSignFinal 5066

CK_DECLARE_FUNCTION(CK_RV, C_MessageSignFinal)( 5067

CK_SESSION_HANDLE hSession 5068

); 5069

C_MessageSignFinal finishes a message-based signing process. hSession is the session’s handle. 5070

The message-based signing process MUST have been initialized with C_MessageSignInit. 5071

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 5072 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 5073 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 5074 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 5075 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, CKR_FUNCTION_REJECTED, 5076 CKR_TOKEN_RESOURCE_EXCEEDED. 5077

5.15 Functions for verifying signatures and MACs 5078

Cryptoki provides the following functions for verifying signatures on data (for the purposes of Cryptoki, 5079 these operations also encompass message authentication codes): 5080

5.15.1 C_VerifyInit 5081

CK_DECLARE_FUNCTION(CK_RV, C_VerifyInit)( 5082 CK_SESSION_HANDLE hSession, 5083 CK_MECHANISM_PTR pMechanism, 5084 CK_OBJECT_HANDLE hKey 5085 ); 5086

C_VerifyInit initializes a verification operation, where the signature is an appendix to the data. hSession 5087 is the session’s handle; pMechanism points to the structure that specifies the verification mechanism; 5088 hKey is the handle of the verification key. 5089

The CKA_VERIFY attribute of the verification key, which indicates whether the key supports verification 5090

where the signature is an appendix to the data, MUST be CK_TRUE. 5091

After calling C_VerifyInit, the application can either call C_Verify to verify a signature on data in a single 5092 part; or call C_VerifyUpdate one or more times, followed by C_VerifyFinal, to verify a signature on data 5093 in multiple parts. The verification operation is active until the application calls C_Verify or C_VerifyFinal. 5094 To process additional data (in single or multiple parts), the application MUST call C_VerifyInit again. 5095

C_VerifyInit can be called with pMechanism set to NULL_PTR to terminate an active verification 5096 operation. If an active operation has been initialized and it cannot be cancelled, 5097 CKR_OPERATION_CANCEL_FAILED must be returned. 5098


Example: see C_VerifyFinal. 5107


5.15.2 C_Verify 5108

CK_DECLARE_FUNCTION(CK_RV, C_Verify)( 5109 CK_SESSION_HANDLE hSession, 5110 CK_BYTE_PTR pData, 5111 CK_ULONG ulDataLen, 5112 CK_BYTE_PTR pSignature, 5113 CK_ULONG ulSignatureLen 5114 ); 5115

C_Verify verifies a signature in a single-part operation, where the signature is an appendix to the data. 5116 hSession is the session’s handle; pData points to the data; ulDataLen is the length of the data; 5117 pSignature points to the signature; ulSignatureLen is the length of the signature. 5118

The verification operation MUST have been initialized with C_VerifyInit. A call to C_Verify always 5119 terminates the active verification operation. 5120

A successful call to C_Verify should return either the value CKR_OK (indicating that the supplied 5121 signature is valid) or CKR_SIGNATURE_INVALID (indicating that the supplied signature is invalid). If the 5122 signature can be seen to be invalid purely on the basis of its length, then 5123 CKR_SIGNATURE_LEN_RANGE should be returned. In any of these cases, the active signing operation 5124 is terminated. 5125

C_Verify cannot be used to terminate a multi-part operation, and MUST be called after C_VerifyInit 5126 without intervening C_VerifyUpdate calls. 5127

For most mechanisms, C_Verify is equivalent to a sequence of C_VerifyUpdate operations followed by 5128 C_VerifyFinal. 5129

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, 5130 CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 5131 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 5132 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 5133 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SIGNATURE_INVALID, 5134 CKR_SIGNATURE_LEN_RANGE, CKR_TOKEN_RESOURCE_EXCEEDED. 5135

Example: see C_VerifyFinal for an example of similar functions. 5136

5.15.3 C_VerifyUpdate 5137

CK_DECLARE_FUNCTION(CK_RV, C_VerifyUpdate)( 5138 CK_SESSION_HANDLE hSession, 5139 CK_BYTE_PTR pPart, 5140 CK_ULONG ulPartLen 5141 ); 5142

C_VerifyUpdate continues a multiple-part verification operation, processing another data part. hSession 5143 is the session’s handle, pPart points to the data part; ulPartLen is the length of the data part. 5144

The verification operation MUST have been initialized with C_VerifyInit. This function may be called any 5145 number of times in succession. A call to C_VerifyUpdate which results in an error terminates the current 5146

verification operation. 5147

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 5148 CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 5149 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 5150 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 5151 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 5152 CKR_TOKEN_RESOURCE_EXCEEDED. 5153

Example: see C_VerifyFinal. 5154


5.15.4 C_VerifyFinal 5155

CK_DECLARE_FUNCTION(CK_RV, C_VerifyFinal)( 5156 CK_SESSION_HANDLE hSession, 5157 CK_BYTE_PTR pSignature, 5158 CK_ULONG ulSignatureLen 5159 ); 5160

C_VerifyFinal finishes a multiple-part verification operation, checking the signature. hSession is the 5161 session’s handle; pSignature points to the signature; ulSignatureLen is the length of the signature. 5162

The verification operation MUST have been initialized with C_VerifyInit. A call to C_VerifyFinal always 5163

terminates the active verification operation. 5164

A successful call to C_VerifyFinal should return either the value CKR_OK (indicating that the supplied 5165 signature is valid) or CKR_SIGNATURE_INVALID (indicating that the supplied signature is invalid). If the 5166 signature can be seen to be invalid purely on the basis of its length, then 5167 CKR_SIGNATURE_LEN_RANGE should be returned. In any of these cases, the active verifying 5168 operation is terminated. 5169

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 5170 CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 5171 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 5172 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 5173 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SIGNATURE_INVALID, 5174 CKR_SIGNATURE_LEN_RANGE, CKR_TOKEN_RESOURCE_EXCEEDED. 5175

Example: 5176





}; 5181

CK_BYTE data[] = {...}; 5182

CK_BYTE mac[4]; 5183

CK_RV rv; 5184

5185

. 5186

. 5187

rv = C_VerifyInit(hSession, &mechanism, hKey); 5188

if (rv == CKR_OK) { 5189

rv = C_VerifyUpdate(hSession, data, sizeof(data)); 5190

. 5191

. 5192

rv = C_VerifyFinal(hSession, mac, sizeof(mac)); 5193

. 5194

. 5195

} 5196

5.15.5 C_VerifyRecoverInit 5197

CK_DECLARE_FUNCTION(CK_RV, C_VerifyRecoverInit)( 5198 CK_SESSION_HANDLE hSession, 5199



CK_MECHANISM_PTR pMechanism, 5200 CK_OBJECT_HANDLE hKey 5201 ); 5202

C_VerifyRecoverInit initializes a signature verification operation, where the data is recovered from the 5203 signature. hSession is the session’s handle; pMechanism points to the structure that specifies the 5204 verification mechanism; hKey is the handle of the verification key. 5205

The CKA_VERIFY_RECOVER attribute of the verification key, which indicates whether the key supports 5206

verification where the data is recovered from the signature, MUST be CK_TRUE. 5207

After calling C_VerifyRecoverInit, the application may call C_VerifyRecover to verify a signature on 5208 data in a single part. The verification operation is active until the application uses a call to 5209 C_VerifyRecover to actually obtain the recovered message. 5210

C_VerifyRecoverInit can be called with pMechanism set to NULL_PTR to terminate an active verification 5211 with data recovery operation. If an active operations has been initialized and it cannot be cancelled, 5212 CKR_OPERATION_CANCEL_FAILED must be returned. 5213


Example: see C_VerifyRecover. 5222

5.15.6 C_VerifyRecover 5223

CK_DECLARE_FUNCTION(CK_RV, C_VerifyRecover)( 5224 CK_SESSION_HANDLE hSession, 5225 CK_BYTE_PTR pSignature, 5226 CK_ULONG ulSignatureLen, 5227 CK_BYTE_PTR pData, 5228 CK_ULONG_PTR pulDataLen 5229 ); 5230

C_VerifyRecover verifies a signature in a single-part operation, where the data is recovered from the 5231 signature. hSession is the session’s handle; pSignature points to the signature; ulSignatureLen is the 5232 length of the signature; pData points to the location that receives the recovered data; and pulDataLen 5233 points to the location that holds the length of the recovered data. 5234

C_VerifyRecover uses the convention described in Section 5.2 on producing output. 5235

The verification operation MUST have been initialized with C_VerifyRecoverInit. A call to 5236 C_VerifyRecover always terminates the active verification operation unless it returns 5237 CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the 5238

length of the buffer needed to hold the recovered data. 5239

A successful call to C_VerifyRecover should return either the value CKR_OK (indicating that the 5240 supplied signature is valid) or CKR_SIGNATURE_INVALID (indicating that the supplied signature is 5241 invalid). If the signature can be seen to be invalid purely on the basis of its length, then 5242 CKR_SIGNATURE_LEN_RANGE should be returned. The return codes CKR_SIGNATURE_INVALID 5243 and CKR_SIGNATURE_LEN_RANGE have a higher priority than the return code 5244 CKR_BUFFER_TOO_SMALL, i.e., if C_VerifyRecover is supplied with an invalid signature, it will never 5245

return CKR_BUFFER_TOO_SMALL. 5246

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 5247 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, 5248 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 5249 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 5250


CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, 5251 CKR_SESSION_HANDLE_INVALID, CKR_SIGNATURE_LEN_RANGE, CKR_SIGNATURE_INVALID, 5252 CKR_TOKEN_RESOURCE_EXCEEDED. 5253

Example: 5254




CKM_RSA_9796, NULL_PTR, 0 5258

}; 5259

CK_BYTE data[] = {...}; 5260

CK_ULONG ulDataLen; 5261

CK_BYTE signature[128]; 5262

CK_RV rv; 5263

5264

. 5265

. 5266

rv = C_VerifyRecoverInit(hSession, &mechanism, hKey); 5267

if (rv == CKR_OK) { 5268

ulDataLen = sizeof(data); 5269

rv = C_VerifyRecover( 5270

hSession, signature, sizeof(signature), data, &ulDataLen); 5271

. 5272

. 5273

} 5274

5.16 Message-based functions for verifying signatures and MACs 5275

Message-based verification refers to the process of verifying signatures on multiple messages using the 5276 same verification mechanism and verification key. 5277

Cryptoki provides the following functions for verifying signatures on messages (for the purposes of 5278 Cryptoki, these operations also encompass message authentication codes). 5279

5.16.1 C_MessageVerifyInit 5280

CK_DECLARE_FUNCTION(CK_RV, C_MessageVerifyInit)( 5281


CK_MECHANISM_PTR pMechanism, 5283

CK_OBJECT_HANDLE hKey 5284

); 5285

C_MessageVerifyInit initializes a message-based verification process, preparing a session for one or 5286 more verification operations (where the signature is an appendix to the data) that use the same 5287 verification mechanism and verification key. hSession is the session’s handle; pMechanism points to the 5288 structure that specifies the verification mechanism; hKey is the handle of the verification key. 5289

The CKA_VERIFY attribute of the verification key, which indicates whether the key supports verification 5290

where the signature is an appendix to the data, MUST be CK_TRUE. 5291

After calling C_MessageVerifyInit, the application can either call C_VerifyMessage to verify a signature 5292 on a message in a single part; or call C_VerifyMessageBegin, followed by C_VerifyMessageNext one 5293


or more times, to verify a signature on a message in multiple parts. This may be repeated several times. 5294 The message-based verification process is active until the application calls C_MessageVerifyFinal to 5295

finish the message-based verification process. 5296

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 5297 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 5298 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 5299 CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, 5300 CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, 5301 CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, 5302 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN. 5303

5.16.2 C_VerifyMessage 5304

CK_DECLARE_FUNCTION(CK_RV, C_VerifyMessage)( 5305




CK_BYTE_PTR pData, 5309

CK_ULONG ulDataLen, 5310


CK_ULONG ulSignatureLen 5312

); 5313

C_VerifyMessage verifies a signature on a message in a single part operation, where the signature is an 5314 appendix to the data. C_MessageVerifyInit must previously been called on the session. hSession is the 5315 session’s handle; pParameter and ulParameterLen specify any mechanism-specific parameters for the 5316 message verification operation; pData points to the data; ulDataLen is the length of the data; pSignature 5317 points to the signature; ulSignatureLen is the length of the signature. 5318

Unlike the pParameter parameter of C_SignMessage, pParameter is always an input parameter. 5319

The message-based verification process MUST have been initialized with C_MessageVerifyInit. A call to 5320 C_VerifyMessage starts and terminates a message verification operation. 5321

A successful call to C_VerifyMessage should return either the value CKR_OK (indicating that the 5322 supplied signature is valid) or CKR_SIGNATURE_INVALID (indicating that the supplied signature is 5323 invalid). If the signature can be seen to be invalid purely on the basis of its length, then 5324 CKR_SIGNATURE_LEN_RANGE should be returned. 5325

C_VerifyMessage does not finish the message-based verification process. Additional C_VerifyMessage 5326 or C_VerifyMessageBegin and C_VerifyMessageNext calls may be made on the session. 5327

For most mechanisms, C_VerifyMessage is equivalent to C_VerifyMessageBegin followed by a 5328 sequence of C_VerifyMessageNext operations. 5329

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, 5330 CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 5331 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 5332 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 5333 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SIGNATURE_INVALID, 5334 CKR_SIGNATURE_LEN_RANGE, CKR_TOKEN_RESOURCE_EXCEEDED. 5335

5.16.3 C_VerifyMessageBegin 5336

CK_DECLARE_FUNCTION(CK_RV, C_VerifyMessageBegin)( 5337




CK_ULONG ulParameterLen 5340

); 5341

C_VerifyMessageBegin begins a multiple-part message verification operation, where the signature is an 5342 appendix to the message. C_MessageVerifyInit must previously been called on the session. hSession is 5343 the session’s handle; pParameter and ulParameterLen specify any mechanism-specific parameters for 5344

the message verification operation. 5345

Unlike the pParameter parameter of C_SignMessageBegin, pParameter is always an input parameter. 5346

After calling C_VerifyMessageBegin, the application should call C_VerifyMessageNext one or more 5347 times to verify a signature on a message in multiple parts. The message verification operation is active 5348 until the application calls C_VerifyMessageNext with a non-NULL pSignature. To process additional 5349 messages (in single or multiple parts), the application MUST call C_VerifyMessage or 5350 C_VerifyMessageBegin again. 5351

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 5352 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 5353 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 5354 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, 5355 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN. 5356

5.16.4 C_VerifyMessageNext 5357

CK_DECLARE_FUNCTION(CK_RV, C_VerifyMessageNext)( 5358




CK_BYTE_PTR pDataPart, 5362

CK_ULONG ulDataPartLen, 5363


CK_ULONG ulSignatureLen 5365

); 5366

C_VerifyMessageNext continues a multiple-part message verification operation, processing another data 5367 part, or finishes a multiple-part message verification operation, checking the signature. hSession is the 5368 session’s handle, pParameter and ulParameterLen specify any mechanism-specific parameters for the 5369 message verification operation, pPart points to the data part; ulPartLen is the length of the data part; 5370 pSignature points to the signature; ulSignatureLen is the length of the signature. 5371

The pSignature argument is set to NULL if there is more data part to follow, or set to a non-NULL value 5372

(pointing to the signature to verify) if this is the last data part. 5373

The message verification operation MUST have been started with C_VerifyMessageBegin. This function 5374 may be called any number of times in succession. A call to C_VerifyMessageNext with a NULL 5375 pSignature which results in an error terminates the current message verification operation. A call to 5376 C_VerifyMessageNext with a non-NULL pSignature always terminates the active message verification 5377

operation. 5378

A successful call to C_VerifyMessageNext with a non-NULL pSignature should return either the value 5379 CKR_OK (indicating that the supplied signature is valid) or CKR_SIGNATURE_INVALID (indicating that 5380 the supplied signature is invalid). If the signature can be seen to be invalid purely on the basis of its 5381 length, then CKR_SIGNATURE_LEN_RANGE should be returned. In any of these cases, the active 5382 message verifying operation is terminated. 5383

Although the last C_VerifyMessageNext call ends the verification of a message, it does not finish the 5384 message-based verification process. Additional C_VerifyMessage or C_VerifyMessageBegin and 5385 C_VerifyMessageNext calls may be made on the session. 5386


Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 5387 CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 5388 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 5389 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 5390 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SIGNATURE_INVALID, 5391 CKR_SIGNATURE_LEN_RANGE, CKR_TOKEN_RESOURCE_EXCEEDED. 5392

5.16.5 C_MessageVerifyFinal 5393

CK_DECLARE_FUNCTION(CK_RV,C_MessageVerifyFinal)( 5394

CK_SESSION_HANDLE hSession 5395

); 5396

C_MessageVerifyFinal finishes a message-based verification process. hSession is the session’s handle. 5397

The message-based verification process MUST have been initialized with C_MessageVerifyInit. 5398

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 5399 CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 5400 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 5401 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 5402 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 5403 CKR_TOKEN_RESOURCE_EXCEEDED. 5404

5.17 Dual-function cryptographic functions 5405

Cryptoki provides the following functions to perform two cryptographic operations “simultaneously” within 5406 a session. These functions are provided so as to avoid unnecessarily passing data back and forth to and 5407 from a token. 5408

5.17.1 C_DigestEncryptUpdate 5409

CK_DECLARE_FUNCTION(CK_RV, C_DigestEncryptUpdate)( 5410 CK_SESSION_HANDLE hSession, 5411 CK_BYTE_PTR pPart, 5412 CK_ULONG ulPartLen, 5413 CK_BYTE_PTR pEncryptedPart, 5414 CK_ULONG_PTR pulEncryptedPartLen 5415 ); 5416

C_DigestEncryptUpdate continues multiple-part digest and encryption operations, processing another 5417 data part. hSession is the session’s handle; pPart points to the data part; ulPartLen is the length of the 5418 data part; pEncryptedPart points to the location that receives the digested and encrypted data part; 5419 pulEncryptedPartLen points to the location that holds the length of the encrypted data part. 5420

C_DigestEncryptUpdate uses the convention described in Section 5.2 on producing output. If a 5421 C_DigestEncryptUpdate call does not produce encrypted output (because an error occurs, or because 5422 pEncryptedPart has the value NULL_PTR, or because pulEncryptedPartLen is too small to hold the entire 5423 encrypted part output), then no plaintext is passed to the active digest operation. 5424

Digest and encryption operations MUST both be active (they MUST have been initialized with 5425 C_DigestInit and C_EncryptInit, respectively). This function may be called any number of times in 5426 succession, and may be interspersed with C_DigestUpdate, C_DigestKey, and C_EncryptUpdate calls 5427 (it would be somewhat unusual to intersperse calls to C_DigestEncryptUpdate with calls to 5428 C_DigestKey, however). 5429



Example: 5435

#define BUF_SZ 512 5436

5437



CK_BYTE iv[8]; 5440

CK_MECHANISM digestMechanism = { 5441


}; 5443

CK_MECHANISM encryptionMechanism = { 5444

CKM_DES_ECB, iv, sizeof(iv) 5445

}; 5446

CK_BYTE encryptedData[BUF_SZ]; 5447

CK_ULONG ulEncryptedDataLen; 5448



CK_BYTE data[(2*BUF_SZ)+8]; 5451

CK_RV rv; 5452

int i; 5453

5454

. 5455

. 5456

memset(iv, 0, sizeof(iv)); 5457

memset(data, ‘A’, ((2*BUF_SZ)+5)); 5458

rv = C_EncryptInit(hSession, &encryptionMechanism, hKey); 5459

if (rv != CKR_OK) { 5460

. 5461

. 5462

} 5463


if (rv != CKR_OK) { 5465

. 5466

. 5467

} 5468

5469

ulEncryptedDataLen = sizeof(encryptedData); 5470

rv = C_DigestEncryptUpdate( 5471

hSession, 5472

&data[0], BUF_SZ, 5473

encryptedData, &ulEncryptedDataLen); 5474

. 5475

. 5476




rv = C_DigestEncryptUpdate( 5478

hSession, 5479

&data[BUF_SZ], BUF_SZ, 5480


. 5482

. 5483

5484

/* 5485

* The last portion of the buffer needs to be 5486

* handled with separate calls to deal with 5487

* padding issues in ECB mode 5488

*/ 5489

5490

/* First, complete the digest on the buffer */ 5491

rv = C_DigestUpdate(hSession, &data[BUF_SZ*2], 5); 5492

. 5493

. 5494



. 5497

. 5498

5499

/* Then, pad last part with 3 0x00 bytes, and complete encryption */ 5500

for(i=0;i<3;i++) 5501

data[((BUF_SZ*2)+5)+i] = 0x00; 5502

5503

/* Now, get second-to-last piece of ciphertext */ 5504



hSession, 5507

&data[BUF_SZ*2], 8, 5508


. 5510

. 5511

5512

/* Get last piece of ciphertext (should have length 0, here) */ 5513


rv = C_EncryptFinal(hSession, encryptedData, &ulEncryptedDataLen); 5515

. 5516

. 5517



5.17.2 C_DecryptDigestUpdate 5518

CK_DECLARE_FUNCTION(CK_RV, C_DecryptDigestUpdate)( 5519 CK_SESSION_HANDLE hSession, 5520 CK_BYTE_PTR pEncryptedPart, 5521 CK_ULONG ulEncryptedPartLen, 5522 CK_BYTE_PTR pPart, 5523 CK_ULONG_PTR pulPartLen 5524 ); 5525

C_DecryptDigestUpdate continues a multiple-part combined decryption and digest operation, 5526 processing another data part. hSession is the session’s handle; pEncryptedPart points to the encrypted 5527 data part; ulEncryptedPartLen is the length of the encrypted data part; pPart points to the location that 5528 receives the recovered data part; pulPartLen points to the location that holds the length of the recovered 5529

data part. 5530

C_DecryptDigestUpdate uses the convention described in Section 5.2 on producing output. If a 5531 C_DecryptDigestUpdate call does not produce decrypted output (because an error occurs, or because 5532 pPart has the value NULL_PTR, or because pulPartLen is too small to hold the entire decrypted part 5533

output), then no plaintext is passed to the active digest operation. 5534

Decryption and digesting operations MUST both be active (they MUST have been initialized with 5535 C_DecryptInit and C_DigestInit, respectively). This function may be called any number of times in 5536 succession, and may be interspersed with C_DecryptUpdate, C_DigestUpdate, and C_DigestKey calls 5537 (it would be somewhat unusual to intersperse calls to C_DigestEncryptUpdate with calls to 5538 C_DigestKey, however). 5539

Use of C_DecryptDigestUpdate involves a pipelining issue that does not arise when using 5540 C_DigestEncryptUpdate, the “inverse function” of C_DecryptDigestUpdate. This is because when 5541 C_DigestEncryptUpdate is called, precisely the same input is passed to both the active digesting 5542 operation and the active encryption operation; however, when C_DecryptDigestUpdate is called, the 5543 input passed to the active digesting operation is the output of the active decryption operation. This issue 5544 comes up only when the mechanism used for decryption performs padding. 5545

In particular, envision a 24-byte ciphertext which was obtained by encrypting an 18-byte plaintext with 5546 DES in CBC mode with PKCS padding. Consider an application which will simultaneously decrypt this 5547 ciphertext and digest the original plaintext thereby obtained. 5548

After initializing decryption and digesting operations, the application passes the 24-byte ciphertext (3 DES 5549 blocks) into C_DecryptDigestUpdate. C_DecryptDigestUpdate returns exactly 16 bytes of plaintext, 5550 since at this point, Cryptoki doesn’t know if there’s more ciphertext coming, or if the last block of 5551 ciphertext held any padding. These 16 bytes of plaintext are passed into the active digesting operation. 5552

Since there is no more ciphertext, the application calls C_DecryptFinal. This tells Cryptoki that there’s 5553 no more ciphertext coming, and the call returns the last 2 bytes of plaintext. However, since the active 5554 decryption and digesting operations are linked only through the C_DecryptDigestUpdate call, these 2 5555 bytes of plaintext are not passed on to be digested. 5556

A call to C_DigestFinal, therefore, would compute the message digest of the first 16 bytes of the 5557 plaintext, not the message digest of the entire plaintext. It is crucial that, before C_DigestFinal is called, 5558 the last 2 bytes of plaintext get passed into the active digesting operation via a C_DigestUpdate call. 5559

Because of this, it is critical that when an application uses a padded decryption mechanism with 5560 C_DecryptDigestUpdate, it knows exactly how much plaintext has been passed into the active digesting 5561 operation. Extreme caution is warranted when using a padded decryption mechanism with 5562 C_DecryptDigestUpdate. 5563

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 5564 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 5565 CKR_DEVICE_REMOVED, CKR_ENCRYPTED_DATA_INVALID, 5566 CKR_ENCRYPTED_DATA_LEN_RANGE, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 5567 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 5568 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 5569


Example: 5570


5572



CK_BYTE iv[8]; 5575

CK_MECHANISM decryptionMechanism = { 5576


}; 5578

CK_MECHANISM digestMechanism = { 5579


}; 5581

CK_BYTE encryptedData[(2*BUF_SZ)+8]; 5582



CK_BYTE data[BUF_SZ]; 5585

CK_ULONG ulDataLen, ulLastUpdateSize; 5586

CK_RV rv; 5587

5588

. 5589

. 5590


memset(encryptedData, ‘A’, ((2*BUF_SZ)+8)); 5592

rv = C_DecryptInit(hSession, &decryptionMechanism, hKey); 5593

if (rv != CKR_OK) { 5594

. 5595

. 5596

} 5597


if (rv != CKR_OK){ 5599

. 5600

. 5601

} 5602

5603


rv = C_DecryptDigestUpdate( 5605

hSession, 5606

&encryptedData[0], BUF_SZ, 5607

data, &ulDataLen); 5608

. 5609

. 5610


rv = C_DecryptDigestUpdate( 5612




hSession, 5613

&encryptedData[BUF_SZ], BUF_SZ, 5614


. 5616

. 5617

5618

/* 5619

* The last portion of the buffer needs to be handled with 5620

* separate calls to deal with padding issues in ECB mode 5621

*/ 5622

5623

/* First, complete the decryption of the buffer */ 5624

ulLastUpdateSize = sizeof(data); 5625


hSession, 5627

&encryptedData[BUF_SZ*2], 8, 5628

data, &ulLastUpdateSize); 5629

. 5630

. 5631

/* Get last piece of plaintext (should have length 0, here) */ 5632

ulDataLen = sizeof(data)-ulLastUpdateSize; 5633

rv = C_DecryptFinal(hSession, &data[ulLastUpdateSize], &ulDataLen); 5634

if (rv != CKR_OK) { 5635

. 5636

. 5637

} 5638

5639

/* Digest last bit of plaintext */ 5640

rv = C_DigestUpdate(hSession, data, 5); 5641

if (rv != CKR_OK) { 5642

. 5643

. 5644

} 5645



if (rv != CKR_OK) { 5648

. 5649

. 5650

} 5651

5.17.3 C_SignEncryptUpdate 5652

CK_DECLARE_FUNCTION(CK_RV, C_SignEncryptUpdate)( 5653 CK_SESSION_HANDLE hSession, 5654



CK_BYTE_PTR pPart, 5655 CK_ULONG ulPartLen, 5656 CK_BYTE_PTR pEncryptedPart, 5657 CK_ULONG_PTR pulEncryptedPartLen 5658 ); 5659

C_SignEncryptUpdate continues a multiple-part combined signature and encryption operation, 5660 processing another data part. hSession is the session’s handle; pPart points to the data part; ulPartLen is 5661 the length of the data part; pEncryptedPart points to the location that receives the digested and encrypted 5662 data part; and pulEncryptedPartLen points to the location that holds the length of the encrypted data part. 5663

C_SignEncryptUpdate uses the convention described in Section 5.2 on producing output. If a 5664 C_SignEncryptUpdate call does not produce encrypted output (because an error occurs, or because 5665 pEncryptedPart has the value NULL_PTR, or because pulEncryptedPartLen is too small to hold the entire 5666

encrypted part output), then no plaintext is passed to the active signing operation. 5667

Signature and encryption operations MUST both be active (they MUST have been initialized with 5668 C_SignInit and C_EncryptInit, respectively). This function may be called any number of times in 5669 succession, and may be interspersed with C_SignUpdate and C_EncryptUpdate calls. 5670

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 5671 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, 5672 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, 5673 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, 5674 CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, 5675 CKR_USER_NOT_LOGGED_IN. 5676

Example: 5677


5679


CK_OBJECT_HANDLE hEncryptionKey, hMacKey; 5681

CK_BYTE iv[8]; 5682

CK_MECHANISM signMechanism = { 5683


}; 5685

CK_MECHANISM encryptionMechanism = { 5686


}; 5688

CK_BYTE encryptedData[BUF_SZ]; 5689

CK_ULONG ulEncryptedDataLen; 5690

CK_BYTE MAC[4]; 5691


CK_BYTE data[(2*BUF_SZ)+8]; 5693

CK_RV rv; 5694

int i; 5695

5696

. 5697

. 5698


memset(data, ‘A’, ((2*BUF_SZ)+5)); 5700

rv = C_EncryptInit(hSession, &encryptionMechanism, hEncryptionKey); 5701



if (rv != CKR_OK) { 5702

. 5703

. 5704

} 5705

rv = C_SignInit(hSession, &signMechanism, hMacKey); 5706

if (rv != CKR_OK) { 5707

. 5708

. 5709

} 5710

5711


rv = C_SignEncryptUpdate( 5713

hSession, 5714

&data[0], BUF_SZ, 5715


. 5717

. 5718


rv = C_SignEncryptUpdate( 5720

hSession, 5721

&data[BUF_SZ], BUF_SZ, 5722


. 5724

. 5725

5726

/* 5727



*/ 5730

5731

/* First, complete the signature on the buffer */ 5732

rv = C_SignUpdate(hSession, &data[BUF_SZ*2], 5); 5733

. 5734

. 5735

ulMacLen = sizeof(MAC); 5736

rv = C_SignFinal(hSession, MAC, &ulMacLen); 5737

. 5738

. 5739

5740

/* Then pad last part with 3 0x00 bytes, and complete encryption */ 5741

for(i=0;i<3;i++) 5742

data[((BUF_SZ*2)+5)+i] = 0x00; 5743

5744


/* Now, get second-to-last piece of ciphertext */ 5745



hSession, 5748

&data[BUF_SZ*2], 8, 5749


. 5751

. 5752

5753

/* Get last piece of ciphertext (should have length 0, here) */ 5754


rv = C_EncryptFinal(hSession, encryptedData, &ulEncryptedDataLen); 5756

. 5757

. 5758

5.17.4 C_DecryptVerifyUpdate 5759

CK_DECLARE_FUNCTION(CK_RV, C_DecryptVerifyUpdate)( 5760 CK_SESSION_HANDLE hSession, 5761 CK_BYTE_PTR pEncryptedPart, 5762 CK_ULONG ulEncryptedPartLen, 5763 CK_BYTE_PTR pPart, 5764 CK_ULONG_PTR pulPartLen 5765 ); 5766

C_DecryptVerifyUpdate continues a multiple-part combined decryption and verification operation, 5767 processing another data part. hSession is the session’s handle; pEncryptedPart points to the encrypted 5768 data; ulEncryptedPartLen is the length of the encrypted data; pPart points to the location that receives the 5769 recovered data; and pulPartLen points to the location that holds the length of the recovered data. 5770

C_DecryptVerifyUpdate uses the convention described in Section 5.2 on producing output. If a 5771 C_DecryptVerifyUpdate call does not produce decrypted output (because an error occurs, or because 5772 pPart has the value NULL_PTR, or because pulPartLen is too small to hold the entire encrypted part 5773

output), then no plaintext is passed to the active verification operation. 5774

Decryption and signature operations MUST both be active (they MUST have been initialized with 5775 C_DecryptInit and C_VerifyInit, respectively). This function may be called any number of times in 5776 succession, and may be interspersed with C_DecryptUpdate and C_VerifyUpdate calls. 5777

Use of C_DecryptVerifyUpdate involves a pipelining issue that does not arise when using 5778 C_SignEncryptUpdate, the “inverse function” of C_DecryptVerifyUpdate. This is because when 5779 C_SignEncryptUpdate is called, precisely the same input is passed to both the active signing operation 5780 and the active encryption operation; however, when C_DecryptVerifyUpdate is called, the input passed 5781 to the active verifying operation is the output of the active decryption operation. This issue comes up only 5782

when the mechanism used for decryption performs padding. 5783

In particular, envision a 24-byte ciphertext which was obtained by encrypting an 18-byte plaintext with 5784 DES in CBC mode with PKCS padding. Consider an application which will simultaneously decrypt this 5785 ciphertext and verify a signature on the original plaintext thereby obtained. 5786

After initializing decryption and verification operations, the application passes the 24-byte ciphertext (3 5787 DES blocks) into C_DecryptVerifyUpdate. C_DecryptVerifyUpdate returns exactly 16 bytes of 5788 plaintext, since at this point, Cryptoki doesn’t know if there’s more ciphertext coming, or if the last block of 5789 ciphertext held any padding. These 16 bytes of plaintext are passed into the active verification operation. 5790

Since there is no more ciphertext, the application calls C_DecryptFinal. This tells Cryptoki that there’s 5791 no more ciphertext coming, and the call returns the last 2 bytes of plaintext. However, since the active 5792


decryption and verification operations are linked only through the C_DecryptVerifyUpdate call, these 2 5793 bytes of plaintext are not passed on to the verification mechanism. 5794

A call to C_VerifyFinal, therefore, would verify whether or not the signature supplied is a valid signature 5795 on the first 16 bytes of the plaintext, not on the entire plaintext. It is crucial that, before C_VerifyFinal is 5796 called, the last 2 bytes of plaintext get passed into the active verification operation via a C_VerifyUpdate 5797 call. 5798

Because of this, it is critical that when an application uses a padded decryption mechanism with 5799 C_DecryptVerifyUpdate, it knows exactly how much plaintext has been passed into the active 5800 verification operation. Extreme caution is warranted when using a padded decryption mechanism with 5801 C_DecryptVerifyUpdate. 5802

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 5803 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, 5804 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_ENCRYPTED_DATA_INVALID, 5805 CKR_ENCRYPTED_DATA_LEN_RANGE, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 5806 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, 5807 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID. 5808

Example: 5809


5811


CK_OBJECT_HANDLE hDecryptionKey, hMacKey; 5813

CK_BYTE iv[8]; 5814

CK_MECHANISM decryptionMechanism = { 5815


}; 5817

CK_MECHANISM verifyMechanism = { 5818


}; 5820

CK_BYTE encryptedData[(2*BUF_SZ)+8]; 5821

CK_BYTE MAC[4]; 5822


CK_BYTE data[BUF_SZ]; 5824

CK_ULONG ulDataLen, ulLastUpdateSize; 5825

CK_RV rv; 5826

5827

. 5828

. 5829


memset(encryptedData, ‘A’, ((2*BUF_SZ)+8)); 5831

rv = C_DecryptInit(hSession, &decryptionMechanism, hDecryptionKey); 5832

if (rv != CKR_OK) { 5833

. 5834

. 5835

} 5836

rv = C_VerifyInit(hSession, &verifyMechanism, hMacKey); 5837

if (rv != CKR_OK){ 5838



. 5839

. 5840

} 5841

5842


rv = C_DecryptVerifyUpdate( 5844

hSession, 5845

&encryptedData[0], BUF_SZ, 5846


. 5848

. 5849


rv = C_DecryptVerifyUpdate( 5851

hSession, 5852

&encryptedData[BUF_SZ], BUF_SZ, 5853


. 5855

. 5856

5857

/* 5858



*/ 5861

5862

/* First, complete the decryption of the buffer */ 5863

ulLastUpdateSize = sizeof(data); 5864


hSession, 5866

&encryptedData[BUF_SZ*2], 8, 5867

data, &ulLastUpdateSize); 5868

. 5869

. 5870

/* Get last little piece of plaintext. Should have length 0 */ 5871

ulDataLen = sizeof(data)-ulLastUpdateSize; 5872

rv = C_DecryptFinal(hSession, &data[ulLastUpdateSize], &ulDataLen); 5873

if (rv != CKR_OK) { 5874

. 5875

. 5876

} 5877

5878

/* Send last bit of plaintext to verification operation */ 5879

rv = C_VerifyUpdate(hSession, data, 5); 5880

if (rv != CKR_OK) { 5881


. 5882

. 5883

} 5884

rv = C_VerifyFinal(hSession, MAC, ulMacLen); 5885

if (rv == CKR_SIGNATURE_INVALID) { 5886

. 5887

. 5888

} 5889

5.18 Key management functions 5890

Cryptoki provides the following functions for key management: 5891

5.18.1 C_GenerateKey 5892

CK_DECLARE_FUNCTION(CK_RV, C_GenerateKey)( 5893 CK_SESSION_HANDLE hSession 5894 CK_MECHANISM_PTR pMechanism, 5895 CK_ATTRIBUTE_PTR pTemplate, 5896 CK_ULONG ulCount, 5897 CK_OBJECT_HANDLE_PTR phKey 5898 ); 5899

C_GenerateKey generates a secret key or set of domain parameters, creating a new object. hSession is 5900 the session’s handle; pMechanism points to the generation mechanism; pTemplate points to the template 5901 for the new key or set of domain parameters; ulCount is the number of attributes in the template; phKey 5902

points to the location that receives the handle of the new key or set of domain parameters. 5903

If the generation mechanism is for domain parameter generation, the CKA_CLASS attribute will have the 5904

value CKO_DOMAIN_PARAMETERS; otherwise, it will have the value CKO_SECRET_KEY. 5905

Since the type of key or domain parameters to be generated is implicit in the generation mechanism, the 5906 template does not need to supply a key type. If it does supply a key type which is inconsistent with the 5907 generation mechanism, C_GenerateKey fails and returns the error code 5908 CKR_TEMPLATE_INCONSISTENT. The CKA_CLASS attribute is treated similarly. 5909

If a call to C_GenerateKey cannot support the precise template supplied to it, it will fail and return without 5910

creating an object. 5911

The object created by a successful call to C_GenerateKey will have its CKA_LOCAL attribute set to 5912 CK_TRUE. In addition, the object created will have a value for CKA_UNIQUE_ID generated and 5913 assigned (See Section 4.4.1). 5914

Return values: CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, 5915 CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, 5916 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, 5917 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, 5918 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, 5919 CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, 5920 CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, 5921 CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, 5922 CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, 5923 CKR_USER_NOT_LOGGED_IN. 5924

Example: 5925





CKM_DES_KEY_GEN, NULL_PTR, 0 5929

}; 5930

CK_RV rv; 5931

5932

. 5933

. 5934

rv = C_GenerateKey(hSession, &mechanism, NULL_PTR, 0, &hKey); 5935

if (rv == CKR_OK) { 5936

. 5937

. 5938

} 5939

5.18.2 C_GenerateKeyPair 5940

CK_DECLARE_FUNCTION(CK_RV, C_GenerateKeyPair)( 5941 CK_SESSION_HANDLE hSession, 5942 CK_MECHANISM_PTR pMechanism, 5943 CK_ATTRIBUTE_PTR pPublicKeyTemplate, 5944 CK_ULONG ulPublicKeyAttributeCount, 5945 CK_ATTRIBUTE_PTR pPrivateKeyTemplate, 5946 CK_ULONG ulPrivateKeyAttributeCount, 5947 CK_OBJECT_HANDLE_PTR phPublicKey, 5948 CK_OBJECT_HANDLE_PTR phPrivateKey 5949 ); 5950

C_GenerateKeyPair generates a public/private key pair, creating new key objects. hSession is the 5951 session’s handle; pMechanism points to the key generation mechanism; pPublicKeyTemplate points to 5952 the template for the public key; ulPublicKeyAttributeCount is the number of attributes in the public-key 5953 template; pPrivateKeyTemplate points to the template for the private key; ulPrivateKeyAttributeCount is 5954 the number of attributes in the private-key template; phPublicKey points to the location that receives the 5955 handle of the new public key; phPrivateKey points to the location that receives the handle of the new 5956

private key. 5957

Since the types of keys to be generated are implicit in the key pair generation mechanism, the templates 5958 do not need to supply key types. If one of the templates does supply a key type which is inconsistent with 5959 the key generation mechanism, C_GenerateKeyPair fails and returns the error code 5960

CKR_TEMPLATE_INCONSISTENT. The CKA_CLASS attribute is treated similarly. 5961

If a call to C_GenerateKeyPair cannot support the precise templates supplied to it, it will fail and return 5962

without creating any key objects. 5963

A call to C_GenerateKeyPair will never create just one key and return. A call can fail, and create no 5964

keys; or it can succeed, and create a matching public/private key pair. 5965

The key objects created by a successful call to C_GenerateKeyPair will have their CKA_LOCAL 5966 attributes set to CK_TRUE. In addition, the key objects created will both have values for 5967 CKA_UNIQUE_ID generated and assigned (See Section 4.4.1). 5968

Note carefully the order of the arguments to C_GenerateKeyPair. The last two arguments do not have 5969 the same order as they did in the original Cryptoki Version 1.0 document. The order of these two 5970 arguments has caused some unfortunate confusion. 5971

Return values: CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, 5972 CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, 5973 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, 5974 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, 5975 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 5976 CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, 5977


CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, 5978 CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, 5979 CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, 5980 CKR_USER_NOT_LOGGED_IN. 5981

Example: 5982


CK_OBJECT_HANDLE hPublicKey, hPrivateKey; 5984


CKM_RSA_PKCS_KEY_PAIR_GEN, NULL_PTR, 0 5986

}; 5987

CK_ULONG modulusBits = 3072; 5988

CK_BYTE publicExponent[] = { 3 }; 5989


CK_BYTE id[] = {123}; 5991


CK_ATTRIBUTE publicKeyTemplate[] = { 5993

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

{CKA_VERIFY, &true, sizeof(true)}, 5995


{CKA_MODULUS_BITS, &modulusBits, sizeof(modulusBits)}, 5997

{CKA_PUBLIC_EXPONENT, publicExponent, sizeof (publicExponent)} 5998

}; 5999

CK_ATTRIBUTE privateKeyTemplate[] = { 6000


{CKA_PRIVATE, &true, sizeof(true)}, 6002



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

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

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

{CKA_UNWRAP, &true, sizeof(true)} 6008

}; 6009

CK_RV rv; 6010

6011

rv = C_GenerateKeyPair( 6012

hSession, &mechanism, 6013

publicKeyTemplate, 5, 6014

privateKeyTemplate, 8, 6015

&hPublicKey, &hPrivateKey); 6016

if (rv == CKR_OK) { 6017

. 6018

. 6019

} 6020


5.18.3 C_WrapKey 6021

CK_DECLARE_FUNCTION(CK_RV, C_WrapKey)( 6022 CK_SESSION_HANDLE hSession, 6023 CK_MECHANISM_PTR pMechanism, 6024 CK_OBJECT_HANDLE hWrappingKey, 6025 CK_OBJECT_HANDLE hKey, 6026 CK_BYTE_PTR pWrappedKey, 6027 CK_ULONG_PTR pulWrappedKeyLen 6028 ); 6029

C_WrapKey wraps (i.e., encrypts) a private or secret key. hSession is the session’s handle; pMechanism 6030 points to the wrapping mechanism; hWrappingKey is the handle of the wrapping key; hKey is the handle 6031 of the key to be wrapped; pWrappedKey points to the location that receives the wrapped key; and 6032 pulWrappedKeyLen points to the location that receives the length of the wrapped key. 6033

C_WrapKey uses the convention described in Section 5.2 on producing output. 6034

The CKA_WRAP attribute of the wrapping key, which indicates whether the key supports wrapping, 6035 MUST be CK_TRUE. The CKA_EXTRACTABLE attribute of the key to be wrapped MUST also be 6036

CK_TRUE. 6037

If the key to be wrapped cannot be wrapped for some token-specific reason, despite its having its 6038 CKA_EXTRACTABLE attribute set to CK_TRUE, then C_WrapKey fails with error code 6039 CKR_KEY_NOT_WRAPPABLE. If it cannot be wrapped with the specified wrapping key and mechanism 6040 solely because of its length, then C_WrapKey fails with error code CKR_KEY_SIZE_RANGE. 6041

C_WrapKey can be used in the following situations: 6042

To wrap any secret key with a public key that supports encryption and decryption. 6043

To wrap any secret key with any other secret key. Consideration MUST be given to key size and 6044 mechanism strength or the token may not allow the operation. 6045

To wrap a private key with any secret key. 6046

Of course, tokens vary in which types of keys can actually be wrapped with which mechanisms. 6047

To partition the wrapping keys so they can only wrap a subset of extractable keys the attribute 6048 CKA_WRAP_TEMPLATE can be used on the wrapping key to specify an attribute set that will be 6049 compared against the attributes of the key to be wrapped. If all attributes match according to the 6050 C_FindObject rules of attribute matching then the wrap will proceed. The value of this attribute is an 6051 attribute template and the size is the number of items in the template times the size of CK_ATTRIBUTE. If 6052 this attribute is not supplied then any template is acceptable. If an attribute is not present, it will not be 6053 checked. If any attribute mismatch occurs on an attempt to wrap a key then the function SHALL return 6054 CKR_KEY_HANDLE_INVALID. 6055

Return Values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, 6056 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 6057 CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, 6058 CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_HANDLE_INVALID, 6059 CKR_KEY_NOT_WRAPPABLE, CKR_KEY_SIZE_RANGE, CKR_KEY_UNEXTRACTABLE, 6060 CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, 6061 CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, 6062 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, 6063 CKR_WRAPPING_KEY_HANDLE_INVALID, CKR_WRAPPING_KEY_SIZE_RANGE, 6064 CKR_WRAPPING_KEY_TYPE_INCONSISTENT. 6065

Example: 6066


CK_OBJECT_HANDLE hWrappingKey, hKey; 6068


CKM_DES3_ECB, NULL_PTR, 0 6070


}; 6071

CK_BYTE wrappedKey[8]; 6072

CK_ULONG ulWrappedKeyLen; 6073

CK_RV rv; 6074

6075

. 6076

. 6077

ulWrappedKeyLen = sizeof(wrappedKey); 6078

rv = C_WrapKey( 6079


hWrappingKey, hKey, 6081

wrappedKey, &ulWrappedKeyLen); 6082

if (rv == CKR_OK) { 6083

. 6084

. 6085

} 6086

5.18.4 C_UnwrapKey 6087

CK_DECLARE_FUNCTION(CK_RV, C_UnwrapKey)( 6088 CK_SESSION_HANDLE hSession, 6089 CK_MECHANISM_PTR pMechanism, 6090 CK_OBJECT_HANDLE hUnwrappingKey, 6091 CK_BYTE_PTR pWrappedKey, 6092 CK_ULONG ulWrappedKeyLen, 6093 CK_ATTRIBUTE_PTR pTemplate, 6094 CK_ULONG ulAttributeCount, 6095 CK_OBJECT_HANDLE_PTR phKey 6096 ); 6097

C_UnwrapKey unwraps (i.e. decrypts) a wrapped key, creating a new private key or secret key object. 6098 hSession is the session’s handle; pMechanism points to the unwrapping mechanism; hUnwrappingKey is 6099 the handle of the unwrapping key; pWrappedKey points to the wrapped key; ulWrappedKeyLen is the 6100 length of the wrapped key; pTemplate points to the template for the new key; ulAttributeCount is the 6101 number of attributes in the template; phKey points to the location that receives the handle of the 6102 recovered key. 6103

The CKA_UNWRAP attribute of the unwrapping key, which indicates whether the key supports 6104 unwrapping, MUST be CK_TRUE. 6105

The new key will have the CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, and the 6106 CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE. The CKA_EXTRACTABLE attribute is by 6107

default set to CK_TRUE. 6108

Some mechanisms may modify, or attempt to modify. the contents of the pMechanism structure at the 6109 same time that the key is unwrapped. 6110

If a call to C_UnwrapKey cannot support the precise template supplied to it, it will fail and return without 6111

creating any key object. 6112

The key object created by a successful call to C_UnwrapKey will have its CKA_LOCAL attribute set to 6113 CK_FALSE. In addition, the object created will have a value for CKA_UNIQUE_ID generated and 6114 assigned (See Section 4.4.1). 6115

To partition the unwrapping keys so they can only unwrap a subset of keys the attribute 6116 CKA_UNWRAP_TEMPLATE can be used on the unwrapping key to specify an attribute set that will be 6117


added to attributes of the key to be unwrapped. If the attributes do not conflict with the user supplied 6118 attribute template, in ‘pTemplate’, then the unwrap will proceed. The value of this attribute is an attribute 6119 template and the size is the number of items in the template times the size of CK_ATTRIBUTE. If this 6120 attribute is not present on the unwrapping key then no additional attributes will be added. If any attribute 6121 conflict occurs on an attempt to unwrap a key then the function SHALL return 6122 CKR_TEMPLATE_INCONSISTENT. 6123

Return values: CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, 6124 CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, 6125 CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, 6126 CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, 6127 CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, CKR_FUNCTION_CANCELED, 6128 CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, 6129 CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, 6130 CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, 6131 CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, 6132 CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, 6133 CKR_UNWRAPPING_KEY_HANDLE_INVALID, CKR_UNWRAPPING_KEY_SIZE_RANGE, 6134 CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT, CKR_USER_NOT_LOGGED_IN, 6135 CKR_WRAPPED_KEY_INVALID, CKR_WRAPPED_KEY_LEN_RANGE. 6136

Example: 6137


CK_OBJECT_HANDLE hUnwrappingKey, hKey; 6139


CKM_DES3_ECB, NULL_PTR, 0 6141

}; 6142

CK_BYTE wrappedKey[8] = {...}; 6143








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

}; 6152

CK_RV rv; 6153

6154

. 6155

. 6156

rv = C_UnwrapKey( 6157

hSession, &mechanism, hUnwrappingKey, 6158

wrappedKey, sizeof(wrappedKey), template, 4, &hKey); 6159

if (rv == CKR_OK) { 6160

. 6161

. 6162

} 6163


5.18.5 C_DeriveKey 6164

CK_DECLARE_FUNCTION(CK_RV, C_DeriveKey)( 6165 CK_SESSION_HANDLE hSession, 6166 CK_MECHANISM_PTR pMechanism, 6167 CK_OBJECT_HANDLE hBaseKey, 6168 CK_ATTRIBUTE_PTR pTemplate, 6169 CK_ULONG ulAttributeCount, 6170 CK_OBJECT_HANDLE_PTR phKey 6171 ); 6172

C_DeriveKey derives a key from a base key, creating a new key object. hSession is the session’s 6173 handle; pMechanism points to a structure that specifies the key derivation mechanism; hBaseKey is the 6174 handle of the base key; pTemplate points to the template for the new key; ulAttributeCount is the number 6175 of attributes in the template; and phKey points to the location that receives the handle of the derived key. 6176

The values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE, and 6177 CKA_NEVER_EXTRACTABLE attributes for the base key affect the values that these attributes can hold 6178 for the newly-derived key. See the description of each particular key-derivation mechanism in Section 6179 5.21.2 for any constraints of this type. 6180

If a call to C_DeriveKey cannot support the precise template supplied to it, it will fail and return without 6181

creating any key object. 6182

The key object created by a successful call to C_DeriveKey will have its CKA_LOCAL attribute set to 6183 CK_FALSE. In addition, the object created will have a value for CKA_UNIQUE_ID generated and 6184 assigned (See Section 4.4.1). 6185

To partition the derivation keys so they can only derive a subset of keys the attribute 6186 CKA_DERIVE_TEMPLATE can be used on the derivation keys to specify an attribute set that will be 6187 added to attributes of the key to be derived. If the attributes do not conflict with the user supplied attribute 6188 template, in ‘pTemplate’, then the derivation will proceed. The value of this attribute is an attribute 6189 template and the size is the number of items in the template times the size of CK_ATTRIBUTE. If this 6190 attribute is not present on the base derivation keys then no additional attributes will be added. If any 6191 attribute conflict occurs on an attempt to derive a key then the function SHALL return 6192 CKR_TEMPLATE_INCONSISTENT. 6193

Return values: CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, 6194 CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, 6195 CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, 6196 CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, 6197 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 6198 CKR_HOST_MEMORY, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, 6199 CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, 6200 CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, 6201 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, 6202 CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT, 6203 CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN. 6204

Example: 6205


CK_OBJECT_HANDLE hPublicKey, hPrivateKey, hKey; 6207

CK_MECHANISM keyPairMechanism = { 6208

CKM_DH_PKCS_KEY_PAIR_GEN, NULL_PTR, 0 6209

}; 6210

CK_BYTE prime[] = {...}; 6211

CK_BYTE base[] = {...}; 6212

CK_BYTE publicValue[128]; 6213


CK_BYTE otherPublicValue[128]; 6214


CKM_DH_PKCS_DERIVE, otherPublicValue, sizeof(otherPublicValue) 6216

}; 6217


{CKA_VALUE, &publicValue, sizeof(publicValue)} 6219

}; 6220




CK_ATTRIBUTE publicKeyTemplate[] = { 6224

{CKA_PRIME, prime, sizeof(prime)}, 6225

{CKA_BASE, base, sizeof(base)} 6226

}; 6227

CK_ATTRIBUTE privateKeyTemplate[] = { 6228

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

}; 6230

CK_ATTRIBUTE derivedKeyTemplate[] = { 6231




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

}; 6236

CK_RV rv; 6237

6238

. 6239

. 6240

rv = C_GenerateKeyPair( 6241

hSession, &keyPairMechanism, 6242

publicKeyTemplate, 2, 6243

privateKeyTemplate, 1, 6244

&hPublicKey, &hPrivateKey); 6245

if (rv == CKR_OK) { 6246

rv = C_GetAttributeValue(hSession, hPublicKey, template, 1); 6247

if (rv == CKR_OK) { 6248

/* Put other guy’s public value in otherPublicValue */ 6249

. 6250

. 6251

rv = C_DeriveKey( 6252


hPrivateKey, derivedKeyTemplate, 4, &hKey); 6254

if (rv == CKR_OK) { 6255

. 6256


. 6257

} 6258

} 6259

} 6260

5.19 Random number generation functions 6261

Cryptoki provides the following functions for generating random numbers: 6262

5.19.1 C_SeedRandom 6263

CK_DECLARE_FUNCTION(CK_RV, C_SeedRandom)( 6264 CK_SESSION_HANDLE hSession, 6265 CK_BYTE_PTR pSeed, 6266 CK_ULONG ulSeedLen 6267 ); 6268

C_SeedRandom mixes additional seed material into the token’s random number generator. hSession is 6269 the session’s handle; pSeed points to the seed material; and ulSeedLen is the length in bytes of the seed 6270

material. 6271

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 6272 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 6273 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 6274 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_ACTIVE, 6275 CKR_RANDOM_SEED_NOT_SUPPORTED, CKR_RANDOM_NO_RNG, CKR_SESSION_CLOSED, 6276 CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN. 6277

Example: see C_GenerateRandom. 6278

5.19.2 C_GenerateRandom 6279

CK_DECLARE_FUNCTION(CK_RV, C_GenerateRandom)( 6280


CK_BYTE_PTR pRandomData, 6282

CK_ULONG ulRandomLen 6283

); 6284

C_GenerateRandom generates random or pseudo-random data. hSession is the session’s handle; 6285 pRandomData points to the location that receives the random data; and ulRandomLen is the length in 6286

bytes of the random or pseudo-random data to be generated. 6287

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, 6288 CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, 6289 CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, 6290 CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_ACTIVE, CKR_RANDOM_NO_RNG, 6291 CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN. 6292

Example: 6293


CK_BYTE seed[] = {...}; 6295

CK_BYTE randomData[] = {...}; 6296

CK_RV rv; 6297

6298

. 6299

. 6300


rv = C_SeedRandom(hSession, seed, sizeof(seed)); 6301

if (rv != CKR_OK) { 6302

. 6303

. 6304

} 6305

rv = C_GenerateRandom(hSession, randomData, sizeof(randomData)); 6306

if (rv == CKR_OK) { 6307

. 6308

. 6309

} 6310

5.20 Parallel function management functions 6311

Cryptoki provides the following functions for managing parallel execution of cryptographic functions. 6312 These functions exist only for backwards compatibility. 6313

5.20.1 C_GetFunctionStatus 6314

CK_DECLARE_FUNCTION(CK_RV, C_GetFunctionStatus)( 6315 CK_SESSION_HANDLE hSession 6316 ); 6317

In previous versions of Cryptoki, C_GetFunctionStatus obtained the status of a function running in 6318 parallel with an application. Now, however, C_GetFunctionStatus is a legacy function which should 6319

simply return the value CKR_FUNCTION_NOT_PARALLEL. 6320

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_FUNCTION_FAILED, 6321 CKR_FUNCTION_NOT_PARALLEL, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, 6322 CKR_SESSION_HANDLE_INVALID, CKR_SESSION_CLOSED. 6323

5.20.2 C_CancelFunction 6324

CK_DECLARE_FUNCTION(CK_RV, C_CancelFunction)( 6325 CK_SESSION_HANDLE hSession 6326 ); 6327

In previous versions of Cryptoki, C_CancelFunction cancelled a function running in parallel with an 6328 application. Now, however, C_CancelFunction is a legacy function which should simply return the value 6329

CKR_FUNCTION_NOT_PARALLEL. 6330

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_FUNCTION_FAILED, 6331 CKR_FUNCTION_NOT_PARALLEL, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, 6332 CKR_SESSION_HANDLE_INVALID, CKR_SESSION_CLOSED. 6333

5.21 Callback functions 6334

Cryptoki sessions can use function pointers of type CK_NOTIFY to notify the application of certain 6335

events. 6336

5.21.1 Surrender callbacks 6337

Cryptographic functions (i.e., any functions falling under one of these categories: encryption functions; 6338 decryption functions; message digesting functions; signing and MACing functions; functions for verifying 6339 signatures and MACs; dual-purpose cryptographic functions; key management functions; random number 6340 generation functions) executing in Cryptoki sessions can periodically surrender control to the application 6341 who called them if the session they are executing in had a notification callback function associated with it 6342


when it was opened. They do this by calling the session’s callback with the arguments (hSession, 6343 CKN_SURRENDER, pApplication), where hSession is the session’s handle and pApplication was 6344 supplied to C_OpenSession when the session was opened. Surrender callbacks should return either the 6345 value CKR_OK (to indicate that Cryptoki should continue executing the function) or the value 6346 CKR_CANCEL (to indicate that Cryptoki should abort execution of the function). Of course, before 6347 returning one of these values, the callback function can perform some computation, if desired. 6348

A typical use of a surrender callback might be to give an application user feedback during a lengthy key 6349 pair generation operation. Each time the application receives a callback, it could display an additional “.” 6350 to the user. It might also examine the keyboard’s activity since the last surrender callback, and abort the 6351 key pair generation operation (probably by returning the value CKR_CANCEL) if the user hit <ESCAPE>. 6352

A Cryptoki library is not required to make any surrender callbacks. 6353

5.21.2 Vendor-defined callbacks 6354

Library vendors can also define additional types of callbacks. Because of this extension capability, 6355 application-supplied notification callback routines should examine each callback they receive, and if they 6356 are unfamiliar with the type of that callback, they should immediately give control back to the library by 6357 returning with the value CKR_OK. 6358


6 Mechanisms 6359

6.1 RSA 6360

Table 32, Mechanisms vs. Functions 6361

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_SHA224_RSA_PKCS

CKM_SHA256_RSA_PKCS

CKM_SHA384_RSA_PKCS

CKM_SHA512_RSA_PKCS

CKM_SHA1_RSA_PKCS_PSS





CKM_SHA1_RSA_X9_31

CKM_RSA_PKCS_TPM_1_1 2

CKM_RSA_PKCS_OAEP_TPM_1_1 2

CKM_SHA3_224_RSA_PKCS




CKM_SHA3_224_RSA_PKCS_PSS





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

Mechanisms: 6365

CKM_RSA_PKCS_KEY_PAIR_GEN 6366

CKM_RSA_PKCS 6367


CKM_RSA_9796 6368

CKM_RSA_X_509 6369

CKM_MD2_RSA_PKCS 6370

CKM_MD5_RSA_PKCS 6371

CKM_SHA1_RSA_PKCS 6372





CKM_RIPEMD128_RSA_PKCS 6377

CKM_RIPEMD160_RSA_PKCS 6378

CKM_RSA_PKCS_OAEP 6379

CKM_RSA_X9_31_KEY_PAIR_GEN 6380

CKM_RSA_X9_31 6381

CKM_SHA1_RSA_X9_31 6382

CKM_RSA_PKCS_PSS 6383

CKM_SHA1_RSA_PKCS_PSS 6384





CKM_RSA_PKCS_TPM_1_1 6389

CKM_RSA_PKCS_OAEP_TPM_1_1 6390

CKM_RSA_AES_KEY_WRAP 6391

CKM_SHA3_224_RSA_PKCS 6392




CKM_SHA3_224_RSA_PKCS_PSS 6396




6400

6.1.2 RSA public key objects 6401

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

Table 33, RSA Public Key Object Attributes 6405



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


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

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

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY; 6410


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


CK_BYTE exponent[] = {...}; 6414



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



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




{CKA_PUBLIC_EXPONENT, exponent, sizeof(exponent)} 6424

}; 6425

6.1.3 RSA private key objects 6426

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

Table 34, RSA Private Key Object Attributes 6430


CKA_MODULUS1,4,6

Big integer Modulus n

CKA_PUBLIC_EXPONENT1,4,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


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

Tokens vary in what they actually store for RSA private keys. Some tokens store all of the above 6434 attributes, which can assist in performing rapid RSA computations. Other tokens might store only the 6435 CKA_MODULUS and CKA_PRIVATE_EXPONENT values. Effective with version 2.40, tokens MUST 6436


also store CKA_PUBLIC_EXPONENT. This permits the retrieval of sufficient data to reconstitute the 6437

associated public key. 6438

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

for an RSA private key. 6451

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

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

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

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY; 6461


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


CK_BYTE id[] = {123}; 6465


CK_BYTE publicExponent[] = {...}; 6467

CK_BYTE privateExponent[] = {...}; 6468

CK_BYTE prime1[] = {...}; 6469

CK_BYTE prime2[] = {...}; 6470

CK_BYTE exponent1[] = {...}; 6471

CK_BYTE exponent2[] = {...}; 6472

CK_BYTE coefficient[] = {...}; 6473










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



{CKA_PUBLIC_EXPONENT, publicExponent, 6486

Formatted: Font: Bold

Formatted: Font: Bold


sizeof(publicExponent)}, 6487

{CKA_PRIVATE_EXPONENT, privateExponent, 6488

sizeof(privateExponent)}, 6489

{CKA_PRIME_1, prime1, sizeof(prime1)}, 6490

{CKA_PRIME_2, prime2, sizeof(prime2)}, 6491

{CKA_EXPONENT_1, exponent1, sizeof(exponent1)}, 6492

{CKA_EXPONENT_2, exponent2, sizeof(exponent2)}, 6493

{CKA_COEFFICIENT, coefficient, sizeof(coefficient)} 6494

}; 6495

6.1.4 PKCS #1 RSA key pair generation 6496

The PKCS #1 RSA key pair generation mechanism, denoted CKM_RSA_PKCS_KEY_PAIR_GEN, is a 6497

key pair generation mechanism based on the RSA public-key cryptosystem, as defined in PKCS #1. 6498

It does not have a parameter. 6499

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

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

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

6.1.5 X9.31 RSA key pair generation 6521

The X9.31 RSA key pair generation mechanism, denoted CKM_RSA_X9_31_KEY_PAIR_GEN, is a key 6522

pair generation mechanism based on the RSA public-key cryptosystem, as defined in X9.31. 6523


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

template for the public key. 6527

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_MODULUS, and 6528 CKA_PUBLIC_EXPONENT attributes to the new public key. It contributes the CKA_CLASS and 6529 CKA_KEY_TYPE attributes to the new private key; it may also contribute some of the following attributes 6530 to the new private key: CKA_MODULUS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, 6531 CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT_2, CKA_COEFFICIENT. 6532 Other attributes supported by the RSA public and private key types (specifically, the flags indicating which 6533 functions the keys support) may also be specified in the templates for the keys, or else are assigned 6534 default initial values. Unlike the CKM_RSA_PKCS_KEY_PAIR_GEN mechanism, this mechanism is 6535


guaranteed to generate p and q values, CKA_PRIME_1 and CKA_PRIME_2 respectively, that meet the 6536

strong primes requirement of X9.31. 6537

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 6538

specify the supported range of RSA modulus sizes, in bits. 6539

6.1.6 PKCS #1 v1.5 RSA 6540

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

This mechanism does not have a parameter. 6547

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

to the recovered key during unwrapping; other attributes must be specified in the template. 6554

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

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

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

2 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.

6559 2 Data length, signature length.

6560


6.1.7 PKCS #1 RSA OAEP mechanism parameters 6563

CK_RSA_PKCS_MGF_TYPE; CK_RSA_PKCS_MGF_TYPE_PTR 6564

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

typedef CK_ULONG CK_RSA_PKCS_MGF_TYPE; 6568

6569


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

Table 36, PKCS #1 Mask Generation Functions 6571

Source Identifier Value

CKG_MGF1_SHA1 0x00000001UL





CKG_MGF1_SHA3_224 0x00000006UL




CK_RSA_PKCS_MGF_TYPE_PTR is a pointer to a CK_RSA_PKCS_ MGF_TYPE. 6572

CK_RSA_PKCS_OAEP_SOURCE_TYPE; 6573

CK_RSA_PKCS_OAEP_SOURCE_TYPE_PTR 6574

CK_RSA_PKCS_OAEP_SOURCE_TYPE is used to indicate the source of the encoding parameter 6575

when formatting a message block for the PKCS #1 OAEP encryption scheme. It is defined as follows: 6576

typedef CK_ULONG CK_RSA_PKCS_OAEP_SOURCE_TYPE; 6577

6578

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

Table 37, PKCS #1 RSA OAEP: Encoding parameter sources 6582

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 6583 CK_RSA_PKCS_OAEP_SOURCE_TYPE. 6584

CK_RSA_PKCS_OAEP_PARAMS; CK_RSA_PKCS_OAEP_PARAMS_PTR 6585

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

typedef struct CK_RSA_PKCS_OAEP_PARAMS { 6588

CK_MECHANISM_TYPE hashAlg; 6589

CK_RSA_PKCS_MGF_TYPE mgf; 6590

CK_RSA_PKCS_OAEP_SOURCE_TYPE source; 6591

CK_VOID_PTR pSourceData; 6592

CK_ULONG ulSourceDataLen; 6593

} CK_RSA_PKCS_OAEP_PARAMS; 6594

6595



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

mgf mask generation function to use on the encoded block 6599

source source of the encoding parameter 6600

pSourceData data used as the input for the encoding parameter source 6601

ulSourceDataLen length of the encoding parameter source input 6602

CK_RSA_PKCS_OAEP_PARAMS_PTR is a pointer to a CK_RSA_PKCS_OAEP_PARAMS. 6603

6604

6.1.8 PKCS #1 RSA OAEP 6605

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

It has a parameter, a CK_RSA_PKCS_OAEP_PARAMS structure. 6609

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

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

Table 38, PKCS #1 RSA OAEP: Key And Data Length 6621

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


6622



6.1.9 PKCS #1 RSA PSS mechanism parameters 6625

CK_RSA_PKCS_PSS_PARAMS; CK_RSA_PKCS_PSS_PARAMS_PTR 6626

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

typedef struct CK_RSA_PKCS_PSS_PARAMS { 6629

CK_MECHANISM_TYPE hashAlg; 6630

CK_RSA_PKCS_MGF_TYPE mgf; 6631

CK_ULONG sLen; 6632

} CK_RSA_PKCS_PSS_PARAMS; 6633


6634


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

mgf mask generation function to use on the encoded block 6642

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

CK_RSA_PKCS_PSS_PARAMS_PTR is a pointer to a CK_RSA_PKCS_PSS_PARAMS. 6645

6.1.10 PKCS #1 RSA PSS 6646

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

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

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

is the length in bytes of the RSA. 6657

Table 39, PKCS #1 RSA PSS: Key And Data Length 6658


C_Sign1 RSA private key hLen k

C_Verify1 RSA public key hLen, k N/A



6660


6.1.11 ISO/IEC 9796 RSA 6663

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

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

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

A signature is converted from a bit string to a byte string by padding the bit string on the left with 0 to 6673 7 zero bits so that the resulting length in bits is a multiple of 8, and converting the resulting bit string 6674


as above; it is converted from a byte string to a bit string by converting the byte string as above, and 6675 removing bits from the left so that the resulting length in bits is the same as that of the RSA modulus. 6676


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

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


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

2 N/A

C_VerifyRecover RSA public key k k/2



6682



6.1.12 X.509 (raw) RSA 6685

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

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


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

Unfortunately, X.509 does not specify how to perform padding for RSA encryption. For this mechanism, 6701 padding should be performed by prepending plaintext data with 0-valued bytes. In effect, to encrypt the 6702

sequence of plaintext bytes b1 b2 … bn (n k), Cryptoki forms P=2n-1

b1+2n-2

b2+…+bn. This number must 6703 be less than the RSA modulus. The k-byte ciphertext (k is the length in bytes of the RSA modulus) is 6704 produced by raising P to the RSA public exponent modulo the RSA modulus. Decryption of a k-byte 6705 ciphertext C is accomplished by raising C to the RSA private exponent modulo the RSA modulus, and 6706 returning the resulting value as a sequence of exactly k bytes. If the resulting plaintext is to be used to 6707 produce an unwrapped key, then however many bytes are specified in the template for the length of the 6708 key are taken from the end of this sequence of bytes. 6709

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

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


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

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


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

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



6721



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

6.1.13 ANSI X9.31 RSA 6726

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

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

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

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

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


Constraints on key types and the length of input and output data are summarized in the following table. 6743 In the table, k is the length in bytes of the RSA modulus. For all operations, the k value must be at least 6744

128 and a multiple of 32 as specified in ANSI X9.31. 6745

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


Output length

C_Sign1 RSA private key k-2 k

C_Verify1 RSA public key k-2, k

2 N/A


6747


2 Data length, signature length. 6748



6.1.14 PKCS #1 v1.5 RSA signature with MD2, MD5, SHA-1, SHA-256, SHA-6751

384, SHA-512, RIPE-MD 128 or RIPE-MD 160 6752

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

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

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

The PKCS #1 v1.5 RSA signature with RIPEMD-128 or RIPEMD-160, denoted 6768 CKM_RIPEMD128_RSA_PKCS and CKM_RIPEMD160_RSA_PKCS respectively, perform the same 6769

operations using the RIPE-MD 128 and RIPE-MD 160 hash functions. 6770

None of these mechanisms has a parameter. 6771

Constraints on key types and the length of the data for these mechanisms are summarized in the 6772 following table. In the table, k is the length in bytes of the RSA modulus. For the PKCS #1 v1.5 RSA 6773 signature with MD2 and PKCS #1 v1.5 RSA signature with MD5 mechanisms, k must be at least 27; for 6774 the PKCS #1 v1.5 RSA signature with SHA-1 mechanism, k must be at least 31, and so on for other 6775

underlying hash functions, where the minimum is always 11 bytes more than the length of the hash value. 6776

Table 43, PKCS #1 v1.5 RSA Signatures with Various Hash Functions: Key And Data Length 6777

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.

6778

For these mechanisms, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO 6779

structure specify the supported range of RSA modulus sizes, in bits. 6780

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

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

function. 6784

6.1.16 PKCS #1 RSA PSS signature with SHA-224 6785

The PKCS #1 RSA PSS signature with SHA-224 mechanism, denoted CKM_SHA224_RSA_PKCS_PSS, 6786 performs similarly as the other CKM_SHAX_RSA_ PKCS_PSS mechanisms but uses the SHA-224 hash 6787

function. 6788


6.1.17 PKCS #1 RSA PSS signature with SHA-1, SHA-256, SHA-384 or SHA-6789

512 6790

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

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

384 and SHA-512 hash functions. 6798

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

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

is the length in bytes of the RSA modulus. 6804

Table 44, PKCS #1 RSA PSS Signatures with Various Hash Functions: Key And Data Length 6805


C_Sign RSA private key any k

C_Verify RSA public key any, k2 N/A


6806



6.1.18 PKCS #1 v1.5 RSA signature with SHA3 6809

The PKCS #1 v1.5 RSA signature with SHA3-224, SHA3-256, SHA3-384, SHA3-512 mechanisms, 6810 denoted CKM_SHA3_224_RSA_PKCS, CKM_SHA3_256_RSA_PKCS, CKM_SHA3_384_RSA_PKCS, 6811 and CKM_SHA3_512_RSA_PKCS respectively, performs similarly as the other 6812 CKM_SHAX_RSA_PKCS mechanisms but uses the corresponding SHA3 hash functions. 6813

6.1.19 PKCS #1 RSA PSS signature with SHA3 6814

The PKCS #1 RSA PSS signature with SHA3-224, SHA3-256, SHA3-384, SHA3-512 mechanisms, 6815 denoted CKM_SHA3_224_RSA_PKCS_PSS, CKM_SHA3_256_RSA_PKCS_PSS, 6816 CKM_SHA3_384_RSA_PKCS_PSS, and CKM_SHA3_512_RSA_PKCS_PSS respectively, performs 6817 similarly as the other CKM_SHAX_RSA_PKCS_PSS mechanisms but uses the corresponding SHA-3 6818

hash functions. 6819

6.1.20 ANSI X9.31 RSA signature with SHA-1 6820

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


Constraints on key types and the length of the data for these mechanisms are summarized in the 6825 following table. In the table, k is the length in bytes of the RSA modulus. For all operations, the k value 6826

must be at least 128 and a multiple of 32 as specified in ANSI X9.31. 6827

Table 45, ANSI X9.31 RSA Signatures with SHA-1: Key And Data Length 6828



C_Sign RSA private key any k

C_Verify RSA public key any, k2 N/A


6829

For these mechanisms, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO 6830

structure specify the supported range of RSA modulus sizes, in bits. 6831

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

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

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



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

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


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


6854

6855


6.1.22 TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP 6858

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


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



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

length in bytes of the RSA modulus. 6881

Table 47, TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP: Key And Data Length 6882


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


6883



6.1.23 RSA AES KEY WRAP 6886

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

It has a parameter, a CK_RSA_AES_KEY_WRAP_PARAMS structure. 6890

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

key. 6892

- A temporary AES key is used for wrapping the target key using 6893

CKM_AES_KEY_WRAP_KWP mechanism. 6894

- The temporary AES key is wrapped with the wrapping RSA key using 6895

CKM_RSA_PKCS_OAEP mechanism. 6896

6897

For wrapping, the mechanism - 6898

Generates a temporary random AES key of ulAESKeyBits length. This key is not accessible to 6899 the user - no handle is returned. 6900

Wraps the AES key with the wrapping RSA key using CKM_RSA_PKCS_OAEP with parameters 6901 of OAEPParams. 6902

Wraps the target key with the temporary AES key using CKM_AES_KEY_WRAP_KWP. 6903

Zeroizes the temporary AES key 6904


Concatenates two wrapped keys and outputs the concatenated blob. The first is the wrapped 6905 AES key, and the second is the wrapped target key. 6906

6907

The private target key will be encoded as defined in section 2.7.6.7. 6908

6909

The use of Attributes in the PrivateKeyInfo structure is OPTIONAL. In case of conflicts between the 6910

object attribute template, and Attributes in the PrivateKeyInfo structure, an error should be thrown 6911

6912

For unwrapping, the mechanism - 6913

Splits the input into two parts. The first is the wrapped AES key, and the second is the wrapped 6914 target key. The length of the first part is equal to the length of the unwrapping RSA key. 6915

Un-wraps the temporary AES key from the first part with the private RSA key using 6916 CKM_RSA_PKCS_OAEP with parameters of OAEPParams. 6917

Un-wraps the target key from the second part with the temporary AES key using 6918 CKM_AES_KEY_WRAP_KWP. 6919

Zeroizes the temporary AES key. 6920

Returns the handle to the newly unwrapped target key. 6921

Table 48, CKM_RSA_AES_KEY_WRAP Mechanisms vs. Functions 6922

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

6.1.24 RSA AES KEY WRAP mechanism parameters 6923

CK_RSA_AES_KEY_WRAP_PARAMS; CK_RSA_AES_KEY_WRAP_PARAMS_PTR 6924

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

typedef struct CK_RSA_AES_KEY_WRAP_PARAMS { 6927

CK_ULONG ulAESKeyBits; 6928

CK_RSA_PKCS_OAEP_PARAMS_PTR pOAEPParams; 6929

} CK_RSA_AES_KEY_WRAP_PARAMS; 6930

6931


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

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

CK_RSA_AES_KEY_WRAP_PARAMS_PTR is a pointer to a CK_RSA_AES_KEY_WRAP_PARAMS. 6938


6.1.25 FIPS 186-4 6939

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

6.2 DSA 6942

Table 49, DSA Mechanisms vs. Functions 6943

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_PROBABILISTIC_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

CKM_DSA_SHA3_224

CKM_DSA_SHA3_256

CKM_DSA_SHA3_384

CKM_DSA_SHA3_512


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

Mechanisms: 6947

CKM_DSA_KEY_PAIR_GEN 6948

CKM_DSA 6949

CKM_DSA_SHA1 6950

CKM_DSA_SHA224 6951

CKM_DSA_SHA256 6952

CKM_DSA_SHA384 6953

CKM_DSA_SHA512 6954

CKM_DSA_SHA3_224 6955





CKM_DSA_PARAMETER_GEN 6959

CKM_DSA_PROBABILISTIC_PARAMETER_GEN 6960

CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN 6961

CKM_DSA_FIPS_G_GEN 6962

6963

CK_DSA_PARAMETER_GEN_PARAM 6964

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

CK_DSA_PARAMETER_GEN_PARAM_PTR is a pointer to a CK_DSA_PARAMETER_GEN_PARAM. 6967

6968

typedef struct CK_DSA_PARAMETER_GEN_PARAM { 6969

CK_MECHANISM_TYPE hash; 6970

CK_BYTE_PTR pSeed; 6971

CK_ULONG ulSeedLen; 6972

CK_ULONG ulIndex; 6973

} CK_DSA_PARAMETER_GEN_PARAM; 6974

6975


hash Mechanism value for the base hash used in PQG generation, Valid 6977 values are CKM_SHA_1, CKM_SHA224, CKM_SHA256, 6978 CKM_SHA384, CKM_SHA512. 6979

pSeed Seed value used to generate PQ and G. This value is returned by 6980 CKM_DSA_PROBABILISTIC_PARAMETER_GEN, 6981 CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN, and passed 6982 into CKM_DSA_FIPS_G_GEN. 6983

ulSeedLen Length of seed value. 6984

ulIndex Index value for generating G. Input for CKM_DSA_FIPS_G_GEN. 6985 Ignored by CKM_DSA_PROBABILISTIC_PARAMETER_GEN and 6986 CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN. 6987

6.2.2 DSA public key objects 6988

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

Table 50, DSA Public Key Object Attributes 6992


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


The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA domain 6994

parameters”. See FIPS PUB 186-4 for more information on DSA keys. 6995

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



CK_KEY_TYPE keyType = CKK_DSA; 6998

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

CK_BYTE prime[] = {...}; 7000

CK_BYTE subprime[] = {...}; 7001

CK_BYTE base[] = {...}; 7002

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








{CKA_SUBPRIME, subprime, sizeof(subprime)}, 7011

{CKA_BASE, base, sizeof(base)}, 7012


}; 7014

7015

6.2.3 DSA Key Restrictions 7016

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

Prime: 1024 bits, Subprime: 160 7018




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

6.2.4 DSA private key objects 7025

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

Table 51, DSA Private Key Object Attributes 7029


CKA_PRIME1,4,6


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



parameters”. See FIPS PUB 186-4 for more information on DSA keys. 7032

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

domain parameters for the pair are specified in the template for the DSA public key. 7035


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



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


CK_BYTE id[] = {123}; 7041

CK_BYTE prime[] = {...}; 7042


CK_BYTE base[] = {...}; 7044

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















}; 7060

6.2.5 DSA domain parameter objects 7061

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

Table 52, DSA Domain Parameter Object Attributes 7065


CKA_PRIME1,4


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.



parameters”. See FIPS PUB 186-4 for more information on DSA domain parameters. 7068

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

If CKA_PRIME_BITS is less than or equal to 1024 then CKA_SUBPRIME_BITS shall be 160 bits 7071

If CKA_PRIME_BITS equals 2048 then CKA_SUBPRIME_BITS shall be 224 bits 7072

If CKA_PRIME_BITS equals 3072 then CKA_SUBPRIME_BITS shall be 256 bits 7073

7074

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


CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS; 7076


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

CK_BYTE prime[] = {...}; 7079


CK_BYTE base[] = {...}; 7081










}; 7091

6.2.6 DSA key pair generation 7092

The DSA key pair generation mechanism, denoted CKM_DSA_KEY_PAIR_GEN, is a key pair generation 7093

mechanism based on the Digital Signature Algorithm defined in FIPS PUB 186-2. 7094


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

key. 7098

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


specify the supported range of DSA prime sizes, in bits. 7105

6.2.7 DSA domain parameter generation 7106

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


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

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, 7113 CKA_BASE and CKA_PRIME_BITS attributes to the new object. Other attributes supported by the DSA 7114

domain parameter types may also be specified in the template, or else are assigned default initial values. 7115



6.2.8 DSA probabilistic domain parameter generation 7118

The DSA probabilistic domain parameter generation mechanism, denoted 7119 CKM_DSA_PROBABILISTIC_PARAMETER_GEN, is a domain parameter generation mechanism based 7120


on the Digital Signature Algorithm defined in FIPS PUB 186-4, section Appendix A.1.1 Generation and 7121 Validation of Probable Primes.. 7122

This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash and 7123

returns the seed (pSeed) and the length (ulSeedLen). 7124

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

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



6.2.9 DSA Shawe-Taylor domain parameter generation 7134

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

This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash and 7139

returns the seed (pSeed) and the length (ulSeedLen). 7140

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

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



6.2.10 DSA base domain parameter generation 7150

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

This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash the seed 7154

(pSeed) and the length (ulSeedLen) and the index value. 7155

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

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

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

6.2.11 DSA without hashing 7163

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


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


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

Table 53, DSA: Key And Data Length 7172


C_Sign1 DSA private key 20, 28, 32,

48, or 64 bytes

2*length of subprime

C_Verify1 DSA public key (20, 28, 32,

48, or 64 bytes),

(2*length of subprime)

2

N/A



7174



6.2.12 DSA with SHA-1 7177

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

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



Table 54, DSA with SHA-1: Key And Data Length 7185


C_Sign DSA private key any 2*subprime length

C_Verify DSA public key any, 2*subprime

length2

N/A


7186



6.2.13 FIPS 186-4 7189

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

L = 1024, N = 160 7192

L = 2048, N = 224 7193

L = 2048, N = 256 7194

L = 3072, N = 256 7195

7196


6.2.14 DSA with SHA-224 7197


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







length2

N/A



6.2.15 DSA with SHA-256 7209









length2

N/A


6.2.16 DSA with SHA-384 7219










length2

N/A


6.2.17 DSA with SHA-512 7229









length2

N/A


6.2.18 DSA with SHA3-224 7239

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




Table 59, DSA with SHA3-224: Key And Data Length 7247




length2

N/A




6.2.19 DSA with SHA3-256 7251









length2

N/A


6.2.20 DSA with SHA3-384 7261









length2

N/A


6.2.21 DSA with SHA3-512 7271

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









length2

N/A


7281

6.3 Elliptic Curve 7282

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

The EC cryptosystem developed by the ANSI X9F1 working group was created at a time when EC curves 7285 were always represented in their Weierstrass form. Since that time, new curves represented in Edwards 7286 form (RFC 8032) and Montgomery form (RFC 7748) have become more common. To support these new 7287 curves, the EC cryptosystem in this document has been extended from the original. Additional key 7288 generation mechanisms have been added as well as an additional signature generation mechanism. 7289

7290

Table 63, Elliptic Curve Mechanisms vs. Functions 7291

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_EC_KEY_PAIR_GEN

CKM_EC_KEY_PAIR_GEN_W_EXTRA_BITS

CKM_EC_EDWARDS_KEY_PAIR_GEN

CKM_EC_MONTGOMERY_KEY_PAIR_GEN

CKM_ECDSA 2

CKM_ECDSA_SHA1

CKM_ECDSA_SHA224

CKM_ECDSA_SHA256

CKM_ECDSA_SHA384

CKM_ECDSA_SHA512

CKM_ECDSA_SHA3_224

CKM_ECDSA_SHA3_256

CKM_ECDSA_SHA3_384

CKM_ECDSA_SHA3_512

CKM_EDDSA

CKM_XEDDSA

CKM_ECDH1_DERIVE

CKM_ECDH1_COFACTOR_DERIVE

CKM_ECMQV_DERIVE


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_ECDH_AES_KEY_WRAP

Note: CKM_ECDH_AES_KEY_WRAP is deprecated with PKCS#11 3.1. 7292

7293

Table 64, Mechanism Information Flags 7294

CKF_EC_F_P 0x00100000UL True if the mechanism can be used with EC domain parameters over Fp

CKF_EC_F_2M 0x00200000UL True if the mechanism can be used

with EC domain parameters over F2m

CKF_EC_ECPARAMETERS 0x00400000UL True if the mechanism can be used with EC domain parameters of the choice ecParameters

CKF_EC_OID 0x00800000UL True if the mechanism can be used with EC domain parameters of the choice oId

CKF_EC_UNCOMPRESS 0x01000000UL True if the mechanism can be used with elliptic curve point uncompressed

CKF_EC_COMPRESS 0x02000000UL True if the mechanism can be used with elliptic curve point compressed

CKF_EC_CURVENAME 0x04000000UL True of the mechanism can be used with EC domain parameters of the choice curveName

Note: CKF_EC_NAMEDCURVE is deprecated with PKCS#11 3.00. It is replaced by CKF_EC_OID. 7295

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

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

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

An EC key in Cryptoki contains information about which variety of EC it is suited for. It is preferable that a 7299 Cryptoki library, which can perform EC mechanisms, be capable of performing operations with the two 7300 varieties of EC, however this is not required. The CK_MECHANISM_INFO structure CKF_EC_F_P flag 7301 identifies a Cryptoki library supporting EC keys over Fp whereas the CKF_EC_F_2M flag identifies a 7302

Cryptoki library supporting EC keys over F2m. A Cryptoki library that can perform EC mechanisms must 7303

set either or both of these flags for each EC mechanism. 7304

In these specifications there are also four representation methods to define the domain parameters for an 7305 EC key. Only the ecParameters, the oId and the curveName choices are supported in Cryptoki. The 7306 CK_MECHANISM_INFO structure CKF_EC_ECPARAMETERS flag identifies a Cryptoki library 7307 supporting the ecParameters choice whereas the CKF_EC_OID flag identifies a Cryptoki library 7308 supporting the oId choice, and the CKF_EC_CURVENAME flag identifies a Cryptoki library supporting 7309 the curveName choice. A Cryptoki library that can perform EC mechanisms must set the appropriate 7310

flag(s) for each EC mechanism. 7311

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


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

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

6.3.1 EC Signatures 7327

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

the signature may have a shorter length but must be composed as specified before. 7335

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

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

An EdDSA signature is an octet string of even length which is two times nLen octets, where nLen is 7345 calculated as EdDSA parameter b divided by 8. The signature octets correspond to the concatenation of 7346 the EdDSA values R and S as defined in [RFC 8032], both represented as an octet string of equal length 7347 of nLen bytes in little endian order. 7348


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

Note: CKK_ECDSA is deprecated. It is replaced by CKK_EC. 7352

Mechanisms: 7353

7354

CKM_EC_KEY_PAIR_GEN 7355

CKM_EC_EDWARDS_KEY_PAIR_GEN 7356

CKM_EC_MONTGOMERY_KEY_PAIR_GEN 7357

CKM_ECDSA 7358

CKM_ECDSA_SHA1 7359

CKM_ECDSA_SHA224 7360




CKM_ECDSA_SHA3_224 7364





CKM_EDDSA 7368

CKM_XEDDSA 7369

CKM_ECDH1_DERIVE 7370

CKM_ECDH1_COFACTOR_DERIVE 7371

CKM_ECMQV_DERIVE 7372

CKM_ECDH_AES_KEY_WRAP 7373

7374

CKD_NULL 7375

CKD_SHA1_KDF 7376

CKD_SHA224_KDF 7377

CKD_SHA256_KDF 7378

CKD_SHA384_KDF 7379

CKD_SHA512_KDF 7380

CKD_SHA3_224_KDF 7381




CKD_SHA1_KDF_SP800 7385





CKD_SHA3_224_KDF_SP800 7390




CKD_BLAKE2B_160_KDF 7394




6.3.3 ECDSA public key objects 7398

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

Table 65, Elliptic Curve Public Key Object Attributes 7402



CKA_EC_PARAMS1,3

Byte array DER-encoding of an ANSI X9.62 Parameters value

CKA_EC_POINT1,4

Byte array DER-encoding of ANSI X9.62 ECPoint value Q


Note: CKA_ECDSA_PARAMS is deprecated. It is replaced by CKA_EC_PARAMS. 7404

The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI 7405

X9.62 as a choice of three parameter representation methods with the following syntax: 7406

Parameters ::= CHOICE { 7407

ecParameters ECParameters, 7408

oId CURVES.&id({CurveNames}), 7409

implicitlyCA NULL, 7410

curveName PrintableString 7411

} 7412

7413

This allows detailed specification of all required values using choice ecParameters, the use of oId as an 7414 object identifier substitute for a particular set of elliptic curve domain parameters, or implicitlyCA to 7415 indicate that the domain parameters are explicitly defined elsewhere, or curveName to specify a curve 7416 name as e.g. define in [ANSI X9.62], [BRAINPOOL], [SEC 2], [LEGIFRANCE]. The use of oId or 7417 curveName is recommended over the choice ecParameters. The choice implicitlyCA must not be used 7418

in Cryptoki. 7419

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


CK_KEY_TYPE keyType = CKK_EC; 7422

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

CK_BYTE ecParams[] = {...}; 7424

CK_BYTE ecPoint[] = {...}; 7425







{CKA_EC_PARAMS, ecParams, sizeof(ecParams)}, 7432

{CKA_EC_POINT, ecPoint, sizeof(ecPoint)} 7433

}; 7434

6.3.4 Elliptic curve private key objects 7435

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

Table 66, Elliptic Curve Private Key Object Attributes 7439



CKA_EC_PARAMS1,4,6

Byte array DER-encoding of an ANSI X9.62 Parameters value

CKA_VALUE1,4,6,7

Big integer ANSI X9.62 private value d


The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI 7441

X9.62 as a choice of three parameter representation methods with the following syntax: 7442






} 7448

7449

This allows detailed specification of all required values using choice ecParameters, the use of oId as an 7450 object identifier substitute for a particular set of elliptic curve domain parameters, or implicitlyCA to 7451 indicate that the domain parameters are explicitly defined elsewhere, or curveName to specify a curve 7452 name as e.g. define in [ANSI X9.62], [BRAINPOOL], [SEC 2], [LEGIFRANCE]. The use of oId or 7453 curveName is recommended over the choice ecParameters. The choice implicitlyCA must not be used 7454 in Cryptoki.Note that when generating an EC private key, the EC domain parameters are not specified in 7455 the key’s template. This is because EC private keys are only generated as part of an EC key pair, and 7456 the EC domain parameters for the pair are specified in the template for the EC public key. 7457

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


CK_KEY_TYPE keyType = CKK_EC; 7460

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


CK_BYTE id[] = {123}; 7463


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










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



}; 7478

6.3.5 Edwards Elliptic curve public key objects 7479

Edwards EC public key objects (object class CKO_PUBLIC_KEY, key type CKK_EC_EDWARDS) hold 7480 Edwards EC public keys. The following table defines the Edwards EC public key object attributes, in 7481 addition to the common attributes defined for this object class: 7482


Table 67, Edwards Elliptic Curve Public Key Object Attributes 7483


CKA_EC_PARAMS1,3

Byte array DER-encoding of a Parameters value as defined above

CKA_EC_POINT1,4

Byte array DER-encoded octet value wrapped inside a DER-octet header of the b-bit public key value in little endian order as defined in RFC 8032


The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI 7485 X9.62 as a choice of three parameter representation methods. A 4

th choice is added to support Edwards 7486

and Montgomery Elliptic curves. The CKA_EC_PARAMS attribute has the following syntax: 7487






} 7493

Edwards EC public keys only support the use of the curveName selection to specify a curve name as 7494 defined in [RFC 8032] and the use of the oID selection to specify a curve through an EdDSA algorithm as 7495 defined in [RFC 8410]. Note that keys defined by RFC 8032 and RFC 8410 are incompatible. 7496

The following is a sample template for creating an Edwards EC public key object with Edwards25519 7497 being specified as curveName: 7498


CK_KEY_TYPE keyType = CKK_EC_EDWARDS; 7500

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

CK_BYTE ecParams[] = {0x13, 0x0c, 0x65, 0x64, 0x77, 0x61, 7502

0x72, 0x64, 0x73, 0x32, 0x35, 0x35, 0x31, 0x39}; 7503










}; 7513

6.3.6 Edwards Elliptic curve private key objects 7514

Edwards EC private key objects (object class CKO_PRIVATE_KEY, key type CKK_EC_EDWARDS) 7515 hold Edwards EC private keys. See Section 6.3 for more information about EC. The following table 7516 defines the Edwards EC private key object attributes, in addition to the common attributes defined for this 7517 object class: 7518

Table 68, Edwards Elliptic Curve Private Key Object Attributes 7519



CKA_EC_PARAMS1,4,6


CKA_VALUE1,4,6,7

Big integer DER-encoded octet value wrapped inside a DER-octet header of the b-bit private key value in little endian order as defined in RFC 8032










} 7529

Edwards EC private keys only support the use of the curveName selection to specify a curve name as 7530 defined in [RFC 8032] and the use of the oID selection to specify a curve through an EdDSA algorithm as 7531

defined in [RFC 8410]. Note that keys defined by RFC 8032 and RFC 8410 are incompatible. 7532

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

public key. 7536

The following is a sample template for creating an Edwards EC private key object: 7537


CK_KEY_TYPE keyType = CKK_EC_EDWARDS; 7539

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


CK_BYTE id[] = {123}; 7542


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












}; 7556

6.3.7 Montgomery Elliptic curve public key objects 7557

Montgomery EC public key objects (object class CKO_PUBLIC_KEY, key type 7558 CKK_EC_MONTGOMERY) hold Montgomery EC public keys. The following table defines the 7559


Montgomery EC public key object attributes, in addition to the common attributes defined for this object 7560 class: 7561

Table 69, Montgomery Elliptic Curve Public Key Object Attributes 7562


CKA_EC_PARAMS1,3


CKA_EC_POINT1,4

Byte array DER-encoded octet value wrapped inside a DER-octet header of the public key value in little endian order as defined in RFC 7748










} 7572

Montgomery EC public keys only support the use of the curveName selection to specify a curve name as 7573 defined in [RFC7748] and the use of the oID selection to specify a curve through an ECDH algorithm as 7574

defined in [RFC 8410]. Note that keys defined by RFC 7748 and RFC 8410 are incompatible. 7575

The following is a sample template for creating a Montgomery EC public key object: 7576


CK_KEY_TYPE keyType = CKK_EC_MONTGOMERY; 7578

CK_UTF8CHAR label[] = “A Montgomery EC public key object”; 7579











}; 7590

6.3.8 Montgomery Elliptic curve private key objects 7591

Montgomery EC private key objects (object class CKO_PRIVATE_KEY, key type 7592 CKK_EC_MONTGOMERY) hold Montgomery EC private keys. See Section 6.3 for more information 7593 about EC. The following table defines the Montgomery EC private key object attributes, in addition to the 7594 common attributes defined for this object class: 7595

Table 70, Montgomery Elliptic Curve Private Key Object Attributes 7596



CKA_EC_PARAMS1,4,6


CKA_VALUE1,4,6,7

Big integer DER-encoded octet value wrapped inside a DER-octet header of the private key value in little endian order as defined in RFC 7748










} 7606

Montgomery EC private keys only support the use of the curveName selection to specify a curve name 7607 as defined in [RFC7748] and the use of the oID selection to specify a curve through an ECDH algorithm 7608 as defined in [RFC 8410]. Note that keys defined by RFC 7748 and RFC 8410 are incompatible. 7609

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

Montgomery EC public key. 7613

The following is a sample template for creating a Montgomery EC private key object: 7614


CK_KEY_TYPE keyType = CKK_EC_MONTGOMERY; 7616

CK_UTF8CHAR label[] = “A Montgomery EC private key object”; 7617


CK_BYTE id[] = {123}; 7619


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












}; 7633

6.3.9 Elliptic curve key pair generation 7634

The EC (also related to ECDSA) key pair generation mechanism, denoted CKM_EC_KEY_PAIR_GEN, is 7635 a key pair generation mechanism that uses the method defined by the ANSI X9.62 and X9.63 standards. 7636


The EC (also related to ECDSA) key pair generation mechanism, denoted 7637 CKM_EC_KEY_PAIR_GEN_W_EXTRA_BITS, is a key pair generation mechanism that uses the method 7638 defined by FIPS 186-4 Appendix B.4.1. 7639

These mechanisms do not have a parameter. 7640

These mechanisms generate EC public/private key pairs with particular EC domain parameters, as 7641 specified in the CKA_EC_PARAMS attribute of the template for the public key. Note that this version of 7642

Cryptoki does not include a mechanism for generating these EC domain parameters. 7643

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

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7649 specify the minimum and maximum supported number of bits in the field sizes, respectively. For 7650 example, if a Cryptoki library supports only ECDSA using a field of characteristic 2 which has between 7651 2

200 and 2

300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary 7652

notation, the number 2200

consists of a 1 bit followed by 200 0 bits. It is therefore a 201-bit number. 7653 Similarly, 2

300 is a 301-bit number). 7654

6.3.10 Edwards Elliptic curve key pair generation 7655

The Edwards EC key pair generation mechanism, denoted CKM_EC_EDWARDS_KEY_PAIR_GEN, is a 7656

key pair generation mechanism for EC keys over curves represented in Edwards form. 7657


The mechanism can only generate EC public/private key pairs over the curves edwards25519 and 7659 edwards448 as defined in RFC 8032 or the curves id-Ed25519 and id-Ed448 as defined in RFC 8410. 7660 These curves can only be specified in the CKA_EC_PARAMS attribute of the template for the public key 7661 using the curveName or the oID methods. Attempts to generate keys over these curves using any other 7662

EC key pair generation mechanism will fail with CKR_CURVE_NOT_SUPPORTED. 7663

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

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7669 specify the minimum and maximum supported number of bits in the field sizes, respectively. For this 7670 mechanism, the only allowed values are 255 and 448 as RFC 8032 only defines curves of these two 7671 sizes. A Cryptoki implementation may support one or both of these curves and should set the 7672 ulMinKeySize and ulMaxKeySize fields accordingly. 7673

6.3.11 Montgomery Elliptic curve key pair generation 7674

The Montgomery EC key pair generation mechanism, denoted 7675 CKM_EC_MONTGOMERY_KEY_PAIR_GEN, is a key pair generation mechanism for EC keys over 7676

curves represented in Montgomery form. 7677


The mechanism can only generate Montgomery EC public/private key pairs over the curves curve25519 7679 and curve448 as defined in RFC 7748 or the curves id-X25519 and id-X448 as defined in RFC 8410. 7680 These curves can only be specified in the CKA_EC_PARAMS attribute of the template for the public key 7681 using the curveName or oId methods. Attempts to generate keys over these curves using any other EC 7682

key pair generation mechanism will fail with CKR_CURVE_NOT_SUPPORTED. 7683

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_EC_POINT attributes to the 7684 new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_EC_PARAMS and CKA_VALUE 7685


attributes to the new private key. Other attributes supported by the EC public and private key types 7686 (specifically, the flags indicating which functions the keys support) may also be specified in the templates 7687 for the keys, or else are assigned default initial values. 7688

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7689 specify the minimum and maximum supported number of bits in the field sizes, respectively. For this 7690 mechanism, the only allowed values are 255 and 448 as RFC 7748 only defines curves of these two 7691 sizes. A Cryptoki implementation may support one or both of these curves and should set the 7692 ulMinKeySize and ulMaxKeySize fields accordingly. 7693

6.3.12 ECDSA without hashing 7694

Refer section 6.3.1 for signature encoding. 7695

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



Table 71, ECDSA without hashing: Key and Data Length 7702


C_Sign1 ECDSA private key any

3 2nLen

C_Verify1 ECDSA public key any

3, 2nLen

2 N/A



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

7705


200 and 2

300 elements (inclusive), then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in 7709

binary notation, the number 2200



6.3.13 ECDSA with hashing 7712

Refer to section 6.3.1 for signature encoding. 7713

The ECDSA with SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, 7714 SHA3-512 mechanism, denoted 7715 CKM_ECDSA_[SHA1|SHA224|SHA256|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_517716 2] respectively, is a mechanism for single- and multiple-part signatures and verification for ECDSA. This 7717 mechanism computes the entire ECDSA specification, including the hashing with SHA-1, SHA-224, SHA-7718 256, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 respectively. 7719



Table 72, ECDSA with hashing: Key and Data Length 7722


C_Sign ECDSA private key any 2nLen

C_Verify ECDSA public key any, 2nLen 2 N/A


7723



200 and 2

300 elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary 7727

notation, the number 2200



6.3.14 EdDSA 7730

The EdDSA mechanism, denoted CKM_EDDSA, is a mechanism for single-part and multipart signatures 7731 and verification for EdDSA. This mechanism implements the five EdDSA signature schemes defined in 7732 RFC 8032 and RFC 8410. 7733

For curves according to RFC 8032, this mechanism has an optional parameter, a CK_EDDSA_PARAMS 7734 structure. The absence or presence of the parameter as well as its content is used to identify which 7735 signature scheme is to be used. The following table enumerates the five signature schemes defined in 7736 RFC 8032 and all supported permutations of the mechanism parameter and its content. 7737

Table 73, Mapping to RFC 8032 Signature Schemes 7738

Signature Scheme Mechanism Param phFlag Context Data

Ed25519 Not Required N/A N/A

Ed25519ctx Required False Optional

Ed25519ph Required True Optional

Ed448 Required False Optional

Ed448ph Required True Optional

For curves according to RFC 8410, the mechanism is implicitly given by the curve, which is EdDSA in 7739 pure mode. 7740


Table 74, EdDSA: Key and Data Length 7742


C_Sign CKK_EC_EDWARDS private key any 2bLen

C_Verify CKK_EC_EDWARDS public key any, 2bLen 2 N/A


Note that for EdDSA in pure mode, Ed25519 and Ed448 the data must be processed twice. Therefore, a 7744 token might need to cache all the data, especially when used with C_SignUpdate/C_VerifyUpdate. If 7745 tokens are unable to do so they can return CKR_TOKEN_RESOURCE_EXCEEDED. 7746

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7747 specify the minimum and maximum supported number of bits in the field sizes, respectively. For this 7748 mechanism, the only allowed values are 255 and 448 as RFC 8032and RFC 8410 only define curves of 7749 these two sizes. A Cryptoki implementation may support one or both of these curves and should set the 7750 ulMinKeySize and ulMaxKeySize fields accordingly. 7751

6.3.15 XEdDSA 7752

The XEdDSA mechanism, denoted CKM_XEDDSA, is a mechanism for single-part signatures and 7753 verification for XEdDSA. This mechanism implements the XEdDSA signature scheme defined in 7754 [XEDDSA]. CKM_XEDDSA operates on CKK_EC_MONTGOMERY type EC keys, which allows these 7755 keys to be used both for signing/verification and for Diffie-Hellman style key-exchanges. This double use 7756 is necessary for the Extended Triple Diffie-Hellman where the long-term identity key is used to sign short-7757 term keys and also contributes to the DH key-exchange. 7758


This mechanism has a parameter, a CK_XEDDSA_PARAMS structure. 7759

Table 75, XEdDSA: Key and Data Length 7760


C_Sign1 CKK_EC_MONTGOMERY private

key

any3 2b

C_Verify1 CKK_EC_MONTGOMERY public

key

any3, 2b

2 N/A


For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7762 specify the minimum and maximum supported number of bits in the field sizes, respectively. For this 7763 mechanism, the only allowed values are 255 and 448 as [XEDDSA] only defines curves of these two 7764 sizes. A Cryptoki implementation may support one or both of these curves and should set the 7765 ulMinKeySize and ulMaxKeySize fields accordingly. 7766

6.3.16 EC mechanism parameters 7767

CK_EDDSA_PARAMS, CK_EDDSA_PARAMS_PTR 7768

CK_EDDSA_PARAMS is a structure that provides the parameters for the CKM_EDDSA signature 7769

mechanism. The structure is defined as follows: 7770

typedef struct CK_EDDSA_PARAMS { 7771

CK_BBOOL phFlag; 7772

CK_ULONG ulContextDataLen; 7773

CK_BYTE_PTR pContextData; 7774

} CK_EDDSA_PARAMS; 7775

7776


phFlaga Boolean value which indicates if Prehashed variant of EdDSA should used 7778

ulContextDataLenthe length in bytes of the context data where 0 <= ulContextDataLen <= 255. 7779

pContextDatacontext data shared between the signer and verifier 7780

CK_EDDSA_PARAMS_PTR is a pointer to a CK_EDDSA_PARAMS. 7781

7782

CK_XEDDSA_PARAMS, CK_XEDDSA_PARAMS_PTR 7783

CK_XEDDSA_PARAMS is a structure that provides the parameters for the CKM_XEDDSA signature 7784 mechanism. The structure is defined as follows: 7785

typedef struct CK_XEDDSA_PARAMS { 7786

CK_XEDDSA_HASH_TYPE hash; 7787

} CK_XEDDSA_PARAMS; 7788

7789


hash a Hash mechanism to be used by the mechanism. 7791

CK_XEDDSA_PARAMS_PTR is a pointer to a CK_XEDDSA_PARAMS. 7792


7793

CK_XEDDSA_HASH_TYPE, CK_XEDDSA_HASH_TYPE_PTR 7794

CK_XEDDSA_HASH_TYPE is used to indicate the hash function used in XEDDSA. It is defined as 7795 follows: 7796

typedef CK_ULONG CK_XEDDSA_HASH_TYPE; 7797

7798

The following table lists the defined functions. 7799

Table 76, EC: Key Derivation Functions 7800

Source Identifier

CKM_BLAKE2B_256

CKM_BLAKE2B_512

CKM_SHA3_256

CKM_SHA3_512

CKM_SHA256

CKM_SHA512

7801

CK_XEDDSA_HASH_TYPE_PTR is a pointer to a CK_XEDDSA_HASH_TYPE. 7802

7803

CK_EC_KDF_TYPE, CK_EC_KDF_TYPE_PTR 7804

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

typedef CK_ULONG CK_EC_KDF_TYPE; 7808

7809


Table 77, EC: Key Derivation Functions 7811

Source Identifier

CKD_NULL

CKD_SHA1_KDF

CKD_SHA224_KDF

CKD_SHA256_KDF

CKD_SHA384_KDF

CKD_SHA512_KDF

CKD_SHA3_224_KDF

CKD_SHA3_256_KDF

CKD_SHA3_384_KDF

CKD_SHA3_512_KDF

CKD_SHA1_KDF_SP800

CKD_SHA224_KDF_SP800





CKD_SHA3_224_KDF_SP800




CKD_BLAKE2B_160_KDF

CKD_BLAKE2B_256_KDF

CKD_BLAKE2B_384_KDF

CKD_BLAKE2B_512_KDF

The key derivation function CKD_NULL produces a raw shared secret value without applying any key 7812 derivation function. 7813

The key derivation functions 7814 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF, which are 7815 based on SHA-1, SHA-224, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 7816 respectively, derive keying data from the shared secret value as defined in [ANSI X9.63]. 7817

The key derivation functions 7818 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF_SP800, 7819 which are based on SHA-1, SHA-224, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 7820 respectively, derive keying data from the shared secret value as defined in [FIPS SP800-56A] section 7821 5.8.1.1. 7822

The key derivation functions CKD_BLAKE2B_[160|256|384|512]_KDF, which are based on the Blake2b 7823 family of hashes, derive keying data from the shared secret value as defined in [FIPS SP800-56A] section 7824 5.8.1.1. CK_EC_KDF_TYPE_PTR is a pointer to a CK_EC_KDF_TYPE. 7825

7826

CK_ECDH1_DERIVE_PARAMS, CK_ECDH1_DERIVE_PARAMS_PTR 7827

CK_ECDH1_DERIVE_PARAMS is a structure that provides the parameters for the 7828 CKM_ECDH1_DERIVE and CKM_ECDH1_COFACTOR_DERIVE key derivation mechanisms, where 7829

each party contributes one key pair. The structure is defined as follows: 7830

typedef struct CK_ECDH1_DERIVE_PARAMS { 7831

CK_EC_KDF_TYPE kdf; 7832

CK_ULONG ulSharedDataLen; 7833

CK_BYTE_PTR pSharedData; 7834

CK_ULONG ulPublicDataLen; 7835

CK_BYTE_PTR pPublicData; 7836

} CK_ECDH1_DERIVE_PARAMS; 7837

7838


kdf key derivation function used on the shared secret value 7840

ulSharedDataLen the length in bytes of the shared info 7841

pSharedData some data shared between the two parties 7842

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


pPublicData1 pointer to other party’s EC public key value. A token MUST be able 7844

to accept this value encoded as a raw octet string (as per section 7845 A.5.2 of [ANSI X9.62]). A token MAY, in addition, support accepting 7846 this value as a DER-encoded ECPoint (as per section E.6 of [ANSI 7847 X9.62]) i.e. the same as a CKA_EC_POINT encoding. The calling 7848 application is responsible for converting the offered public key to the 7849 compressed or uncompressed forms of these encodings if the token 7850 does not support the offered form. 7851

With the key derivation function CKD_NULL, pSharedData must be NULL and ulSharedDataLen must be 7852 zero. With the key derivation functions 7853 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF, 7854 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF_SP800, an 7855 optional pSharedData may be supplied, which consists of some data shared by the two parties intending 7856 to share the shared secret. Otherwise, pSharedData must be NULL and ulSharedDataLen must be zero. 7857

CK_ECDH1_DERIVE_PARAMS_PTR is a pointer to a CK_ECDH1_DERIVE_PARAMS. 7858

CK_ECDH2_DERIVE_PARAMS, CK_ECDH2_DERIVE_PARAMS_PTR 7859

CK_ECDH2_DERIVE_PARAMS is a structure that provides the parameters to the 7860 CKM_ECMQV_DERIVE key derivation mechanism, where each party contributes two key pairs. The 7861

structure is defined as follows: 7862

typedef struct CK_ECDH2_DERIVE_PARAMS { 7863






CK_ULONG ulPrivateDataLen; 7869

CK_OBJECT_HANDLE hPrivateData; 7870

CK_ULONG ulPublicDataLen2; 7871

CK_BYTE_PTR pPublicData2; 7872

} CK_ECDH2_DERIVE_PARAMS; 7873

7874





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

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

ulPrivateDataLen the length in bytes of the second EC private key 7882

hPrivateData key handle for second EC private key value 7883

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

1 The encoding in V2.20 was not specified and resulted in different implementations choosing different encodings. Applications relying only on a V2.20 encoding

(e.g. the DER variant) other than the one specified now (raw) may not work with all V2.30 compliant tokens.


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

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

CK_ECDH2_DERIVE_PARAMS_PTR is a pointer to a CK_ECDH2_DERIVE_PARAMS. 7891

7892

CK_ECMQV_DERIVE_PARAMS, CK_ECMQV_DERIVE_PARAMS_PTR 7893

CK_ECMQV_DERIVE_PARAMS is a structure that provides the parameters to the 7894 CKM_ECMQV_DERIVE key derivation mechanism, where each party contributes two key pairs. The 7895

structure is defined as follows: 7896

typedef struct CK_ECMQV_DERIVE_PARAMS { 7897










CK_OBJECT_HANDLE publicKey; 7907

} CK_ECMQV_DERIVE_PARAMS; 7908

7909





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

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

ulPrivateDataLen the length in bytes of the second EC private key 7917

hPrivateData key handle for second EC private key value 7918

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

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

publicKey Handle to the first party’s ephemeral public key 7922

With the key derivation function CKD_NULL, pSharedData must be NULL and ulSharedDataLen must be 7923 zero. With the key derivation functions 7924 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF, 7925 CKD_[SHA1|SHA224|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512]_KDF_SP800, an 7926 optional pSharedData may be supplied, which consists of some data shared by the two parties intending 7927 to share the shared secret. Otherwise, pSharedData must be NULL and ulSharedDataLen must be zero. 7928

CK_ECMQV_DERIVE_PARAMS_PTR is a pointer to a CK_ECMQV_DERIVE_PARAMS. 7929


6.3.17 Elliptic curve Diffie-Hellman key derivation 7930

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

It has a parameter, a CK_ECDH1_DERIVE_PARAMS structure. 7935

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

type must be specified in the template. 7940

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

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

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

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

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 7953 specify the minimum and maximum supported number of bits in the field sizes, respectively. For 7954 example, if a Cryptoki library supports only EC using a field of characteristic 2 which has between 2

200 7955

and 2300

elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, 7956 the number 2

200 consists of a 1 bit followed by 200 0 bits. It is therefore a 201-bit number. Similarly, 2

300 7957

is a 301-bit number). 7958

Constraints on key types are summarized in the following table: 7959

Table 78: ECDH: Allowed Key Types 7960

Function Key type

C_Derive CKK_EC or CKK_EC_MONTGOMERY

6.3.18 Elliptic curve Diffie-Hellman with cofactor key derivation 7961

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

It has a parameter, a CK_ECDH1_DERIVE_PARAMS structure. 7967









200 7987

and 2300

elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, 7988 the number 2

200 consists of a 1 bit followed by 200 0 bits. It is therefore a 201-bit number. Similarly, 2

300 7989

is a 301-bit number). 7990


Table 79: ECDH with cofactor: Allowed Key Types 7992

Function Key type

C_Derive CKK_EC

6.3.19 Elliptic curve Menezes-Qu-Vanstone key derivation 7993

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

It has a parameter, a CK_ECMQV_DERIVE_PARAMS structure. 7998








200 8018

and 2300

elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, 8019


the number 2200

consists of a 1 bit followed by 200 0 bits. It is therefore a 201-bit number. Similarly, 2300

8020 is a 301-bit number). 8021


Table 80: ECDH MQV: Allowed Key Types 8023

Function Key type

C_Derive CKK_EC

6.3.20 ECDH AES KEY WRAP 8024

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

It has a parameter, a CK_ECDH_AES_KEY_WRAP_PARAMS structure. 8028

8029

The mechanism can wrap and unwrap an asymmetric target key of any length and type using an EC 8030

key. 8031

- A temporary AES key is derived from a temporary EC key and the wrapping EC key 8032

using the CKM_ECDH1_DERIVE mechanism. 8033

- The derived AES key is used for wrapping the target key using the 8034

CKM_AES_KEY_WRAP_KWP mechanism. 8035

8036

For wrapping, the mechanism - 8037

Generates a temporary random EC key (transport key) having the same parameters as the 8038 wrapping EC key (and domain parameters). Saves the transport key public key material. 8039

Performs ECDH operation using CKM_ECDH1_DERIVE with parameters of kdf, 8040 ulSharedDataLen and pSharedData using the private key of the transport EC key and the public 8041 key of wrapping EC key and gets the first ulAESKeyBits bits of the derived key to be the 8042 temporary AES key. 8043

Wraps the target key with the temporary AES key using CKM_AES_KEY_WRAP_KWP. 8044

Zeroizes the temporary AES key and EC transport private key. 8045

Concatenates public key material of the transport key and output the concatenated blob. The first 8046 part is the public key material of the transport key and the second part is the wrapped target key. 8047

8048

The private target key will be encoded as defined in section 2.7.6.7. 8049

8050

The use of Attributes in the PrivateKeyInfo structure is OPTIONAL. In case of conflicts between the 8051

object attribute template, and Attributes in the PrivateKeyInfo structure, an error should be thrown. 8052

8053

For unwrapping, the mechanism - 8054

Splits the input into two parts. The first part is the public key material of the transport key and the 8055 second part is the wrapped target key. The length of the first part is equal to the length of the 8056 public key material of the unwrapping EC key. 8057

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

Performs ECDH operation using CKM_ECDH1_DERIVE with parameters of kdf, 8061 ulSharedDataLen and pSharedData using the private part of unwrapping EC key and the public 8062 part of the transport EC key and gets first ulAESKeyBits bits of the derived key to be the 8063 temporary AES key. 8064


Un-wraps the target key from the second part with the temporary AES key using 8065 CKM_AES_KEY_WRAP_KWP. 8066

Zeroizes the temporary AES key. 8067

8068

Table 81, CKM_ECDH_AES_KEY_WRAP Mechanisms vs. Functions 8069

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_ECDH_AES_KEY_WRAP


8070


Table 82: ECDH AES Key Wrap: Allowed Key Types 8072

Function Key type

C_Wrap / C_Unwrap

CKK_EC or CKK_EC_MONTGOMERY

6.3.21 ECDH AES KEY WRAP mechanism parameters 8073

CK_ECDH_AES_KEY_WRAP_PARAMS; CK_ECDH_AES_KEY_WRAP_PARAMS_PTR 8074

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

8077

typedef struct CK_ECDH_AES_KEY_WRAP_PARAMS { 8078

CK_ULONG ulAESKeyBits; 8079




} CK_ECDH_AES_KEY_WRAP_PARAMS; 8083

8084


8086

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

kdf key derivation function used on the shared secret value to generate 8089 AES key. 8090


pSharedData Some data shared between the two parties 8092

8093

CK_ECDH_AES_KEY_WRAP_PARAMS_PTR is a pointer to a 8094 CK_ECDH_AES_KEY_WRAP_PARAMS. 8095

8096


6.3.22 FIPS 186-4 8097

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

8101

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

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

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

K-571, B-571 8105

6.4 Diffie-Hellman 8106

Table 83, Diffie-Hellman Mechanisms vs. Functions 8107

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_ PARAMETER_GEN

CKM_X9_42_DH_DERIVE

CKM_X9_42_DH_HYBRID_DERIVE

CKM_X9_42_MQV_DERIVE


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

Mechanisms: 8111

CKM_DH_PKCS_KEY_PAIR_GEN 8112

CKM_DH_PKCS_PARAMETER_GEN 8113

CKM_DH_PKCS_DERIVE 8114

CKM_X9_42_DH_KEY_PAIR_GEN 8115

CKM_X9_42_DH_PARAMETER_GEN 8116

CKM_X9_42_DH_DERIVE 8117

CKM_X9_42_DH_HYBRID_DERIVE 8118

CKM_X9_42_MQV_DERIVE 8119

8120


6.4.2 Diffie-Hellman public key objects 8121

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

Table 84, Diffie-Hellman Public Key Object Attributes 8125


CKA_PRIME1,3

Big integer Prime p

CKA_BASE1,3

Big integer Base g

CKA_VALUE1,4



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

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


CK_KEY_TYPE keyType = CKK_DH; 8132

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

CK_BYTE prime[] = {...}; 8134

CK_BYTE base[] = {...}; 8135

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










}; 8146

6.4.3 X9.42 Diffie-Hellman public key objects 8147

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

Table 85, X9.42 Diffie-Hellman Public Key Object Attributes 8151


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



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


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


CK_KEY_TYPE keyType = CKK_X9_42_DH; 8158

CK_UTF8CHAR label[] = “A X9.42 Diffie-Hellman public key 8159

object”; 8160

CK_BYTE prime[] = {...}; 8161

CK_BYTE base[] = {...}; 8162


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











}; 8175

6.4.4 Diffie-Hellman private key objects 8176

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

Table 86, Diffie-Hellman Private Key Object Attributes 8180


CKA_PRIME1,4,6

Big integer Prime p

CKA_BASE1,4,6

Big integer Base g

CKA_VALUE1,4,6,7


CKA_VALUE_BITS2,6

CK_ULONG Length in bits of private value x


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

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

Diffie-Hellman public key. 8188

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



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


CK_BYTE id[] = {123}; 8194

CK_BYTE prime[] = {...}; 8195

CK_BYTE base[] = {...}; 8196


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














}; 8211

6.4.5 X9.42 Diffie-Hellman private key objects 8212

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

Table 87, X9.42 Diffie-Hellman Private Key Object Attributes 8216


CKA_PRIME1,4,6


CKA_BASE1,4,6

Big integer Base g

CKA_SUBPRIME1,4,6


CKA_VALUE1,4,6,7



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

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

parameters for the pair are specified in the template for the X9.42 Diffie-Hellman public key. 8224

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



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


CK_BYTE id[] = {123}; 8230

CK_BYTE prime[] = {...}; 8231

CK_BYTE base[] = {...}; 8232


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
















}; 8249

6.4.6 Diffie-Hellman domain parameter objects 8250

Diffie-Hellman domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type 8251 CKK_DH) hold Diffie-Hellman domain parameters. The following table defines the Diffie-Hellman domain 8252

parameter object attributes, in addition to the common attributes defined for this object class: 8253

Table 88, Diffie-Hellman Domain Parameter Object Attributes 8254


CKA_PRIME1,4

Big integer Prime p

CKA_BASE1,4

Big integer Base g

CKA_PRIME_BITS2,3



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

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



CK_UTF8CHAR label[] = “A Diffie-Hellman domain parameters 8262

object”; 8263

CK_BYTE prime[] = {...}; 8264

CK_BYTE base[] = {...}; 8265









}; 8274

6.4.7 X9.42 Diffie-Hellman domain parameters objects 8275

X9.42 Diffie-Hellman domain parameters objects (object class CKO_DOMAIN_PARAMETERS, key type 8276 CKK_X9_42_DH) hold X9.42 Diffie-Hellman domain parameters. The following table defines the X9.42 8277


Diffie-Hellman domain parameters object attributes, in addition to the common attributes defined for this 8278 object class: 8279

Table 89, X9.42 Diffie-Hellman Domain Parameters Object Attributes 8280


CKA_PRIME1,4


CKA_BASE1,4

Big integer Base g

CKA_SUBPRIME1,4


CKA_PRIME_BITS2,3


CKA_SUBPRIME_BITS2,3

CK_ULONG Length of the subprime value.


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

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



CK_UTF8CHAR label[] = “A X9.42 Diffie-Hellman domain 8289

parameters object”; 8290

CK_BYTE prime[] = {...}; 8291

CK_BYTE base[] = {...}; 8292











}; 8303

6.4.8 PKCS #3 Diffie-Hellman key pair generation 8304

The PKCS #3 Diffie-Hellman key pair generation mechanism, denoted 8305 CKM_DH_PKCS_KEY_PAIR_GEN, is a key pair generation mechanism based on Diffie-Hellman key 8306

agreement, as defined in PKCS #3. This is what PKCS #3 calls “phase I”. It does not have a parameter. 8307

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

private value, as described in PKCS #3. 8311

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


specify the supported range of Diffie-Hellman prime sizes, in bits. 8318


6.4.9 PKCS #3 Diffie-Hellman domain parameter generation 8319

The PKCS #3 Diffie-Hellman domain parameter generation mechanism, denoted 8320 CKM_DH_PKCS_PARAMETER_GEN, is a domain parameter generation mechanism based on Diffie-8321

Hellman key agreement, as defined in PKCS #3. 8322


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

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, and 8326 CKA_PRIME_BITS attributes to the new object. Other attributes supported by the Diffie-Hellman domain 8327

parameter types may also be specified in the template, or else are assigned default initial values. 8328


specify the supported range of Diffie-Hellman prime sizes, in bits. 8330

6.4.10 PKCS #3 Diffie-Hellman key derivation 8331

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

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

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

template. 8343

This mechanism has the following rules about key sensitivity and extractability2: 8344




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

2 Note that the rules regarding the CKA_SENSITIVE, CKA_EXTRACTABLE, CKA_ALWAYS_SENSITIVE, and CKA_NEVER_EXTRACTABLE attributes have

changed in version 2.11 to match the policy used by other key derivation mechanisms such as CKM_SSL3_MASTER_KEY_DERIVE.


6.4.11 X9.42 Diffie-Hellman mechanism parameters 8358

CK_X9_42_DH_KDF_TYPE, CK_X9_42_DH_KDF_TYPE_PTR 8359

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

typedef CK_ULONG CK_X9_42_DH_KDF_TYPE; 8363

8364


Table 90, X9.42 Diffie-Hellman Key Derivation Functions 8366

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 8367 derivation function whereas the key derivation functions CKD_SHA1_KDF_ASN1 and 8368 CKD_SHA1_KDF_CONCATENATE, which are both based on SHA-1, derive keying data from the 8369

shared secret value as defined in the ANSI X9.42 standard. 8370

CK_X9_42_DH_KDF_TYPE_PTR is a pointer to a CK_X9_42_DH_KDF_TYPE. 8371

CK_X9_42_DH1_DERIVE_PARAMS, CK_X9_42_DH1_DERIVE_PARAMS_PTR 8372

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

typedef struct CK_X9_42_DH1_DERIVE_PARAMS { 8376

CK_X9_42_DH_KDF_TYPE kdf; 8377

CK_ULONG ulOtherInfoLen; 8378

CK_BYTE_PTR pOtherInfo; 8379



} CK_X9_42_DH1_DERIVE_PARAMS; 8382

8383



ulOtherInfoLen the length in bytes of the other info 8386

pOtherInfo some data shared between the two parties 8387

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

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

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



data shared by the two parties intending to share the shared secret. Otherwise, pOtherInfo must be 8396 NULL and ulOtherInfoLen must be zero. 8397

CK_X9_42_DH1_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_DH1_DERIVE_PARAMS. 8398

CK_X9_42_DH2_DERIVE_PARAMS, CK_X9_42_DH2_DERIVE_PARAMS_PTR 8399

CK_X9_42_DH2_DERIVE_PARAMS is a structure that provides the parameters to the 8400 CKM_X9_42_DH_HYBRID_DERIVE and CKM_X9_42_MQV_DERIVE key derivation mechanisms, 8401

where each party contributes two key pairs. The structure is defined as follows: 8402

typedef struct CK_X9_42_DH2_DERIVE_PARAMS { 8403










} CK_X9_42_DH2_DERIVE_PARAMS; 8413

8414





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

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

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

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

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

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

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

CK_X9_42_DH2_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_DH2_DERIVE_PARAMS. 8435


CK_X9_42_MQV_DERIVE_PARAMS, CK_X9_42_MQV_DERIVE_PARAMS_PTR 8436

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

typedef struct CK_X9_42_MQV_DERIVE_PARAMS { 8440










CK_OBJECT_HANDLE publicKey; 8450

} CK_X9_42_MQV_DERIVE_PARAMS; 8451

8452





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

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

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

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

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

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

publicKey Handle to the first party’s ephemeral public key 8466

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

CK_X9_42_MQV_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_MQV_DERIVE_PARAMS. 8474

6.4.12 X9.42 Diffie-Hellman key pair generation 8475

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



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

for the public key. 8482

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 8483 public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, CKA_SUBPRIME, and 8484 CKA_VALUE attributes to the new private key; other attributes required by the X9.42 Diffie-Hellman 8485

public and private key types must be specified in the templates. 8486

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

6.4.13 X9.42 Diffie-Hellman domain parameter generation 8489

The X9.42 Diffie-Hellman domain parameter generation mechanism, denoted 8490 CKM_X9_42_DH_PARAMETER_GEN, is a domain parameters generation mechanism based on X9.42 8491

Diffie-Hellman key agreement, as defined in the ANSI X9.42 standard. 8492


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

template for the domain parameters. 8496

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


specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits. 8502

6.4.14 X9.42 Diffie-Hellman key derivation 8503

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

It has a parameter, a CK_X9_42_DH1_DERIVE_PARAMS structure. 8508

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







6.4.15 X9.42 Diffie-Hellman hybrid key derivation 8530

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

It has a parameter, a CK_X9_42_DH2_DERIVE_PARAMS structure. 8535







6.4.16 X9.42 Diffie-Hellman Menezes-Qu-Vanstone key derivation 8557

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

It has a parameter, a CK_X9_42_MQV_DERIVE_PARAMS structure. 8562




If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 8574 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 8575


derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 8576 CKA_SENSITIVE attribute. 8577



6.5 Extended Triple Diffie-Hellman (x3dh) 8584

The Extended Triple Diffie-Hellman mechanism described here is the one described in 8585

[SIGNAL]. 8586

8587

Table 91, Extended Triple Diffie-Hellman Mechanisms vs. Functions 8588

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_X3DH_INITIALIZE

CKM_X3DH_RESPOND


Mechanisms: 8590

CKM_X3DH_INITIALIZE 8591

CKM_X3DH_RESPOND 8592

6.5.2 Extended Triple Diffie-Hellman key objects 8593

Extended Triple Diffie-Hellman uses Elliptic Curve keys in Montgomery representation 8594 (CKK_EC_MONTGOMERY). Three different kinds of keys are used, they differ in their lifespan: 8595

identity keys are long-term keys, which identify the peer, 8596

prekeys are short-term keys, which should be rotated often (weekly to hourly) 8597

onetime prekeys are keys, which should be used only once. 8598

Any peer intending to be contacted using X3DH must publish their so-called prekey-bundle, consisting of 8599 their: 8600

public Identity key, 8601

current prekey, signed using XEDDSA with their identity key 8602

optionally a batch of One-time public keys. 8603

6.5.3 Initiating an Extended Triple Diffie-Hellman key exchange 8604

Initiating an Extended Triple Diffie-Hellman key exchange starts by retrieving the following required public 8605 keys (the so-called prekey-bundle) of the other peer: the Identity key, the signed public Prekey, and 8606 optionally one One-time public key. 8607

When the necessary key material is available, the initiating party calls CKM_X3DH_INITIALIZE, also 8608 providing the following additional parameters: 8609

the initiators identity key 8610


the initiators ephemeral key (a fresh, one-time CKK_EC_MONTGOMERY type key) 8611

8612

CK_X3DH_INITIATE_PARAMS is a structure that provides the parameters to the 8613 CKM_X3DH_INITIALIZE key exchange mechanism. The structure is defined as follows: 8614

typedef struct CK_X3DH_INITIATE_PARAMS { 8615

CK_X3DH_KDF_TYPE kdf; 8616

CK_OBJECT_HANDLE pPeer_identity; 8617

CK_OBJECT_HANDLE pPeer_prekey; 8618

CK_BYTE_PTR pPrekey_signature; 8619

CK_BYTE_PTR pOnetime_key; 8620

CK_OBJECT_HANDLE pOwn_identity; 8621

CK_OBJECT_HANDLE pOwn_ephemeral; 8622

} CK_X3DH_INITIATE_PARAMS; 8623

Table 92, Extended Triple Diffie-Hellman Initiate Message parameters: 8624

Parameter Data type Meaning

kdf CK_X3DH_KDF_TYPE Key derivation function

pPeer_identity Key handle Peers public Identity key (from the prekey-bundle)

pPeer_prekey Key Handle Peers public prekey (from the prekey-bundle)

pPrekey_signature Byte array XEDDSA signature of PEER_PREKEY (from prekey-bundle)

pOnetime_key Byte array Optional one-time public prekey of peer (from the prekey-bundle)

pOwn_identity Key Handle Initiators Identity key

pOwn_ephemeral Key Handle Initiators ephemeral key

8625

6.5.4 Responding to an Extended Triple Diffie-Hellman key exchange 8626

Responding an Extended Triple Diffie-Hellman key exchange is done by executing a 8627 CKM_X3DH_RESPOND mechanism. CK_X3DH_RESPOND_PARAMS is a structure that provides the 8628 parameters to the CKM_X3DH_RESPOND key exchange mechanism. All these parameter should be 8629 supplied by the Initiator in a message to the responder. The structure is defined as follows: 8630

typedef struct CK_X3DH_RESPOND_PARAMS { 8631

CK_X3DH_KDF_TYPE kdf; 8632

CK_BYTE_PTR pIdentity_id; 8633

CK_BYTE_PTR pPrekey_id; 8634

CK_BYTE_PTR pOnetime_id; 8635

CK_OBJECT_HANDLE pInitiator_identity; 8636

CK_BYTE_PTR pInitiator_ephemeral; 8637

} CK_X3DH_RESPOND_PARAMS; 8638

8639

Table 93, Extended Triple Diffie-Hellman 1st Message parameters: 8640



kdf CK_X3DH_KDF_TYPE

Key derivation function

pIdentity_id Byte array Peers public Identity key identifier (from the prekey-bundle)

pPrekey_id Byte array Peers public prekey identifier (from the prekey-bundle)

pOnetime_id Byte array Optional one-time public prekey of peer (from the prekey-bundle)

pInitiator_identity Key handle Initiators Identity key

pInitiator_ephemeral Byte array Initiators ephemeral key

8641

Where the *_id fields are identifiers marking which key has been used from the prekey-bundle, these 8642 identifiers could be the keys themselves. 8643

8644

This mechanism has the following rules about key sensitivity and extractability3: 8645

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

2 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 8649 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 8650 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 8651 CKA_SENSITIVE attribute. 8652

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

6.5.5 Extended Triple Diffie-Hellman parameters 8657

CK_X3DH_KDF_TYPE, CK_X3DH_KDF_TYPE_PTR 8658

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

typedef CK_ULONG CK_X3DH_KDF_TYPE; 8662

8663


Table 94, X3DH: Key Derivation Functions 8665

Source Identifier

CKD_NULL

CKD_BLAKE2B_256_KDF

CKD_BLAKE2B_512_KDF

3 Note that the rules regarding the CKA_SENSITIVE, CKA_EXTRACTABLE, CKA_ALWAYS_SENSITIVE, and CKA_NEVER_EXTRACTABLE attributes have

changed in version 2.11 to match the policy used by other key derivation mechanisms such as CKM_SSL3_MASTER_KEY_DERIVE.



CKD_SHA3_256_KDF

CKD_SHA256_KDF

CKD_SHA3_512_KDF

CKD_SHA512_KDF

6.6 Double Ratchet 8666

The Double Ratchet is a key management algorithm managing the ongoing renewal and maintenance of 8667 short-lived session keys providing forward secrecy and break-in recovery for encrypt/decrypt operations. 8668 The algorithm is described in [DoubleRatchet]. The Signal protocol uses X3DH to exchange a shared 8669

secret in the first step, which is then used to derive a Double Ratchet secret key. 8670

Table 95, Double Ratchet Mechanisms vs. Functions 8671

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_X2RATCHET_INITIALIZE ✓

CKM_X2RATCHET_RESPOND ✓

CKM_X2RATCHET_ENCRYPT ✓ ✓

CKM_X2RATCHET_DECRYPT ✓ ✓

8672


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

Mechanisms: 8676

CKM_X2RATCHET_INITIALIZE 8677

CKM_X2RATCHET_RESPOND 8678

CKM_X2RATCHET_ENCRYPT 8679

CKM_X2RATCHET_DECRYPT 8680

6.6.2 Double Ratchet secret key objects 8681

Double Ratchet secret key objects (object class CKO_SECRET_KEY, key type CKK_X2RATCHET) hold 8682 Double Ratchet keys. Double Ratchet secret keys can only be derived from shared secret keys using the 8683 mechanism CKM_X2RATCHET_INITIALIZE or CKM_X2RATCHET_RESPOND. In the Signal protocol 8684 these are seeded with the shared secret derived from an Extended Triple Diffie-Hellman [X3DH] key-8685 exchange. The following table defines the Double Ratchet secret key object attributes, in addition to the 8686 common attributes defined for this object class: 8687

Table 96, Double Ratchet Secret Key Object Attributes 8688


CKA_X2RATCHET_RK Byte array Root key

CKA_X2RATCHET_HKS Byte array Sender Header key

CKA_X2RATCHET_HKR Byte array Receiver Header key

CKA_X2RATCHET_NHKS Byte array Next Sender Header Key

CKA_X2RATCHET_NHKR Byte array Next Receiver Header Key



CKA_X2RATCHET_CKS Byte array Sender Chain key

CKA_X2RATCHET_CKR Byte array Receiver Chain key

CKA_X2RATCHET_DHS Byte array Sender DH secret key

CKA_X2RATCHET_DHP Byte array Sender DH public key

CKA_X2RATCHET_DHR Byte array Receiver DH public key

CKA_X2RATCHET_NS ULONG Message number send

CKA_X2RATCHET_NR ULONG Message number receive

CKA_X2RATCHET_PNS ULONG Previous message number send

CKA_X2RATCHET_BOBS1STMSG BOOL Is this bob and has he ever sent a message?

CKA_X2RATCHET_ISALICE BOOL Is this Alice?

CKA_X2RATCHET_BAGSIZE ULONG How many out-of-order keys do we store

CKA_X2RATCHET_BAG Byte array Out-of-order keys

6.6.3 Double Ratchet key derivation 8689

The Double Ratchet key derivation mechanisms depend on who is the initiating party, and who the 8690 receiving, denoted CKM_X2RATCHET_INITIALIZE and CKM_X2RATCHET_RESPOND, are the key 8691 derivation mechanisms for the Double Ratchet. Usually the keys are derived from a shared secret by 8692 executing a X3DH key exchange. 8693

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 8694 key. Additionally the attribute flags indicating which functions the key supports are also contributed by the 8695 mechanism. 8696

For this mechanism, the only allowed values are 255 and 448 as RFC 8032 only defines curves of these 8697 two sizes. A Cryptoki implementation may support one or both of these curves and should set the 8698 ulMinKeySize and ulMaxKeySize fields accordingly. 8699

CK_X2RATCHET_INITIALIZE_PARAMS; 8700

CK_X2RATCHET_INITIALIZE_PARAMS_PTR 8701

CK_X2RATCHET_INITIALIZE_PARAMS provides the parameters to the 8702 CKM_X2RATCHET_INITIALIZE mechanism. It is defined as follows: 8703

typedef struct CK_X2RATCHET_INITIALIZE_PARAMS { 8704

CK_BYTE_PTR sk; 8705

CK_OBJECT_HANDLE peer_public_prekey; 8706

CK_OBJECT_HANDLE peer_public_identity; 8707

CK_OBJECT_HANDLE own_public_identity; 8708

CK_BBOOL bEncryptedHeader; 8709

CK_ULONG eCurve; 8710

CK_MECHANISM_TYPE aeadMechanism; 8711

CK_X2RATCHET_KDF_TYPE kdfMechanism; 8712

} CK_X2RATCHET_INITIALIZE_PARAMS; 8713

8714


sk the shared secret with peer (derived using X3DH) 8716

peers_public_prekey Peers public prekey which the Initiator used in the X3DH 8717

peers_public_identity Peers public identity which the Initiator used in the X3DH 8718


own_public_identity Initiators public identity as used in the X3DH 8719

bEncryptedHeader whether the headers are encrypted 8720

eCurve 255 for curve 25519 or 448 for curve 448 8721

aeadMechanism a mechanism supporting AEAD encryption 8722

kdfMechanism a Key Derivation Mechanism, such as 8723


CK_X2RATCHET_RESPOND_PARAMS; 8725

CK_X2RATCHET_RESPOND_PARAMS_PTR 8726

CK_X2RATCHET_RESPOND_PARAMS provides the parameters to the 8727 CKM_X2RATCHET_RESPOND mechanism. It is defined as follows: 8728

typedef struct CK_X2RATCHET_RESPOND_PARAMS { 8729

CK_BYTE_PTR sk; 8730

CK_OBJECT_HANDLE own_prekey; 8731

CK_OBJECT_HANDLE initiator_identity; 8732

CK_OBJECT_HANDLE own_public_identity; 8733

CK_BBOOL bEncryptedHeader; 8734

CK_ULONG eCurve; 8735

CK_MECHANISM_TYPE aeadMechanism; 8736

CK_X2RATCHET_KDF_TYPE kdfMechanism; 8737

} CK_X2RATCHET_RESPOND_PARAMS; 8738

8739


sk shared secret with the Initiator 8741

own_prekey Own Prekey pair that the Initiator used 8742

initiator_identity Initiators public identity key used 8743

own_public_identity as used in the prekey bundle by the initiator in the X3DH 8744

bEncryptedHeader whether the headers are encrypted 8745

eCurve 255 for curve 25519 or 448 for curve 448 8746

aeadMechanism a mechanism supporting AEAD encryption 8747

kdfMechanism a Key Derivation Mechanism, such as 8748


6.6.4 Double Ratchet Encryption mechanism 8750

The Double Ratchet encryption mechanism, denoted CKM_X2RATCHET_ENCRYPT and 8751 CKM_X2RATCHET_DECRYPT, are a mechanisms for single part encryption and decryption based on 8752

the Double Ratchet and its underlying AEAD cipher. 8753


6.6.5 Double Ratchet parameters 8754

CK_X2RATCHET_KDF_TYPE, CK_X2RATCHET_KDF_TYPE_PTR 8755

CK_X2RATCHET_KDF_TYPE is used to indicate the Key Derivation Function (KDF) applied to derive 8756 keying data from a shared secret. The key derivation function will be used by the X key derivation 8757 scheme. It is defined as follows: 8758

typedef CK_ULONG CK_X2RATCHET_KDF_TYPE; 8759

8760


Table 97, X2RATCHET: Key Derivation Functions 8762

Source Identifier

CKD_NULL

CKD_BLAKE2B_256_KDF

CKD_BLAKE2B_512_KDF

CKD_SHA3_256_KDF

CKD_SHA256_KDF

CKD_SHA3_512_KDF

CKD_SHA512_KDF

8763

6.7 Wrapping/unwrapping private keys 8764

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

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

8771

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

8773

dhpublicnumber OBJECT IDENTIFIER ::= { iso(1) member-body(2) 8774

us(840) ansi-x942(10046) number-type(2) 1 } 8775

8776

id-ecPublicKey OBJECT IDENTIFIER ::= { iso(1) member-body(2) 8777

us(840) ansi-x9-62(10045) publicKeyType(2) 1 } 8778

8779

id-dsa OBJECT IDENTIFIER ::= { 8780

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

8782

where 8783

pkcs-1 OBJECT IDENTIFIER ::= { 8784

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

8786

pkcs-3 OBJECT IDENTIFIER ::= { 8787

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

8789


These parameters for the algorithm identifiers have the 8790

following types, respectively: 8791

NULL 8792

8793

DHParameter ::= SEQUENCE { 8794

prime INTEGER, -- p 8795

base INTEGER, -- g 8796

privateValueLength INTEGER OPTIONAL 8797

} 8798

8799

DomainParameters ::= SEQUENCE { 8800

prime INTEGER, -- p 8801

base INTEGER, -- g 8802

subprime INTEGER, -- q 8803

cofactor INTEGER OPTIONAL, -- j 8804

validationParms ValidationParms OPTIONAL 8805

} 8806

8807

ValidationParms ::= SEQUENCE { 8808

Seed BIT STRING, -- seed 8809

PGenCounter INTEGER -- parameter verification 8810

} 8811

8812



namedCurve CURVES.&id({CurveNames}), 8815

implicitlyCA NULL 8816

} 8817

8818

Dss-Parms ::= SEQUENCE { 8819

p INTEGER, 8820

q INTEGER, 8821

g INTEGER 8822

} 8823

8824

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

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

Within the PrivateKeyInfo type: 8830

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

RSAPrivateKey BER-encoding of the key, and so it must not prepare it for wrapping. 8836

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


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

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

ECPrivateKey ::= SEQUENCE { 8841

Version INTEGER { ecPrivkeyVer1(1) } 8842

(ecPrivkeyVer1), 8843

privateKey OCTET STRING, 8844

parameters [0] Parameters OPTIONAL, 8845

publicKey [1] BIT STRING OPTIONAL 8846

} 8847

8848

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

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

Once a private key has been BER-encoded as a PrivateKeyInfo type, the resulting string of bytes is 8854 encrypted with the secret key. This encryption is defined in the section for the respective key wrapping 8855 mechanism. 8856

Unwrapping a wrapped private key undoes the above procedure. The ciphertext is decrypted as defined 8857 for the respective key unwrapping mechanism. The data thereby obtained are parsed as a 8858 PrivateKeyInfo type. An error will result if the original wrapped key does not decrypt properly, or if the 8859 decrypted data does not parse properly, or its type does not match the key type specified in the template 8860 for the new key. The unwrapping mechanism contributes only those attributes specified in the 8861 PrivateKeyInfo type to the newly-unwrapped key; other attributes must be specified in the template, or will 8862 take their default values. 8863

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

DSA OBJECT IDENTIFIER ::= { algorithm 12 } 8865

algorithm OBJECT IDENTIFIER ::= { 8866

iso(1) identifier-organization(3) oiw(14) secsig(3) 8867

algorithm(2) } 8868

8869

with associated parameters 8870

DSAParameters ::= SEQUENCE { 8871

prime1 INTEGER, -- modulus p 8872

prime2 INTEGER, -- modulus q 8873

base INTEGER -- base g 8874

} 8875

8876

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

6.8 Generic secret key 8880

Table 98, Generic Secret Key Mechanisms vs. Functions 8881


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_GENERIC_SECRET_KEY_GEN


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

Mechanisms: 8885

CKM_GENERIC_SECRET_KEY_GEN 8886

6.8.2 Generic secret key objects 8887

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

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

Table 99, Generic Secret Key Object Attributes 8893


CKA_VALUE1,4,6,7

Byte array Key value (arbitrary length)

CKA_VALUE_LEN2,3

CK_ULONG Length in bytes of key value


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

CK_OBJECT_CLASS class = CKO_SECRET_KEY; 8896

CK_KEY_TYPE keyType = CKK_GENERIC_SECRET; 8897

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

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









}; 8908

8909

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


6.8.3 Generic secret key generation 8912

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

to be generated. 8916


The template supplied must specify a value for the CKA_VALUE_LEN attribute. If the template specifies 8918

an object type and a class, they must have the following values: 8919

CK_OBJECT_CLASS = CKO_SECRET_KEY; 8920

CK_KEY_TYPE = CKK_GENERIC_SECRET; 8921

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

6.9 HMAC mechanisms 8924

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

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

6.9.1 General block cipher mechanism parameters 8930

CK_MAC_GENERAL_PARAMS; CK_MAC_GENERAL_PARAMS_PTR 8931

CK_MAC_GENERAL_PARAMS provides the parameters to the general-length MACing mechanisms of 8932 the DES, DES3 (triple-DES), AES, Camellia, SEED, and ARIA ciphers. It also provides the parameters to 8933 the general-length HMACing mechanisms (i.e.,SHA-1, SHA-256, SHA-384, SHA-512, and SHA-512/T 8934 family) and the two SSL 3.0 MACing mechanisms, (i.e., MD5 and SHA-1). It holds the length of the MAC 8935 that these mechanisms produce. It is defined as follows: 8936

typedef CK_ULONG CK_MAC_GENERAL_PARAMS; 8937

8938

CK_MAC_GENERAL_PARAMS_PTR is a pointer to a CK_MAC_GENERAL_PARAMS. 8939

6.10 AES 8940

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

Table 100, AES Mechanisms vs. Functions 8942

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


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

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


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

Mechanisms: 8946

CKM_AES_KEY_GEN 8947

CKM_AES_ECB 8948

CKM_AES_CBC 8949

CKM_AES_MAC 8950

CKM_AES_MAC_GENERAL 8951

CKM_AES_CBC_PAD 8952

CKM_AES_OFB 8953

CKM_AES_CFB64 8954

CKM_AES_CFB8 8955

CKM_AES_CFB128 8956

CKM_AES_CFB1 8957

CKM_AES_XCBC_MAC 8958

CKM_AES_XCBC_MAC_96 8959

6.10.2 AES secret key objects 8960

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

Table 101, AES Secret Key Object Attributes 8964


CKA_VALUE1,4,6,7

Byte array Key value (16, 24, or 32 bytes)

CKA_VALUE_LEN2,3,6



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



CK_KEY_TYPE keyType = CKK_AES; 8968

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

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









}; 8979

8980

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

6.10.3 AES key generation 8984

The AES key generation mechanism, denoted CKM_AES_KEY_GEN, is a key generation mechanism for 8985

NIST’s Advanced Encryption Standard. 8986


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

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


specify the supported range of AES key sizes, in bytes. 8994

6.10.4 AES-ECB 8995

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


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

For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the 9006 CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the 9007 CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the CKA_VALUE 9008

attribute of the new key; other attributes required by the key type must be specified in the template. 9009


Table 102, AES-ECB: Key And Data Length 9011


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


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



6.10.5 AES-CBC 9014

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

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





Table 103, AES-CBC: Key And Data Length 9030

Function Key type


C_Encrypt AES multiple of block size




C_WrapKey AES any input length rounded up to multiple of the block size



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

6.10.6 AES-CBC with PKCS padding 9033

AES-CBC with PKCS padding, denoted CKM_AES_CBC_PAD, is a mechanism for single- and multiple-9034 part encryption and decryption; key wrapping; and key unwrapping, based on NIST’s Advanced 9035


Encryption Standard; cipher-block chaining mode; and the block cipher padding method detailed in PKCS 9036 #7. 9037


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

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


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

Function Key type

Input length Output length

C_Encrypt AES any input length rounded up to multiple of the 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


between 1 and block length bytes shorter than input length


6.10.7 AES-OFB 9050

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

It has a parameter, an initialization vector for this mode. The initialization vector has the same length as 9053 the block size. 9054 9055 Constraints on key types and the length of data are summarized in the following table: 9056 9057

Table 105, AES-OFB: Key And Data Length 9058

Function Key type


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. 9059

6.10.8 AES-CFB 9060

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

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


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

Table 106, AES-CFB: Key And Data Length 9069

Function Key type


C_Encrypt AES any same as input length no final part

C_Decrypt AES any same as input length no final part


6.10.9 General-length AES-MAC 9071

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

It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length 9075

desired from the mechanism. 9076

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


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

Function Key type Data length Signature length

C_Sign AES any 1-block size, as specified in parameters

C_Verify AES any 1-block size, as specified in parameters


6.10.10 AES-MAC 9083

AES-MAC, denoted by CKM_AES_MAC, is a special case of the general-length AES-MAC mechanism. 9084

AES-MAC always produces and verifies MACs that are half the block size in length. 9085



Table 108, AES-MAC: Key And Data Length 9088


C_Sign AES Any ½ block size (8 bytes)

C_Verify AES Any ½ block size (8 bytes)


6.10.11 AES-XCBC-MAC 9091

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



Table 109, AES-XCBC-MAC: Key And Data Length 9096



C_Sign AES Any 16 bytes

C_Verify AES Any 16 bytes


6.10.12 AES-XCBC-MAC-96 9099

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



Table 110, AES-XCBC-MAC: Key And Data Length 9104


C_Sign AES Any 12 bytes

C_Verify AES Any 12 bytes


6.11 AES with Counter 9107

Table 111, AES with Counter Mechanisms vs. Functions 9108

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_AES_CTR


Mechanisms: 9110

CKM_AES_CTR 9111

6.11.2 AES with Counter mechanism parameters 9112

CK_AES_CTR_PARAMS; CK_AES_CTR_PARAMS_PTR 9113

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

typedef struct CK_AES_CTR_PARAMS { 9116

CK_ULONG ulCounterBits; 9117

CK_BYTE cb[16]; 9118

} CK_AES_CTR_PARAMS; 9119

9120

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


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

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

0 1 2 3 9128 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 9129 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 9130 | Nonce | 9131 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 9132 | Initialization Vector (IV) | 9133 | | 9134 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 9135 | Block Counter | 9136 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 9137

9138

This construction permits each packet to consist of up to 232

-1 blocks = 4,294,967,295 blocks = 9139 68,719,476,720 octets. 9140

CK_AES_CTR_PARAMS_PTR is a pointer to a CK_AES_CTR_PARAMS. 9141

6.11.3 AES with Counter Encryption / Decryption 9142

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

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

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

9154

6.12 AES CBC with Cipher Text Stealing CTS 9155

Ref [NIST AES CTS] 9156

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

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

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_AES_CTS


Mechanisms: 9161

CKM_AES_CTS 9162


6.12.2 AES CTS mechanism parameters 9163


Table 113, AES-CTS: Key And Data Length 9165

Function Key type


C_Encrypt AES Any, ≥ block size (16 bytes)


C_Decrypt AES any, ≥ block size (16 bytes)


9166

6.13 Additional AES Mechanisms 9167

Table 114, Additional AES Mechanisms vs. Functions 9168

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

9169


Mechanisms: 9171

CKM_AES_GCM 9172

CKM_AES_CCM 9173

CKM_AES_GMAC 9174

Generator Functions: 9175

CKG_NO_GENERATE 9176

CKG_GENERATE 9177

CKG_GENERATE_COUNTER 9178

CKG_GENERATE_RANDOM 9179

CKG_GENERATE_COUNTER_XOR 9180

6.13.2 AES-GCM Authenticated Encryption / Decryption 9181

Generic GCM mode is described in [GCM]. To set up for AES-GCM use the following process, where K 9182 (key) and AAD (additional authenticated data) are as described in [GCM]. AES-GCM uses 9183 CK_GCM_PARAMS for Encrypt, Decrypt and CK_GCM_MESSAGE_PARAMS for MessageEncrypt and 9184 MessageDecrypt. 9185

Encrypt: 9186

Set the IV length ulIvLen in the parameter block. 9187

Set the IV data pIv in the parameter block. 9188


Set the AAD data pAAD and size ulAADLen in the parameter block. pAAD may be NULL if 9189 ulAADLen is 0. 9190

Set the tag length ulTagBits in the parameter block. 9191

Call C_EncryptInit() for CKM_AES_GCM mechanism with parameters and key K. 9192

Call C_Encrypt(), or C_EncryptUpdate()*4 C_EncryptFinal(), for the plaintext obtaining ciphertext 9193

and authentication tag output. 9194

Decrypt: 9195





Call C_DecryptInit() for CKM_AES_GCM mechanism with parameters and key K. 9201

Call C_Decrypt(), or C_DecryptUpdate()*1 C_DecryptFinal(), for the ciphertext, including the 9202

appended tag, obtaining plaintext output. Note: since CKM_AES_GCM is an AEAD cipher, no 9203 data should be returned until C_Decrypt() or C_DecryptFinal(). 9204

MessageEncrypt: 9205


Set pIv to hold the IV data returned from C_EncryptMessage() and C_EncryptMessageBegin(). If 9207 ulIvFixedBits is not zero, then the most significant bits of pIV contain the fixed IV. If ivGenerator is 9208 set to CKG_NO_GENERATE, pIv is an input parameter with the full IV. 9209

Set the ulIvFixedBits and ivGenerator fields in the parameter block. 9210


Set pTag to hold the tag data returned from C_EncryptMessage() or the final 9212 C_EncryptMessageNext(). 9213

Call C_MessageEncryptInit() for CKM_AES_GCM mechanism key K. 9214

Call C_EncryptMessage(), or C_EncryptMessageBegin() followed by C_EncryptMessageNext()*5. 9215

The mechanism parameter is passed to all three of these functions. 9216

Call C_MessageEncryptFinal() to close the message decryption. 9217

MessageDecrypt: 9218



The ulIvFixedBits and ivGenerator fields are ignored. 9221


Set the tag data pTag in the parameter block before C_DecryptMessage() or the final 9223 C_DecryptMessageNext(). 9224

4 “*” indicates 0 or more calls may be made as required



Call C_MessageDecryptInit() for CKM_AES_GCM mechanism key K. 9225

Call C_DecryptMessage(), or C_DecryptMessageBegin followed by C_DecryptMessageNext()*6. 9226

The mechanism parameter is passed to all three of these functions. 9227

Call C_MessageDecryptFinal() to close the message decryption. 9228

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

On MessageEncrypt, the meaning of ivGenerator is as follows: CKG_NO_GENERATE means the IV is 9231 passed in on MessageEncrypt and no internal IV generation is done. CKG_GENERATE means that the 9232 non-fixed portion of the IV is generated by the module internally. The generation method is not defined. 9233

CKG_GENERATE_COUNTER means that the non-fixed portion of the IV is generated by the module 9234 internally by use of an incrementing counter, the initial IV counter is zero. 9235

CKG_GENERATE_COUNTER_XOR means that the non-fixed portion of the IV is xored with a counter. 9236 The value of the non-fixed portion passed must not vary from call to call. Like 9237 CKG_GENERATE_COUNTER, the counter starts at zero. 9238

CKG_GENERATE_RANDOM means that the non-fixed portion of the IV is generated by the module 9239 internally using a PRNG. In any case the entire IV, including the fixed portion, is returned in pIV. 9240

Modules must implement CKG_GENERATE. Modules may also reject ulIvFixedBits values which are too 9241 large. Zero is always an acceptable value for ulIvFixedBits. 9242

In Encrypt and Decrypt the tag is appended to the cipher text and the least significant bit of the tag is the 9243 rightmost bit and the tag bits are the rightmost ulTagBits bits. In MessageEncrypt the tag is returned in 9244 the pTag field of CK_GCM_MESSAGE_PARAMS. In MesssageDecrypt the tag is provided by the pTag 9245

field of CK_GCM_MESSAGE_PARAMS. 9246

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

6.13.3 AES-CCM authenticated Encryption / Decryption 9250

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

To set up for AES-CCM use the following process, where K (key), nonce and additional authenticated 9253 data are as described in [RFC 3610]. AES-CCM uses CK_CCM_PARAMS for Encrypt and Decrypt, and 9254 CK_CCM_MESSAGE_PARAMS for MessageEncrypt and MessageDecrypt. 9255

Encrypt: 9256

Set the message/data length ulDataLen in the parameter block. 9257

Set the nonce length ulNonceLen and the nonce data pNonce in the parameter block. 9258


Set the MAC length ulMACLen in the parameter block. 9261

Call C_EncryptInit() for CKM_AES_CCM mechanism with parameters and key K. 9262

Call C_Encrypt(), C_EncryptUpdate(), or C_EncryptFinal(), for the plaintext obtaining the final 9263 ciphertext output and the MAC. The total length of data processed must be ulDataLen. The output 9264 length will be ulDataLen + ulMACLen. 9265



Decrypt: 9266

Set the message/data length ulDataLen in the parameter block. This length must not include the 9267 length of the MAC that is appended to the cipher text. 9268

Set the nonce length ulNonceLen and the nonce data pNonce in the parameter block. 9269



Call C_DecryptInit() for CKM_AES_CCM mechanism with parameters and key K. 9273

Call C_Decrypt(), C_DecryptUpdate(), or C_DecryptFinal(), for the ciphertext, including the 9274 appended MAC, obtaining plaintext output. The total length of data processed must be ulDataLen 9275 + ulMACLen. Note: since CKM_AES_CCM is an AEAD cipher, no data should be returned until 9276 C_Decrypt() or C_DecryptFinal(). 9277

MessageEncrypt: 9278


Set the nonce length ulNonceLen. 9280

Set pNonce to hold the nonce data returned from C_EncryptMessage() and 9281 C_EncryptMessageBegin(). If ulNonceFixedBits is not zero, then the most significant bits of 9282 pNonce contain the fixed nonce. If nonceGenerator is set to CKG_NO_GENERATE, pNonce is 9283 an input parameter with the full nonce. 9284

Set the ulNonceFixedBits and nonceGenerator fields in the parameter block. 9285


Set pMAC to hold the MAC data returned from C_EncryptMessage() or the final 9287 C_EncryptMessageNext(). 9288

Call C_MessageEncryptInit() for CKM_AES_CCM mechanism key K. 9289

Call C_EncryptMessage(), or C_EncryptMessageBegin() followed by 9290 C_EncryptMessageNext()*

7.. The mechanism parameter is passed to all three functions. 9291

Call C_MessageEncryptFinal() to close the message encryption. 9292

The MAC is returned in pMac of the CK_CCM_MESSAGE_PARAMS structure. 9293



Set the nonce length ulNonceLen and the nonce data pNonce in the parameter block 9296

The ulNonceFixedBits and nonceGenerator fields in the parameter block are ignored. 9297


Set the MAC data pMAC in the parameter block before C_DecryptMessage() or the final 9299 C_DecryptMessageNext(). 9300

Call C_MessageDecryptInit() for CKM_AES_CCM mechanism key K. 9301



Call C_DecryptMessage(), or C_DecryptMessageBegin() followed by 9302 C_DecryptMessageNext()*

8. The mechanism parameter is passed to all three functions. 9303

Call C_MessageDecryptFinal() to close the message decryption. 9304

In pNonce the least significant bit of the nonce is the rightmost bit. ulNonceLen is the length of the nonce 9305 in bytes. 9306

On MessageEncrypt, the meaning of nonceGenerator is as follows: CKG_NO_GENERATE means the 9307 nonce is passed in on MessageEncrypt and no internal MAC generation is done. CKG_GENERATE 9308 means that the non-fixed portion of the nonce is generated by the module internally. The generation 9309 method is not defined. 9310

CKG_GENERATE_COUNTER means that the non-fixed portion of the nonce is generated by the module 9311 internally by use of an incrementing counter, the initial IV counter is zero. 9312

CKG_GENERATE_COUNTER_XOR means that the non-fixed portion of the IV is xored with a counter. 9313 The value of the non-fixed portion passed must not vary from call to call. Like 9314 CKG_GENERATE_COUNTER, the counter starts at zero. 9315

CKG_GENERATE_RANDOM means that the non-fixed portion of the nonce is generated by the module 9316 internally using a PRNG. In any case the entire nonce, including the fixed portion, is returned in pNonce. 9317

Modules must implement CKG_GENERATE. Modules may also reject ulNonceFixedBits values which are 9318 too large. Zero is always an acceptable value for ulNonceFixedBits. 9319

In Encrypt and Decrypt the MAC is appended to the cipher text and the least significant byte of the MAC 9320 is the rightmost byte and the MAC bytes are the rightmost ulMACLen bytes. In MessageEncrypt the MAC 9321 is returned in the pMAC field of CK_CCM_MESSAGE_PARAMS. In MesssageDecrypt the MAC is 9322 provided by the pMAC field of CK_CCM_MESSAGE_PARAMS. 9323

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

6.13.4 AES-GMAC 9327

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

The signature produced by GMAC, also referred to as a Tag, the tag’s length is determined by the 9333 CK_GCM_PARAMS field ulTagBits. 9334

The IV length is determined by the CK_GCM_PARAMS field ulIvLen. 9335


Table 115, AES-GMAC: Key And Data Length 9337


C_Sign CKK_AES < 2^64 Depends on param’s ulTagBits

C_Verify CKK_AES < 2^64 Depends on param’s ulTagBits




6.13.5 AES GCM and CCM Mechanism parameters 9340

CK_GENERATOR_FUNCTION 9341

Functions to generate unique IVs and nonces. 9342

typedef CK_ULONG CK_GENERATOR_FUNCTION; 9343

CK_GCM_PARAMS; CK_GCM_PARAMS_PTR 9344

CK_GCM_PARAMS is a structure that provides the parameters to the CKM_AES_GCM mechanism 9345 when used for Encrypt or Decrypt. It is defined as follows: 9346

typedef struct CK_GCM_PARAMS { 9347

CK_BYTE_PTR pIv; 9348

CK_ULONG ulIvLen; 9349

CK_ULONG ulIvBits; 9350

CK_BYTE_PTR pAAD; 9351

CK_ULONG ulAADLen; 9352

CK_ULONG ulTagBits; 9353

} CK_GCM_PARAMS; 9354

9355


pIv pointer to initialization vector 9357

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

ulIvBits length of initialization vector in bits. Do no use ulIvBits to specify the 9362 length of the initialization vector, but ulIvLen instead. 9363

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

ulAADLen length of pAAD in bytes. The length of the AAD can be any number 9366 between 0 and (2^32) – 1. 9367

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

CK_GCM_PARAMS_PTR is a pointer to a CK_GCM_PARAMS. 9370

CK_GCM_MESSAGE_PARAMS; CK_GCM_MESSAGE_PARAMS_PTR 9371

CK_GCM_MESSAGE_PARAMS is a structure that provides the parameters to the CKM_AES_GCM 9372 mechanism when used for MessageEncrypt or MessageDecrypt. It is defined as follows: 9373

typedef struct CK_GCM_MESSAGE_PARAMS { 9374

CK_BYTE_PTR pIv; 9375

CK_ULONG ulIvLen; 9376

CK_ULONG ulIvFixedBits; 9377

CK_GENERATOR_FUNCTION ivGenerator; 9378

CK_BYTE_PTR pTag; 9379

CK_ULONG ulTagBits; 9380


} CK_GCM_MESSAGE_PARAMS; 9381

9382


pIv pointer to initialization vector 9384

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

ulIvFixedBits number of bits of the original IV to preserve when generating an 9389 new IV. These bits are counted from the Most significant bits (to the 9390 right). 9391

ivGenerator Function used to generate a new IV. Each IV must be unique for a 9392 given session. 9393

pTag location of the authentication tag which is returned on 9394 MessageEncrypt, and provided on MessageDecrypt. 9395

ulTagBits length of authentication tag in bits. Can be any value between 0 and 9396 128. 9397

CK_GCM_MESSAGE_PARAMS_PTR is a pointer to a CK_GCM_MESSAGE_PARAMS. 9398

9399

CK_CCM_PARAMS; CK_CCM_PARAMS_PTR 9400

CK_CCM_PARAMS is a structure that provides the parameters to the CKM_AES_CCM mechanism 9401

when used for Encrypt or Decrypt. It is defined as follows: 9402

typedef struct CK_CCM_PARAMS { 9403

CK_ULONG ulDataLen; /*plaintext or ciphertext*/ 9404

CK_BYTE_PTR pNonce; 9405

CK_ULONG ulNonceLen; 9406



CK_ULONG ulMACLen; 9409

} CK_CCM_PARAMS; 9410

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

ulDataLen length of the data where 0 <= ulDataLen < 2^(8L). 9413

pNonce the nonce. 9414

ulNonceLen length of pNonce in bytes where 7 <= ulNonceLen <= 13. 9415

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

ulAADLen length of pAAD in bytes where 0 <= ulAADLen <= (2^32) - 1. 9418

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

CK_CCM_PARAMS_PTR is a pointer to a CK_CCM_PARAMS. 9421


CK_CCM_MESSAGE_PARAMS; CK_CCM_MESSAGE_PARAMS_PTR 9422

CK_CCM_MESSAGE_PARAMS is a structure that provides the parameters to the CKM_AES_CCM 9423

mechanism when used for MessageEncrypt or MessageDecrypt. It is defined as follows: 9424

typedef struct CK_CCM_MESSAGE_PARAMS { 9425

CK_ULONG ulDataLen; /*plaintext or ciphertext*/ 9426



CK_ULONG ulNonceFixedBits; 9429

CK_GENERATOR_FUNCTION nonceGenerator; 9430

CK_BYTE_PTR pMAC; 9431

CK_ULONG ulMACLen; 9432

} CK_CCM_MESSAGE_PARAMS; 9433

9434

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

ulDataLen length of the data where 0 <= ulDataLen < 2^(8L). 9437

pNonce the nonce. 9438

ulNonceLen length of pNonce in bytes where 7 <= ulNonceLen <= 13. 9439

ulNonceFixedBits number of bits of the original nonce to preserve when generating a 9440 new nonce. These bits are counted from the Most significant bits (to 9441 the right). 9442

nonceGenerator Function used to generate a new nonce. Each nonce must be 9443 unique for a given session. 9444

pMAC location of the CCM MAC returned on MessageEncrypt, provided on 9445 MessageDecrypt 9446

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

CK_CCM_MESSAGE_PARAMS_PTR is a pointer to a CK_CCM_MESSAGE_PARAMS. 9449

9450

6.14 AES CMAC 9451


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

. 9453


Mechanisms: 9455

CKM_AES_CMAC_GENERAL 9456


CKM_AES_CMAC 9457

6.14.2 Mechanism parameters 9458

CKM_AES_CMAC_GENERAL uses the existing CK_MAC_GENERAL_PARAMS structure. 9459

CKM_AES_CMAC does not use a mechanism parameter. 9460

6.14.3 General-length AES-CMAC 9461

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

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

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


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


C_Sign CKK_AES any 1-block size, as specified in parameters

C_Verify CKK_AES any 1-block size, as specified in parameters

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



6.14.4 AES-CMAC 9475

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


Table 118, AES-CMAC: Key And Data Length 9480


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 9481 than 64 bits. The MAC length must be specified before the communication starts, and must not be 9482 changed during the lifetime of the key. It is the caller’s responsibility to follow these rules. 9483



6.15 AES XTS 9486



Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_AES_XTS

CKM_AES_XTS_KEY_GEN


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

Mechanisms: 9491

CKM_AES_XTS 9492

CKM_AES_XTS_KEY_GEN 9493

6.15.2 AES-XTS secret key objects 9494

Table 120, AES-XTS Secret Key Object Attributes 9495


CKA_VALUE1,4,6,7

Byte array Key value (32 or 64 bytes)

CKA_VALUE_LEN2,3,6



6.15.3 AES-XTS key generation 9497

The double-length AES-XTS key generation mechanism, denoted CKM_AES_XTS_KEY_GEN, is a key 9498

generation mechanism for double-length AES-XTS keys. 9499

The mechanism generates AES-XTS keys with a particular length in bytes as specified in the 9500 CKA_VALUE_LEN attributes of the template for the key. 9501

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

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

6.15.4 AES-XTS 9508

AES-XTS (XEX-based Tweaked CodeBook mode with CipherText Stealing), denoted CKM_AES_XTS, 9509

isa mechanism for single- and multiple-part encryption and decryption. It is specified in NIST SP800-38E. 9510

Its single parameter is a Data Unit Sequence Number 16 bytes long. Supported key lengths are 32 and 9511 64 bytes. Keys are internally split into half-length sub-keys of 16 and 32 bytes respectively. Constraintson 9512 key types and the length of data are summarized in the following table: 9513

Table 121, AES-XTS: Key And Data Length 9514



C_Encrypt CKK_AES_XTS Any, ≥ block size (16 bytes)

Same as input length No final part

C_Decrypt CKK_AES_XTS Any, ≥ block size (16 bytes)


9515

6.16 AES Key Wrap 9516

Table 122, AES Key Wrap Mechanisms vs. Functions 9517

9518

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

CKM_AES_KEY_WRAP_KWP

CKM_AES_KEY_WRAP_PKCS7



Mechanisms: 9520

CKM_AES_KEY_WRAP 9521

CKM_AES_KEY_WRAP_PAD 9522

CKM_AES_KEY_WRAP_KWP 9523

CKM_AES_KEY_WRAP_PKCS7 9524

6.16.2 AES Key Wrap Mechanism parameters 9525

The mechanisms will accept an optional mechanism parameter as the Initialization vector which, if 9526 present, must be a fixed size array of 8 bytes for CKM_AES_KEY_WRAP and 9527 CKM_AES_KEY_WRAP_PKCS7, resp. 4 bytes for CKM_AES_KEY_WRAP_KWP; and, if NULL, will use 9528 the default initial value defined in Section 4.3 resp. 6.2 / 6.3 of [AES KEYWRAP]. 9529

The type of this parameter is CK_BYTE_PTR and the pointer points to the array of bytes to be used as 9530 the initial value. The length shall be either 0 and the pointer NULL; or 8 for CKM_AES_KEY_WRAP and 9531 CKM_AES_KEY_WRAP_PKCS7, resp. 4 for CKM_AES_KEY_WRAP_KWP, and the pointer non-NULL. 9532

6.16.3 AES Key Wrap 9533

The mechanisms support only single-part operations, i.e. single part wrapping and unwrapping, and 9534 single-part encryption and decryption. 9535

CKM_AES_KEY_WRAP 9536

The CKM_AES_KEY_WRAP mechanism can wrap a key of any length. A secret key whose length is not 9537 a multiple of the AES Key Wrap semiblock size (8 bytes) will be zero padded to fit. Semiblock size is 9538 defined in Section 5.2 of [AES KEYWRAP]. A private key will be encoded as defined in section 6.7; the 9539 encoded private key will be zero padded to fit if necessary. 9540


9541

The CKM_AES_KEY_WRAP mechanism can only encrypt a block of data whose size is an exact multiple 9542 of the AES Key Wrap algorithm semiblock size. 9543

9544

For unwrapping, the mechanism decrypts the wrapped key. In case of a secret key, it truncates the result 9545 according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, 9546 the CKA_VALUE_LEN attribute of the template. The length specified in the template must not be less 9547 than n-7 bytes, where n is the length of the wrapped key. In case of a private key, the mechanism parses 9548 the encoding as defined in section 6.7 and ignores trailing zero bytes. 9549

CKM_AES_KEY_WRAP_PAD 9550

The CKM_AES_KEY_WRAP_PAD mechanism is deprecated and shall not be used anymore. 9551 CKM_AES_KEY_WRAP_KWP resp. CKM_AES_KEY_WRAP_PKCS7 shall be used instead. 9552

CKM_AES_KEY_WRAP_KWP 9553

The CKM_AES_KEY_WRAP_KWP mechanism can wrap a key or encrypt block of data of any length. 9554 The input is zero-padded and wrapped / encrypted as defined in Section 6.3 of [AES KEYWRAP], which 9555 produces same results as RFC 5649. 9556

CKM_AES_KEY_WRAP_PKCS7 9557

The CKM_AES_KEY_WRAP_PKCS7 mechanism can wrap a key or encrypt a block of data of any 9558 length. It does the padding detailed in PKCS #7 of inputs (keys or data blocks) up to a semiblock size to 9559 make it an exact multiple of AES Key Wrap algorithum semiblock size (8bytes), always producing 9560 wrapped output that is larger than the input key/data to be wrapped. This padding is done by the token 9561 before being passed to the AES key wrap algorithm, which then wraps / encrypts the padded block of 9562 data as defined in Section 6.2 of [AES KEYWRAP]. 9563

6.17 Key derivation by data encryption – DES & AES 9564

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

Table 123, Key derivation by data encryption Mechanisms vs. Functions 9567

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


Mechanisms: 9569


CKM_DES_ECB_ENCRYPT_DATA 9570

CKM_DES_CBC_ENCRYPT_DATA 9571

CKM_DES3_ECB_ENCRYPT_DATA 9572

CKM_DES3_CBC_ENCRYPT_DATA 9573

CKM_AES_ECB_ENCRYPT_DATA 9574

CKM_AES_CBC_ENCRYPT_DATA 9575

9576

typedef struct CK_DES_CBC_ENCRYPT_DATA_PARAMS { 9577

CK_BYTE iv[8]; 9578

CK_BYTE_PTR pData; 9579

CK_ULONG length; 9580

} CK_DES_CBC_ENCRYPT_DATA_PARAMS; 9581

9582

typedef CK_DES_CBC_ENCRYPT_DATA_PARAMS CK_PTR 9583

CK_DES_CBC_ENCRYPT_DATA_PARAMS_PTR; 9584

9585

typedef struct CK_AES_CBC_ENCRYPT_DATA_PARAMS { 9586

CK_BYTE iv[16]; 9587



} CK_AES_CBC_ENCRYPT_DATA_PARAMS; 9590

9591

typedef CK_AES_CBC_ENCRYPT_DATA_PARAMS CK_PTR 9592

CK_AES_CBC_ENCRYPT_DATA_PARAMS_PTR; 9593

6.17.2 Mechanism Parameters 9594

Uses CK_KEY_DERIVATION_STRING_DATA as defined in section 6.43.2 9595

Table 124, Mechanism Parameters 9596

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.

6.17.3 Mechanism Description 9597

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


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

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

6.18 Double and Triple-length DES 9607

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

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


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

Mechanisms: 9612

CKM_DES2_KEY_GEN 9613

CKM_DES3_KEY_GEN 9614

CKM_DES3_ECB 9615

CKM_DES3_CBC 9616

CKM_DES3_MAC 9617

CKM_DES3_MAC_GENERAL 9618

CKM_DES3_CBC_PAD 9619

6.18.2 DES2 secret key objects 9620

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

Table 126, DES2 Secret Key Object Attributes 9624


CKA_VALUE1,4,6,7

Byte array Key value (always 16 bytes long)


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

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




CK_KEY_TYPE keyType = CKK_DES2; 9631

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

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









}; 9642

9643


6.18.3 DES3 secret key objects 9647

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

Table 127, DES3 Secret Key Object Attributes 9651


CKA_VALUE1,4,6,7



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

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


CK_KEY_TYPE keyType = CKK_DES3; 9658

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

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









}; 9669

9670



6.18.4 Double-length DES key generation 9674

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


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

Double-length DES keys can be used with all the same mechanisms as triple-DES keys: 9683 CKM_DES3_ECB, CKM_DES3_CBC, CKM_DES3_CBC_PAD, CKM_DES3_MAC_GENERAL, and 9684 CKM_DES3_MAC. Triple-DES encryption with a double-length DES key is equivalent to encryption with 9685

a triple-length DES key with K1=K3 as specified in FIPS PUB 46-3. 9686

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

6.18.5 Triple-length DES Order of Operations 9689

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

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

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

6.18.6 Triple-length DES in CBC Mode 9695

Triple-length DES operations in CBC mode, with double or triple-length keys, are performed using outer 9696 CBC as defined in X9.52. X9.52 describes this mode as TCBC. The mathematical representations of the 9697 CBC encrypt and decrypt operations are as follows: 9698

DES3-CBC-E({K1,K2,K3}, P) = E(K3, D(K2, E(K1, P + I))) 9699

DES3-CBC-D({K1,K2,K3}, C) = D(K1, E(K2, D(K3, P))) + I 9700

The value I is either an 8-byte initialization vector or the previous block of cipher text that is added to the 9701

current input block. The addition operation is used is addition modulo-2 (XOR). 9702

6.18.7 DES and Triple length DES in OFB Mode 9703

Table 128, DES and Triple Length DES in OFB Mode Mechanisms vs. Functions 9704

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_DES_OFB64

CKM_DES_OFB8

CKM_DES_CFB64

CKM_DES_CFB8

9705

Cipher DES has a output feedback mode, DES-OFB, denoted CKM_DES_OFB8 and 9706 CKM_DES_OFB64. It is a mechanism for single and multiple-part encryption and decryption with DES. 9707




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


Table 129, OFB: Key And Data Length 9711


Output length Comments

C_Encrypt CKK_DES, CKK_DES2, CKK_DES3

any same as input length no final part

C_Decrypt CKK_DES, CKK_DES2, CKK_DES3



6.18.8 DES and Triple length DES in CFB Mode 9713

Cipher DES has a cipher feedback mode, DES-CFB, denoted CKM_DES_CFB8 and CKM_DES_CFB64. 9714

It is a mechanism for single and multiple-part encryption and decryption with DES. 9715

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


Table 130, CFB: Key And Data Length 9719



C_Encrypt CKK_DES, CKK_DES2, CKK_DES3


C_Decrypt CKK_DES, CKK_DES2, CKK_DES3



6.19 Double and Triple-length DES CMAC 9721

Table 131, Double and Triple-length DES CMAC Mechanisms vs. Functions 9722

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_DES3_CMAC_GENERAL

CKM_DES3_CMAC

1 SR = SignRecover, VR = VerifyRecover.

9723


Mechanisms: 9725

CKM_DES3_CMAC_GENERAL 9726

CKM_DES3_CMAC 9727






6.19.2 Mechanism parameters 9728

CKM_DES3_CMAC_GENERAL uses the existing CK_MAC_GENERAL_PARAMS structure. 9729 CKM_DES3_CMAC does not use a mechanism parameter. 9730

6.19.3 General-length DES3-MAC 9731

General-length DES3-CMAC, denoted CKM_DES3_CMAC_GENERAL, is a mechanism for single- and 9732

multiple-part signatures and verification with DES3 or DES2 keys, based on [NIST sp800-38b]. 9733



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


Table 132, General-length DES3-CMAC: Key And Data Length 9739


C_Sign CKK_DES3 CKK_DES2

any 1-block size, as specified in parameters

C_Verify CKK_DES3 CKK_DES2

any 1-block size, as specified in parameters

Reference [NIST sp800-38b] recommends that the output MAC is not truncated to less than 64 bits 9740 (which means using the entire block for DES). The MAC length must be specified before the 9741 communication starts, and must not be changed during the lifetime of the key. It is the caller’s 9742 responsibility to follow these rules. 9743


are not used 9745

6.19.4 DES3-CMAC 9746

DES3-CMAC, denoted CKM_DES3_CMAC, is a special case of the general-length DES3-CMAC 9747 mechanism. DES3-MAC always produces and verifies MACs that are a full block size in length, since the 9748 DES3 block length is the minimum output length recommended by [NIST sp800-38b]. 9749


Table 133, DES3-CMAC: Key And Data Length 9751


C_Sign CKK_DES3 CKK_DES2

any Block size (8 bytes)

C_Verify CKK_DES3 CKK_DES2

any Block size (8 bytes)

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 9752 are not used. 9753

6.20 SHA-1 9754

Table 134, SHA-1 Mechanisms vs. Functions 9755


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA_1

CKM_SHA_1_HMAC_GENERAL

CKM_SHA_1_HMAC

CKM_SHA1_KEY_DERIVATION

CKM_SHA_1_KEY_GEN


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

Mechanisms: 9759

CKM_SHA_1 9760

CKM_SHA_1_HMAC 9761

CKM_SHA_1_HMAC_GENERAL 9762

CKM_SHA1_KEY_DERIVATION 9763

CKM_SHA_1_KEY_GEN 9764

9765

6.20.2 SHA-1 digest 9766

The SHA-1 mechanism, denoted CKM_SHA_1, is a mechanism for message digesting, following the 9767

Secure Hash Algorithm with a 160-bit message digest defined in FIPS PUB 180-2. 9768


Constraints on the length of input and output data are summarized in the following table. For single-part 9770 digesting, the data and the digest may begin at the same location in memory. 9771

Table 135, SHA-1: Data Length 9772

Function Input length Digest length

C_Digest any 20

6.20.3 General-length SHA-1-HMAC 9773

The general-length SHA-1-HMAC mechanism, denoted CKM_SHA_1_HMAC_GENERAL, is a 9774 mechanism for signatures and verification. It uses the HMAC construction, based on the SHA-1 hash 9775 function. The keys it uses are generic secret keys and CKK_SHA_1_HMAC. 9776

It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 9777 output. This length should be in the range 1-20 (the output size of SHA-1 is 20 bytes). Signatures 9778 (MACs) produced by this mechanism will be taken from the start of the full 20-byte HMAC output. 9779

Table 136, General-length SHA-1-HMAC: Key And Data Length 9780



C_Sign generic secret

CKK_SHA_1_HMAC

any 1-20, depending on parameters

C_Verify generic secret

CKK_SHA_1_HMAC

any 1-20, depending on parameters

6.20.4 SHA-1-HMAC 9781

The SHA-1-HMAC mechanism, denoted CKM_SHA_1_HMAC, is a special case of the general-length 9782

SHA-1-HMAC mechanism in Section 6.20.3. 9783

It has no parameter, and always produces an output of length 20. 9784

6.20.5 SHA-1 key derivation 9785

SHA-1 key derivation, denoted CKM_SHA1_KEY_DERIVATION, is a mechanism which provides the 9786 capability of deriving a secret key by digesting the value of another secret key with SHA-1. 9787

The value of the base key is digested once, and the result is used to make the value of derived secret 9788 key. 9789

If no length or key type is provided in the template, then the key produced by this mechanism will be a 9790 generic secret key. Its length will be 20 bytes (the output size of SHA-1). 9791

If no key type is provided in the template, but a length is, then the key produced by this mechanism 9792 will be a generic secret key of the specified length. 9793

If no length was provided in the template, but a key type is, then that key type must have a well-9794 defined length. If it does, then the key produced by this mechanism will be of the type specified in the 9795 template. If it doesn’t, an error will be returned. 9796

If both a key type and a length are provided in the template, the length must be compatible with that 9797 key type. The key produced by this mechanism will be of the specified type and length. 9798

If a DES, DES2, or CDMF key is derived with this mechanism, the parity bits of the key will be set 9799 properly. 9800

If the requested type of key requires more than 20 bytes, such as DES3, an error is generated. 9801





6.20.6 SHA-1 HMAC key generation 9814

The SHA-1-HMAC key generation mechanism, denoted CKM_SHA_1_KEY_GEN, is a key generation 9815

mechanism for NIST’s SHA-1-HMAC. 9816



The mechanism generates SHA-1-HMAC keys with a particular length in bytes, as specified in the 9818 CKA_VALUE_LEN attribute of the template for the key. 9819

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

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

6.21 SHA-224 9826


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA224

CKM_SHA224_HMAC

CKM_SHA224_HMAC_GENERAL

CKM_SHA224_RSA_PKCS



CKM_SHA224_KEY_GEN


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

Mechanisms: 9831

CKM_SHA224 9832

CKM_SHA224_HMAC 9833

CKM_SHA224_HMAC_GENERAL 9834


CKM_SHA224_KEY_GEN 9836

6.21.2 SHA-224 digest 9837

The SHA-224 mechanism, denoted CKM_SHA224, is a mechanism for message digesting, following the 9838 Secure Hash Algorithm with a 224-bit message digest defined in 0.FIPS PUB 180-4. 9839






C_Digest any 28


The general-length SHA-224-HMAC mechanism, denoted CKM_SHA224_HMAC_GENERAL, is the 9845 same as the general-length SHA-1-HMAC mechanism except that it uses the HMAC construction based 9846 on the SHA-224 hash function and length of the output should be in the range 1-28. The keys it uses are 9847 generic secret keys and CKK_SHA224_HMAC. FIPS-198 compliant tokens may require the key length to 9848 be at least 14 bytes; that is, half the size of the SHA-224 hash output. 9849

It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 9850 output. This length should be in the range 1-28 (the output size of SHA-224 is 28 bytes). FIPS-198 9851 compliant tokens may constrain the output length to be at least 4 or 14 (half the maximum length). 9852 Signatures (MACs) produced by this mechanism will be taken from the start of the full 28-byte HMAC 9853 output. 9854



C_Sign generic secret

CKK_SHA224_HMAC

Any 1-28, depending on parameters

C_Verify generic secret

CKK_SHA224_HMAC


6.21.4 SHA-224-HMAC 9856

The SHA-224-HMAC mechanism, denoted CKM_SHA224_HMAC, is a special case of the general-length 9857

SHA-224-HMAC mechanism. 9858



SHA-224 key derivation, denoted CKM_SHA224_KEY_DERIVATION, is the same as the SHA-1 key 9861 derivation mechanism in Section 12.21.56.20.5 except that it uses the SHA-224 hash function and the 9862 relevant length is 28 bytes. 9863


The SHA-224-HMAC key generation mechanism, denoted CKM_SHA224_KEY_GEN, is a key 9865

generation mechanism for NIST’s SHA224-HMAC. 9866


The mechanism generates SHA224-HMAC keys with a particular length in bytes, as specified in the 9868 CKA_VALUE_LEN attribute of the template for the key. 9869

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

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


6.22 SHA-256 9876


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA256


CKM_SHA256_HMAC


CKM_SHA256_KEY_GEN



Mechanisms: 9881

CKM_SHA256 9882





6.22.2 SHA-256 digest 9887

The SHA-256 mechanism, denoted CKM_SHA256, is a mechanism for message digesting, following the 9888






C_Digest any 32


The general-length SHA-256-HMAC mechanism, denoted CKM_SHA256_HMAC_GENERAL, is the 9895 same as the general-length SHA-1-HMAC mechanism in Section 6.20.3, except that it uses the HMAC 9896 construction based on the SHA-256 hash function and length of the output should be in the range 1-32. 9897 The keys it uses are generic secret keys and CKK_SHA256_HMAC. FIPS-198 compliant tokens may 9898 require the key length to be at least 16 bytes; that is, half the size of the SHA-256 hash output. 9899





C_Sign generic secret,

CKK_SHA256_HMAC


C_Verify generic secret,

CKK_SHA256_HMAC


6.22.4 SHA-256-HMAC 9906


SHA-256-HMAC mechanism in Section 6.22.3. 9908



SHA-256 key derivation, denoted CKM_SHA256_KEY_DERIVATION, is the same as the SHA-1 key 9911 derivation mechanism in Section 6.20.5, except that it uses the SHA-256 hash function and the relevant 9912 length is 32 bytes. 9913


The SHA-256-HMAC key generation mechanism, denoted CKM_SHA256_KEY_GEN, is a key 9915 generation mechanism for NIST’s SHA256-HMAC. 9916





6.23 SHA-384 9926


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA384


CKM_SHA384_HMAC


CKM_SHA384_KEY_GEN




CKM_SHA384 9931





6.23.2 SHA-384 digest 9936







C_Digest any 48


The general-length SHA-384-HMAC mechanism, denoted CKM_SHA384_HMAC_GENERAL, is the 9944 same as the general-length SHA-1-HMAC mechanism in Section 6.20.3, except that it uses the HMAC 9945 construction based on the SHA-384 hash function and length of the output should be in the range 1-48. 9946

The keys it uses are generic secret keys and CKK_SHA384_HMAC. FIPS-198 compliant tokens may 9947 require the key length to be at least 24 bytes; that is, half the size of the SHA-384 hash output. 9948




C_Sign generic secret, CKK_SHA384_

HMAC



CKK_SHA384_HMAC


9955

6.23.4 SHA-384-HMAC 9956


SHA-384-HMAC mechanism. 9958






The SHA-384-HMAC key generation mechanism, denoted CKM_SHA384_KEY_GEN, is a key 9965 generation mechanism for NIST’s SHA384-HMAC. 9966





6.24 SHA-512 9976


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA512


CKM_SHA512_HMAC


CKM_SHA512_KEY_GEN



Mechanisms: 9981

CKM_SHA512 9982





6.24.2 SHA-512 digest 9987








C_Digest any 64


The general-length SHA-512-HMAC mechanism, denoted CKM_SHA512_HMAC_GENERAL, is the 9995 same as the general-length SHA-1-HMAC mechanism in Section 6.20.3, except that it uses the HMAC 9996 construction based on the SHA-512 hash function and length of the output should be in the range 1-64. 9997

The keys it uses are generic secret keys and CKK_SHA512_HMAC. FIPS-198 compliant tokens may 9998 require the key length to be at least 32 bytes; that is, half the size of the SHA-512 hash output. 9999





HMAC



CKK_SHA512_HMAC


10006

6.24.4 SHA-512-HMAC 10007

The SHA-512-HMAC mechanism, denoted CKM_SHA512_HMAC, is a special case of the general-length 10008 SHA-512-HMAC mechanism. 10009





The SHA-512-HMAC key generation mechanism, denoted CKM_SHA512_KEY_GEN, is a key 10016

generation mechanism for NIST’s SHA512-HMAC. 10017






6.25 SHA-512/224 10027

Table 149, SHA-512/224 Mechanisms vs. Functions 10028

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA512_224

CKM_SHA512_224_HMAC_GENERAL

CKM_SHA512_224_HMAC

CKM_SHA512_224_KEY_DERIVATION

CKM_SHA512_224_KEY_GEN


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

Mechanisms: 10032

CKM_SHA512_224 10033

CKM_SHA512_224_HMAC 10034

CKM_SHA512_224_HMAC_GENERAL 10035

CKM_SHA512_224_KEY_DERIVATION 10036

CKM_SHA512_224_KEY_GEN 10037

6.25.2 SHA-512/224 digest 10038

The SHA-512/224 mechanism, denoted CKM_SHA512_224, is a mechanism for message digesting, 10039 following the Secure Hash Algorithm defined in FIPS PUB 180-4, section 5.3.6. It is based on a 512-bit 10040 message digest with a distinct initial hash value and truncated to 224 bits. CKM_SHA512_224 is the 10041 same as CKM_SHA512_T with a parameter value of 224. 10042



Table 150, SHA-512/224: Data Length 10046


C_Digest any 28

6.25.3 General-length SHA-512/224-HMAC 10047

The general-length SHA-512/224-HMAC mechanism, denoted CKM_SHA512_224_HMAC_GENERAL, 10048 is the same as the general-length SHA-1-HMAC mechanism in Section 6.20.3, except that it uses the 10049 HMAC construction based on the SHA-512/224 hash function and length of the output should be in the 10050 range 1-28. The keys it uses are generic secret keys and CKK_SHA512_224_HMAC. FIPS-198 10051 compliant tokens may require the key length to be at least 14 bytes; that is, half the size of the SHA-10052 512/224 hash output. 10053


It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 10054 output. This length should be in the range 0-28 (the output size of SHA-512/224 is 28 bytes). FIPS-198 10055 compliant tokens may constrain the output length to be at least 4 or 14 (half the maximum length). 10056 Signatures (MACs) produced by this mechanism will be taken from the start of the full 28-byte HMAC 10057 output. 10058




224_HMAC



CKK_SHA512_224_HMAC


10060

6.25.4 SHA-512/224-HMAC 10061

The SHA-512-HMAC mechanism, denoted CKM_SHA512_224_HMAC, is a special case of the general-10062

length SHA-512/224-HMAC mechanism. 10063


6.25.5 SHA-512/224 key derivation 10065

The SHA-512/224 key derivation, denoted CKM_SHA512_224_KEY_DERIVATION, is the same as the 10066 SHA-512 key derivation mechanism in section 2.25.5,6.24.5, except that it uses the SHA-512/224 hash 10067 function and the relevant length is 28 bytes. 10068

6.25.6 SHA-512/224 HMAC key generation 10069

The SHA-512/224-HMAC key generation mechanism, denoted CKM_SHA512_224_KEY_GEN, is a key 10070

generation mechanism for NIST’s SHA512/224-HMAC. 10071


The mechanism generates SHA512/224-HMAC keys with a particular length in bytes, as specified in the 10073 CKA_VALUE_LEN attribute of the template for the key. 10074

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 10075 key. Other attributes supported by the SHA512/224-HMAC key type (specifically, the flags indicating 10076 which functions the key supports) may be specified in the template for the key, or else are assigned 10077 default initial values. 10078

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

6.26 SHA-512/256 10081

Table 152, SHA-512/256 Mechanisms vs. Functions 10082

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA512_256


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive


CKM_SHA512_256_HMAC




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

Mechanisms: 10086

CKM_SHA512_256 10087





6.26.2 SHA-512/256 digest 10092

The SHA-512/256 mechanism, denoted CKM_SHA512_256, is a mechanism for message digesting, 10093 following the Secure Hash Algorithm defined in FIPS PUB 180-4, section 5.3.6. It is based on a 512-bit 10094 message digest with a distinct initial hash value and truncated to 256 bits. CKM_SHA512_256 is the 10095 same as CKM_SHA512_T with a parameter value of 256. 10096





C_Digest any 32

6.26.3 General-length SHA-512/256-HMAC 10101

The general-length SHA-512/256-HMAC mechanism, denoted CKM_SHA512_256_HMAC_GENERAL, 10102 is the same as the general-length SHA-1-HMAC mechanism in Section 6.20.3, except that it uses the 10103 HMAC construction based on the SHA-512/256 hash function and length of the output should be in the 10104 range 1-32. The keys it uses are generic secret keys and CKK_SHA512_256_HMAC. FIPS-198 10105 compliant tokens may require the key length to be at least 16 bytes; that is, half the size of the SHA-10106 512/256 hash output. 10107

It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 10108 output. This length should be in the range 1-32 (the output size of SHA-512/256 is 32 bytes). FIPS-198 10109 compliant tokens may constrain the output length to be at least 4 or 16 (half the maximum length). 10110 Signatures (MACs) produced by this mechanism will be taken from the start of the full 32-byte HMAC 10111 output. 10112





256_HMAC



CKK_SHA512_256_HMAC


10114

6.26.4 SHA-512/256-HMAC 10115


length SHA-512/256-HMAC mechanism. 10117


6.26.5 SHA-512/256 key derivation 10119

The SHA-512/256 key derivation, denoted CKM_SHA512_256_KEY_DERIVATION, is the same as the 10120 SHA-512 key derivation mechanism in section 2.25.5,6.24.5, except that it uses the SHA-512/256 hash 10121 function and the relevant length is 32 bytes. 10122

6.26.6 SHA-512/256 HMAC key generation 10123

The SHA-512/256-HMAC key generation mechanism, denoted CKM_SHA512_256_KEY_GEN, is a key 10124

generation mechanism for NIST’s SHA512/256-HMAC. 10125


The mechanism generates SHA512/256-HMAC keys with a particular length in bytes, as specified in the 10127 CKA_VALUE_LEN attribute of the template for the key. 10128

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 10129 key. Other attributes supported by the SHA512/256-HMAC key type (specifically, the flags indicating 10130 which functions the key supports) may be specified in the template for the key, or else are assigned 10131 default initial values. 10132


6.27 SHA-512/t 10135

Table 155, SHA-512 / t Mechanisms vs. Functions 10136

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA512_T

CKM_SHA512_T_HMAC_GENERAL

CKM_SHA512_T_HMAC

CKM_SHA512_T_KEY_DERIVATION

CKM_SHA512_T_KEY_GEN



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

Mechanisms: 10140

CKM_SHA512_T 10141

CKM_SHA512_T_HMAC 10142

CKM_SHA512_T_HMAC_GENERAL 10143

CKM_SHA512_T_KEY_DERIVATION 10144

CKM_SHA512_T_KEY_GEN 10145

6.27.2 SHA-512/t digest 10146

The SHA-512/t mechanism, denoted CKM_SHA512_T, is a mechanism for message digesting, following 10147 the Secure Hash Algorithm defined in FIPS PUB 180-4, section 5.3.6. It is based on a 512-bit message 10148 digest with a distinct initial hash value and truncated to t bits. 10149

It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the value of t in bits. The length in 10150

bytes of the desired output should be in the range of 0-⌈ t/8⌉, where 0 < t < 512, and t <> 384. 10151




C_Digest any ⌈t/8⌉, where 0 < t < 512, and t <> 384

6.27.3 General-length SHA-512/t-HMAC 10155

The general-length SHA-512/t-HMAC mechanism, denoted CKM_SHA512_T_HMAC_GENERAL, is the 10156 same as the general-length SHA-1-HMAC mechanism in Section 6.20.3, except that it uses the HMAC 10157 construction based on the SHA-512/t hash function and length of the output should be in the range 0 – 10158

⌈t/8⌉, where 0 < t < 512, and t <> 384. 10159

6.27.4 SHA-512/t-HMAC 10160

The SHA-512/t-HMAC mechanism, denoted CKM_SHA512_T_HMAC, is a special case of the general-10161

length SHA-512/t-HMAC mechanism. 10162

It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the value of t in bits. The length in 10163

bytes of the desired output should be in the range of 0-⌈t/8⌉, where 0 < t < 512, and t <> 384. 10164

6.27.5 SHA-512/t key derivation 10165

The SHA-512/t key derivation, denoted CKM_SHA512_T_KEY_DERIVATION, is the same as the SHA-10166 512 key derivation mechanism in section 2.25.5,6.24.5, except that it uses the SHA-512/t hash function 10167

and the relevant length is ⌈t/8⌉ bytes, where 0 < t < 512, and t <> 384. 10168

6.27.6 SHA-512/t HMAC key generation 10169

The SHA-512/t-HMAC key generation mechanism, denoted CKM_SHA512_T_KEY_GEN, is a key 10170

generation mechanism for NIST’s SHA512/t-HMAC. 10171



The mechanism generates SHA512/t-HMAC keys with a particular length in bytes, as specified in the 10173 CKA_VALUE_LEN attribute of the template for the key. 10174

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 10175 key. Other attributes supported by the SHA512/t-HMAC key type (specifically, the flags indicating which 10176 functions the key supports) may be specified in the template for the key, or else are assigned default 10177 initial values. 10178

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

10181

6.28 SHA3-224 10182


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA3_224

CKM_SHA3_224_HMAC





Mechanisms: 10185

CKM_SHA3_224 10186





10191

CKK_SHA3_224_HMAC 10192

6.28.2 SHA3-224 digest 10193

The SHA3-224 mechanism, denoted CKM_SHA3_224, is a mechanism for message digesting, following 10194

the Secure Hash 3 Algorithm with a 224-bit message digest defined in FIPS Pub 202. 10195



Table 158, SHA3-224: Data Length 10199



C_Digest any 28

6.28.3 General-length SHA3-224-HMAC 10200

The general-length SHA3-224-HMAC mechanism, denoted CKM_SHA3_224_HMAC_GENERAL, is the 10201 same as the general-length SHA-1-HMAC mechanism in section 6.20.4 except that it uses the HMAC 10202 construction based on the SHA3-224 hash function and length of the output should be in the range 1-28. 10203 The keys it uses are generic secret keys and CKK_SHA3_224_HMAC. FIPS-198 compliant tokens may 10204 require the key length to be at least 14 bytes; that is, half the size of the SHA3-224 hash output. 10205

It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 10206 output. This length should be in the range 1-28 (the output size of SHA3-224 is 28 bytes). FIPS-198 10207 compliant tokens may constrain the output length to be at least 4 or 14 (half the maximum length). 10208 Signatures (MACs) produced by this mechanism shall be taken from the start of the full 28-byte HMAC 10209 output. 10210

Table 159, General-length SHA3-224-HMAC: Key And Data Length 10211


C_Sign generic secret or CKK_SHA3_224_HMAC


C_Verify generic secret or CKK_SHA3_224_HMAC


6.28.4 SHA3-224-HMAC 10212

The SHA3-224-HMAC mechanism, denoted CKM_SHA3_224_HMAC, is a special case of the general-10213

length SHA3-224-HMAC mechanism. 10214


6.28.5 SHA3-224 key derivation 10216

SHA-224 key derivation, denoted CKM_SHA3_224_KEY_DERIVATION, is the same as the SHA-1 key 10217 derivation mechanism in Section 6.20.5 except that it uses the SHA3-224 hash function and the relevant 10218 length is 28 bytes. 10219

6.28.6 SHA3-224 HMAC key generation 10220

The SHA3-224-HMAC key generation mechanism, denoted CKM_SHA3_224_KEY_GEN, is a key 10221

generation mechanism for NIST’s SHA3-224-HMAC. 10222


The mechanism generates SHA3-224-HMAC keys with a particular length in bytes, as specified in the 10224 CKA_VALUE_LEN attribute of the template for the key. 10225

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


6.29 SHA3-256 10232

Table 160, SHA3-256 Mechanisms vs. Functions 10233


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA3_256


CKM_SHA3_256_HMAC




Mechanisms: 10235

CKM_SHA3_256 10236





10241


6.29.2 SHA3-256 digest 10243


the Secure Hash 3 Algorithm with a 256-bit message digest defined in FIPS PUB 202. 10245





C_Digest any 32


The general-length SHA3-256-HMAC mechanism, denoted CKM_SHA3_256_HMAC_GENERAL, is the 10251 same as the general-length SHA-1-HMAC mechanism in Section 6.20.4, except that it uses the HMAC 10252 construction based on the SHA3-256 hash function and length of the output should be in the range 1-32. 10253 The keys it uses are generic secret keys and CKK_SHA3_256_HMAC. FIPS-198 compliant tokens may 10254 require the key length to be at least 16 bytes; that is, half the size of the SHA3-256 hash output. 10255







C_Verify generic secret or

CKK_SHA3_256_HMAC


6.29.4 SHA3-256-HMAC 10262


length SHA-256-HMAC mechanism. 10264



SHA-256 key derivation, denoted CKM_SHA3_256_KEY_DERIVATION, is the same as the SHA-1 key 10267 derivation mechanism in Section 6.20.56.20.5, except that it uses the SHA3-256 hash function and the 10268 relevant length is 32 bytes. 10269


The SHA3-256-HMAC key generation mechanism, denoted CKM_SHA3_256_KEY_GEN, is a key 10271

generation mechanism for NIST’s SHA3-256-HMAC. 10272





10282

6.30 SHA3-384 10283

Table 163, SHA3-384 Mechanisms vs. Functions 10284

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA3_384


CKM_SHA3_384_HMAC




CKM_SHA3_384 10286






10291


6.30.2 SHA3-384 digest 10293







C_Digest any 48


The general-length SHA3-384-HMAC mechanism, denoted CKM_SHA3_384_HMAC_GENERAL, is the 10301 same as the general-length SHA-1-HMAC mechanism in Section 6.20.4, except that it uses the HMAC 10302 construction based on the SHA-384 hash function and length of the output should be in the range 1-10303 48.The keys it uses are generic secret keys and CKK_SHA3_384_HMAC. FIPS-198 compliant tokens 10304 may require the key length to be at least 24 bytes; that is, half the size of the SHA3-384 hash output. 10305

10306




C_Sign generic secret or

CKK_SHA3_384_HMAC


C_Verify generic secret or

CKK_SHA3_384_HMAC


10313

6.30.4 SHA3-384-HMAC 10314

The SHA3-384-HMAC mechanism, denoted CKM_SHA3_384_HMAC, is a special case of the general-10315 length SHA3-384-HMAC mechanism. 10316



SHA3-384 key derivation, denoted CKM_SHA3_384_KEY_DERIVATION, is the same as the SHA-1 key 10319 derivation mechanism in Section 6.20.5, except that it uses the SHA-384 hash function and the relevant 10320 length is 48 bytes. 10321



The SHA3-384-HMAC key generation mechanism, denoted CKM_SHA3_384_KEY_GEN, is a key 10323 generation mechanism for NIST’s SHA3-384-HMAC. 10324





6.31 SHA3-512 10334


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHA3_512


CKM_SHA3_512_HMAC




CKM_SHA3_512 10337





10342


6.31.2 SHA3-512 digest 10344








C_Digest any 64


The general-length SHA3-512-HMAC mechanism, denoted CKM_SHA3_512_HMAC_GENERAL, is the 10352 same as the general-length SHA-1-HMAC mechanism in Section 6.20.4, except that it uses the HMAC 10353 construction based on the SHA3-512 hash function and length of the output should be in the range 1-10354 64.The keys it uses are generic secret keys and CKK_SHA3_512_HMAC. FIPS-198 compliant tokens 10355 may require the key length to be at least 32 bytes; that is, half the size of the SHA3-512 hash output. 10356

10357






C_Verify generic secret or CKK_SHA3_512_HMAC


10364

6.31.4 SHA3-512-HMAC 10365

The SHA3-512-HMAC mechanism, denoted CKM_SHA3_512_HMAC, is a special case of the general-10366

length SHA3-512-HMAC mechanism. 10367



SHA3-512 key derivation, denoted CKM_SHA3_512_KEY_DERIVATION, is the same as the SHA-1 key 10370 derivation mechanism in Section 6.20.5, except that it uses the SHA-512 hash function and the relevant 10371 length is 64 bytes. 10372


The SHA3-512-HMAC key generation mechanism, denoted CKM_SHA3_512_KEY_GEN, is a key 10374 generation mechanism for NIST’s SHA3-512-HMAC. 10375






6.32 SHAKE 10385


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SHAKE_128_KEY_DERIVATION

CKM_SHAKE_256_KEY_DERIVATION


CKM_SHAKE_128_KEY_DERIVATION 10388

CKM_SHAKE_256_KEY_DERIVATION 10389

6.32.2 SHAKE Key Derivation 10390

SHAKE-128 and SHAKE-256 key derivation, denoted CKM_SHAKE_128_KEY_DERIVATION and 10391 CKM_SHAKE_256_KEY_DERIVATION, implements the SHAKE expansion function defined in FIPS 202 10392

on the input key. 10393

If no length or key type is provided in the template a CKR_TEMPLATE_INCOMPLETE error is 10394 generated. 10395

If no key type is provided in the template, but a length is, then the key produced by this mechanism 10396 shall be a generic secret key of the specified length. 10397

If no length was provided in the template, but a key type is, then that key type must have a well-10398 defined length. If it does, then the key produced by this mechanism shall be of the type specified in 10399 the template. If it doesn’t, an error shall be returned. 10400

If both a key type and a length are provided in the template, the length must be compatible with that 10401 key type. The key produced by this mechanism shall be of the specified type and length. 10402

If a DES, DES2, or CDMF key is derived with this mechanism, the parity bits of the key shall be set 10403 properly. 10404



If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 10409 shall as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 10410 derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 10411 CKA_SENSITIVE attribute. 10412

Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then 10413 the derived key shall, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to 10414 CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite 10415 value from its CKA_EXTRACTABLE attribute. 10416

6.33 BLAKElake2Bb-160 10417

Table 170, BLAKElake2Bb-160 Mechanisms vs. Functions 10418


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_BLAKE2B_160

CKM_BLAKE2B_160_HMAC

CKM_BLAKE2B_160_HMAC_GENERAL

CKM_BLAKE2B_160_KEY_DERIVE

CKM_BLAKE2B_160_KEY_GEN


Mechanisms: 10420

CKM_BLAKE2B_160 10421

CKM_BLAKE2B_160_HMAC 10422

CKM_BLAKE2B_160_HMAC_GENERAL 10423

CKM_BLAKE2B_160_KEY_DERIVE 10424

CKM_BLAKE2B_160_KEY_GEN 10425

CKK_BLAKE2B_160_HMAC 10426

6.33.2 BLAKE2B-160 digest 10427

The BLAKE2B-160 mechanism, denoted CKM_BLAKE2B_160, is a mechanism for message digesting, 10428

following the Blake2b Algorithm with a 160-bit message digest without a key as defined in RFC 7693. 10429



Table 171, BLAKE2B-160: Data Length 10433


C_Digest any 20

6.33.3 General-length BLAKE2B-160-HMAC 10434

The general-length BLAKE2B-160-HMAC mechanism, denoted 10435 CKM_BLAKE2B_160_HMAC_GENERAL, is the keyed variant of BLAKE2b-160 and length of the output 10436

should be in the range 1-20. The keys it uses are generic secret keys and CKK_BLAKE2B_160_HMAC. 10437

It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired 10438 output. This length should be in the range 1-20 (the output size of BLAKE2B-160 is 20 bytes). Signatures 10439 (MACs) produced by this mechanism shall be taken from the start of the full 20-byte HMAC output. 10440

Table 172, General-length BLAKE2B-160-HMAC: Key And Data Length 10441




C_Sign generic secret or CKK_BLAKE2B_160_H

MAC


C_Verify generic secret or CKK_BLAKE2B_160_H

MAC


6.33.4 BLAKE2B-160-HMAC 10442

The BLAKE2B-160-HMAC mechanism, denoted CKM_BLAKE2B_160_HMAC, is a special case of the 10443

general-length BLAKE2B-160-HMAC mechanism. 10444


6.33.5 BLAKE2B-160 key derivation 10446

BLAKE2B-160 key derivation, denoted CKM_BLAKE2B_160_KEY_DERIVE, is the same as the SHA-1 10447 key derivation mechanism in Section 6.20.5 except that it uses the BLAKE2B-160 hash function and the 10448 relevant length is 20 bytes. 10449

6.33.6 BLAKE2B-160 HMAC key generation 10450

The BLAKE2B-160-HMAC key generation mechanism, denoted CKM_BLAKE2B_160_KEY_GEN, is a 10451

key generation mechanism for BLAKE2B-160-HMAC. 10452


The mechanism generates BLAKE2B-160-HMAC keys with a particular length in bytes, as specified in the 10454 CKA_VALUE_LEN attribute of the template for the key. 10455

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

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

6.34 BLAKE2B-256 10462

Table 173, BLAKE2B-256 Mechanisms vs. Functions 10463

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_BLAKE2B_256







Mechanisms: 10465







6.34.2 BLAKE2B-256 digest 10472


following the Blake2b Algorithm with a 256-bit message digest without a key as defined in RFC 7693. 10474





C_Digest any 32


The general-length BLAKE2B-256-HMAC mechanism, denoted 10480 CKM_BLAKE2B_256_HMAC_GENERAL, is the keyed variant of Blake2b-256 and length of the output 10481 should be in the range 1-32. The keys it uses are generic secret keys and CKK_BLAKE2B_256_HMAC. 10482




C_Sign generic secret or CKK_BLAKE2B_256_HM

AC


C_Verify generic secret or CKK_BLAKE2B_256_HM

AC


6.34.4 BLAKE2B-256-HMAC 10487


general-length BLAKE2B-256-HMAC mechanism in Section 6.22.36.34.3. 10489



BLAKE2B-256 key derivation, denoted CKM_BLAKE2B_256_KEY_DERIVE, is the same as the SHA-1 10492 key derivation mechanism in Section 6.20.5, except that it uses the BLAKE2B-256 hash function and the 10493 relevant length is 32 bytes. 10494

Field Code Changed



The BLAKE2B-256-HMAC key generation mechanism, denoted CKM_BLAKE2B_256_KEY_GEN, is a 10496 key generation mechanism for BLAKE2B-256-HMAC. 10497





6.35 BLAKE2B-384 10507

Table 176, BLAKE2B-384 Mechanisms vs. Functions 10508

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_BLAKE2B_384












6.35.2 BLAKE2B-384 digest 10516

The BLAKE2B-384 mechanism, denoted CKM_BLAKE2B_384, is a mechanism for message digesting, 10517 following the Blake2b Algorithm with a 384-bit message digest without a key as defined in RFC 7693. 10518






C_Digest any 48


The general-length BLAKE2B-384-HMAC mechanism, denoted 10524 CKM_BLAKE2B_384_HMAC_GENERAL, is the keyed variant of the BLAKElake2Bb-384 hash function 10525 and length of the output should be in the range 1-48.The keys it uses are generic secret keys and 10526 CKK_BLAKE2B_384_HMAC. 10527

10528

It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired output. 10529

This length should be in the range 1-48 (the output size of BLAKE2B-384 is 48 bytes). Signatures 10530 (MACs) produced by this mechanism shall be taken from the start of the full 48-byte HMAC output. 10531



C_Sign generic secret or CKK_BLAKE2B_384_H

MAC


C_Verify generic secret or CKK_BLAKE2B_384_H

MAC


10533

6.35.4 BLAKE2B-384-HMAC 10534





BLAKE2B-384 key derivation, denoted CKM_BLAKE2B_384_KEY_DERIVE, is the same as the SHA-1 10539 key derivation mechanism in Section 6.20.5, except that it uses the BLAKE2BSHA-384 hash function and 10540 the relevant length is 48 bytes. 10541



key generation mechanism for NIST’s BLAKE2B-384-HMAC. 10544





6.36 BLAKE2B-512 10554


Formatted: Font: (Default) CourierNew


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_BLAKE2B_512












6.36.2 BLAKE2B-512 digest 10563


following the Blake2b Algorithm with a 512-bit message digest defined in RFC 7693. 10565





C_Digest any 64


The general-length BLAKE2B-512-HMAC mechanism, denoted 10571 CKM_BLAKE2B_512_HMAC_GENERAL, is the keyed variant of the BLAKE2B-512 hash function and 10572 length of the output should be in the range 1-64.The keys it uses are generic secret keys and 10573 CKK_BLAKE2B_512_HMAC. 10574

10575





C_Sign generic secret or CKK_BLAKE2B_512_HM

AC


C_Verify generic secret or CKK_BLAKE2B_512_HM

AC


10580

6.36.4 BLAKE2B-512-HMAC 10581





BLAKE2B-512 key derivation, denoted CKM_BLAKE2B_512_KEY_DERIVE, is the same as the SHA-1 10586 key derivation mechanism in Section6.20.5, except that it uses the BLAKElake2Bb-512 hash function and 10587 the relevant length is 64 bytes. 10588



key generation mechanism for NIST’s BLAKE2B-512-HMAC. 10591





10601

6.37 PKCS #5 and PKCS #5-style password-based encryption (PBE) 10602

The mechanisms in this section are for generating keys and IVs for performing password-based 10603 encryption. The method used to generate keys and IVs is specified in PKCS #5. 10604

Table 182, PKCS 5 Mechanisms vs. Functions 10605

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_PBE_SHA1_DES3_EDE_CBC

CKM_PBE_SHA1_DES2_EDE_CBC

CKM_PBA_SHA1_WITH_SHA1_HMAC

CKM_PKCS5_PBKD2



Mechanisms: 10607

CKM_PBE_SHA1_DES3_EDE_CBC 10608

CKM_PBE_SHA1_DES2_EDE_CBC 10609

CKM_PKCS5_PBKD2 10610

CKM_PBA_SHA1_WITH_SHA1_HMAC 10611

6.37.2 Password-based encryption/authentication mechanism parameters 10612

CK_PBE_PARAMS; CK_PBE_PARAMS_PTR 10613

CK_PBE_PARAMS is a structure which provides all of the necessary information required by the 10614 CKM_PBE mechanisms (see PKCS #5 and PKCS #12 for information on the PBE generation 10615 mechanisms) and the CKM_PBA_SHA1_WITH_SHA1_HMAC mechanism. It is defined as follows: 10616

typedef struct CK_PBE_PARAMS { 10617

CK_BYTE_PTR pInitVector; 10618

CK_UTF8CHAR_PTR pPassword; 10619

CK_ULONG ulPasswordLen; 10620

CK_BYTE_PTR pSalt; 10621

CK_ULONG ulSaltLen; 10622

CK_ULONG ulIteration; 10623

} CK_PBE_PARAMS; 10624

10625


pInitVector pointer to the location that receives the 8-byte initialization vector 10627 (IV), if an IV is required; 10628

pPassword points to the password to be used in the PBE key generation; 10629

ulPasswordLen length in bytes of the password information; 10630

pSalt points to the salt to be used in the PBE key generation; 10631

ulSaltLen length in bytes of the salt information; 10632

ulIteration number of iterations required for the generation. 10633

CK_PBE_PARAMS_PTR is a pointer to a CK_PBE_PARAMS. 10634

6.37.3 PKCS #5 PBKDF2 key generation mechanism parameters 10635

CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE; 10636

CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE_PTR 10637

CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE is used to indicate the Pseudo-Random 10638

Function (PRF) used to generate key bits using PKCS #5 PBKDF2. It is defined as follows: 10639

typedef CK_ULONG CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE; 10640

10641

The following PRFs are defined in PKCS #5 v2.1. The following table lists the defined functions. 10642

Table 183, PKCS #5 PBKDF2 Key Generation: Pseudo-random functions 10643


PRF Identifier Value Parameter Type

CKP_PKCS5_PBKD2_HMAC_SHA1 0x00000001UL No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero.

CKP_PKCS5_PBKD2_HMAC_GOSTR3411

0x00000002UL

This PRF uses GOST R34.11-94 hash to produce secret key value. pPrfData should point to DER-encoded OID, indicating GOSTR34.11-94 parameters. ulPrfDataLen holds encoded OID length in bytes. If pPrfData is set to NULL_PTR, then id-GostR3411-94-CryptoProParamSet parameters will be used (RFC 4357, 11.2), and ulPrfDataLen must be 0.





CKP_PKCS5_PBKD2_HMAC_SHA512_224 0x00000007UL No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero.

CKP_PKCS5_PBKD2_HMAC_SHA512_256 0x00000008UL No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero.

CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE_PTR is a pointer to a 10644 CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE. 10645

10646

CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE; 10647

CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE_PTR 10648

CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE is used to indicate the source of the salt value when 10649 deriving a key using PKCS #5 PBKDF2. It is defined as follows: 10650

typedef CK_ULONG CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE; 10651

10652

The following salt value sources are defined in PKCS #5 v2.1. The following table lists the defined 10653 sources along with the corresponding data type for the pSaltSourceData field in the 10654 CK_PKCS5_PBKD2_PARAMS2 structure defined below. 10655

Table 184, PKCS #5 PBKDF2 Key Generation: Salt sources 10656

Source Identifier Value Data Type


CKZ_SALT_SPECIFIED 0x00000001 Array of CK_BYTE containing the value of the salt value.

CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE_PTR is a pointer to a 10657 CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE. 10658

CK_PKCS5_PBKD2_PARAMS2; CK_PKCS5_PBKD2_PARAMS2_PTR 10659

CK_PKCS5_PBKD2_PARAMS2 is a structure that provides the parameters to the 10660 CKM_PKCS5_PBKD2 mechanism. The structure is defined as follows: 10661

typedef struct CK_PKCS5_PBKD2_PARAMS2 { 10662

CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE saltSource; 10663

CK_VOID_PTR pSaltSourceData; 10664

CK_ULONG ulSaltSourceDataLen; 10665

CK_ULONG iterations; 10666

CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE prf; 10667

CK_VOID_PTR pPrfData; 10668

CK_ULONG ulPrfDataLen; 10669

CK_UTF8CHAR_PTR pPassword; 10670

CK_ULONG ulPasswordLen; 10671

} CK_PKCS5_PBKD2_PARAMS2; 10672

10673


saltSource source of the salt value 10675

pSaltSourceData data used as the input for the salt source 10676

ulSaltSourceDataLen length of the salt source input 10677

iterations number of iterations to perform when generating each block of 10678 random data 10679

prf pseudo-random function used to generate the key 10680

pPrfData data used as the input for PRF in addition to the salt value 10681

ulPrfDataLen length of the input data for the PRF 10682

pPassword points to the password to be used in the PBE key generation 10683

ulPasswordLen length in bytes of the password information 10684

CK_PKCS5_PBKD2_PARAMS2_PTR is a pointer to a CK_PKCS5_PBKD2_PARAMS2. 10685

6.37.4 PKCS #5 PBKD2 key generation 10686

PKCS #5 PBKDF2 key generation, denoted CKM_PKCS5_PBKD2, is a mechanism used for generating 10687

a secret key from a password and a salt value. This functionality is defined in PKCS#5 as PBKDF2. 10688

It has a parameter, a CK_PKCS5_PBKD2_PARAMS2 structure. The parameter specifies the salt value 10689

source, pseudo-random function, and iteration count used to generate the new key. 10690

Since this mechanism can be used to generate any type of secret key, new key templates must contain 10691 the CKA_KEY_TYPE and CKA_VALUE_LEN attributes. If the key type has a fixed length the 10692 CKA_VALUE_LEN attribute may be omitted. 10693


6.38 PKCS #12 password-based encryption/authentication 10694

mechanisms 10695

The mechanisms in this section are for generating keys and IVs for performing password-based 10696 encryption or authentication. The method used to generate keys and IVs is based on a method that was 10697 specified in PKCS #12. 10698

We specify here a general method for producing various types of pseudo-random bits from a password, 10699 p; a string of salt bits, s; and an iteration count, c. The “type” of pseudo-random bits to be produced is 10700 identified by an identification byte, ID, the meaning of which will be discussed later. 10701

Let H be a hash function built around a compression function f: Z2u Z2

v Z2

u (that is, H has a chaining 10702

variable and output of length u bits, and the message input to the compression function of H is v bits). 10703 For MD2 and MD5, u=128 and v=512; for SHA-1, u=160 and v=512. 10704

We assume here that u and v are both multiples of 8, as are the lengths in bits of the password and salt 10705 strings and the number n of pseudo-random bits required. In addition, u and v are of course nonzero. 10706

1. Construct a string, D (the “diversifier”), by concatenating v/8 copies of ID. 10707

2. Concatenate copies of the salt together to create a string S of length vs/v bits (the final copy of the 10708 salt may be truncated to create S). Note that if the salt is the empty string, then so is S. 10709

3. Concatenate copies of the password together to create a string P of length vp/v bits (the final copy 10710 of the password may be truncated to create P). Note that if the password is the empty string, then so 10711 is P. 10712

4. Set I=S||P to be the concatenation of S and P. 10713

5. Set j=n/u. 10714

6. For i=1, 2, …, j, do the following: 10715

a. Set Ai=Hc(D||I), the c

th hash of D||I. That is, compute the hash of D||I; compute the hash of 10716

that hash; etc.; continue in this fashion until a total of c hashes have been computed, each on 10717

the result of the previous hash. 10718

b. Concatenate copies of Ai to create a string B of length v bits (the final copy of Ai may be 10719 truncated to create B). 10720

c. Treating I as a concatenation I0, I1, …, Ik-1 of v-bit blocks, where k=s/v+p/v, modify I by 10721 setting Ij=(Ij+B+1) mod 2

v for each j. To perform this addition, treat each v-bit block as a 10722

binary number represented most-significant bit first. 10723

7. Concatenate A1, A2, …, Aj together to form a pseudo-random bit string, A. 10724

8. Use the first n bits of A as the output of this entire process. 10725

When the password-based encryption mechanisms presented in this section are used to generate a key 10726 and IV (if needed) from a password, salt, and an iteration count, the above algorithm is used. To 10727 generate a key, the identifier byte ID is set to the value 1; to generate an IV, the identifier byte ID is set to 10728

the value 2. 10729

When the password based authentication mechanism presented in this section is used to generate a key 10730 from a password, salt, and an iteration count, the above algorithm is used. The identifier byte ID is set to 10731

the value 3. 10732

6.38.1 SHA-1-PBE for 3-key triple-DES-CBC 10733

SHA-1-PBE for 3-key triple-DES-CBC, denoted CKM_PBE_SHA1_DES3_EDE_CBC, is a mechanism 10734 used for generating a 3-key triple-DES secret key and IV from a password and a salt value by using the 10735 SHA-1 digest algorithm and an iteration count. The method used to generate the key and IV is described 10736 above. Each byte of the key produced will have its low-order bit adjusted, if necessary, so that a valid 3-10737 key triple-DES key with proper parity bits is obtained. 10738


It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the 10739 key generation process and the location of the application-supplied buffer which will receive the 8-byte IV 10740 generated by the mechanism. 10741

The key and IV produced by this mechanism will typically be used for performing password-based 10742 encryption. 10743

6.38.2 SHA-1-PBE for 2-key triple-DES-CBC 10744

SHA-1-PBE for 2-key triple-DES-CBC, denoted CKM_PBE_SHA1_DES2_EDE_CBC, is a mechanism 10745 used for generating a 2-key triple-DES secret key and IV from a password and a salt value by using the 10746 SHA-1 digest algorithm and an iteration count. The method used to generate the key and IV is described 10747 above. Each byte of the key produced will have its low-order bit adjusted, if necessary, so that a valid 2-10748 key triple-DES key with proper parity bits is obtained. 10749

It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the 10750 key generation process and the location of the application-supplied buffer which will receive the 8-byte IV 10751 generated by the mechanism. 10752

The key and IV produced by this mechanism will typically be used for performing password-based 10753 encryption. 10754

6.38.3 SHA-1-PBA for SHA-1-HMAC 10755

SHA-1-PBA for SHA-1-HMAC, denoted CKM_PBA_SHA1_WITH_SHA1_HMAC, is a mechanism used 10756 for generating a 160-bit generic secret key from a password and a salt value by using the SHA-1 digest 10757 algorithm and an iteration count. The method used to generate the key is described above. 10758

It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the 10759 key generation process. The parameter also has a field to hold the location of an application-supplied 10760 buffer which will receive an IV; for this mechanism, the contents of this field are ignored, since 10761 authentication with SHA-1-HMAC does not require an IV. 10762

The key generated by this mechanism will typically be used for computing a SHA-1 HMAC to perform 10763 password-based authentication (not password-based encryption). At the time of this writing, this is 10764

primarily done to ensure the integrity of a PKCS #12 PDU. 10765

6.39 SSL 10766

Table 185,SSL Mechanisms vs. Functions 10767

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SSL3_PRE_MASTER_KEY_GEN

CKM_TLS_PRE_MASTER_KEY_GEN

CKM_SSL3_MASTER_KEY_DERIVE

CKM_SSL3_MASTER_KEY_DERIVE_DH

CKM_SSL3_KEY_AND_MAC_DERIVE

CKM_SSL3_MD5_MAC

CKM_SSL3_SHA1_MAC



Mechanisms: 10769

CKM_SSL3_PRE_MASTER_KEY_GEN 10770

CKM_TLS_PRE_MASTER_KEY_GEN 10771

CKM_SSL3_MASTER_KEY_DERIVE 10772

CKM_SSL3_KEY_AND_MAC_DERIVE 10773

CKM_SSL3_MASTER_KEY_DERIVE_DH 10774

CKM_SSL3_MD5_MAC 10775

CKM_SSL3_SHA1_MAC 10776

6.39.2 SSL mechanism parameters 10777

CK_SSL3_RANDOM_DATA 10778

CK_SSL3_RANDOM_DATA is a structure which provides information about the random data of a client 10779 and a server in an SSL context. This structure is used by both the CKM_SSL3_MASTER_KEY_DERIVE 10780 and the CKM_SSL3_KEY_AND_MAC_DERIVE mechanisms. It is defined as follows: 10781

typedef struct CK_SSL3_RANDOM_DATA { 10782

CK_BYTE_PTR pClientRandom; 10783

CK_ULONG ulClientRandomLen; 10784

CK_BYTE_PTR pServerRandom; 10785

CK_ULONG ulServerRandomLen; 10786

} CK_SSL3_RANDOM_DATA; 10787

10788


pClientRandom pointer to the client’s random data 10790

ulClientRandomLen length in bytes of the client’s random data 10791

pServerRandom pointer to the server’s random data 10792

ulServerRandomLen length in bytes of the server’s random data 10793

CK_SSL3_MASTER_KEY_DERIVE_PARAMS; 10794

CK_SSL3_MASTER_KEY_DERIVE_PARAMS_PTR 10795

CK_SSL3_MASTER_KEY_DERIVE_PARAMS is a structure that provides the parameters to the 10796 CKM_SSL3_MASTER_KEY_DERIVE mechanism. It is defined as follows: 10797

typedef struct CK_SSL3_MASTER_KEY_DERIVE_PARAMS { 10798

CK_SSL3_RANDOM_DATA RandomInfo; 10799

CK_VERSION_PTR pVersion; 10800

} CK_SSL3_MASTER_KEY_DERIVE_PARAMS; 10801

10802


RandomInfo client’s and server’s random data information. 10804

pVersion pointer to a CK_VERSION structure which receives the SSL 10805 protocol version information 10806


CK_SSL3_MASTER_KEY_DERIVE_PARAMS_PTR is a pointer to a 10807 CK_SSL3_MASTER_KEY_DERIVE_PARAMS. 10808

CK_SSL3_KEY_MAT_OUT; CK_SSL3_KEY_MAT_OUT_PTR 10809

CK_SSL3_KEY_MAT_OUT is a structure that contains the resulting key handles and initialization vectors 10810 after performing a C_DeriveKey function with the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. It 10811

is defined as follows: 10812

typedef struct CK_SSL3_KEY_MAT_OUT { 10813

CK_OBJECT_HANDLE hClientMacSecret; 10814

CK_OBJECT_HANDLE hServerMacSecret; 10815

CK_OBJECT_HANDLE hClientKey; 10816

CK_OBJECT_HANDLE hServerKey; 10817

CK_BYTE_PTR pIVClient; 10818

CK_BYTE_PTR pIVServer; 10819

} CK_SSL3_KEY_MAT_OUT; 10820

10821


hClientMacSecret key handle for the resulting Client MAC Secret key 10823

hServerMacSecret key handle for the resulting Server MAC Secret key 10824

hClientKey key handle for the resulting Client Secret key 10825

hServerKey key handle for the resulting Server Secret key 10826

pIVClient pointer to a location which receives the initialization vector (IV) 10827 created for the client (if any) 10828

pIVServer pointer to a location which receives the initialization vector (IV) 10829 created for the server (if any) 10830

CK_SSL3_KEY_MAT_OUT_PTR is a pointer to a CK_SSL3_KEY_MAT_OUT. 10831

CK_SSL3_KEY_MAT_PARAMS; CK_SSL3_KEY_MAT_PARAMS_PTR 10832

CK_SSL3_KEY_MAT_PARAMS is a structure that provides the parameters to the 10833 CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. It is defined as follows: 10834

typedef struct CK_SSL3_KEY_MAT_PARAMS { 10835

CK_ULONG ulMacSizeInBits; 10836

CK_ULONG ulKeySizeInBits; 10837

CK_ULONG ulIVSizeInBits; 10838

CK_BBOOL bIsExport; 10839


CK_SSL3_KEY_MAT_OUT_PTR pReturnedKeyMaterial; 10841

} CK_SSL3_KEY_MAT_PARAMS; 10842

10843


ulMacSizeInBits the length (in bits) of the MACing keys agreed upon during the 10845 protocol handshake phase 10846

ulKeySizeInBits the length (in bits) of the secret keys agreed upon during the 10847 protocol handshake phase 10848


ulIVSizeInBits the length (in bits) of the IV agreed upon during the protocol 10849 handshake phase. If no IV is required, the length should be set to 0 10850

bIsExport a Boolean value which indicates whether the keys have to be 10851 derived for an export version of the protocol 10852


pReturnedKeyMaterial points to a CK_SSL3_KEY_MAT_OUT structures which receives 10854 the handles for the keys generated and the IVs 10855

CK_SSL3_KEY_MAT_PARAMS_PTR is a pointer to a CK_SSL3_KEY_MAT_PARAMS. 10856

6.39.3 Pre-master key generation 10857

Pre-master key generation in SSL 3.0, denoted CKM_SSL3_PRE_MASTER_KEY_GEN, is a mechanism 10858 which generates a 48-byte generic secret key. It is used to produce the "pre_master" key used in SSL 10859 version 3.0 for RSA-like cipher suites. 10860

It has one parameter, a CK_VERSION structure, which provides the client’s SSL version number. 10861

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 10862 key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may 10863

be specified in the template, or else are assigned default values. 10864

The template sent along with this mechanism during a C_GenerateKey call may indicate that the object 10865 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN 10866 attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to 10867 specify any of them. 10868

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 10869 both indicate 48 bytes. 10870

CKM_TLS_PRE_MASTER_KEY_GEN has identical functionality as 10871 CKM_SSL3_PRE_MASTER_KEY_GEN. It exists only for historical reasons, please use 10872 CKM_SSL3_PRE_MASTER_KEY_GEN instead. 10873

6.39.4 Master key derivation 10874

Master key derivation in SSL 3.0, denoted CKM_SSL3_MASTER_KEY_DERIVE, is a mechanism used 10875 to derive one 48-byte generic secret key from another 48-byte generic secret key. It is used to produce 10876 the "master_secret" key used in the SSL protocol from the "pre_master" key. This mechanism returns the 10877 value of the client version, which is built into the "pre_master" key as well as a handle to the derived 10878 "master_secret" key. 10879

It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the 10880 passing of random data to the token as well as the returning of the protocol version number which is part 10881 of the pre-master key. This structure is defined in Section 6.39. 10882


be specified in the template; otherwise they are assigned default values. 10885

The template sent along with this mechanism during a C_DeriveKey call may indicate that the object 10886 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN 10887 attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to 10888 specify any of them. 10889



If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key 10894 will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the 10895


derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its 10896 CKA_SENSITIVE attribute. 10897



both indicate 48 bytes. 10903

Note that the CK_VERSION structure pointed to by the CK_SSL3_MASTER_KEY_DERIVE_PARAMS 10904 structure’s pVersion field will be modified by the C_DeriveKey call. In particular, when the call returns, 10905

this structure will hold the SSL version associated with the supplied pre_master key. 10906

Note that this mechanism is only useable for cipher suites that use a 48-byte “pre_master” secret with an 10907 embedded version number. This includes the RSA cipher suites, but excludes the Diffie-Hellman cipher 10908 suites. 10909

6.39.5 Master key derivation for Diffie-Hellman 10910

Master key derivation for Diffie-Hellman in SSL 3.0, denoted CKM_SSL3_MASTER_KEY_DERIVE_DH, 10911 is a mechanism used to derive one 48-byte generic secret key from another arbitrary length generic 10912 secret key. It is used to produce the "master_secret" key used in the SSL protocol from the "pre_master" 10913 key. 10914

It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the 10915 passing of random data to the token. This structure is defined in Section 6.39. The pVersion field of the 10916 structure must be set to NULL_PTR since the version number is not embedded in the "pre_master" key 10917 as it is for RSA-like cipher suites. 10918










Note that this mechanism is only useable for cipher suites that do not use a fixed length 48-byte 10940 “pre_master” secret with an embedded version number. This includes the Diffie-Hellman cipher suites, but 10941 excludes the RSA cipher suites. 10942


6.39.6 Key and MAC derivation 10943

Key, MAC and IV derivation in SSL 3.0, denoted CKM_SSL3_KEY_AND_MAC_DERIVE, is a 10944 mechanism used to derive the appropriate cryptographic keying material used by a "CipherSuite" from the 10945 "master_secret" key and random data. This mechanism returns the key handles for the keys generated in 10946 the process, as well as the IVs created. 10947

It has a parameter, a CK_SSL3_KEY_MAT_PARAMS structure, which allows for the passing of random 10948 data as well as the characteristic of the cryptographic material for the given CipherSuite and a pointer to a 10949 structure which receives the handles and IVs which were generated. This structure is defined in Section 10950 6.39. 10951

This mechanism contributes to the creation of four distinct keys on the token and returns two IVs (if IVs 10952 are requested by the caller) back to the caller. The keys are all given an object class of 10953 CKO_SECRET_KEY. 10954

The two MACing keys ("client_write_MAC_secret" and "server_write_MAC_secret") are always given a 10955 type of CKK_GENERIC_SECRET. They are flagged as valid for signing, verification, and derivation 10956

operations. 10957

The other two keys ("client_write_key" and "server_write_key") are typed according to information found 10958 in the template sent along with this mechanism during a C_DeriveKey function call. By default, they are 10959

flagged as valid for encryption, decryption, and derivation operations. 10960

IVs will be generated and returned if the ulIVSizeInBits field of the CK_SSL3_KEY_MAT_PARAMS field 10961 has a nonzero value. If they are generated, their length in bits will agree with the value in the 10962 ulIVSizeInBits field. 10963

All four keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, 10964 CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template 10965 provided to C_DeriveKey may not specify values for any of these attributes which differ from those held 10966

by the base key. 10967

Note that the CK_SSL3_KEY_MAT_OUT structure pointed to by the CK_SSL3_KEY_MAT_PARAMS 10968 structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the four 10969 key handle fields in the CK_SSL3_KEY_MAT_OUT structure will be modified to hold handles to the 10970 newly-created keys; in addition, the buffers pointed to by the CK_SSL3_KEY_MAT_OUT structure’s 10971 pIVClient and pIVServer fields will have IVs returned in them (if IVs are requested by the caller). 10972

Therefore, these two fields must point to buffers with sufficient space to hold any IVs that will be returned. 10973

This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. 10974 For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result of a 10975 successful completion. However, since the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism returns 10976 all of its key handles in the CK_SSL3_KEY_MAT_OUT structure pointed to by the 10977 CK_SSL3_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey 10978 passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. 10979

If a call to C_DeriveKey with this mechanism fails, then none of the four keys will be created on the 10980

token. 10981

6.39.7 MD5 MACing in SSL 3.0 10982

MD5 MACing in SSL3.0, denoted CKM_SSL3_MD5_MAC, is a mechanism for single- and multiple-part 10983 signatures (data authentication) and verification using MD5, based on the SSL 3.0 protocol. This 10984 technique is very similar to the HMAC technique. 10985

It has a parameter, a CK_MAC_GENERAL_PARAMS, which specifies the length in bytes of the 10986

signatures produced by this mechanism. 10987

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

Table 186, MD5 MACing in SSL 3.0: Key And Data Length 10989



C_Sign generic secret any 4-8, depending on parameters

C_Verify generic secret any 4-8, depending on parameters

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

6.39.8 SHA-1 MACing in SSL 3.0 10992

SHA-1 MACing in SSL3.0, denoted CKM_SSL3_SHA1_MAC, is a mechanism for single- and multiple-10993 part signatures (data authentication) and verification using SHA-1, based on the SSL 3.0 protocol. This 10994 technique is very similar to the HMAC technique. 10995

It has a parameter, a CK_MAC_GENERAL_PARAMS, which specifies the length in bytes of the 10996

signatures produced by this mechanism. 10997


Table 187, SHA-1 MACing in SSL 3.0: Key And Data Length 10999

Function Key type Data length

Signature length

C_Sign generic secret any 4-8, depending on parameters

C_Verify generic secret any 4-8, depending on parameters

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

6.40 TLS 1.2 Mechanisms 11002

Details for TLS 1.2 and its key derivation and MAC mechanisms can be found in [TLS12]. TLS 1.2 11003 mechanisms differ from TLS 1.0 and 1.1 mechanisms in that the base hash used in the underlying TLS 11004 PRF (pseudo-random function) can be negotiated. Therefore each mechanism parameter for the TLS 1.2 11005 mechanisms contains a new value in the parameters structure to specify the hash function. 11006

This section also specifies CKM_TLS12_MAC which should be used in place of CKM_TLS_PRF to 11007 calculate the verify_data in the TLS "finished" message. 11008

This section also specifies CKM_TLS_KDF that can be used in place of CKM_TLS_PRF to implement 11009 key material exporters. 11010

11011

Table 188, TLS 1.2 Mechanisms vs. Functions 11012

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_TLS12_MASTER_KEY_DERIVE

CKM_TLS12_MASTER_KEY_DERIVE_DH

CKM_TLS12_KEY_AND_MAC_DERIVE

CKM_TLS12_KEY_SAFE_DERIVE

CKM_TLS_KDF

CKM_TLS12_MAC


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_TLS12_KDF


Mechanisms: 11014

CKM_TLS12_MASTER_KEY_DERIVE 11015

CKM_TLS12_MASTER_KEY_DERIVE_DH 11016

CKM_TLS12_KEY_AND_MAC_DERIVE 11017

CKM_TLS12_KEY_SAFE_DERIVE 11018

CKM_TLS_KDF 11019

CKM_TLS12_MAC 11020

CKM_TLS12_KDF 11021

6.40.2 TLS 1.2 mechanism parameters 11022

CK_TLS12_MASTER_KEY_DERIVE_PARAMS; 11023

CK_TLS12_MASTER_KEY_DERIVE_PARAMS_PTR 11024

CK_TLS12_MASTER_KEY_DERIVE_PARAMS is a structure that provides the parameters to the 11025 CKM_TLS12_MASTER_KEY_DERIVE mechanism. It is defined as follows: 11026

typedef struct CK_TLS12_MASTER_KEY_DERIVE_PARAMS { 11027


CK_VERSION_PTR pVersion; 11029

CK_MECHANISM_TYPE prfHashMechanism; 11030

} CK_TLS12_MASTER_KEY_DERIVE_PARAMS; 11031

11032



pVersion pointer to a CK_VERSION structure which receives the SSL 11035 protocol version information 11036

prfHashMechanism base hash used in the underlying TLS1.2 PRF operation used to 11037 derive the master key. 11038

11039

CK_TLS12_MASTER_KEY_DERIVE_PARAMS_PTR is a pointer to a 11040 CK_TLS12_MASTER_KEY_DERIVE_PARAMS. 11041

CK_TLS12_KEY_MAT_PARAMS; CK_TLS12_KEY_MAT_PARAMS_PTR 11042

CK_TLS12_KEY_MAT_PARAMS is a structure that provides the parameters to the 11043 CKM_TLS12_KEY_AND_MAC_DERIVE mechanism. It is defined as follows: 11044

typedef struct CK_TLS12_KEY_MAT_PARAMS { 11045







CK_SSL3_KEY_MAT_OUT_PTR pReturnedKeyMaterial; 11051


} CK_TLS12_KEY_MAT_PARAMS; 11053

11054


ulMacSizeInBits the length (in bits) of the MACing keys agreed upon during the 11056 protocol handshake phase. If no MAC key is required, the length 11057 should be set to 0. 11058

ulKeySizeInBits the length (in bits) of the secret keys agreed upon during the 11059 protocol handshake phase 11060

ulIVSizeInBits the length (in bits) of the IV agreed upon during the protocol 11061 handshake phase. If no IV is required, the length should be set to 0 11062

bIsExport must be set to CK_FALSE because export cipher suites must not be 11063 used in TLS 1.1 and later. 11064


pReturnedKeyMaterial points to a CK_SSL3_KEY_MAT_OUT structures which receives 11066 the handles for the keys generated and the IVs 11067

prfHashMechanism base hash used in the underlying TLS1.2 PRF operation used to 11068 derive the master key. 11069

CK_TLS12_KEY_MAT_PARAMS_PTR is a pointer to a CK_TLS12_KEY_MAT_PARAMS. 11070

CK_TLS_KDF_PARAMS; CK_TLS_KDF_PARAMS_PTR 11071

CK_TLS_KDF_PARAMS is a structure that provides the parameters to the CKM_TLS_KDF mechanism. 11072


typedef struct CK_TLS_KDF_PARAMS { 11074

CK_MECHANISM_TYPE prfMechanism; 11075

CK_BYTE_PTR pLabel; 11076

CK_ULONG ulLabelLength; 11077


CK_BYTE_PTR pContextData; 11079

CK_ULONG ulContextDataLength; 11080

} CK_TLS_KDF_PARAMS; 11081

11082


prfMechanism the hash mechanism used in the TLS1.2 PRF construct or 11084 CKM_TLS_PRF to use with the TLS1.0 and 1.1 PRF construct. 11085

pLabel a pointer to the label for this key derivation 11086

ulLabelLength length of the label in bytes 11087

RandomInfo the random data for the key derivation 11088


pContextData a pointer to the context data for this key derivation. NULL_PTR if not 11089 present 11090

ulContextDataLength length of the context data in bytes. 0 if not present. 11091

CK_TLS_KDF_PARAMS_PTR is a pointer to a CK_TLS_KDF_PARAMS. 11092

CK_TLS_MAC_PARAMS; CK_TLS_MAC_PARAMS_PTR 11093

CK_TLS_MAC_PARAMS is a structure that provides the parameters to the CKM_TLS_MAC 11094

mechanism. It is defined as follows: 11095

typedef struct CK_TLS_MAC_PARAMS { 11096


CK_ULONG ulMacLength; 11098

CK_ULONG ulServerOrClient; 11099

} CK_TLS_MAC_PARAMS; 11100

11101


prfHashMechanism the hash mechanism used in the TLS12 PRF construct or 11103 CKM_TLS_PRF to use with the TLS1.0 and 1.1 PRF construct. 11104

ulMacLength the length of the MAC tag required or offered. Always 12 octets in 11105 TLS 1.0 and 1.1. Generally 12 octets, but may be negotiated to a 11106 longer value in TLS1.2. 11107

ulServerOrClient 1 to use the label "server finished", 2 to use the label "client 11108 finished". All other values are invalid. 11109

CK_TLS_MAC_PARAMS_PTR is a pointer to a CK_TLS_MAC_PARAMS. 11110

11111

CK_TLS_PRF_PARAMS; CK_TLS_PRF_PARAMS_PTR 11112

CK_TLS_PRF_PARAMS is a structure, which provides the parameters to the CKM_TLS_PRF 11113


typedef struct CK_TLS_PRF_PARAMS { 11115




CK_ULONG ulLabelLen; 11119

CK_BYTE_PTR pOutput; 11120

CK_ULONG_PTR pulOutputLen; 11121

} CK_TLS_PRF_PARAMS; 11122

11123


pSeed pointer to the input seed 11125

ulSeedLen length in bytes of the input seed 11126

pLabel pointer to the identifying label 11127

ulLabelLen length in bytes of the identifying label 11128

pOutput pointer receiving the output of the operation 11129


pulOutputLen pointer to the length in bytes that the output to be created shall 11130 have, has to hold the desired length as input and will receive the 11131 calculated length as output 11132

CK_TLS_PRF_PARAMS_PTR is a pointer to a CK_TLS_PRF_PARAMS. 11133

6.40.3 TLS MAC 11134

The TLS MAC mechanism is used to generate integrity tags for the TLS "finished" message. It replaces 11135 the use of the CKM_TLS_PRF function for TLS1.0 and 1.1 and that mechanism is deprecated. 11136

CKM_TLS_MAC takes a parameter of CK_TLS_MAC_PARAMS. To use this mechanism with TLS1.0 11137 and TLS1.1, use CKM_TLS_PRF as the value for prfMechanism in place of a hash mechanism. Note: 11138 Although CKM_TLS_PRF is deprecated as a mechanism for C_DeriveKey, the manifest value is retained 11139 for use with this mechanism to indicate the use of the TLS1.0/1.1 pseudo-random function. 11140

In TLS1.0 and 1.1 the "finished" message verify_data (i.e. the output signature from the MAC mechanism) 11141 is always 12 bytes. In TLS1.2 the "finished" message verify_data is a minimum of 12 bytes, defaults to 12 11142 bytes, but may be negotiated to longer length. 11143

Table 189, General-length TLS MAC: Key And Data Length 11144


C_Sign generic secret any >=12 bytes

C_Verify generic secret any >=12 bytes

11145

6.40.4 Master key derivation 11146

Master key derivation in TLS 1.0, denoted CKM_TLS_MASTER_KEY_DERIVE, is a mechanism used to 11147 derive one 48-byte generic secret key from another 48-byte generic secret key. It is used to produce the 11148 "master_secret" key used in the TLS protocol from the "pre_master" key. This mechanism returns the 11149 value of the client version, which is built into the "pre_master" key as well as a handle to the derived 11150 "master_secret" key. 11151

It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the 11152 passing of random data to the token as well as the returning of the protocol version number which is part 11153 of the pre-master key. This structure is defined in Section 6.39. 11154



The mechanism also contributes the CKA_ALLOWED_MECHANISMS attribute consisting only of 11158 CKM_TLS12_KEY_AND_MAC_DERIVE, CKM_TLS12_KEY_SAFE_DERIVE, CKM_TLS12_KDF and 11159 CKM_TLS12_MAC. 11160









Note that the CK_VERSION structure pointed to by the CK_SSL3_MASTER_KEY_DERIVE_PARAMS 11179 structure’s pVersion field will be modified by the C_DeriveKey call. In particular, when the call returns, 11180

this structure will hold the SSL version associated with the supplied pre_master key. 11181

Note that this mechanism is only useable for cipher suites that use a 48-byte “pre_master” secret with an 11182 embedded version number. This includes the RSA cipher suites, but excludes the Diffie-Hellman cipher 11183 suites. 11184

6.40.5 Master key derivation for Diffie-Hellman 11185

Master key derivation for Diffie-Hellman in TLS 1.0, denoted CKM_TLS_MASTER_KEY_DERIVE_DH, is 11186 a mechanism used to derive one 48-byte generic secret key from another arbitrary length generic secret 11187 key. It is used to produce the "master_secret" key used in the TLS protocol from the "pre_master" key. 11188

It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the 11189 passing of random data to the token. This structure is defined in Section 6.39. The pVersion field of the 11190 structure must be set to NULL_PTR since the version number is not embedded in the "pre_master" key 11191 as it is for RSA-like cipher suites. 11192



The mechanism also contributes the CKA_ALLOWED_MECHANISMS attribute consisting only of 11196 CKM_TLS12_KEY_AND_MAC_DERIVE, CKM_TLS12_KEY_SAFE_DERIVE, CKM_TLS12_KDF and 11197 CKM_TLS12_MAC. 11198








Note that this mechanism is only useable for cipher suites that do not use a fixed length 48-byte 11217 “pre_master” secret with an embedded version number. This includes the Diffie-Hellman cipher suites, but 11218 excludes the RSA cipher suites. 11219


6.40.6 Key and MAC derivation 11220

Key, MAC and IV derivation in TLS 1.0, denoted CKM_TLS_KEY_AND_MAC_DERIVE, is a mechanism 11221 used to derive the appropriate cryptographic keying material used by a "CipherSuite" from the 11222 "master_secret" key and random data. This mechanism returns the key handles for the keys generated in 11223 the process, as well as the IVs created. 11224

It has a parameter, a CK_SSL3_KEY_MAT_PARAMS structure, which allows for the passing of random 11225 data as well as the characteristic of the cryptographic material for the given CipherSuite and a pointer to a 11226 structure which receives the handles and IVs which were generated. This structure is defined in Section 11227 6.39. 11228

This mechanism contributes to the creation of four distinct keys on the token and returns two IVs (if IVs 11229 are requested by the caller) back to the caller. The keys are all given an object class of 11230 CKO_SECRET_KEY. 11231

The two MACing keys ("client_write_MAC_secret" and "server_write_MAC_secret") (if present) are 11232 always given a type of CKK_GENERIC_SECRET. They are flagged as valid for signing and verification. 11233

The other two keys ("client_write_key" and "server_write_key") are typed according to information found 11234 in the template sent along with this mechanism during a C_DeriveKey function call. By default, they are 11235

flagged as valid for encryption, decryption, and derivation operations. 11236

For CKM_TLS12_KEY_AND_MAC_DERIVE, IVs will be generated and returned if the ulIVSizeInBits 11237 field of the CK_SSL3_KEY_MAT_PARAMS field has a nonzero value. If they are generated, their length 11238 in bits will agree with the value in the ulIVSizeInBits field. 11239

11240

Note Well: CKM_TLS12_KEY_AND_MAC_DERIVE produces both private (key) and public (IV) 11241 data. It is possible to "leak" private data by the simple expedient of decreasing the length of 11242 private data requested. E.g. Setting ulMacSizeInBits and ulKeySizeInBits to 0 (or other lengths 11243 less than the key size) will result in the private key data being placed in the destination 11244 designated for the IV's. Repeated calls with the same master key and same RandomInfo but with 11245

differing lengths for the private key material will result in different data being leaked.< 11246

11247

All four keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, 11248 CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template 11249 provided to C_DeriveKey may not specify values for any of these attributes which differ from those held 11250 by the base key. 11251

Note that the CK_SSL3_KEY_MAT_OUT structure pointed to by the CK_SSL3_KEY_MAT_PARAMS 11252 structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the four 11253 key handle fields in the CK_SSL3_KEY_MAT_OUT structure will be modified to hold handles to the 11254 newly-created keys; in addition, the buffers pointed to by the CK_SSL3_KEY_MAT_OUT structure’s 11255 pIVClient and pIVServer fields will have IVs returned in them (if IVs are requested by the caller). 11256

Therefore, these two fields must point to buffers with sufficient space to hold any IVs that will be returned. 11257

This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. 11258 For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result of a 11259 successful completion. However, since the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism returns 11260 all of its key handles in the CK_SSL3_KEY_MAT_OUT structure pointed to by the 11261 CK_SSL3_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey 11262 passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. 11263

If a call to C_DeriveKey with this mechanism fails, then none of the four keys will be created on the 11264

token. 11265

6.40.7 CKM_TLS12_KEY_SAFE_DERIVE 11266

CKM_TLS12_KEY_SAFE_DERIVE is identical to CKM_TLS12_KEY_AND_MAC_DERIVE except that it 11267 shall never produce IV data, and the ulIvSizeInBits field of CK_TLS12_KEY_MAT_PARAMS is ignored 11268


and treated as 0. All of the other conditions and behavior described for 11269 CKM_TLS12_KEY_AND_MAC_DERIVE, with the exception of the black box warning, apply to this 11270 mechanism. 11271

CKM_TLS12_KEY_SAFE_DERIVE is provided as a separate mechanism to allow a client to control the 11272 export of IV material (and possible leaking of key material) through the use of the 11273 CKA_ALLOWED_MECHANISMS key attribute. 11274

6.40.8 Generic Key Derivation using the TLS PRF 11275

CKM_TLS_KDF is the mechanism defined in [RFC 5705]. It uses the TLS key material and TLS PRF 11276 function to produce additional key material for protocols that want to leverage the TLS key negotiation 11277 mechanism. CKM_TLS_KDF has a parameter of CK_TLS_KDF_PARAMS. If the protocol using this 11278 mechanism does not use context information, the pContextData field shall be set to NULL_PTR and the 11279 ulContextDataLength field shall be set to 0. 11280

To use this mechanism with TLS1.0 and TLS1.1, use CKM_TLS_PRF as the value for prfMechanism in 11281 place of a hash mechanism. Note: Although CKM_TLS_PRF is deprecated as a mechanism for 11282 C_DeriveKey, the manifest value is retained for use with this mechanism to indicate the use of the 11283 TLS1.0/1.1 Pseudo-random function. 11284

This mechanism can be used to derive multiple keys (e.g. similar to 11285 CKM_TLS12_KEY_AND_MAC_DERIVE) by first deriving the key stream as a CKK_GENERIC_SECRET 11286 of the necessary length and doing subsequent derives against that derived key using the 11287 CKM_EXTRACT_KEY_FROM_KEY mechanism to split the key stream into the actual operational keys. 11288

The mechanism should not be used with the labels defined for use with TLS, but the token does not 11289 enforce this behavior. 11290


If the original key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, 11292 then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from the 11293 original key. 11294

Similarly, if the original key has its CKA_EXTRACTABLE attribute set to CK_FALSE, so does the 11295 derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either from the 11296 supplied template or from the original key. 11297

The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the original 11298 key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE. 11299

Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 11300 the original key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE. 11301

6.40.9 Generic Key Derivation using the TLS12 PRF 11302

CKM_TLS12_KDF is the mechanism defined in [RFC 5705]. It uses the TLS key material and TLS PRF 11303 function to produce additional key material for protocols that want to leverage the TLS key negotiation 11304 mechanism. CKM_TLS12_KDF has a parameter of CK_TLS_KDF_PARAMS. If the protocol using this 11305 mechanism does not use context information, the pContextData field shall be set to NULL_PTR and the 11306 ulContextDataLength field shall be set to 0. 11307

To use this mechanism with TLS1.0 and TLS1.1, use CKM_TLS_PRF as the value for prfMechanism in 11308 place of a hash mechanism. Note: Although CKM_TLS_PRF is deprecated as a mechanism for 11309 C_DeriveKey, the manifest value is retained for use with this mechanism to indicate the use of the 11310 TLS1.0/1.1 Pseudo-random function. 11311

This mechanism can be used to derive multiple keys (e.g. similar to 11312 CKM_TLS12_KEY_AND_MAC_DERIVE) by first deriving the key stream as a CKK_GENERIC_SECRET 11313 of the necessary length and doing subsequent derives against that derived key stream using the 11314 CKM_EXTRACT_KEY_FROM_KEY mechanism to split the key stream into the actual operational keys. 11315


The mechanism should not be used with the labels defined for use with TLS, but the token does not 11316 enforce this behavior. 11317


If the original key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, 11319 then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from the 11320 original key. 11321

Similarly, if the original key has its CKA_EXTRACTABLE attribute set to CK_FALSE, so does the 11322 derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either from the 11323 supplied template or from the original key. 11324

The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the original 11325 key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE. 11326

Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 11327 the original key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE. 11328

6.41 WTLS 11329

Details can be found in [WTLS]. 11330

When comparing the existing TLS mechanisms with these extensions to support WTLS one could argue 11331 that there would be no need to have distinct handling of the client and server side of the handshake. 11332 However, since in WTLS the server and client use different sequence numbers, there could be instances 11333 (e.g. when WTLS is used to protect asynchronous protocols) where sequence numbers on the client and 11334 server side differ, and hence this motivates the introduced split. 11335

11336

Table 190, WTLS Mechanisms vs. Functions 11337

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key

/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_WTLS_PRE_MASTER_KEY_GEN

CKM_WTLS_MASTER_KEY_DERIVE

CKM_WTLS_MASTER_KEY_DERIVE_DH_ECC

CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE

CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE

CKM_WTLS_PRF


Mechanisms: 11339

CKM_WTLS_PRE_MASTER_KEY_GEN 11340

CKM_WTLS_MASTER_KEY_DERIVE 11341

CKM_WTLS_MASTER_KEY_DERIVE_DH_ECC 11342


CKM_WTLS_PRF 11343

CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE 11344

CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE 11345

6.41.2 WTLS mechanism parameters 11346

CK_WTLS_RANDOM_DATA; CK_WTLS_RANDOM_DATA_PTR 11347

CK_WTLS_RANDOM_DATA is a structure, which provides information about the random data of a client 11348 and a server in a WTLS context. This structure is used by the CKM_WTLS_MASTER_KEY_DERIVE 11349


typedef struct CK_WTLS_RANDOM_DATA { 11351

CK_BYTE_PTR pClientRandom; 11352

CK_ULONG ulClientRandomLen; 11353

CK_BYTE_PTR pServerRandom; 11354

CK_ULONG ulServerRandomLen; 11355

} CK_WTLS_RANDOM_DATA; 11356

11357


pClientRandom pointer to the client’s random data 11359

pClientRandomLen length in bytes of the client’s random data 11360

pServerRaondom pointer to the server’s random data 11361

ulServerRandomLen length in bytes of the server’s random data 11362

CK_WTLS_RANDOM_DATA_PTR is a pointer to a CK_WTLS_RANDOM_DATA. 11363

CK_WTLS_MASTER_KEY_DERIVE_PARAMS; 11364

CK_WTLS_MASTER_KEY_DERIVE_PARAMS _PTR 11365

CK_WTLS_MASTER_KEY_DERIVE_PARAMS is a structure, which provides the parameters to the 11366 CKM_WTLS_MASTER_KEY_DERIVE mechanism. It is defined as follows: 11367

typedef struct CK_WTLS_MASTER_KEY_DERIVE_PARAMS { 11368

CK_MECHANISM_TYPE DigestMechanism; 11369

CK_WTLS_RANDOM_DATA RandomInfo; 11370

CK_BYTE_PTR pVersion; 11371

} CK_WTLS_MASTER_KEY_DERIVE_PARAMS; 11372

11373


DigestMechanism the mechanism type of the digest mechanism to be used (possible 11375 types can be found in [WTLS]) 11376

RandomInfo Client’s and server’s random data information 11377

pVersion pointer to a CK_BYTE which receives the WTLS protocol version 11378 information 11379

CK_WTLS_MASTER_KEY_DERIVE_PARAMS_PTR is a pointer to a 11380 CK_WTLS_MASTER_KEY_DERIVE_PARAMS. 11381


CK_WTLS_PRF_PARAMS; CK_WTLS_PRF_PARAMS_PTR 11382

CK_WTLS_PRF_PARAMS is a structure, which provides the parameters to the CKM_WTLS_PRF 11383


typedef struct CK_WTLS_PRF_PARAMS { 11385





CK_ULONG ulLabelLen; 11390

CK_BYTE_PTR pOutput; 11391

CK_ULONG_PTR pulOutputLen; 11392

} CK_WTLS_PRF_PARAMS; 11393

11394


Digest Mechanism the mechanism type of the digest mechanism to be used (possible 11396 types can be found in [WTLS]) 11397

pSeed pointer to the input seed 11398


pLabel pointer to the identifying label 11400

ulLabelLen length in bytes of the identifying label 11401

pOutput pointer receiving the output of the operation 11402

pulOutputLen pointer to the length in bytes that the output to be created shall 11403 have, has to hold the desired length as input and will receive the 11404 calculated length as output 11405

CK_WTLS_PRF_PARAMS_PTR is a pointer to a CK_WTLS_PRF_PARAMS. 11406

CK_WTLS_KEY_MAT_OUT; CK_WTLS_KEY_MAT_OUT_PTR 11407

CK_WTLS_KEY_MAT_OUT is a structure that contains the resulting key handles and initialization 11408 vectors after performing a C_DeriveKey function with the 11409 CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE or with the 11410 CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE mechanism. It is defined as follows: 11411

typedef struct CK_WTLS_KEY_MAT_OUT { 11412

CK_OBJECT_HANDLE hMacSecret; 11413


CK_BYTE_PTR pIV; 11415

} CK_WTLS_KEY_MAT_OUT; 11416

11417


hMacSecret Key handle for the resulting MAC secret key 11419

hKey Key handle for the resulting secret key 11420

pIV Pointer to a location which receives the initialization vector (IV) 11421 created (if any) 11422

CK_WTLS_KEY_MAT_OUT _PTR is a pointer to a CK_WTLS_KEY_MAT_OUT. 11423


CK_WTLS_KEY_MAT_PARAMS; CK_WTLS_KEY_MAT_PARAMS_PTR 11424

CK_WTLS_KEY_MAT_PARAMS is a structure that provides the parameters to the 11425 CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE and the 11426 CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE mechanisms. It is defined as follows: 11427

typedef struct CK_WTLS_KEY_MAT_PARAMS { 11428





CK_ULONG ulSequenceNumber; 11433


CK_WTLS_RANDOM_DATA RandomInfo; 11435

CK_WTLS_KEY_MAT_OUT_PTR pReturnedKeyMaterial; 11436

} CK_WTLS_KEY_MAT_PARAMS; 11437

11438


Digest Mechanism the mechanism type of the digest mechanism to be used (possible 11440 types can be found in [WTLS]) 11441

ulMaxSizeInBits the length (in bits) of the MACing key agreed upon during the 11442 protocol handshake phase 11443

ulKeySizeInBits the length (in bits) of the secret key agreed upon during the 11444 handshake phase 11445

ulIVSizeInBits the length (in bits) of the IV agreed upon during the handshake 11446 phase. If no IV is required, the length should be set to 0. 11447

ulSequenceNumber the current sequence number used for records sent by the client 11448 and server respectively 11449

bIsExport a boolean value which indicates whether the keys have to be 11450 derives for an export version of the protocol. If this value is true 11451 (i.e., the keys are exportable) then ulKeySizeInBits is the length of 11452 the key in bits before expansion. The length of the key after 11453 expansion is determined by the information found in the template 11454 sent along with this mechanism during a C_DeriveKey function call 11455 (either the CKA_KEY_TYPE or the CKA_VALUE_LEN attribute). 11456

RandomInfo client’s and server’s random data information 11457

pReturnedKeyMaterial points to a CK_WTLS_KEY_MAT_OUT structure which receives 11458 the handles for the keys generated and the IV 11459

CK_WTLS_KEY_MAT_PARAMS_PTR is a pointer to a CK_WTLS_KEY_MAT_PARAMS. 11460

6.41.3 Pre master secret key generation for RSA key exchange suite 11461

Pre master secret key generation for the RSA key exchange suite in WTLS denoted 11462 CKM_WTLS_PRE_MASTER_KEY_GEN, is a mechanism, which generates a variable length secret key. 11463 It is used to produce the pre master secret key for RSA key exchange suite used in WTLS. This 11464 mechanism returns a handle to the pre master secret key. 11465

It has one parameter, a CK_BYTE, which provides the client’s WTLS version. 11466

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE and CKA_VALUE attributes to the new 11467 key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may 11468 be specified in the template, or else are assigned default values. 11469


The template sent along with this mechanism during a C_GenerateKey call may indicate that the object 11470 class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN 11471

attribute indicates the length of the pre master secret key. 11472

For this mechanism, the ulMinKeySize field of the CK_MECHANISM_INFO structure shall indicate 20 11473

bytes. 11474

6.41.4 Master secret key derivation 11475

Master secret derivation in WTLS, denoted CKM_WTLS_MASTER_KEY_DERIVE, is a mechanism used 11476 to derive a 20 byte generic secret key from variable length secret key. It is used to produce the master 11477 secret key used in WTLS from the pre master secret key. This mechanism returns the value of the client 11478 version, which is built into the pre master secret key as well as a handle to the derived master secret key. 11479

It has a parameter, a CK_WTLS_MASTER_KEY_DERIVE_PARAMS structure, which allows for passing 11480 the mechanism type of the digest mechanism to be used as well as the passing of random data to the 11481 token as well as the returning of the protocol version number which is part of the pre master secret key. 11482





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

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

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



Note that the CK_BYTE pointed to by the CK_WTLS_MASTER_KEY_DERIVE_PARAMS structure’s 11503 pVersion field will be modified by the C_DeriveKey call. In particular, when the call returns, this byte will 11504

hold the WTLS version associated with the supplied pre master secret key. 11505

Note that this mechanism is only useable for key exchange suites that use a 20-byte pre master secret 11506 key with an embedded version number. This includes the RSA key exchange suites, but excludes the 11507 Diffie-Hellman and Elliptic Curve Cryptography key exchange suites. 11508

6.41.5 Master secret key derivation for Diffie-Hellman and Elliptic Curve 11509

Cryptography 11510

Master secret derivation for Diffie-Hellman and Elliptic Curve Cryptography in WTLS, denoted 11511 CKM_WTLS_MASTER_KEY_DERIVE_DH_ECC, is a mechanism used to derive a 20 byte generic 11512 secret key from variable length secret key. It is used to produce the master secret key used in WTLS from 11513 the pre master secret key. This mechanism returns a handle to the derived master secret key. 11514

It has a parameter, a CK_WTLS_MASTER_KEY_DERIVE_PARAMS structure, which allows for the 11515 passing of the mechanism type of the digest mechanism to be used as well as random data to the token. 11516 The pVersion field of the structure must be set to NULL_PTR since the version number is not embedded 11517

in the pre master secret key as it is for RSA-like key exchange suites. 11518






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

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

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



Note that this mechanism is only useable for key exchange suites that do not use a fixed length 20-byte 11539 pre master secret key with an embedded version number. This includes the Diffie-Hellman and Elliptic 11540 Curve Cryptography key exchange suites, but excludes the RSA key exchange suites. 11541

6.41.6 WTLS PRF (pseudorandom function) 11542

PRF (pseudo random function) in WTLS, denoted CKM_WTLS_PRF, is a mechanism used to produce a 11543

securely generated pseudo-random output of arbitrary length. The keys it uses are generic secret keys. 11544

It has a parameter, a CK_WTLS_PRF_PARAMS structure, which allows for passing the mechanism type 11545 of the digest mechanism to be used, the passing of the input seed and its length, the passing of an 11546 identifying label and its length and the passing of the length of the output to the token and for receiving 11547 the output. 11548

This mechanism produces securely generated pseudo-random output of the length specified in the 11549 parameter. 11550

This mechanism departs from the other key derivation mechanisms in Cryptoki in not using the template 11551 sent along with this mechanism during a C_DeriveKey function call, which means the template shall be a 11552 NULL_PTR. For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result 11553 of a successful completion. However, since the CKM_WTLS_PRF mechanism returns the requested 11554 number of output bytes in the CK_WTLS_PRF_PARAMS structure specified as the mechanism 11555 parameter, the parameter phKey passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. 11556

If a call to C_DeriveKey with this mechanism fails, then no output will be generated. 11557

6.41.7 Server Key and MAC derivation 11558

Server key, MAC and IV derivation in WTLS, denoted 11559 CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE, is a mechanism used to derive the appropriate 11560 cryptographic keying material used by a cipher suite from the master secret key and random data. This 11561 mechanism returns the key handles for the keys generated in the process, as well as the IV created. 11562

It has a parameter, a CK_WTLS_KEY_MAT_PARAMS structure, which allows for the passing of the 11563 mechanism type of the digest mechanism to be used, random data, the characteristic of the cryptographic 11564 material for the given cipher suite, and a pointer to a structure which receives the handles and IV which 11565 were generated. 11566


This mechanism contributes to the creation of two distinct keys and returns one IV (if an IV is requested 11567 by the caller) back to the caller. The keys are all given an object class of CKO_SECRET_KEY. 11568

The MACing key (server write MAC secret) is always given a type of CKK_GENERIC_SECRET. It is 11569

flagged as valid for signing, verification and derivation operations. 11570

The other key (server write key) is typed according to information found in the template sent along with 11571 this mechanism during a C_DeriveKey function call. By default, it is flagged as valid for encryption, 11572

decryption, and derivation operations. 11573

An IV (server write IV) will be generated and returned if the ulIVSizeInBits field of the 11574 CK_WTLS_KEY_MAT_PARAMS field has a nonzero value. If it is generated, its length in bits will agree 11575 with the value in the ulIVSizeInBits field 11576

Both keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, 11577 CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template 11578 provided to C_DeriveKey may not specify values for any of these attributes that differ from those held by 11579

the base key. 11580

Note that the CK_WTLS_KEY_MAT_OUT structure pointed to by the CK_WTLS_KEY_MAT_PARAMS 11581 structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the two key 11582 handle fields in the CK_WTLS_KEY_MAT_OUT structure will be modified to hold handles to the newly-11583 created keys; in addition, the buffer pointed to by the CK_WTLS_KEY_MAT_OUT structure’s pIV field will 11584 have the IV returned in them (if an IV is requested by the caller). Therefore, this field must point to a 11585 buffer with sufficient space to hold any IV that will be returned. 11586

This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. 11587 For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result of a 11588 successful completion. However, since the CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE 11589 mechanism returns all of its key handles in the CK_WTLS_KEY_MAT_OUT structure pointed to by the 11590 CK_WTLS_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey 11591 passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. 11592

If a call to C_DeriveKey with this mechanism fails, then none of the two keys will be created. 11593

6.41.8 Client key and MAC derivation 11594

Client key, MAC and IV derivation in WTLS, denoted CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE, 11595 is a mechanism used to derive the appropriate cryptographic keying material used by a cipher suite from 11596 the master secret key and random data. This mechanism returns the key handles for the keys generated 11597 in the process, as well as the IV created. 11598

It has a parameter, a CK_WTLS_KEY_MAT_PARAMS structure, which allows for the passing of the 11599 mechanism type of the digest mechanism to be used, random data, the characteristic of the cryptographic 11600 material for the given cipher suite, and a pointer to a structure which receives the handles and IV which 11601 were generated. 11602

This mechanism contributes to the creation of two distinct keys and returns one IV (if an IV is requested 11603 by the caller) back to the caller. The keys are all given an object class of CKO_SECRET_KEY. 11604

The MACing key (client write MAC secret) is always given a type of CKK_GENERIC_SECRET. It is 11605

flagged as valid for signing, verification and derivation operations. 11606

The other key (client write key) is typed according to information found in the template sent along with this 11607 mechanism during a C_DeriveKey function call. By default, it is flagged as valid for encryption, 11608

decryption, and derivation operations. 11609

An IV (client write IV) will be generated and returned if the ulIVSizeInBits field of the 11610 CK_WTLS_KEY_MAT_PARAMS field has a nonzero value. If it is generated, its length in bits will agree 11611 with the value in the ulIVSizeInBits field 11612

Both keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, 11613 CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template 11614 provided to C_DeriveKey may not specify values for any of these attributes that differ from those held by 11615

the base key. 11616


Note that the CK_WTLS_KEY_MAT_OUT structure pointed to by the CK_WTLS_KEY_MAT_PARAMS 11617 structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the two key 11618 handle fields in the CK_WTLS_KEY_MAT_OUT structure will be modified to hold handles to the newly-11619 created keys; in addition, the buffer pointed to by the CK_WTLS_KEY_MAT_OUT structure’s pIV field will 11620 have the IV returned in them (if an IV is requested by the caller). Therefore, this field must point to a 11621 buffer with sufficient space to hold any IV that will be returned. 11622

This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. 11623 For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result of a 11624 successful completion. However, since the CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE mechanism 11625 returns all of its key handles in the CK_WTLS_KEY_MAT_OUT structure pointed to by the 11626 CK_WTLS_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey 11627 passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. 11628

If a call to C_DeriveKey with this mechanism fails, then none of the two keys will be created. 11629

6.42 SP 800-108 Key Derivation 11630

NIST SP800-108 defines three types of key derivation functions (KDF); a Counter Mode KDF, a 11631 Feedback Mode KDF and a Double Pipeline Mode KDF. 11632

This section defines a unique mechanism for each type of KDF. These mechanisms can be used to 11633 derive one or more symmetric keys from a single base symmetric key. 11634

The KDFs defined in SP800-108 are all built upon pseudo random functions (PRF). In general terms, the 11635 PRFs accepts two pieces of input; a base key and some input data. The base key is taken from the 11636 hBaseKey parameter to C_Derive. The input data is constructed from an iteration variable (internally 11637 defined by the KDF/PRF) and the data provided in the CK_ PRF_DATA_PARAM array that is part of the 11638 mechanism parameter. 11639

Table 191, SP800-108 Mechanisms vs. Functions 11640

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SP800_108_COUNTER_KDF

CKM_SP800_108_FEEDBACK_KDF

CKM_SP800_108_DOUBLE_PIPELINE_KDF

11641

For these mechanisms, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO 11642 structure specify the minimum and maximum supported base key size in bits. Note, these mechanisms 11643 support multiple PRF types and key types; as such the values reported by ulMinKeySize and 11644 ulMaxKeySize specify the minimum and maximum supported base key size when all PRF and keys types 11645 are considered. For example, a Cryptoki implementation may support CKK_GENERIC_SECRET keys 11646 that can be as small as 8-bits in length and therefore ulMinKeySize could report 8-bits. However, for an 11647 AES-CMAC PRF the base key must be of type CKK_AES and must be either 16-bytes, 24-bytes or 32-11648 bytes in lengths and therefore the value reported by ulMinKeySize could be misleading. Depending on 11649 the PRF type selected, additional key size restrictions may apply. 11650


Mechanisms: 11652

CKM_SP800_108_COUNTER_KDF 11653

CKM_SP800_108_FEEDBACK_KDF 11654


CKM_SP800_108_DOUBLE_PIPELINE_KDF 11655

11656

Data Field Types: 11657

CK_SP800_108_ITERATION_VARIABLE 11658

CK_SP800_108_COUNTER 11659

CK_SP800_108_DKM_LENGTH 11660

CK_SP800_108_BYTE_ARRAY 11661

11662

DKM Length Methods: 11663

CK_SP800_108_DKM_LENGTH_SUM_OF_KEYS 11664

CK_SP800_108_DKM_LENGTH_SUM_OF_SEGMENTS 11665


CK_SP800_108_PRF_TYPE 11667

The CK_SP800_108_PRF_TYPE field of the mechanism parameter is used to specify the type of PRF 11668

that is to be used. It is defined as follows: 11669

typedef CK_MECHANISM_TYPE CK_SP800_108_PRF_TYPE; 11670

The CK_SP800_108_PRF_TYPE field reuses the existing mechanisms definitions. The following table 11671

lists the supported PRF types: 11672

Table 192, SP800-108 Pseudo Random Functions 11673

Pseudo Random Function Identifiers

CKM_SHA_1_HMAC

CKM_SHA224_HMAC

CKM_SHA256_HMAC

CKM_SHA384_HMAC

CKM_SHA512_HMAC

CKM_SHA3_224_HMAC

CKM_SHA3_256_HMAC

CKM_SHA3_384_HMAC

CKM_SHA3_512_HMAC

CKM_DES3_CMAC

CKM_AES_CMAC

11674

CK_PRF_DATA_TYPE 11675

Each mechanism parameter contains an array of CK_PRF_DATA_PARAM structures. The 11676 CK_PRF_DATA_PARAM structure contains CK_PRF_DATA_TYPE field. The CK_PRF_DATA_TYPE 11677 field is used to identify the type of data identified by each CK_PRF_DATA_PARAM element in the array. 11678 Depending on the type of KDF used, some data field types are mandatory, some data field types are 11679 optional and some data field types are not allowed. These requirements are defined on a per-mechanism 11680 basis in the sections below. The CK_PRF_DATA_TYPE is defined as follows: 11681

typedef CK_ULONG CK_PRF_DATA_TYPE; 11682


The following table lists all of the supported data field types: 11683

Table 193, SP800-108 PRF Data Field Types 11684

Data Field Identifier Description

CK_SP800_108_ITERATION_VARIABLE Identifies the iteration variable defined internally by the

KDF.

CK_SP800_108_COUNTER Identifies an optional counter value represented as a

binary string. Exact formatting of the counter value is

defined by the CK_SP800_108_COUNTER_FORMAT

structure. The value of the counter is defined by the

KDF’s internal loop counter.

CK_SP800_108_DKM_LENGTH Identifies the length in bits of the derived keying material

(DKM) represented as a binary string. Exact formatting

of the length value is defined by the

CK_SP800_108_DKM_LENGTH_FORMAT structure.

CK_SP800_108_BYTE_ARRAY Identifies a generic byte array of data. This data type can be used to provide “context”, “label”, “separator bytes” as well as any other type of encoding information required by the higher level protocol.

11685

CK_PRF_DATA_PARAM 11686

CK_PRF_DATA_PARAM is used to define a segment of input for the PRF. Each mechanism parameter 11687 supports an array of CK_PRF_DATA_PARAM structures. The CK_PRF_DATA_PARAM is defined as 11688

follows: 11689

typedef struct CK_PRF_DATA_PARAM 11690

{ 11691

CK_PRF_DATA_TYPE type; 11692

CK_VOID_PTR pValue; 11693

CK_ULONG ulValueLen; 11694

} CK_PRF_DATA_PARAM; 11695

11696

typedef CK_PRF_DATA_PARAM CK_PTR CK_PRF_DATA_PARAM_PTR 11697

11698

The fields of the CK_PRF_DATA_PARAM structure have the following meaning: 11699 type defines the type of data pointed to by pValue 11700

pValue pointer to the data defined by type 11701

ulValueLen size of the data pointed to by pValue 11702

If the type field of the CK_PRF_DATA_PARAM structure is set to 11703 CK_SP800_108_ITERATION_VARIABLE, then pValue must be set the appropriate value for the KDF’s 11704 iteration variable type. For the Counter Mode KDF, pValue must be assigned a valid 11705 CK_SP800_108_COUNTER_FORMAT_PTR and ulValueLen must be set to 11706 sizeof(CK_SP800_108_COUNTER_FORMAT). For all other KDF types, pValue must be set to 11707 NULL_PTR and ulValueLen must be set to 0. 11708

11709

If the type field of the CK_PRF_DATA_PARAM structure is set to CK_SP800_108_COUNTER, then 11710 pValue must be assigned a valid CK_SP800_108_COUNTER_FORMAT_PTR and ulValueLen must be 11711 set to sizeof(CK_SP800_108_COUNTER_FORMAT). 11712


11713

If the type field of the CK_PRF_DATA_PARAM structure is set to CK_SP800_108_DKM_LENGTH then 11714 pValue must be assigned a valid CK_SP800_108_DKM_LENGTH_FORMAT_PTR and ulValueLen must 11715 be set to sizeof(CK_SP800_108_DKM_LENGTH_FORMAT). 11716

11717

If the type field of the CK_PRF_DATA_PARAM structure is set to CK_SP800_108_BYTE_ARRAY, then 11718 pValue must be assigned a valid CK_BYTE_PTR value and ulValueLen must be set to a non-zero length. 11719

CK_SP800_108_COUNTER_FORMAT 11720

CK_SP800_108_COUNTER_FORMAT is used to define the encoding format for a counter value. The 11721 CK_SP800_108_COUNTER_FORMAT is defined as follows: 11722

typedef struct CK_SP800_108_COUNTER_FORMAT 11723

{ 11724

CK_BBOOL bLittleEndian; 11725

CK_ULONG ulWidthInBits; 11726

} CK_SP800_108_COUNTER_FORMAT; 11727

11728

typedef CK_SP800_108_COUNTER_FORMAT CK_PTR 11729

CK_SP800_108_COUNTER_FORMAT_PTR 11730

11731

The fields of the CK_SP800_108_COUNTER_FORMAT structure have the following meaning: 11732 bLittleEndian defines if the counter should be represented in Big Endian or Little 11733

Endian format 11734

ulWidthInBits defines the number of bits used to represent the counter value 11735

CK_SP800_108_DKM_LENGTH_METHOD 11736

CK_SP800_108_DKM_LENGTH_METHOD is used to define how the DKM length value is calculated. 11737 The CK_SP800_108_DKM_LENGTH_METHOD type is defined as follows: 11738

typedef CK_ULONG CK_SP800_108_DKM_LENGTH_METHOD; 11739

The following table lists all of the supported DKM Length Methods: 11740

Table 194, SP800-108 DKM Length Methods 11741

DKM Length Method Identifier Description

CK_SP800_108_DKM_LENGTH_SUM_OF_KEYS Specifies that the DKM length should be set to the

sum of the length of all keys derived by this

invocation of the KDF.

CK_SP800_108_DKM_LENGTH_SUM_OF_SEGMENTS Specifies that the DKM length should be set to the

sum of the length of all segments of output produced

by the PRF by this invocation of the KDF.

11742

CK_SP800_108_DKM_LENGTH_FORMAT 11743

CK_SP800_108_DKM_LENGTH_FORMAT is used to define the encoding format for the DKM length 11744 value. The CK_SP800_108_DKM_LENGTH_FORMAT is defined as follows: 11745

typedef struct CK_SP800_108_DKM_LENGTH_FORMAT 11746


{ 11747

CK_SP800_108_DKM_LENGTH_METHOD dkmLengthMethod; 11748

CK_BBOOL bLittleEndian; 11749

CK_ULONG ulWidthInBits; 11750

} CK_SP800_108_DKM_LENGTH_FORMAT; 11751

11752

typedef CK_SP800_108_DKM_LENGTH_FORMAT CK_PTR 11753

CK_SP800_108_DKM_LENGTH_FORMAT_PTR 11754

11755

The fields of the CK_SP800_108_DKM_LENGTH_FORMAT structure have the following meaning: 11756 dkmLengthMethod defines the method used to calculate the DKM length value 11757

bLittleEndian defines if the DKM length value should be represented in Big 11758 Endian or Little Endian format 11759

ulWidthInBits defines the number of bits used to represent the DKM length value 11760

CK_DERIVED_KEY 11761

CK_DERIVED_KEY is used to define an additional key to be derived as well as provide a 11762 CK_OBJECT_HANDLE_PTR to receive the handle for the derived keys. The CK_DERIVED_KEY is 11763


typedef struct CK_DERIVED_KEY 11765

{ 11766

CK_ATTRIBUTE_PTR pTemplate; 11767

CK_ULONG ulAttributeCount; 11768

CK_OBJECT_HANDLE_PTR phKey; 11769

} CK_DERIVED_KEY; 11770

11771

typedef CK_DERIVED_KEY CK_PTR CK_DERIVED_KEY_PTR 11772

11773

The fields of the CK_DERIVED_KEY structure have the following meaning: 11774 pTemplate pointer to a template that defines a key to derive 11775

ulAttributeCount number of attributes in the template pointed to by pTemplate 11776

phKey pointer to receive the handle for a derived key 11777

CK_SP800_108_KDF_PARAMS, CK_SP800_108_KDF_PARAMS_PTR 11778

CK_SP800_108_KDF_PARAMS is a structure that provides the parameters for the 11779 CKM_SP800_108_COUNTER_KDF and CKM_SP800_108_DOUBLE_PIPELINE_KDF mechanisms. 11780

11781

typedef struct CK_SP800_108_KDF_PARAMS 11782

{ 11783

CK_SP800_108_PRF_TYPE prfType; 11784

CK_ULONG ulNumberOfDataParams; 11785

CK_PRF_DATA_PARAM_PTR pDataParams; 11786

CK_ULONG ulAdditionalDerivedKeys; 11787

CK_DERIVED_KEY_PTR pAdditionalDerivedKeys; 11788

} CK_SP800_108_KDF_PARAMS; 11789


11790

typedef CK_SP800_108_KDF_PARAMS CK_PTR 11791

CK_SP800_108_KDF_PARAMS_PTR; 11792

11793

The fields of the CK_SP800_108_KDF_PARAMS structure have the following meaning: 11794 prfType type of PRF 11795

ulNumberOfDataParams number of elements in the array pointed to by pDataParams 11796

pDataParams an array of CK_PRF_DATA_PARAM structures. The array defines 11797 input parameters that are used to construct the “data” input to the 11798 PRF. 11799

ulAdditionalDerivedKeys number of additional keys that will be derived and the number of 11800 elements in the array pointed to by pAdditionalDerivedKeys. If 11801 pAdditionalDerivedKeys is set to NULL_PTR, this parameter must 11802 be set to 0. 11803

pAdditionalDerivedKeys an array of CK_DERIVED_KEY structures. If 11804 ulAdditionalDerivedKeys is set to 0, this parameter must be set to 11805 NULL_PTR 11806

CK_SP800_108_FEEDBACK_KDF_PARAMS, 11807

CK_SP800_108_FEEDBACK_KDF_PARAMS_PTR 11808

The CK_SP800_108_FEEDBACK_KDF_PARAMS structure provides the parameters for the 11809 CKM_SP800_108_FEEDBACK_KDF mechanism. It is defined as follows: 11810

typedef struct CK_SP800_108_FEEDBACK_KDF_PARAMS 11811

{ 11812

CK_SP800_108_PRF_TYPE prfType; 11813

CK_ULONG ulNumberOfDataParams; 11814

CK_PRF_DATA_PARAM_PTR pDataParams; 11815

CK_ULONG ulIVLen; 11816

CK_BYTE_PTR pIV; 11817

CK_ULONG ulAdditionalDerivedKeys; 11818

CK_DERIVED_KEY_PTR pAdditionalDerivedKeys; 11819

} CK_SP800_108_FEEDBACK_KDF_PARAMS; 11820

11821

typedef CK_SP800_108_FEEDBACK_KDF_PARAMS CK_PTR 11822

CK_SP800_108_FEEDBACK_KDF_PARAMS_PTR; 11823

11824

The fields of the CK_SP800_108_FEEDBACK_KDF_PARAMS structure have the following meaning: 11825 prfType type of PRF 11826

ulNumberOfDataParams number of elements in the array pointed to by pDataParams 11827

pDataParams an array of CK_PRF_DATA_PARAM structures. The array defines 11828 input parameters that are used to construct the “data” input to the 11829 PRF. 11830

ulIVLen the length in bytes of the IV. If pIV is set to NULL_PTR, this 11831 parameter must be set to 0. 11832

pIV an array of bytes to be used as the IV for the feedback mode KDF. 11833 This parameter is optional and can be set to NULL_PTR. If ulIVLen 11834 is set to 0, this parameter must be set to NULL_PTR. 11835


ulAdditionalDerivedKeys number of additional keys that will be derived and the number of 11836 elements in the array pointed to by pAdditionalDerivedKeys. If 11837 pAdditionalDerivedKeys is set to NULL_PTR, this parameter must 11838 be set to 0. 11839

pAdditionalDerivedKeys an array of CK_DERIVED_KEY structures. If 11840 ulAdditionalDerivedKeys is set to 0, this parameter must be set to 11841 NULL_PTR. 11842

6.42.3 Counter Mode KDF 11843

The SP800-108 Counter Mode KDF mechanism, denoted CKM_SP800_108_COUNTER_KDF, 11844 represents the KDF defined SP800-108 section 5.1. CKM_SP800_108_COUNTER_KDF is a 11845

mechanism for deriving one or more symmetric keys from a symmetric base key. 11846

It has a parameter, a CK_SP800_108_KDF_PARAMS structure. 11847

The following table lists the data field types that are supported for this KDF type and their meaning: 11848

Table 195, Counter Mode data field requirements 11849


CK_SP800_108_ITERATION_VARIABLE This data field type is mandatory.

This data field type identifies the location of the iteration

variable in the constructed PRF input data.

The iteration variable for this KDF type is a counter.

Exact formatting of the counter value is defined by the

CK_SP800_108_COUNTER_FORMAT structure.

CK_SP800_108_COUNTER This data field type is invalid for this KDF type.

CK_SP800_108_DKM_LENGTH This data field type is optional.

This data field type identifies the location of the DKM length

in the constructed PRF input data.

Exact formatting of the DKM length is defined by the


If specified, only one instance of this type may be specified.

CK_SP800_108_BYTE_ARRAY This data field type is optional.

This data field type identifies the location and value of a byte

array of data in the constructed PRF input data.

This standard does not restrict the number of instances of this data type.

11850

SP800-108 limits the amount of derived keying material that can be produced by a Counter Mode KDF by 11851 limiting the internal loop counter to (2

r−1), where “r” is the number of bits used to represent the counter. 11852

Therefore the maximum number of bits that can be produced is (2r−1)h, where “h” is the length in bits of 11853

the output of the selected PRF. 11854

6.42.4 Feedback Mode KDF 11855

The SP800-108 Feedback Mode KDF mechanism, denoted CKM_SP800_108_FEEDBACK_KDF, 11856 represents the KDF defined SP800-108 section 5.2. CKM_SP800_108_FEEDBACK_KDF is a 11857

mechanism for deriving one or more symmetric keys from a symmetric base key. 11858

It has a parameter, a CK_SP800_108_FEEDBACK_KDF_PARAMS structure. 11859


Table 196, Feedback Mode data field requirements 11861






The iteration variable is defined as K(i-1) in section 5.2 of

SP800-108.

The size, format and value of this data input is defined by the

internal KDF structure and PRF output.



CK_SP800_108_COUNTER This data field type is optional.

This data field type identifies the location of the counter in the

constructed PRF input data.











This data field type identifies the location and value of a byte

array of data in the constructed PRF input data.


11862

SP800-108 limits the amount of derived keying material that can be produced by a Feedback Mode KDF 11863 by limiting the internal loop counter to (2

32−1). Therefore the maximum number of bits that can be 11864

produced is (232

−1)h, where “h” is the length in bits of the output of the selected PRF. 11865

6.42.5 Double Pipeline Mode KDF 11866

The SP800-108 Double Pipeline Mode KDF mechanism, denoted 11867 CKM_SP800_108_DOUBLE_PIPELINE_KDF, represents the KDF defined SP800-108 section 5.3. 11868 CKM_SP800_108_DOUBLE_PIPELINE_KDF is a mechanism for deriving one or more symmetric keys 11869

from a symmetric base key. 11870

It has a parameter, a CK_SP800_108_KDF_PARAMS structure. 11871


Table 197, Double Pipeline Mode data field requirements 11873





The iteration variable is defined as A(i) in section 5.3 of

SP800-108.

The size, format and value of this data input is defined by


the internal KDF structure and PRF output.



CK_SP800_108_COUNTER This data field type is optional.

This data field type identifies the location of the counter in

the constructed PRF input data.











This data field type identifies the location and value of a

byte array of data in the constructed PRF input data.


11874

SP800-108 limits the amount of derived keying material that can be produced by a Double-Pipeline Mode 11875 KDF by limiting the internal loop counter to (2

32−1). Therefore the maximum number of bits that can be 11876

produced is (232

−1)h, where “h” is the length in bits of the output of the selected PRF. 11877

The Double Pipeline KDF requires an internal IV value. The IV is constructed using the same method 11878 used to construct the PRF input data; the data/values identified by the array of CK_PRF_DATA_PARAM 11879 structures are concatenated in to a byte array that is used as the IV. As shown in SP800-108 section 5.3, 11880 the CK_SP800_108_ITERATION_VARIABLE and CK_SP800_108_COUNTER data field types are not 11881 included in IV construction process. All other data field types are included in the construction process. 11882

6.42.6 Deriving Additional Keys 11883

The KDFs defined in this section can be used to derive more than one symmetric key from the base key. 11884 The C_Derive function accepts one CK_ATTRIBUTE_PTR to define a single derived key and one 11885

CK_OBJECT_HANDLE_PTR to receive the handle for the derived key. 11886

To derive additional keys, the mechanism parameter structure can be filled in with one or more 11887 CK_DERIVED_KEY structures. Each structure contains a CK_ATTRIBUTE_PTR to define a derived key 11888 and a CK_OBJECT_HANDLE_PTR to receive the handle for the additional derived keys. The key 11889 defined by the C_Derive function parameters is always derived before the keys defined by the 11890 CK_DERIVED_KEY array that is part of the mechanism parameter. The additional keys that are defined 11891 by the CK_DERIVED_KEY array are derived in the order they are defined in the array. That is to say that 11892 the derived keying material produced by the KDF is processed from left to right, and bytes are assigned 11893 first to the key defined by the C_Derive function parameters, and then bytes are assigned to the keys that 11894

are defined by the CK_DERIVED_KEY array in the order they are defined in the array. 11895

Each internal iteration of a KDF produces a unique segment of PRF output. Sometimes, a single iteration 11896 will produce enough keying material for the key being derived. Other times, additional internal iterations 11897 are performed to produce multiple segments which are concatenated together to produce enough keying 11898 material for the derived key(s). 11899

When deriving multiple keys, no key can be created using part of a segment that was used for another 11900 key. All keys must be created from disjoint segments. For example, if the parameters are defined such 11901 that a 48-byte key (defined by the C_Derive function parameters) and a 16-byte key (defined by the 11902


content of CK_DERIVED_KEY) are to be derived using CKM_SHA256_HMAC as a PRF, three internal 11903 iterations of the KDF will be performed and three segments of PRF output will be produced. The first 11904 segment and half of the second segment will be used to create the 48-byte key and the third segment will 11905 be used to create the 16-byte key. 11906

32-byte segment32-byte segment32-byte segment

16-byte key48-byte key unusedunused

3 KDF Segments of Output:

2 Derived Keys:

11907

In the above example, if the CK_SP800_108_DKM_LENGTH data field type is specified with method 11908 CK_SP800_108_DKM_LENGTH_SUM_OF_KEYS, then the DKM length value will be 512 bits. If the 11909 CK_SP800_108_DKM_LENGTH data field type is specified with method 11910 CK_SP800_108_DKM_LENGTH_SUM_OF_SEGMENTS, then the DKM length value will be 768 bits. 11911

When deriving multiple keys, if any of the keys cannot be derived for any reason, none of the keys shall 11912 be derived. If the failure was caused by the content of a specific key’s template (ie the template defined 11913 by the content of pTemplate), the corresponding phKey value will be set to CK_INVALID_HANDLE to 11914

identify the offending template. 11915

6.42.7 Key Derivation Attribute Rules 11916

The CKM_SP800_108_COUNTER_KDF, CKM_SP800_108_FEEDBACK_KDF and 11917 CKM_SP800_108_DOUBLE_PIPELINE_KDF mechanisms have the following rules about key sensitivity 11918

and extractability: 11919

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



6.42.8 Constructing PRF Input Data 11931

SP800-108 defines the PRF input data for each KDF at a high level using terms like “label”, “context”, 11932 “separator”, “counter”…etc. The value, formatting and order of the input data is not strictly defined by 11933 SP800-108, instead it is described as being defined by the “encoding scheme”. 11934

To support any encoding scheme, these mechanisms construct the PRF input data from from the array of 11935 CK_PRF_DATA_PARAM structures in the mechanism parameter. All of the values defined by the 11936 CK_PRF_DATA_PARAM array are concatenated in the order they are defined and passed in to the PRF 11937 as the data parameter. 11938

6.42.8.1 Sample Counter Mode KDF 11939

SP800-108 section 5.1 outlines a sample Counter Mode KDF which defines the following PRF input: 11940

PRF (KI, [i]2 || Label || 0x00 || Context || [L]2) 11941

Section 5.1 does not define the number of bits used to represent the counter (the “r” value) or the DKM 11942 length (the “L” value), so 16-bits is assumed for both cases. The following sample code shows how to 11943 define this PRF input data using an array of CK_PRF_DATA_PARAM structures. 11944

#define DIM(a) (sizeof((a))/sizeof((a)[0])) 11945


11946 CK_OBJECT_HANDLE hBaseKey; 11947 CK_OBJECT_HANDLE hDerivedKey; 11948 CK_ATTRIBUTE derivedKeyTemplate = { … }; 11949 11950 CK_BYTE baLabel[] = {0xde, 0xad, 0xbe , 0xef}; 11951 CK_ULONG ulLabelLen = sizeof(baLabel); 11952 CK_BYTE baContext[] = {0xfe, 0xed, 0xbe , 0xef}; 11953 CK_ULONG ulContextLen = sizeof(baContext); 11954 11955 CK_SP800_108_COUNTER_FORMAT counterFormat = {0, 16}; 11956 CK_SP800_108_DKM_LENGTH_FORMAT dkmFormat 11957 = {CK_SP800_108_DKM_LENGTH_SUM_OF_KEYS, 0, 16}; 11958 11959 CK_PRF_DATA_PARAM dataParams[] = 11960 { 11961 { CK_SP800_108_ITERATION_VARIABLE, 11962 &counterFormat, sizeof(counterFormat) }, 11963 { CK_SP800_108_BYTE_ARRAY, baLabel, ulLabelLen }, 11964 { CK_SP800_108_BYTE_ARRAY, {0x00}, 1 }, 11965 { CK_SP800_108_BYTE_ARRAY, baContext, ulContextLen }, 11966 { CK_SP800_108_DKM_LENGTH, dkmFormat, sizeof(dkmFormat) } 11967 }; 11968 11969 CK_SP800_108_KDF_PARAMS kdfParams = 11970 { 11971 CKM_AES_CMAC, 11972 DIM(dataParams), 11973 &dataParams, 11974 0, /* no addition derived keys */ 11975 NULL /* no addition derived keys */ 11976 }; 11977 11978 CK_MECHANISM = mechanism 11979 { 11980 CKM_SP800_108_COUNTER_KDF, 11981 &kdfParams, 11982 sizeof(kdfParams) 11983 }; 11984 11985 hBaseKey = GetBaseKeyHandle(.....); 11986 11987 rv = C_DeriveKey( 11988 hSession, 11989 &mechanism, 11990 hBaseKey, 11991 &derivedKeyTemplate, 11992 DIM(derivedKeyTemplate), 11993 &hDerivedKey); 11994

6.42.8.2 Sample SCP03 Counter Mode KDF 11995

The SCP03 standard defines a variation of a counter mode KDF which defines the following PRF input: 11996

PRF (KI, Label || 0x00 || [L]2 || [i]2 || Context) 11997

SCP03 defines the number of bits used to represent the counter (the “r” value) and number of bits used to 11998 represent the DKM length (the “L” value) as 16-bits. The following sample code shows how to define this 11999 PRF input data using an array of CK_PRF_DATA_PARAM structures. 12000


#define DIM(a) (sizeof((a))/sizeof((a)[0])) 12001 12002 CK_OBJECT_HANDLE hBaseKey; 12003 CK_OBJECT_HANDLE hDerivedKey; 12004 CK_ATTRIBUTE derivedKeyTemplate = { … }; 12005 12006 CK_BYTE baLabel[] = {0xde, 0xad, 0xbe , 0xef}; 12007 CK_ULONG ulLabelLen = sizeof(baLabel); 12008 CK_BYTE baContext[] = {0xfe, 0xed, 0xbe , 0xef}; 12009 CK_ULONG ulContextLen = sizeof(baContext); 12010 12011 CK_SP800_108_COUNTER_FORMAT counterFormat = {0, 16}; 12012 CK_SP800_108_DKM_LENGTH_FORMAT dkmFormat 12013 = {CK_SP800_108_DKM_LENGTH_SUM_OF_KEYS, 0, 16}; 12014 12015 CK_PRF_DATA_PARAM dataParams[] = 12016 { 12017 { CK_SP800_108_BYTE_ARRAY, baLabel, ulLabelLen }, 12018 { CK_SP800_108_BYTE_ARRAY, {0x00}, 1 }, 12019 { CK_SP800_108_DKM_LENGTH, dkmFormat, sizeof(dkmFormat) }, 12020 { CK_SP800_108_ITERATION_VARIABLE, 12021 &counterFormat, sizeof(counterFormat) }, 12022 { CK_SP800_108_BYTE_ARRAY, baContext, ulContextLen } 12023 }; 12024 12025 CK_SP800_108_KDF_PARAMS kdfParams = 12026 { 12027 CKM_AES_CMAC, 12028 DIM(dataParams), 12029 &dataParams, 12030 0, /* no addition derived keys */ 12031 NULL /* no addition derived keys */ 12032 }; 12033 12034 CK_MECHANISM = mechanism 12035 { 12036 CKM_SP800_108_COUNTER_KDF, 12037 &kdfParams, 12038 sizeof(kdfParams) 12039 }; 12040 12041 hBaseKey = GetBaseKeyHandle(.....); 12042 12043 rv = C_DeriveKey( 12044 hSession, 12045 &mechanism, 12046 hBaseKey, 12047 &derivedKeyTemplate, 12048 DIM(derivedKeyTemplate), 12049 &hDerivedKey); 12050

6.42.8.3 Sample Feedback Mode KDF 12051

SP800-108 section 5.2 outlines a sample Feedback Mode KDF which defines the following PRF input: 12052

PRF (KI, K(i-1) {|| [i]2 }|| Label || 0x00 || Context || [L]2) 12053

Section 5.2 does not define the number of bits used to represent the counter (the “r” value) or the DKM 12054 length (the “L” value), so 16-bits is assumed for both cases. The counter is defined as being optional and 12055


is included in this example. The following sample code shows how to define this PRF input data using an 12056 array of CK_PRF_DATA_PARAM structures. 12057

#define DIM(a) (sizeof((a))/sizeof((a)[0])) 12058 12059 CK_OBJECT_HANDLE hBaseKey; 12060 CK_OBJECT_HANDLE hDerivedKey; 12061 CK_ATTRIBUTE derivedKeyTemplate = { … }; 12062 12063 CK_BYTE baFeedbackIV[] = {0x01, 0x02, 0x03, 0x04}; 12064 CK_ULONG ulFeedbackIVLen = sizeof(baFeedbackIV); 12065 CK_BYTE baLabel[] = {0xde, 0xad, 0xbe, 0xef}; 12066 CK_ULONG ulLabelLen = sizeof(baLabel); 12067 CK_BYTE baContext[] = {0xfe, 0xed, 0xbe, 0xef}; 12068 CK_ULONG ulContextLen = sizeof(baContext); 12069 12070 CK_SP800_108_COUNTER_FORMAT counterFormat = {0, 16}; 12071 CK_SP800_108_DKM_LENGTH_FORMAT dkmFormat 12072 = {CK_SP800_108_DKM_LENGTH_SUM_OF_KEYS, 0, 16}; 12073 12074 CK_PRF_DATA_PARAM dataParams[] = 12075 { 12076 { CK_SP800_108_ITERATION_VARIABLE, 12077 &counterFormat, sizeof(counterFormat) }, 12078 { CK_SP800_108_BYTE_ARRAY, baLabel, ulLabelLen }, 12079 { CK_SP800_108_BYTE_ARRAY, {0x00}, 1 }, 12080 { CK_SP800_108_BYTE_ARRAY, baContext, ulContextLen }, 12081 { CK_SP800_108_DKM_LENGTH, dkmFormat, sizeof(dkmFormat) } 12082 }; 12083 12084 CK_SP800_108_FEEDBACK_KDF_PARAMS kdfParams = 12085 { 12086 CKM_AES_CMAC, 12087 DIM(dataParams), 12088 &dataParams, 12089 ulFeedbackIVLen, 12090 baFeedbackIV, 12091 0, /* no addition derived keys */ 12092 NULL /* no addition derived keys */ 12093 }; 12094 12095 CK_MECHANISM = mechanism 12096 { 12097 CKM_SP800_108_FEEDBACK_KDF, 12098 &kdfParams, 12099 sizeof(kdfParams) 12100 }; 12101 12102 hBaseKey = GetBaseKeyHandle(.....); 12103 12104 rv = C_DeriveKey( 12105 hSession, 12106 &mechanism, 12107 hBaseKey, 12108 &derivedKeyTemplate, 12109 DIM(derivedKeyTemplate), 12110 &hDerivedKey); 12111


6.42.8.4 Sample Double-Pipeline Mode KDF 12112

SP800-108 section 5.3 outlines a sample Double-Pipeline Mode KDF which defines the two following 12113 PRF inputs: 12114

PRF (KI, A(i-1)) 12115

PRF (KI, K(i-1) {|| [i]2 }|| Label || 0x00 || Context || [L]2) 12116

Section 5.3 does not define the number of bits used to represent the counter (the “r” value) or the DKM 12117 length (the “L” value), so 16-bits is assumed for both cases. The counter is defined as being optional so it 12118 is left out in this example. The following sample code shows how to define this PRF input data using an 12119 array of CK_PRF_DATA_PARAM structures. 12120

#define DIM(a) (sizeof((a))/sizeof((a)[0])) 12121 12122 CK_OBJECT_HANDLE hBaseKey; 12123 CK_OBJECT_HANDLE hDerivedKey; 12124 CK_ATTRIBUTE derivedKeyTemplate = { … }; 12125 12126 CK_BYTE baLabel[] = {0xde, 0xad, 0xbe , 0xef}; 12127 CK_ULONG ulLabelLen = sizeof(baLabel); 12128 CK_BYTE baContext[] = {0xfe, 0xed, 0xbe , 0xef}; 12129 CK_ULONG ulContextLen = sizeof(baContext); 12130 12131 CK_SP800_108_DKM_LENGTH_FORMAT dkmFormat 12132 = {CK_SP800_108_DKM_LENGTH_SUM_OF_KEYS, 0, 16}; 12133 12134 CK_PRF_DATA_PARAM dataParams[] = 12135 { 12136 { CK_SP800_108_BYTE_ARRAY, baLabel, ulLabelLen }, 12137 { CK_SP800_108_BYTE_ARRAY, {0x00}, 1 }, 12138 { CK_SP800_108_BYTE_ARRAY, baContext, ulContextLen }, 12139 { CK_SP800_108_DKM_LENGTH, dkmFormat, sizeof(dkmFormat) } 12140 }; 12141 12142 CK_SP800_108_KDF_PARAMS kdfParams = 12143 { 12144 CKM_AES_CMAC, 12145 DIM(dataParams), 12146 &dataParams, 12147 0, /* no addition derived keys */ 12148 NULL /* no addition derived keys */ 12149 }; 12150 12151 CK_MECHANISM = mechanism 12152 { 12153 CKM_SP800_108_DOUBLE_PIPELINE_KDF, 12154 &kdfParams, 12155 sizeof(kdfParams) 12156 }; 12157 12158 hBaseKey = GetBaseKeyHandle(.....); 12159 12160 rv = C_DeriveKey( 12161 hSession, 12162 &mechanism, 12163 hBaseKey, 12164 &derivedKeyTemplate, 12165 DIM(derivedKeyTemplate), 12166


&hDerivedKey); 12167

6.43 Miscellaneous simple key derivation mechanisms 12168

Table 198, Miscellaneous simple key derivation Mechanisms vs. Functions 12169

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_CONCATENATE_BASE_AND_KEY

CKM_CONCATENATE_BASE_AND_DATA

CKM_CONCATENATE_DATA_AND_BASE

CKM_XOR_BASE_AND_DATA

CKM_EXTRACT_KEY_FROM_KEY


Mechanisms: 12171

CKM_CONCATENATE_BASE_AND_DATA 12172

CKM_CONCATENATE_DATA_AND_BASE 12173

CKM_XOR_BASE_AND_DATA 12174

CKM_EXTRACT_KEY_FROM_KEY 12175

CKM_CONCATENATE_BASE_AND_KEY 12176

6.43.2 Parameters for miscellaneous simple key derivation mechanisms 12177

CK_KEY_DERIVATION_STRING_DATA; 12178

CK_KEY_DERIVATION_STRING_DATA_PTR 12179

CK_KEY_DERIVATION_STRING_DATA provides the parameters for the 12180 CKM_CONCATENATE_BASE_AND_DATA, CKM_CONCATENATE_DATA_AND_BASE, and 12181 CKM_XOR_BASE_AND_DATA mechanisms. It is defined as follows: 12182

typedef struct CK_KEY_DERIVATION_STRING_DATA { 12183


CK_ULONG ulLen; 12185

} CK_KEY_DERIVATION_STRING_DATA; 12186

12187


pData pointer to the byte string 12189

ulLen length of the byte string 12190

CK_KEY_DERIVATION_STRING_DATA_PTR is a pointer to a 12191 CK_KEY_DERIVATION_STRING_DATA. 12192


CK_EXTRACT_PARAMS; CK_EXTRACT_PARAMS_PTR 12193

CK_EXTRACT_PARAMS provides the parameter to the CKM_EXTRACT_KEY_FROM_KEY 12194 mechanism. It specifies which bit of the base key should be used as the first bit of the derived key. It is 12195 defined as follows: 12196

typedef CK_ULONG CK_EXTRACT_PARAMS; 12197

12198

CK_EXTRACT_PARAMS_PTR is a pointer to a CK_EXTRACT_PARAMS. 12199

6.43.3 Concatenation of a base key and another key 12200

This mechanism, denoted CKM_CONCATENATE_BASE_AND_KEY, derives a secret key from the 12201 concatenation of two existing secret keys. The two keys are specified by handles; the values of the keys 12202 specified are concatenated together in a buffer. 12203

This mechanism takes a parameter, a CK_OBJECT_HANDLE. This handle produces the key value 12204 information which is appended to the end of the base key’s value information (the base key is the key 12205 whose handle is supplied as an argument to C_DeriveKey). 12206

For example, if the value of the base key is 0x01234567, and the value of the other key is 0x89ABCDEF, 12207 then the value of the derived key will be taken from a buffer containing the string 0x0123456789ABCDEF. 12208

If no length or key type is provided in the template, then the key produced by this mechanism will be a 12209 generic secret key. Its length will be equal to the sum of the lengths of the values of the two original 12210 keys. 12211


If no length is provided in the template, but a key type is, then that key type must have a well-defined 12214 length. If it does, then the key produced by this mechanism will be of the type specified in the 12215 template. If it doesn’t, an error will be returned. 12216


If a DES, DES2, DES3, or CDMF key is derived with this mechanism, the parity bits of the key will be set 12219 properly. 12220

If the requested type of key requires more bytes than are available by concatenating the two original keys’ 12221 values, an error is generated. 12222


If either of the two original keys has its CKA_SENSITIVE attribute set to CK_TRUE, so does the 12224 derived key. If not, then the derived key’s CKA_SENSITIVE attribute is set either from the supplied 12225

template or from a default value. 12226

Similarly, if either of the two original keys has its CKA_EXTRACTABLE attribute set to CK_FALSE, 12227 so does the derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either 12228

from the supplied template or from a default value. 12229

The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if both of the 12230 original keys have their CKA_ALWAYS_SENSITIVE attributes set to CK_TRUE. 12231

Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 12232 both of the original keys have their CKA_NEVER_EXTRACTABLE attributes set to CK_TRUE. 12233

6.43.4 Concatenation of a base key and data 12234

This mechanism, denoted CKM_CONCATENATE_BASE_AND_DATA, derives a secret key by 12235 concatenating data onto the end of a specified secret key. 12236


This mechanism takes a parameter, a CK_KEY_DERIVATION_STRING_DATA structure, which 12237

specifies the length and value of the data which will be appended to the base key to derive another key. 12238

For example, if the value of the base key is 0x01234567, and the value of the data is 0x89ABCDEF, then 12239 the value of the derived key will be taken from a buffer containing the string 0x0123456789ABCDEF. 12240

If no length or key type is provided in the template, then the key produced by this mechanism will be a 12241 generic secret key. Its length will be equal to the sum of the lengths of the value of the original key 12242 and the data. 12243





If the requested type of key requires more bytes than are available by concatenating the original key’s 12253 value and the data, an error is generated. 12254


If the base key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, 12256 then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from a 12257 default value. 12258

Similarly, if the base key has its CKA_EXTRACTABLE attribute set to CK_FALSE, so does the 12259 derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either from the 12260

supplied template or from a default value. 12261

The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the base 12262 key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE. 12263

Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if 12264 the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE. 12265

6.43.5 Concatenation of data and a base key 12266

This mechanism, denoted CKM_CONCATENATE_DATA_AND_BASE, derives a secret key by 12267

prepending data to the start of a specified secret key. 12268


specifies the length and value of the data which will be prepended to the base key to derive another key. 12270

For example, if the value of the base key is 0x01234567, and the value of the data is 0x89ABCDEF, then 12271 the value of the derived key will be taken from a buffer containing the string 0x89ABCDEF01234567. 12272

If no length or key type is provided in the template, then the key produced by this mechanism will be a 12273 generic secret key. Its length will be equal to the sum of the lengths of the data and the value of the 12274 original key. 12275






If the requested type of key requires more bytes than are available by concatenating the data and the 12285 original key’s value, an error is generated. 12286







6.43.6 XORing of a key and data 12298

XORing key derivation, denoted CKM_XOR_BASE_AND_DATA, is a mechanism which provides the 12299 capability of deriving a secret key by performing a bit XORing of a key pointed to by a base key handle 12300 and some data. 12301


specifies the data with which to XOR the original key’s value. 12303

For example, if the value of the base key is 0x01234567, and the value of the data is 0x89ABCDEF, then 12304 the value of the derived key will be taken from a buffer containing the string 0x88888888. 12305

If no length or key type is provided in the template, then the key produced by this mechanism will be a 12306 generic secret key. Its length will be equal to the minimum of the lengths of the data and the value of 12307 the original key. 12308





If the requested type of key requires more bytes than are available by taking the shorter of the data and 12318 the original key’s value, an error is generated. 12319


If the base key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, 12321 then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from a 12322

default value. 12323






6.43.7 Extraction of one key from another key 12331

Extraction of one key from another key, denoted CKM_EXTRACT_KEY_FROM_KEY, is a mechanism 12332 which provides the capability of creating one secret key from the bits of another secret key. 12333

This mechanism has a parameter, a CK_EXTRACT_PARAMS, which specifies which bit of the original 12334 key should be used as the first bit of the newly-derived key. 12335

We give an example of how this mechanism works. Suppose a token has a secret key with the 4-byte 12336 value 0x329F84A9. We will derive a 2-byte secret key from this key, starting at bit position 21 (i.e., the 12337 value of the parameter to the CKM_EXTRACT_KEY_FROM_KEY mechanism is 21). 12338

1. We write the key’s value in binary: 0011 0010 1001 1111 1000 0100 1010 1001. We regard this 12339 binary string as holding the 32 bits of the key, labeled as b0, b1, …, b31. 12340

2. We then extract 16 consecutive bits (i.e., 2 bytes) from this binary string, starting at bit b21. We 12341 obtain the binary string 1001 0101 0010 0110. 12342

3. The value of the new key is thus 0x9526. 12343

Note that when constructing the value of the derived key, it is permissible to wrap around the end of the 12344 binary string representing the original key’s value. 12345

If the original key used in this process is sensitive, then the derived key must also be sensitive for the 12346 derivation to succeed. 12347

If no length or key type is provided in the template, then an error will be returned. 12348





If the requested type of key requires more bytes than the original key has, an error is generated. 12358







6.44 CMS 12370

Table 199, CMS Mechanisms vs. Functions 12371


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_CMS_SIG


Mechanisms: 12373

CKM_CMS_SIG 12374

6.44.2 CMS Signature Mechanism Objects 12375

These objects provide information relating to the CKM_CMS_SIG mechanism. CKM_CMS_SIG 12376 mechanism object attributes represent information about supported CMS signature attributes in the token. 12377 They are only present on tokens supporting the CKM_CMS_SIG mechanism, but must be present on 12378

those tokens. 12379

Table 200, CMS Signature Mechanism Object Attributes 12380


CKA_REQUIRED_CMS_ATTRIBUTES

Byte array Attributes the token always will include in the set of CMS signed attributes

CKA_DEFAULT_CMS_ATTRIBUTES Byte array Attributes the token will include in the set of CMS signed attributes in the absence of any attributes specified by the application

CKA_SUPPORTED_CMS_ATTRIBUTES

Byte array Attributes the token may include in the set of CMS signed attributes upon request by the application

The contents of each byte array will be a DER-encoded list of CMS Attributes with optional accompanying 12381 values. Any attributes in the list shall be identified with its object identifier, and any values shall be DER-12382 encoded. The list of attributes is defined in ASN.1 as: 12383

Attributes ::= SET SIZE (1..MAX) OF Attribute 12384

Attribute ::= SEQUENCE { 12385

attrType OBJECT IDENTIFIER, 12386

attrValues SET OF ANY DEFINED BY OBJECT IDENTIFIER 12387

OPTIONAL 12388

} 12389

The client may not set any of the attributes. 12390

6.44.3 CMS mechanism parameters 12391

CK_CMS_SIG_PARAMS, CK_CMS_SIG_PARAMS_PTR 12392

CK_CMS_SIG_PARAMS is a structure that provides the parameters to the CKM_CMS_SIG mechanism. 12393


typedef struct CK_CMS_SIG_PARAMS { 12395

CK_OBJECT_HANDLE certificateHandle; 12396

CK_MECHANISM_PTR pSigningMechanism; 12397

CK_MECHANISM_PTR pDigestMechanism; 12398


CK_UTF8CHAR_PTR pContentType; 12399

CK_BYTE_PTR pRequestedAttributes; 12400

CK_ULONG ulRequestedAttributesLen; 12401

CK_BYTE_PTR pRequiredAttributes; 12402

CK_ULONG ulRequiredAttributesLen; 12403

} CK_CMS_SIG_PARAMS; 12404

12405


certificateHandle Object handle for a certificate associated with the signing key. The 12407 token may use information from this certificate to identify the signer 12408 in the SignerInfo result value. CertificateHandle may be NULL_PTR 12409 if the certificate is not available as a PKCS #11 object or if the 12410 calling application leaves the choice of certificate completely to the 12411 token. 12412

pSigningMechanism Mechanism to use when signing a constructed CMS 12413 SignedAttributes value. E.g. CKM_SHA1_RSA_PKCS. 12414

pDigestMechanism Mechanism to use when digesting the data. Value shall be 12415 NULL_PTR when the digest mechanism to use follows from the 12416 pSigningMechanism parameter. 12417

pContentType NULL-terminated string indicating complete MIME Content-type of 12418 message to be signed; or the value NULL_PTR if the message is a 12419 MIME object (which the token can parse to determine its MIME 12420 Content-type if required). Use the value “application/octet-stream“ if 12421 the MIME type for the message is unknown or undefined. Note that 12422 the pContentType string shall conform to the syntax specified in 12423 RFC 2045, i.e. any parameters needed for correct presentation of 12424 the content by the token (such as, for example, a non-default 12425 “charset”) must be present. The token must follow rules and 12426 procedures defined in RFC 2045 when presenting the content. 12427

pRequestedAttributes Pointer to DER-encoded list of CMS Attributes the caller requests to 12428 be included in the signed attributes. Token may freely ignore this list 12429 or modify any supplied values. 12430

ulRequestedAttributesLen Length in bytes of the value pointed to by pRequestedAttributes 12431

pRequiredAttributes Pointer to DER-encoded list of CMS Attributes (with accompanying 12432 values) required to be included in the resulting signed attributes. 12433 Token must not modify any supplied values. If the token does not 12434 support one or more of the attributes, or does not accept provided 12435 values, the signature operation will fail. The token will use its own 12436 default attributes when signing if both the pRequestedAttributes and 12437 pRequiredAttributes field are set to NULL_PTR. 12438

ulRequiredAttributesLen Length in bytes, of the value pointed to by pRequiredAttributes. 12439

6.44.4 CMS signatures 12440

The CMS mechanism, denoted CKM_CMS_SIG, is a multi-purpose mechanism based on the structures 12441 defined in PKCS #7 and RFC 2630. It supports single- or multiple-part signatures with and without 12442 message recovery. The mechanism is intended for use with, e.g., PTDs (see MeT-PTD) or other capable 12443 tokens. The token will construct a CMS SignedAttributes value and compute a signature on this value. 12444 The content of the SignedAttributes value is decided by the token, however the caller can suggest some 12445 attributes in the parameter pRequestedAttributes. The caller can also require some attributes to be 12446


present through the parameters pRequiredAttributes. The signature is computed in accordance with the 12447 parameter pSigningMechanism. 12448

When this mechanism is used in successful calls to C_Sign or C_SignFinal, the pSignature return value 12449 will point to a DER-encoded value of type SignerInfo. SignerInfo is defined in ASN.1 as follows (for a 12450

complete definition of all fields and types, see RFC 2630): 12451

SignerInfo ::= SEQUENCE { 12452

version CMSVersion, 12453

sid SignerIdentifier, 12454

digestAlgorithm DigestAlgorithmIdentifier, 12455

signedAttrs [0] IMPLICIT SignedAttributes OPTIONAL, 12456

signatureAlgorithm SignatureAlgorithmIdentifier, 12457

signature SignatureValue, 12458

unsignedAttrs [1] IMPLICIT UnsignedAttributes 12459

OPTIONAL } 12460

The certificateHandle parameter, when set, helps the token populate the sid field of the SignerInfo value. 12461 If certificateHandle is NULL_PTR the choice of a suitable certificate reference in the SignerInfo result 12462

value is left to the token (the token could, e.g., interact with the user). 12463

This mechanism shall not be used in calls to C_Verify or C_VerifyFinal (use the pSigningMechanism 12464

mechanism instead). 12465

For the pRequiredAttributes field, the token may have to interact with the user to find out whether to 12466 accept a proposed value or not. The token should never accept any proposed attribute values without 12467 some kind of confirmation from its owner (but this could be through, e.g., configuration or policy settings 12468 and not direct interaction). If a user rejects proposed values, or the signature request as such, the value 12469 CKR_FUNCTION_REJECTED shall be returned. 12470

When possible, applications should use the CKM_CMS_SIG mechanism when generating CMS-12471 compatible signatures rather than lower-level mechanisms such as CKM_SHA1_RSA_PKCS. This is 12472 especially true when the signatures are to be made on content that the token is able to present to a user. 12473 Exceptions may include those cases where the token does not support a particular signing attribute. Note 12474 however that the token may refuse usage of a particular signature key unless the content to be signed is 12475 known (i.e. the CKM_CMS_SIG mechanism is used). 12476

When a token does not have presentation capabilities, the PKCS #11-aware application may avoid 12477 sending the whole message to the token by electing to use a suitable signature mechanism (e.g. 12478 CKM_RSA_PKCS) as the pSigningMechanism value in the CK_CMS_SIG_PARAMS structure, and 12479

digesting the message itself before passing it to the token. 12480

PKCS #11-aware applications making use of tokens with presentation capabilities, should attempt to 12481 provide messages to be signed by the token in a format possible for the token to present to the user. 12482 Tokens that receive multipart MIME-messages for which only certain parts are possible to present may 12483 fail the signature operation with a return value of CKR_DATA_INVALID, but may also choose to add a 12484

signing attribute indicating which parts of the message were possible to present. 12485

6.45 Blowfish 12486

Blowfish, a secret-key block cipher. It is a Feistel network, iterating a simple encryption function 16 times. 12487 The block size is 64 bits, and the key can be any length up to 448 bits. Although there is a complex 12488 initialization phase required before any encryption can take place, the actual encryption of data is very 12489 efficient on large microprocessors. 12490

12491

Table 201, Blowfish Mechanisms vs. Functions 12492


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_BLOWFISH_CBC ✓ ✓

CKM_BLOWFISH_CBC_PAD ✓ ✓


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

Mechanisms: 12496

CKM_BLOWFISH_KEY_GEN 12497

CKM_BLOWFISH_CBC 12498

CKM_BLOWFISH_CBC_PAD 12499

6.45.2 BLOWFISH secret key objects 12500

Blowfish secret key objects (object class CKO_SECRET_KEY, key type CKK_BLOWFISH) hold Blowfish 12501 keys. The following table defines the Blowfish secret key object attributes, in addition to the common 12502 attributes defined for this object class: 12503

Table 202, BLOWFISH Secret Key Object 12504


CKA_VALUE1,4,6,7

Byte array Key value the key can be any length up to 448 bits. Bit length restricted to a byte array.

CKA_VALUE_LEN2,3



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


CK_KEY_TYPE keyType = CKK_BLOWFISH; 12508

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

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









}; 12519


6.45.3 Blowfish key generation 12520

The Blowfish key generation mechanism, denoted CKM_BLOWFISH_KEY_GEN, is a key generation 12521 mechanism Blowfish. 12522


The mechanism generates Blowfish keys with a particular length, as specified in the CKA_VALUE_LEN 12524

attribute of the template for the key. 12525

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

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

6.45.4 Blowfish-CBC 12531

Blowfish-CBC, denoted CKM_BLOWFISH_CBC, is a mechanism for single- and multiple-part encryption 12532

and decryption; key wrapping; and key unwrapping. 12533


This mechanism can wrap and unwrap any secret key. For wrapping, the mechanism encrypts the value 12535 of the CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size 12536 minus one null bytes so that the resulting length is a multiple of the block size. The output data is the 12537 same length as the padded input data. It does not wrap the key type, key length, or any other information 12538 about the key; the application must convey these separately. 12539




Table 203, BLOWFISH-CBC: Key and Data Length 12545

Function Key type Input Length Output Length

C_Encrypt BLOWFISH Multiple of block size Same as input length

C_Decrypt BLOWFISH Multiple of block size Same as input length

C_WrapKey BLOWFISH Any Input length rounded up to multiple of the block size

C_UnwrapKey BLOWFISH Multiple of block size Determined by type of key being unwrapped or CKA_VALUE_LEN

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

6.45.5 Blowfish-CBC with PKCS padding 12548

Blowfish-CBC-PAD, denoted CKM_BLOWFISH_CBC_PAD, is a mechanism for single- and multiple-part 12549 encryption and decryption, key wrapping and key unwrapping, cipher-block chaining mode and the block 12550 cipher padding method detailed in PKCS #7. 12551


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

The entries in the table below for data length constraints when wrapping and unwrapping keys do not 12556 apply to wrapping and unwrapping private keys. 12557



12559

Table 204, BLOWFISH-CBC with PKCS Padding: Key and Data Length 12560

Function Key type Input Length Output Length

C_Encrypt BLOWFISH Any Input length rounded up to multiple of the block size

C_Decrypt BLOWFISH Multiple of block size Between 1 and block length block size bytes shorter than input length

C_WrapKey BLOWFISH Any Input length rounded up to multiple of the block size

C_UnwrapKey BLOWFISH Multiple of block size Between 1 and block length block size bytes shorter than input length

6.46 Twofish 12561

Ref. https://www.schneier.com/twofish.html 12562


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

Mechanisms: 12566

CKM_TWOFISH_KEY_GEN 12567

CKM_TWOFISH_CBC 12568

CKM_TWOFISH_CBC_PAD 12569

12570

6.46.2 Twofish secret key objects 12571

Twofish secret key objects (object class CKO_SECRET_KEY, key type CKK_TWOFISH) hold Twofish 12572 keys. The following table defines the Twofish secret key object attributes, in addition to the common 12573 attributes defined for this object class: 12574

Table 205, Twofish Secret Key Object 12575


CKA_VALUE1,4,6,7

Byte array Key value 128-, 192-, or 256-bit key

CKA_VALUE_LEN2,3



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


CK_KEY_TYPE keyType = CKK_TWOFISH; 12579

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

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










}; 12590

6.46.3 Twofish key generation 12591

The Twofish key generation mechanism, denoted CKM_TWOFISH_KEY_GEN, is a key generation 12592

mechanism Twofish. 12593


The mechanism generates Blowfish keys with a particular length, as specified in the CKA_VALUE_LEN 12595

attribute of the template for the key. 12596



specify the supported range of key sizes, in bytes. 12601

6.46.4 Twofish -CBC 12602

Twofish-CBC, denoted CKM_TWOFISH_CBC, is a mechanism for single- and multiple-part encryption 12603

and decryption; key wrapping; and key unwrapping. 12604


6.46.5 Twofish-CBC with PKCS padding 12606

Twofish-CBC-PAD, denoted CKM_TWOFISH_CBC_PAD, is a mechanism for single- and multiple-part 12607 encryption and decryption, key wrapping and key unwrapping, cipher-block chaining mode and the block 12608 cipher padding method detailed in PKCS #7. 12609


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

6.47 CAMELLIA 12614

Camellia is a block cipher with 128-bit block size and 128-, 192-, and 256-bit keys, similar to AES. 12615 Camellia is described e.g. in IETF RFC 3713. 12616

Table 206, Camellia Mechanisms vs. Functions 12617

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_CAMELLIA_KEY_GEN

CKM_CAMELLIA_ECB

CKM_CAMELLIA_CBC


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_CAMELLIA_CBC_PAD

CKM_CAMELLIA_MAC_GENERAL

CKM_CAMELLIA_MAC

CKM_CAMELLIA_ECB_ENCRYPT_DATA

CKM_CAMELLIA_CBC_ENCRYPT_DATA


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

Mechanisms: 12621

CKM_CAMELLIA_KEY_GEN 12622

CKM_CAMELLIA_ECB 12623

CKM_CAMELLIA_CBC 12624

CKM_CAMELLIA_MAC 12625

CKM_CAMELLIA_MAC_GENERAL 12626

CKM_CAMELLIA_CBC_PAD 12627

6.47.2 Camellia secret key objects 12628

Camellia secret key objects (object class CKO_SECRET_KEY, key type CKK_CAMELLIA) hold 12629 Camellia keys. The following table defines the Camellia secret key object attributes, in addition to the 12630 common attributes defined for this object class: 12631

Table 207, Camellia Secret Key Object Attributes 12632


CKA_VALUE1,4,6,7


CKA_VALUE_LEN2,3,6



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


CK_KEY_TYPE keyType = CKK_CAMELLIA; 12636

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

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










}; 12647

6.47.3 Camellia key generation 12648

The Camellia key generation mechanism, denoted CKM_CAMELLIA_KEY_GEN, is a key generation 12649 mechanism for Camellia. 12650


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

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


specify the supported range of Camellia key sizes, in bytes. 12658

6.47.4 Camellia-ECB 12659

Camellia-ECB, denoted CKM_CAMELLIA_ECB, is a mechanism for single- and multiple-part encryption 12660

and decryption; key wrapping; and key unwrapping, based on Camellia and electronic codebook mode. 12661






Table 208, Camellia-ECB: Key and Data Length 12674



C_Encrypt CKK_CAMELLIA multiple of block size


C_Decrypt CKK_CAMELLIA multiple of block size


C_WrapKey CKK_CAMELLIA any input length rounded up to multiple of block size

C_UnwrapKey CKK_CAMELLIA 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 12675 specify the supported range of Camellia key sizes, in bytes. 12676


6.47.5 Camellia-CBC 12677

Camellia-CBC, denoted CKM_CAMELLIA_CBC, is a mechanism for single- and multiple-part encryption 12678 and decryption; key wrapping; and key unwrapping, based on Camellia and cipher-block chaining mode. 12679



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


Table 209, Camellia-CBC: Key and Data Length 12692



C_Encrypt CKK_CAMELLIA multiple of block size




C_WrapKey CKK_CAMELLIA any input length rounded up to multiple of the

block size




6.47.6 Camellia-CBC with PKCS padding 12695

Camellia-CBC with PKCS padding, denoted CKM_CAMELLIA_CBC_PAD, is a mechanism for single- 12696 and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on Camellia; 12697 cipher-block chaining mode; and the block cipher padding method detailed in PKCS #7. 12698



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


Table 210, Camellia-CBC with PKCS Padding: Key and Data Length 12708



Output length

C_Encrypt CKK_CAMELLIA any input length rounded up to multiple of the block size



C_WrapKey CKK_CAMELLIA any input length rounded up to multiple of the block size




12711

6.47.7 CAMELLIA with Counter mechanism parameters 12712

CK_CAMELLIA_CTR_PARAMS; CK_CAMELLIA_CTR_PARAMS_PTR 12713

CK_CAMELLIA_CTR_PARAMS is a structure that provides the parameters to the 12714 CKM_CAMELLIA_CTR mechanism. It is defined as follows: 12715

typedef struct CK_CAMELLIA_CTR_PARAMS { 12716

CK_ULONG ulCounterBits; 12717

CK_BYTE cb[16]; 12718

} CK_CAMELLIA_CTR_PARAMS; 12719

12720

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

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

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

0 1 2 3 12728 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 12729 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 12730 | Nonce | 12731 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 12732 | Initialization Vector (IV) | 12733 | | 12734 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 12735 | Block Counter | 12736 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 12737

12738

This construction permits each packet to consist of up to 232

-1 blocks = 4,294,967,295 blocks = 12739 68,719,476,720 octets. 12740

CK_CAMELLIA_CTR_PARAMS_PTR is a pointer to a CK_CAMELLIA_CTR_PARAMS. 12741

12742


6.47.8 General-length Camellia-MAC 12743

General-length Camellia -MAC, denoted CKM_CAMELLIA_MAC_GENERAL, is a mechanism for single- 12744 and multiple-part signatures and verification, based on Camellia and data authentication as defined 12745 in.[CAMELLIA] 12746



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


Table 211, General-length Camellia-MAC: Key and Data Length 12752


Signature length

C_Sign CKK_CAMELLIA any 1-block size, as specified in parameters

C_Verify CKK_CAMELLIA any 1-block size, as specified in parameters


6.47.9 Camellia-MAC 12755

Camellia-MAC, denoted by CKM_CAMELLIA_MAC, is a special case of the general-length Camellia-12756 MAC mechanism. Camellia-MAC always produces and verifies MACs that are half the block size in 12757 length. 12758



Table 212, Camellia-MAC: Key and Data Length 12761


Signature length

C_Sign CKK_CAMELLIA any ½ block size (8 bytes)

C_Verify CKK_CAMELLIA any ½ block size (8 bytes)


6.48 Key derivation by data encryption - Camellia 12764



Mechanisms: 12768

CKM_CAMELLIA_ECB_ENCRYPT_DATA 12769

CKM_CAMELLIA_CBC_ENCRYPT_DATA 12770

12771

typedef struct CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS { 12772

CK_BYTE iv[16]; 12773



} CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS; 12776


12777

typedef CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS CK_PTR 12778

CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS_PTR; 12779


Uses CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS, and CK_KEY_DERIVATION_STRING_DATA. 12781

Table 213, Mechanism Parameters for Camellia-based key derivation 12782

CKM_CAMELLIA_ECB_ENCRYPT_DATA Uses CK_KEY_DERIVATION_STRING_DATA structure. Parameter is the data to be encrypted and must be a multiple of 16 long.

CKM_CAMELLIA_CBC_ENCRYPT_DATA Uses CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS. Parameter is an 16 byte IV value followed by the data. The data value part must be a multiple of 16 bytes long.

12783

6.49 ARIA 12784

ARIA is a block cipher with 128-bit block size and 128-, 192-, and 256-bit keys, similar to AES. ARIA is 12785 described in NSRI “Specification of ARIA”. 12786

Table 214, ARIA Mechanisms vs. Functions 12787

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_ARIA_KEY_GEN

CKM_ARIA_ECB

CKM_ARIA_CBC

CKM_ARIA_CBC_PAD

CKM_ARIA_MAC_GENERAL

CKM_ARIA_MAC

CKM_ARIA_ECB_ENCRYPT_DATA

CKM_ARIA_CBC_ENCRYPT_DATA


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

Mechanisms: 12791

CKM_ARIA_KEY_GEN 12792

CKM_ARIA_ECB 12793

CKM_ARIA_CBC 12794

CKM_ARIA_MAC 12795

CKM_ARIA_MAC_GENERAL 12796


CKM_ARIA_CBC_PAD 12797

6.49.2 Aria secret key objects 12798

ARIA secret key objects (object class CKO_SECRET_KEY, key type CKK_ARIA) hold ARIA keys. The 12799 following table defines the ARIA secret key object attributes, in addition to the common attributes defined 12800 for this object class: 12801

Table 215, ARIA Secret Key Object Attributes 12802


CKA_VALUE1,4,6,7


CKA_VALUE_LEN2,3,6



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


CK_KEY_TYPE keyType = CKK_ARIA; 12806

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

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









}; 12817

6.49.3 ARIA key generation 12818

The ARIA key generation mechanism, denoted CKM_ARIA_KEY_GEN, is a key generation mechanism 12819 for Aria. 12820


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

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

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

6.49.4 ARIA-ECB 12829

ARIA-ECB, denoted CKM_ARIA_ECB, is a mechanism for single- and multiple-part encryption and 12830

decryption; key wrapping; and key unwrapping, based on Aria and electronic codebook mode. 12831


This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 12833 wrap/unwrap every secret key that it supports. For wrapping, the mechanism encrypts the value of the 12834 CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus 12835


one null bytes so that the resulting length is a multiple of the block size. The output data is the same 12836 length as the padded input data. It does not wrap the key type, key length, or any other information about 12837 the key; the application must convey these separately. 12838




Table 216, ARIA-ECB: Key and Data Length 12844



C_Encrypt CKK_ARIA multiple of block size


C_Decrypt CKK_ARIA multiple of block size


C_WrapKey CKK_ARIA any input length rounded up to multiple of block size

C_UnwrapKey CKK_ARIA multiple of block size

determined by type of key being unwrapped or

CKA_VALUE_LEN


specify the supported range of ARIA key sizes, in bytes. 12846

6.49.5 ARIA-CBC 12847

ARIA-CBC, denoted CKM_ARIA_CBC, is a mechanism for single- and multiple-part encryption and 12848

decryption; key wrapping; and key unwrapping, based on ARIA and cipher-block chaining mode. 12849






Table 217, ARIA-CBC: Key and Data Length 12862




C_Encrypt CKK_ARIA multiple of block size




C_WrapKey CKK_ARIA any input length rounded up to multiple of the

block size



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

6.49.6 ARIA-CBC with PKCS padding 12865

ARIA-CBC with PKCS padding, denoted CKM_ARIA_CBC_PAD, is a mechanism for single- and 12866 multiple-part encryption and decryption; key wrapping; and key unwrapping, based on ARIA; cipher-block 12867 chaining mode; and the block cipher padding method detailed in PKCS #7. 12868



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


Table 218, ARIA-CBC with PKCS Padding: Key and Data Length 12878


Output length

C_Encrypt CKK_ARIA any input length rounded up to multiple of the block size



C_WrapKey CKK_ARIA any input length rounded up to multiple of the block size




6.49.7 General-length ARIA-MAC 12881

General-length ARIA -MAC, denoted CKM_ARIA_MAC_GENERAL, is a mechanism for single- and 12882

multiple-part signatures and verification, based on ARIA and data authentication as defined in [FIPS 113]. 12883




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


Table 219, General-length ARIA-MAC: Key and Data Length 12889


Signature length

C_Sign CKK_ARIA any 1-block size, as specified in parameters

C_Verify CKK_ARIA any 1-block size, as specified in parameters


6.49.8 ARIA-MAC 12892

ARIA-MAC, denoted by CKM_ARIA_MAC, is a special case of the general-length ARIA-MAC 12893

mechanism. ARIA-MAC always produces and verifies MACs that are half the block size in length. 12894



Table 220, ARIA-MAC: Key and Data Length 12897


Signature length

C_Sign CKK_ARIA any ½ block size (8 bytes)

C_Verify CKK_ARIA any ½ block size (8 bytes)


specify the supported range of ARIA key sizes, in bytes. 12899

6.50 Key derivation by data encryption - ARIA 12900



Mechanisms: 12904

CKM_ARIA_ECB_ENCRYPT_DATA 12905

CKM_ARIA_CBC_ENCRYPT_DATA 12906

12907

typedef struct CK_ARIA_CBC_ENCRYPT_DATA_PARAMS { 12908

CK_BYTE iv[16]; 12909



} CK_ARIA_CBC_ENCRYPT_DATA_PARAMS; 12912

12913

typedef CK_ARIA_CBC_ENCRYPT_DATA_PARAMS CK_PTR 12914

CK_ARIA_CBC_ENCRYPT_DATA_PARAMS_PTR; 12915


Uses CK_ARIA_CBC_ENCRYPT_DATA_PARAMS, and CK_KEY_DERIVATION_STRING_DATA. 12917

Table 221, Mechanism Parameters for Aria-based key derivation 12918


CKM_ARIA_ECB_ENCRYPT_DATA Uses CK_KEY_DERIVATION_STRING_DATA structure. Parameter is the data to be encrypted and must be a multiple of 16 long.

CKM_ARIA_CBC_ENCRYPT_DATA Uses CK_ARIA_CBC_ENCRYPT_DATA_PARAMS. Parameter is an 16 byte IV value followed by the data. The data value part must be a multiple of 16 bytes long.

12919

6.51 SEED 12920

SEED is a symmetric block cipher developed by the South Korean Information Security Agency (KISA). It 12921 has a 128-bit key size and a 128-bit block size. 12922

Its specification has been published as Internet [RFC 4269]. 12923

RFCs have been published defining the use of SEED in 12924

TLS ftp://ftp.rfc-editor.org/in-notes/rfc4162.txt 12925

IPsec ftp://ftp.rfc-editor.org/in-notes/rfc4196.txt 12926

CMS ftp://ftp.rfc-editor.org/in-notes/rfc4010.txt 12927

12928

TLS cipher suites that use SEED include: 12929

CipherSuite TLS_RSA_WITH_SEED_CBC_SHA = { 0x00, 12930

0x96}; 12931

CipherSuite TLS_DH_DSS_WITH_SEED_CBC_SHA = { 0x00, 12932

0x97}; 12933

CipherSuite TLS_DH_RSA_WITH_SEED_CBC_SHA = { 0x00, 12934

0x98}; 12935

CipherSuite TLS_DHE_DSS_WITH_SEED_CBC_SHA = { 0x00, 12936

0x99}; 12937

CipherSuite TLS_DHE_RSA_WITH_SEED_CBC_SHA = { 0x00, 12938

0x9A}; 12939

CipherSuite TLS_DH_anon_WITH_SEED_CBC_SHA = { 0x00, 12940

0x9B}; 12941

12942

As with any block cipher, it can be used in the ECB, CBC, OFB and CFB modes of operation, as well as 12943 in a MAC algorithm such as HMAC. 12944

OIDs have been published for all these uses. A list may be seen at 12945 http://www.alvestrand.no/objectid/1.2.410.200004.1.html 12946

12947

Table 222, SEED Mechanisms vs. Functions 12948

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SEED_KEY_GEN

ftp://ftp.rfc-editor.org/in-notes/rfc4162.txt



http://www.alvestrand.no/objectid/1.2.410.200004.1.html


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SEED_ECB

CKM_SEED_CBC

CKM_SEED_CBC_PAD

CKM_SEED_MAC_GENERAL

CKM_SEED_MAC

CKM_SEED_ECB_ENCRYPT_DATA

CKM_SEED_CBC_ENCRYPT_DATA


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

Mechanisms: 12952

CKM_SEED_KEY_GEN 12953

CKM_SEED_ECB 12954

CKM_SEED_CBC 12955

CKM_SEED_MAC 12956

CKM_SEED_MAC_GENERAL 12957

CKM_SEED_CBC_PAD 12958

12959

For all of these mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO 12960 are always 16. 12961

6.51.2 SEED secret key objects 12962

SEED secret key objects (object class CKO_SECRET_KEY, key type CKK_SEED) hold SEED keys. 12963 The following table defines the secret key object attributes, in addition to the common attributes defined 12964 for this object class: 12965

Table 223, SEED Secret Key Object Attributes 12966


CKA_VALUE1,4,6,7



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


CK_KEY_TYPE keyType = CKK_SEED; 12970

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

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










}; 12981

6.51.3 SEED key generation 12982

The SEED key generation mechanism, denoted CKM_SEED_KEY_GEN, is a key generation mechanism 12983 for SEED. 12984


The mechanism generates SEED keys. 12986

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

6.51.4 SEED-ECB 12990

SEED-ECB, denoted CKM_SEED_ECB, is a mechanism for single- and multiple-part encryption and 12991 decryption; key wrapping; and key unwrapping, based on SEED and electronic codebook mode. 12992


6.51.5 SEED-CBC 12994

SEED-CBC, denoted CKM_SEED_CBC, is a mechanism for single- and multiple-part encryption and 12995

decryption; key wrapping; and key unwrapping, based on SEED and cipher-block chaining mode. 12996


6.51.6 SEED-CBC with PKCS padding 12998

SEED-CBC with PKCS padding, denoted CKM_SEED_CBC_PAD, is a mechanism for single- and 12999 multiple-part encryption and decryption; key wrapping; and key unwrapping, based on SEED; cipher-13000 block chaining mode; and the block cipher padding method detailed in PKCS #7. 13001


6.51.7 General-length SEED-MAC 13003

General-length SEED-MAC, denoted CKM_SEED_MAC_GENERAL, is a mechanism for single- and 13004 multiple-part signatures and verification, based on SEED and data authentication as defined in 0.. 13005

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

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

6.51.8 SEED-MAC 13010

SEED-MAC, denoted by CKM_SEED_MAC, is a special case of the general-length SEED-MAC 13011

mechanism. SEED-MAC always produces and verifies MACs that are half the block size in length. 13012


Comment [DM1]: I could not find the original reference. Therefore, better deleted

than wrong.


6.52 Key derivation by data encryption - SEED 13014



Mechanisms: 13018

CKM_SEED_ECB_ENCRYPT_DATA 13019

CKM_SEED_CBC_ENCRYPT_DATA 13020

13021

typedef struct CK_SEED_CBC_ENCRYPT_DATA_PARAMS { 13022

CK_BYTE iv[16]; 13023



} CK_SEED_CBC_ENCRYPT_DATA_PARAMS; 13026

13027

typedef CK_SEED_CBC_ENCRYPT_DATA_PARAMS CK_PTR 13028

CK_SEED_CBC_ENCRYPT_DATA_PARAMS_PTR; 13029


Table 224, Mechanism Parameters for SEED-based key derivation 13031

CKM_SEED_ECB_ENCRYPT_DATA Uses CK_KEY_DERIVATION_STRING_DATA structure. Parameter is the data to be encrypted and must be a multiple of 16 long.

CKM_SEED_CBC_ENCRYPT_DATA Uses CK_SEED_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.

13032

6.53 OTP 13033

6.53.1 Usage overview 13034

OTP tokens represented as PKCS #11 mechanisms may be used in a variety of ways. The usage cases 13035 can be categorized according to the type of sought functionality. 13036


6.53.2 Case 1: Generation of OTP values 13037

. 13038

Figure 2: Retrieving OTP values through C_Sign 13039

Figure 2Figure 2 shows an integration of PKCS #11 into an application that needs to authenticate users 13040 holding OTP tokens. In this particular example, a connected hardware token is used, but a software token 13041 is equally possible. The application invokes C_Sign to retrieve the OTP value from the token. In the 13042 example, the application then passes the retrieved OTP value to a client API that sends it via the network 13043 to an authentication server. The client API may implement a standard authentication protocol such as 13044 RADIUS [RFC 2865] or EAP [RFC 3748], or a proprietary protocol such as that used by RSA Security's 13045 ACE/Agent

® software. 13046


6.53.3 Case 2: Verification of provided OTP values 13047

13048

Figure 3: Server-side verification of OTP values 13049

Figure 3Figure 3 illustrates the server-side equivalent of the scenario depicted in Figure 2Figure 2. In this 13050 case, a server application invokes C_Verify with the received OTP value as the signature value to be 13051 verified. 13052

Server Application

PKCS #11 Library

C_Verify()

Internal Token API

Token (or query to authentication

server)


6.53.4 Case 3: Generation of OTP keys 13053

13054

Figure 4: Generation of an OTP key 13055

Figure 4Figure 4 shows an integration of PKCS #11 into an application that generates OTP keys. The 13056 application invokes C_GenerateKey to generate an OTP key of a particular type on the token. The key 13057

may subsequently be used as a basis to generate OTP values. 13058

6.53.5 OTP objects 13059

6.53.5.1 Key objects 13060

OTP key objects (object class CKO_OTP_KEY) hold secret keys used by OTP tokens. The following 13061 table defines the attributes common to all OTP keys, in addition to the attributes defined for secret keys, 13062 all of which are inherited by this class: 13063

Table 225: Common OTP key attributes 13064

Client Application

PKCS #11 Library

C_GenerateKey()

Internal Token API

Token (or software version thereof)



CKA_OTP_FORMAT CK_ULONG Format of OTP values produced with this key:

CK_OTP_FORMAT_DECIMAL = Decimal (default) (UTF8-encoded)

CK_OTP_FORMAT_HEXADECIMAL = Hexadecimal (UTF8-encoded)

CK_OTP_FORMAT_ALPHANUMERIC = Alphanumeric (UTF8-encoded)

CK_OTP_FORMAT_BINARY = Only binary values.

CKA_OTP_LENGTH9 CK_ULONG Default length of OTP values (in the

CKA_OTP_FORMAT) produced with this key.

CKA_OTP_USER_FRIENDLY_MODE9 CK_BBOOL Set to CK_TRUE when the token is

capable of returning OTPs suitable for human consumption. See the description of CKF_USER_FRIENDLY_OTP below.

CKA_OTP_CHALLENGE_REQUIREMENT

9

CK_ULONG Parameter requirements when generating or verifying OTP values with this key:

CK_OTP_PARAM_MANDATORY = A challenge must be supplied.

CK_OTP_PARAM_OPTIONAL = A challenge may be supplied but need not be. CK_OTP_PARAM_IGNORED = A challenge, if supplied, will be ignored.

CKA_OTP_TIME_REQUIREMENT9 CK_ULONG Parameter requirements when

generating or verifying OTP values with this key:

CK_OTP_PARAM_MANDATORY = A time value must be supplied.

CK_OTP_PARAM_OPTIONAL = A time value may be supplied but need not be. CK_OTP_PARAM_IGNORED = A time value, if supplied, will be ignored.


CKA_OTP_COUNTER_REQUIREMENT

9

CK_ULONG Parameter requirements when generating or verifying OTP values with this key:

CK_OTP_PARAM_MANDATORY = A counter value must be supplied.

CK_OTP_PARAM_OPTIONAL = A counter value may be supplied but need not be. CK_OTP_PARAM_IGNORED = A counter value, if supplied, will be ignored.

CKA_OTP_PIN_REQUIREMENT9 CK_ULONG Parameter requirements when

generating or verifying OTP values with this key:

CK_OTP_PARAM_MANDATORY = A PIN value must be supplied.

CK_OTP_PARAM_OPTIONAL = A PIN value may be supplied but need not be (if not supplied, then library will be responsible for collecting it)

CK_OTP_PARAM_IGNORED = A PIN value, if supplied, will be ignored.

CKA_OTP_COUNTER Byte array Value of the associated internal counter. Default value is empty (i.e. ulValueLen = 0).

CKA_OTP_TIME RFC 2279 string

Value of the associated internal UTC time in the form YYYYMMDDhhmmss. Default value is empty (i.e. ulValueLen= 0).

CKA_OTP_USER_IDENTIFIER RFC 2279 string

Text string that identifies a user associated with the OTP key (may be used to enhance the user experience). Default value is empty (i.e. ulValueLen = 0).

CKA_OTP_SERVICE_IDENTIFIER RFC 2279 string

Text string that identifies a service that may validate OTPs generated by this key. Default value is empty (i.e. ulValueLen = 0).

CKA_OTP_SERVICE_LOGO Byte array Logotype image that identifies a service that may validate OTPs generated by this key. Default value is empty (i.e. ulValueLen = 0).

CKA_OTP_SERVICE_LOGO_TYPE RFC 2279 string

MIME type of the CKA_OTP_SERVICE_LOGO attribute value. Default value is empty (i.e. ulValueLen = 0).

CKA_VALUE1, 4, 6, 7

Byte array Value of the key.

CKA_VALUE_LEN2, 3

CK_ULONG Length in bytes of key value.



Note: A Cryptoki library may support PIN-code caching in order to reduce user interactions. An OTP-13066 PKCS #11 application should therefore always consult the state of the CKA_OTP_PIN_REQUIREMENT 13067 attribute before each call to C_SignInit, as the value of this attribute may change dynamically. 13068

For OTP tokens with multiple keys, the keys may be enumerated using C_FindObjects. The 13069 CKA_OTP_SERVICE_IDENTIFIER and/or the CKA_OTP_SERVICE_LOGO attribute may be used to 13070 distinguish between keys. The actual choice of key for a particular operation is however application-13071 specific and beyond the scope of this document. 13072

For all OTP keys, the CKA_ALLOWED_MECHANISMS attribute should be set as required. 13073

6.53.6 OTP-related notifications 13074

This document extends the set of defined notifications as follows: 13075

CKN_OTP_CHANGED Cryptoki is informing the application that the OTP for a key on a 13076 connected token just changed. This notification is particularly useful 13077 when applications wish to display the current OTP value for time-13078 based mechanisms. 13079

6.53.7 OTP mechanisms 13080

The following table shows, for the OTP mechanisms defined in this document, their support by different 13081 cryptographic operations. For any particular token, of course, a particular operation may well support 13082 only a subset of the mechanisms listed. There is also no guarantee that a token that supports one 13083 mechanism for some operation supports any other mechanism for any other operation (or even supports 13084 that same mechanism for any other operation). 13085

Table 226: OTP mechanisms vs. applicable functions 13086

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SECURID_KEY_GEN

CKM_SECURID

CKM_HOTP_KEY_GEN

CKM_HOTP

CKM_ACTI_KEY_GEN

CKM_ACTI

The remainder of this section will present in detail the OTP mechanisms and the parameters that are 13087 supplied to them. 13088

6.53.7.1 OTP mechanism parameters 13089

CK_OTP_PARAM_TYPE 13090

CK_OTP_PARAM_TYPE is a value that identifies an OTP parameter type. It is defined as follows: 13091

typedef CK_ULONG CK_OTP_PARAM_TYPE; 13092

The following CK_OTP_PARAM_TYPE types are defined: 13093

Table 227, OTP parameter types 13094



CK_OTP_PIN RFC 2279 string

A UTF8 string containing a PIN for use when computing or verifying PIN-based OTP values.

CK_OTP_CHALLENGE Byte array Challenge to use when computing or verifying challenge-based OTP values.

CK_OTP_TIME RFC 2279 string

UTC time value in the form YYYYMMDDhhmmss to use when computing or verifying time-based OTP values.

CK_OTP_COUNTER Byte array Counter value to use when computing or verifying counter-based OTP values.

CK_OTP_FLAGS CK_FLAGS Bit flags indicating the characteristics of the sought OTP as defined below.

CK_OTP_OUTPUT_LENGTH CK_ULONG Desired output length (overrides any default value). A Cryptoki library will return CKR_MECHANISM_PARAM_INVALID if a provided length value is not supported.

CK_OTP_OUTPUT_FORMAT

CK_ULONG Returned OTP format (allowed values are the same as for CKA_OTP_FORMAT). This parameter is only intended for C_Sign output, see paragraphs below. When not present, the returned OTP format will be the same as the value of the CKA_OTP_FORMAT attribute for the key in question.

CK_OTP_VALUE Byte array An actual OTP value. This parameter type is intended for C_Sign output, see paragraphs below.

13095

The following table defines the possible values for the CK_OTP_FLAGS type: 13096

Table 228: OTP Mechanism Flags 13097

Bit flag Mask Meaning

CKF_NEXT_OTP 0x00000001 True (i.e. set) if the OTP computation shall be for the next OTP, rather than the current one (current being interpreted in the context of the algorithm, e.g. for the current counter value or current time window). A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if the CKF_NEXT_OTP flag is set and the OTP mechanism in question does not support the concept of “next” OTP or the library is not capable of generating the next OTP

9.

9 Applications that may need to retrieve the next OTP should be prepared to handle this situation. For example, an application could store the OTP value returned

by C_Sign so that, if a next OTP is required, it can compare it to the OTP value returned by subsequent calls to C_Sign should it turn out that the library does not

support the CKF_NEXT_OTP flag.


Bit flag Mask Meaning

CKF_EXCLUDE_TIME 0x00000002 True (i.e. set) if the OTP computation must not include a time value. Will have an effect only on mechanisms that do include a time value in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed.

CKF_EXCLUDE_COUNTER 0x00000004 True (i.e. set) if the OTP computation must not include a counter value. Will have an effect only on mechanisms that do include a counter value in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed.

CKF_EXCLUDE_CHALLENGE 0x00000008 True (i.e. set) if the OTP computation must not include a challenge. Will have an effect only on mechanisms that do include a challenge in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed.

CKF_EXCLUDE_PIN 0x00000010 True (i.e. set) if the OTP computation must not include a PIN value. Will have an effect only on mechanisms that do include a PIN in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed.

CKF_USER_FRIENDLY_OTP 0x00000020 True (i.e. set) if the OTP returned shall be in a form suitable for human consumption. If this flag is set, and the call is successful, then the returned CK_OTP_VALUE shall be a UTF8-encoded printable string. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if this flag is set when CKA_OTP_USER_FRIENDLY_MODE for the key in question is CK_FALSE.

Note: Even if CKA_OTP_FORMAT is not set to CK_OTP_FORMAT_BINARY, then there may still be 13098 value in setting the CKF_USER_FRIENDLY_OTP flag (assuming CKA_OTP_USER_FRIENDLY_MODE 13099 is CK_TRUE, of course) if the intent is for a human to read the generated OTP value, since it may 13100 become shorter or otherwise better suited for a user. Applications that do not intend to provide a returned 13101 OTP value to a user should not set the CKF_USER_FRIENDLY_OTP flag. 13102

CK_OTP_PARAM; CK_OTP_PARAM_PTR 13103

CK_OTP_PARAM is a structure that includes the type, value, and length of an OTP parameter. It is 13104



typedef struct CK_OTP_PARAM { 13106

CK_OTP_PARAM_TYPE type; 13107

CK_VOID_PTR pValue; 13108

CK_ULONG ulValueLen; 13109

} CK_OTP_PARAM; 13110


type the parameter type 13112

pValue pointer to the value of the parameter 13113

ulValueLen length in bytes of the value 13114

If a parameter has no value, then ulValueLen = 0, and the value of pValue is irrelevant. Note that pValue 13115 is a “void” pointer, facilitating the passing of arbitrary values. Both the application and the Cryptoki library 13116 must ensure that the pointer can be safely cast to the expected type (i.e., without word-alignment errors). 13117

CK_OTP_PARAM_PTR is a pointer to a CK_OTP_PARAM. 13118

13119

CK_OTP_PARAMS; CK_OTP_PARAMS_PTR 13120

CK_OTP_PARAMS is a structure that is used to provide parameters for OTP mechanisms in a generic 13121 fashion. It is defined as follows: 13122

typedef struct CK_OTP_PARAMS { 13123

CK_OTP_PARAM_PTR pParams; 13124


} CK_OTP_PARAMS; 13126


pParams pointer to an array of OTP parameters 13128

ulCount the number of parameters in the array 13129

CK_OTP_PARAMS_PTR is a pointer to a CK_OTP_PARAMS. 13130

13131

When calling C_SignInit or C_VerifyInit with a mechanism that takes a CK_OTP_PARAMS structure as a 13132 parameter, the CK_OTP_PARAMS structure shall be populated in accordance with the 13133 CKA_OTP_X_REQUIREMENT key attributes for the identified key, where X is PIN, CHALLENGE, TIME, 13134

or COUNTER. 13135

For example, if CKA_OTP_TIME_REQUIREMENT = CK_OTP_PARAM_MANDATORY, then the 13136 CK_OTP_TIME parameter shall be present. If CKA_OTP_TIME_REQUIREMENT = 13137 CK_OTP_PARAM_OPTIONAL, then a CK_OTP_TIME parameter may be present. If it is not present, 13138 then the library may collect it (during the C_Sign call). If CKA_OTP_TIME_REQUIREMENT = 13139 CK_OTP_PARAM_IGNORED, then a provided CK_OTP_TIME parameter will always be ignored. 13140 Additionally, a provided CK_OTP_TIME parameter will always be ignored if CKF_EXCLUDE_TIME is set 13141 in a CK_OTP_FLAGS parameter. Similarly, if this flag is set, a library will not attempt to collect the value 13142 itself, and it will also instruct the token not to make use of any internal value, subject to token policies. It is 13143 an error (CKR_MECHANISM_PARAM_INVALID) to set the CKF_EXCLUDE_TIME flag when the 13144 CKA_OTP_TIME_REQUIREMENT attribute is CK_OTP_PARAM_MANDATORY. 13145

The above discussion holds for all CKA_OTP_X_REQUIREMENT attributes (i.e., 13146 CKA_OTP_PIN_REQUIREMENT, CKA_OTP_CHALLENGE_REQUIREMENT, 13147 CKA_OTP_COUNTER_REQUIREMENT, CKA_OTP_TIME_REQUIREMENT). A library may set a 13148 particular CKA_OTP_X_REQUIREMENT attribute to CK_OTP_PARAM_OPTIONAL even if it is required 13149 by the mechanism as long as the token (or the library itself) has the capability of providing the value to the 13150 computation. One example of this is a token with an on-board clock. 13151


In addition, applications may use the CK_OTP_FLAGS, the CK_OTP_OUTPUT_FORMAT and the 13152 CKA_OTP_LENGTH parameters to set additional parameters. 13153

13154

CK_OTP_SIGNATURE_INFO, CK_OTP_SIGNATURE_INFO_PTR 13155

CK_OTP_SIGNATURE_INFO is a structure that is returned by all OTP mechanisms in successful calls to 13156 C_Sign (C_SignFinal). The structure informs applications of actual parameter values used in particular 13157 OTP computations in addition to the OTP value itself. It is used by all mechanisms for which the key 13158 belongs to the class CKO_OTP_KEY and is defined as follows: 13159

typedef struct CK_OTP_SIGNATURE_INFO { 13160

CK_OTP_PARAM_PTR pParams; 13161


} CK_OTP_SIGNATURE_INFO; 13163


pParams pointer to an array of OTP parameter values 13165

ulCount the number of parameters in the array 13166

After successful calls to C_Sign or C_SignFinal with an OTP mechanism, the pSignature parameter will 13167 be set to point to a CK_OTP_SIGNATURE_INFO structure. One of the parameters in this structure will be 13168 the OTP value itself, identified with the CK_OTP_VALUE tag. Other parameters may be present for 13169 informational purposes, e.g. the actual time used in the OTP calculation. In order to simplify OTP 13170 validations, authentication protocols may permit authenticating parties to send some or all of these 13171 parameters in addition to OTP values themselves. Applications should therefore check for their presence 13172 in returned CK_OTP_SIGNATURE_INFO values whenever such circumstances apply. 13173

Since C_Sign and C_SignFinal follows the convention described in [PKCS11-Base] Section 5.2 on 13174 producing output, a call to C_Sign (or C_SignFinal) with pSignature set to NULL_PTR will return (in the 13175 pulSignatureLen parameter) the required number of bytes to hold the CK_OTP_SIGNATURE_INFO 13176 structure as well as all the data in all its CK_OTP_PARAM components. If an application allocates a 13177 memory block based on this information, it shall therefore not subsequently de-allocate components of 13178 such a received value but rather de-allocate the complete CK_OTP_PARAMS structure itself. A Cryptoki 13179 library that is called with a non-NULL pSignature pointer will assume that it points to a contiguous 13180 memory block of the size indicated by the pulSignatureLen parameter. 13181

When verifying an OTP value using an OTP mechanism, pSignature shall be set to the OTP value itself, 13182 e.g. the value of the CK_OTP_VALUE component of a CK_OTP_PARAM structure returned by a call to 13183 C_Sign. The CK_OTP_PARAM value supplied in the C_VerifyInit call sets the values to use in the 13184

verification operation. 13185

CK_OTP_SIGNATURE_INFO_PTR points to a CK_OTP_SIGNATURE_INFO. 13186

6.53.8 RSA SecurID 13187

6.53.8.1 RSA SecurID secret key objects 13188

RSA SecurID secret key objects (object class CKO_OTP_KEY, key type CKK_SECURID) hold RSA 13189 SecurID secret keys. The following table defines the RSA SecurID secret key object attributes, in 13190 addition to the common attributes defined for this object class: 13191

Table 229, RSA SecurID secret key object attributes 13192


CKA_OTP_TIME_INTERVAL1 CK_ULONG Interval between OTP values produced

with this key, in seconds. Default is 60.


The following is a sample template for creating an RSA SecurID secret key object: 13194


CK_OBJECT_CLASS class = CKO_OTP_KEY; 13195

CK_KEY_TYPE keyType = CKK_SECURID; 13196

CK_DATE endDate = {...}; 13197

CK_UTF8CHAR label[] = “RSA SecurID secret key object”; 13198

CK_BYTE keyId[]= {...}; 13199

CK_ULONG outputFormat = CK_OTP_FORMAT_DECIMAL; 13200

CK_ULONG outputLength = 6; 13201

CK_ULONG needPIN = CK_OTP_PARAM_MANDATORY; 13202

CK_ULONG timeInterval = 60; 13203

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





{CKA_END_DATE, &endDate, sizeof(endDate)}, 13209






{CKA_ID, keyId, sizeof(keyId)}, 13215

{CKA_OTP_FORMAT, &outputFormat, sizeof(outputFormat)}, 13216

{CKA_OTP_LENGTH, &outputLength, sizeof(outputLength)}, 13217

{CKA_OTP_PIN_REQUIREMENT, &needPIN, sizeof(needPIN)}, 13218

{CKA_OTP_TIME_INTERVAL, &timeInterval, 13219

sizeof(timeInterval)}, 13220


}; 13222

6.53.8.2 RSA SecurID key generation 13223

The RSA SecurID key generation mechanism, denoted CKM_SECURID_KEY_GEN, is a key generation 13224

mechanism for the RSA SecurID algorithm. 13225


The mechanism generates RSA SecurID keys with a particular set of attributes as specified in the 13227 template for the key. 13228

The mechanism contributes at least the CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE_LEN, and 13229 CKA_VALUE attributes to the new key. Other attributes supported by the RSA SecurID key type may be 13230

specified in the template for the key, or else are assigned default initial values 13231


specify the supported range of SecurID key sizes, in bytes. 13233

6.53.8.3 SecurID OTP generation and validation 13234

CKM_SECURID is the mechanism for the retrieval and verification of RSA SecurID OTP values. 13235

The mechanism takes a pointer to a CK_OTP_PARAMS structure as a parameter. 13236

When signing or verifying using the CKM_SECURID mechanism, pData shall be set to NULL_PTR and 13237 ulDataLen shall be set to 0. 13238


6.53.8.4 Return values 13239

Support for the CKM_SECURID mechanism extends the set of return values for C_Verify with the 13240 following values: 13241

CKR_NEW_PIN_MODE: The supplied OTP was not accepted and the library requests a new OTP 13242 computed using a new PIN. The new PIN is set through means out of scope for this document. 13243

CKR_NEXT_OTP: The supplied OTP was correct but indicated a larger than normal drift in the 13244 token's internal state (e.g. clock, counter). To ensure this was not due to a temporary problem, the 13245 application should provide the next one-time password to the library for verification. 13246

6.53.9 OATH HOTP 13247

6.53.9.1 OATH HOTP secret key objects 13248

HOTP secret key objects (object class CKO_OTP_KEY, key type CKK_HOTP) hold generic secret keys 13249

and associated counter values. 13250

The CKA_OTP_COUNTER value may be set at key generation; however, some tokens may set it to a 13251 fixed initial value. Depending on the token’s security policy, this value may not be modified and/or may 13252 not be revealed if the object has its CKA_SENSITIVE attribute set to CK_TRUE or its 13253 CKA_EXTRACTABLE attribute set to CK_FALSE. 13254

For HOTP keys, the CKA_OTP_COUNTER value shall be an 8 bytes unsigned integer in big endian (i.e. 13255 network byte order) form. The same holds true for a CK_OTP_COUNTER value in a CK_OTP_PARAM 13256 structure. 13257

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


CK_KEY_TYPE keyType = CKK_HOTP; 13260

CK_UTF8CHAR label[] = “HOTP secret key object”; 13261

CK_BYTE keyId[]= {...}; 13262




CK_BYTE counterValue[8] = {0}; 13266

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












{CKA_OTP_FORMAT, &outputFormat, sizeof(outputFormat)}, 13279

{CKA_OTP_LENGTH, &outputLength, sizeof(outputLength)}, 13280

{CKA_OTP_COUNTER, counterValue, sizeof(counterValue)}, 13281


}; 13283


6.53.9.2 HOTP key generation 13284

The HOTP key generation mechanism, denoted CKM_HOTP_KEY_GEN, is a key generation mechanism 13285

for the HOTP algorithm. 13286


The mechanism generates HOTP keys with a particular set of attributes as specified in the template for 13288 the key. 13289

The mechanism contributes at least the CKA_CLASS, CKA_KEY_TYPE, CKA_OTP_COUNTER, 13290 CKA_VALUE and CKA_VALUE_LEN attributes to the new key. Other attributes supported by the HOTP 13291

key type may be specified in the template for the key, or else are assigned default initial values. 13292


specify the supported range of HOTP key sizes, in bytes. 13294

6.53.9.3 HOTP OTP generation and validation 13295

CKM_HOTP is the mechanism for the retrieval and verification of HOTP OTP values based on the current 13296 internal counter, or a provided counter. 13297


As for the CKM_SECURID mechanism, when signing or verifying using the CKM_HOTP mechanism, 13299 pData shall be set to NULL_PTR and ulDataLen shall be set to 0. 13300

For verify operations, the counter value CK_OTP_COUNTER must be provided as a CK_OTP_PARAM 13301 parameter to C_VerifyInit. When verifying an OTP value using the CKM_HOTP mechanism, pSignature 13302 shall be set to the OTP value itself, e.g. the value of the CK_OTP_VALUE component of a 13303 CK_OTP_PARAM structure in the case of an earlier call to C_Sign. 13304

6.53.10 ActivIdentity ACTI 13305

6.53.10.1 ACTI secret key objects 13306

ACTI secret key objects (object class CKO_OTP_KEY, key type CKK_ACTI) hold ActivIdentity ACTI 13307 secret keys. 13308

For ACTI keys, the CKA_OTP_COUNTER value shall be an 8 bytes unsigned integer in big endian (i.e. 13309 network byte order) form. The same holds true for the CK_OTP_COUNTER value in the 13310 CK_OTP_PARAM structure. 13311

The CKA_OTP_COUNTER value may be set at key generation; however, some tokens may set it to a 13312 fixed initial value. Depending on the token’s security policy, this value may not be modified and/or may 13313 not be revealed if the object has its CKA_SENSITIVE attribute set to CK_TRUE or its 13314 CKA_EXTRACTABLE attribute set to CK_FALSE. 13315

The CKA_OTP_TIME value may be set at key generation; however, some tokens may set it to a fixed 13316 initial value. Depending on the token’s security policy, this value may not be modified and/or may not be 13317 revealed if the object has its CKA_SENSITIVE attribute set to CK_TRUE or its CKA_EXTRACTABLE 13318 attribute set to CK_FALSE. 13319

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


CK_KEY_TYPE keyType = CKK_ACTI; 13322

CK_UTF8CHAR label[] = “ACTI secret key object”; 13323

CK_BYTE keyId[]= {...}; 13324




CK_BYTE counterValue[8] = {0}; 13328


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












{CKA_OTP_FORMAT, &outputFormat, 13341

sizeof(outputFormat)}, 13342

{CKA_OTP_LENGTH, &outputLength, 13343

sizeof(outputLength)}, 13344

{CKA_OTP_COUNTER, counterValue, 13345

sizeof(counterValue)}, 13346


}; 13348

6.53.10.2 ACTI key generation 13349

The ACTI key generation mechanism, denoted CKM_ACTI_KEY_GEN, is a key generation mechanism 13350 for the ACTI algorithm. 13351


The mechanism generates ACTI keys with a particular set of attributes as specified in the template for the 13353 key. 13354

The mechanism contributes at least the CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE and 13355 CKA_VALUE_LEN attributes to the new key. Other attributes supported by the ACTI key type may be 13356 specified in the template for the key, or else are assigned default initial values. 13357

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

6.53.10.3 ACTI OTP generation and validation 13360

CKM_ACTI is the mechanism for the retrieval and verification of ACTI OTP values. 13361


When signing or verifying using the CKM_ACTI mechanism, pData shall be set to NULL_PTR and 13363 ulDataLen shall be set to 0. 13364

When verifying an OTP value using the CKM_ACTI mechanism, pSignature shall be set to the OTP value 13365 itself, e.g. the value of the CK_OTP_VALUE component of a CK_OTP_PARAM structure in the case of 13366 an earlier call to C_Sign. 13367


6.54 CT-KIP 13368

6.54.1 Principles of Operation 13369

13370

Figure 5: PKCS #11 and CT-KIP integration 13371

Figure 5Figure 5 shows an integration of PKCS #11 into an application that generates cryptographic keys 13372 through the use of CT-KIP. The application invokes C_DeriveKey to derive a key of a particular type on 13373 the token. The key may subsequently be used as a basis to e.g., generate one-time password values. 13374 The application communicates with a CT-KIP server that participates in the key derivation and stores a 13375 copy of the key in its database. The key is transferred to the server in wrapped form, after a call to 13376 C_WrapKey. The server authenticates itself to the client and the client verifies the authentication by calls 13377 to C_Verify. 13378

6.54.2 Mechanisms 13379

The following table shows, for the mechanisms defined in this document, their support by different 13380 cryptographic operations. For any particular token, of course, a particular operation may well support 13381 only a subset of the mechanisms listed. There is also no guarantee that a token that supports one 13382 mechanism for some operation supports any other mechanism for any other operation (or even supports 13383 that same mechanism for any other operation). 13384

Table 230: CT-KIP Mechanisms vs. applicable functions 13385

C_DeriveKey, C_WrapKey,

C_Verify

Client Application

PKCS #11 Library

Internal Token API

Token (or software version thereof)

Server Application


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_KIP_DERIVE

CKM_KIP_WRAP

CKM_KIP_MAC

The remainder of this section will present in detail the mechanisms and the parameters that are supplied 13386 to them. 13387


Mechanisms: 13389

CKM_KIP_DERIVE 13390

CKM_KIP_WRAP 13391

CKM_KIP_MAC 13392

6.54.4 CT-KIP Mechanism parameters 13393

CK_KIP_PARAMS; CK_KIP_PARAMS_PTR 13394

CK_KIP_PARAMS is a structure that provides the parameters to all the CT-KIP related mechanisms: The 13395 CKM_KIP_DERIVE key derivation mechanism, the CKM_KIP_WRAP key wrap and key unwrap 13396 mechanism, and the CKM_KIP_MAC signature mechanism. The structure is defined as follows: 13397

typedef struct CK_KIP_PARAMS { 13398

CK_MECHANISM_PTR pMechanism; 13399




} CK_KIP_PARAMS; 13403


pMechanism pointer to the underlying cryptographic mechanism (e.g. AES, SHA-13405 256), see further Error! Reference source not found., Appendix 13406 DAES, SHA-256) 13407

hKey handle to a key that will contribute to the entropy of the derived key 13408 (CKM_KIP_DERIVE) or will be used in the MAC operation 13409 (CKM_KIP_MAC) 13410

pSeed pointer to an input seed 13411


CK_KIP_PARAMS_PTR is a pointer to a CK_KIP_PARAMS structure. 13413

6.54.5 CT-KIP key derivation 13414

The CT-KIP key derivation mechanism, denoted CKM_KIP_DERIVE, is a key derivation mechanism that 13415

is capable of generating secret keys of potentially any type, subject to token limitations. 13416

It takes a parameter of type CK_KIP_PARAMS which allows for the passing of the desired underlying 13417 cryptographic mechanism as well as some other data. In particular, when the hKey parameter is a handle 13418

Comment [DM2]: Again, original

refernce unknown.


to an existing key, that key will be used in the key derivation in addition to the hBaseKey of C_DeriveKey. 13419 The pSeed parameter may be used to seed the key derivation operation. 13420

The mechanism derives a secret key with a particular set of attributes as specified in the attributes of the 13421 template for the key. 13422

The mechanism contributes the CKA_CLASS and CKA_VALUE attributes to the new key. Other 13423 attributes supported by the key type may be specified in the template for the key, or else will be assigned 13424 default initial values. Since the mechanism is generic, the CKA_KEY_TYPE attribute should be set in the 13425 template, if the key is to be used with a particular mechanism. 13426

6.54.6 CT-KIP key wrap and key unwrap 13427

The CT-KIP key wrap and unwrap mechanism, denoted CKM_KIP_WRAP, is a key wrap mechanism that 13428

is capable of wrapping and unwrapping generic secret keys. 13429

It takes a parameter of type CK_KIP_PARAMS, which allows for the passing of the desired underlying 13430 cryptographic mechanism as well as some other data. It does not make use of the hKey parameter of 13431 CK_KIP_PARAMS. 13432

6.54.7 CT-KIP signature generation 13433

The CT-KIP signature (MAC) mechanism, denoted CKM_KIP_MAC, is a mechanism used to produce a 13434

message authentication code of arbitrary length. The keys it uses are secret keys. 13435

It takes a parameter of type CK_KIP_PARAMS, which allows for the passing of the desired underlying 13436 cryptographic mechanism as well as some other data. The mechanism does not make use of the pSeed 13437 and the ulSeedLen parameters of CT_KIP_PARAMS. 13438

This mechanism produces a MAC of the length specified by pulSignatureLen parameter in calls to 13439 C_Sign. 13440

If a call to C_Sign with this mechanism fails, then no output will be generated. 13441

6.55 GOST 28147-89 13442

GOST 28147-89 is a block cipher with 64-bit block size and 256-bit keys. 13443

13444

Table 231, GOST 28147-89 Mechanisms vs. Functions 13445

Mechanism Functions

Encrypt &

Decrypt

Sign &

Verify

SR &

VR

Digest

Gen. Key/ Key Pair

Wrap &

Unwrap

Derive

CKM_GOST28147_KEY_GEN

CKM_GOST28147_ECB

CKM_GOST28147

CKM_GOST28147_MAC

CKM_GOST28147_KEY_WRAP

13446


This section defines the key type “CKK_GOST28147” for type CK_KEY_TYPE as used in the 13448 CKA_KEY_TYPE attribute of key objects and domain parameter objects. 13449


Mechanisms: 13450

CKM_GOST28147_KEY_GEN 13451

CKM_GOST28147_ECB 13452

CKM_GOST28147 13453

CKM_GOST28147_MAC 13454

CKM_GOST28147_KEY_WRAP 13455

6.55.2 GOST 28147-89 secret key objects 13456

GOST 28147-89 secret key objects (object class CKO_SECRET_KEY, key type CKK_GOST28147) hold 13457 GOST 28147-89 keys. The following table defines the GOST 28147-89 secret key object attributes, in 13458 addition to the common attributes defined for this object class: 13459

Table 232, GOST 28147-89 Secret Key Object Attributes 13460


CKA_VALUE1,4,6,7

Byte array 32 bytes in little endian order

CKA_GOST28147_PARAMS1,3,5

Byte array DER-encoding of the object identifier indicating the data object type of GOST 28147-89.

When key is used the domain parameter object of key type CKK_GOST28147 must be specified with the same attribute CKA_OBJECT_ID


The following is a sample template for creating a GOST 28147-89 secret key object: 13462


CK_KEY_TYPE keyType = CKK_GOST28147; 13464

CK_UTF8CHAR label[] = “A GOST 28147-89 secret key object”; 13465

CK_BYTE value[32] = {...}; 13466

CK_BYTE params_oid[] = {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 13467

0x02, 0x1f, 0x00}; 13468








{CKA_GOST28147_PARAMS, params_oid, sizeof(params_oid)}, 13476


}; 13478

6.55.3 GOST 28147-89 domain parameter objects 13479

GOST 28147-89 domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type 13480 CKK_GOST28147) hold GOST 28147-89 domain parameters. 13481

The following table defines the GOST 28147-89 domain parameter object attributes, in addition to the 13482 common attributes defined for this object class: 13483


Table 233, GOST 28147-89 Domain Parameter Object Attributes 13484


CKA_VALUE1 Byte array DER-encoding of the domain parameters as it

was introduced in [4] section 8.1 (type Gost28147-89-ParamSetParameters)

CKA_OBJECT_ID1 Byte array DER-encoding of the object identifier indicating

the domain parameters


For any particular token, there is no guarantee that a token supports domain parameters loading up 13486 and/or fetching out. Furthermore, applications, that make direct use of domain parameters objects, should 13487 take in account that CKA_VALUE attribute may be inaccessible. 13488

The following is a sample template for creating a GOST 28147-89 domain parameter object: 13489


CK_KEY_TYPE keyType = CKK_GOST28147; 13491

CK_UTF8CHAR label[] = “A GOST 28147-89 cryptographic 13492


CK_BYTE oid[] = {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 13494

0x1f, 0x00}; 13495

CK_BYTE value[] = { 13496

0x30,0x62,0x04,0x40,0x4c,0xde,0x38,0x9c,0x29,0x89,0xef,0xb6, 13497

0xff,0xeb,0x56,0xc5,0x5e,0xc2,0x9b,0x02,0x98,0x75,0x61,0x3b, 13498

0x11,0x3f,0x89,0x60,0x03,0x97,0x0c,0x79,0x8a,0xa1,0xd5,0x5d, 13499

0xe2,0x10,0xad,0x43,0x37,0x5d,0xb3,0x8e,0xb4,0x2c,0x77,0xe7, 13500

0xcd,0x46,0xca,0xfa,0xd6,0x6a,0x20,0x1f,0x70,0xf4,0x1e,0xa4, 13501

0xab,0x03,0xf2,0x21,0x65,0xb8,0x44,0xd8,0x02,0x01,0x00,0x02, 13502

0x01,0x40,0x30,0x0b,0x06,0x07,0x2a,0x85,0x03,0x02,0x02,0x0e, 13503

0x00,0x05,0x00 13504

}; 13505







{CKA_OBJECT_ID, oid, sizeof(oid)}, 13512


}; 13514

6.55.4 GOST 28147-89 key generation 13515

The GOST 28147-89 key generation mechanism, denoted CKM_GOST28147_KEY_GEN, is a key 13516

generation mechanism for GOST 28147-89. 13517


The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 13519 key. Other attributes supported by the GOST 28147-89 key type may be specified for objects of object 13520 class CKO_SECRET_KEY. 13521

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO are not 13522

used. 13523




6.55.5 GOST 28147-89-ECB 13524

GOST 28147-89-ECB, denoted CKM_GOST28147_ECB, is a mechanism for single and multiple-part 13525 encryption and decryption; key wrapping; and key unwrapping, based on GOST 28147-89 and electronic 13526 codebook mode. 13527


This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 13529 wrap/unwrap every secret key that it supports. 13530

For wrapping (C_WrapKey), the mechanism encrypts the value of the CKA_VALUE attribute of the key 13531 that is wrapped, padded on the trailing end with up to block size so that the resulting length is a multiple 13532 of the block size. 13533

For unwrapping (C_UnwrapKey), the mechanism decrypts the wrapped key, and truncates the result 13534 according to the CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports 13535 it, the CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the 13536 CKA_VALUE attribute of the new key. 13537


Table 234, GOST 28147-89-ECB: Key and Data Length 13539


C_Encrypt CKK_GOST28147 Multiple of block size

Same as input length

C_Decrypt CKK_GOST28147 Multiple of block size

Same as input length

C_WrapKey CKK_GOST28147 Any

Input length rounded up to multiple of block size

C_UnwrapKey CKK_GOST28147 Multiple of block size

Determined by type of key being unwrapped

13540


are not used. 13542

6.55.6 GOST 28147-89 encryption mode except ECB 13543

GOST 28147-89 encryption mode except ECB, denoted CKM_GOST28147, is a mechanism for single 13544 and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on 13545 [GOST 28147-89] and CFB, counter mode, and additional CBC mode defined in [RFC 4357] section 2. 13546 Encryption’s parameters are specified in object identifier of attribute CKA_GOST28147_PARAMS. 13547

It has a parameter, which is an 8-byte initialization vector. This parameter may be omitted then a zero 13548 initialization vector is used. 13549

This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to 13550 wrap/unwrap every secret key that it supports. 13551

For wrapping (C_WrapKey), the mechanism encrypts the value of the CKA_VALUE attribute of the key 13552

that is wrapped. 13553

For unwrapping (C_UnwrapKey), the mechanism decrypts the wrapped key, and contributes the result as 13554 the CKA_VALUE attribute of the new key. 13555


Table 235, GOST 28147-89 encryption modes except ECB: Key and Data Length 13557

Function Key type Input Output length


length

C_Encrypt CKK_GOST28147 Any For counter mode and CFB is the same as input length. For CBC is the same as input length padded on the trailing end with up to block size so that the resulting length is a multiple of the block size

C_Decrypt CKK_GOST28147 Any

C_WrapKey CKK_GOST28147 Any

C_UnwrapKey CKK_GOST28147 Any

13558


are not used. 13560

6.55.7 GOST 28147-89-MAC 13561

GOST 28147-89-MAC, denoted CKM_GOST28147_MAC, is a mechanism for data integrity and 13562

authentication based on GOST 28147-89 and key meshing algorithms [RFC 4357] section 2.3. 13563

MACing parameters are specified in object identifier of attribute CKA_GOST28147_PARAMS. 13564

The output bytes from this mechanism are taken from the start of the final GOST 28147-89 cipher block 13565 produced in the MACing process. 13566

It has a parameter, which is an 8-byte MAC initialization vector. This parameter may be omitted then a 13567 zero initialization vector is used. 13568


Table 236, GOST28147-89-MAC: Key and Data Length 13570


C_Sign CKK_GOST28147 Any 4 bytes

C_Verify CKK_GOST28147 Any 4 bytes

13571

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 13572 are not used. 13573 13574

6.55.8 GOST 28147-89 keys wrapping/unwrapping with GOST 28147-89 13575

GOST 28147-89 keys as a KEK (key encryption keys) for encryption GOST 28147-89 keys, denoted by 13576 CKM_GOST28147_KEY_WRAP, is a mechanism for key wrapping; and key unwrapping, based on 13577 GOST 28147-89. Its purpose is to encrypt and decrypt keys have been generated by key generation 13578 mechanism for GOST 28147-89. 13579

For wrapping (C_WrapKey), the mechanism first computes MAC from the value of the CKA_VALUE 13580 attribute of the key that is wrapped and then encrypts in ECB mode the value of the CKA_VALUE 13581

attribute of the key that is wrapped. The result is 32 bytes of the key that is wrapped and 4 bytes of MAC. 13582

For unwrapping (C_UnwrapKey), the mechanism first decrypts in ECB mode the 32 bytes of the key that 13583 was wrapped and then computes MAC from the unwrapped key. Then compared together 4 bytes MAC 13584 has computed and 4 bytes MAC of the input. If these two MACs do not match the wrapped key is 13585 disallowed. The mechanism contributes the result as the CKA_VALUE attribute of the unwrapped key. 13586

It has a parameter, which is an 8-byte MAC initialization vector. This parameter may be omitted then a 13587 zero initialization vector is used. 13588


Table 237, GOST 28147-89 keys as KEK: Key and Data Length 13590



C_WrapKey CKK_GOST28147 32 bytes 36 bytes

C_UnwrapKey CKK_GOST28147 32 bytes 36 bytes

13591

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 13592 are not used. 13593 13594

6.56 GOST R 34.11-94 13595

GOST R 34.11-94 is a mechanism for message digesting, following the hash algorithm with 256-bit 13596 message digest defined in [GOST R 34.11-94]. 13597

13598

Table 238, GOST R 34.11-94 Mechanisms vs. Functions 13599

Mechanism Functions

Encrypt &

Decrypt

Sign &

Verify

SR &

VR

Digest

Gen. Key/ Key Pair

Wrap &

Unwrap

Derive

CKM_GOSTR3411

CKM_GOSTR3411_HMAC

13600


This section defines the key type “CKK_GOSTR3411” for type CK_KEY_TYPE as used in the 13602 CKA_KEY_TYPE attribute of domain parameter objects. 13603

Mechanisms: 13604

CKM_GOSTR3411 13605

CKM_GOSTR3411_HMAC 13606

6.56.2 GOST R 34.11-94 domain parameter objects 13607

GOST R 34.11-94 domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type 13608 CKK_GOSTR3411) hold GOST R 34.11-94 domain parameters. 13609

The following table defines the GOST R 34.11-94 domain parameter object attributes, in addition to the 13610 common attributes defined for this object class: 13611

Table 239, GOST R 34.11-94 Domain Parameter Object Attributes 13612



was introduced in [4] section 8.2 (type GostR3411-94-ParamSetParameters)






The following is a sample template for creating a GOST R 34.11-94 domain parameter object: 13617


CK_KEY_TYPE keyType = CKK_GOSTR3411; 13619

CK_UTF8CHAR label[] = “A GOST R34.11-94 cryptographic 13620


CK_BYTE oid[] = {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 13622

0x1e, 0x00}; 13623


0x30,0x64,0x04,0x40,0x4e,0x57,0x64,0xd1,0xab,0x8d,0xcb,0xbf, 13625

0x94,0x1a,0x7a,0x4d,0x2c,0xd1,0x10,0x10,0xd6,0xa0,0x57,0x35, 13626

0x8d,0x38,0xf2,0xf7,0x0f,0x49,0xd1,0x5a,0xea,0x2f,0x8d,0x94, 13627

0x62,0xee,0x43,0x09,0xb3,0xf4,0xa6,0xa2,0x18,0xc6,0x98,0xe3, 13628

0xc1,0x7c,0xe5,0x7e,0x70,0x6b,0x09,0x66,0xf7,0x02,0x3c,0x8b, 13629

0x55,0x95,0xbf,0x28,0x39,0xb3,0x2e,0xcc,0x04,0x20,0x00,0x00, 13630

0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, 13631

0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, 13632

0x00,0x00,0x00,0x00,0x00,0x00 13633

}; 13634









}; 13643

6.56.3 GOST R 34.11-94 digest 13644

GOST R 34.11-94 digest, denoted CKM_GOSTR3411, is a mechanism for message digesting based on 13645

GOST R 34.11-94 hash algorithm [GOST R 34.11-94]. 13646

As a parameter this mechanism utilizes a DER-encoding of the object identifier. A mechanism parameter 13647 may be missed then parameters of the object identifier id-GostR3411-94-CryptoProParamSet [RFC 4357] 13648 (section 11.2) must be used. 13649


Table 240, GOST R 34.11-94: Data Length 13652


C_Digest Any 32 bytes

13653


are not used. 13655



6.56.4 GOST R 34.11-94 HMAC 13656

GOST R 34.11-94 HMAC mechanism, denoted CKM_GOSTR3411_HMAC, is a mechanism for 13657 signatures and verification. It uses the HMAC construction, based on the GOST R 34.11-94 hash 13658 function [GOST R 34.11-94] and core HMAC algorithm [RFC 2104]. The keys it uses are of generic key 13659 type CKK_GENERIC_SECRET or CKK_GOST28147. 13660

To be conformed to GOST R 34.11-94 hash algorithm [GOST R 34.11-94] the block length of core HMAC 13661 algorithm is 32 bytes long (see [RFC 2104] section 2, and [RFC 4357] section 3). 13662

As a parameter this mechanism utilizes a DER-encoding of the object identifier. A mechanism parameter 13663 may be missed then parameters of the object identifier id-GostR3411-94-CryptoProParamSet [RFC 4357] 13664

(section 11.2) must be used. 13665

Signatures (MACs) produced by this mechanism are of 32 bytes long. 13666

Constraints on the length of input and output data are summarized in the following table: 13667

Table 241, GOST R 34.11-94 HMAC: Key And Data Length 13668


C_Sign CKK_GENERIC_SECRET or CKK_GOST28147

Any 32 byte

C_Verify CKK_GENERIC_SECRET or CKK_GOST28147

Any 32 bytes


6.57 GOST R 34.10-2001 13671

GOST R 34.10-2001 is a mechanism for single- and multiple-part signatures and verification, following 13672 the digital signature algorithm defined in [GOST R 34.10-2001]. 13673

13674

Table 242, GOST R34.10-2001 Mechanisms vs. Functions 13675

Mechanism Functions

Encrypt &

Decrypt

Sign &

Verify

SR &

VR

Digest

Gen. Key/ Key Pair

Wrap &

Unwrap

Derive

CKM_GOSTR3410_KEY_PAIR_GEN

CKM_GOSTR3410 1

CKM_GOSTR3410_WITH_GOSTR3411

CKM_GOSTR3410_KEY_WRAP

CKM_GOSTR3410_DERIVE

1 Single-part operations only

13676

13677


This section defines the key type “CKK_GOSTR3410” for type CK_KEY_TYPE as used in the 13679 CKA_KEY_TYPE attribute of key objects and domain parameter objects. 13680

Mechanisms: 13681

CKM_GOSTR3410_KEY_PAIR_GEN 13682


CKM_GOSTR3410 13683

CKM_GOSTR3410_WITH_GOSTR3411 13684

CKM_GOSTR3410 13685

CKM_GOSTR3410_KEY_WRAP 13686

CKM_GOSTR3410_DERIVE 13687

6.57.2 GOST R 34.10-2001 public key objects 13688

GOST R 34.10-2001 public key objects (object class CKO_PUBLIC_KEY, key type CKK_GOSTR3410) 13689

hold GOST R 34.10-2001 public keys. 13690

The following table defines the GOST R 34.10-2001 public key object attributes, in addition to the 13691 common attributes defined for this object class: 13692

Table 243, GOST R 34.10-2001 Public Key Object Attributes 13693


CKA_VALUE1,4

Byte array 64 bytes for public key; 32 bytes for each coordinates X and Y of elliptic curve point P(X, Y) in little endian order

CKA_GOSTR3410_PARAMS1,3

Byte array DER-encoding of the object identifier indicating the data object type of GOST R 34.10-2001.

When key is used the domain parameter object of key type CKK_GOSTR3410 must be specified with the same attribute CKA_OBJECT_ID

CKA_GOSTR3411_PARAMS1,3,8



CKA_GOST28147_PARAMS8 Byte array DER-encoding of the object identifier

indicating the data object type of GOST 28147-89.

When key is used the domain parameter object of key type CKK_GOST28147 must be specified with the same attribute CKA_OBJECT_ID. The attribute value may be omitted


The following is a sample template for creating an GOST R 34.10-2001 public key object: 13695



CK_UTF8CHAR label[] = “A GOST R34.10-2001 public key object”; 13698

CK_BYTE gostR3410params_oid[] = 13699

{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x00}; 13700


{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1e, 0x00}; 13702


CK_BYTE gost28147params_oid[] = 13703

{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x00}; 13704

CK_BYTE value[64] = {...}; 13705







{CKA_GOSTR3410_PARAMS, gostR3410params_oid, 13712

sizeof(gostR3410params_oid)}, 13713



{CKA_GOST28147_PARAMS, gost28147params_oid, 13716

sizeof(gost28147params_oid)}, 13717


}; 13719

6.57.3 GOST R 34.10-2001 private key objects 13720

GOST R 34.10-2001 private key objects (object class CKO_PRIVATE_KEY, key type 13721 CKK_GOSTR3410) hold GOST R 34.10-2001 private keys. 13722

The following table defines the GOST R 34.10-2001 private key object attributes, in addition to the 13723 common attributes defined for this object class: 13724

Table 244, GOST R 34.10-2001 Private Key Object Attributes 13725


CKA_VALUE1,4,6,7

Byte array 32 bytes for private key in little endian order

CKA_GOSTR3410_PARAMS1,4,6



CKA_GOSTR3411_PARAMS1,4,6,8



CKA_GOST28147_PARAMS4,6,8

Byte array DER-encoding of the object identifier indicating the data object type of GOST 28147-89.

When key is used the domain parameter object of key type CKK_GOST28147 must be specified



with the same attribute CKA_OBJECT_ID. The attribute value may be omitted


Note that when generating an GOST R 34.10-2001 private key, the GOST R 34.10-2001 domain 13727 parameters are not specified in the key’s template. This is because GOST R 34.10-2001 private keys are 13728 only generated as part of an GOST R 34.10-2001 key pair, and the GOST R 34.10-2001 domain 13729

parameters for the pair are specified in the template for the GOST R 34.10-2001 public key. 13730

The following is a sample template for creating an GOST R 34.10-2001 private key object: 13731



CK_UTF8CHAR label[] = “A GOST R34.10-2001 private key 13734

object”; 13735


CK_BYTE id[] = {123}; 13737


{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x00}; 13739


{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1e, 0x00}; 13741

CK_BYTE gost28147params_oid[] = 13742

{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x00}; 13743

CK_BYTE value[32] = {...}; 13744















{CKA_GOST28147_PARAMS, gost28147params_oid, 13759

sizeof(gost28147params_oid)}, 13760


}; 13762

13763

6.57.4 GOST R 34.10-2001 domain parameter objects 13764

GOST R 34.10-2001 domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type 13765 CKK_GOSTR3410) hold GOST R 34.10-2001 domain parameters. 13766


The following table defines the GOST R 34.10-2001 domain parameter object attributes, in addition to the 13767 common attributes defined for this object class: 13768

Table 245, GOST R 34.10-2001 Domain Parameter Object Attributes 13769



was introduced in [4] section 8.4 (type GostR3410-2001-ParamSetParameters)





The following is a sample template for creating a GOST R 34.10-2001 domain parameter object: 13774



CK_UTF8CHAR label[] = “A GOST R34.10-2001 cryptographic 13777


CK_BYTE oid[] = 13779

{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x00}; 13780


0x30,0x81,0x90,0x02,0x01,0x07,0x02,0x20,0x5f,0xbf,0xf4,0x98, 13782

0xaa,0x93,0x8c,0xe7,0x39,0xb8,0xe0,0x22,0xfb,0xaf,0xef,0x40, 13783

0x56,0x3f,0x6e,0x6a,0x34,0x72,0xfc,0x2a,0x51,0x4c,0x0c,0xe9, 13784

0xda,0xe2,0x3b,0x7e,0x02,0x21,0x00,0x80,0x00,0x00,0x00,0x00, 13785

0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, 13786

0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, 13787

0x00,0x04,0x31,0x02,0x21,0x00,0x80,0x00,0x00,0x00,0x00,0x00, 13788

0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01,0x50,0xfe, 13789

0x8a,0x18,0x92,0x97,0x61,0x54,0xc5,0x9c,0xfc,0x19,0x3a,0xcc, 13790

0xf5,0xb3,0x02,0x01,0x02,0x02,0x20,0x08,0xe2,0xa8,0xa0,0xe6, 13791

0x51,0x47,0xd4,0xbd,0x63,0x16,0x03,0x0e,0x16,0xd1,0x9c,0x85, 13792

0xc9,0x7f,0x0a,0x9c,0xa2,0x67,0x12,0x2b,0x96,0xab,0xbc,0xea, 13793

0x7e,0x8f,0xc8 13794

}; 13795









}; 13804

13805




6.57.5 GOST R 34.10-2001 mechanism parameters 13806

♦ CK_GOSTR3410_KEY_WRAP_PARAMS 13807

CK_GOSTR3410_KEY_WRAP_PARAMS is a structure that provides the parameters to the 13808 CKM_GOSTR3410_KEY_WRAP mechanism. It is defined as follows: 13809

typedef struct CK_GOSTR3410_KEY_WRAP_PARAMS { 13810

CK_BYTE_PTR pWrapOID; 13811

CK_ULONG ulWrapOIDLen; 13812

CK_BYTE_PTR pUKM; 13813

CK_ULONG ulUKMLen; 13814


} CK_GOSTR3410_KEY_WRAP_PARAMS; 13816

13817


pWrapOID pointer to a data with DER-encoding of the object identifier indicating the data object type of GOST 28147-89. If pointer takes NULL_PTR value in C_WrapKey operation then parameters are specified in object identifier of attribute CKA_GOSTR3411_PARAMS must be used. For C_UnwrapKey operation the pointer is not used and must take NULL_PTR value anytime

ulWrapOIDLen length of data with DER-encoding of the object identifier indicating the data object type of GOST 28147-89

pUKM pointer to a data with UKM. If pointer takes NULL_PTR value in C_WrapKey operation then random value of UKM will be used. If pointer takes non-NULL_PTR value in C_UnwrapKey operation then the pointer value will be compared with UKM value of wrapped key. If these two values do not match the wrapped key will be rejected

ulUKMLen length of UKM data. If pUKM-pointer is different from

NULL_PTR then equal to 8

hKey key handle. Key handle of a sender for C_WrapKey operation. Key handle of a receiver for C_UnwrapKey operation. When key handle takes CK_INVALID_HANDLE value then an ephemeral (one time) key pair of a sender will be used

CK_GOSTR3410_KEY_WRAP_PARAMS_PTR is a pointer to a 13819 CK_GOSTR3410_KEY_WRAP_PARAMS. 13820

♦ CK_GOSTR3410_DERIVE_PARAMS 13821

CK_GOSTR3410_DERIVE_PARAMS is a structure that provides the parameters to the 13822 CKM_GOSTR3410_DERIVE mechanism. It is defined as follows: 13823

typedef struct CK_GOSTR3410_DERIVE_PARAMS { 13824




CK_BYTE_PTR pUKM; 13828


CK_ULONG ulUKMLen; 13829

} CK_GOSTR3410_DERIVE_PARAMS; 13830

13831


kdf additional key diversification algorithm identifier. Possible values are CKD_NULL and CKD_CPDIVERSIFY_KDF. In case of CKD_NULL, result of the key derivation function

described in [RFC 4357], section 5.2 is used directly; In case of CKD_CPDIVERSIFY_KDF, the resulting key value is additionally processed with algorithm from [RFC 4357], section 6.5.

pPublicData1 pointer to data with public key of a receiver

ulPublicDataLen length of data with public key of a receiver (must be 64)

pUKM pointer to a UKM data

ulUKMLen length of UKM data in bytes (must be 8)

13833 1 Public key of a receiver is an octet string of 64 bytes long. The public key octets correspond to the concatenation of X and Y coordinates of a point. Any one of

13834 them is 32 bytes long and represented in little endian order.

13835

CK_GOSTR3410_DERIVE_PARAMS_PTR is a pointer to a CK_GOSTR3410_DERIVE_PARAMS.

13836

6.57.6 GOST R 34.10-2001 key pair generation 13837

The GOST R 34.10-2001 key pair generation mechanism, denoted 13838 CKM_GOSTR3410_KEY_PAIR_GEN, is a key pair generation mechanism for GOST R 34.10-2001. 13839


The mechanism generates GOST R 34.10-2001 public/private key pairs with particular 13841 GOST R 34.10-2001 domain parameters, as specified in the CKA_GOSTR3410_PARAMS, 13842 CKA_GOSTR3411_PARAMS, and CKA_GOST28147_PARAMS attributes of the template for the public 13843 key. Note that CKA_GOST28147_PARAMS attribute may not be present in the template. 13844

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 13845 public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE, and CKA_GOSTR3410_PARAMS, 13846 CKA_GOSTR3411_PARAMS, CKA_GOST28147_PARAMS attributes to the new private key. 13847


are not used. 13849

6.57.7 GOST R 34.10-2001 without hashing 13850

The GOST R 34.10-2001 without hashing mechanism, denoted CKM_GOSTR3410, is a mechanism for 13851 single-part signatures and verification for GOST R 34.10-2001. (This mechanism corresponds only to the 13852 part of GOST R 34.10-2001 that processes the 32-bytes hash value; it does not compute the hash value.) 13853


For the purposes of these mechanisms, a GOST R 34.10-2001 signature is an octet string of 64 bytes 13855 long. The signature octets correspond to the concatenation of the GOST R 34.10-2001 values s and r’, 13856 both represented as a 32 bytes octet string in big endian order with the most significant byte first [RFC 13857 4490] section 3.2, and [RFC 4491] section 2.2.2. 13858


The input for the mechanism is an octet string of 32 bytes long with digest has computed by means of 13859 GOST R 34.11-94 hash algorithm in the context of signed or should be signed message. 13860

Table 246, GOST R 34.10-2001 without hashing: Key and Data Length 13861


C_Sign1 CKK_GOSTR3410 32 bytes 64 bytes

C_Verify1 CKK_GOSTR3410 32 bytes 64 bytes


13862


are not used. 13864

6.57.8 GOST R 34.10-2001 with GOST R 34.11-94 13865

The GOST R 34.10-2001 with GOST R 34.11-94, denoted CKM_GOSTR3410_WITH_GOSTR3411, is a 13866 mechanism for signatures and verification for GOST R 34.10-2001. This mechanism computes the entire 13867 GOST R 34.10-2001 specification, including the hashing with GOST R 34.11-94 hash algorithm. 13868

As a parameter this mechanism utilizes a DER-encoding of the object identifier indicating 13869 GOST R 34.11-94 data object type. A mechanism parameter may be missed then parameters are 13870 specified in object identifier of attribute CKA_GOSTR3411_PARAMS must be used. 13871

For the purposes of these mechanisms, a GOST R 34.10-2001 signature is an octet string of 64 bytes 13872 long. The signature octets correspond to the concatenation of the GOST R 34.10-2001 values s and r’, 13873 both represented as a 32 bytes octet string in big endian order with the most significant byte first [RFC 13874 4490] section 3.2, and [RFC 4491] section 2.2.2. 13875

The input for the mechanism is signed or should be signed message of any length. Single- and multiple-13876 part signature operations are available. 13877

Table 247, GOST R 34.10-2001 with GOST R 34.11-94: Key and Data Length 13878


C_Sign CKK_GOSTR3410 Any 64 bytes

C_Verify CKK_GOSTR3410 Any 64 bytes


6.57.9 GOST 28147-89 keys wrapping/unwrapping with GOST R 34.10-2001 13881

GOST R 34.10-2001 keys as a KEK (key encryption keys) for encryption GOST 28147 keys, denoted by 13882 CKM_GOSTR3410_KEY_WRAP, is a mechanism for key wrapping; and key unwrapping, based on 13883 GOST R 34.10-2001. Its purpose is to encrypt and decrypt keys have been generated by key generation 13884 mechanism for GOST 28147-89. An encryption algorithm from [RFC 4490] (section 5.2) must be used. 13885 Encrypted key is a DER-encoded structure of ASN.1 GostR3410-KeyTransport type [RFC 4490] section 13886 4.2. 13887

It has a parameter, a CK_GOSTR3410_KEY_WRAP_PARAMS structure defined in section 6.57.5. 13888

For unwrapping (C_UnwrapKey), the mechanism decrypts the wrapped key, and contributes the result as 13889 the CKA_VALUE attribute of the new key. 13890


are not used. 13892

6.57.10 Common key derivation with assistance of GOST R 34.10-2001 keys 13893

Common key derivation, denoted CKM_GOSTR3410_DERIVE, is a mechanism for key derivation with 13894 assistance of GOST R 34.10-2001 private and public keys. The key of the mechanism must be of object 13895


class CKO_DOMAIN_PARAMETERS and key type CKK_GOSTR3410. An algorithm for key derivation 13896

from [RFC 4357] (section 5.2) must be used. 13897

The mechanism contributes the result as the CKA_VALUE attribute of the new private key. All other 13898

attributes must be specified in a template for creating private key object. 13899

6.58 ChaCha20 13900

ChaCha20 is a secret-key stream cipher described in [CHACHA]. 13901

Table 248, ChaCha20 Mechanisms vs. Functions 13902

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_CHACHA20_KEY_GEN ✓

CKM_CHACHA20 ✓ ✓

13903


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

Mechanisms: 13907

CKM_CHACHA20_KEY_GEN 13908

CKM_CHACHA20 13909

6.58.2 ChaCha20 secret key objects 13910

ChaCha20 secret key objects (object class CKO_SECRET_KEY, key type CKK_CHACHA20) hold 13911 ChaCha20 keys. The following table defines the ChaCha20 secret key object attributes, in addition to the 13912 common attributes defined for this object class: 13913

Table 249, ChaCha20 Secret Key Object 13914


CKA_VALUE1,4,6,7 Byte array Key length is fixed at 256 bits.

Bit length restricted to a byte array.

CKA_VALUE_LEN2,3 CK_ULONG Length in bytes of key value

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


CK_KEY_TYPE keyType = CKK_CHACHA20; 13917

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

CK_BYTE value[32] = {...}; 13919










}; 13928

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

6.58.3 ChaCha20 mechanism parameters 13931

CK_CHACHA20_PARAMS; CK_CHACHA20_PARAMS_PTR 13932

CK_CHACHA20_PARAMS provides the parameters to the CKM_CHACHA20 mechanism. It is defined 13933 as follows: 13934

typedef struct CK_CHACHA20_PARAMS { 13935

CK_BYTE_PTR pBlockCounter; 13936

CK_ULONG blockCounterBits; 13937


CK_ULONG ulNonceBits; 13939

} CK_CHACHA20_PARAMS; 13940


pBlockCounter pointer to block counter 13942

ulblockCounterBits length of block counter in bits (can be either 32 or 64) 13943

pNonce nonce (This should be never re-used with the same key.) 13944

ulNonceBits length of nonce in bits (is 64 for original, 96 for IETF and 192 for 13945 xchacha20 variant) 13946

The block counter is used to address 512 bit blocks in the stream. In certain settings (e.g. disk encryption) 13947 it is necessary to address these blocks in random order, thus this counter is exposed here. 13948

CK_CHACHA20_PARAMS_PTR is a pointer to CK_CHACHA20_PARAMS. 13949

6.58.4 ChaCha20 key generation 13950

The ChaCha20 key generation mechanism, denoted CKM_CHACHA20_KEY_GEN, is a key generation 13951

mechanism for ChaCha20. 13952


The mechanism generates ChaCha20 keys of 256 bits. 13954


For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 13958 specify the supported range of key sizes in bytes. As a practical matter, the key size for ChaCha20 is 13959 fixed at 256 bits. 13960

13961

6.58.5 ChaCha20 mechanism 13962

ChaCha20, denoted CKM_CHACHA20, is a mechanism for single and multiple-part encryption and 13963 decryption based on the ChaCha20 stream cipher. It comes in 3 variants, which only differ in the size and 13964 handling of their nonces, affecting the safety of using random nonces and the maximum size that can be 13965 encrypted safely. 13966


Chacha20 has a parameter, CK_CHACHA20_PARAMS, which indicates the nonce and initial block 13967

counter value. 13968


Table 250, ChaCha20: Key and Data Length 13970


C_Encrypt ChaCha20 Any / only up to 256 GB in case of IETF variant


C_Decrypt ChaCha20 Any / only up to 256 GB in case of IETF variant


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

Table 251, ChaCha20: Nonce and block counter lengths 13973

Variant Nonce Block counter

Maximum message Nonce generation

original 64 bit 64 bit Virtually unlimited 1st msg:

nonce0=random

nth msg:

noncen-1++

IETF 96 bit 32 bit Max ~256 GB 1st msg:

nonce0=random

nth msg:

noncen-1++

XChaCha20

192 bit 64 bit Virtually unlimited Each nonce can be randomly generated.

Nonces must not ever be reused with the same key. However due to the birthday paradox the first two 13974 variants cannot guarantee that randomly generated nonces are never repeating. Thus the recommended 13975 way to handle this is to generate the first nonce randomly, then increase this for follow-up messages. 13976 Only the last (XChaCha20) has large enough nonces so that it is virtually impossible to trigger with 13977 randomly generated nonces the birthday paradox. 13978

6.59 Salsa20 13979

Salsa20 is a secret-key stream cipher described in [SALSA]. 13980

Table 252, Salsa20 Mechanisms vs. Functions 13981


Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_SALSA20_KEY_GEN ✓

CKM_SALSA20 ✓ ✓

13982


This section defines the key type “CKK_SALSA20” and “CKK_SALSA20” for type CK_KEY_TYPE as 13984 used in the CKA_KEY_TYPE attribute of key objects. 13985

Mechanisms: 13986

CKM_SALSA20_KEY_GEN 13987

CKM_SALSA20 13988

6.59.2 Salsa20 secret key objects 13989

Salsa20 secret key objects (object class CKO_SECRET_KEY, key type CKK_SALSA20) hold Salsa20 13990 keys. The following table defines the Salsa20 secret key object attributes, in addition to the common 13991 attributes defined for this object class: 13992

Table 253, ChaCha20 Secret Key Object 13993





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


CK_KEY_TYPE keyType = CKK_SALSA20; 13996

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

CK_BYTE value[32] = {...}; 13998









}; 14007

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


6.59.3 Salsa20 mechanism parameters 14010

CK_SALSA20_PARAMS; CK_SALSA20_PARAMS_PTR 14011

CK_SALSA20_PARAMS provides the parameters to the CKM_SALSA20 mechanism. It is defined as 14012 follows: 14013

typedef struct CK_SALSA20_PARAMS { 14014

CK_BYTE_PTR pBlockCounter; 14015


CK_ULONG ulNonceBits; 14017

} CK_SALSA20_PARAMS; 14018

14019


pBlockCounter pointer to block counter (64 bits) 14021

pNonce nonce 14022

ulNonceBits size of the nonce in bits (64 for classic and 192 for XSalsa20) 14023

The block counter is used to address 512 bit blocks in the stream. In certain settings (e.g. disk encryption) 14024 it is necessary to address these blocks in random order, thus this counter is exposed here. 14025

CK_SALSA20_PARAMS_PTR is a pointer to CK_SALSA20_PARAMS. 14026

6.59.4 Salsa20 key generation 14027

The Salsa20 key generation mechanism, denoted CKM_SALSA20_KEY_GEN, is a key generation 14028 mechanism for Salsa20. 14029


The mechanism generates Salsa20 keys of 256 bits. 14031


For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 14035 specify the supported range of key sizes in bytes. As a practical matter, the key size for Salsa20 is fixed 14036 at 256 bits. 14037

6.59.5 Salsa20 mechanism 14038

Salsa20, denoted CKM_SALSA20, is a mechanism for single and multiple-part encryption and decryption 14039 based on the Salsa20 stream cipher. Salsa20 comes in two variants which only differ in the size and 14040 handling of their nonces, affecting the safety of using random nonces. 14041

Salsa20 has a parameter, CK_SALSA20_PARAMS, which indicates the nonce and initial block counter 14042

value. 14043


Table 254, Salsa20: Key and Data Length 14045


C_Encrypt Salsa20 Any Same as input length No final part

C_Decrypt Salsa20 Any Same as input length No final part


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

Table 255, Salsa20: Nonce sizes 14048

Variant Nonce Maximum message Nonce generation

original 64 bit Virtually unlimited 1st msg:

nonce0=random

nth msg:

noncen-1++

XSalsa20 192 bit Virtually unlimited Each nonce can be randomly generated.

Nonces must not ever be reused with the same key. However due to the birthday paradox the original 14049 variant cannot guarantee that randomly generated nonces are never repeating. Thus the recommended 14050 way to handle this is to generate the first nonce randomly, then increase this for follow-up messages. 14051 Only the XSalsa20 has large enough nonces so that it is virtually impossible to trigger with randomly 14052 generated nonces the birthday paradox. 14053

6.60 Poly1305 14054

Poly1305 is a message authentication code designed by D.J Bernsterin [POLY1305]. Poly1305 takes a 14055 256 bit key and a message and produces a 128 bit tag that is used to verify the message. 14056

Table 256, Poly1305 Mechanisms vs. Functions 14057

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_POLY1305_KEY_GEN ✓

CKM_POLY1305 ✓


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

Mechanisms: 14061

CKM_POLY1305_KEY_GEN 14062

CKM_POLY1305 14063

6.60.2 Poly1305 secret key objects 14064

Poly1305 secret key objects (object class CKO_SECRET_KEY, key type CKK_POLY1305) hold 14065 Poly1305 keys. The following table defines the Poly1305 secret key object attributes, in addition to the 14066 common attributes defined for this object class: 14067

Table 257, Poly1305 Secret Key Object 14068






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


CK_KEY_TYPE keyType = CKK_POLY1305; 14071

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

CK_BYTE value[32] = {...}; 14073









}; 14082

14083

6.60.3 Poly1305 mechanism 14084

Poly1305, denoted CKM_POLY1305, is a mechanism for producing an output tag based on a 256 bit key 14085 and arbitrary length input. 14086

It has no parameters. 14087

Signatures (MACs) produced by this mechanism will be fixed at 128 bits in size. 14088

Table 258, Poly1305: Key and Data Length 14089

Function Key type Data length Signature Length

C_Sign Poly1305 Any 128 bits

C_Verify Poly1305 Any 128 bits

6.61 Chacha20/Poly1305 and Salsa20/Poly1305 Authenticated 14090

Encryption / Decryption 14091

The stream ciphers Salsa20 and ChaCha20 are normally used in conjunction with the Poly1305 14092 authenticator, in such a construction they also provide Authenticated Encryption with Associated Data 14093 (AEAD). This section defines the combined mechanisms and their usage in an AEAD setting. 14094

Table 259, Poly1305 Mechanisms vs. Functions 14095

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_CHACHA20_POLY1305 ✓

CKM_SALSA20_POLY1305 ✓



Mechanisms: 14097

CKM_CHACHA20_POLY1305 14098

CKM_SALSA20_POLY1305 14099

6.61.2 Usage 14100

Generic ChaCha20, Salsa20, Poly1305 modes are described in [CHACHA], [SALSA] and [POLY1305]. 14101 To set up for ChaCha20/Poly1305 or Salsa20/Poly1305 use the following process. ChaCha20/Poly1305 14102 and Salsa20/Poly1305 both use CK_SALSA20_CHACHA20_POLY1305_PARAMS for Encrypt, Decrypt 14103 and CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS for MessageEncrypt, and MessageDecrypt. 14104

Encrypt: 14105

Set the Nonce length ulNonceLen in the parameter block. (this affects which variant of Chacha20 14106 will be used: 64 bits → original, 96 bits → IETF, 192 bits → XChaCha20) 14107

Set the Nonce data pNonce in the parameter block. 14108


Call C_EncryptInit() for CKM_CHACHA20_POLY1305 or CKM_SALSA20_POLY1305 14111 mechanism with parameters and key K. 14112

Call C_Encrypt(), or C_EncryptUpdate()*10

C_EncryptFinal(), for the plaintext obtaining ciphertext 14113 and authentication tag output. 14114

Decrypt: 14115




Call C_DecryptInit() for CKM_CHACHA20_POLY1305 or CKM_SALSA20_POLY1305 14121 mechanism with parameters and key K. 14122

Call C_Decrypt(), or C_DecryptUpdate()*1 C_DecryptFinal(), for the ciphertext, including the 14123

appended tag, obtaining plaintext output. Note: since CKM_CHACHA20_POLY1305 and 14124 CKM_SALSA20_POLY1305 are AEAD ciphers, no data should be returned until C_Decrypt() or 14125 C_DecryptFinal(). 14126

MessageEncrypt:: 14127



Set pTag to hold the tag data returned from C_EncryptMessage() or the final 14131 C_EncryptMessageNext(). 14132



Call C_MessageEncryptInit() for CKM_CHACHA20_POLY1305 or CKM_SALSA20_POLY1305 14133 mechanism with key K. 14134

Call C_EncryptMessage(), or C_EncryptMessageBegin followed by C_EncryptMessageNext()*11

. 14135 The mechanism parameter is passed to all three of these functions. 14136

Call C_MessageEncryptFinal() to close the message decryption. 14137




Set the tag data pTag in the parameter block before C_DecryptMessage or the final 14142 C_DecryptMessageNext() 14143

Call C_MessageDecryptInit() for CKM_CHACHA20_POLY1305 or CKM_SALSA20_POLY1305 14144 mechanism with key K. 14145

Call C_DecryptMessage(), or C_DecryptMessageBegin followed by C_DecryptMessageNext()*12

. 14146 The mechanism parameter is passed to all three of these functions. 14147

Call C_MessageDecryptFinal() to close the message decryption 14148

14149

ulNonceLen is the length of the nonce in bits. 14150

In Encrypt and Decrypt the tag is appended to the cipher text. In MessageEncrypt the tag is returned in 14151 the pTag filed of CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS. In MesssageDecrypt the tag is 14152 provided by the pTag field of CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS. The application 14153 must provide 16 bytes of space for the tag. 14154

The key type for K must be compatible with CKM_CHACHA20 or CKM_SALSA20 respectively and the 14155 C_EncryptInit/C_DecryptInit calls shall behave, with respect to K, as if they were called directly with 14156 CKM_CHACHA20 or CKM_SALSA20, K and NULL parameters. 14157

Unlike the atomic Salsa20/ChaCha20 mechanism the AEAD mechanism based on them does not expose 14158 the block counter, as the AEAD construction is based on a message metaphor in which random access is 14159 not needed. 14160

6.61.3 ChaCha20/Poly1305 and Salsa20/Poly1305 Mechanism parameters 14161

CK_SALSA20_CHACHA20_POLY1305_PARAMS; 14162

CK_SALSA20_CHACHA20_POLY1305_PARAMS_PTR 14163

CK_SALSA20_CHACHA20_POLY1305_PARAMS is a structure that provides the parameters to the 14164 CKM_CHACHA20_POLY1305 and CKM_SALSA20_POLY1305 mechanisms. It is defined as follows: 14165

typedef struct CK_SALSA20_CHACHA20_POLY1305_PARAMS { 14166








} CK_SALSA20_CHACHA20_POLY1305_PARAMS; 14171


pNonce nonce (This should be never re-used with the same key.) 14173

ulNonceLen length of nonce in bits (is 64 for original, 96 for IETF (only for 14174 chacha20) and 192 for xchacha20/xsalsa20 variant) 14175

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

ulAADLen length of pAAD in bytes. 14178

CK_SALSA20_CHACHA20_POLY1305_PARAMS_PTR is a pointer to a 14179 CK_SALSA20_CHACHA20_POLY1305_PARAMS. 14180

CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS; 14181

CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS_PTR 14182

CK_CHACHA20POLY1305_PARAMS is a structure that provides the parameters to the CKM_ 14183 CHACHA20_POLY1305 mechanism. It is defined as follows: 14184

typedef struct CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS { 14185



CK_BYTE_PTR pTag; 14188

} CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS; 14189


pNonce pointer to nonce 14191

ulNonceLen length of nonce in bits. The length of the influences which variant of 14192 the ChaCha20 will be used (64 original, 96 IETF(only for 14193 ChaCha20), 192 XChaCha20/XSalsa20) 14194

pTag location of the authentication tag which is returned on 14195 MessageEncrypt, and provided on MessageDecrypt. 14196

CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS_PTR is a pointer to a 14197 CK_SALSA20_CHACHA20_POLY1305_MSG_PARAMS. 14198

6.62 HKDF Mechanisms 14199

Details for HKDF key derivation mechanisms can be found in [RFC 5869]. 14200

14201

Table 260, HKDF Mechanisms vs. Functions 14202

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_HKDF_DERIVE

CKM_HKDF_DATA

CKM_HKDF_KEY_GEN



Mechanisms: 14204

CKM_HKDF_DERIVE 14205

CKM_HKDF_DATA 14206

CKM_HKDF_KEY_GEN 14207

14208

Key Types: 14209

CKK_HKDF 14210

6.62.2 HKDF mechanism parameters 14211

CK_HKDF_PARAMS; CK_HKDF_PARAMS_PTR 14212

CK_HKDF_PARAMS is a structure that provides the parameters to the CKM_HKDF_DERIVE and 14213 CKM_HKDF_DATA mechanisms. It is defined as follows: 14214

typedef struct CK_HKDF_PARAMS { 14215

CK_BBOOL bExtract; 14216

CK_BBOOL bExpand; 14217


CK_ULONG ulSaltType; 14219

CK_BYTE_PTR pSalt; 14220

CK_ULONG ulSaltLen; 14221

CK_OBJECT_HANDLE hSaltKey; 14222

CK_BYTE_PTR pInfo; 14223

CK_ULONG ulInfoLen; 14224

} CK_HKDF_PARAMS; 14225

14226


bExtract execute the extract portion of HKDF. 14228

bExpand execute the expand portion of HKDF. 14229

prfHashMechanism base hash used for the HMAC in the underlying HKDF operation. 14230

ulSaltType specifies how the salt for the extract portion of the KDF is supplied. 14231

CKF_HKDF_SALT_NULL no salt is supplied. 14232

CKF_HKDF_SALT_DATA salt is supplied as a data in pSalt with 14233 length ulSaltLen. 14234

CKF_HKDF_SALT_KEY salt is supplied as a key in hSaltKey. 14235

pSalt pointer to the salt. 14236

ulSaltLen length of the salt pointed to in pSalt. 14237

hSaltKey object handle to the salt key. 14238

pInfo info string for the expand stage. 14239

ulInfoLen length of the info string for the expand stage. 14240

14241

CK_HKDF_PARAMS_PTR is a pointer to a CK_HKDF_PARAMS. 14242


6.62.3 HKDF derive 14243

HKDF derivation implements the HKDF as specified in [RFC 5869]. The two booleans bExtract and 14244 bExpand control whether the extract section of the HKDF or the expand section of the HKDF is in use. 14245

It has a parameter, a CK_HKDF_PARAMS structure, which allows for the passing of the salt and or the 14246 expansion info. The structure contains the bools bExtract and bExpand which control whether the extract 14247

or expand portions of the HKDF is to be used. This structure is defined in Section 6.62.26.62.2. 14248

The input key must be of type CKK_HKDF or CKK_GENERIC_SECRET and the length must be the size 14249 of the underlying hash function specified in prfHashMechanism. The exception is a data object which has 14250 the same size as the underlying hash function, and which may be supplied as an input key. In this case 14251 bExtract should be true and non-null salt should be supplied. 14252

Either bExtract or bExpand must be set to true. If they are both set to true, input key is first extracted then 14253 expanded. The salt is used in the extraction stage. If bExtract is set to true and no salt is given, a ‘zero’ 14254 salt (salt whose length is the same as the underlying hash and values all set to zero) is used as specified 14255 by the RFC. If bExpand is set to true, CKA_VALUE_LEN should be set to the desired key length. If it is 14256 false CKA_VALUE_LEN may be set to the length of the hash, but that is not necessary as the mechanism 14257 will supply this value. The salt should be ignored if bExtract is false. The pInfo should be ignored if 14258 bExpand is set to false. 14259

The mechanism also contributes the CKA_CLASS, and CKA_VALUE attributes to the new key. Other 14260

attributes may be specified in the template, or else are assigned default values. 14261

The template sent along with this mechanism during a C_DeriveKey call may indicate that the object 14262 class is CKO_SECRET_KEY. However, since these facts are all implicit in the mechanism, there is no 14263

need to specify any of them. 14264





6.62.4 HKDF Data 14277

HKDF Data derive mechanism, denoted CKM_HKDF_DATA, is identical to HKDF Derive except the 14278 output is a CKO_DATA object whose value is the result to the derive operation. Some tokens may restrict 14279 what data may be successfully derived based on the pInfo portion of the CK_HKDF_PARAMS. Tokens 14280 may reject requests based on the pInfo values. Allowed pInfo values are specified in the profile document 14281

and applications could then query the appropriate profile before depending on the mechanism. 14282

6.62.5 HKDF Key gen 14283

HKDF key gen, denoted CKM_HKDF_KEY_GEN generates a new random HKDF key. 14284 CKA_VALUE_LEN must be set in the template. 14285

6.63 NULL Mechanism 14286

CKM_NULL is a mechanism used to implement the trivial pass-through function. 14287

14288

Field Code Changed


Table 261, CKM_NULL Mechanisms vs. Functions 14289

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_NULL


14290


Mechanisms: 14292

CKM_NULL 14293

6.63.2 CKM_NULL mechanism parameters 14294

CKM_NULL does not have a parameter. 14295

14296

When used for encrypting / decrypting data, the input data is copied unchanged to the output data. 14297

When used for signing, the input data is copied to the signature. When used for signature verification, it 14298 compares the input data and the signature, and returns CKR_OK (indicating that both are identical) or 14299 CKR_SIGNATURE_INVALID. 14300

When used for digesting data, the input data is copied to the message digest. 14301

When used for wrapping a private or secret key object, the wrapped key will be identical to the key to be 14302 wrapped. When used for unwrapping, a new object with the same value as the wrapped key will be 14303 created. 14304

When used for deriving a key, the derived key has the same value as the base key. 14305

14306

6.64 IKE Mechanisms 14307

14308

Table 262, IKE Mechanisms vs. Functions 14309

Functions

Mechanism

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR1

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_IKE2_PRF_PLUS_DERIVE

CKM_IKE_PRF_DERIVE

CKM_IKE1_PRF_DERIVE

CKM_IKE1_EXTENDED_DERIVE

14310


Mechanisms: 14312


CKM_IKE2_PRF_PLUS_DERIVE 14313

CKM_IKE_PRF_DERIVE 14314

CKM_IKE1_PRF_DERIVE 14315

CKM_IKE1_EXTENDED_DERIVE 14316

14317

6.64.2 IKE mechanism parameters 14318

CK_IKE2_PRF_PLUS_DERIVE_PARAMS; 14319

CK_IKE2_PRF_PLUS_DERIVE_PARAMS_PTR 14320

CK_IKE2_PRF_PLUS_DERIVE_PARAMS is a structure that provides the parameters to the 14321 CKM_IKE2_PRF_PLUS_DERIVE mechanism. It is defined as follows: 14322

typedef struct CK_IKE2_PRF_PLUS_DERIVE_PARAMS { 14323


CK_BBOOL bHasSeedKey; 14325

CK_OBJECT_HANDLE hSeedKey; 14326

CK_BYTE_PTR pSeedData; 14327

CK_ULONG ulSeedDataLen; 14328

} CK_IKE2_PRF_PLUS_DERIVE_PARAMS; 14329

14330


prfMechanism underlying MAC mechanism used to generate the prf 14332

bHasSeedKey hSeed key is present 14333

hSeedKey optional seed from key 14334

pSeedData optional seed from data 14335

ulSeedDataLen length of optional seed data. If no seed data is present this value is 14336 0 14337

CK_IKE2_PRF_PLUS_DERIVE_PARAMS_PTR is a pointer to a 14338 CK_IKE2_PRF_PLUS_DERIVE_PARAMS. 14339

14340

CK_IKE_PRF_DERIVE_PARAMS; CK_IKE_PRF_DERIVE_PARAMS_PTR 14341

CK_IKE_PRF_DERIVE_PARAMS is a structure that provides the parameters to the 14342 CKM_IKE_PRF_DERIVE mechanism. It is defined as follows: 14343

14344

typedef struct CK_IKE_PRF_DERIVE_PARAMS { 14345


CK_BBOOL bDataAsKey; 14347

CK_BBOOL bRekey; 14348

CK_BYTE_PTR pNi; 14349

CK_ULONG ulNiLen; 14350

CK_BYTE_PTR pNr; 14351

CK_ULONG ulNrLen; 14352

CK_OBJECT_HANDLE hNewKey; 14353

} CK_IKE_PRF_PARAMS; 14354


14355



bDataAsKey Ni||Nr is used as the key for the prf rather than baseKey 14358

bRekey rekey operation. hNewKey must be present 14359

pNi Ni value 14360

ulNiLen length of Ni 14361

pNr Nr value 14362

ulNrLen length of Nr 14363

hNewKey New key value to drive the rekey. 14364

CK_IKE_PRF_DERIVE_PARAMS_PTR is a pointer to a CK_IKE_PRF_DERIVE_PARAMS. 14365

14366

CK_IKE1_PRF_DERIVE_PARAMS; CK_IKE1_PRF_DERIVE_PARAMS_PTR 14367

CK_IKE1_PRF_DERIVE_PARAMS is a structure that provides the parameters to the 14368 CKM_IKE1_PRF_DERIVE mechanism. It is defined as follows: 14369

typedef struct CK_IKE1_PRF_DERIVE_PARAMS { 14370


CK_BBOOL bHasPrevKey; 14372

CK_OBJECT_HANDLE hKeygxy; 14373

CK_OBJECT_HANDLE hPrevKey; 14374

CK_BYTE_PTR pCKYi; 14375

CK_ULONG ulCKYiLen; 14376

CK_BYTE_PTR pCKYr; 14377

CK_ULONG ulCKYrLen; 14378

CK_BYTE keyNumber; 14379

} CK_IKE1_PRF_DERIVE_PARAMS; 14380

14381



bHasPrevkey hPrevKey is present 14384

hKeygxy handle to the exchanged g^xy key 14385

hPrevKey handle to the previously derived key 14386

pCKYi CKYi value 14387

ulCKYiLen length of CKYi 14388

pCKYr CKYr value 14389

ulCKYrLen length of CKYr 14390

keyNumber unique number for this key derivation 14391

CK_IKE1_PRF_DERIVE_PARAMS_PTR is a pointer to a CK_IKE1_PRF_DERIVE_PARAMS. 14392

14393


CK_IKE1_EXTENDED_DERIVE_PARAMS; 14394

CK_IKE1_EXTENDED_DERIVE_PARAMS_PTR 14395

CK_IKE1_EXTENDED_DERIVE_PARAMS is a structure that provides the parameters to the 14396 CKM_IKE1_EXTENDED_DERIVE mechanism. It is defined as follows: 14397

14398

typedef struct CK_NSS_IKE1_EXTENDED_DERIVE_PARAMS { 14399


CK_BBOOL bHasKeygxy; 14401

CK_OBJECT_HANDLE hKeygxy; 14402

CK_BYTE_PTR pExtraData; 14403

CK_ULONG ulExtraDataLen; 14404

} CK_NSS_IKE1_EXTENDED_DERIVE_PARAMS; 14405



bHasKeygxy hKeygxy key is present 14408

hKeygxy optional key g^xy 14409

pExtraData optional extra data 14410

ulExtraDataLen length of optional extra data. If no extra data is present this value is 14411 0 14412

CK_IKE2_PRF_PLUS_DERIVE_PARAMS_PTR is a pointer to a 14413 CK_IKE2_PRF_PLUS_DERIVE_PARAMS. 14414

14415

6.64.3 IKE PRF DERIVE 14416

The IKE PRF Derive mechanism denoted CKM_IKE_PRF_DERIVE is used in IPSEC both IKEv1 and 14417 IKEv2 to generate an initial key that is used to generate additional keys. It takes a 14418 CK_IKE_PRF_DERIVE_PARAMS as a mechanism parameter. baseKey is the base key passed into 14419 C_DeriveKey. baseKey must be of type CKK_GENERIC_SECRET if bDataAsKey is TRUE and the key 14420 type of the underlying prf if bDataAsKey is FALSE. hNewKey must be of type CKK_GENERIC_SECRET. 14421 Depending on the parameter settings, it generates keys with a CKA_VALUE of: 14422

14423

1. prf(pNi|pNr, baseKey); (bDataAsKey=TRUE, bRekey=FALSE) 14424

2. prf(baseKey, pNi|pNr); (bDataAsKkey=FALSE, bRekey=FALSE) 14425

3. prf(baseKey, ValueOf(hNewKey)| pNi | pNr); (bDataAsKey=FALSE, bRekey=TRUE) 14426

The resulting output key is always the length of the underlying prf. The combination of 14427 bDataAsKey=TRUE and bRekey=TRUE is not allowed. If both are set, CKR_ARGUMENTS_BAD is 14428

returned. 14429

Case 1 is used in 14430

a. ikev2 (RFC 5996) baseKey is called gîr, the output is called SKEYSEED 14431

b. ikev1 (RFC 2409) baseKey is called gîr, the output is called SKEYID 14432

Case 2 is used in ikev1 (RFC 2409) inkey is called pre-shared-key, output is called SKEYID 14433

Case 3 is used in ikev2 (RFC 5996) rekey case, baseKey is SK_d, hNewKey is gîr (new), the output is 14434 called SKEYSEED. The derived key will have a length of the length of the underlying prf. If 14435 CKA_VALUE_LENGTHLEN is specified, it must equal the underlying prf or CKR_KEY_RANGE_ERROR 14436


is returned. If CKA_KEY_TYPE is not specified in the template, it will be the underlying key type of the 14437

prf. 14438

14439

6.64.4 IKEv1 PRF DERIVE 14440

The IKEv1 PRF Derive mechanism denoted CKM_IKE1_PRF_DERIVE is used in IPSEC IKEv1 to 14441 generate various additional keys from the initial SKEYID. It takes a CK_IKE1_PRF_DERIVE_PARAMS 14442 as a mechanism parameter. SKEYID is the base key passed into C_DeriveKey. 14443

14444

This mechanism derives a key with CKA_VALUE set to either: 14445

prf(baseKey, ValueOf(hKeygxy) || pCKYi || pCKYr || key_number) 14446

or 14447

prf(baseKey, ValueOf(hPrevKey) || ValueOf(hKeygxy) || pCKYi || pCKYr || key_number) 14448

depending on the state of bHasPrevKey. 14449

The key type of baseKey must be the key type of the prf, and the key type of hKeygxy must be 14450 CKK_GENERIC_SECRET. The key type of hPrevKey can be any key type. 14451

14452

This is defined in RFC 2409. For each of the following keys. 14453

baseKey is SKEYID, hKeygxy is g^xy 14454

for outKey = SKEYID_d, bHasPrevKey = false, key_number = 0 14455

for outKey = SKEYID_a, hPrevKey= SKEYID_d, key_number = 1 14456

for outKey = SKEYID_e, hPrevKey= SKEYID_a, key_number = 2 14457

If CKA_VALUE_LEN is not specified, the resulting key will be the length of the prf. If CKA_VALUE_LEN 14458 is greater then the prf, CKR_KEY_RANGE_ERROR is returned. If it is less the key is truncated taking 14459 the left most bytes. The value CKA_KEY_TYPE must be specified in the template or 14460 CKR_TEMPLATE_INCOMPLETE is returned. 14461

14462

6.64.5 IKEv2 PRF PLUS DERIVE 14463

The IKEv2 PRF PLUS Derive mechanism denoted CKM_IKE2_PRF_PLUS_DERIVE is used in IPSEC 14464 IKEv2 to derive various additional keys from the initial SKEYSEED. It takes a 14465 CKMCK_IKE2_PRF_PLUS_DERIVE_PARAMS as a mechanism parameter. SKEYSEED is the base key 14466 passed into C_DeriveKey. The key type of baseKey must be the key type of the underlying prf. This 14467 mechanism uses the base key and a feedback version of the prf to generate sufficient bytes to cover all 14468 the session keys. The application will then use CKM_EXTRACT_KEY_FROM_KEY to pull out the 14469 various subkeys. CKA_VALUE_LEN must be set in the template or CKR_KEY_RANGE_ERROR will be 14470 returned. If CKA_KEY_TYPE is not specified, the output key type will be CKK_GENERIC_SECRET. 14471

14472

This mechanism derives a key with a CKA_VALUE of (from RFC 5996): 14473

14474

prfplus = T1 | T2 | T3 | T4 |... Tn 14475

where: 14476

T1 = prf(K, S | 0x01) 14477

T2 = prf(K, T1 | S | 0x02) 14478

T3 = prf(K, T3 | S | 0x03) 14479

T4 = prf(K, T4 | S | 0x04) 14480


. 14481

Tn = prf(K, T(n-1) | n) 14482

K = baseKey, S = valueOf(hSeedKey) | pSeedData 14483

14484

6.64.6 IKEv1 Extended Derive 14485

The IKE Extended Derive mechanism denoted CKM_IKE1_EXTENDED_DERIVE is used in IPSEC 14486 IKEv1 to derive longer keys than CKM_IKE1_EXTENDED_DERVIVEDERIVE can from the initial 14487 SKEYID. It is used to support RFC 2409 appendix B and RFC 2409 section 5.5 (Quick Mode). It takes a 14488 CK_IKE1_EXTENDED_DERIVE_PARAMPARAMS as a mechanism parameter. SKEYID is the base key 14489 passed into C_DeriveKey. CKA_VALUE_LEN must be set in the template or 14490 CKR_KEY_RANGE_ERROR will be returned. If CKA_KEY_TYPE is not specified, the output key type 14491 will be CKK_GENERIC_SECRET. The key type of SKEYID must be the key type of the prf, and the key 14492 type of hKeygxy (if present) must be CKK_GENERIC_SECRET. 14493

14494

This mechanism derives a key with CKA_VALUE (from RFC 2409 appendix B and section 5.5): 14495

Ka = K1 | K2 | K3 | K4 |... Kn 14496

where: 14497

K1 = prf(K, valueOf(hKeygxy)|pExtraData) or prf(K,0x00) if bHashKeygxy is FALSE and ulExtraData 14498

is 0 14499

K2 = prf(K, K1|valueOf(hKeygxy)|pExtraData) 14500



. 14503

Kn = prf(K, K(n-1)|valueOf(hKeygxy)|pExtraData) 14504

K = baseKey 14505

14506

If CKA_VALUE_LEN is less then or equal to the prf length and bHasKeygxy is CK_FALSE, then the new 14507 key is simply the base key truncated to CKA_VALUE_LEN (specified in RFC 2409 appendix B). 14508 Otherwise the prf is executed and the derived keys value is CKA_VALUE_LEN bytes of the resulting prf. 14509

6.65 HSS 14510

HSS is a mechanism for single-part signatures and verification, following the digital signature algorithm 14511 defined in [RFC 8554] and [NIST 802-208]. 14512

14513

Table 263, HSS Mechanisms vs. Functions 14514

Mechanism Functions

Encrypt

&

Decrypt

Sign

&

Verify

SR

&

VR

Digest

Gen.

Key/

Key

Pair

Wrap

&

Unwrap

Derive

CKM_HSS_KEY_PAIR_GEN

CKM_HSS 1

1 Single-part operations only

14515

14516

Formatted: English (U.S.)



This section defines the key type CKK_HSS for type CK_KEY_TYPE as used in the CKA_KEY_TYPE 14518 attribute of key objects and domain parameter objects. 14519

Mechanisms: 14520

CKM_HSS_KEY_PAIR_GEN 14521

CKM_HSS 14522

6.65.2 HSS public key objects 14523

HSS public key objects (object class CKO_PUBLIC_KEY, key type CKK_HSS) hold HSS public keys. 14524

The following table defines the HSS public key object attributes, in addition to the common attributes 14525 defined for this object class: 14526

Table 264, HSS Public Key Object Attributes 14527


CKA_HSS_LEVELS2,4

CK_ULONG The number of levels in the HSS scheme.

CKA_HSS_LMS_TYPE2,4

CK_ULONG The encoding for the Merkle tree heights of the

top level LMS tree in the hierarchy.

CKA_HSS_LMOTS_TYPE2,4

CK_ULONG The encoding for the Winternitz parameter of

the one-time-signature scheme of the top level

LMS tree.

CKA_VALUE1,4

Byte array XDR-encoded public key as defined in

[RFC8554].


14529

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

14531

CK_OBJECT_CLASS keyClass = CKO_PUBLIC_KEY; 14532

CK_KEY_TYPE keyType = CKK_HSS; 14533

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

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



14538






{CKA_VALUE, value, sizeof(value)}, 14544

{CKA_VERIFY, &true, sizeof(true)} 14545

}; 14546


6.65.3 HSS private key objects 14547

HSS private key objects (object class CKO_PRIVATE_KEY, key type CKK_HSS) hold HSS private keys. 14548

The following table defines the HSS private key object attributes, in addition to the common attributes 14549 defined for this object class: 14550

14551

Table 265267, HSS Private Key Object Attributes 14552


CKA_HSS_LEVELS1,3

CK_ULONG The number of levels in the HSS scheme.

CKA_HSS_LMS_TYPES1,3

CK_ULONG_PTR A list of encodings for the Merkle tree

heights of the LMS trees in the hierarchy

from top to bottom. The number of

encodings in the array is the ulValueLen

component of the attribute divided by the

size of CK_ULONG. This number must

match the CKA_HSS_LEVELS attribute

value.

CKA_HSS_LMOTS_TYPES1,3

CK_ULONG_PTR A list of encodings for the Winternitz

parameter of the one-time-signature

scheme of the LMS trees in the hierarchy

from top to bottom. The number of

encodings in the array is the ulValueLen

component of the attribute divided by the

size of CK_ULONG. This number must

match the CKA_HSS_LEVELS attribute

value.

CKA_VALUE1,4,6,7

Byte array Vendor defined, must include state

information.

Note that exporting this value is dangerous

as it would allow key reuse.

CKA_HSS_KEYS_REMAINING2,4

CK_ULONG The minimum of the following two values:

1) The number of one-time private keys

remaining; 2) 2^32-1


14554

The encodings for CKA_HSS_LMOTS_TYPES and CKA_HSS_LMS_TYPES are defined in [RFC 8554] 14555 and [NIST 802-208]. 14556

14557

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

14559

CK_OBJECT_CLASS keyClass = CKO_PRIVATE_KEY; 14560


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

CK_ULONG hssLevels = 123; 14563

CK_ULONG lmsTypes[] = {123,...}; 14564


CK_ULONG lmotsTypes[] = {123,...}; 14565

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









{CKA_EXTRACTABLE, &false, sizeof(true)}, 14575

{CKA_HSS_LEVELS, &hssLevels, sizeof(hssLevels)}, 14576

{CKA_HSS_LMS_TYPES, lmsTypes, sizeof(lmsTypes)}, 14577

{CKA_HSS_LMOTS_TYPES, lmotsTypes, sizeof(lmotsTypes)}, 14578


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

}; 14581

14582

CKA_SENSITIVE MUST be true, CKA_EXTRACTABLE MUST be false, and CKA_COPYABLE MUST 14583 be false for this key. 14584

6.65.4 HSS key pair generation 14585

The HSS key pair generation mechanism, denoted CKM_HSS_KEY_PAIR_GEN, is a key pair generation 14586

mechanism for HSS. 14587


The mechanism generates HSS public/private key pairs for the scheme specified by the 14589 CKA_HSS_LEVELS, CKA_HSS_LMS_TYPES, and CKA_HSS_LMOTS_TYPES attributes of the 14590

template for the private key. 14591

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_HSS_LEVELS, 14592 CKA_HSS_LMS_TYPE, CKA_HSS_LMOTS_TYPE, and CKA_VALUE attributes to the new public key 14593 and the CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE, and CKA_HSS_KEYS_REMAINING attributes 14594

to the new private key. 14595


are not used and must be set to 0. 14597

If the operation takes longer to complete than a timeout determined by the device, 14598 CKR_OPERATION_TIMEOUT will be returned. If this code is returned, the requestor may try the 14599 operation again. 14600

6.65.5 HSS without hashing 14601

The HSS without hashing mechanism, denoted CKM_HSS, is a mechanism for single-part signatures and 14602 verification for HSS. (This mechanism corresponds only to the part of LMS that processes the hash value, 14603 which may be of any length; it does not compute the hash value.) 14604



For the purposes of these mechanisms, an HSS signature is a byte string with length depending on 14606 CKA_HSS_LEVELS, CKA_HSS_LMS_TYPES, CKA_HSS_LMOTS_TYPES as described in the 14607

following table. 14608

Table 266268, HSS without hashing: Key and Data Length 14609


C_Sign1 HSS Private Key any 1296-74988

2

C_Verify1 HSS Public Key any, 1296-

749882

N/A


14610 2 4+(levels-1)*56+levels*(8+(36+32*p)+h*32)

where p has values (265, 133, 67, 34) for lmots type (W1, W2, W4, W8) and h is the number of levels in the LMS

14611 Merkle trees.

14612



If the number of signatures is exhausted, CKR_KEY_EXHAUSTED will be returned. 14615

6.65.2 HSS public key objects 14616

HSS public key objects (object class CKO_PUBLIC_KEY, key type CKK_HSS) hold HSS public keys. 14617

The following table defines the HSS public key object attributes, in addition to the common attributes 14618 defined for this object class: 14619

Table 264, HSS Public Key Object Attributes 14620


CKA_HSS_PARAMS1,3

Byte array DER-encoding of a Parameters value as

defined below.

CKA_VALUE1,4

Byte array 28+N bytes; a 4 byte integer in big-endian

order encoding levels, a 4 byte integer in

big-endian order encoding lm_type, a 4

byte integer in big-endian order encoding

lm_ots_type, a 16 byte generated string

(the Merkle tree identifier), an N byte

string (the Merkle tree root hash value)

- Refer to Table 11 for footnotes 14621

The CKA_HSS_PARAMS attribute value is known as the “HSS domain parameters” and is defined as a 14622 choice of one representation method (with the possibility of future additions, such as a NIST-prescribed 14623 oId) with the following syntax: 14624

14625

Parameters ::= CHOICE { -- only one possibility for now -- 14626

specifiedParams OCTET STRING 14627

} 14628

14629

specifiedParams is defined as a 17 byte struct encoding the HSS domain parameters with the following 14630 syntax: 14631

14632

typedef CK_ULONG CK_HSS_LEVELS; 14633

typedef CK_ULONG CK_LMS_TYPE; 14634

typedef CK_ULONG CK_LMOTS_TYPE; 14635


14636

typedef struct specifiedParams { 14637

CK_HSS_LEVELS levels; 14638

CK_LMS_TYPE lm_type[8]; 14639

CK_LMOTS_TYPE lm_ots_type[8]; 14640

} specifiedParams; 14641

14642

where levels is the number of levels in the scheme, the ith entry of the first levels entries in lm_type 14643 contains the encoding for the Merkle tree height of the ith level and the remaining entries are not used 14644 and should be set to 0, the ith entry of the first levels entries in lm_ots_type contains the encoding for the 14645 Winternitz parameter of the one-time-signature scheme of the ith level and the remaining entries are not 14646 used and should be set to 0. The encodings are defined as in [RFC 8554] and [NIST 802-208]: 14647

14648

The following values are valid for CK_LMOTS_TYPE. 14649

Table 265, CK_LMOTS_TYPE values 14650


CK_LMOTS_SHA256_N32_W1 0x00000001UL




CK_LMOTS_SHA256_N24_W1 TBD




CK_LMOTS_SHAKE_N32_W1 TBD








14651

The following values are valid for CK_LMS_TYPE. 14652

Table 266, CK_LMS_TYPE values 14653



CK_LMS_SHA256_M32_H5 0x00000005UL

CK_LMS_SHA256_M32_H10 0x00000006UL

CK_LMS_SHA256_M32_H15 0x00000007UL

CK_LMS_SHA256_M32_H20 0x00000008UL

CK_LMS_SHA256_M32_H25 0x00000009UL

CK_LMS_SHA256_M24_H5 TBD





CK_LMS_SHAKE_M32_H5 TBD










14654

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

14656

CK_OBJECT_CLASS keyClass = CKO_PUBLIC_KEY; 14657


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

CK_BYTE hssParams[] = {...}; 14660

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



14664






{CKA_HSS_PARAMS, &hssParams, sizeof(hssParams)}, 14670


{CKA_VERIFY, &true, sizeof(true)} 14672

}; 14673

6.65.3 HSS private key objects 14674

HSS private key objects (object class CKO_PRIVATE_KEY, key type CKK_HSS) hold HSS private keys. 14675


The following table defines the HSS private key object attributes, in addition to the common attributes 14676 defined for this object class: 14677

14678

Table 267, HSS Private Key Object Attributes 14679


CKA_HSS_PARAMS1,4,6

Byte array DER-encoding of a Parameters value

as defined below.

CKA_VALUE1,4,6,7

Byte array Vendor defined, must include state

information.

Note that exporting this value is

dangerous as it would allow key reuse.

- Refer to Table 11 for footnotes 14680

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

14682

CK_OBJECT_CLASS keyClass = CKO_PRIVATE_KEY; 14683


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

CK_BYTE hssParams[] = {...}; 14686

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









{CKA_EXTRACTABLE, &false, sizeof(true)}, 14696

{CKA_HSS_PARAMS, hssParams, sizeof(hssParams)}, 14697


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

}; 14700

14701

CKA_SENSITIVE MUST be true and CKA_EXTRACTABLE MUST be false for this key. 14702

6.65.4 HSS key pair generation 14703

The HSS key pair generation mechanism, denoted CKM_HSS_KEY_PAIR_GEN, is a key pair generation 14704

mechanism for HSS. 14705


The mechanism generates HSS public/private key pairs with levels, lm_type and lm_ots type, as specified 14707 in the CKA_HSS_PARAMS attribute of the template for the public key. 14708

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new 14709 public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE, and CKA_HSS_PARAMS attributes 14710

to the new private key. 14711




If the operation takes longer to complete than a timeout determined by the device, 14714 CKR_OPERATION_TIMEOUT will be returned. If this code is returned, the requestor may try the 14715 operation again. 14716

14717

6.65.5 HSS without hashing 14718

The HSS without hashing mechanism, denoted CKM_HSS, is a mechanism for single-part signatures and 14719 verification for HSS. (This mechanism corresponds only to the part of LMS that processes the hash value, 14720 which may be of any length; it does not compute the hash value.) 14721


For the purposes of these mechanisms, an HSS signature is a byte string with length depending on 14723 levels, lm_type, and lm_ots_type as described in the following table. 14724

Table 268, HSS without hashing: Key and Data Length 14725


C_Sign1 HSS Private Key any 1296-74988

2

C_Verify1 HSS Public Key any, 1296-

749882

N/A


14726 2 4+(levels-1)*56+levels*(8+(36+32*p)+h*32)

where p has values (265, 133, 67, 34) for lmots type (W1, W2, W4, W8) and h is the number of levels in the LMS

14727 Merkle trees.

14728

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure 14729 are not used and must be set to 0. 14730

If the number of signatures is exhausted, CKR_KEY_EXHAUSTED will be returned. 14731


7 PKCS #11 Implementation Conformance 14732

7.1 PKCS#11 Consumer Implementation Conformance 14733

An implementation is a conforming PKCS#11 Consumer if the implementation meets the conditions 14734 specified in one or more consumer profiles specified in [PKCS11-Prof]. 14735

A PKCS#11 consumer implementation SHALL be a conforming PKCS#11 Consumer. 14736

If a PKCS#11 consumer implementation claims support for a particular consumer profile, then the 14737 implementation SHALL conform to all normative statements within the clauses specified for that profile 14738 and for any subclauses to each of those clauses. 14739

7.2 PKCS#11 Provider Implementation Conformance 14740

An implementation is a conforming PKCS#11 Provider if the implementation meets the conditions 14741 specified in one or more provider profiles specified in [PKCS11-Prof]. 14742

A PKCS#11 provider implementation SHALL be a conforming PKCS#11 Provider. 14743


Appendix A. Acknowledgments 14744

The following individuals have participated in the creation of this specification and are gratefully 14745 acknowledged: 14746

Participants: 14747

<TBA> 14748


Appendix B. Manifest constants 14749

The definitions for manifest constants specified in this document can be found in the following normative 14750 computer language definition files: 14751

TBA 14752


Appendix C. Revision History 14753

14754

Revision Date Editor Changes Made

WD01 02 December 2020

Dieter Bong & Tony Cox

- Merged Base Specification & Current Mechanisms forming new “PKCS#11 Specification v3.1”

- Added CKA_DERIVE_TEMPLATE

WD02 04 December 2020

Dieter Bong & Tony Cox

- Removed section 4.9.1 (covered in 6.1.3)

WD03 4 March 2021 Dieter Bong & Tony Cox

- Section 6.3.8 2nd

paragraph replace “Edwards” by “Montgomery”

- Revised Note in § 5.2

WD04 1 June 2021 Daniel Minder & Dieter Bong

- Fixed several references and typos

- Moved CKM_SHA224_RSA_PKCS and CKM_SHA224_RSA_PKCS_PSS from table 137 to table 32

- Fixed the typo and added the wording wrt. CKA_VALUE_LEN in sections 6.64.2 and 6.64.6

- Section 4.9 Private key objects: replaced “<this version>” by “PKCS #11 V2.40”

- Section 6.65 updated to HSS proposal dd. 12 May 2021

- Section 6.3: deprecation notice for CKM_ECDH_AES_KEY_WRAP

14755

Documents

PKCS #11 Base Specification Version 3