PKCS #11 Cryptographic Token Interface Current Mechanisms Specification Version 3.0
Committee Specification 01
19 December 2019
This stage:
https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/cs01/pkcs11currv3.0cs01.docx (Authoritative)
https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/cs01/pkcs11currv3.0cs01.html
https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/cs01/pkcs11currv3.0cs01.pdf
Previous stage:
https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/csprd01/pkcs11currv3.0csprd01.docx (Authoritative)
https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/csprd01/pkcs11currv3.0csprd01.html
https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/csprd01/pkcs11currv3.0csprd01.pdf
Latest stage:
https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/pkcs11currv3.0.docx (Authoritative)
https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/pkcs11currv3.0.html
https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/pkcs11currv3.0.pdf
Technical Committee:
Chairs:
Tony Cox (tony.cox@cryptsoft.com), Cryptsoft Pty Ltd
Robert Relyea (rrelyea@redhat.com), Red Hat
Editors:
Chris Zimman (chris@wmpp.com), Individual
Dieter Bong (dieter.bong@utimaco.com), Utimaco IS GmbH
This prose specification is one component of a Work Product that also includes:
This specification replaces or supersedes:
This specification is related to:
Abstract:
This document defines data types, functions and other basic components of the PKCS #11 Cryptoki interface.
Status:
This document was last revised or approved by the OASIS PKCS 11 TC on the above date. The level of approval is also listed above. Check the "Latest stage" location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasisopen.org/committees/tc_home.php?wg_abbrev=pkcs11#technical.
TC members should send comments on this document to the TC's email list. Others should send comments to the TC's public comment list, after subscribing to it by following the instructions at the "Send A Comment" button on the TC's web page at https://www.oasisopen.org/committees/pkcs11/.
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.oasisopen.org/committees/pkcs11/ipr.php).
Note that any machinereadable 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.
Citation format:
When referencing this specification the following citation format should be used:
[PKCS11Currentv3.0]
PKCS #11 Cryptographic Token Interface Current Mechanisms Specification Version 3.0. Edited by Chris Zimman and Dieter Bong. 19 December 2019. OASIS Committee Specification 01. https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/cs01/pkcs11currv3.0cs01.html. Latest stage: https://docs.oasisopen.org/pkcs11/pkcs11curr/v3.0/pkcs11currv3.0.html.
Notices
Copyright © OASIS Open 2019. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasisopen.org/policiesguidelines/trademark for above guidance.
Table of Contents
2.1.4 PKCS #1 RSA key pair generation
2.1.5 X9.31 RSA key pair generation
2.1.7 PKCS #1 RSA OAEP mechanism parameters
2.1.9 PKCS #1 RSA PSS mechanism parameters
2.1.15 PKCS #1 v1.5 RSA signature with SHA224
2.1.16 PKCS #1 RSA PSS signature with SHA224
2.1.17 PKCS #1 RSA PSS signature with SHA1, SHA256, SHA384 or SHA512
2.1.18 PKCS #1 v1.5 RSA signature with SHA3
2.1.19 PKCS #1 RSA PSS signature with SHA3
2.1.20 ANSI X9.31 RSA signature with SHA1
2.1.21 TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA
2.1.22 TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP
2.1.24 RSA AES KEY WRAP mechanism parameters
2.2.5 DSA domain parameter objects
2.2.7 DSA domain parameter generation
2.2.8 DSA probabilistic domain parameter generation
2.2.9 DSA ShaweTaylor domain parameter generation
2.2.10 DSA base domain parameter generation
2.3.3 ECDSA public key objects
2.3.4 Elliptic curve private key objects
2.3.5 Edwards Elliptic curve public key objects
2.3.6 Edwards Elliptic curve private key objects
2.3.7 Montgomery Elliptic curve public key objects
2.3.8 Montgomery Elliptic curve private key objects
2.3.9 Elliptic curve key pair generation
2.3.10 Edwards Elliptic curve key pair generation
2.3.11 Montgomery Elliptic curve key pair generation
2.3.16 EC mechanism parameters
2.3.17 Elliptic curve DiffieHellman key derivation
2.3.18 Elliptic curve DiffieHellman with cofactor key derivation
2.3.19 Elliptic curve MenezesQuVanstone key derivation
2.3.21 ECDH AES KEY WRAP mechanism parameters
2.4.2 DiffieHellman public key objects
2.4.3 X9.42 DiffieHellman public key objects
2.4.4 DiffieHellman private key objects
2.4.5 X9.42 DiffieHellman private key objects
2.4.6 DiffieHellman domain parameter objects
2.4.7 X9.42 DiffieHellman domain parameters objects
2.4.8 PKCS #3 DiffieHellman key pair generation
2.4.9 PKCS #3 DiffieHellman domain parameter generation
2.4.10 PKCS #3 DiffieHellman key derivation
2.4.11 X9.42 DiffieHellman mechanism parameters
2.4.12 X9.42 DiffieHellman key pair generation
2.4.13 X9.42 DiffieHellman domain parameter generation
2.4.14 X9.42 DiffieHellman key derivation
2.4.15 X9.42 DiffieHellman hybrid key derivation
2.4.16 X9.42 DiffieHellman MenezesQuVanstone key derivation
2.5 Extended Triple DiffieHellman (x3dh)
2.5.2 Extended Triple DiffieHellman key objects
2.5.3 Initiating an Extended Triple DiffieHellman key exchange
2.5.4 Responding to an Extended Triple DiffieHellman key exchange
2.5.5 Extended Triple DiffieHellman parameters
2.6.2 Double Ratchet secret key objects
2.6.3 Double Ratchet key derivation
2.6.4 Double Ratchet Encryption mechanism
2.6.5 Double Ratchet parameters
2.7 Wrapping/unwrapping private keys
2.8.2 Generic secret key objects
2.8.3 Generic secret key generation
2.9.1 General block cipher mechanism parameters
2.10.6 AESCBC with PKCS padding
2.11.2 AES with Counter mechanism parameters
2.11.3 AES with Counter Encryption / Decryption
2.12 AES CBC with Cipher Text Stealing CTS
2.12.2 AES CTS mechanism parameters
2.13 Additional AES Mechanisms
2.13.2 AESGCM Authenticated Encryption / Decryption
2.13.3 AESCCM authenticated Encryption / Decryption
2.13.5 AES GCM and CCM Mechanism parameters
2.14.3 Generallength AESCMAC
2.15.2 AESXTS secret key objects
2.16.2 AES Key Wrap Mechanism parameters
2.17 Key derivation by data encryption – DES & AES
2.18 Double and Triplelength DES
2.18.2 DES2 secret key objects
2.18.3 DES3 secret key objects
2.18.4 Doublelength DES key generation
2.18.5 Triplelength DES Order of Operations
2.18.6 Triplelength DES in CBC Mode
2.18.7 DES and Triple length DES in OFB Mode
2.18.8 DES and Triple length DES in CFB Mode
2.19 Double and Triplelength DES CMAC
2.19.3 Generallength DES3MAC
2.20.3 Generallength SHA1HMAC
2.20.6 SHA1 HMAC key generation
2.21.3 Generallength SHA224HMAC
2.21.6 SHA224 HMAC key generation
2.22.3 Generallength SHA256HMAC
2.22.6 SHA256 HMAC key generation
2.23.3 Generallength SHA384HMAC
2.23.6 SHA384 HMAC key generation
2.24.3 Generallength SHA512HMAC
2.24.6 SHA512 HMAC key generation
2.25.3 Generallength SHA512/224HMAC
2.25.5 SHA512/224 key derivation
2.25.6 SHA512/224 HMAC key generation
2.26.3 Generallength SHA512/256HMAC
2.26.5 SHA512/256 key derivation
2.26.6 SHA512/256 HMAC key generation
2.27.3 Generallength SHA512/tHMAC
2.27.5 SHA512/t key derivation
2.27.6 SHA512/t HMAC key generation
2.28.3 Generallength SHA3224HMAC
2.28.5 SHA3224 key derivation
2.28.6 SHA3224 HMAC key generation
2.29.3 Generallength SHA3256HMAC
2.29.5 SHA3256 key derivation
2.29.6 SHA3256 HMAC key generation
2.30.3 Generallength SHA3384HMAC
2.30.5 SHA3384 key derivation
2.30.6 SHA3384 HMAC key generation
2.31.3 Generallength SHA3512HMAC
2.31.5 SHA3512 key derivation
2.31.6 SHA3512 HMAC key generation
2.33.3 Generallength BLAKE2B160HMAC
2.33.5 BLAKE2B160 key derivation
2.33.6 BLAKE2B160 HMAC key generation
2.34.3 Generallength BLAKE2B256HMAC
2.34.5 BLAKE2B256 key derivation
2.34.6 BLAKE2B256 HMAC key generation
2.35.3 Generallength BLAKE2B384HMAC
2.35.5 BLAKE2B384 key derivation
2.35.6 BLAKE2B384 HMAC key generation
2.36.3 Generallength BLAKE2B512HMAC
2.36.5 BLAKE2B512 key derivation
2.36.6 BLAKE2B512 HMAC key generation
2.37 PKCS #5 and PKCS #5style passwordbased encryption (PBE)
2.37.2 Passwordbased encryption/authentication mechanism parameters
2.37.3 PKCS #5 PBKDF2 key generation mechanism parameters
2.37.4 PKCS #5 PBKD2 key generation
2.38 PKCS #12 passwordbased encryption/authentication mechanisms
2.38.1 SHA1PBE for 3key tripleDESCBC
2.38.2 SHA1PBE for 2key tripleDESCBC
2.38.3 SHA1PBA for SHA1HMAC
2.39.2 SSL mechanism parameters
2.39.3 Premaster key generation
2.39.5 Master key derivation for DiffieHellman
2.39.8 SHA1 MACing in SSL 3.0
2.40.2 TLS 1.2 mechanism parameters
2.40.5 Master key derivation for DiffieHellman
2.40.7 CKM_TLS12_KEY_SAFE_DERIVE
2.40.8 Generic Key Derivation using the TLS PRF
2.40.9 Generic Key Derivation using the TLS12 PRF
2.41.2 WTLS mechanism parameters
2.41.3 Pre master secret key generation for RSA key exchange suite
2.41.4 Master secret key derivation
2.41.5 Master secret key derivation for DiffieHellman and Elliptic Curve Cryptography
2.41.6 WTLS PRF (pseudorandom function)
2.41.7 Server Key and MAC derivation
2.41.8 Client key and MAC derivation
2.42 SP 800108 Key Derivation
2.42.5 Double Pipeline Mode KDF
2.42.6 Deriving Additional Keys
2.42.7 Key Derivation Attribute Rules
2.42.8 Constructing PRF Input Data
2.42.8.1 Sample Counter Mode KDF
2.42.8.2 Sample SCP03 Counter Mode KDF
2.42.8.3 Sample Feedback Mode KDF
2.42.8.4 Sample DoublePipeline Mode KDF
2.43 Miscellaneous simple key derivation mechanisms
2.43.2 Parameters for miscellaneous simple key derivation mechanisms
2.43.3 Concatenation of a base key and another key
2.43.4 Concatenation of a base key and data
2.43.5 Concatenation of data and a base key
2.43.6 XORing of a key and data
2.43.7 Extraction of one key from another key
2.44.2 CMS Signature Mechanism Objects
2.44.3 CMS mechanism parameters
2.45.2 BLOWFISH secret key objects
2.45.3 Blowfish key generation
2.45.5 BlowfishCBC with PKCS padding
2.46.2 Twofish secret key objects
2.46.5 TwofishCBC with PKCS padding
2.47.2 Camellia secret key objects
2.47.3 Camellia key generation
2.47.6 CamelliaCBC with PKCS padding
2.47.7 CAMELLIA with Counter mechanism parameters
2.47.8 Generallength CamelliaMAC
2.48 Key derivation by data encryption  Camellia
2.49.2 Aria secret key objects
2.49.6 ARIACBC with PKCS padding
2.49.7 Generallength ARIAMAC
2.50 Key derivation by data encryption  ARIA
2.51.2 SEED secret key objects
2.51.6 SEEDCBC with PKCS padding
2.51.7 Generallength SEEDMAC
2.52 Key derivation by data encryption  SEED
2.53.2 Case 1: Generation of OTP values
2.53.3 Case 2: Verification of provided OTP values
2.53.4 Case 3: Generation of OTP keys
2.53.6 OTPrelated notifications
2.53.7.1 OTP mechanism parameters
2.53.8.1 RSA SecurID secret key objects
2.53.8.2 RSA SecurID key generation
2.53.8.3 SecurID OTP generation and validation
2.53.9.1 OATH HOTP secret key objects
2.53.9.3 HOTP OTP generation and validation
2.53.10.1 ACTI secret key objects
2.53.10.3 ACTI OTP generation and validation
2.54.1 Principles of Operation
2.54.4 CTKIP Mechanism parameters
2.54.6 CTKIP key wrap and key unwrap
2.54.7 CTKIP signature generation
2.55.2 GOST 2814789 secret key objects
2.55.3 GOST 2814789 domain parameter objects
2.55.4 GOST 2814789 key generation
2.55.6 GOST 2814789 encryption mode except ECB
2.55.8 GOST 2814789 keys wrapping/unwrapping with GOST 2814789.
2.56.2 GOST R 34.1194 domain parameter objects
2.57.2 GOST R 34.102001 public key objects
2.57.3 GOST R 34.102001 private key objects
2.57.4 GOST R 34.102001 domain parameter objects
2.57.5 GOST R 34.102001 mechanism parameters
2.57.6 GOST R 34.102001 key pair generation
2.57.7 GOST R 34.102001 without hashing
2.57.8 GOST R 34.102001 with GOST R 34.1194
2.57.9 GOST 2814789 keys wrapping/unwrapping with GOST R 34.102001
2.57.10 Common key derivation with assistance of GOST R 34.102001 keys
2.58.2 ChaCha20 secret key objects
2.58.3 ChaCha20 mechanism parameters
2.58.4 ChaCha20 key generation
2.59.2 Salsa20 secret key objects
2.59.3 Salsa20 mechanism parameters
2.60.2 Poly1305 secret key objects
2.61 Chacha20/Poly1305 and Salsa20/Poly1305 Authenticated Encryption / Decryption
2.61.3 ChaCha20/Poly1305 and Salsa20/Poly1305 Mechanism parameters.
2.62.2 HKDF mechanism parameters
2.63.2 CKM_NULL mechanism parameters
3 PKCS #11 Implementation Conformance
Appendix B. Manifest Constants
This document defines mechanisms that are anticipated to be used with the current version of PKCS #11.
All text is normative unless otherwise labeled.
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.oasisopen.org/committees/pkcs11/ipr.php).
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119]
For the purposes of this standard, the following definitions apply. Please refer to the [PKCS#11Base] for further definitions:
AES Advanced Encryption Standard, as defined in FIPS PUB 197.
CAMELLIA The Camellia encryption algorithm, as defined in RFC 3713.
BLOWFISH The Blowfish Encryption Algorithm of Bruce Schneier, www.schneier.com.
CBC CipherBlock Chaining mode, as defined in FIPS PUB 81.
CDMF Commercial Data Masking Facility, a block encipherment method specified by International Business Machines Corporation and based on DES.
CMAC Cipherbased Message Authenticate Code as defined in [NIST sp80038b] and [RFC 4493].
CMS Cryptographic Message Syntax (see RFC 2630)
CTKIP Cryptographic Token Key Initialization Protocol (as defined in [CTKIP])
DES Data Encryption Standard, as defined in FIPS PUB 463.
DSA Digital Signature Algorithm, as defined in FIPS PUB 1862.
EC Elliptic Curve
ECB Electronic Codebook mode, as defined in FIPS PUB 81.
ECDH Elliptic Curve DiffieHellman.
ECDSA Elliptic Curve DSA, as in ANSI X9.62.
ECMQV Elliptic Curve MenezesQuVanstone
GOST 2814789 The encryption algorithm, as defined in Part 2 [GOST 2814789] and [RFC 4357] [RFC 4490], and RFC [4491].
GOST R 34.1194 Hash algorithm, as defined in [GOST R 34.1194] and [RFC 4357], [RFC 4490], and [RFC 4491].
GOST R 34.102001 The digital signature algorithm, as defined in [GOST R 34.102001] and [RFC 4357], [RFC 4490], and [RFC 4491].
IV Initialization Vector.
MAC Message Authentication Code.
MQV MenezesQuVanstone
OAEP Optimal Asymmetric Encryption Padding for RSA.
PKCS PublicKey Cryptography Standards.
PRF Pseudo random function.
PTD Personal Trusted Device, as defined in MeTPTD
RSA The RSA publickey cryptosystem.
SHA1 The (revised) Secure Hash Algorithm with a 160bit message digest, as defined in FIPS PUB 1802.
SHA224 The Secure Hash Algorithm with a 224bit message digest, as defined in RFC 3874. Also defined in FIPS PUB 1802 with Change Notice 1.
SHA256 The Secure Hash Algorithm with a 256bit message digest, as defined in FIPS PUB 1802.
SHA384 The Secure Hash Algorithm with a 384bit message digest, as defined in FIPS PUB 1802.
SHA512 The Secure Hash Algorithm with a 512bit message digest, as defined in FIPS PUB 1802.
SSL The Secure Sockets Layer 3.0 protocol.
SO A Security Officer user.
TLS Transport Layer Security.
WIM Wireless Identification Module.
WTLS Wireless Transport Layer Security.
[ARIA] National Security
Research Institute, Korea, “Block Cipher Algorithm ARIA”,
URL: http://tools.ietf.org/html/rfc5794
[BLOWFISH] B. Schneier. Description of a New VariableLength
Key, 64Bit Block Cipher (Blowfish), December 1993.
URL: https://www.schneier.com/paperblowfishfse.html
[CAMELLIA] M.
Matsui, J. Nakajima, S. Moriai. A Description of the Camellia Encryption
Algorithm, April 2004.
URL: http://www.ietf.org/rfc/rfc3713.txt
[CDMF] Johnson, D.B The Commercial Data
Masking Facility (CDMF) data privacy algorithm, March 1994.
URL: http://ieeexplore.ieee.org/xpl/articleDetails.jsp?arnumber=5389557
[CHACHA] D. Bernstein, ChaCha, a variant of
Salsa20, Jan 2008.
URL: http://cr.yp.to/chacha/chacha20080128.pdf
[DH] W. Diffie, M. Hellman. New
Directions in Cryptography. Nov, 1976.
URL: http://wwwee.stanford.edu/~hellman/publications/24.pdf
[FIPS PUB 81] NIST. FIPS 81: DES Modes of Operation. December 1980.
URL: http://csrc.nist.gov/publications/fips/fips81/fips81.htm
[FIPS PUB 1864] NIST.
FIPS 1864: Digital Signature Standard. July 2013.
URL: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.1864.pdf
[FIPS PUB 197] NIST.
FIPS 197: Advanced Encryption Standard. November 26, 2001.
URL: http://csrc.nist.gov/publications/fips/fips197/fips197.pdf
[FIPS SP 80056A] NIST. Special Publication 80056A
Revision 2: Recommendation for PairWise Key Establishment Schemes
Using Discrete Logarithm Cryptography, May 2013.
URL: http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.80056Ar2.pdf
[FIPS SP 800108] NIST. Special Publication 800108
(Revised): Recommendation for Key Derivation Using Pseudorandom Functions,
October 2009.
URL: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800108.pdf
[GOST] V. Dolmatov, A. Degtyarev. GOST
R. 34.112012: Hash Function. August 2013.
URL: http://tools.ietf.org/html/rfc6986
[MD2] B. Kaliski. RSA Laboratories. The MD2 MessageDigest
Algorithm. April, 1992.
URL: http://tools.ietf.org/html/rfc1319
[MD5] RSA Data Security. R. Rivest.
The MD5 MessageDigest Algorithm. April, 1992.
URL: http://tools.ietf.org/html/rfc1319
[OAEP] M. Bellare, P. Rogaway. Optimal
Asymmetric Encryption – How to Encrypt with RSA. Nov 19, 1995.
URL: http://cseweb.ucsd.edu/users/mihir/papers/oae.pdf
[PKCS11Base] PKCS #11 Cryptographic Token Interface Base Specification Version 3.0. Edited by Chris Zimman and Dieter Bong. Latest version. https://docs.oasisopen.org/pkcs11/pkcs11base/v3.0/pkcs11basev3.0.html.
[RFC2119] Bradner, S.,
“Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119,
March 1997.
URL: http://www.ietf.org/rfc/rfc2119.txt.
[RIPEMD] H. Dobbertin, A.
Bosselaers, B. Preneel. The hash function RIPEMD160, Feb 13, 2012.
URL: http://homes.esat.kuleuven.be/~bosselae/ripemd160.html
[SALSA] D. Bernstein, ChaCha, a variant of
Salsa20, Jan 2008.
URL: http://cr.yp.to/chacha/chacha20080128.pdf
[SEED] KISA. SEED 128
Algorithm Specification. Sep 2003.
URL: http://seed.kisa.or.kr/html/egovframework/iwt/ds/ko/ref/%5B2%5D_SEED+128_Specification_english_M.pdf
[SHA1] NIST. FIPS 1804:
Secure Hash Standard. March 2012.
URL: http://csrc.nist.gov/publications/fips/fips1804/fips1804.pdf
[SHA2] NIST. FIPS 1804: Secure Hash Standard. March 2012.
URL: http://csrc.nist.gov/publications/fips/fips1804/fips1804.pdf
[TWOFISH] B. Schneier, J. Kelsey,
D. Whiting, C. Hall, N. Ferguson. Twofish: A 128Bit Block Cipher. June 15,
1998.
URL: https://www.schneier.com/papertwofishpaper.pdf
[CAP1.2] Common
Alerting Protocol Version 1.2. 01 July 2010. OASIS Standard.
URL: http://docs.oasisopen.org/emergency/cap/v1.2/CAPv1.2os.html
[AES KEYWRAP] National Institute of Standards and Technology, NIST Special Publication 80038F, Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping, December 2012, http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.80038F.pdf
[ANSI C] ANSI/ISO. American National Standard for Programming Languages – C. 1990.
[ANSI X9.31] Accredited Standards Committee X9. Digital Signatures Using Reversible Public Key Cryptography for the Financial Services Industry (rDSA). 1998.
[ANSI X9.42] Accredited Standards Committee X9. Public Key Cryptography for the Financial Services Industry: Agreement of Symmetric Keys Using Discrete Logarithm Cryptography. 2003.
[ANSI X9.62] Accredited Standards Committee X9. Public Key Cryptography for the Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA). 1998.
[ANSI X9.63] Accredited Standards Committee X9.
Public Key Cryptography for the Financial Services Industry: Key Agreement and
Key Transport Using Elliptic Curve Cryptography. 2001.
URL: http://webstore.ansi.org/RecordDetail.aspx?sku=X9.632011
[BRAINPOOL] ECC Brainpool Standard Curves and Curve Generation, v1.0, 19.10.2005
URL: http://www.eccbrainpool.org
[CTKIP] RSA Laboratories. Cryptographic Token Key
Initialization Protocol. Version 1.0, December 2005.
URL: ftp://ftp.rsasecurity.com/pub/otps/ctkip/ctkipv10.pdf.
[CC/PP] CCPPSTRUCTVOCAB, G. Klyne, F.
Reynolds, C. , H. Ohto, J. Hjelm, M. H. Butler, L. Tran, Editors, W3C
Recommendation, 15 January 2004,
URL: http://www.w3.org/TR/2004/RECCCPPstructvocab20040115/
Latest version available at http://www.w3.org/TR/CCPPstructvocab/
[LEGIFRANCE] Avis relatif aux paramètres de courbes
elliptiques définis par l'Etat français (Publication of elliptic curve
parameters by the French state)
URL: https://www.legifrance.gouv.fr/affichTexte.do?cidTexte=JORFTEXT000024668816
[NIST AES CTS] National Institute of Standards and
Technology, Addendum to NIST Special Publication 80038A, “Recommendation for
Block Cipher Modes of Operation: Three Variants of Ciphertext Stealing for CBC
Mode”
URL: http://csrc.nist.gov/publications/nistpubs/80038a/addendumtonist_sp80038A.pdf
[PKCS11UG] PKCS #11 Cryptographic Token Interface Usage Guide Version 2.41. Edited by John Leiseboer and Robert Griffin. version: http://docs.oasisopen.org/pkcs11/pkcs11ug/v2.40/pkcs11ugv2.40.html.
[RFC 2865] Rigney
et al, “Remote Authentication Dial In User Service (RADIUS)”, IETF RFC2865,
June 2000.
URL: http://www.ietf.org/rfc/rfc2865.txt.
[RFC 3686] Housley,
“Using Advanced Encryption Standard (AES) Counter Mode With IPsec Encapsulating
Security Payload (ESP),” IETF RFC 3686, January 2004.
URL: http://www.ietf.org/rfc/rfc3686.txt.
[RFC 3717] Matsui, et
al, ”A Description of the Camellia Encryption Algorithm,” IETF RFC 3717, April
2004.
URL: http://www.ietf.org/rfc/rfc3713.txt.
[RFC 3610] Whiting, D.,
Housley, R., and N. Ferguson, “Counter with CBCMAC (CCM)", IETF RFC 3610,
September 2003.
URL: http://www.ietf.org/rfc/rfc3610.txt
[RFC 3874] Smit et al, “A 224bit Oneway Hash
Function: SHA224,” IETF RFC 3874, June 2004.
URL: http://www.ietf.org/rfc/rfc3874.txt.
[RFC 3748] Aboba et al,
“Extensible Authentication Protocol (EAP)”, IETF RFC 3748, June 2004.
URL: http://www.ietf.org/rfc/rfc3748.txt.
[RFC
4269] South Korean Information Security Agency (KISA) “The SEED
Encryption Algorithm”, December 2005.
URL: ftp://ftp.rfceditor.org/innotes/rfc4269.txt
[RFC 4309] Housley, R., “Using Advanced
Encryption Standard (AES) CCM Mode with IPsec Encapsulating Security Payload
(ESP),” IETF RFC 4309, December 2005.
URL: http://www.ietf.org/rfc/rfc4309.txt
[RFC 4357] V.
Popov, I. Kurepkin, S. Leontiev “Additional Cryptographic Algorithms for Use
with GOST 2814789, GOST R 34.1094, GOST R 34.102001, and GOST R 34.1194
Algorithms”, January 2006.
URL: http://www.ietf.org/rfc/rfc4357.txt
[RFC 4490] S. Leontiev, Ed. G.
Chudov, Ed. “Using the GOST 2814789, GOST R 34.1194,GOST R 34.1094,
and GOST R 34.102001 Algorithms with Cryptographic Message Syntax (CMS)”, May
2006.
URL: http://www.ietf.org/rfc/rfc4490.txt
[RFC
4491] S. Leontiev, Ed., D. Shefanovski, Ed., “Using the GOST R
34.1094, GOST R 34.102001, and GOST R 34.1194 Algorithms with the Internet
X.509 Public Key Infrastructure Certificate and CRL Profile”, May 2006.
URL: http://www.ietf.org/rfc/rfc4491.txt
[RFC 4493] J.
Song et al. RFC 4493: The AESCMAC Algorithm. June 2006.
URL: http://www.ietf.org/rfc/rfc4493.txt
[RFC 5705] Rescorla,
E., “The Keying Material Exporters for Transport Layer Security (TLS)”, RFC
5705, March 2010.
URL: http://www.ietf.org/rfc/rfc5705.txt
[RFC 5869] H.
Krawczyk, P. Eronen, “HMACbased
ExtractandExpand Key Derivation Function (HKDF)“, May 2010
URL: http://www.ietf.org/rfc/rfc5869.txt
[RFC 7539] Y
Nir, A. Langley. RFC 7539: ChaCha20 and Poly1305 for IETF Protocols, May
2015
URL: https://tools.ietf.org/rfc/rfc7539.txt
[RFC 7748] Aboba et al, “Elliptic Curves for
Security”, IETF RFC 7748, January 2016
URL: https://tools.ietf.org/html/rfc7748
[RFC 8032] Aboba et al, “EdwardsCurve Digital
Signature Algorithm (EdDSA)”, IETF RFC 8032, January 2017
URL: https://tools.ietf.org/html/rfc8032
[SEC 1] Standards for Efficient Cryptography Group (SECG). Standards for Efficient Cryptography (SEC) 1: Elliptic Curve Cryptography. Version 1.0, September 20, 2000.
[SEC 2] Standards for Efficient Cryptography Group (SECG). Standards for Efficient Cryptography (SEC) 2: Recommended Elliptic Curve Domain Parameters. Version 1.0, September 20, 2000.
[SIGNAL] The X3DH Key Agreement Protocol,
Revision 1, 20161104, Moxie Marlinspike, Trevor Perrin (editor)
URL: https://signal.org/docs/specifications/x3dh/
[TLS] [RFC2246] Dierks, T. and C.
Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999.
http://www.ietf.org/rfc/rfc2246.txt, superseded by [RFC4346] Dierks, T. and E.
Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.1",
RFC 4346, April 2006. http://www.ietf.org/rfc/rfc4346.txt, which was superseded
by [5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS)
Protocol Version 1.2", RFC 5246, August 2008.
URL: http://www.ietf.org/rfc/rfc5246.txt
[TLS12] [RFC5246] Dierks, T. and E.
Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2",
RFC 5246, August 2008.
URL: http://www.ietf.org/rfc/rfc5246.txt
[TLS13] [RFC8446] E. Rescorla, "The
Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, August 2018.
URL: http://www.ietf.org/rfc/rfc8446.txt
[WIM] WAP. Wireless Identity Module. —
WAP260WIM20010712a. July 2001.
URL: http://technical.openmobilealliance.org/tech/affiliates/LicenseAgreement.asp?DocName=/wap/wap260wim20010712a.pdf
[WPKI] Wireless Application Protocol:
Public Key Infrastructure Definition. — WAP217WPKI20010424a. April 2001.
URL: http://technical.openmobilealliance.org/tech/affiliates/LicenseAgreement.asp?DocName=/wap/wap217wpki20010424a.pdf
[WTLS] WAP. Wireless Transport Layer
Security Version — WAP261WTLS20010406a. April 2001.
URL: http://technical.openmobilealliance.org/tech/affiliates/LicenseAgreement.asp?DocName=/wap/wap261wtls20010406a.pdf
[XEDDSA] The XEdDSA and VXEdDSA Signature
Schemes  Revision 1, 20161020, Trevor Perrin (editor)
URL: https://signal.org/docs/specifications/xeddsa/
[X.500] ITUT. Information Technology — Open Systems Interconnection — The Directory: Overview of Concepts, Models and Services. February 2001. Identical to ISO/IEC 95941
[X.509] ITUT. Information Technology — Open Systems Interconnection — The Directory: Publickey and Attribute Certificate Frameworks. March 2000. Identical to ISO/IEC 95948
[X.680] ITUT. Information Technology — Abstract Syntax Notation One (ASN.1): Specification of Basic Notation. July 2002. Identical to ISO/IEC 88241
[X.690] ITUT. Information Technology — ASN.1 Encoding Rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER). July 2002. Identical to ISO/IEC 88251
A mechanism specifies precisely how a certain cryptographic process is to be performed. PKCS #11 implementations MAY use one of more mechanisms defined in this document.
The following table shows which Cryptoki mechanisms are supported by different cryptographic operations. For any particular token, of course, a particular operation may well support only a subset of the mechanisms listed. There is also no guarantee that a token which supports one mechanism for some operations supports any other mechanism for any other operation (or even supports that same mechanism for any other operation). For example, even if a token is able to create RSA digital signatures with the CKM_RSA_PKCS mechanism, it may or may not be the case that the same token can also perform RSA encryption with CKM_RSA_PKCS.
Each mechanism description is be preceded by a table, of the following format, mapping mechanisms to API functions.

Functions 

Mechanism 
Encrypt & Decrypt 
Sign & Verify 
SR & VR^{1} 
Digest 
Gen. Key/ Key Pair 
Wrap & Unwrap 
Derive 








^{1} SR = SignRecover, VR = VerifyRecover.
2 Singlepart operations only.
3 Mechanism can only be used for wrapping, not unwrapping.
The remainder of this section will present in detail the mechanisms supported by Cryptoki and the parameters which are supplied to them.
In general, if a mechanism makes no mention of the ulMinKeyLen and ulMaxKeyLen fields of the CK_MECHANISM_INFO structure, then those fields have no meaning for that particular mechanism.
Table 1, Mechanisms vs. Functions
This section defines the RSA key type “CKK_RSA” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of RSA key objects.
Mechanisms:
CKM_RSA_PKCS_KEY_PAIR_GEN
CKM_RSA_PKCS
CKM_RSA_9796
CKM_RSA_X_509
CKM_MD2_RSA_PKCS
CKM_MD5_RSA_PKCS
CKM_SHA1_RSA_PKCS
CKM_SHA224_RSA_PKCS
CKM_SHA256_RSA_PKCS
CKM_SHA384_RSA_PKCS
CKM_SHA512_RSA_PKCS
CKM_RIPEMD128_RSA_PKCS
CKM_RIPEMD160_RSA_PKCS
CKM_RSA_PKCS_OAEP
CKM_RSA_X9_31_KEY_PAIR_GEN
CKM_RSA_X9_31
CKM_SHA1_RSA_X9_31
CKM_RSA_PKCS_PSS
CKM_SHA1_RSA_PKCS_PSS
CKM_SHA224_RSA_PKCS_PSS
CKM_SHA256_RSA_PKCS_PSS
CKM_SHA512_RSA_PKCS_PSS
CKM_SHA384_RSA_PKCS_PSS
CKM_RSA_PKCS_TPM_1_1
CKM_RSA_PKCS_OAEP_TPM_1_1
CKM_RSA_AES_KEY_WRAP
CKM_SHA3_224_RSA_PKCS
CKM_SHA3_256_RSA_PKCS
CKM_SHA3_384_RSA_PKCS
CKM_SHA3_512_RSA_PKCS
CKM_SHA3_224_RSA_PKCS_PSS
CKM_SHA3_256_RSA_PKCS_PSS
CKM_SHA3_384_RSA_PKCS_PSS
CKM_SHA3_512_RSA_PKCS_PSS
RSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_RSA) hold RSA public keys. The following table defines the RSA public key object attributes, in addition to the common attributes defined for this object class:
Table 2, RSA Public Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_MODULUS^{1,4} 
Big integer 
Modulus n 
CKA_MODULUS_BITS^{2,3} 
CK_ULONG 
Length in bits of modulus n 
CKA_PUBLIC_EXPONENT^{1} 
Big integer 
Public exponent e 
^{ Refer to [PKCS11Base] table 11 for footnotes}
Depending on the token, there may be limits on the length of key components. See PKCS #1 for more information on RSA keys.
The following is a sample template for creating an RSA public key object:
CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_RSA;
CK_UTF8CHAR label[] = “An RSA public key object”;
CK_BYTE modulus[] = {...};
CK_BYTE exponent[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_WRAP, &true, sizeof(true)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_MODULUS, modulus, sizeof(modulus)},
{CKA_PUBLIC_EXPONENT, exponent, sizeof(exponent)}
};
RSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_RSA) hold RSA private keys. The following table defines the RSA private key object attributes, in addition to the common attributes defined for this object class:
Table 3, RSA Private Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_MODULUS^{1,4,6} 
Big integer 
Modulus n 
CKA_PUBLIC_EXPONENT^{4,6} 
Big integer 
Public exponent e 
CKA_PRIVATE_EXPONENT^{1,4,6,7} 
Big integer 
Private exponent d 
CKA_PRIME_1^{4,6,7} 
Big integer 
Prime p 
CKA_PRIME_2^{4,6,7} 
Big integer 
Prime q 
CKA_EXPONENT_1^{4,6,7} 
Big integer 
Private exponent d modulo p1 
CKA_EXPONENT_2^{4,6,7} 
Big integer 
Private exponent d modulo q1 
CKA_COEFFICIENT^{4,6,7} 
Big integer 
CRT coefficient q^{1} mod p 
^{ Refer to [PKCS11Base] table 11 for footnotes}
Depending on the token, there may be limits on the length of the key components. See PKCS #1 for more information on RSA keys.
Tokens vary in what they actually store for RSA private keys. Some tokens store all of the above attributes, which can assist in performing rapid RSA computations. Other tokens might store only the CKA_MODULUS and CKA_PRIVATE_EXPONENT values. Effective with version 2.40, tokens MUST also store CKA_PUBLIC_EXPONENT. This permits the retrieval of sufficient data to reconstitute the associated public key.
Because of this, Cryptoki is flexible in dealing with RSA private key objects. When a token generates an RSA private key, it stores whichever of the fields in Table 3 it keeps track of. Later, if an application asks for the values of the key’s various attributes, Cryptoki supplies values only for attributes whose values it can obtain (i.e., if Cryptoki is asked for the value of an attribute it cannot obtain, the request fails). Note that a Cryptoki implementation may or may not be able and/or willing to supply various attributes of RSA private keys which are not actually stored on the token. E.g., if a particular token stores values only for the CKA_PRIVATE_EXPONENT, CKA_PRIME_1, and CKA_PRIME_2 attributes, then Cryptoki is certainly able to report values for all the attributes above (since they can all be computed efficiently from these three values). However, a Cryptoki implementation may or may not actually do this extra computation. The only attributes from Table 3 for which a Cryptoki implementation is required to be able to return values are CKA_MODULUS and CKA_PRIVATE_EXPONENT.
If an RSA private key object is created on a token, and more attributes from Table 3 are supplied to the object creation call than are supported by the token, the extra attributes are likely to be thrown away. If an attempt is made to create an RSA private key object on a token with insufficient attributes for that particular token, then the object creation call fails and returns CKR_TEMPLATE_INCOMPLETE.
Note that when generating an RSA private key, there is no CKA_MODULUS_BITS attribute specified. This is because RSA private keys are only generated as part of an RSA key pair, and the CKA_MODULUS_BITS attribute for the pair is specified in the template for the RSA public key.
The following is a sample template for creating an RSA private key object:
CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_RSA;
CK_UTF8CHAR label[] = “An RSA private key object”;
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE modulus[] = {...};
CK_BYTE publicExponent[] = {...};
CK_BYTE privateExponent[] = {...};
CK_BYTE prime1[] = {...};
CK_BYTE prime2[] = {...};
CK_BYTE exponent1[] = {...};
CK_BYTE exponent2[] = {...};
CK_BYTE coefficient[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DECRYPT, &true, sizeof(true)},
{CKA_SIGN, &true, sizeof(true)},
{CKA_MODULUS, modulus, sizeof(modulus)},
{CKA_PUBLIC_EXPONENT, publicExponent, sizeof(publicExponent)},
{CKA_PRIVATE_EXPONENT, privateExponent, sizeof(privateExponent)},
{CKA_PRIME_1, prime1, sizeof(prime1)},
{CKA_PRIME_2, prime2, sizeof(prime2)},
{CKA_EXPONENT_1, exponent1, sizeof(exponent1)},
{CKA_EXPONENT_2, exponent2, sizeof(exponent2)},
{CKA_COEFFICIENT, coefficient, sizeof(coefficient)}
};
The PKCS #1 RSA key pair generation mechanism, denoted CKM_RSA_PKCS_KEY_PAIR_GEN, is a key pair generation mechanism based on the RSA publickey cryptosystem, as defined in PKCS #1.
It does not have a parameter.
The mechanism generates RSA public/private key pairs with a particular modulus length in bits and public exponent, as specified in the CKA_MODULUS_BITS and CKA_PUBLIC_EXPONENT attributes of the template for the public key. The CKA_PUBLIC_EXPONENT may be omitted in which case the mechanism shall supply the public exponent attribute using the default value of 0x10001 (65537). Specific implementations may use a random value or an alternative default if 0x10001 cannot be used by the token.
Note: Implementations strictly compliant with version 2.11 or prior versions may generate an error if this attribute is omitted from the template. Experience has shown that many implementations of 2.11 and prior did allow the CKA_PUBLIC_EXPONENT attribute to be omitted from the template, and behaved as described above. The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_MODULUS, and CKA_PUBLIC_EXPONENT attributes to the new public key. CKA_PUBLIC_EXPONENT will be copied from the template if supplied. CKR_TEMPLATE_INCONSISTENT shall be returned if the implementation cannot use the supplied exponent value. It contributes the CKA_CLASS and CKA_KEY_TYPE attributes to the new private key; it may also contribute some of the following attributes to the new private key: CKA_MODULUS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT_2, CKA_COEFFICIENT. Other attributes supported by the RSA public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
The X9.31 RSA key pair generation mechanism, denoted CKM_RSA_X9_31_KEY_PAIR_GEN, is a key pair generation mechanism based on the RSA publickey cryptosystem, as defined in X9.31.
It does not have a parameter.
The mechanism generates RSA public/private key pairs with a particular modulus length in bits and public exponent, as specified in the CKA_MODULUS_BITS and CKA_PUBLIC_EXPONENT attributes of the template for the public key.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_MODULUS, and CKA_PUBLIC_EXPONENT attributes to the new public key. It contributes the CKA_CLASS and CKA_KEY_TYPE attributes to the new private key; it may also contribute some of the following attributes to the new private key: CKA_MODULUS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT_2, CKA_COEFFICIENT. Other attributes supported by the RSA public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, or else are assigned default initial values. Unlike the CKM_RSA_PKCS_KEY_PAIR_GEN mechanism, this mechanism is guaranteed to generate p and q values, CKA_PRIME_1 and CKA_PRIME_2 respectively, that meet the strong primes requirement of X9.31.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
The PKCS #1 v1.5 RSA mechanism, denoted CKM_RSA_PKCS, is a multipurpose mechanism based on the RSA publickey cryptosystem and the block formats initially defined in PKCS #1 v1.5. It supports singlepart encryption and decryption; singlepart signatures and verification with and without message recovery; key wrapping; and key unwrapping. This mechanism corresponds only to the part of PKCS #1 v1.5 that involves RSA; it does not compute a message digest or a DigestInfo encoding as specified for the md2withRSAEncryption and md5withRSAEncryption algorithms in PKCS #1 v1.5 .
This mechanism does not have a parameter.
This mechanism can wrap and unwrap any secret key of appropriate length. Of course, a particular token may not be able to wrap/unwrap every appropriatelength secret key that it supports. For wrapping, the “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping. The mechanism does not wrap the key type or any other information about the key, except the key length; the application must convey these separately. In particular, the mechanism contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes to the recovered key during unwrapping; other attributes must be specified in the template.
Constraints on key types and the length of the data are summarized in the following table. For encryption, decryption, signatures and signature verification, the input and output data may begin at the same location in memory. In the table, k is the length in bytes of the RSA modulus.
Table 4, PKCS #1 v1.5 RSA: Key And Data Length
Function 
Key type 
Input length 
Output length 
Comments 
C_Encrypt^{1} 
RSA public key 
£ k11 
k 
block type 02 
C_Decrypt^{1} 
RSA private key 
k 
£ k11 
block type 02 
C_Sign^{1} 
RSA private key 
£ k11 
k 
block type 01 
C_SignRecover 
RSA private key 
£ k11 
k 
block type 01 
C_Verify^{1} 
RSA public key 
£ k11, k^{2} 
N/A 
block type 01 
C_VerifyRecover 
RSA public key 
k 
£ k11 
block type 01 
C_WrapKey 
RSA public key 
£ k11 
k 
block type 02 
C_UnwrapKey 
RSA private key 
k 
£ k11 
block type 02 
^{1} Singlepart operations only.
2 Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
¨ CK_RSA_PKCS_MGF_TYPE; CK_RSA_PKCS_MGF_TYPE_PTR
CK_RSA_PKCS_MGF_TYPE is used to indicate the Message Generation Function (MGF) applied to a message block when formatting a message block for the PKCS #1 OAEP encryption scheme or the PKCS #1 PSS signature scheme. It is defined as follows:
typedef CK_ULONG CK_RSA_PKCS_MGF_TYPE;
The following MGFs are defined in PKCS #1. The following table lists the defined functions.
Table 5, PKCS #1 Mask Generation Functions
Source Identifier 
Value 
CKG_MGF1_SHA1 
0x00000001UL 
CKG_MGF1_SHA224 
0x00000005UL 
CKG_MGF1_SHA256 
0x00000002UL 
CKG_MGF1_SHA384 
0x00000003UL 
CKG_MGF1_SHA512 
0x00000004UL 
CKG_MGF1_SHA3_224 
0x00000006UL 
CKG_MGF1_SHA3_256 
0x00000007UL 
CKG_MGF1_SHA3_384 
0x00000008UL 
CKG_MGF1_SHA3_512 
0x00000009UL 
CK_RSA_PKCS_MGF_TYPE_PTR is a pointer to a CK_RSA_PKCS_ MGF_TYPE.
¨ CK_RSA_PKCS_OAEP_SOURCE_TYPE; CK_RSA_PKCS_OAEP_SOURCE_TYPE_PTR
CK_RSA_PKCS_OAEP_SOURCE_TYPE is used to indicate the source of the encoding parameter when formatting a message block for the PKCS #1 OAEP encryption scheme. It is defined as follows:
typedef CK_ULONG CK_RSA_PKCS_OAEP_SOURCE_TYPE;
The following encoding parameter sources are defined in PKCS #1. The following table lists the defined sources along with the corresponding data type for the pSourceData field in the CK_RSA_PKCS_OAEP_PARAMS structure defined below.
Table 6, PKCS #1 RSA OAEP: Encoding parameter sources
Source Identifier 
Value 
Data Type 
CKZ_DATA_SPECIFIED 
0x00000001UL 
Array of CK_BYTE containing the value of the encoding parameter. If the parameter is empty, pSourceData must be NULL and ulSourceDataLen must be zero. 
CK_RSA_PKCS_OAEP_SOURCE_TYPE_PTR is a pointer to a CK_RSA_PKCS_OAEP_SOURCE_TYPE.
¨ CK_RSA_PKCS_OAEP_PARAMS; CK_RSA_PKCS_OAEP_PARAMS_PTR
CK_RSA_PKCS_OAEP_PARAMS is a structure that provides the parameters to the CKM_RSA_PKCS_OAEP mechanism. The structure is defined as follows:
typedef struct CK_RSA_PKCS_OAEP_PARAMS {
CK_MECHANISM_TYPE hashAlg;
CK_RSA_PKCS_MGF_TYPE mgf;
CK_RSA_PKCS_OAEP_SOURCE_TYPE source;
CK_VOID_PTR pSourceData;
CK_ULONG ulSourceDataLen;
} CK_RSA_PKCS_OAEP_PARAMS;
The fields of the structure have the following meanings:
hashAlg mechanism ID of the message digest algorithm used to calculate the digest of the encoding parameter
mgf mask generation function to use on the encoded block
source source of the encoding parameter
pSourceData data used as the input for the encoding parameter source
ulSourceDataLen length of the encoding parameter source input
CK_RSA_PKCS_OAEP_PARAMS_PTR is a pointer to a CK_RSA_PKCS_OAEP_PARAMS.
The PKCS #1 RSA OAEP mechanism, denoted CKM_RSA_PKCS_OAEP, is a multipurpose mechanism based on the RSA publickey cryptosystem and the OAEP block format defined in PKCS #1. It supports singlepart encryption and decryption; key wrapping; and key unwrapping.
It has a parameter, a CK_RSA_PKCS_OAEP_PARAMS structure.
This mechanism can wrap and unwrap any secret key of appropriate length. Of course, a particular token may not be able to wrap/unwrap every appropriatelength secret key that it supports. For wrapping, the “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping. The mechanism does not wrap the key type or any other information about the key, except the key length; the application must convey these separately. In particular, the mechanism contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes to the recovered key during unwrapping; other attributes must be specified in the template.
Constraints on key types and the length of the data are summarized in the following table. For encryption and decryption, the input and output data may begin at the same location in memory. In the table, k is the length in bytes of the RSA modulus, and hLen is the output length of the message digest algorithm specified by the hashAlg field of the CK_RSA_PKCS_OAEP_PARAMS structure.
Table 7, PKCS #1 RSA OAEP: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Encrypt^{1} 
RSA public key 
£ k22hLen 
k 
C_Decrypt^{1} 
RSA private key 
k 
£ k22hLen 
C_WrapKey 
RSA public key 
£ k22hLen 
k 
C_UnwrapKey 
RSA private key 
k 
£ k22hLen 
^{1} Singlepart operations only.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
¨ CK_RSA_PKCS_PSS_PARAMS; CK_RSA_PKCS_PSS_PARAMS_PTR
CK_RSA_PKCS_PSS_PARAMS is a structure that provides the parameters to the CKM_RSA_PKCS_PSS mechanism. The structure is defined as follows:
typedef struct CK_RSA_PKCS_PSS_PARAMS {
CK_MECHANISM_TYPE hashAlg;
CK_RSA_PKCS_MGF_TYPE mgf;
CK_ULONG sLen;
} CK_RSA_PKCS_PSS_PARAMS;
The fields of the structure have the following meanings:
hashAlg hash algorithm used in the PSS encoding; if the signature mechanism does not include message hashing, then this value must be the mechanism used by the application to generate the message hash; if the signature mechanism includes hashing, then this value must match the hash algorithm indicated by the signature mechanism
mgf mask generation function to use on the encoded block
sLen length, in bytes, of the salt value used in the PSS encoding; typical values are the length of the message hash and zero
CK_RSA_PKCS_PSS_PARAMS_PTR is a pointer to a CK_RSA_PKCS_PSS_PARAMS.
The PKCS #1 RSA PSS mechanism, denoted CKM_RSA_PKCS_PSS, is a mechanism based on the RSA publickey cryptosystem and the PSS block format defined in PKCS #1. It supports singlepart signature generation and verification without message recovery. This mechanism corresponds only to the part of PKCS #1 that involves block formatting and RSA, given a hash value; it does not compute a hash value on the message to be signed.
It has a parameter, a CK_RSA_PKCS_PSS_PARAMS structure. The sLen field must be less than or equal to k*2hLen and hLen is the length of the input to the C_Sign or C_Verify function. k* is the length in bytes of the RSA modulus, except if the length in bits of the RSA modulus is one more than a multiple of 8, in which case k* is one less than the length in bytes of the RSA modulus.
Constraints on key types and the length of the data are summarized in the following table. In the table, k is the length in bytes of the RSA.
Table 8, PKCS #1 RSA PSS: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign^{1} 
RSA private key 
hLen 
k 
C_Verify^{1} 
RSA public key 
hLen, k 
N/A 
^{1} Singlepart operations only.
2 Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
The ISO/IEC 9796 RSA mechanism, denoted CKM_RSA_9796, is a mechanism for singlepart signatures and verification with and without message recovery based on the RSA publickey cryptosystem and the block formats defined in ISO/IEC 9796 and its annex A.
This mechanism processes only byte strings, whereas ISO/IEC 9796 operates on bit strings. Accordingly, the following transformations are performed:
· Data is converted between byte and bit string formats by interpreting the mostsignificant bit of the leading byte of the byte string as the leftmost bit of the bit string, and the leastsignificant bit of the trailing byte of the byte string as the rightmost bit of the bit string (this assumes the length in bits of the data is a multiple of 8).
· A signature is converted from a bit string to a byte string by padding the bit string on the left with 0 to 7 zero bits so that the resulting length in bits is a multiple of 8, and converting the resulting bit string as above; it is converted from a byte string to a bit string by converting the byte string as above, and removing bits from the left so that the resulting length in bits is the same as that of the RSA modulus.
This mechanism does not have a parameter.
Constraints on key types and the length of input and output data are summarized in the following table. In the table, k is the length in bytes of the RSA modulus.
Table 9, ISO/IEC 9796 RSA: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign^{1} 
RSA private key 
£ ëk/2û 
k 
C_SignRecover 
RSA private key 
£ ëk/2û 
k 
C_Verify^{1} 
RSA public key 
£ ëk/2û, k^{2} 
N/A 
C_VerifyRecover 
RSA public key 
k 
£ ëk/2û 
^{1} Singlepart operations only.
2 Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
The X.509 (raw) RSA mechanism, denoted CKM_RSA_X_509, is a multipurpose mechanism based on the RSA publickey cryptosystem. It supports singlepart encryption and decryption; singlepart signatures and verification with and without message recovery; key wrapping; and key unwrapping. All these operations are based on socalled “raw” RSA, as assumed in X.509.
“Raw” RSA as defined here encrypts a byte string by converting it to an integer, mostsignificant byte first, applying “raw” RSA exponentiation, and converting the result to a byte string, mostsignificant byte first. The input string, considered as an integer, must be less than the modulus; the output string is also less than the modulus.
This mechanism does not have a parameter.
This mechanism can wrap and unwrap any secret key of appropriate length. Of course, a particular token may not be able to wrap/unwrap every appropriatelength secret key that it supports. For wrapping, the “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping. The mechanism does not wrap the key type, key length, or any other information about the key; the application must convey these separately, and supply them when unwrapping the key.
Unfortunately, X.509 does not specify how to perform padding for RSA encryption. For this mechanism, padding should be performed by prepending plaintext data with 0valued bytes. In effect, to encrypt the sequence of plaintext bytes b_{1} b_{2} … b_{n} (n £ k), Cryptoki forms P=2^{n1}b_{1}+2^{n2}b_{2}+…+b_{n}. This number must be less than the RSA modulus. The kbyte ciphertext (k is the length in bytes of the RSA modulus) is produced by raising P to the RSA public exponent modulo the RSA modulus. Decryption of a kbyte ciphertext C is accomplished by raising C to the RSA private exponent modulo the RSA modulus, and returning the resulting value as a sequence of exactly k bytes. If the resulting plaintext is to be used to produce an unwrapped key, then however many bytes are specified in the template for the length of the key are taken from the end of this sequence of bytes.
Technically, the above procedures may differ very slightly from certain details of what is specified in X.509.
Executing cryptographic operations using this mechanism can result in the error returns CKR_DATA_INVALID (if plaintext is supplied which has the same length as the RSA modulus and is numerically at least as large as the modulus) and CKR_ENCRYPTED_DATA_INVALID (if ciphertext is supplied which has the same length as the RSA modulus and is numerically at least as large as the modulus).
Constraints on key types and the length of input and output data are summarized in the following table. In the table, k is the length in bytes of the RSA modulus.
Table 10, X.509 (Raw) RSA: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Encrypt^{1} 
RSA public key 
£ k 
k 
C_Decrypt^{1} 
RSA private key 
k 
k 
C_Sign^{1} 
RSA private key 
£ k 
k 
C_SignRecover 
RSA private key 
£ k 
k 
C_Verify^{1} 
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) 
^{1} Singlepart operations only.
2 Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
This mechanism is intended for compatibility with applications that do not follow the PKCS #1 or ISO/IEC 9796 block formats.
The ANSI X9.31 RSA mechanism, denoted CKM_RSA_X9_31, is a mechanism for singlepart signatures and verification without message recovery based on the RSA publickey cryptosystem and the block formats defined in ANSI X9.31.
This mechanism applies the header and padding fields of the hash encapsulation. The trailer field must be applied by the application.
This mechanism processes only byte strings, whereas ANSI X9.31 operates on bit strings. Accordingly, the following transformations are performed:
· Data is converted between byte and bit string formats by interpreting the mostsignificant bit of the leading byte of the byte string as the leftmost bit of the bit string, and the leastsignificant bit of the trailing byte of the byte string as the rightmost bit of the bit string (this assumes the length in bits of the data is a multiple of 8).
· A signature is converted from a bit string to a byte string by padding the bit string on the left with 0 to 7 zero bits so that the resulting length in bits is a multiple of 8, and converting the resulting bit string as above; it is converted from a byte string to a bit string by converting the byte string as above, and removing bits from the left so that the resulting length in bits is the same as that of the RSA modulus.
This mechanism does not have a parameter.
Constraints on key types and the length of input and output data are summarized in the following table. In the table, k is the length in bytes of the RSA modulus. For all operations, the k value must be at least 128 and a multiple of 32 as specified in ANSI X9.31.
Table 11, ANSI X9.31 RSA: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign^{1} 
RSA private key 
£ k2 
k 
C_Verify^{1} 
RSA public key 
£ k2, k^{2} 
N/A 
^{1} Singlepart operations only.
2 Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
The PKCS #1 v1.5 RSA signature with MD2 mechanism, denoted CKM_MD2_RSA_PKCS, performs single and multiplepart digital signatures and verification operations without message recovery. The operations performed are as described initially in PKCS #1 v1.5 with the object identifier md2WithRSAEncryption, and as in the scheme RSASSAPKCS1v1_5 in the current version of PKCS #1, where the underlying hash function is MD2.
Similarly, the PKCS #1 v1.5 RSA signature with MD5 mechanism, denoted CKM_MD5_RSA_PKCS, performs the same operations described in PKCS #1 with the object identifier md5WithRSAEncryption. The PKCS #1 v1.5 RSA signature with SHA1 mechanism, denoted CKM_SHA1_RSA_PKCS, performs the same operations, except that it uses the hash function SHA1 with object identifier sha1WithRSAEncryption.
Likewise, the PKCS #1 v1.5 RSA signature with SHA256, SHA384, and SHA512 mechanisms, denoted CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, and CKM_SHA512_RSA_PKCS respectively, perform the same operations using the SHA256, SHA384 and SHA512 hash functions with the object identifiers sha256WithRSAEncryption, sha384WithRSAEncryption and sha512WithRSAEncryption respectively.
The PKCS #1 v1.5 RSA signature with RIPEMD128 or RIPEMD160, denoted CKM_RIPEMD128_RSA_PKCS and CKM_RIPEMD160_RSA_PKCS respectively, perform the same operations using the RIPEMD 128 and RIPEMD 160 hash functions.
None of these mechanisms has a parameter.
Constraints on key types and the length of the data for these mechanisms are summarized in the following table. In the table, k is the length in bytes of the RSA modulus. For the PKCS #1 v1.5 RSA signature with MD2 and PKCS #1 v1.5 RSA signature with MD5 mechanisms, k must be at least 27; for the PKCS #1 v1.5 RSA signature with SHA1 mechanism, k must be at least 31, and so on for other underlying hash functions, where the minimum is always 11 bytes more than the length of the hash value.
Table 12, PKCS #1 v1.5 RSA Signatures with Various Hash Functions: Key And Data Length
Function 
Key type 
Input length 
Output length 
Comments 
C_Sign 
RSA private key 
any 
k 
block type 01 
C_Verify 
RSA public key 
any, k^{2} 
N/A 
block type 01 
^{2} Data length, signature length.
For these mechanisms, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
The PKCS #1 v1.5 RSA signature with SHA224 mechanism, denoted CKM_SHA224_RSA_PKCS, performs similarly as the other CKM_SHAX_RSA_PKCS mechanisms but uses the SHA224 hash function.
The PKCS #1 RSA PSS signature with SHA224 mechanism, denoted CKM_SHA224_RSA_PKCS_PSS, performs similarly as the other CKM_SHAX_RSA_ PKCS_PSS mechanisms but uses the SHA224 hash function.
The PKCS #1 RSA PSS signature with SHA1 mechanism, denoted CKM_SHA1_RSA_PKCS_PSS, performs single and multiplepart digital signatures and verification operations without message recovery. The operations performed are as described in PKCS #1 with the object identifier idRSASSAPSS, i.e., as in the scheme RSASSAPSS in PKCS #1 where the underlying hash function is SHA1.
The PKCS #1 RSA PSS signature with SHA256, SHA384, and SHA512 mechanisms, denoted CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, and CKM_SHA512_RSA_PKCS_PSS respectively, perform the same operations using the SHA256, SHA384 and SHA512 hash functions.
The mechanisms have a parameter, a CK_RSA_PKCS_PSS_PARAMS structure. The sLen field must be less than or equal to k*2hLen where hLen is the length in bytes of the hash value. k* is the length in bytes of the RSA modulus, except if the length in bits of the RSA modulus is one more than a multiple of 8, in which case k* is one less than the length in bytes of the RSA modulus.
Constraints on key types and the length of the data are summarized in the following table. In the table, k is the length in bytes of the RSA modulus.
Table 13, PKCS #1 RSA PSS Signatures with Various Hash Functions: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
RSA private key 
any 
k 
C_Verify 
RSA public key 
any, k^{2} 
N/A 
^{2} Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
The PKCS #1 v1.5 RSA signature with SHA3224, SHA3256, SHA3384, SHA3512 mechanisms, denoted CKM_SHA3_224_RSA_PKCS, CKM_SHA3_256_RSA_PKCS, CKM_SHA3_384_RSA_PKCS, and CKM_SHA3_512_RSA_PKCS respectively, performs similarly as the other CKM_SHAX_RSA_PKCS mechanisms but uses the corresponding SHA3 hash functions.
The PKCS #1 RSA PSS signature with SHA3224, SHA3256, SHA3384, SHA3512 mechanisms, denoted CKM_SHA3_224_RSA_PKCS_PSS, CKM_SHA3_256_RSA_PKCS_PSS, CKM_SHA3_384_RSA_PKCS_PSS, and CKM_SHA3_512_RSA_PKCS_PSS respectively, performs similarly as the other CKM_SHAX_RSA_PKCS_PSS mechanisms but uses the corresponding SHA3 hash functions.
The ANSI X9.31 RSA signature with SHA1 mechanism, denoted CKM_SHA1_RSA_X9_31, performs single and multiplepart digital signatures and verification operations without message recovery. The operations performed are as described in ANSI X9.31.
This mechanism does not have a parameter.
Constraints on key types and the length of the data for these mechanisms are summarized in the following table. In the table, k is the length in bytes of the RSA modulus. For all operations, the k value must be at least 128 and a multiple of 32 as specified in ANSI X9.31.
Table 14, ANSI X9.31 RSA Signatures with SHA1: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
RSA private key 
any 
k 
C_Verify 
RSA public key 
any, k^{2} 
N/A 
^{2} Data length, signature length.
For these mechanisms, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
The TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA mechanism, denoted CKM_RSA_PKCS_TPM_1_1, is a multiuse mechanism based on the RSA publickey cryptosystem and the block formats initially defined in PKCS #1 v1.5, with additional formatting rules defined in TCPA TPM Specification Version 1.1b. Additional formatting rules remained the same in TCG TPM Specification 1.2 The mechanism supports singlepart encryption and decryption; key wrapping; and key unwrapping.
This mechanism does not have a parameter. It differs from the standard PKCS#1 v1.5 RSA encryption mechanism in that the plaintext is wrapped in a TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1.2) structure before being submitted to the PKCS#1 v1.5 encryption process. On encryption, the version field of the TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1.2) structure must contain 0x01, 0x01, 0x00, 0x00. On decryption, any structure of the form 0x01, 0x01, 0xXX, 0xYY may be accepted.
This mechanism can wrap and unwrap any secret key of appropriate length. Of course, a particular token may not be able to wrap/unwrap every appropriatelength secret key that it supports. For wrapping, the “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping. The mechanism does not wrap the key type or any other information about the key, except the key length; the application must convey these separately. In particular, the mechanism contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes to the recovered key during unwrapping; other attributes must be specified in the template.
Constraints on key types and the length of the data are summarized in the following table. For encryption and decryption, the input and output data may begin at the same location in memory. In the table, k is the length in bytes of the RSA modulus.
Table 15, TPM 1.1b and TPM 1.2 PKCS #1 v1.5 RSA: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Encrypt^{1} 
RSA public key 
£ k115 
k 
C_Decrypt^{1} 
RSA private key 
k 
£ k115 
C_WrapKey 
RSA public key 
£ k115 
k 
C_UnwrapKey 
RSA private key 
k 
£ k115 
^{1} Singlepart operations only.
^{ }
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
The TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP mechanism, denoted CKM_RSA_PKCS_OAEP_TPM_1_1, is a multipurpose mechanism based on the RSA publickey cryptosystem and the OAEP block format defined in PKCS #1, with additional formatting defined in TCPA TPM Specification Version 1.1b. Additional formatting rules remained the same in TCG TPM Specification 1.2. The mechanism supports singlepart encryption and decryption; key wrapping; and key unwrapping.
This mechanism does not have a parameter. It differs from the standard PKCS#1 OAEP RSA encryption mechanism in that the plaintext is wrapped in a TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1.2) structure before being submitted to the encryption process and that all of the values of the parameters that are passed to a standard CKM_RSA_PKCS_OAEP operation are fixed. On encryption, the version field of the TCPA_BOUND_DATA (TPM_BOUND_DATA for TPM 1.2) structure must contain 0x01, 0x01, 0x00, 0x00. On decryption, any structure of the form 0x01, 0x01, 0xXX, 0xYY may be accepted.
This mechanism can wrap and unwrap any secret key of appropriate length. Of course, a particular token may not be able to wrap/unwrap every appropriatelength secret key that it supports. For wrapping, the “input” to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping. The mechanism does not wrap the key type or any other information about the key, except the key length; the application must convey these separately. In particular, the mechanism contributes only the CKA_CLASS and CKA_VALUE (and CKA_VALUE_LEN, if the key has it) attributes to the recovered key during unwrapping; other attributes must be specified in the template.
Constraints on key types and the length of the data are summarized in the following table. For encryption and decryption, the input and output data may begin at the same location in memory. In the table, k is the length in bytes of the RSA modulus.
Table 16, TPM 1.1b and TPM 1.2 PKCS #1 RSA OAEP: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Encrypt^{1} 
RSA public key 
£ k2405 
k 
C_Decrypt^{1} 
RSA private key 
k 
£ k2405 
C_WrapKey 
RSA public key 
£ k2405 
k 
C_UnwrapKey 
RSA private key 
k 
£ k2405 
^{1} Singlepart operations only.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.
The RSA AES key wrap mechanism, denoted CKM_RSA_AES_KEY_WRAP, is a mechanism based on the RSA publickey cryptosystem and the AES key wrap mechanism. It supports singlepart key wrapping; and key unwrapping.
It has a parameter, a CK_RSA_AES_KEY_WRAP_PARAMS structure.
The mechanism can wrap and unwrap a target asymmetric key of any length and type using an RSA key.
 A temporary AES key is used for wrapping the target key using CKM_AES_KEY_WRAP_KWP mechanism.
 The temporary AES key is wrapped with the wrapping RSA key using CKM_RSA_PKCS_OAEP mechanism.
For wrapping, the mechanism 
The recommended format for an asymmetric target key being wrapped is as a PKCS8 PrivateKeyInfo
The use of Attributes in the PrivateKeyInfo structure is OPTIONAL. In case of conflicts between the object attribute template, and Attributes in the PrivateKeyInfo structure, an error should be thrown
For unwrapping, the mechanism 
Table 17, CKM_RSA_AES_KEY_WRAP Mechanisms vs. Functions

Functions 

Mechanism 
Encrypt & Decrypt 
Sign & Verify 
SR & VR1 
Digest 
Gen. Key/ Key Pair 
Wrap & Unwrap 
Derive 
CKM_RSA_AES_KEY_WRAP 





ü 

1SR = SignRecover, VR = VerifyRecover 
¨ CK_RSA_AES_KEY_WRAP_PARAMS; CK_RSA_AES_KEY_WRAP_PARAMS_PTR
CK_RSA_AES_KEY_WRAP_PARAMS is a structure that provides the parameters to the CKM_RSA_AES_KEY_WRAP mechanism. It is defined as follows:
typedef struct CK_RSA_AES_KEY_WRAP_PARAMS {
CK_ULONG ulAESKeyBits;
CK_RSA_PKCS_OAEP_PARAMS_PTR pOAEPParams;
} CK_RSA_AES_KEY_WRAP_PARAMS;
The fields of the structure have the following meanings:
ulAESKeyBits length of the temporary AES key in bits. Can be only 128, 192 or 256.
pOAEPParams pointer to the parameters of the temporary AES key wrapping. See also the description of PKCS #1 RSA OAEP mechanism parameters.
CK_RSA_AES_KEY_WRAP_PARAMS_PTR is a pointer to a CK_RSA_AES_KEY_WRAP_PARAMS.
When CKM_RSA_PKCS is operated in FIPS mode, the length of the modulus SHALL only be 1024, 2048, or 3072 bits.
Table 18, DSA Mechanisms vs. Functions

Functions 

Mechanism 
Encrypt & Decrypt 
Sign & Verify 
SR & VR^{1} 
Digest 
Gen. Key/ Key Pair 
Wrap & Unwrap 
Derive 




ü 



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 attribute of DSA key objects.
Mechanisms:
CKM_DSA
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
CKM_DSA_PARAMETER_GEN
CKM_DSA_PROBABILISTIC_PARAMETER_GEN
CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN
CKM_DSA_FIPS_G_GEN
¨ CK_DSA_PARAMETER_GEN_PARAM
CK_DSA_PARAMETER_GEN_PARAM is a structure which provides and returns parameters for the NIST FIPS 1864 parameter generating algorithms.
CK_DSA_PARAMETER_GEN_PARAM_PTR is a pointer to a CK_DSA_PARAMETER_GEN_PARAM.
typedef struct CK_DSA_PARAMETER_GEN_PARAM {
CK_MECHANISM_TYPE hash;
CK_BYTE_PTR pSeed;
CK_ULONG ulSeedLen;
CK_ULONG ulIndex;
} CK_DSA_PARAMETER_GEN_PARAM;
The fields of the structure have the following meanings:
hash Mechanism value for the base hash used in PQG generation, Valid values are CKM_SHA_1, CKM_SHA224, CKM_SHA256, CKM_SHA384, CKM_SHA512.
pSeed Seed value used to generate PQ and G. This value is returned by CKM_DSA_PROBABILISTIC_PARAMETER_GEN, CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN, and passed into CKM_DSA_FIPS_G_GEN.
ulSeedLen Length of seed value.
ulIndex Index value for generating G. Input for CKM_DSA_FIPS_G_GEN. Ignored by CKM_DSA_PROBABILISTIC_PARAMETER_GEN and CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN.
DSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_DSA) hold DSA public keys. The following table defines the DSA public key object attributes, in addition to the common attributes defined for this object class:
Table 19, DSA Public Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_PRIME^{1,3} 
Big integer 
Prime p (512 to 3072 bits, in steps of 64 bits) 
CKA_SUBPRIME^{1,3} 
Big integer 
Subprime q (160, 224 bits, or 256 bits) 
CKA_BASE^{1,3} 
Big integer 
Base g 
CKA_VALUE^{1,4} 
Big integer 
Public value y 
^{ Refer to [PKCS11Base] table 11 for footnotes}
The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA domain parameters”. See FIPS PUB 1864 for more information on DSA keys.
The following is a sample template for creating a DSA public key object:
CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_DSA;
CK_UTF8CHAR label[] = “A DSA public key object”;
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};
FIPS PUB 1864 specifies permitted combinations of prime and subprime lengths. They are:
Earlier versions of FIPS 186 permitted smaller prime lengths, and those are included here for backwards compatibility. An implementation that is compliant to FIPS 1864 does not permit the use of primes of any length less than 1024 bits.
DSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_DSA) hold DSA private keys. The following table defines the DSA private key object attributes, in addition to the common attributes defined for this object class:
Table 20, DSA Private Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_PRIME^{1,4,6} 
Big integer 
Prime p (512 to 1024 bits, in steps of 64 bits) 
CKA_SUBPRIME^{1,4,6} 
Big integer 
Subprime q (160 bits, 224 bits, or 256 bits) 
CKA_BASE^{1,4,6} 
Big integer 
Base g 
CKA_VALUE^{1,4,6,7} 
Big integer 
Private value x 
^{ Refer to [PKCS11Base] table 11 for footnotes}
The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA domain parameters”. See FIPS PUB 1864 for more information on DSA keys.
Note that when generating a DSA private key, the DSA domain parameters are not specified in the key’s template. This is because DSA private keys are only generated as part of a DSA key pair, and the DSA domain parameters for the pair are specified in the template for the DSA public key.
The following is a sample template for creating a DSA private key object:
CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_DSA;
CK_UTF8CHAR label[] = “A DSA private key object”;
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_SIGN, &true, sizeof(true)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};
DSA domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type CKK_DSA) hold DSA domain parameters. The following table defines the DSA domain parameter object attributes, in addition to the common attributes defined for this object class:
Table 21, DSA Domain Parameter Object Attributes
Attribute 
Data type 
Meaning 
CKA_PRIME^{1,4} 
Big integer 
Prime p (512 to 1024 bits, in steps of 64 bits) 
CKA_SUBPRIME^{1,4} 
Big integer 
Subprime q (160 bits, 224 bits, or 256 bits) 
CKA_BASE^{1,4} 
Big integer 
Base g 
CKA_PRIME_BITS^{2,3} 
CK_ULONG 
Length of the prime value. 
^{ Refer to [PKCS11Base] table 11 for footnotes}
The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA domain parameters”. See FIPS PUB 1864 for more information on DSA domain parameters.
To ensure backwards compatibility, if CKA_SUBPRIME_BITS is not specified for a call to C_GenerateKey, it takes on a default based on the value of CKA_PRIME_BITS as follows:
The following is a sample template for creating a DSA domain parameter object:
CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS;
CK_KEY_TYPE keyType = CKK_DSA;
CK_UTF8CHAR label[] = “A DSA domain parameter object”;
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
};
The DSA key pair generation mechanism, denoted CKM_DSA_KEY_PAIR_GEN, is a key pair generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 1862.
This mechanism does not have a parameter.
The mechanism generates DSA public/private key pairs with a particular prime, subprime and base, as specified in the CKA_PRIME, CKA_SUBPRIME, and CKA_BASE attributes of the template for the public key.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_BASE, and CKA_VALUE attributes to the new private key. Other attributes supported by the DSA public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.
The DSA domain parameter generation mechanism, denoted CKM_DSA_PARAMETER_GEN, is a domain parameter generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 1862.
This mechanism does not have a parameter.
The mechanism generates DSA domain parameters with a particular prime length in bits, as specified in the CKA_PRIME_BITS attribute of the template.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_BASE and CKA_PRIME_BITS attributes to the new object. Other attributes supported by the DSA domain parameter types may also be specified in the template, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.
The DSA probabilistic domain parameter generation mechanism, denoted CKM_DSA_PROBABILISTIC_PARAMETER_GEN, is a domain parameter generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 1864, section Appendix A.1.1 Generation and Validation of Probable Primes..
This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash and returns the seed (pSeed) and the length (ulSeedLen).
The mechanism generates DSA the prime and subprime domain parameters with a particular prime length in bits, as specified in the CKA_PRIME_BITS attribute of the template and the subprime length as specified in the CKA_SUBPRIME_BITS attribute of the template.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_PRIME_BITS, and CKA_SUBPRIME_BITS attributes to the new object. CKA_BASE is not set by this call. Other attributes supported by the DSA domain parameter types may also be specified in the template, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.
The DSA ShaweTaylor domain parameter generation mechanism, denoted CKM_DSA_SHAWE_TAYLOR_PARAMETER_GEN, is a domain parameter generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 1864, section Appendix A.1.2 Construction and Validation of Provable Primes p and q.
This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash and returns the seed (pSeed) and the length (ulSeedLen).
The mechanism generates DSA the prime and subprime domain parameters with a particular prime length in bits, as specified in the CKA_PRIME_BITS attribute of the template and the subprime length as specified in the CKA_SUBPRIME_BITS attribute of the template.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_PRIME_BITS, and CKA_SUBPRIME_BITS attributes to the new object. CKA_BASE is not set by this call. Other attributes supported by the DSA domain parameter types may also be specified in the template, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.
The DSA base domain parameter generation mechanism, denoted CKM_DSA_FIPS_G_GEN, is a base parameter generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 1864, section Appendix A.2 Generation of Generator G.
This mechanism takes a CK_DSA_PARAMETER_GEN_PARAM which supplies the base hash the seed (pSeed) and the length (ulSeedLen) and the index value.
The mechanism generates the DSA base with the domain parameter specified in the CKA_PRIME and CKA_SUBPRIME attributes of the template.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_BASE attributes to the new object. Other attributes supported by the DSA domain parameter types may also be specified in the template, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.
The DSA without hashing mechanism, denoted CKM_DSA, is a mechanism for singlepart signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1862. (This mechanism corresponds only to the part of DSA that processes the 20byte hash value; it does not compute the hash value.)
For the purposes of this mechanism, a DSA signature is a 40byte string, corresponding to the concatenation of the DSA values r and s, each represented mostsignificant byte first.
It does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 22, DSA: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign^{1} 
DSA private key 
20, 28, 32, 48, or 64 bits 
2*length of subprime 
C_Verify^{1} 
DSA public key 
(20, 28, 32, 48, or 64 bits), (2*length of subprime)^{2} 
N/A 
^{1} Singlepart operations only.
2 Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.
The DSA with SHA1 mechanism, denoted CKM_DSA_SHA1, is a mechanism for single and multiplepart signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1862. This mechanism computes the entire DSA specification, including the hashing with SHA1.
For the purposes of this mechanism, a DSA signature is a 40byte string, corresponding to the concatenation of the DSA values r and s, each represented mostsignificant byte first.
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 23, DSA with SHA1: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
DSA private key 
any 
2*subprime length 
C_Verify 
DSA public key 
any, 2*subprime length^{2} 
N/A 
^{2} Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.
When CKM_DSA is operated in FIPS mode, only the following bit lengths of p and q, represented by L and N, SHALL be used:
L = 1024, N = 160
L = 2048, N = 224
L = 2048, N = 256
L = 3072, N = 256
The DSA with SHA1 mechanism, denoted CKM_DSA_SHA224, is a mechanism for single and multiplepart signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1864. This mechanism computes the entire DSA specification, including the hashing with SHA224.
For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented mostsignificant byte first.
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 24, DSA with SHA244: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
DSA private key 
any 
2*subprime length 
C_Verify 
DSA public key 
any, 2*subprime length^{2} 
N/A 
^{2} Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.
The DSA with SHA1 mechanism, denoted CKM_DSA_SHA256, is a mechanism for single and multiplepart signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1864. This mechanism computes the entire DSA specification, including the hashing with SHA256.
For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented mostsignificant byte first.
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 25, DSA with SHA256: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
DSA private key 
any 
2*subprime length 
C_Verify 
DSA public key 
any, 2*subprime length^{2} 
N/A 
^{2} Data length, signature length.
The DSA with SHA1 mechanism, denoted CKM_DSA_SHA384, is a mechanism for single and multiplepart signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1864. This mechanism computes the entire DSA specification, including the hashing with SHA384.
For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented mostsignificant byte first.
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 26, DSA with SHA384: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
DSA private key 
any 
2*subprime length 
C_Verify 
DSA public key 
any, 2*subprime length^{2} 
N/A 
^{2} Data length, signature length.
The DSA with SHA1 mechanism, denoted CKM_DSA_SHA512, is a mechanism for single and multiplepart signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1864. This mechanism computes the entire DSA specification, including the hashing with SHA512.
For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented mostsignificant byte first.
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 27, DSA with SHA512: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
DSA private key 
any 
2*subprime length 
C_Verify 
DSA public key 
any, 2*subprime length^{2} 
N/A 
^{2} Data length, signature length.
The DSA with SHA3224 mechanism, denoted CKM_DSA_SHA3_224, is a mechanism for single and multiplepart signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1864. This mechanism computes the entire DSA specification, including the hashing with SHA3224.
For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented mostsignificant byte first.
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 28, DSA with SHA3224: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
DSA private key 
any 
2*subprime length 
C_Verify 
DSA public key 
any, 2*subprime length^{2} 
N/A 
^{2} Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.
The DSA with SHA3256 mechanism, denoted CKM_DSA_SHA3_256, is a mechanism for single and multiplepart signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1864. This mechanism computes the entire DSA specification, including the hashing with SHA3256.
For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented mostsignificant byte first.
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 29, DSA with SHA3256: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
DSA private key 
any 
2*subprime length 
C_Verify 
DSA public key 
any, 2*subprime length^{2} 
N/A 
^{2} Data length, signature length.
The DSA with SHA3384 mechanism, denoted CKM_DSA_SHA3_384, is a mechanism for single and multiplepart signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1864. This mechanism computes the entire DSA specification, including the hashing with SHA3384.
For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented mostsignificant byte first.
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 30, DSA with SHA3384: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
DSA private key 
any 
2*subprime length 
C_Verify 
DSA public key 
any, 2*subprime length^{2} 
N/A 
^{2} Data length, signature length.
The DSA with SHA3512 mechanism, denoted CKM_DSA_SHA3_512, is a mechanism for single and multiplepart signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 1864. This mechanism computes the entire DSA specification, including the hashing with SH3A512.
For the purposes of this mechanism, a DSA signature is a string of length 2*subprime, corresponding to the concatenation of the DSA values r and s, each represented mostsignificant byte first.
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 31, DSA with SHA3512: Key And Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
DSA private key 
any 
2*subprime length 
C_Verify 
DSA public key 
any, 2*subprime length^{2} 
N/A 
^{2} Data length, signature length.
The Elliptic Curve (EC) cryptosystem (also related to ECDSA) in this document was originally based on the one described in the ANSI X9.62 and X9.63 standards developed by the ANSI X9F1 working group.
The EC cryptosystem developed by the ANSI X9F1 working group was created at a time when EC curves were always represented in their Weierstrass form. Since that time, new curves represented in Edwards form (RFC 8032) and Montgomery form (RFC 7748) have become more common. To support these new curves, the EC cryptosystem in this document has been extended from the original. Additional key generation mechanisms have been added as well as an additional signature generation mechanism.
Table 32, Elliptic Curve Mechanisms vs. Functions

Functions 

Mechanism 
Encrypt & Decrypt 
Sign & Verify 
SR & VR^{1} 
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 






ü 
CKM_ECDH_AES_KEY_WRAP 





ü 

Table 33, Mechanism Information Flags
CKF_EC_F_P 
0x00100000UL 
True if the mechanism can be used with EC domain parameters over F_{p} 
CKF_EC_F_2M 
0x00200000UL 
True if the mechanism can be used with EC domain parameters over F_{2m} 
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.
In these standards, there are two different varieties of EC defined:
1. EC using a field with an odd prime number of elements (i.e. the finite field F_{p}).
2. EC using a field of characteristic two (i.e. the finite field F_{2m}).
An EC key in Cryptoki contains information about which variety of EC it is suited for. It is preferable that a Cryptoki library, which can perform EC mechanisms, be capable of performing operations with the two varieties of EC, however this is not required. The CK_MECHANISM_INFO structure CKF_EC_F_P flag identifies a Cryptoki library supporting EC keys over F_{p} whereas the CKF_EC_F_2M flag identifies a Cryptoki library supporting EC keys over F_{2m}. A Cryptoki library that can perform EC mechanisms must set either or both of these flags for each EC mechanism.
In these specifications there are also four representation methods to define the domain parameters for an EC key. Only the ecParameters, the oId and the curveName choices are supported in Cryptoki. The CK_MECHANISM_INFO structure CKF_EC_ECPARAMETERS flag identifies a Cryptoki library supporting the ecParameters choice whereas the CKF_EC_OID flag identifies a Cryptoki library supporting the oId choice, and the CKF_EC_CURVENAME flag identifies a Cryptoki library supporting the curveName choice. A Cryptoki library that can perform EC mechanisms must set the appropriate flag(s) for each EC mechanism.
In these specifications, an EC public key (i.e. EC point Q) or the base point G when the ecParameters choice is used can be represented as an octet string of the uncompressed form or the compressed form. The CK_MECHANISM_INFO structure CKF_EC_UNCOMPRESS flag identifies a Cryptoki library supporting the uncompressed form whereas the CKF_EC_COMPRESS flag identifies a Cryptoki library supporting the compressed form. A Cryptoki library that can perform EC mechanisms must set either or both of these flags for each EC mechanism.
Note that an implementation of a Cryptoki library supporting EC with only one variety, one representation of domain parameters or one form may encounter difficulties achieving interoperability with other implementations.
If an attempt to create, generate, derive or unwrap an EC key of an unsupported curve is made, the attempt should fail with the error code CKR_CURVE_NOT_SUPPORTED. If an attempt to create, generate, derive, or unwrap an EC key with invalid or of an unsupported representation of domain parameters is made, that attempt should fail with the error code CKR_DOMAIN_PARAMS_INVALID. If an attempt to create, generate, derive, or unwrap an EC key of an unsupported form is made, that attempt should fail with the error code CKR_TEMPLATE_INCONSISTENT.
For the purposes of these mechanisms, an ECDSA signature is an octet string of even length which is at most two times nLen octets, where nLen is the length in octets of the base point order n. The signature octets correspond to the concatenation of the ECDSA values r and s, both represented as an octet string of equal length of at most nLen with the most significant byte first. If r and s have different octet length, the shorter of both must be padded with leading zero octets such that both have the same octet length. Loosely spoken, the first half of the signature is r and the second half is s. For signatures created by a token, the resulting signature is always of length 2nLen. For signatures passed to a token for verification, the signature may have a shorter length but must be composed as specified before.
If the length of the hash value is larger than the bit length of n, only the leftmost bits of the hash up to the length of n will be used. Any truncation is done by the token.
Note: For applications, it is recommended to encode the signature as an octet string of length two times nLen if possible. This ensures that the application works with PKCS#11 modules which have been implemented based on an older version of this document. Older versions required all signatures to have length two times nLen. It may be impossible to encode the signature with the maximum length of two times nLen if the application just gets the integer values of r and s (i.e. without leading zeros), but does not know the base point order n, because r and s can have any value between zero and the base point order n.
An EdDSA signature is an octet string of even length which is two times nLen octets, where nLen is calculated as EdDSA parameter b divided by 8. The signature octets correspond to the concatenation of the EdDSA values R and S as defined in [RFC 8032], both represented as an octet string of equal length of nLen bytes in little endian order.
This section defines the key type “CKK_EC” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.
Note: CKK_ECDSA is deprecated. It is replaced by CKK_EC.
Mechanisms:
CKM_EC_KEY_PAIR_GEN
CKM_EC_EDWARDS_KEY_PAIR_GEN
CKM_EC_MONTGOMERY_KEY_PAIR_GEN
CKM_ECDSA
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_ECMQV_DERIVE
CKM_ECDH_AES_KEY_WRAP
CKD_NULL
CKD_SHA1_KDF
CKD_SHA224_KDF
CKD_SHA256_KDF
CKD_SHA384_KDF
CKD_SHA512_KDF
CKD_SHA3_224_KDF
CKD_SHA3_256_KDF
CKD_SHA3_384_KDF
CKD_SHA3_512_KDF
CKD_SHA1_KDF_SP800
CKD_SHA224_KDF_SP800
CKD_SHA256_KDF_SP800
CKD_SHA384_KDF_SP800
CKD_SHA512_KDF_SP800
CKD_SHA3_224_KDF_SP800
CKD_SHA3_256_KDF_SP800
CKD_SHA3_384_KDF_SP800
CKD_SHA3_512_KDF_SP800
CKD_BLAKE2B_160_KDF
CKD_BLAKE2B_256_KDF
CKD_BLAKE2B_384_KDF
CKD_BLAKE2B_512_KDF
EC (also related to ECDSA) public key objects (object class CKO_PUBLIC_KEY, key type CKK_EC) hold EC public keys. The following table defines the EC public key object attributes, in addition to the common attributes defined for this object class:
Table 34, Elliptic Curve Public Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_EC_PARAMS^{1,3 } 
Byte array 
DERencoding of an ANSI X9.62 Parameters value 
CKA_EC_POINT^{1,4} 
Byte array 
DERencoding of ANSI X9.62 ECPoint value Q 
^{ Refer to [PKCS11Base] table 11 for footnotes}
Note: CKA_ECDSA_PARAMS is deprecated. It is replaced by CKA_EC_PARAMS.
The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI X9.62 as a choice of three parameter representation methods with the following syntax:
Parameters ::= CHOICE {
ecParameters ECParameters,
oId CURVES.&id({CurveNames}),
implicitlyCA NULL,
curveName PrintableString
}
This allows detailed specification of all required values using choice ecParameters, the use of oId as an object identifier substitute for a particular set of elliptic curve domain parameters, or implicitlyCA to indicate that the domain parameters are explicitly defined elsewhere, or curveName to specify a curve name as e.g. define in [ANSI X9.62], [BRAINPOOL], [SEC 2], [LEGIFRANCE]. The use of oId or curveName is recommended over the choice ecParameters. The choice implicitlyCA must not be used in Cryptoki.
The following is a sample template for creating an EC (ECDSA) public key object:
CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_EC;
CK_UTF8CHAR label[] = “An EC public key object”;
CK_BYTE ecParams[] = {...};
CK_BYTE ecPoint[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_EC_PARAMS, ecParams, sizeof(ecParams)},
{CKA_EC_POINT, ecPoint, sizeof(ecPoint)}
};
EC (also related to ECDSA) private key objects (object class CKO_PRIVATE_KEY, key type CKK_EC) hold EC private keys. See Section 2.3 for more information about EC. The following table defines the EC private key object attributes, in addition to the common attributes defined for this object class:
Table 35, Elliptic Curve Private Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_EC_PARAMS^{1,4,6} 
Byte array 
DERencoding of an ANSI X9.62 Parameters value 
CKA_VALUE^{1,4,6,7} 
Big integer 
ANSI X9.62 private value d 
^{ Refer to [PKCS11Base] table 11 for footnotes}
The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI X9.62 as a choice of three parameter representation methods with the following syntax:
Parameters ::= CHOICE {
ecParameters ECParameters,
oId CURVES.&id({CurveNames}),
implicitlyCA NULL,
curveName PrintableString
}
This allows detailed specification of all required values using choice ecParameters, the use of oId as an object identifier substitute for a particular set of elliptic curve domain parameters, or implicitlyCA to indicate that the domain parameters are explicitly defined elsewhere, or curveName to specify a curve name as e.g. define in [ANSI X9.62], [BRAINPOOL], [SEC 2], [LEGIFRANCE]. The use of oId or curveName is recommended over the choice ecParameters. The choice implicitlyCA must not be used in Cryptoki.Note that when generating an EC private key, the EC domain parameters are not specified in the key’s template. This is because EC private keys are only generated as part of an EC key pair, and the EC domain parameters for the pair are specified in the template for the EC public key.
The following is a sample template for creating an EC (ECDSA) private key object:
CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_EC;
CK_UTF8CHAR label[] = “An EC private key object”;
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE ecParams[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_EC_PARAMS, ecParams, sizeof(ecParams)},
{CKA_VALUE, value, sizeof(value)}
Edwards EC public key objects (object class CKO_PUBLIC_KEY, key type CKK_EC_EDWARDS) hold Edwards EC public keys. The following table defines the Edwards EC public key object attributes, in addition to the common attributes defined for this object class:
Table 36, Edwards Elliptic Curve Public Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_EC_PARAMS^{1,3} 
Byte array 
DERencoding of a Parameters value as defined above 
CKA_EC_POINT^{1,4} 
Byte array 
DERencoding of the bbit public key value in little endian order as defined in RFC 8032 
^{ Refer to [PKCS #11Base] table 11 for footnotes}
The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI X9.62 as a choice of three parameter representation methods. A 4^{th} choice is added to support Edwards and Montgomery Elliptic curves. The CKA_EC_PARAMS attribute has the following syntax:
Parameters ::= CHOICE {
ecParameters ECParameters,
oId CURVES.&id({CurveNames}),
implicitlyCA NULL,
curveName PrintableString
}
Edwards EC public keys only support the use of the curveName selection to specify a curve name as defined in [RFC 8032] and the use of the oID selection to specify a curve through an EdDSA algorithm as defined in [RFC 8410]. Note that keys defined by RFC 8032 and RFC 8410 are incompatible.
The following is a sample template for creating an Edwards EC public key object with Edwards25519 being specified as curveName:
CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_EC;
CK_UTF8CHAR label[] = “An Edwards EC public key object”;
CK_BYTE ecParams[] = {0x13, 0x0c, 0x65, 0x64, 0x77, 0x61, 0x72, 0x64, 0x73, 0x32, 0x35, 0x35, 0x31, 0x39};
CK_BYTE ecPoint[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_EC_PARAMS, ecParams, sizeof(ecParams)},
{CKA_EC_POINT, ecPoint, sizeof(ecPoint)}
};
Edwards EC private key objects (object class CKO_PRIVATE_KEY, key type CKK_EC_EDWARDS) hold Edwards EC private keys. See Section 2.3 for more information about EC. The following table defines the Edwards EC private key object attributes, in addition to the common attributes defined for this object class:
Table 37, Edwards Elliptic Curve Private Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_EC_PARAMS^{1,4,6} 
Byte array 
DERencoding of a Parameters value as defined above 
CKA_VALUE^{1,4,6,7} 
Big integer 
bbit private key value in little endian order as defined in RFC 8032 
^{ Refer to [PKCS #11Base] table 11 for footnotes}
The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI X9.62 as a choice of three parameter representation methods. A 4^{th} choice is added to support Edwards and Montgomery Elliptic curves. The CKA_EC_PARAMS attribute has the following syntax:
Parameters ::= CHOICE {
ecParameters ECParameters,
oId CURVES.&id({CurveNames}),
implicitlyCA NULL,
curveName PrintableString
}
Edwards EC private keys only support the use of the curveName selection to specify a curve name as defined in [RFC 8032] and the use of the oID selection to specify a curve through an EdDSA algorithm as defined in [RFC 8410]. Note that keys defined by RFC 8032 and RFC 8410 are incompatible.
Note that when generating an Edwards EC private key, the EC domain parameters are not specified in the key’s template. This is because Edwards EC private keys are only generated as part of an Edwards EC key pair, and the EC domain parameters for the pair are specified in the template for the Edwards EC public key.
The following is a sample template for creating an Edwards EC private key object:
CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_EC;
CK_UTF8CHAR label[] = “An Edwards EC private key object”;
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE ecParams[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};
Montgomery EC public key objects (object class CKO_PUBLIC_KEY, key type CKK_EC_MONTGOMERY) hold Montgomery EC public keys. The following table defines the Montgomery EC public key object attributes, in addition to the common attributes defined for this object class:
Table 38, Montgomery Elliptic Curve Public Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_EC_PARAMS^{1,3} 
Byte array 
DERencoding of a Parameters value as defined above 
CKA_EC_POINT^{1,4} 
Byte array 
DERencoding of the public key value in little endian order as defined in RFC 7748 
^{ Refer to [PKCS #11Base] table 11 for footnotes}
The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI X9.62 as a choice of three parameter representation methods. A 4^{th} choice is added to support Edwards and Montgomery Elliptic curves. The CKA_EC_PARAMS attribute has the following syntax:
Parameters ::= CHOICE {
ecParameters ECParameters,
oId CURVES.&id({CurveNames}),
implicitlyCA NULL,
curveName PrintableString
}
Montgomery EC public keys only support the use of the curveName selection to specify a curve name as defined in [RFC7748] and the use of the oID selection to specify a curve through an ECDH algorithm as defined in [RFC 8410]. Note that keys defined by RFC 7748 and RFC 8410 are incompatible.
The following is a sample template for creating a Montgomery EC public key object:
CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_EC;
CK_UTF8CHAR label[] = “A Montgomery EC public key object”;
CK_BYTE ecParams[] = {...};
CK_BYTE ecPoint[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_EC_PARAMS, ecParams, sizeof(ecParams)},
{CKA_EC_POINT, ecPoint, sizeof(ecPoint)}
};
Montgomery EC private key objects (object class CKO_PRIVATE_KEY, key type CKK_EC_MONTGOMERY) hold Montgomery EC private keys. See Section 2.3 for more information about EC. The following table defines the Montgomery EC private key object attributes, in addition to the common attributes defined for this object class:
Table 39, Montgomery Elliptic Curve Private Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_EC_PARAMS^{1,4,6} 
Byte array 
DERencoding of a Parameters value as defined above 
CKA_VALUE^{1,4,6,7} 
Big integer 
Private key value in little endian order as defined in RFC 7748 
^{ Refer to [PKCS #11Base] table 11 for footnotes}
The CKA_EC_PARAMS attribute value is known as the “EC domain parameters” and is defined in ANSI X9.62 as a choice of three parameter representation methods. A 4^{th} choice is added to support Edwards and Montgomery Elliptic curves. The CKA_EC_PARAMS attribute has the following syntax:
Parameters ::= CHOICE {
ecParameters ECParameters,
oId CURVES.&id({CurveNames}),
implicitlyCA NULL,
curveName PrintableString
}
Edwards EC private keys only support the use of the curveName selection to specify a curve name as defined in [RFC7748] and the use of the oID selection to specify a curve through an ECDH algorithm as defined in [RFC 8410]. Note that keys defined by RFC 7748 and RFC 8410 are incompatible.
Note that when generating a Montgomery EC private key, the EC domain parameters are not specified in the key’s template. This is because Montgomery EC private keys are only generated as part of a Montgomery EC key pair, and the EC domain parameters for the pair are specified in the template for the Montgomery EC public key.
The following is a sample template for creating a Montgomery EC private key object:
CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_EC;
CK_UTF8CHAR label[] = “A Montgomery EC private key object”;
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE ecParams[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};
The EC (also related to ECDSA) key pair generation mechanism, denoted CKM_EC_KEY_PAIR_GEN, is a key pair generation mechanism that uses the method defined by the ANSI X9.62 and X9.63 standards.
The EC (also related to ECDSA) key pair generation mechanism, denoted CKM_EC_KEY_PAIR_GEN_W_EXTRA_BITS, is a key pair generation mechanism that uses the method defined by FIPS 1864 Appendix B.4.1.
These mechanisms do not have a parameter.
These mechanisms generate EC public/private key pairs with particular EC domain parameters, as specified in the CKA_EC_PARAMS attribute of the template for the public key. Note that this version of Cryptoki does not include a mechanism for generating these EC domain parameters.
These mechanism contribute the CKA_CLASS, CKA_KEY_TYPE, and CKA_EC_POINT attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_EC_PARAMS and CKA_VALUE attributes to the new private key. Other attributes supported by the EC public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively. For example, if a Cryptoki library supports only ECDSA using a field of characteristic 2 which has between 2^{200} and 2^{300} elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2^{200} consists of a 1 bit followed by 200 0 bits. It is therefore a 201bit number. Similarly, 2^{300} is a 301bit number).
The Edwards EC key pair generation mechanism, denoted CKM_EC_EDWARDS_KEY_PAIR_GEN, is a key pair generation mechanism for EC keys over curves represented in Edwards form.
This mechanism does not have a parameter.
The mechanism can only generate EC public/private key pairs over the curves edwards25519 and edwards448 as defined in RFC 8032 or the curves idEd25519 and idEd448 as defined in RFC 8410. These curves can only be specified in the CKA_EC_PARAMS attribute of the template for the public key using the curveName or the oID methods. Attempts to generate keys over these curves using any other EC key pair generation mechanism will fail with CKR_CURVE_NOT_SUPPORTED.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_EC_POINT attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_EC_PARAMS and CKA_VALUE attributes to the new private key. Other attributes supported by the Edwards EC public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively. For this mechanism, the only allowed values are 255 and 448 as RFC 8032 only defines curves of these two sizes. A Cryptoki implementation may support one or both of these curves and should set the ulMinKeySize and ulMaxKeySize fields accordingly.
The Montgomery EC key pair generation mechanism, denoted CKM_EC_MONTGOMERY_KEY_PAIR_GEN, is a key pair generation mechanism for EC keys over curves represented in Montgomery form.
This mechanism does not have a parameter.
The mechanism can only generate Montgomery EC public/private key pairs over the curves curve25519 and curve448 as defined in RFC 7748 or the curves idX25519 and idX448 as defined in RFC 8410. These curves can only be specified in the CKA_EC_PARAMS attribute of the template for the public key using the curveName or oId methods. Attempts to generate keys over these curves using any other EC key pair generation mechanism will fail with CKR_CURVE_NOT_SUPPORTED.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_EC_POINT attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_EC_PARAMS and CKA_VALUE attributes to the new private key. Other attributes supported by the EC public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively. For this mechanism, the only allowed values are 255 and 448 as RFC 7748 only defines curves of these two sizes. A Cryptoki implementation may support one or both of these curves and should set the ulMinKeySize and ulMaxKeySize fields accordingly.
Refer section 2.3.1 for signature encoding.
The ECDSA without hashing mechanism, denoted CKM_ECDSA, is a mechanism for singlepart signatures and verification for ECDSA. (This mechanism corresponds only to the part of ECDSA that processes the hash value, which should not be longer than 1024 bits; it does not compute the hash value.)
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 40, ECDSA without hashing: Key and Data Length
Function 
Key type 
Input length 
Output length 
C_Sign^{1} 
ECDSA private key 
any^{3} 
2nLen 
C_Verify^{1} 
ECDSA public key 
any^{3}, £2nLen ^{2} 
N/A 
^{1} Singlepart operations only.
2 Data length, signature length.
3 Input the entire raw digest. Internally, this will be truncated to the appropriate number of bits.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively. For example, if a Cryptoki library supports only ECDSA using a field of characteristic 2 which has between 2^{200} and 2^{300} elements (inclusive), then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2^{200} consists of a 1 bit followed by 200 0 bits. It is therefore a 201bit number. Similarly, 2^{300} is a 301bit number).
Refer to section 2.3.1 for signature encoding.
The ECDSA with SHA1, SHA224, SHA384, SHA512, SHA3224, SHA3256, SHA3384, SHA3512 mechanism, denoted CKM_ECDSA_[SHA1SHA224SHA384SHA512SHA3_224SHA3_256SHA3_384SHA3_512] respectively, is a mechanism for single and multiplepart signatures and verification for ECDSA. This mechanism computes the entire ECDSA specification, including the hashing with SHA1, SHA224, SHA384, SHA512, SHA3224, SHA3256, SHA3384, SHA3512 respectively.
This mechanism does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 41, ECDSA with hashing: Key and Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
ECDSA private key 
any 
2nLen 
C_Verify 
ECDSA public key 
any, £2nLen^{ 2} 
N/A 
^{2} Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively. For example, if a Cryptoki library supports only ECDSA using a field of characteristic 2 which has between 2^{200} and 2^{300} elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2^{200} consists of a 1 bit followed by 200 0 bits. It is therefore a 201bit number. Similarly, 2^{300} is a 301bit number).
The EdDSA mechanism, denoted CKM_EDDSA, is a mechanism for singlepart and multipart signatures and verification for EdDSA. This mechanism implements the five EdDSA signature schemes defined in RFC 8032 and RFC 8410.
For curves according to RFC 8032, this mechanism has an optional parameter, a CK_EDDSA_PARAMS structure. The absence or presence of the parameter as well as its content is used to identify which signature scheme is to be used. The following table enumerates the five signature schemes defined in RFC 8032 and all supported permutations of the mechanism parameter and its content.
Table 42, Mapping to RFC 8032 Signature Schemes
Signature Scheme 
Mechanism Param 
phFlag 
Context Data 
Ed25519 
Not Required 
N/A 
N/A 
Ed25519ctx 
Required 
False 
Optional 
Ed25519ph 
Required 
True 
Optional 
Ed448 
Required 
False 
Optional 
Ed448ph 
Required 
True 
Optional 
For curves according to RFC 8410, the mechanism is implicitly given by the curve, which is EdDSA in pure mode.
Constraints on key types and the length of data are summarized in the following table:
Table 43, EdDSA: Key and Data Length
Function 
Key type 
Input length 
Output length 
C_Sign 
CKK_EC_EDWARDS private key 
any 
2bLen 
C_Verify 
CKK_EC_EDWARDS public key 
any, £2bLen ^{2} 
N/A 
2 Data length, signature length.
Note that for EdDSA in pure mode, Ed25519 and Ed448 the data must be processed twice. Therefore, a token might need to cache all the data, especially when used with C_SignUpdate/C_VerifyUpdate. If tokens are unable to do so they can return CKR_TOKEN_RESOURCE_EXCEEDED.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively. For this mechanism, the only allowed values are 255 and 448 as RFC 8032and RFC 8410 only define curves of these two sizes. A Cryptoki implementation may support one or both of these curves and should set the ulMinKeySize and ulMaxKeySize fields accordingly.
The XEdDSA mechanism, denoted CKM_XEDDSA, is a mechanism for singlepart signatures and verification for XEdDSA. This mechanism implements the XEdDSA signature scheme defined in [XEDDSA]. CKM_XEDDSA operates on CKK_EC_MONTGOMERY type EC keys, which allows these keys to be used both for signing/verification and for DiffieHellman style keyexchanges. This double use is necessary for the Extended Triple DiffieHellman where the longterm identity key is used to sign shortterm keys and also contributes to the DH keyexchange.
This mechanism has a parameter, a CK_XEDDSA_PARAMS structure.
Table 44, XEdDSA: Key and Data Length
Function 
Key type 
Input length 
Output length 
C_Sign^{1} 
CKK_EC_MONTGOMERY private key 
any^{3} 
2b 
C_Verify^{1} 
CKK_EC_MONTGOMERY public key 
any^{3}, £2b ^{2} 
N/A 
2 Data length, signature length.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively. For this mechanism, the only allowed values are 255 and 448 as [XEDDSA] only defines curves of these two sizes. A Cryptoki implementation may support one or both of these curves and should set the ulMinKeySize and ulMaxKeySize fields accordingly.
¨ CK_EDDSA_PARAMS, CK_EDDSA_PARAMS_PTR
CK_EDDSA_PARAMS is a structure that provides the parameters for the CKM_EDDSA signature mechanism. The structure is defined as follows:
typedef struct CK_EDDSA_PARAMS {
CK_BBOOL phFlag;
CK_ULONG ulContextDataLen;
CK_BYTE_PTR pContextData;
} CK_EDDSA_PARAMS;
The fields of the structure have the following meanings:
phFlag a Boolean value which indicates if Prehashed variant of EdDSA should used
ulContextDataLen the length in bytes of the context data where 0 <= ulContextDataLen <= 255.
pContextData context data shared between the signer and verifier
CK_EDDSA_PARAMS_PTR is a pointer to a CK_EDDSA_PARAMS.
¨ CK_XEDDSA_PARAMS, CK_XEDDSA_PARAMS_PTR
CK_XEDDSA_PARAMS is a structure that provides the parameters for the CKM_XEDDSA signature mechanism. The structure is defined as follows:
typedef struct CK_XEDDSA_PARAMS {
CK_XEDDSA_HASH_TYPE hash;
} CK_XEDDSA_PARAMS;
The fields of the structure have the following meanings:
hash a Hash mechanism to be used by the mechanism.
CK_XEDDSA_PARAMS_PTR is a pointer to a CK_XEDDSA_PARAMS.
¨ CK_XEDDSA_HASH_TYPE, CK_XEDDSA_HASH_TYPE_PTR
CK_XEDDSA_HASH_TYPE is used to indicate the hash function used in XEDDSA. It is defined as follows:
typedef CK_ULONG CK_XEDDSA_HASH_TYPE;
The following table lists the defined functions.
Table 45, EC: Key Derivation Functions
Source Identifier 
CKM_BLAKE2B_256 
CKM_BLAKE2B_512 
CKM_SHA3_256 
CKM_SHA3_512 
CKM_SHA256 
CKM_SHA512 
CK_XEDDSA_HASH_TYPE_PTR is a pointer to a CK_XEDDSA_HASH_TYPE.
¨ CK_EC_KDF_TYPE, CK_EC_KDF_TYPE_PTR
CK_EC_KDF_TYPE is used to indicate the Key Derivation Function (KDF) applied to derive keying data from a shared secret. The key derivation function will be used by the EC key agreement schemes. It is defined as follows:
typedef CK_ULONG CK_EC_KDF_TYPE;
The following table lists the defined functions.
Table 46, EC: Key Derivation Functions
Source Identifier 
CKD_NULL 
CKD_SHA1_KDF 
CKD_SHA224_KDF 
CKD_SHA256_KDF 
CKD_SHA384_KDF 
CKD_SHA512_KDF 
CKD_SHA3_256_KDF 
CKD_SHA3_384_KDF 
CKD_SHA3_512_KDF 
CKD_SHA1_KDF_SP800 
CKD_SHA224_KDF_SP800 
CKD_SHA256_KDF_SP800 
CKD_SHA384_KDF_SP800 
CKD_SHA512_KDF_SP800 
CKD_SHA3_224_KDF_SP800 
CKD_SHA3_256_KDF_SP800 
CKD_SHA3_384_KDF_SP800 
CKD_SHA3_512_KDF_SP800 
CKD_BLAKE2B_160_KDF 
CKD_BLAKE2B_256_KDF 
CKD_BLAKE2B_384_KDF 
CKD_BLAKE2B_512_KDF 
The key derivation function CKD_NULL produces a raw shared secret value without applying any key derivation function.
The key derivation functions CKD_[SHA1SHA224SHA384SHA512SHA3_224SHA3_256SHA3_384SHA3_512]_KDF, which are based on SHA1, SHA224, SHA384, SHA512, SHA3224, SHA3256, SHA3384, SHA3512 respectively, derive keying data from the shared secret value as defined in [ANSI X9.63].
The key derivation functions CKD_[SHA1SHA224SHA384SHA512SHA3_224SHA3_256SHA3_384SHA3_512]_KDF_SP800, which are based on SHA1, SHA224, SHA384, SHA512, SHA3224, SHA3256, SHA3384, SHA3512 respectively, derive keying data from the shared secret value as defined in [FIPS SP80056A] section 5.8.1.1.
The key derivation functions CKD_BLAKE2B_[160256384512]_KDF, which are based on the Blake2b family of hashes, derive keying data from the shared secret value as defined in [FIPS SP80056A] section 5.8.1.1. CK_EC_KDF_TYPE_PTR is a pointer to a CK_EC_KDF_TYPE.
¨ CK_ECDH1_DERIVE_PARAMS, CK_ECDH1_DERIVE_PARAMS_PTR
CK_ECDH1_DERIVE_PARAMS is a structure that provides the parameters for the CKM_ECDH1_DERIVE and CKM_ECDH1_COFACTOR_DERIVE key derivation mechanisms, where each party contributes one key pair. The structure is defined as follows:
typedef struct CK_ECDH1_DERIVE_PARAMS {
CK_EC_KDF_TYPE kdf;
CK_ULONG ulSharedDataLen;
CK_BYTE_PTR pSharedData;
CK_ULONG ulPublicDataLen;
CK_BYTE_PTR pPublicData;
} CK_ECDH1_DERIVE_PARAMS;
The fields of the structure have the following meanings:
kdf key derivation function used on the shared secret value
ulSharedDataLen the length in bytes of the shared info
pSharedData some data shared between the two parties
ulPublicDataLen the length in bytes of the other party’s EC public key
pPublicData^{[1]} pointer to other party’s EC public key value. A token MUST be able to accept this value encoded as a raw octet string (as per section A.5.2 of [ANSI X9.62]). A token MAY, in addition, support accepting this value as a DERencoded ECPoint (as per section E.6 of [ANSI X9.62]) i.e. the same as a CKA_EC_POINT encoding. The calling application is responsible for converting the offered public key to the compressed or uncompressed forms of these encodings if the token does not support the offered form.
With the key derivation function CKD_NULL, pSharedData must be NULL and ulSharedDataLen must be zero. With the key derivation functions CKD_[SHA1SHA224SHA384SHA512SHA3_224SHA3_256SHA3_384SHA3_512]_KDF, CKD_[SHA1SHA224SHA384SHA512SHA3_224SHA3_256SHA3_384SHA3_512]_KDF_SP800, an optional pSharedData may be supplied, which consists of some data shared by the two parties intending to share the shared secret. Otherwise, pSharedData must be NULL and ulSharedDataLen must be zero.
CK_ECDH1_DERIVE_PARAMS_PTR is a pointer to a CK_ECDH1_DERIVE_PARAMS.
¨ CK_ECDH2_DERIVE_PARAMS, CK_ECDH2_DERIVE_PARAMS_PTR
CK_ECDH2_DERIVE_PARAMS is a structure that provides the parameters to the CKM_ECMQV_DERIVE key derivation mechanism, where each party contributes two key pairs. The structure is defined as follows:
typedef struct CK_ECDH2_DERIVE_PARAMS {
CK_EC_KDF_TYPE kdf;
CK_ULONG ulSharedDataLen;
CK_BYTE_PTR pSharedData;
CK_ULONG ulPublicDataLen;
CK_BYTE_PTR pPublicData;
CK_ULONG ulPrivateDataLen;
CK_OBJECT_HANDLE hPrivateData;
CK_ULONG ulPublicDataLen2;
CK_BYTE_PTR pPublicData2;
} CK_ECDH2_DERIVE_PARAMS;
The fields of the structure have the following meanings:
kdf key derivation function used on the shared secret value
ulSharedDataLen the length in bytes of the shared info
pSharedData some data shared between the two parties
ulPublicDataLen the length in bytes of the other party’s first EC public key
pPublicData pointer to other party’s first EC public key value. Encoding rules are as per pPublicData of CK_ECDH1_DERIVE_PARAMS
ulPrivateDataLen the length in bytes of the second EC private key
hPrivateData key handle for second EC private key value
ulPublicDataLen2 the length in bytes of the other party’s second EC public key
pPublicData2 pointer to other party’s second EC public key value. Encoding rules are as per pPublicData of CK_ECDH1_DERIVE_PARAMS
With the key derivation function CKD_NULL, pSharedData must be NULL and ulSharedDataLen must be zero. With the key derivation function CKD_SHA1_KDF, an optional pSharedData may be supplied, which consists of some data shared by the two parties intending to share the shared secret. Otherwise, pSharedData must be NULL and ulSharedDataLen must be zero.
CK_ECDH2_DERIVE_PARAMS_PTR is a pointer to a CK_ECDH2_DERIVE_PARAMS.
¨ CK_ECMQV_DERIVE_PARAMS, CK_ECMQV_DERIVE_PARAMS_PTR
CK_ECMQV_DERIVE_PARAMS is a structure that provides the parameters to the CKM_ECMQV_DERIVE key derivation mechanism, where each party contributes two key pairs. The structure is defined as follows:
typedef struct CK_ECMQV_DERIVE_PARAMS {
CK_EC_KDF_TYPE kdf;
CK_ULONG ulSharedDataLen;
CK_BYTE_PTR pSharedData;
CK_ULONG ulPublicDataLen;
CK_BYTE_PTR pPublicData;
CK_ULONG ulPrivateDataLen;
CK_OBJECT_HANDLE hPrivateData;
CK_ULONG ulPublicDataLen2;
CK_BYTE_PTR pPublicData2;
} CK_ECMQV_DERIVE_PARAMS;
The fields of the structure have the following meanings:
kdf key derivation function used on the shared secret value
ulSharedDataLen the length in bytes of the shared info
pSharedData some data shared between the two parties
ulPublicDataLen the length in bytes of the other party’s first EC public key
pPublicData pointer to other party’s first EC public key value. Encoding rules are as per pPublicData of CK_ECDH1_DERIVE_PARAMS
ulPrivateDataLen the length in bytes of the second EC private key
hPrivateData key handle for second EC private key value
ulPublicDataLen2 the length in bytes of the other party’s second EC public key
pPublicData2 pointer to other party’s second EC public key value. Encoding rules are as per pPublicData of CK_ECDH1_DERIVE_PARAMS
publicKey Handle to the first party’s ephemeral public key
With the key derivation function CKD_NULL, pSharedData must be NULL and ulSharedDataLen must be zero. With the key derivation functions CKD_[SHA1SHA224SHA384SHA512SHA3_224SHA3_256SHA3_384SHA3_512]_KDF, CKD_[SHA1SHA224SHA384SHA512SHA3_224SHA3_256SHA3_384SHA3_512]_KDF_SP800, an optional pSharedData may be supplied, which consists of some data shared by the two parties intending to share the shared secret. Otherwise, pSharedData must be NULL and ulSharedDataLen must be zero.
CK_ECMQV_DERIVE_PARAMS_PTR is a pointer to a CK_ECMQV_DERIVE_PARAMS.
The elliptic curve DiffieHellman (ECDH) key derivation mechanism, denoted CKM_ECDH1_DERIVE, is a mechanism for key derivation based on the DiffieHellman version of the elliptic curve key agreement scheme, as defined in ANSI X9.63, where each party contributes one key pair all using the same EC domain parameters.
It has a parameter, a CK_ECDH1_DERIVE_PARAMS structure.
This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively. For example, if a Cryptoki library supports only EC using a field of characteristic 2 which has between 2^{200} and 2^{300} elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2^{200} consists of a 1 bit followed by 200 0 bits. It is therefore a 201bit number. Similarly, 2^{300} is a 301bit number).
Constraints on key types are summarized in the following table:
Table 47: ECDH: Allowed Key Types
Function 
Key type 
C_Derive 
CKK_EC or CKK_EC_MONTGOMERY 
The elliptic curve DiffieHellman (ECDH) with cofactor key derivation mechanism, denoted CKM_ECDH1_COFACTOR_DERIVE, is a mechanism for key derivation based on the cofactor DiffieHellman version of the elliptic curve key agreement scheme, as defined in ANSI X9.63, where each party contributes one key pair all using the same EC domain parameters. Cofactor multiplication is computationally efficient and helps to prevent security problems like small group attacks.
It has a parameter, a CK_ECDH1_DERIVE_PARAMS structure.
This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively. For example, if a Cryptoki library supports only EC using a field of characteristic 2 which has between 2^{200} and 2^{300} elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2^{200} consists of a 1 bit followed by 200 0 bits. It is therefore a 201bit number. Similarly, 2^{300} is a 301bit number).
Constraints on key types are summarized in the following table:
Table 48: ECDH with cofactor: Allowed Key Types
Function 
Key type 
C_Derive 
CKK_EC 
The elliptic curve MenezesQuVanstone (ECMQV) key derivation mechanism, denoted CKM_ECMQV_DERIVE, is a mechanism for key derivation based the MQV version of the elliptic curve key agreement scheme, as defined in ANSI X9.63, where each party contributes two key pairs all using the same EC domain parameters.
It has a parameter, a CK_ECMQV_DERIVE_PARAMS structure.
This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the minimum and maximum supported number of bits in the field sizes, respectively. For example, if a Cryptoki library supports only EC using a field of characteristic 2 which has between 2^{200} and 2^{300} elements, then ulMinKeySize = 201 and ulMaxKeySize = 301 (when written in binary notation, the number 2^{200} consists of a 1 bit followed by 200 0 bits. It is therefore a 201bit number. Similarly, 2^{300} is a 301bit number).
Constraints on key types are summarized in the following table:
Table 49: ECDH MQV: Allowed Key Types
Function 
Key type 
C_Derive 
CKK_EC 
The ECDH AES KEY WRAP mechanism, denoted CKM_ECDH_AES_KEY_WRAP, is a mechanism based on elliptic curve publickey cryptosystem and the AES key wrap mechanism. It supports singlepart key wrapping; and key unwrapping.
It has a parameter, a CK_ECDH_AES_KEY_WRAP_PARAMS structure.
The mechanism can wrap and unwrap an asymmetric target key of any length and type using an EC key.
 A temporary AES key is derived from a temporary EC key and the wrapping EC key using the CKM_ECDH1_DERIVE mechanism.
 The derived AES key is used for wrapping the target key using the CKM_AES_KEY_WRAP_KWP mechanism.
For wrapping, the mechanism 
The recommended format for an asymmetric target key being wrapped is as a PKCS8 PrivateKeyInfo
The use of Attributes in the PrivateKeyInfo structure is OPTIONAL. In case of conflicts between the object attribute template, and Attributes in the PrivateKeyInfo structure, an error should be thrown.
For unwrapping, the mechanism 
Note: since the transport key and the wrapping EC key share the same domain, the length of the public key material of the transport key is the same length of the public key material of the unwrapping EC key.
Table 50, CKM_ECDH_AES_KEY_WRAP Mechanisms vs. Functions

Functions 

Mechanism 
Encrypt & Decrypt 
Sign & Verify 
SR & VR1 
Digest 
Gen. Key/ Key Pair 
Wrap & Unwrap 
Derive 
CKM_ECDH_AES_KEY_WRAP 





ü 

1SR = SignRecover, VR = VerifyRecover 
Constraints on key types are summarized in the following table:
Table 51: ECDH AES Key Wrap: Allowed Key Types
Key type 

C_Derive 
CKK_EC or CKK_EC_MONTGOMERY 
¨ CK_ECDH_AES_KEY_WRAP_PARAMS; CK_ECDH_AES_KEY_WRAP_PARAMS_PTR
CK_ECDH_AES_KEY_WRAP_PARAMS is a structure that provides the parameters to the CKM_ECDH_AES_KEY_WRAP mechanism. It is defined as follows:
typedef struct CK_ECDH_AES_KEY_WRAP_PARAMS {
CK_ULONG ulAESKeyBits;
CK_EC_KDF_TYPE kdf;
CK_ULONG ulSharedDataLen;
CK_BYTE_PTR pSharedData;
} CK_ECDH_AES_KEY_WRAP_PARAMS;
The fields of the structure have the following meanings:
ulAESKeyBits length of the temporary AES key in bits. Can be only 128, 192 or 256.
kdf key derivation function used on the shared secret value to generate AES key.
ulSharedDataLen the length in bytes of the shared info
pSharedData Some data shared between the two parties
CK_ECDH_AES_KEY_WRAP_PARAMS_PTR is a pointer to a CK_ECDH_AES_KEY_WRAP_PARAMS.
When CKM_ECDSA is operated in FIPS mode, the curves SHALL either be NIST recommended curves (with a fixed set of domain parameters) or curves with domain parameters generated as specified by ANSI X9.64. The NIST recommended curves are:
P192, P224, P256, P384, P521
K163, B163, K233, B233
K283, B283, K409, B409
K571, B571
Table 52, DiffieHellman Mechanisms vs. Functions
This section defines the key type “CKK_DH” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of [DH] key objects.
Mechanisms:
CKM_DH_PKCS_KEY_PAIR_GEN
CKM_DH_PKCS_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
DiffieHellman public key objects (object class CKO_PUBLIC_KEY, key type CKK_DH) hold DiffieHellman public keys. The following table defines the DiffieHellman public key object attributes, in addition to the common attributes defined for this object class:
Table 53, DiffieHellman Public Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_PRIME^{1,3} 
Big integer 
Prime p 
CKA_BASE^{1,3} 
Big integer 
Base g 
CKA_VALUE^{1,4} 
Big integer 
Public value y 
 Refer to [PKCS11Base] table 11 for footnotes
The CKA_PRIME and CKA_BASE attribute values are collectively the “DiffieHellman domain parameters”. Depending on the token, there may be limits on the length of the key components. See PKCS #3 for more information on DiffieHellman keys.
The following is a sample template for creating a DiffieHellman public key object:
CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_DH;
CK_UTF8CHAR label[] = “A DiffieHellman public key object”;
CK_BYTE prime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};
X9.42 DiffieHellman public key objects (object class CKO_PUBLIC_KEY, key type CKK_X9_42_DH) hold X9.42 DiffieHellman public keys. The following table defines the X9.42 DiffieHellman public key object attributes, in addition to the common attributes defined for this object class:
Table 54, X9.42 DiffieHellman Public Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_PRIME^{1,3} 
Big integer 
Prime p (³ 1024 bits, in steps of 256 bits) 
CKA_BASE^{1,3} 
Big integer 
Base g 
CKA_SUBPRIME^{1,3} 
Big integer 
Subprime q (³ 160 bits) 
CKA_VALUE^{1,4} 
Big integer 
Public value y 
^{ Refer to [PKCS11Base] table 11 for footnotes}
The CKA_PRIME, CKA_BASE and CKA_SUBPRIME attribute values are collectively the “X9.42 DiffieHellman domain parameters”. See the ANSI X9.42 standard for more information on X9.42 DiffieHellman keys.
The following is a sample template for creating a X9.42 DiffieHellman public key object:
CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_X9_42_DH;
CK_UTF8CHAR label[] = “A X9.42 DiffieHellman public key object”;
CK_BYTE prime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_BASE, base, sizeof(base)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_VALUE, value, sizeof(value)}
};
DiffieHellman private key objects (object class CKO_PRIVATE_KEY, key type CKK_DH) hold DiffieHellman private keys. The following table defines the DiffieHellman private key object attributes, in addition to the common attributes defined for this object class:
Table 55, DiffieHellman Private Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_PRIME^{1,4,6} 
Big integer 
Prime p 
CKA_BASE^{1,4,6} 
Big integer 
Base g 
CKA_VALUE^{1,4,6,7} 
Big integer 
Private value x 
CKA_VALUE_BITS^{2,6} 
CK_ULONG 
Length in bits of private value x 
^{ Refer to [PKCS11Base] table 11 for footnotes}
The CKA_PRIME and CKA_BASE attribute values are collectively the “DiffieHellman domain parameters”. Depending on the token, there may be limits on the length of the key components. See PKCS #3 for more information on DiffieHellman keys.
Note that when generating a DiffieHellman private key, the DiffieHellman parameters are not specified in the key’s template. This is because DiffieHellman private keys are only generated as part of a DiffieHellman key pair, and the DiffieHellman parameters for the pair are specified in the template for the DiffieHellman public key.
The following is a sample template for creating a DiffieHellman private key object:
CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_DH;
CK_UTF8CHAR label[] = “A DiffieHellman private key object”;
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE prime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};
X9.42 DiffieHellman private key objects (object class CKO_PRIVATE_KEY, key type CKK_X9_42_DH) hold X9.42 DiffieHellman private keys. The following table defines the X9.42 DiffieHellman private key object attributes, in addition to the common attributes defined for this object class:
Table 56, X9.42 DiffieHellman Private Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_PRIME^{1,4,6} 
Big integer 
Prime p (³ 1024 bits, in steps of 256 bits) 
CKA_BASE^{1,4,6} 
Big integer 
Base g 
CKA_SUBPRIME^{1,4,6} 
Big integer 
Subprime q (³ 160 bits) 
CKA_VALUE^{1,4,6,7} 
Big integer 
Private value x 
^{ Refer to [PKCS11Base] table 11 for footnotes}
The CKA_PRIME, CKA_BASE and CKA_SUBPRIME attribute values are collectively the “X9.42 DiffieHellman domain parameters”. Depending on the token, there may be limits on the length of the key components. See the ANSI X9.42 standard for more information on X9.42 DiffieHellman keys.
Note that when generating a X9.42 DiffieHellman private key, the X9.42 DiffieHellman domain parameters are not specified in the key’s template. This is because X9.42 DiffieHellman private keys are only generated as part of a X9.42 DiffieHellman key pair, and the X9.42 DiffieHellman domain parameters for the pair are specified in the template for the X9.42 DiffieHellman public key.
The following is a sample template for creating a X9.42 DiffieHellman private key object:
CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_X9_42_DH;
CK_UTF8CHAR label[] = “A X9.42 DiffieHellman private key object”;
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE prime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_BASE, base, sizeof(base)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_VALUE, value, sizeof(value)}
};
DiffieHellman domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type CKK_DH) hold DiffieHellman domain parameters. The following table defines the DiffieHellman domain parameter object attributes, in addition to the common attributes defined for this object class:
Table 57, DiffieHellman Domain Parameter Object Attributes
Attribute 
Data type 
Meaning 
CKA_PRIME^{1,4} 
Big integer 
Prime p 
CKA_BASE^{1,4} 
Big integer 
Base g 
CKA_PRIME_BITS^{2,3} 
CK_ULONG 
Length of the prime value. 
^{ Refer to [PKCS11Base] table 11 for footnotes}
The CKA_PRIME and CKA_BASE attribute values are collectively the “DiffieHellman domain parameters”. Depending on the token, there may be limits on the length of the key components. See PKCS #3 for more information on DiffieHellman domain parameters.
The following is a sample template for creating a DiffieHellman domain parameter object:
CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS;
CK_KEY_TYPE keyType = CKK_DH;
CK_UTF8CHAR label[] = “A DiffieHellman domain parameters object”;
CK_BYTE prime[] = {...};
CK_BYTE base[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_BASE, base, sizeof(base)},
};
X9.42 DiffieHellman domain parameters objects (object class CKO_DOMAIN_PARAMETERS, key type CKK_X9_42_DH) hold X9.42 DiffieHellman domain parameters. The following table defines the X9.42 DiffieHellman domain parameters object attributes, in addition to the common attributes defined for this object class:
Table 58, X9.42 DiffieHellman Domain Parameters Object Attributes
Attribute 
Data type 
Meaning 
CKA_PRIME^{1,4} 
Big integer 
Prime p (³ 1024 bits, in steps of 256 bits) 
CKA_BASE^{1,4} 
Big integer 
Base g 
CKA_SUBPRIME^{1,4} 
Big integer 
Subprime q (³ 160 bits) 
CKA_PRIME_BITS^{2,3} 
CK_ULONG 
Length of the prime value. 
CKA_SUBPRIME_BITS^{2,3} 
CK_ULONG 
Length of the subprime value. 
^{ Refer to [PKCS11Base] table 11 for footnotes}
The CKA_PRIME, CKA_BASE and CKA_SUBPRIME attribute values are collectively the “X9.42 DiffieHellman domain parameters”. Depending on the token, there may be limits on the length of the domain parameters components. See the ANSI X9.42 standard for more information on X9.42 DiffieHellman domain parameters.
The following is a sample template for creating a X9.42 DiffieHellman domain parameters object:
CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS;
CK_KEY_TYPE keyType = CKK_X9_42_DH;
CK_UTF8CHAR label[] = “A X9.42 DiffieHellman domain parameters object”;
CK_BYTE prime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE subprime[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)1},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_BASE, base, sizeof(base)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
};
The PKCS #3 DiffieHellman key pair generation mechanism, denoted CKM_DH_PKCS_KEY_PAIR_GEN, is a key pair generation mechanism based on DiffieHellman key agreement, as defined in PKCS #3. This is what PKCS #3 calls “phase I”. It does not have a parameter.
The mechanism generates DiffieHellman public/private key pairs with a particular prime and base, as specified in the CKA_PRIME and CKA_BASE attributes of the template for the public key. If the CKA_VALUE_BITS attribute of the private key is specified, the mechanism limits the length in bits of the private value, as described in PKCS #3.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, and CKA_VALUE (and the CKA_VALUE_BITS attribute, if it is not already provided in the template) attributes to the new private key; other attributes required by the DiffieHellman public and private key types must be specified in the templates.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DiffieHellman prime sizes, in bits.
The PKCS #3 DiffieHellman domain parameter generation mechanism, denoted CKM_DH_PKCS_PARAMETER_GEN, is a domain parameter generation mechanism based on DiffieHellman key agreement, as defined in PKCS #3.
It does not have a parameter.
The mechanism generates DiffieHellman domain parameters with a particular prime length in bits, as specified in the CKA_PRIME_BITS attribute of the template.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, and CKA_PRIME_BITS attributes to the new object. Other attributes supported by the DiffieHellman domain parameter types may also be specified in the template, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DiffieHellman prime sizes, in bits.
The PKCS #3 DiffieHellman key derivation mechanism, denoted CKM_DH_PKCS_DERIVE, is a mechanism for key derivation based on DiffieHellman key agreement, as defined in PKCS #3. This is what PKCS #3 calls “phase II”.
It has a parameter, which is the public value of the other party in the key agreement protocol, represented as a Cryptoki “Big integer” (i.e., a sequence of bytes, mostsignificant byte first).
This mechanism derives a secret key from a DiffieHellman private key and the public value of the other party. It computes a DiffieHellman secret value from the public value and private key according to PKCS #3, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.
This mechanism has the following rules about key sensitivity and extractability[2]:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DiffieHellman prime sizes, in bits.
¨ CK_X9_42_DH_KDF_TYPE, CK_X9_42_DH_KDF_TYPE_PTR
CK_X9_42_DH_KDF_TYPE is used to indicate the Key Derivation Function (KDF) applied to derive keying data from a shared secret. The key derivation function will be used by the X9.42 DiffieHellman key agreement schemes. It is defined as follows:
typedef CK_ULONG CK_X9_42_DH_KDF_TYPE;
The following table lists the defined functions.
Table 59, X9.42 DiffieHellman Key Derivation Functions
Source Identifier 
CKD_NULL 
CKD_SHA1_KDF_ASN1 
CKD_SHA1_KDF_CONCATENATE 
The key derivation function CKD_NULL produces a raw shared secret value without applying any key derivation function whereas the key derivation functions CKD_SHA1_KDF_ASN1 and CKD_SHA1_KDF_CONCATENATE, which are both based on SHA1, derive keying data from the shared secret value as defined in the ANSI X9.42 standard.
CK_X9_42_DH_KDF_TYPE_PTR is a pointer to a CK_X9_42_DH_KDF_TYPE.
¨ CK_X9_42_DH1_DERIVE_PARAMS, CK_X9_42_DH1_DERIVE_PARAMS_PTR
CK_X9_42_DH1_DERIVE_PARAMS is a structure that provides the parameters to the CKM_X9_42_DH_DERIVE key derivation mechanism, where each party contributes one key pair. The structure is defined as follows:
typedef struct CK_X9_42_DH1_DERIVE_PARAMS {
CK_X9_42_DH_KDF_TYPE kdf;
CK_ULONG ulOtherInfoLen;
CK_BYTE_PTR pOtherInfo;
CK_ULONG ulPublicDataLen;
CK_BYTE_PTR pPublicData;
} CK_X9_42_DH1_DERIVE_PARAMS;
The fields of the structure have the following meanings:
kdf key derivation function used on the shared secret value
ulOtherInfoLen the length in bytes of the other info
pOtherInfo some data shared between the two parties
ulPublicDataLen the length in bytes of the other party’s X9.42 DiffieHellman public key
pPublicData pointer to other party’s X9.42 DiffieHellman public key value
With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero. With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by the two parties intending to share the shared secret. With the key derivation function CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some data shared by the two parties intending to share the shared secret. Otherwise, pOtherInfo must be NULL and ulOtherInfoLen must be zero.
CK_X9_42_DH1_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_DH1_DERIVE_PARAMS.
· CK_X9_42_DH2_DERIVE_PARAMS, CK_X9_42_DH2_DERIVE_PARAMS_PTR
CK_X9_42_DH2_DERIVE_PARAMS is a structure that provides the parameters to the CKM_X9_42_DH_HYBRID_DERIVE and CKM_X9_42_MQV_DERIVE key derivation mechanisms, where each party contributes two key pairs. The structure is defined as follows:
typedef struct CK_X9_42_DH2_DERIVE_PARAMS {
CK_X9_42_DH_KDF_TYPE kdf;
CK_ULONG ulOtherInfoLen;
CK_BYTE_PTR pOtherInfo;
CK_ULONG ulPublicDataLen;
CK_BYTE_PTR pPublicData;
CK_ULONG ulPrivateDataLen;
CK_OBJECT_HANDLE hPrivateData;
CK_ULONG ulPublicDataLen2;
CK_BYTE_PTR pPublicData2;
} CK_X9_42_DH2_DERIVE_PARAMS;
The fields of the structure have the following meanings:
kdf key derivation function used on the shared secret value
ulOtherInfoLen the length in bytes of the other info
pOtherInfo some data shared between the two parties
ulPublicDataLen the length in bytes of the other party’s first X9.42 DiffieHellman public key
pPublicData pointer to other party’s first X9.42 DiffieHellman public key value
ulPrivateDataLen the length in bytes of the second X9.42 DiffieHellman private key
hPrivateData key handle for second X9.42 DiffieHellman private key value
ulPublicDataLen2 the length in bytes of the other party’s second X9.42 DiffieHellman public key
pPublicData2 pointer to other party’s second X9.42 DiffieHellman public key value
With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero. With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by the two parties intending to share the shared secret. With the key derivation function CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some data shared by the two parties intending to share the shared secret. Otherwise, pOtherInfo must be NULL and ulOtherInfoLen must be zero.
CK_X9_42_DH2_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_DH2_DERIVE_PARAMS.
· CK_X9_42_MQV_DERIVE_PARAMS, CK_X9_42_MQV_DERIVE_PARAMS_PTR
CK_X9_42_MQV_DERIVE_PARAMS is a structure that provides the parameters to the CKM_X9_42_MQV_DERIVE key derivation mechanism, where each party contributes two key pairs. The structure is defined as follows:
typedef struct CK_X9_42_MQV_DERIVE_PARAMS {
CK_X9_42_DH_KDF_TYPE kdf;
CK_ULONG ulOtherInfoLen;
CK_BYTE_PTR pOtherInfo;
CK_ULONG ulPublicDataLen;
CK_BYTE_PTR pPublicData;
CK_ULONG ulPrivateDataLen;
CK_OBJECT_HANDLE hPrivateData;
CK_ULONG ulPublicDataLen2;
CK_BYTE_PTR pPublicData2;
CK_OBJECT_HANDLE publicKey;
} CK_X9_42_MQV_DERIVE_PARAMS;
The fields of the structure have the following meanings:
kdf key derivation function used on the shared secret value
ulOtherInfoLen the length in bytes of the other info
pOtherInfo some data shared between the two parties
ulPublicDataLen the length in bytes of the other party’s first X9.42 DiffieHellman public key
pPublicData pointer to other party’s first X9.42 DiffieHellman public key value
ulPrivateDataLen the length in bytes of the second X9.42 DiffieHellman private key
hPrivateData key handle for second X9.42 DiffieHellman private key value
ulPublicDataLen2 the length in bytes of the other party’s second X9.42 DiffieHellman public key
pPublicData2 pointer to other party’s second X9.42 DiffieHellman public key value
publicKey Handle to the first party’s ephemeral public key
With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero. With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by the two parties intending to share the shared secret. With the key derivation function CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some data shared by the two parties intending to share the shared secret. Otherwise, pOtherInfo must be NULL and ulOtherInfoLen must be zero.
CK_X9_42_MQV_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_MQV_DERIVE_PARAMS.
The X9.42 DiffieHellman key pair generation mechanism, denoted CKM_X9_42_DH_KEY_PAIR_GEN, is a key pair generation mechanism based on DiffieHellman key agreement, as defined in the ANSI X9.42 standard.
It does not have a parameter.
The mechanism generates X9.42 DiffieHellman public/private key pairs with a particular prime, base and subprime, as specified in the CKA_PRIME, CKA_BASE and CKA_SUBPRIME attributes of the template for the public key.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, CKA_SUBPRIME, and CKA_VALUE attributes to the new private key; other attributes required by the X9.42 DiffieHellman public and private key types must be specified in the templates.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 DiffieHellman prime sizes, in bits, for the CKA_PRIME attribute.
The X9.42 DiffieHellman domain parameter generation mechanism, denoted CKM_X9_42_DH_PARAMETER_GEN, is a domain parameters generation mechanism based on X9.42 DiffieHellman key agreement, as defined in the ANSI X9.42 standard.
It does not have a parameter.
The mechanism generates X9.42 DiffieHellman domain parameters with particular prime and subprime length in bits, as specified in the CKA_PRIME_BITS and CKA_SUBPRIME_BITS attributes of the template for the domain parameters.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, CKA_SUBPRIME, CKA_PRIME_BITS and CKA_SUBPRIME_BITS attributes to the new object. Other attributes supported by the X9.42 DiffieHellman domain parameter types may also be specified in the template for the domain parameters, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 DiffieHellman prime sizes, in bits.
The X9.42 DiffieHellman key derivation mechanism, denoted CKM_X9_42_DH_DERIVE, is a mechanism for key derivation based on the DiffieHellman key agreement scheme, as defined in the ANSI X9.42 standard, where each party contributes one key pair, all using the same X9.42 DiffieHellman domain parameters.
It has a parameter, a CK_X9_42_DH1_DERIVE_PARAMS structure.
This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. Note that in order to validate this mechanism it may be required to use the CKA_VALUE attribute as the key of a generallength MAC mechanism (e.g. CKM_SHA_1_HMAC_GENERAL) over some test data.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 DiffieHellman prime sizes, in bits, for the CKA_PRIME attribute.
The X9.42 DiffieHellman hybrid key derivation mechanism, denoted CKM_X9_42_DH_HYBRID_DERIVE, is a mechanism for key derivation based on the DiffieHellman hybrid key agreement scheme, as defined in the ANSI X9.42 standard, where each party contributes two key pair, all using the same X9.42 DiffieHellman domain parameters.
It has a parameter, a CK_X9_42_DH2_DERIVE_PARAMS structure.
This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. Note that in order to validate this mechanism it may be required to use the CKA_VALUE attribute as the key of a generallength MAC mechanism (e.g. CKM_SHA_1_HMAC_GENERAL) over some test data.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 DiffieHellman prime sizes, in bits, for the CKA_PRIME attribute.
The X9.42 DiffieHellman MenezesQuVanstone (MQV) key derivation mechanism, denoted CKM_X9_42_MQV_DERIVE, is a mechanism for key derivation based the MQV scheme, as defined in the ANSI X9.42 standard, where each party contributes two key pairs, all using the same X9.42 DiffieHellman domain parameters.
It has a parameter, a CK_X9_42_MQV_DERIVE_PARAMS structure.
This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. Note that in order to validate this mechanism it may be required to use the CKA_VALUE attribute as the key of a generallength MAC mechanism (e.g. CKM_SHA_1_HMAC_GENERAL) over some test data.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 DiffieHellman prime sizes, in bits, for the CKA_PRIME attribute.
The Extended Triple DiffieHellman mechanism described here is the one described in [SIGNAL].
Table 60, Extended Triple DiffieHellman Mechanisms vs. Functions

Functions 

Mechanism 
Encrypt & Decrypt 
Sign & Verify 
SR & VR^{1} 
Digest 
Gen.Key/ Key Pair 
Wrap & Unwrap 
Derive 
CKM_X3DH_INITIALIZE 






ü 
CKM_X3DH_RESPOND 






ü 
Mechanisms:
CKM_X3DH_INITIALIZE
CKM_X3DH_RESPOND
Extended Triple DiffieHellman uses Elliptic Curve keys in Montgomery representation (CKK_EC_MONTGOMERY). Three different kinds of keys are used, they differ in their lifespan:
Any peer intending to be contacted using X3DH must publish their socalled prekeybundle, consisting of their:
Initiating an Extended Triple DiffieHellman key exchange starts by retrieving the following required public keys (the socalled prekeybundle) of the other peer: the Identity key, the signed public Prekey, and optionally one Onetime public key.
When the necessary key material is available, the initiating party calls CKM_X3DH_INITIALIZE, also providing the following additional parameters:
· the initiators identity key
· the initiators ephemeral key (a fresh, onetime CKK_EC_MONTGOMERY type key)
CK_X3DH_INITIATE_PARAMS is a structure that provides the parameters to the CKM_X3DH_INITIALIZE key exchange mechanism. The structure is defined as follows:
typedef struct CK_X3DH_INITIATE_PARAMS {
CK_X3DH_KDF_TYPE kdf;
CK_OBJECT_HANDLE pPeer_identity;
CK_OBJECT_HANDLE pPeer_prekey;
CK_BYTE_PTR pPrekey_signature;
CK_BYTE_PTR pOnetime_key;
CK_OBJECT_HANDLE pOwn_identity;
CK_OBJECT_HANDLE pOwn_ephemeral;
} CK_X3DH_INITIATE_PARAMS;
Table 61, Extended Triple DiffieHellman Initiate Message parameters:
Parameter 
Data type 
Meaning 
kdf 
CK_X3DH_KDF_TYPE 
Key derivation function 
pPeer_identity 
Key handle 
Peers public Identity key (from the prekeybundle) 
pPeer_prekey 
Key Handle 
Peers public prekey (from the prekeybundle) 
pPrekey_signature 
Byte array 
XEDDSA signature of PEER_PREKEY (from prekeybundle) 
pOnetime_key 
Byte array 
Optional onetime public prekey of peer (from the prekeybundle) 
pOwn_identity 
Key Handle 
Initiators Identity key 
pOwn_ephemeral 
Key Handle 
Initiators ephemeral key 
Responding an Extended Triple DiffieHellman key exchange is done by executing a CKM_X3DH_RESPOND mechanism. CK_X3DH_RESPOND_PARAMS is a structure that provides the parameters to the CKM_X3DH_RESPOND key exchange mechanism. All these parameter should be supplied by the Initiator in a message to the responder. The structure is defined as follows:
typedef struct CK_X3DH_RESPOND_PARAMS {
CK_X3DH_KDF_TYPE kdf;
CK_BYTE_PTR pIdentity_id;
CK_BYTE_PTR pPrekey_id;
CK_BYTE_PTR pOnetime_id;
CK_OBJECT_HANDLE pInitiator_identity;
CK_BYTE_PTR pInitiator_ephemeral;
} CK_X3DH_RESPOND_PARAMS;
Table 62, Extended Triple DiffieHellman 1st Message parameters:
Parameter 
Data type 
Meaning 
kdf 
CK_X3DH_KDF_TYPE 
Key derivation function 
pIdentity_id 
Byte array 
Peers public Identity key identifier (from the prekeybundle) 
pPrekey_id 
Byte array 
Peers public prekey identifier (from the prekeybundle) 
pOnetime_id 
Byte array 
Optional onetime public prekey of peer (from the prekeybundle) 
pInitiator_identity 
Key handle 
Initiators Identity key 
pInitiator_ephemeral 
Byte array 
Initiators ephemeral key 
Where the *_id fields are identifiers marking which key has been used from the prekeybundle, these identifiers could be the keys themselves.
This mechanism has the following rules about key sensitivity and extractability[3]:
1 The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
2 If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
3 Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
· CK_X3DH_KDF_TYPE, CK_X3DH_KDF_TYPE_PTR
CK_X3DH_KDF_TYPE is used to indicate the Key Derivation Function (KDF) applied to derive keying data from a shared secret. The key derivation function will be used by the X3DH key agreement schemes. It is defined as follows:
typedef CK_ULONG CK_X3DH_KDF_TYPE;
The following table lists the defined functions.
Table 63, X3DH: Key Derivation Functions
Source Identifier 
CKD_NULL 
CKD_BLAKE2B_256_KDF 
CKD_BLAKE2B_512_KDF 
CKD_SHA3_256_KDF 
CKD_SHA256_KDF 
CKD_SHA3_512_KDF 
CKD_SHA512_KDF 
The Double Ratchet is a key management algorithm managing the ongoing renewal and maintenance of shortlived session keys providing forward secrecy and breakin recovery for encrypt/decrypt operations. The algorithm is described in [DoubleRatchet]. The Signal protocol uses X3DH to exchange a shared secret in the first step, which is then used to derive a Double Ratchet secret key.
Table 64, Double Ratchet Mechanisms vs. Functions

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 
✓ 




✓ 

This section defines the key type “CKK_X2RATCHET” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.
Mechanisms:
CKM_X2RATCHET_INITIALIZE
CKM_X2RATCHET_RESPOND
CKM_X2RATCHET_ENCRYPT
CKM_X2RATCHET_DECRYPT
Double Ratchet secret key objects (object class CKO_SECRET_KEY, key type CKK_X2RATCHET) hold Double Ratchet keys. Double Ratchet secret keys can only be derived from shared secret keys using the mechanism CKM_X2RATCHET_INITIALIZE or CKM_X2RATCHET_RESPOND. In the Signal protocol these are seeded with the shared secret derived from an Extended Triple DiffieHellman [X3DH] keyexchange. The following table defines the Double Ratchet secret key object attributes, in addition to the common attributes defined for this object class:
Table 65, Double Ratchet Secret Key Object Attributes
Attribute 
Data type 
Meaning 
CKA_X2RATCHET_RK 
Byte array 
Root key 
CKA_X2RATCHET_HKS 
Byte array 
Sender Header key 
CKA_X2RATCHET_HKR 
Byte array 
Receiver Header key 
CKA_X2RATCHET_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 outoforder keys do we store 
CKA_X2RATCHET_BAG 
Byte array 
Outoforder keys 
The Double Ratchet key derivation mechanisms depend on who is the initiating party, and who the receiving, denoted CKM_X2RATCHET_INITIALIZE and CKM_X2RATCHET_RESPOND, are the key derivation mechanisms for the Double Ratchet. Usually the keys are derived from a shared secret by executing a X3DH key exchange.
The mechanism contr