PKCS #11 Cryptographic Token Interface Base Specification Version 2.40
OASIS Standard
14 April 2015
Specification URIs
This version:
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.doc (Authoritative)
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.pdf
Previous version:
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/cs01/pkcs11-base-v2.40-cs01.doc (Authoritative)
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/cs01/pkcs11-base-v2.40-cs01.html
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/cs01/pkcs11-base-v2.40-cs01.pdf
Latest version:
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.doc (Authoritative)
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.pdf
Technical Committee:
Chairs:
Robert Griffin (robert.griffin@rsa.com), EMC Corporation
Valerie Fenwick (valerie.fenwick@oracle.com), Oracle
Editors:
Susan Gleeson (susan.gleeson@oracle.com), Oracle
Chris Zimman (chris@wmpp.com), Individual
Related work:
This specification 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 membership of OASIS on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=pkcs11#technical.
TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/pkcs11/.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (https://www.oasis-open.org/committees/pkcs11/ipr.php).
Citation format:
When referencing this specification the following citation format should be used:
[PKCS11-base-v2.40]
PKCS #11 Cryptographic Token Interface Base Specification Version 2.40. Edited by Susan Gleeson and Chris Zimman. 14 April 2015. OASIS Standard. http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html.
Notices
Copyright © OASIS Open 2015. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.
Table of Contents
2 Platform- and compiler-dependent directives for C or C++
4.1 Creating, modifying, and copying objects
4.3.4 Monotonic Counter Objects
4.6.3 X.509 public key certificate objects
4.6.4 WTLS public key certificate objects
4.6.5 X.509 attribute certificate objects
5.1.1 Universal Cryptoki function return values
5.1.2 Cryptoki function return values for functions that use a session handle
5.1.3 Cryptoki function return values for functions that use a token
5.1.4 Special return value for application-supplied callbacks
5.1.5 Special return values for mutex-handling functions
5.1.6 All other Cryptoki function return values.
5.1.7 More on relative priorities of Cryptoki errors
5.2 Conventions for functions returning output in a variable-length buffer
5.3 Disclaimer concerning sample code
5.5 Slot and token management functions
5.6 Session management functions
5.7 Object management functions
5.10 Message digesting functions
5.11 Signing and MACing functions
5.12 Dual-function cryptographic functions.
5.14 Random number generation functions
5.15 Parallel function management functions.
5.16.2 Vendor-defined callbacks
6 PKCS #11 Implementation Conformance
Appendix B. Manifest constants
This document describes the basic PKCS#11 token interface and token behavior.
The PKCS#11 standard specifies an application programming interface (API), called “Cryptoki,” for devices that hold cryptographic information and perform cryptographic functions. Cryptoki follows a simple object based approach, addressing the goals of technology independence (any kind of device) and resource sharing (multiple applications accessing multiple devices), presenting to applications a common, logical view of the device called a “cryptographic token”.
This document specifies the data types and functions available to an application requiring cryptographic services using the ANSI C programming language. The supplier of a Cryptoki library implementation typically provides these data types and functions via ANSI C header files. Generic ANSI C header files for Cryptoki are available from the PKCS#11 web page. This document and up-to-date errata for Cryptoki will also be available from the same place.
Additional documents may provide a generic, language-independent Cryptoki interface and/or bindings between Cryptoki and other programming languages.
Cryptoki isolates an application from the details of the cryptographic device. The application does not have to change to interface to a different type of device or to run in a different environment; thus, the application is portable. How Cryptoki provides this isolation is beyond the scope of this document, although some conventions for the support of multiple types of device will be addressed here and possibly in a separate document.
Details of cryptographic mechanisms (algorithms) may be found in the associated PKCS#11 Mechanisms documents.
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:
API Application programming interface.
Application Any computer program that calls the Cryptoki interface.
ASN.1 Abstract Syntax Notation One, as defined in X.680.
Attribute A characteristic of an object.
BER Basic Encoding Rules, as defined in X.690.
CBC Cipher-Block Chaining mode, as defined in FIPS PUB 81.
Certificate A signed message binding a subject name and a public key, or a subject name and a set of attributes.
CMS Cryptographic Message Syntax (see RFC 5652)
Cryptographic Device A device storing cryptographic information and possibly performing cryptographic functions. May be implemented as a smart card, smart disk, PCMCIA card, or with some other technology, including software-only.
Cryptoki The Cryptographic Token Interface defined in this standard.
Cryptoki library A library that implements the functions specified in this standard.
DER Distinguished Encoding Rules, as defined in X.690.
DES Data Encryption Standard, as defined in FIPS PUB 46-3.
DSA Digital Signature Algorithm, as defined in FIPS PUB 186-4.
EC Elliptic Curve
ECB Electronic Codebook mode, as defined in FIPS PUB 81.
IV Initialization Vector.
MAC Message Authentication Code.
Mechanism A process for implementing a cryptographic operation.
Object An item that is stored on a token. May be data, a certificate, or a key.
PIN Personal Identification Number.
PKCS Public-Key Cryptography Standards.
PRF Pseudo random function.
PTD Personal Trusted Device, as defined in MeT-PTD
RSA The RSA public-key cryptosystem.
Reader The means by which information is exchanged with a device.
Session A logical connection between an application and a token.
Slot A logical reader that potentially contains a token.
SSL The Secure Sockets Layer 3.0 protocol.
Subject Name The X.500 distinguished name of the entity to which a key is assigned.
SO A Security Officer user.
TLS Transport Layer Security.
Token The logical view of a cryptographic device defined by Cryptoki.
User The person using an application that interfaces to Cryptoki.
UTF-8 Universal Character Set (UCS) transformation format (UTF) that represents ISO 10646 and UNICODE strings with a variable number of octets.
WIM Wireless Identification Module.
WTLS Wireless Transport Layer Security.
The following symbols are used in this standard:
Table 1, Symbols
|
Symbol |
Definition |
|
N/A |
Not applicable |
|
R/O |
Read-only |
|
R/W |
Read/write |
The following prefixes are used in this standard:
Table 2, Prefixes
|
Prefix |
Description |
|
C_ |
Function |
|
CK_ |
Data type or general constant |
|
CKA_ |
Attribute |
|
CKC_ |
Certificate type |
|
CKD_ |
Key derivation function |
|
CKF_ |
Bit flag |
|
CKG_ |
Mask generation function |
|
CKH_ |
Hardware feature type |
|
CKK_ |
Key type |
|
CKM_ |
Mechanism type |
|
CKN_ |
Notification |
|
CKO_ |
Object class |
|
CKP_ |
Pseudo-random function |
|
CKS_ |
Session state |
|
CKR_ |
Return value |
|
CKU_ |
User type |
|
CKZ_ |
Salt/Encoding parameter source |
|
h |
a handle |
|
ul |
a CK_ULONG |
|
p |
a pointer |
|
pb |
a pointer to a CK_BYTE |
|
ph |
a pointer to a handle |
|
pul |
a pointer to a CK_ULONG |
Cryptoki is based on ANSI C types, and defines the following data types:
/* an unsigned 8-bit value */
typedef unsigned char CK_BYTE;
/* an unsigned 8-bit character */
typedef CK_BYTE CK_CHAR;
/* an 8-bit UTF-8 character */
typedef CK_BYTE CK_UTF8CHAR;
/* a BYTE-sized Boolean flag */
typedef CK_BYTE CK_BBOOL;
/* an unsigned value, at least 32 bits long */
typedef unsigned long int CK_ULONG;
/* a signed value, the same size as a CK_ULONG */
typedef long int CK_LONG;
/* at least 32 bits; each bit is a Boolean flag */
typedef CK_ULONG CK_FLAGS;
Cryptoki also uses pointers to some of these data types, as well as to the type void, which are implementation-dependent. These pointer types are:
CK_BYTE_PTR /* Pointer to a CK_BYTE */
CK_CHAR_PTR /* Pointer to a CK_CHAR */
CK_UTF8CHAR_PTR /* Pointer to a CK_UTF8CHAR */
CK_ULONG_PTR /* Pointer to a CK_ULONG */
CK_VOID_PTR /* Pointer to a void */
Cryptoki also defines a pointer to a CK_VOID_PTR, which is implementation-dependent:
CK_VOID_PTR_PTR /* Pointer to a CK_VOID_PTR */
In addition, Cryptoki defines a C-style NULL pointer, which is distinct from any valid pointer:
NULL_PTR /* A NULL pointer */
It follows that many of the data and pointer types will vary somewhat from one environment to another (e.g., a CK_ULONG will sometimes be 32 bits, and sometimes perhaps 64 bits). However, these details should not affect an application, assuming it is compiled with Cryptoki header files consistent with the Cryptoki library to which the application is linked.
All numbers and values expressed in this document are decimal, unless they are preceded by “0x”, in which case they are hexadecimal values.
The CK_CHAR data type holds characters from the following table, taken from ANSI C:
Table 3, Character Set
|
Category |
Characters |
|
Letters |
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z |
|
Numbers |
0 1 2 3 4 5 6 7 8 9 |
|
Graphic characters |
! “ # % & ‘ ( ) * + , - . / : ; < = > ? [ \ ] ^ _ { | } ~ |
|
Blank character |
‘ ‘ |
The CK_UTF8CHAR data type holds UTF-8 encoded Unicode characters as specified in RFC2279. UTF-8 allows internationalization while maintaining backward compatibility with the Local String definition of PKCS #11 version 2.01.
In Cryptoki, the CK_BBOOL data type is a Boolean type that can be true or false. A zero value means false, and a nonzero value means true. Similarly, an individual bit flag, CKF_..., can also be set (true) or unset (false). For convenience, Cryptoki defines the following macros for use with values of type CK_BBOOL:
#define CK_FALSE 0
#define CK_TRUE 1
For backwards compatibility, header files for this version of Cryptoki also define TRUE and FALSE as (CK_DISABLE_TRUE_FALSE may be set by the application vendor):
#ifndef CK_DISABLE_TRUE_FALSE
#ifndef FALSE
#define FALSE CK_FALSE
#endif
#ifndef TRUE
#define TRUE CK_TRUE
#endif
#endif
[FIPS PUB 46-3] NIST. FIPS 46-3: Data Encryption Standard. October 1999.
URL: http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf
[FIPS PUB 81] NIST. FIPS 81: DES Modes of Operation. December 1980.
URL: http://csrc.nist.gov/publications/fips/fips81/fips81.htm
[FIPS PUB 186-4] NIST. FIPS 186-4: Digital Signature Standard. July, 2013.
URL: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf
[PKCS11-Curr] PKCS #11 Cryptographic Token Interface Current Mechanisms Specification Version 2.40. Edited by Susan Gleeson and Chris Zimman. 14 April 2015. OASIS Standard. http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/os/pkcs11-curr-v2.40-os.html. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/pkcs11-curr-v2.40.html.
[PKCS11-Hist] PKCS #11 Cryptographic Token Interface Historical Mechanisms Specification Version 2.40. Edited by Susan Gleeson and Chris Zimman. 14 April 2015. OASIS Standard. http://docs.oasis-open.org/pkcs11/pkcs11-hist/v2.40/os/pkcs11-hist-v2.40-os.html. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-hist/v2.40/pkcs11-hist-v2.40.html.
[PKCS11-Prof] PKCS #11 Cryptographic Token Interface Profiles Version 2.40. Edited by Tim Hudson. 14 April 2015. OASIS Standard. http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/os/pkcs11-profiles-v2.40-os.html. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/pkcs11-profiles-v2.40.html.
[PKCS #1] RSA Laboratories. RSA Cryptography Standard. v2.1, June 14, 2002.
URL: ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-1/pkcs-1v2-1.pdf
[PKCS #3] RSA Laboratories. Diffie-Hellman Key-Agreement Standard. v1.4, November 1993.
URL: ftp://ftp.rsasecurity.com/pub/pkcs/doc/pkcs-3.doc
[PKCS #5] RSA Laboratories. Password-Based Encryption Standard. v2.0, March 25, 1999
URL: ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-5v2/pkcs5v2-0.pdf
[PKCS #7] RSA Laboratories. Cryptographic Message Syntax Standard. v1.5, November 1993
URL : ftp://ftp.rsasecurity.com/pub/pkcs/doc/pkcs-7.doc
[PKCS #8] RSA Laboratories. Private-Key Information Syntax Standard. v1.2, November 1993.
URL: ftp://ftp.rsasecurity.com/pub/pkcs/doc/pkcs-8.doc
[PKCS11-UG] PKCS #11 Cryptographic Token Interface Usage Guide Version 2.40. Edited by John Leiseboer and Robert Griffin. 16 November 2014. OASIS Committee Note 02. http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/cn02/pkcs11-ug-v2.40-cn02.html. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/pkcs11-ug-v2.40.html.
[PKCS #12] RSA Laboratories. Personal Information Exchange Syntax Standard. v1.0, June 1999.
[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.
[RFC 2279] F. Yergeau. RFC 2279: UTF-8, a transformation format of ISO 10646 Alis Technologies, January 1998. URL: http://www.ietf.org/rfc/rfc2279.txt
[RFC 2534] Masinter, L., Wing, D., Mutz, A., and K. Holtman. RFC 2534: Media Features for Display, Print, and Fax. March 1999. URL: http://www.ietf.org/rfc/rfc2534.txt
[TLS] IETF. RFC 2246: The TLS Protocol Version 1.0 . January 1999.
URL: http://www.ietf.org/rfc/rfc2246.txt
[RFC 5652] R. Housley. RFC 5652: Cryptographic Message Syntax. Septmber 2009. URL: http://www.ietf.org/rfc/rfc5652.txt
[X.500] ITU-T. Information Technology — Open Systems Interconnection — The Directory: Overview of Concepts, Models and Services. February 2001. Identical to ISO/IEC 9594-1
[X.509] ITU-T. Information Technology — Open Systems Interconnection — The Directory: Public-key and Attribute Certificate Frameworks. March 2000.
Identical to ISO/IEC 9594-8
[X.680] ITU-T. Information Technology — Abstract Syntax Notation One (ASN.1): Specification of Basic Notation. July 2002.
Identical to ISO/IEC 8824-1
[X.690] ITU-T. Information Technology — ASN.1 Encoding Rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER). July 2002.
Identical to ISO/IEC 8825-1
[ANSI C] ANSI/ISO. American National Standard for Programming Languages – C. 1990.
[CC/PP] W3C. Composite Capability/Preference Profiles (CC/PP): Structure and Vocabularies. World Wide Web Consortium, January 2004.
URL: http://www.w3.org/TR/CCPP-struct-vocab/
[CDPD] Ameritech Mobile Communications et al. Cellular Digital Packet Data System Specifications: Part 406: Airlink Security. 1993.
[GCS-API] X/Open Company Ltd. Generic Cryptographic Service API (GCS-API), Base - Draft 2. February 14, 1995.
[ISO/IEC 7816-1] ISO. Information Technology — Identification Cards — Integrated Circuit(s) with Contacts — Part 1: Physical Characteristics. 1998.
[ISO/IEC 7816-4] ISO. Information Technology — Identification Cards — Integrated Circuit(s) with Contacts — Part 4: Interindustry Commands for Interchange. 1995.
[ISO/IEC 8824-1] ISO. Information Technology-- Abstract Syntax Notation One (ASN.1): Specification of Basic Notation. 2002.
[ISO/IEC 8825-1] ISO. Information Technology—ASN.1 Encoding Rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER). 2002.
[ISO/IEC 9594-1] ISO. Information Technology — Open Systems Interconnection — The Directory: Overview of Concepts, Models and Services. 2001.
[ISO/IEC 9594-8] ISO. Information Technology — Open Systems Interconnection — The Directory: Public-key and Attribute Certificate Frameworks. 2001
[ISO/IEC 9796-2] ISO. Information Technology — Security Techniques — Digital Signature Scheme Giving Message Recovery — Part 2: Integer factorization based mechanisms. 2002.
[Java MIDP] Java Community Process. Mobile Information Device Profile for Java 2 Micro Edition. November 2002.
URL: http://jcp.org/jsr/detail/118.jsp
[MeT-PTD] MeT. MeT PTD Definition – Personal Trusted Device Definition, Version 1.0, February 2003.
URL: http://www.mobiletransaction.org
[PCMCIA] Personal Computer Memory Card International Association. PC Card Standard, Release 2.1,. July 1993.
[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.
[WIM] WAP. Wireless Identity Module. — WAP-260-WIM-20010712-a. July 2001.
[WPKI] Wireless Application Protocol: Public Key Infrastructure Definition. — WAP-217-WPKI-20010424-a. April 2001.
[WTLS] WAP. Wireless Transport Layer Security Version — WAP-261-WTLS-20010406-a. April 2001.
There is a large array of Cryptoki-related data types that are defined in the Cryptoki header files. Certain packing and pointer-related aspects of these types are platform and compiler-dependent; these aspects are therefore resolved on a platform-by-platform (or compiler-by-compiler) basis outside of the Cryptoki header files by means of preprocessor directives.
This means that when writing C or C++ code, certain preprocessor directives MUST be issued before including a Cryptoki header file. These directives are described in the remainder of Section 6.
Cryptoki structures are packed to occupy as little space as is possible. Cryptoki structures SHALL be packed with 1-byte alignment.
Because different platforms and compilers have different ways of dealing with different types of pointers, the following 6 macros SHALL be set outside the scope of Cryptoki:
CK_PTR is the “indirection string” a given platform and compiler uses to make a pointer to an object. It is used in the following fashion:
typedef CK_BYTE CK_PTR CK_BYTE_PTR;
CK_DEFINE_FUNCTION(returnType, name), when followed by a parentheses-enclosed list of arguments and a function definition, defines a Cryptoki API function in a Cryptoki library. returnType is the return type of the function, and name is its name. It SHALL be used in the following fashion:
CK_DEFINE_FUNCTION(CK_RV, C_Initialize)(
CK_VOID_PTR pReserved
)
{
...
}
CK_DECLARE_FUNCTION(returnType, name), when followed by a parentheses-enclosed list of arguments and a semicolon, declares a Cryptoki API function in a Cryptoki library. returnType is the return type of the function, and name is its name. It SHALL be used in the following fashion:
CK_DECLARE_FUNCTION(CK_RV, C_Initialize)(
CK_VOID_PTR pReserved
);
CK_DECLARE_FUNCTION_POINTER(returnType, name), when followed by a parentheses-enclosed list of arguments and a semicolon, declares a variable or type which is a pointer to a Cryptoki API function in a Cryptoki library. returnType is the return type of the function, and name is its name. It SHALL be used in either of the following fashions to define a function pointer variable, myC_Initialize, which can point to a C_Initialize function in a Cryptoki library (note that neither of the following code snippets actually assigns a value to myC_Initialize):
CK_DECLARE_FUNCTION_POINTER(CK_RV, myC_Initialize)(
CK_VOID_PTR pReserved
);
or:
typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, myC_InitializeType)(
CK_VOID_PTR pReserved
);
myC_InitializeType myC_Initialize;
CK_CALLBACK_FUNCTION(returnType, name), when followed by a parentheses-enclosed list of arguments and a semicolon, declares a variable or type which is a pointer to an application callback function that can be used by a Cryptoki API function in a Cryptoki library. returnType is the return type of the function, and name is its name. It SHALL be used in either of the following fashions to define a function pointer variable, myCallback, which can point to an application callback which takes arguments args and returns a CK_RV (note that neither of the following code snippets actually assigns a value to myCallback):
CK_CALLBACK_FUNCTION(CK_RV, myCallback)(args);
or:
typedef CK_CALLBACK_FUNCTION(CK_RV, myCallbackType)(args);
myCallbackType myCallback;
NULL_PTR is the value of a NULL pointer. In any ANSI C environment—and in many others as well—NULL_PTR SHALL be defined simply as 0.
The general Cryptoki data types are described in the following subsections. The data types for holding parameters for various mechanisms, and the pointers to those parameters, are not described here; these types are described with the information on the mechanisms themselves, in Section 12.
A C or C++ source file in a Cryptoki application or library can define all these types (the types described here and the types that are specifically used for particular mechanism parameters) by including the top-level Cryptoki include file, pkcs11.h. pkcs11.h, in turn, includes the other Cryptoki include files, pkcs11t.h and pkcs11f.h. A source file can also include just pkcs11t.h (instead of pkcs11.h); this defines most (but not all) of the types specified here.
When including either of these header files, a source file MUST specify the preprocessor directives indicated in Section 2.
Cryptoki represents general information with the following types:
¨ CK_VERSION; CK_VERSION_PTR
CK_VERSION is a structure that describes the version of a Cryptoki interface, a Cryptoki library, or an SSL implementation, or the hardware or firmware version of a slot or token. It is defined as follows:
typedef struct CK_VERSION {
CK_BYTE major;
CK_BYTE minor;
} CK_VERSION;
The fields of the structure have the following meanings:
major major version number (the integer portion of the version)
minor minor version number (the hundredths portion of the version)
Example: For version 1.0, major = 1 and minor = 0. For version 2.10, major = 2 and minor = 10. Table 4 below lists the major and minor version values for the officially published Cryptoki specifications.
Table 4, Major and minor version values for published Cryptoki specifications
|
Version |
major |
minor |
|
1.0 |
0x01 |
0x00 |
|
2.01 |
0x02 |
0x01 |
|
2.10 |
0x02 |
0x0a |
|
2.11 |
0x02 |
0x0b |
|
2.20 |
0x02 |
0x14 |
|
2.30 |
0x02 |
0x1e |
|
2.40 |
0x02 |
0x28 |
Minor revisions of the Cryptoki standard are always upwardly compatible within the same major version number.
CK_VERSION_PTR is a pointer to a CK_VERSION.
¨ CK_INFO; CK_INFO_PTR
CK_INFO provides general information about Cryptoki. It is defined as follows:
typedef struct CK_INFO {
CK_VERSION cryptokiVersion;
CK_UTF8CHAR manufacturerID[32];
CK_FLAGS flags;
CK_UTF8CHAR libraryDescription[32];
CK_VERSION libraryVersion;
}
CK_INFO;
The fields of the structure have the following meanings:
cryptokiVersion Cryptoki interface version number, for compatibility with future revisions of this interface
manufacturerID ID of the Cryptoki library manufacturer. MUST be padded with the blank character (‘ ‘). Should not be null-terminated.
flags bit flags reserved for future versions. MUST be zero for this version
libraryDescription character-string description of the library. MUST be padded with the blank character (‘ ‘). Should not be null-terminated.
libraryVersion Cryptoki library version number
For libraries written to this document, the value of cryptokiVersion should match the version of this specification; the value of libraryVersion is the version number of the library software itself.
CK_INFO_PTR is a pointer to a CK_INFO.
CK_NOTIFICATION holds the types of notifications that Cryptoki provides to an application. It is defined as follows:
typedef CK_ULONG CK_NOTIFICATION;
For this version of Cryptoki, the following types of notifications are defined:
CKN_SURRENDER
The notifications have the following meanings:
CKN_SURRENDER Cryptoki is surrendering the execution of a function executing in a session so that the application may perform other operations. After performing any desired operations, the application should indicate to Cryptoki whether to continue or cancel the function (see Section 5.16.1).
Cryptoki represents slot and token information with the following types:
¨ CK_SLOT_ID; CK_SLOT_ID_PTR
CK_SLOT_ID is a Cryptoki-assigned value that identifies a slot. It is defined as follows:
typedef CK_ULONG CK_SLOT_ID;
A list of CK_SLOT_IDs is returned by C_GetSlotList. A priori, any value of CK_SLOT_ID can be a valid slot identifier—in particular, a system may have a slot identified by the value 0. It need not have such a slot, however.
CK_SLOT_ID_PTR is a pointer to a CK_SLOT_ID.
¨ CK_SLOT_INFO; CK_SLOT_INFO_PTR
CK_SLOT_INFO provides information about a slot. It is defined as follows:
typedef struct CK_SLOT_INFO {
CK_UTF8CHAR slotDescription[64];
CK_UTF8CHAR manufacturerID[32];
CK_FLAGS flags;
CK_VERSION hardwareVersion;
CK_VERSION firmwareVersion;
} CK_SLOT_INFO;
The fields of the structure have the following meanings:
slotDescription character-string description of the slot. MUST be padded with the blank character (‘ ‘). MUST NOT be null-terminated.
manufacturerID ID of the slot manufacturer. MUST be padded with the blank character (‘ ‘). MUST NOT be null-terminated.
flags bits flags that provide capabilities of the slot. The flags are defined below
hardwareVersion version number of the slot’s hardware
firmwareVersion version number of the slot’s firmware
The following table defines the flags field:
Table 5, Slot Information Flags
|
Bit Flag |
Mask |
Meaning |
|
CKF_TOKEN_PRESENT |
0x00000001 |
True if a token is present in the slot (e.g., a device is in the reader) |
|
CKF_REMOVABLE_DEVICE |
0x00000002 |
True if the reader supports removable devices |
|
CKF_HW_SLOT |
0x00000004 |
True if the slot is a hardware slot, as opposed to a software slot implementing a “soft token” |
For a given slot, the value of the CKF_REMOVABLE_DEVICE flag never changes. In addition, if this flag is not set for a given slot, then the CKF_TOKEN_PRESENT flag for that slot is always set. That is, if a slot does not support a removable device, then that slot always has a token in it.
CK_SLOT_INFO_PTR is a pointer to a CK_SLOT_INFO.
¨ CK_TOKEN_INFO; CK_TOKEN_INFO_PTR
CK_TOKEN_INFO provides information about a token. It is defined as follows:
typedef struct CK_TOKEN_INFO {
CK_UTF8CHAR label[32];
CK_UTF8CHAR manufacturerID[32];
CK_UTF8CHAR model[16];
CK_CHAR serialNumber[16];
CK_FLAGS flags;
CK_ULONG ulMaxSessionCount;
CK_ULONG ulSessionCount;
CK_ULONG ulMaxRwSessionCount;
CK_ULONG ulRwSessionCount;
CK_ULONG ulMaxPinLen;
CK_ULONG ulMinPinLen;
CK_ULONG ulTotalPublicMemory;
CK_ULONG ulFreePublicMemory;
CK_ULONG ulTotalPrivateMemory;
CK_ULONG ulFreePrivateMemory;
CK_VERSION hardwareVersion;
CK_VERSION firmwareVersion;
CK_CHAR utcTime[16];
} CK_TOKEN_INFO;
The fields of the structure have the following meanings:
label application-defined label, assigned during token initialization. MUST be padded with the blank character (‘ ‘). MUST NOT be null-terminated.
manufacturerID ID of the device manufacturer. MUST be padded with the blank character (‘ ‘). MUST NOT be null-terminated.
model model of the device. MUST be padded with the blank character (‘ ‘). MUST NOT be null-terminated.
serialNumber character-string serial number of the device. MUST be padded with the blank character (‘ ‘). MUST NOT be null-terminated.
flags bit flags indicating capabilities and status of the device as defined below
ulMaxSessionCount maximum number of sessions that can be opened with the token at one time by a single application (see CK_TOKEN_INFO Note below)
ulSessionCount number of sessions that this application currently has open with the token (see CK_TOKEN_INFO Note below)
ulMaxRwSessionCount maximum number of read/write sessions that can be opened with the token at one time by a single application (see CK_TOKEN_INFO Note below)
ulRwSessionCount number of read/write sessions that this application currently has open with the token (see CK_TOKEN_INFO Note below)
ulMaxPinLen maximum length in bytes of the PIN
ulMinPinLen minimum length in bytes of the PIN
ulTotalPublicMemory the total amount of memory on the token in bytes in which public objects may be stored (see CK_TOKEN_INFO Note below)
ulFreePublicMemory the amount of free (unused) memory on the token in bytes for public objects (see CK_TOKEN_INFO Note below)
ulTotalPrivateMemory the total amount of memory on the token in bytes in which private objects may be stored (see CK_TOKEN_INFO Note below)
ulFreePrivateMemory the amount of free (unused) memory on the token in bytes for private objects (see CK_TOKEN_INFO Note below)
hardwareVersion version number of hardware
firmwareVersion version number of firmware
utcTime current time as a character-string of length 16, represented in the format YYYYMMDDhhmmssxx (4 characters for the year; 2 characters each for the month, the day, the hour, the minute, and the second; and 2 additional reserved ‘0’ characters). The value of this field only makes sense for tokens equipped with a clock, as indicated in the token information flags (see below)
The following table defines the flags field:
Table 6, Token Information Flags
|
Bit Flag |
Mask |
Meaning |
|
CKF_RNG |
0x00000001 |
True if the token has its own random number generator |
|
CKF_WRITE_PROTECTED |
0x00000002 |
True if the token is write-protected (see below) |
|
CKF_LOGIN_REQUIRED |
0x00000004 |
True if there are some cryptographic functions that a user MUST be logged in to perform |
|
CKF_USER_PIN_INITIALIZED |
0x00000008 |
True if the normal user’s PIN has been initialized |
|
CKF_RESTORE_KEY_NOT_NEEDED |
0x00000020 |
True if a successful save of a session’s cryptographic operations state always contains all keys needed to restore the state of the session |
|
CKF_CLOCK_ON_TOKEN |
0x00000040 |
True if token has its own hardware clock |
|
CKF_PROTECTED_AUTHENTICATION_PATH |
0x00000100 |
True if token has a “protected authentication path”, whereby a user can log into the token without passing a PIN through the Cryptoki library |
|
CKF_DUAL_CRYPTO_OPERATIONS |
0x00000200 |
True if a single session with the token can perform dual cryptographic operations (see Section 5.12) |
|
CKF_TOKEN_INITIALIZED |
0x00000400 |
True if the token has been initialized using C_InitToken or an equivalent mechanism outside the scope of this standard. Calling C_InitToken when this flag is set will cause the token to be reinitialized. |
|
CKF_SECONDARY_AUTHENTICATION |
0x00000800 |
True if the token supports secondary authentication for private key objects. (Deprecated; new implementations MUST NOT set this flag) |
|
CKF_USER_PIN_COUNT_LOW |
0x00010000 |
True if an incorrect user login PIN has been entered at least once since the last successful authentication. |
|
CKF_USER_PIN_FINAL_TRY |
0x00020000 |
True if supplying an incorrect user PIN will cause it to become locked. |
|
CKF_USER_PIN_LOCKED |
0x00040000 |
True if the user PIN has been locked. User login to the token is not possible. |
|
CKF_USER_PIN_TO_BE_CHANGED |
0x00080000 |
True if the user PIN value is the default value set by token initialization or manufacturing, or the PIN has been expired by the card. |
|
CKF_SO_PIN_COUNT_LOW |
0x00100000 |
True if an incorrect SO login PIN has been entered at least once since the last successful authentication. |
|
CKF_SO_PIN_FINAL_TRY |
0x00200000 |
True if supplying an incorrect SO PIN will cause it to become locked. |
|
CKF_SO_PIN_LOCKED |
0x00400000 |
True if the SO PIN has been locked. SO login to the token is not possible. |
|
CKF_SO_PIN_TO_BE_CHANGED |
0x00800000 |
True if the SO PIN value is the default value set by token initialization or manufacturing, or the PIN has been expired by the card. |
|
CKF_ERROR_STATE
|
0x01000000 |
True if the token failed a FIPS 140-2 self-test and entered an error state. |
Exactly what the CKF_WRITE_PROTECTED flag means is not specified in Cryptoki. An application may be unable to perform certain actions on a write-protected token; these actions can include any of the following, among others:
· Creating/modifying/deleting any object on the token.
· Creating/modifying/deleting a token object on the token.
· Changing the SO’s PIN.
· Changing the normal user’s PIN.
The token may change the value of the CKF_WRITE_PROTECTED flag depending on the session state to implement its object management policy. For instance, the token may set the CKF_WRITE_PROTECTED flag unless the session state is R/W SO or R/W User to implement a policy that does not allow any objects, public or private, to be created, modified, or deleted unless the user has successfully called C_Login.
The CKF_USER_PIN_COUNT_LOW, CKF_USER_PIN_COUNT_LOW, CKF_USER_PIN_FINAL_TRY, and CKF_SO_PIN_FINAL_TRY flags may always be set to false if the token does not support the functionality or will not reveal the information because of its security policy.
The CKF_USER_PIN_TO_BE_CHANGED and CKF_SO_PIN_TO_BE_CHANGED flags may always be set to false if the token does not support the functionality. If a PIN is set to the default value, or has expired, the appropriate CKF_USER_PIN_TO_BE_CHANGED or CKF_SO_PIN_TO_BE_CHANGED flag is set to true. When either of these flags are true, logging in with the corresponding PIN will succeed, but only the C_SetPIN function can be called. Calling any other function that required the user to be logged in will cause CKR_PIN_EXPIRED to be returned until C_SetPIN is called successfully.
CK_TOKEN_INFO Note: The fields ulMaxSessionCount, ulSessionCount, ulMaxRwSessionCount, ulRwSessionCount, ulTotalPublicMemory, ulFreePublicMemory, ulTotalPrivateMemory, and ulFreePrivateMemory can have the special value CK_UNAVAILABLE_INFORMATION, which means that the token and/or library is unable or unwilling to provide that information. In addition, the fields ulMaxSessionCount and ulMaxRwSessionCount can have the special value CK_EFFECTIVELY_INFINITE, which means that there is no practical limit on the number of sessions (resp. R/W sessions) an application can have open with the token.
It is important to check these fields for these special values. This is particularly true for CK_EFFECTIVELY_INFINITE, since an application seeing this value in the ulMaxSessionCount or ulMaxRwSessionCount field would otherwise conclude that it can’t open any sessions with the token, which is far from being the case.
The upshot of all this is that the correct way to interpret (for example) the ulMaxSessionCount field is something along the lines of the following:
CK_TOKEN_INFO info;
.
.
if ((CK_LONG) info.ulMaxSessionCount
== CK_UNAVAILABLE_INFORMATION) {
/* Token refuses to give value of ulMaxSessionCount */
.
.
} else if (info.ulMaxSessionCount == CK_EFFECTIVELY_INFINITE) {
/* Application can open as many sessions as it wants */
.
.
} else {
/* ulMaxSessionCount really does contain what it should */
.
.
}
CK_TOKEN_INFO_PTR is a pointer to a CK_TOKEN_INFO.
Cryptoki represents session information with the following types:
¨ CK_SESSION_HANDLE; CK_SESSION_HANDLE_PTR
CK_SESSION_HANDLE is a Cryptoki-assigned value that identifies a session. It is defined as follows:
typedef CK_ULONG CK_SESSION_HANDLE;
Valid session handles in Cryptoki always have nonzero values. For developers’ convenience, Cryptoki defines the following symbolic value:
CK_INVALID_HANDLE
CK_SESSION_HANDLE_PTR is a pointer to a CK_SESSION_HANDLE.
CK_USER_TYPE holds the types of Cryptoki users described in [PKCS11-UG] and, in addition, a context-specific type described in Section 4.9. It is defined as follows:
typedef CK_ULONG CK_USER_TYPE;
For this version of Cryptoki, the following types of users are defined:
CKU_SO
CKU_USER
CKU_CONTEXT_SPECIFIC
CK_STATE holds the session state, as described in [PKCS11-UG]. It is defined as follows:
typedef CK_ULONG CK_STATE;
For this version of Cryptoki, the following session states are defined:
CKS_RO_PUBLIC_SESSION
CKS_RO_USER_FUNCTIONS
CKS_RW_PUBLIC_SESSION
CKS_RW_USER_FUNCTIONS
CKS_RW_SO_FUNCTIONS
¨ CK_SESSION_INFO; CK_SESSION_INFO_PTR
CK_SESSION_INFO provides information about a session. It is defined as follows:
typedef struct CK_SESSION_INFO {
CK_SLOT_ID slotID;
CK_STATE state;
CK_FLAGS flags;
CK_ULONG ulDeviceError;
} CK_SESSION_INFO;
The fields of the structure have the following meanings:
slotID ID of the slot that interfaces with the token
state the state of the session
flags bit flags that define the type of session; the flags are defined below
ulDeviceError an error code defined by the cryptographic device. Used for errors not covered by Cryptoki.
The following table defines the flags field:
Table 7, Session Information Flags
|
Mask |
Meaning |
|
|
CKF_RW_SESSION |
0x00000002 |
True if the session is read/write; false if the session is read-only |
|
CKF_SERIAL_SESSION |
0x00000004 |
This flag is provided for backward compatibility, and should always be set to true |
CK_SESSION_INFO_PTR is a pointer to a CK_SESSION_INFO.
Cryptoki represents object information with the following types:
¨ CK_OBJECT_HANDLE; CK_OBJECT_HANDLE_PTR
CK_OBJECT_HANDLE is a token-specific identifier for an object. It is defined as follows:
typedef CK_ULONG CK_OBJECT_HANDLE;
When an object is created or found on a token by an application, Cryptoki assigns it an object handle for that application’s sessions to use to access it. A particular object on a token does not necessarily have a handle which is fixed for the lifetime of the object; however, if a particular session can use a particular handle to access a particular object, then that session will continue to be able to use that handle to access that object as long as the session continues to exist, the object continues to exist, and the object continues to be accessible to the session.
Valid object handles in Cryptoki always have nonzero values. For developers’ convenience, Cryptoki defines the following symbolic value:
CK_INVALID_HANDLE
CK_OBJECT_HANDLE_PTR is a pointer to a CK_OBJECT_HANDLE.
¨ CK_OBJECT_CLASS; CK_OBJECT_CLASS_PTR
CK_OBJECT_CLASS is a value that identifies the classes (or types) of objects that Cryptoki recognizes. It is defined as follows:
typedef CK_ULONG CK_OBJECT_CLASS;
Object classes are defined with the objects that use them. The type is specified on an object through the CKA_CLASS attribute of the object.
Vendor defined values for this type may also be specified.
CKO_VENDOR_ DEFINED
Object classes CKO_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their object classes through the PKCS process.
CK_OBJECT_CLASS_PTR is a pointer to a CK_OBJECT_CLASS.
CK_HW_FEATURE_TYPE is a value that identifies a hardware feature type of a device. It is defined as follows:
typedef CK_ULONG CK_HW_FEATURE_TYPE;
Hardware feature types are defined with the objects that use them. The type is specified on an object through the CKA_HW_FEATURE_TYPE attribute of the object.
Vendor defined values for this type may also be specified.
CKH_VENDOR_DEFINED
Feature types CKH_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their feature types through the PKCS process.
CK_KEY_TYPE is a value that identifies a key type. It is defined as follows:
typedef CK_ULONG CK_KEY_TYPE;
Key types are defined with the objects and mechanisms that use them. The key type is specified on an object through the CKA_KEY_TYPE attribute of the object.
Vendor defined values for this type may also be specified.
CKK_VENDOR_DEFINED
Key types CKK_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their key types through the PKCS process.
CK_CERTIFICATE_TYPE is a value that identifies a certificate type. It is defined as follows:
typedef CK_ULONG CK_CERTIFICATE_TYPE;
Certificate types are defined with the objects and mechanisms that use them. The certificate type is specified on an object through the CKA_CERTIFICATE_TYPE attribute of the object.
Vendor defined values for this type may also be specified.
CKC_VENDOR_DEFINED
¨ CK_CERTIFICATE_CATEGORY
CK_CERTIFICATE_CATEGORY is a value that identifies a certificate category. It is defined as follows:
typedef CK_ULONG CK_CERTIFICATE_CATEGORY;
For this version of Cryptoki, the following certificate categories are defined:
|
Constant |
Value |
Meaning |
|
CK_CERTIFICATE_CATEGORY_UNSPECIFIED |
0x00000000UL |
No category specified |
|
CK_CERTIFICATE_CATEGORY_TOKEN_USER |
0x00000001UL |
Certificate belongs to owner of the token |
|
CK_CERTIFICATE_CATEGORY_AUTHORITY |
0x00000002UL |
Certificate belongs to a certificate authority |
|
CK_CERTIFICATE_CATEGORY_OTHER_ENTITY |
0x00000003UL |
Certificate belongs to an end entity (i.e.: not a CA) |
CK_ATTRIBUTE_TYPE is a value that identifies an attribute type. It is defined as follows:
typedef CK_ULONG CK_ATTRIBUTE_TYPE;
Attributes are defined with the objects and mechanisms that use them. Attributes are specified on an object as a list of type, length value items. These are often specified as an attribute template.
Vendor defined values for this type may also be specified.
CKA_VENDOR_DEFINED
Attribute types CKA_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their attribute types through the PKCS process.
¨ CK_ATTRIBUTE; CK_ATTRIBUTE_PTR
CK_ATTRIBUTE is a structure that includes the type, value, and length of an attribute. It is defined as follows:
typedef struct CK_ATTRIBUTE {
CK_ATTRIBUTE_TYPE type;
CK_VOID_PTR pValue;
CK_ULONG ulValueLen;
} CK_ATTRIBUTE;
The fields of the structure have the following meanings:
type the attribute type
pValue pointer to the value of the attribute
ulValueLen length in bytes of the value
If an attribute has no value, then ulValueLen = 0, and the value of pValue is irrelevant. An array of CK_ATTRIBUTEs is called a “template” and is used for creating, manipulating and searching for objects. The order of the attributes in a template never matters, even if the template contains vendor-specific attributes. Note that pValue is a “void” pointer, facilitating the passing of arbitrary values. Both the application and Cryptoki library MUST ensure that the pointer can be safely cast to the expected type (i.e., without word-alignment errors).
The constant CK_UNAVAILABLE_INFORMATION is used in the ulValueLen field to denote an invalid or unavailable value. See C_GetAttributeValue for further details.
CK_ATTRIBUTE_PTR is a pointer to a CK_ATTRIBUTE.
CK_DATE is a structure that defines a date. It is defined as follows:
typedef struct CK_DATE {
CK_CHAR year[4];
CK_CHAR month[2];
CK_CHAR day[2];
} CK_DATE;
The fields of the structure have the following meanings:
year the year (“1900” - “9999”)
month the month (“01” - “12”)
day the day (“01” - “31”)
The fields hold numeric characters from the character set in Table 3, not the literal byte values.
When a Cryptoki object carries an attribute of this type, and the default value of the attribute is specified to be "empty," then Cryptoki libraries SHALL set the attribute's ulValueLen to 0.
Note that implementations of previous versions of Cryptoki may have used other methods to identify an "empty" attribute of type CK_DATE, and applications that needs to interoperate with these libraries therefore have to be flexible in what they accept as an empty value.
¨ CK_JAVA_MIDP_SECURITY_DOMAIN
CK_JAVA_MIDP_SECURITY_DOMAIN is a value that identifies the Java MIDP security domain of a certificate. It is defined as follows:
typedef CK_ULONG CK_JAVA_MIDP_SECURITY_DOMAIN;
For this version of Cryptoki, the following security domains are defined. See the Java MIDP specification for further information:
|
Constant |
Value |
Meaning |
|
CK_SECURITY_DOMAIN_UNSPECIFIED |
0x00000000UL |
No domain specified |
|
CK_SECURITY_DOMAIN_MANUFACTURER |
0x00000001UL |
Manufacturer protection domain |
|
CK_SECURITY_DOMAIN_OPERATOR |
0x00000002UL |
Operator protection domain |
|
CK_SECURITY_DOMAIN_THIRD_PARTY |
0x00000003UL |
Third party protection domain |
Cryptoki supports the following types for describing mechanisms and parameters to them:
¨ CK_MECHANISM_TYPE; CK_MECHANISM_TYPE_PTR
CK_MECHANISM_TYPE is a value that identifies a mechanism type. It is defined as follows:
typedef CK_ULONG CK_MECHANISM_TYPE;
Mechanism types are defined with the objects and mechanism descriptions that use them.
Vendor defined values for this type may also be specified.
CKM_VENDOR_DEFINED
CK_MECHANISM_TYPE_PTR is a pointer to a CK_MECHANISM_TYPE.
¨ CK_MECHANISM; CK_MECHANISM_PTR
CK_MECHANISM is a structure that specifies a particular mechanism and any parameters it requires. It is defined as follows:
typedef struct CK_MECHANISM {
CK_MECHANISM_TYPE mechanism;
CK_VOID_PTR pParameter;
CK_ULONG ulParameterLen;
} CK_MECHANISM;
The fields of the structure have the following meanings:
mechanism the type of mechanism
pParameter pointer to the parameter if required by the mechanism
ulParameterLen length in bytes of the parameter
CK_MECHANISM_PTR is a pointer to a CK_MECHANISM.
¨ CK_MECHANISM_INFO; CK_MECHANISM_INFO_PTR
CK_MECHANISM_INFO is a structure that provides information about a particular mechanism. It is defined as follows:
typedef struct CK_MECHANISM_INFO {
CK_ULONG ulMinKeySize;
CK_ULONG ulMaxKeySize;
CK_FLAGS flags;
} CK_MECHANISM_INFO;
The fields of the structure have the following meanings:
ulMinKeySize the minimum size of the key for the mechanism (whether this is measured in bits or in bytes is mechanism-dependent)
ulMaxKeySize the maximum size of the key for the mechanism (whether this is measured in bits or in bytes is mechanism-dependent)
flags bit flags specifying mechanism capabilities
For some mechanisms, the ulMinKeySize and ulMaxKeySize fields have meaningless values.
The following table defines the flags field:
Table 8, Mechanism Information Flags
|
Bit Flag |
Mask |
Meaning |
|
CKF_HW |
0x00000001 |
True if the mechanism is performed by the device; false if the mechanism is performed in software |
|
CKF_ENCRYPT |
0x00000100 |
True if the mechanism can be used with C_EncryptInit |
|
CKF_DECRYPT |
0x00000200 |
True if the mechanism can be used with C_DecryptInit |
|
CKF_DIGEST |
0x00000400 |
True if the mechanism can be used with C_DigestInit |
|
CKF_SIGN |
0x00000800 |
True if the mechanism can be used with C_SignInit |
|
CKF_SIGN_RECOVER |
0x00001000 |
True if the mechanism can be used with C_SignRecoverInit |
|
CKF_VERIFY |
0x00002000 |
True if the mechanism can be used with C_VerifyInit |
|
CKF_VERIFY_RECOVER |
0x00004000 |
True if the mechanism can be used with C_VerifyRecoverInit |
|
CKF_GENERATE |
0x00008000 |
True if the mechanism can be used with C_GenerateKey |
|
CKF_GENERATE_KEY_PAIR |
0x00010000 |
True if the mechanism can be used with C_GenerateKeyPair |
|
CKF_WRAP |
0x00020000 |
True if the mechanism can be used with C_WrapKey |
|
CKF_UNWRAP |
0x00040000 |
True if the mechanism can be used with C_UnwrapKey |
|
CKF_DERIVE |
0x00080000 |
True if the mechanism can be used with C_DeriveKey |
|
CKF_EXTENSION |
0x80000000 |
True if there is an extension to the flags; false if no extensions. MUST be false for this version. |
CK_MECHANISM_INFO_PTR is a pointer to a CK_MECHANISM_INFO.
Cryptoki represents information about functions with the following data types:
CK_RV is a value that identifies the return value of a Cryptoki function. It is defined as follows:
typedef CK_ULONG CK_RV;
Vendor defined values for this type may also be specified.
CKR_VENDOR_DEFINED
Section 5.1 defines the meaning of each CK_RV value. Return values CKR_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their return values through the PKCS process.
CK_NOTIFY is the type of a pointer to a function used by Cryptoki to perform notification callbacks. It is defined as follows:
typedef CK_CALLBACK_FUNCTION(CK_RV, CK_NOTIFY)(
CK_SESSION_HANDLE hSession,
CK_NOTIFICATION event,
CK_VOID_PTR pApplication
);
The arguments to a notification callback function have the following meanings:
hSession The handle of the session performing the callback
event The type of notification callback
pApplication An application-defined value. This is the same value as was passed to C_OpenSession to open the session performing the callback
Cryptoki also defines an entire family of other function pointer types. For each function C_XXX in the Cryptoki API (see Section 4.12 for detailed information about each of them), Cryptoki defines a type CK_C_XXX, which is a pointer to a function with the same arguments and return value as C_XXX has. An appropriately-set variable of type CK_C_XXX may be used by an application to call the Cryptoki function C_XXX.
¨ CK_FUNCTION_LIST; CK_FUNCTION_LIST_PTR; CK_FUNCTION_LIST_PTR_PTR
CK_FUNCTION_LIST is a structure which contains a Cryptoki version and a function pointer to each function in the Cryptoki API. It is defined as follows:
typedef struct CK_FUNCTION_LIST {
CK_VERSION version;
CK_C_Initialize C_Initialize;
CK_C_Finalize C_Finalize;
CK_C_GetInfo C_GetInfo;
CK_C_GetFunctionList C_GetFunctionList;
CK_C_GetSlotList C_GetSlotList;
CK_C_GetSlotInfo C_GetSlotInfo;
CK_C_GetTokenInfo C_GetTokenInfo;
CK_C_GetMechanismList C_GetMechanismList;
CK_C_GetMechanismInfo C_GetMechanismInfo;
CK_C_InitToken C_InitToken;
CK_C_InitPIN C_InitPIN;
CK_C_SetPIN C_SetPIN;
CK_C_OpenSession C_OpenSession;
CK_C_CloseSession C_CloseSession;
CK_C_CloseAllSessions C_CloseAllSessions;
CK_C_GetSessionInfo C_GetSessionInfo;
CK_C_GetOperationState C_GetOperationState;
CK_C_SetOperationState C_SetOperationState;
CK_C_Login C_Login;
CK_C_Logout C_Logout;
CK_C_CreateObject C_CreateObject;
CK_C_CopyObject C_CopyObject;
CK_C_DestroyObject C_DestroyObject;
CK_C_GetObjectSize C_GetObjectSize;
CK_C_GetAttributeValue C_GetAttributeValue;
CK_C_SetAttributeValue C_SetAttributeValue;
CK_C_FindObjectsInit C_FindObjectsInit;
CK_C_FindObjects C_FindObjects;
CK_C_FindObjectsFinal C_FindObjectsFinal;
CK_C_EncryptInit C_EncryptInit;
CK_C_Encrypt C_Encrypt;
CK_C_EncryptUpdate C_EncryptUpdate;
CK_C_EncryptFinal C_EncryptFinal;
CK_C_DecryptInit C_DecryptInit;
CK_C_Decrypt C_Decrypt;
CK_C_DecryptUpdate C_DecryptUpdate;
CK_C_DecryptFinal C_DecryptFinal;
CK_C_DigestInit C_DigestInit;
CK_C_Digest C_Digest;
CK_C_DigestUpdate C_DigestUpdate;
CK_C_DigestKey C_DigestKey;
CK_C_DigestFinal C_DigestFinal;
CK_C_SignInit C_SignInit;
CK_C_Sign C_Sign;
CK_C_SignUpdate C_SignUpdate;
CK_C_SignFinal C_SignFinal;
CK_C_SignRecoverInit C_SignRecoverInit;
CK_C_SignRecover C_SignRecover;
CK_C_VerifyInit C_VerifyInit;
CK_C_Verify C_Verify;
CK_C_VerifyUpdate C_VerifyUpdate;
CK_C_VerifyFinal C_VerifyFinal;
CK_C_VerifyRecoverInit C_VerifyRecoverInit;
CK_C_VerifyRecover C_VerifyRecover;
CK_C_DigestEncryptUpdate C_DigestEncryptUpdate;
CK_C_DecryptDigestUpdate C_DecryptDigestUpdate;
CK_C_SignEncryptUpdate C_SignEncryptUpdate;
CK_C_DecryptVerifyUpdate C_DecryptVerifyUpdate;
CK_C_GenerateKey C_GenerateKey;
CK_C_GenerateKeyPair C_GenerateKeyPair;
CK_C_WrapKey C_WrapKey;
CK_C_UnwrapKey C_UnwrapKey;
CK_C_DeriveKey C_DeriveKey;
CK_C_SeedRandom C_SeedRandom;
CK_C_GenerateRandom C_GenerateRandom;
CK_C_GetFunctionStatus C_GetFunctionStatus;
CK_C_CancelFunction C_CancelFunction;
CK_C_WaitForSlotEvent C_WaitForSlotEvent;
} CK_FUNCTION_LIST;
Each Cryptoki library has a static CK_FUNCTION_LIST structure, and a pointer to it (or to a copy of it which is also owned by the library) may be obtained by the C_GetFunctionList function (see Section 5.2). The value that this pointer points to can be used by an application to quickly find out where the executable code for each function in the Cryptoki API is located. Every function in the Cryptoki API MUST have an entry point defined in the Cryptoki library’s CK_FUNCTION_LIST structure. If a particular function in the Cryptoki API is not supported by a library, then the function pointer for that function in the library’s CK_FUNCTION_LIST structure should point to a function stub which simply returns CKR_FUNCTION_NOT_SUPPORTED.
In this structure ‘version’ is the cryptoki specification version number. It should match the value of ‘cryptokiVersion’ returned in the CK_INFO structure.
An application may or may not be able to modify a Cryptoki library’s static CK_FUNCTION_LIST structure. Whether or not it can, it should never attempt to do so.
CK_FUNCTION_LIST_PTR is a pointer to a CK_FUNCTION_LIST.
CK_FUNCTION_LIST_PTR_PTR is a pointer to a CK_FUNCTION_LIST_PTR.
The types in this section are provided solely for applications which need to access Cryptoki from multiple threads simultaneously. Applications which will not do this need not use any of these types.
CK_CREATEMUTEX is the type of a pointer to an application-supplied function which creates a new mutex object and returns a pointer to it. It is defined as follows:
typedef CK_CALLBACK_FUNCTION(CK_RV, CK_CREATEMUTEX)(
CK_VOID_PTR_PTR ppMutex
);
Calling a CK_CREATEMUTEX function returns the pointer to the new mutex object in the location pointed to by ppMutex. Such a function should return one of the following values:
CKR_OK, CKR_GENERAL_ERROR
CKR_HOST_MEMORY
CK_DESTROYMUTEX is the type of a pointer to an application-supplied function which destroys an existing mutex object. It is defined as follows:
typedef CK_CALLBACK_FUNCTION(CK_RV, CK_DESTROYMUTEX)(
CK_VOID_PTR pMutex
);
The argument to a CK_DESTROYMUTEX function is a pointer to the mutex object to be destroyed. Such a function should return one of the following values:
CKR_OK, CKR_GENERAL_ERROR
CKR_HOST_MEMORY
CKR_MUTEX_BAD
¨ CK_LOCKMUTEX and CK_UNLOCKMUTEX
CK_LOCKMUTEX is the type of a pointer to an application-supplied function which locks an existing mutex object. CK_UNLOCKMUTEX is the type of a pointer to an application-supplied function which unlocks an existing mutex object. The proper behavior for these types of functions is as follows:
· If a CK_LOCKMUTEX function is called on a mutex which is not locked, the calling thread obtains a lock on that mutex and returns.
· If a CK_LOCKMUTEX function is called on a mutex which is locked by some thread other than the calling thread, the calling thread blocks and waits for that mutex to be unlocked.
· If a CK_LOCKMUTEX function is called on a mutex which is locked by the calling thread, the behavior of the function call is undefined.
· If a CK_UNLOCKMUTEX function is called on a mutex which is locked by the calling thread, that mutex is unlocked and the function call returns. Furthermore:
o If exactly one thread was blocking on that particular mutex, then that thread stops blocking, obtains a lock on that mutex, and its CK_LOCKMUTEX call returns.
o If more than one thread was blocking on that particular mutex, then exactly one of the blocking threads is selected somehow. That lucky thread stops blocking, obtains a lock on the mutex, and its CK_LOCKMUTEX call returns. All other threads blocking on that particular mutex continue to block.
· If a CK_UNLOCKMUTEX function is called on a mutex which is not locked, then the function call returns the error code CKR_MUTEX_NOT_LOCKED.
· If a CK_UNLOCKMUTEX function is called on a mutex which is locked by some thread other than the calling thread, the behavior of the function call is undefined.
CK_LOCKMUTEX is defined as follows:
typedef CK_CALLBACK_FUNCTION(CK_RV, CK_LOCKMUTEX)(
CK_VOID_PTR pMutex
);
The argument to a CK_LOCKMUTEX function is a pointer to the mutex object to be locked. Such a function should return one of the following values:
CKR_OK, CKR_GENERAL_ERROR
CKR_HOST_MEMORY,
CKR_MUTEX_BAD
CK_UNLOCKMUTEX is defined as follows:
typedef CK_CALLBACK_FUNCTION(CK_RV, CK_UNLOCKMUTEX)(
CK_VOID_PTR pMutex
);
The argument to a CK_UNLOCKMUTEX function is a pointer to the mutex object to be unlocked. Such a function should return one of the following values:
CKR_OK, CKR_GENERAL_ERROR
CKR_HOST_MEMORY
CKR_MUTEX_BAD
CKR_MUTEX_NOT_LOCKED
¨ CK_C_INITIALIZE_ARGS; CK_C_INITIALIZE_ARGS_PTR
CK_C_INITIALIZE_ARGS is a structure containing the optional arguments for the C_Initialize function. For this version of Cryptoki, these optional arguments are all concerned with the way the library deals with threads. CK_C_INITIALIZE_ARGS is defined as follows:
typedef struct CK_C_INITIALIZE_ARGS {
CK_CREATEMUTEX CreateMutex;
CK_DESTROYMUTEX DestroyMutex;
CK_LOCKMUTEX LockMutex;
CK_UNLOCKMUTEX UnlockMutex;
CK_FLAGS flags;
CK_VOID_PTR pReserved;
} CK_C_INITIALIZE_ARGS;
The fields of the structure have the following meanings:
CreateMutex pointer to a function to use for creating mutex objects
DestroyMutex pointer to a function to use for destroying mutex objects
LockMutex pointer to a function to use for locking mutex objects
UnlockMutex pointer to a function to use for unlocking mutex objects
flags bit flags specifying options for C_Initialize; the flags are defined below
pReserved reserved for future use. Should be NULL_PTR for this version of Cryptoki
The following table defines the flags field:
Table 9, C_Initialize Parameter Flags
|
Bit Flag |
Mask |
Meaning |
|
CKF_LIBRARY_CANT_CREATE_OS_THREADS |
0x00000001 |
True if application threads which are executing calls to the library may not use native operating system calls to spawn new threads; false if they may |
|
CKF_OS_LOCKING_OK |
0x00000002 |
True if the library can use the native operation system threading model for locking; false otherwise |
CK_C_INITIALIZE_ARGS_PTR is a pointer to a CK_C_INITIALIZE_ARGS.
Cryptoki recognizes a number of classes of objects, as defined in the CK_OBJECT_CLASS data type. An object consists of a set of attributes, each of which has a given value. Each attribute that an object possesses has precisely one value. The following figure illustrates the high-level hierarchy of the Cryptoki objects and some of the attributes they support:
Figure 1, Object Attribute Hierarchy
Cryptoki provides functions for creating, destroying, and copying objects in general, and for obtaining and modifying the values of their attributes. Some of the cryptographic functions (e.g., C_GenerateKey) also create key objects to hold their results.
Objects are always “well-formed” in Cryptoki—that is, an object always contains all required attributes, and the attributes are always consistent with one another from the time the object is created.  In Cryptoki, objects are always initialized.
Tables throughout most of Section 4 define each Cryptoki attribute in terms of the data type of the attribute value and the meaning of the attribute, which may include a default initial value. Some of the data types are defined explicitly by Cryptoki (e.g., CK_OBJECT_CLASS). Attribute values may also take the following types:
Byte array an arbitrary string (array) of CK_BYTEs
Big integer a string of CK_BYTEs representing an unsigned integer of arbitrary size, most-significant byte first (e.g., the integer 32768 is represented as the 2-byte string 0x80 0x00)
Local string an unpadded string of CK_CHARs (see Table 3) with no null-termination
RFC2279 string an unpadded string of CK_UTF8CHARs with no null-termination
A token can hold several identical objects, i.e., it is permissible for two or more objects to have exactly the same values for all their attributes.
In most cases each type of object in the Cryptoki specification possesses a completely well-defined set of Cryptoki attributes. Some of these attributes possess default values, and need not be specified when creating an object; some of these default values may even be the empty string (“”). Nonetheless, the object possesses these attributes. A given object has a single value for each attribute it possesses, even if the attribute is a vendor-specific attribute whose meaning is outside the scope of Cryptoki.
In addition to possessing Cryptoki attributes, objects may possess additional vendor-specific attributes whose meanings and values are not specified by Cryptoki.
All Cryptoki functions that create, modify, or copy objects take a template as one of their arguments, where the template specifies attribute values. Cryptographic functions that create objects (see Section 5.13) may also contribute some additional attribute values themselves; which attributes have values contributed by a cryptographic function call depends on which cryptographic mechanism is being performed (see [PKCS11-Curr] and [PKCS11-Hist] for specification of mechanisms for PKCS #11). In any case, all the required attributes supported by an object class that do not have default values MUST be specified when an object is created, either in the template or by the function itself.
Objects may be created with the Cryptoki functions C_CreateObject (see Section 5.7), C_GenerateKey, C_GenerateKeyPair, C_UnwrapKey, and C_DeriveKey (see Section 5.13). In addition, copying an existing object (with the function C_CopyObject) also creates a new object, but we consider this type of object creation separately in Section 4.1.3.
Attempting to create an object with any of these functions requires an appropriate template to be supplied.
1. If the supplied template specifies a value for an invalid attribute, then the attempt should fail with the error code CKR_ATTRIBUTE_TYPE_INVALID. An attribute is valid if it is either one of the attributes described in the Cryptoki specification or an additional vendor-specific attribute supported by the library and token.
2. If the supplied template specifies an invalid value for a valid attribute, then the attempt should fail with the error code CKR_ATTRIBUTE_VALUE_INVALID. The valid values for Cryptoki attributes are described in the Cryptoki specification.
3. If the supplied template specifies a value for a read-only attribute, then the attempt should fail with the error code CKR_ATTRIBUTE_READ_ONLY. Whether or not a given Cryptoki attribute is read-only is explicitly stated in the Cryptoki specification; however, a particular library and token may be even more restrictive than Cryptoki specifies. In other words, an attribute which Cryptoki says is not read-only may nonetheless be read-only under certain circumstances (i.e., in conjunction with some combinations of other attributes) for a particular library and token. Whether or not a given non-Cryptoki attribute is read-only is obviously outside the scope of Cryptoki.
4. If the attribute values in the supplied template, together with any default attribute values and any attribute values contributed to the object by the object-creation function itself, are insufficient to fully specify the object to create, then the attempt should fail with the error code CKR_TEMPLATE_INCOMPLETE.
5. If the attribute values in the supplied template, together with any default attribute values and any attribute values contributed to the object by the object-creation function itself, are inconsistent, then the attempt should fail with the error code CKR_TEMPLATE_INCONSISTENT. A set of attribute values is inconsistent if not all of its members can be satisfied simultaneously by the token, although each value individually is valid in Cryptoki. One example of an inconsistent template would be using a template which specifies two different values for the same attribute. Another example would be trying to create a secret key object with an attribute which is appropriate for various types of public keys or private keys, but not for secret keys. A final example would be a template with an attribute that violates some token specific requirement. Note that this final example of an inconsistent template is token-dependent—on a different token, such a template might not be inconsistent.
6. If the supplied template specifies the same value for a particular attribute more than once (or the template specifies the same value for a particular attribute that the object-creation function itself contributes to the object), then the behavior of Cryptoki is not completely specified. The attempt to create an object can either succeed—thereby creating the same object that would have been created if the multiply-specified attribute had only appeared once—or it can fail with error code CKR_TEMPLATE_INCONSISTENT. Library developers are encouraged to make their libraries behave as though the attribute had only appeared once in the template; application developers are strongly encouraged never to put a particular attribute into a particular template more than once.
If more than one of the situations listed above applies to an attempt to create an object, then the error code returned from the attempt can be any of the error codes from above that applies.
Objects may be modified with the Cryptoki function C_SetAttributeValue (see Section 5.7). The template supplied to C_SetAttributeValue can contain new values for attributes which the object already possesses; values for attributes which the object does not yet possess; or both.
Some attributes of an object may be modified after the object has been created, and some may not. In addition, attributes which Cryptoki specifies are modifiable may actually not be modifiable on some tokens. That is, if a Cryptoki attribute is described as being modifiable, that really means only that it is modifiable insofar as the Cryptoki specification is concerned. A particular token might not actually support modification of some such attributes. Furthermore, whether or not a particular attribute of an object on a particular token is modifiable might depend on the values of certain attributes of the object. For example, a secret key object’s CKA_SENSITIVE attribute can be changed from CK_FALSE to CK_TRUE, but not the other way around.
All the scenarios in Section 4.1.1—and the error codes they return—apply to modifying objects with C_SetAttributeValue, except for the possibility of a template being incomplete.
Unless an object's CKA_COPYABLE (see table 21) attribute is set to CK_FALSE, it may be copied with the Cryptoki function C_CopyObject (see Section 5.7). In the process of copying an object, C_CopyObject also modifies the attributes of the newly-created copy according to an application-supplied template.
The Cryptoki attributes which can be modified during the course of a C_CopyObject operation are the same as the Cryptoki attributes which are described as being modifiable, plus the three special attributes CKA_TOKEN, CKA_PRIVATE, CKA_MODIFIABLE and CKA_DESTROYABLE. To be more precise, these attributes are modifiable during the course of a C_CopyObject operation insofar as the Cryptoki specification is concerned. A particular token might not actually support modification of some such attributes during the course of a C_CopyObject operation. Furthermore, whether or not a particular attribute of an object on a particular token is modifiable during the course of a C_CopyObject operation might depend on the values of certain attributes of the object. For example, a secret key object’s CKA_SENSITIVE attribute can be changed from CK_FALSE to CK_TRUE during the course of a C_CopyObject operation, but not the other way around.
If the CKA_COPYABLE attribute of the object to be copied is set to CK_FALSE, C_CopyObject returns CKR_ACTION_PROHIBITED. Otherwise, the scenarios described in 10.1.1 - and the error codes they return - apply to copying objects with C_CopyObject, except for the possibility of a template being incomplete.
Table 10, Common footnotes for object attribute tables
|
1 MUST be specified when object is created with C_CreateObject. 2 MUST not be specified when object is created with C_CreateObject. 3 MUST be specified when object is generated with C_GenerateKey or C_GenerateKeyPair. 4 MUST not be specified when object is generated with C_GenerateKey or C_GenerateKeyPair. 5 MUST be specified when object is unwrapped with C_UnwrapKey. 6 MUST not be specified when object is unwrapped with C_UnwrapKey. 7 Cannot be revealed if object has its CKA_SENSITIVE attribute set to CK_TRUE or its CKA_EXTRACTABLE attribute set to CK_FALSE. 8 May be modified after object is created with a C_SetAttributeValue call, or in the process of copying object with a C_CopyObject call. However, it is possible that a particular token may not permit modification of the attribute during the course of a C_CopyObject call. 9 Default value is token-specific, and may depend on the values of other attributes. 10 Can only be set to CK_TRUE by the SO user. 11 Attribute cannot be changed once set to CK_TRUE. It becomes a read only attribute. 12 Attribute cannot be changed once set to CK_FALSE. It becomes a read only attribute.
|
Table 11, Common Object Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_CLASS1 |
CK_OBJECT_CLASS |
Object class (type) |
Refer to Table 10 for footnotes
The above table defines the attributes common to all objects.
This section defines the object class CKO_HW_FEATURE for type CK_OBJECT_CLASS as used in the CKA_CLASS attribute of objects.
Hardware feature objects (CKO_HW_FEATURE) represent features of the device. They provide an easily expandable method for introducing new value-based features to the Cryptoki interface.
When searching for objects using C_FindObjectsInit and C_FindObjects, hardware feature objects are not returned unless the CKA_CLASS attribute in the template has the value CKO_HW_FEATURE. This protects applications written to previous versions of Cryptoki from finding objects that they do not understand.
Table 12, Hardware Feature Common Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_HW_FEATURE_TYPE1 |
CK_HW_FEATURE_TYPE |
Hardware feature (type) |
- Refer to Table 10 for footnotes
The CKA_HW_FEATURE_TYPE attribute takes the value CKH_CLOCK of type CK_HW_FEATURE.
Clock objects represent real-time clocks that exist on the device. This represents the same clock source as the utcTime field in the CK_TOKEN_INFO structure.
Table 13, Clock Object Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_VALUE |
CK_CHAR[16] |
Current time as a character-string of length 16, represented in the format YYYYMMDDhhmmssxx (4 characters for the year; 2 characters each for the month, the day, the hour, the minute, and the second; and 2 additional reserved ‘0’ characters). |
The CKA_VALUE attribute may be set using the C_SetAttributeValue function if permitted by the device. The session used to set the time MUST be logged in. The device may require the SO to be the user logged in to modify the time value. C_SetAttributeValue will return the error CKR_USER_NOT_LOGGED_IN to indicate that a different user type is required to set the value.
The CKA_HW_FEATURE_TYPE attribute takes the value CKH_MONOTONIC_COUNTER of type CK_HW_FEATURE.
Monotonic counter objects represent hardware counters that exist on the device. The counter is guaranteed to increase each time its value is read, but not necessarily by one. This might be used by an application for generating serial numbers to get some assurance of uniqueness per token.
Table 14, Monotonic Counter Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_RESET_ON_INIT1 |
CK_BBOOL |
The value of the counter will reset to a previously returned value if the token is initialized using C_InitToken. |
|
CKA_HAS_RESET1 |
CK_BBOOL |
The value of the counter has been reset at least once at some point in time. |
|
CKA_VALUE1 |
Byte Array |
The current version of the monotonic counter. The value is returned in big endian order. |
1Read Only
The CKA_VALUE attribute may not be set by the client.
The CKA_HW_FEATURE_TYPE attribute takes the value CKH_USER_INTERFACE of type CK_HW_FEATURE.
User interface objects represent the presentation capabilities of the device.
Table 15, User Interface Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_PIXEL_X |
CK_ULONG |
Screen resolution (in pixels) in X-axis (e.g. 1280) |
|
CKA_PIXEL_Y |
CK_ULONG |
Screen resolution (in pixels) in Y-axis (e.g. 1024) |
|
CKA_RESOLUTION |
CK_ULONG |
DPI, pixels per inch |
|
CKA_CHAR_ROWS |
CK_ULONG |
For character-oriented displays; number of character rows (e.g. 24) |
|
CKA_CHAR_COLUMNS |
CK_ULONG |
For character-oriented displays: number of character columns (e.g. 80). If display is of proportional-font type, this is the width of the display in “em”-s (letter “M”), see CC/PP Struct. |
|
CKA_COLOR |
CK_BBOOL |
Color support |
|
CKA_BITS_PER_PIXEL |
CK_ULONG |
The number of bits of color or grayscale information per pixel. |
|
CKA_CHAR_SETS |
RFC 2279 string |
String indicating supported character sets, as defined by IANA MIBenum sets (www.iana.org). Supported character sets are separated with “;”. E.g. a token supporting iso-8859-1 and US-ASCII would set the attribute value to “4;3”. |
|
CKA_ENCODING_METHODS |
RFC 2279 string |
String indicating supported content transfer encoding methods, as defined by IANA (www.iana.org). Supported methods are separated with “;”. E.g. a token supporting 7bit, 8bit and base64 could set the attribute value to “7bit;8bit;base64”. |
|
CKA_MIME_TYPES |
RFC 2279 string |
String indicating supported (presentable) MIME-types, as defined by IANA (www.iana.org). Supported types are separated with “;”. E.g. a token supporting MIME types "a/b", "a/c" and "a/d" would set the attribute value to “a/b;a/c;a/d”. |
The selection of attributes, and associated data types, has been done in an attempt to stay as aligned with RFC 2534 and CC/PP Struct as possible. The special value CK_UNAVAILABLE_INFORMATION may be used for CK_ULONG-based attributes when information is not available or applicable.
None of the attribute values may be set by an application.
The value of the CKA_ENCODING_METHODS attribute may be used when the application needs to send MIME objects with encoded content to the token.
This is not an object class; hence no CKO_ definition is required. It is a category of object classes with common attributes for the object classes that follow.
Table 16, Common Storage Object Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_TOKEN |
CK_BBOOL |
CK_TRUE if object is a token object; CK_FALSE if object is a session object. Default is CK_FALSE. |
|
CKA_PRIVATE |
CK_BBOOL |
CK_TRUE if object is a private object; CK_FALSE if object is a public object. Default value is token-specific, and may depend on the values of other attributes of the object. |
|
CKA_MODIFIABLE |
CK_BBOOL |
CK_TRUE if object can be modified Default is CK_TRUE. |
|
CKA_LABEL |
RFC2279 string |
Description of the object (default empty). |
|
CKA_COPYABLE |
CK_BBOOL |
CK_TRUE if object can be copied using C_CopyObject. Defaults to CK_TRUE. Can’t be set to TRUE once it is set to FALSE. |
|
CKA_DESTROYABLE |
CK_BBOOL |
CK_TRUE if the object can be destroyed using C_DestroyObject. Default is CK_TRUE. |
Only the CKA_LABEL attribute can be modified after the object is created. (The CKA_TOKEN, CKA_PRIVATE, and CKA_MODIFIABLE attributes can be changed in the process of copying an object, however.)
The CKA_TOKEN attribute identifies whether the object is a token object or a session object.
When the CKA_PRIVATE attribute is CK_TRUE, a user may not access the object until the user has been authenticated to the token.
The value of the CKA_MODIFIABLE attribute determines whether or not an object is read-only.
The CKA_LABEL attribute is intended to assist users in browsing.
The value of the CKA_COPYABLE attribute determines whether or not an object can be copied. This attribute can be used in conjunction with CKA_MODIFIABLE to prevent changes to the permitted usages of keys and other objects.
The value of the CKA_DESTROYABLE attribute determines whether the object can be destroyed using C_DestroyObject.
This section defines the object class CKO_DATA for type CK_OBJECT_CLASS as used in the CKA_CLASS attribute of objects.
Data objects (object class CKO_DATA) hold information defined by an application. Other than providing access to it, Cryptoki does not attach any special meaning to a data object. The following table lists the attributes supported by data objects, in addition to the common attributes defined for this object class:
Table 17, Data Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_APPLICATION |
RFC2279 string |
Description of the application that manages the object (default empty) |
|
CKA_OBJECT_ID |
Byte Array |
DER-encoding of the object identifier indicating the data object type (default empty) |
|
CKA_VALUE |
Byte array |
Value of the object (default empty) |
The CKA_APPLICATION attribute provides a means for applications to indicate ownership of the data objects they manage. Cryptoki does not provide a means of ensuring that only a particular application has access to a data object, however.
The CKA_OBJECT_ID attribute provides an application independent and expandable way to indicate the type of the data object value. Cryptoki does not provide a means of insuring that the data object identifier matches the data value.
The following is a sample template containing attributes for creating a data object:
CK_OBJECT_CLASS class = CKO_DATA;
CK_UTF8CHAR label[] = “A data object”;
CK_UTF8CHAR application[] = “An application”;
CK_BYTE data[] = “Sample data”;
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_APPLICATION, application, sizeof(application)-1},
{CKA_VALUE, data, sizeof(data)}
};
This section defines the object class CKO_CERTIFICATE for type CK_OBJECT_CLASS as used in the CKA_CLASS attribute of objects.
Certificate objects (object class CKO_CERTIFICATE) hold public-key or attribute certificates. Other than providing access to certificate objects, Cryptoki does not attach any special meaning to certificates. The following table defines the common certificate object attributes, in addition to the common attributes defined for this object class:
Table 18, Common Certificate Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_CERTIFICATE_TYPE1 |
CK_CERTIFICATE_TYPE |
Type of certificate |
|
CKA_TRUSTED10 |
CK_BBOOL |
The certificate can be trusted for the application that it was created. |
|
CKA_CERTIFICATE_CATEGORY |
CKA_CERTIFICATE_CATEGORY |
(default CK_CERTIFICATE_CATEGORY_UNSPECIFIED) |
|
CKA_CHECK_VALUE |
Byte array |
Checksum |
|
CKA_START_DATE |
CK_DATE |
Start date for the certificate (default empty) |
|
CKA_END_DATE |
CK_DATE |
End date for the certificate (default empty) |
|
CKA_PUBLIC_KEY_INFO |
Byte Array |
DER-encoding of the SubjectPublicKeyInfo for the public key contained in this certificate (default empty) |
- Refer to Table 10 for footnotes
Cryptoki does not enforce the relationship of the CKA_PUBLIC_KEY_INFO to the public key in the certificate, but does recommend that the key be extracted from the certificate to create this value.
The CKA_CERTIFICATE_TYPE attribute may not be modified after an object is created. This version of Cryptoki supports the following certificate types:
· X.509 public key certificate
· X.509 attribute certificate
The CKA_TRUSTED attribute cannot be set to CK_TRUE by an application. It MUST be set by a token initialization application or by the token’s SO. Trusted certificates cannot be modified.
The CKA_CERTIFICATE_CATEGORY attribute is used to indicate if a stored certificate is a user certificate for which the corresponding private key is available on the token (“token user”), a CA certificate (“authority”), or another end-entity certificate (“other entity”). This attribute may not be modified after an object is created.
The CKA_CERTIFICATE_CATEGORY and CKA_TRUSTED attributes will together be used to map to the categorization of the certificates.
CKA_CHECK_VALUE: The value of this attribute is derived from the certificate by taking the first three bytes of the SHA-1 hash of the certificate object’s CKA_VALUE attribute.
The CKA_START_DATE and CKA_END_DATE attributes are for reference only; Cryptoki does not attach any special meaning to them. When present, the application is responsible to set them to values that match the certificate’s encoded “not before” and “not after” fields (if any).
X.509 certificate objects (certificate type CKC_X_509) hold X.509 public key certificates. The following table defines the X.509 certificate object attributes, in addition to the common attributes defined for this object class:
Table 19, X.509 Certificate Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_SUBJECT1 |
Byte array |
DER-encoding of the certificate subject name |
|
CKA_ID |
Byte array |
Key identifier for public/private key pair (default empty) |
|
CKA_ISSUER |
Byte array |
DER-encoding of the certificate issuer name (default empty) |
|
CKA_SERIAL_NUMBER |
Byte array |
DER-encoding of the certificate serial number (default empty) |
|
CKA_VALUE2 |
Byte array |
BER-encoding of the certificate |
|
CKA_URL3 |
RFC2279 string |
If not empty this attribute gives the URL where the complete certificate can be obtained (default empty) |
|
CKA_HASH_OF_SUBJECT_PUBLIC_KEY4 |
Byte array |
Hash of the subject public key (default empty). Hash algorithm is defined by CKA_NAME_HASH_ALGORITHM |
|
CKA_HASH_OF_ISSUER_PUBLIC_KEY4 |
Byte array |
Hash of the issuer public key (default empty). Hash algorithm is defined by CKA_NAME_HASH_ALGORITHM |
|
CKA_JAVA_MIDP_SECURITY_DOMAIN |
CK_JAVA_MIDP_SECURITY_DOMAIN |
Java MIDP security domain. (default CK_SECURITY_DOMAIN_UNSPECIFIED) |
|
CKA_NAME_HASH_ALGORITHM |
CK_MECHANISM_TYPE |
Defines the mechanism used to calculate CKA_HASH_OF_SUBJECT_PUBLIC_KEY and CKA_HASH_OF_ISSUER_PUBLIC_KEY. If the attribute is not present then the type defaults to SHA-1. |
1MUST be specified when the object is created.
2MUST be specified when the object is created. MUST be non-empty if
CKA_URL is empty.
3MUST be non-empty if CKA_VALUE is empty.
4Can only be empty if CKA_URL is empty.
Only the CKA_ID, CKA_ISSUER, and CKA_SERIAL_NUMBER attributes may be modified after the object is created.
The CKA_ID attribute is intended as a means of distinguishing multiple public-key/private-key pairs held by the same subject (whether stored in the same token or not). (Since the keys are distinguished by subject name as well as identifier, it is possible that keys for different subjects may have the same CKA_ID value without introducing any ambiguity.)
It is intended in the interests of interoperability that the subject name and key identifier for a certificate will be the same as those for the corresponding public and private keys (though it is not required that all be stored in the same token). However, Cryptoki does not enforce this association, or even the uniqueness of the key identifier for a given subject; in particular, an application may leave the key identifier empty.
The CKA_ISSUER and CKA_SERIAL_NUMBER attributes are for compatibility with PKCS #7 and Privacy Enhanced Mail (RFC1421). Note that with the version 3 extensions to X.509 certificates, the key identifier may be carried in the certificate. It is intended that the CKA_ID value be identical to the key identifier in such a certificate extension, although this will not be enforced by Cryptoki.
The CKA_URL attribute enables the support for storage of the URL where the certificate can be found instead of the certificate itself. Storage of a URL instead of the complete certificate is often used in mobile environments.
The CKA_HASH_OF_SUBJECT_PUBLIC_KEY and CKA_HASH_OF_ISSUER_PUBLIC_KEY attributes are used to store the hashes of the public keys of the subject and the issuer. They are particularly important when only the URL is available to be able to correlate a certificate with a private key and when searching for the certificate of the issuer. The hash algorithm is defined by CKA_NAME_HASH_ALGORITHM.
The CKA_JAVA_MIDP_SECURITY_DOMAIN attribute associates a certificate with a Java MIDP security domain.
The following is a sample template for creating an X.509 certificate object:
CK_OBJECT_CLASS class = CKO_CERTIFICATE;
CK_CERTIFICATE_TYPE certType = CKC_X_509;
CK_UTF8CHAR label[] = “A certificate object”;
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE certificate[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_CERTIFICATE_TYPE, &certType, sizeof(certType)};
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_VALUE, certificate, sizeof(certificate)}
};
WTLS certificate objects (certificate type CKC_WTLS) hold WTLS public key certificates. The following table defines the WTLS certificate object attributes, in addition to the common attributes defined for this object class.
Table 20: WTLS Certificate Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_SUBJECT1 |
Byte array |
WTLS-encoding (Identifier type) of the certificate subject |
|
CKA_ISSUER |
Byte array |
WTLS-encoding (Identifier type) of the certificate issuer (default empty) |
|
CKA_VALUE2 |
Byte array |
WTLS-encoding of the certificate |
|
CKA_URL3 |
RFC2279 string |
If not empty this attribute gives the URL where the complete certificate can be obtained |
|
CKA_HASH_OF_SUBJECT_PUBLIC_KEY4 |
Byte array |
SHA-1 hash of the subject public key (default empty). Hash algorithm is defined by CKA_NAME_HASH_ALGORITHM |
|
CKA_HASH_OF_ISSUER_PUBLIC_KEY4 |
Byte array |
SHA-1 hash of the issuer public key (default empty). Hash algorithm is defined by CKA_NAME_HASH_ALGORITHM |
|
CKA_NAME_HASH_ALGORITHM |
CK_MECHANISM_TYPE |
Defines the mechanism used to calculate CKA_HASH_OF_SUBJECT_PUBLIC_KEY and CKA_HASH_OF_ISSUER_PUBLIC_KEY. If the attribute is not present then the type defaults to SHA-1. |
1MUST be specified when the object is created. Can only be empty if CKA_VALUE is empty.
2MUST be specified when the object is created. MUST be non-empty if CKA_URL is empty.
3MUST be non-empty if CKA_VALUE is empty.
4Can only be empty if CKA_URL is empty.
Only the CKA_ISSUER attribute may be modified after the object has been created.
The encoding for the CKA_SUBJECT, CKA_ISSUER, and CKA_VALUE attributes can be found in [WTLS] (see References).
The CKA_URL attribute enables the support for storage of the URL where the certificate can be found instead of the certificate itself. Storage of a URL instead of the complete certificate is often used in mobile environments.
The CKA_HASH_OF_SUBJECT_PUBLIC_KEY and CKA_HASH_OF_ISSUER_PUBLIC_KEY attributes are used to store the hashes of the public keys of the subject and the issuer. They are particularly important when only the URL is available to be able to correlate a certificate with a private key and when searching for the certificate of the issuer. The hash algorithm is defined by CKA_NAME_HASH_ALGORITHM.
The following is a sample template for creating a WTLS certificate object:
CK_OBJECT_CLASS class = CKO_CERTIFICATE;
CK_CERTIFICATE_TYPE certType = CKC_WTLS;
CK_UTF8CHAR label[] = “A certificate object”;
CK_BYTE subject[] = {...};
CK_BYTE certificate[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] =
{
{CKA_CLASS, &class, sizeof(class)},
{CKA_CERTIFICATE_TYPE, &certType, sizeof(certType)};
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_VALUE, certificate, sizeof(certificate)}
};
X.509 attribute certificate objects (certificate type CKC_X_509_ATTR_CERT) hold X.509 attribute certificates. The following table defines the X.509 attribute certificate object attributes, in addition to the common attributes defined for this object class:
Table 21, X.509 Attribute Certificate Object Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_OWNER1 |
Byte Array |
DER-encoding of the attribute certificate's subject field. This is distinct from the CKA_SUBJECT attribute contained in CKC_X_509 certificates because the ASN.1 syntax and encoding are different. |
|
CKA_AC_ISSUER |
Byte Array |
DER-encoding of the attribute certificate's issuer field. This is distinct from the CKA_ISSUER attribute contained in CKC_X_509 certificates because the ASN.1 syntax and encoding are different. (default empty) |
|
CKA_SERIAL_NUMBER |
Byte Array |
DER-encoding of the certificate serial number. (default empty) |
|
CKA_ATTR_TYPES |
Byte Array |
BER-encoding of a sequence of object identifier values corresponding to the attribute types contained in the certificate. When present, this field offers an opportunity for applications to search for a particular attribute certificate without fetching and parsing the certificate itself. (default empty) |
|
CKA_VALUE1 |
Byte Array |
BER-encoding of the certificate. |
1MUST be specified when the object is created
Only the CKA_AC_ISSUER, CKA_SERIAL_NUMBER and CKA_ATTR_TYPES attributes may be modified after the object is created.
The following is a sample template for creating an X.509 attribute certificate object:
CK_OBJECT_CLASS class = CKO_CERTIFICATE;
CK_CERTIFICATE_TYPE certType = CKC_X_509_ATTR_CERT;
CK_UTF8CHAR label[] = "An attribute certificate object";
CK_BYTE owner[] = {...};
CK_BYTE certificate[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_CERTIFICATE_TYPE, &certType, sizeof(certType)};
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_OWNER, owner, sizeof(owner)},
{CKA_VALUE, certificate, sizeof(certificate)}
};
There is no CKO_ definition for the base key object class, only for the key types derived from it.
This section defines the object class CKO_PUBLIC_KEY, CKO_PRIVATE_KEY and CKO_SECRET_KEY for type CK_OBJECT_CLASS as used in the CKA_CLASS attribute of objects.
Key objects hold encryption or authentication keys, which can be public keys, private keys, or secret keys. The following common footnotes apply to all the tables describing attributes of keys:
The following table defines the attributes common to public key, private key and secret key classes, in addition to the common attributes defined for this object class:
Table 22, Common Key Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_KEY_TYPE1,5 |
CK_KEY_TYPE |
Type of key |
|
CKA_ID8 |
Byte array |
Key identifier for key (default empty) |
|
CKA_START_DATE8 |
CK_DATE |
Start date for the key (default empty) |
|
CKA_END_DATE8 |
CK_DATE |
End date for the key (default empty) |
|
CKA_DERIVE8 |
CK_BBOOL |
CK_TRUE if key supports key derivation (i.e., if other keys can be derived from this one (default CK_FALSE) |
|
CKA_LOCAL2,4,6 |
CK_BBOOL |
CK_TRUE only if key was either · generated locally (i.e., on the token) with a C_GenerateKey or C_GenerateKeyPair call · created with a C_CopyObject call as a copy of a key which had its CKA_LOCAL attribute set to CK_TRUE |
|
CKA_KEY_GEN_ |
CK_MECHANISM_TYPE |
Identifier of the mechanism used to generate the key material. |
|
CKA_ALLOWED_MECHANISMS |
CK_MECHANISM_TYPE _PTR, pointer to a CK_MECHANISM_TYPE array |
A list of mechanisms allowed to be used with this key. The number of mechanisms in the array is the ulValueLen component of the attribute divided by the size of CK_MECHANISM_TYPE. |
- Refer to Table 10 for footnotes
The CKA_ID field is intended to distinguish among multiple keys. In the case of public and private keys, this field assists in handling multiple keys held by the same subject; the key identifier for a public key and its corresponding private key should be the same. The key identifier should also be the same as for the corresponding certificate, if one exists. Cryptoki does not enforce these associations, however. (See Section 4.6 for further commentary.)
In the case of secret keys, the meaning of the CKA_ID attribute is up to the application.
Note that the CKA_START_DATE and CKA_END_DATE attributes are for reference only; Cryptoki does not attach any special meaning to them. In particular, it does not restrict usage of a key according to the dates; doing this is up to the application.
The CKA_DERIVE attribute has the value CK_TRUE if and only if it is possible to derive other keys from the key.
The CKA_LOCAL attribute has the value CK_TRUE if and only if the value of the key was originally generated on the token by a C_GenerateKey or C_GenerateKeyPair call.
The CKA_KEY_GEN_MECHANISM attribute identifies the key generation mechanism used to generate the key material. It contains a valid value only if the CKA_LOCAL attribute has the value CK_TRUE. If CKA_LOCAL has the value CK_FALSE, the value of the attribute is CK_UNAVAILABLE_INFORMATION.
Public key objects (object class CKO_PUBLIC_KEY) hold public keys. The following table defines the attributes common to all public keys, in addition to the common attributes defined for this object class:
Table 23, Common Public Key Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_SUBJECT8 |
Byte array |
DER-encoding of the key subject name (default empty) |
|
CKA_ENCRYPT8 |
CK_BBOOL |
CK_TRUE if key supports encryption9 |
|
CKA_VERIFY8 |
CK_BBOOL |
CK_TRUE if key supports verification where the signature is an appendix to the data9 |
|
CKA_VERIFY_RECOVER8 |
CK_BBOOL |
CK_TRUE if key supports verification where the data is recovered from the signature9 |
|
CKA_WRAP8 |
CK_BBOOL |
CK_TRUE if key supports wrapping (i.e., can be used to wrap other keys)9 |
|
CK_BBOOL |
The key can be trusted for the application that it was created. The wrapping key can be used to wrap keys with CKA_WRAP_WITH_TRUSTED set to CK_TRUE. |
|
|
CKA_WRAP_TEMPLATE |
CK_ATTRIBUTE_PTR |
For wrapping keys. The attribute template to match against any keys wrapped using this wrapping key. Keys that do not match cannot be wrapped. The number of attributes in the array is the ulValueLen component of the attribute divided by the size of CK_ATTRIBUTE. |
|
CKA_PUBLIC_KEY_INFO |
Byte array |
DER-encoding of the SubjectPublicKeyInfo for this public key. (MAY be empty, DEFAULT derived from the underlying public key data) |
- Refer to Table 10 for footnotes
It is intended in the interests of interoperability that the subject name and key identifier for a public key will be the same as those for the corresponding certificate and private key. However, Cryptoki does not enforce this, and it is not required that the certificate and private key also be stored on the token.
To map between ISO/IEC 9594-8 (X.509) keyUsage flags for public keys and the PKCS #11 attributes for public keys, use the following table.
Table 24, Mapping of X.509 key usage flags to Cryptoki attributes for public keys
|
Key usage flags for public keys in X.509 public key certificates |
Corresponding cryptoki attributes for public keys. |
|
dataEncipherment |
CKA_ENCRYPT |
|
digitalSignature, keyCertSign, cRLSign |
CKA_VERIFY |
|
digitalSignature, keyCertSign, cRLSign |
CKA_VERIFY_RECOVER |
|
keyAgreement |
CKA_DERIVE |
|
keyEncipherment |
CKA_WRAP |
|
nonRepudiation |
CKA_VERIFY |
|
nonRepudiation |
CKA_VERIFY_RECOVER |
The value of the CKA_PUBLIC_KEY_INFO attribute is the DER encoded value of SubjectPublicKeyInfo:
SubjectPublicKeyInfo ::= SEQUENCE {
algorithm AlgorithmIdentifier,
subjectPublicKey BIT_STRING }
The encodings for the subjectPublicKey field are specified in the description of the public key types in the appropriate [PKCS11-Curr] document for the key types defined within this specification.
Private key objects (object class CKO_PRIVATE_KEY) hold private keys. The following table defines the attributes common to all private keys, in addition to the common attributes defined for this object class:
Table 25, Common Private Key Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_SUBJECT8 |
Byte array |
DER-encoding of certificate subject name (default empty) |
|
CKA_SENSITIVE8,11 |
CK_BBOOL |
CK_TRUE if key is sensitive9 |
|
CKA_DECRYPT8 |
CK_BBOOL |
CK_TRUE if key supports decryption9 |
|
CKA_SIGN8 |
CK_BBOOL |
CK_TRUE if key supports signatures where the signature is an appendix to the data9 |
|
CKA_SIGN_RECOVER8 |
CK_BBOOL |
CK_TRUE if key supports signatures where the data can be recovered from the signature9 |
|
CKA_UNWRAP8 |
CK_BBOOL |
CK_TRUE if key supports unwrapping (i.e., can be used to unwrap other keys)9 |
|
CKA_EXTRACTABLE8,12 |
CK_BBOOL |
CK_TRUE if key is extractable and can be wrapped 9 |
|
CKA_ALWAYS_SENSITIVE2,4,6 |
CK_BBOOL |
CK_TRUE if key has always had the CKA_SENSITIVE attribute set to CK_TRUE |
|
CKA_NEVER_EXTRACTABLE2,4,6 |
CK_BBOOL |
CK_TRUE if key has never had the CKA_EXTRACTABLE attribute set to CK_TRUE |
|
CKA_WRAP_WITH_TRUSTED11 |
CK_BBOOL |
CK_TRUE if the key can only be wrapped with a wrapping key that has CKA_TRUSTED set to CK_TRUE. Default is CK_FALSE. |
|
CKA_UNWRAP_TEMPLATE |
CK_ATTRIBUTE_PTR |
For wrapping keys. The attribute template to apply to any keys unwrapped using this wrapping key. Any user supplied template is applied after this template as if the object has already been created. The number of attributes in the array is the ulValueLen component of the attribute divided by the size of CK_ATTRIBUTE. |
|
CKA_ALWAYS_AUTHENTICATE |
CK_BBOOL |
If CK_TRUE, the user has to supply the PIN for each use (sign or decrypt) with the key. Default is CK_FALSE. |
|
CKA_PUBLIC_KEY_INFO8 |
Byte Array |
DER-encoding of the SubjectPublicKeyInfo for the associated public key (MAY be empty; DEFAULT derived from the underlying private key data; MAY be manually set for specific key types; if set; MUST be consistent with the underlying private key data) |
- Refer to Table 10 for footnotes
It is intended in the interests of interoperability that the subject name and key identifier for a private key will be the same as those for the corresponding certificate and public key. However, this is not enforced by Cryptoki, and it is not required that the certificate and public key also be stored on the token.
If the CKA_SENSITIVE attribute is CK_TRUE, or if the CKA_EXTRACTABLE attribute is CK_FALSE, then certain attributes of the private key cannot be revealed in plaintext outside the token. Which attributes these are is specified for each type of private key in the attribute table in the section describing that type of key.
The CKA_ALWAYS_AUTHENTICATE attribute can be used to force re-authentication (i.e. force the user to provide a PIN) for each use of a private key. “Use” in this case means a cryptographic operation such as sign or decrypt. This attribute may only be set to CK_TRUE when CKA_PRIVATE is also CK_TRUE.
Re-authentication occurs by calling C_Login with userType set to CKU_CONTEXT_SPECIFIC immediately after a cryptographic operation using the key has been initiated (e.g. after C_SignInit). In this call, the actual user type is implicitly given by the usage requirements of the active key. If C_Login returns CKR_OK the user was successfully authenticated and this sets the active key in an authenticated state that lasts until the cryptographic operation has successfully or unsuccessfully been completed (e.g. by C_Sign, C_SignFinal,..). A return value CKR_PIN_INCORRECT from C_Login means that the user was denied permission to use the key and continuing the cryptographic operation will result in a behavior as if C_Login had not been called. In both of these cases the session state will remain the same, however repeated failed re-authentication attempts may cause the PIN to be locked. C_Login returns in this case CKR_PIN_LOCKED and this also logs the user out from the token. Failing or omitting to re-authenticate when CKA_ALWAYS_AUTHENTICATE is set to CK_TRUE will result in CKR_USER_NOT_LOGGED_IN to be returned from calls using the key. C_Login will return CKR_OPERATION_NOT_INITIALIZED, but the active cryptographic operation will not be affected, if an attempt is made to re-authenticate when CKA_ALWAYS_AUTHENTICATE is set to CK_FALSE.
The CKA_PUBLIC_KEY_INFO attribute represents the public key associated with this private key. The data it represents may either be stored as part of the private key data, or regenerated as needed from the private key.
If this attribute is supplied as part of a template for C_CreateObject, C_CopyObject or C_SetAttributeValue for a private key, the token MUST verify correspondence between the private key data and the public key data as supplied in CKA_PUBLIC_KEY_INFO. This can be done either by deriving a public key from the private key and comparing the values, or by doing a sign and verify operation. If there is a mismatch, the command SHALL return CKR_ATTRIBUTE_VALUE_INVALID. A token MAY choose not to support the CKA_PUBLIC_KEY_INFO attribute for commands which create new private keys. If it does not support the attribute, the command SHALL return CKR_ATTRIBUTE_TYPE_INVALID.
As a general guideline, private keys of any type SHOULD store sufficient information to retrieve the public key information. In particular, the RSA private key description has been modified in <this version> to add the CKA_PUBLIC_EXPONENT to the list of attributes required for an RSA private key. All other private key types described in this specification contain sufficient information to recover the associated public key.
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 26, RSA Private Key Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_MODULUS1,4,6 |
Big integer |
Modulus n |
|
CKA_PUBLIC_EXPONENT1,4,6 |
Big integer |
Public exponent e |
|
CKA_PRIVATE_EXPONENT1,4,6,7 |
Big integer |
Private exponent d |
|
CKA_PRIME_14,6,7 |
Big integer |
Prime p |
|
CKA_PRIME_24,6,7 |
Big integer |
Prime q |
|
CKA_EXPONENT_14,6,7 |
Big integer |
Private exponent d modulo p-1 |
|
CKA_EXPONENT_24,6,7 |
Big integer |
Private exponent d modulo q-1 |
|
CKA_COEFFICIENT4,6,7 |
Big integer |
CRT coefficient q-1 mod p |
Refer to Table 10 for footnotes
Depending on the token, there may be limits on the length of the key components. See PKCS #1 for more information on RSA keys.
Tokens vary in what they actually store for RSA private keys. Some tokens store all of the above attributes, which can assist in performing rapid RSA computations. Other tokens might store only the CKA_MODULUS and CKA_PRIVATE_EXPONENT values. Effective with version 2.40, tokens MUST also store CKA_PUBLIC_EXPONENT. This permits the retrieval of sufficient data to reconstitute the associated public key.
Because of this, Cryptoki is flexible in dealing with RSA private key objects. When a token generates an RSA private key, it stores whichever of the fields in Table 26 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_PUBLIC_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 four values). However, a Cryptoki implementation may or may not actually do this extra computation. The only attributes from Table 26 for which a Cryptoki implementation is required to be able to return values are CKA_MODULUS, CKA_PRIVATE_EXPONENT, and CKA_PUBLIC_EXPONENT. A token SHOULD also be able to return CKA_PUBLIC_KEY_INFO for an RSA private key. See the general guidance for Private Keys above.
Secret key objects (object class CKO_SECRET_KEY) hold secret keys. The following table defines the attributes common to all secret keys, in addition to the common attributes defined for this object class:
Table 27, Common Secret Key Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_SENSITIVE8,11 |
CK_BBOOL |
CK_TRUE if object is sensitive (default CK_FALSE) |
|
CKA_ENCRYPT8 |
CK_BBOOL |
CK_TRUE if key supports encryption9 |
|
CKA_DECRYPT8 |
CK_BBOOL |
CK_TRUE if key supports decryption9 |
|
CKA_SIGN8 |
CK_BBOOL |
CK_TRUE if key supports signatures (i.e., authentication codes) where the signature is an appendix to the data9 |
|
CKA_VERIFY8 |
CK_BBOOL |
CK_TRUE if key supports verification (i.e., of authentication codes) where the signature is an appendix to the data9 |
|
CKA_WRAP8 |
CK_BBOOL |
CK_TRUE if key supports wrapping (i.e., can be used to wrap other keys)9 |
|
CKA_UNWRAP8 |
CK_BBOOL |
CK_TRUE if key supports unwrapping (i.e., can be used to unwrap other keys)9 |
|
CKA_EXTRACTABLE8,12 |
CK_BBOOL |
CK_TRUE if key is extractable and can be wrapped 9 |
|
CKA_ALWAYS_SENSITIVE2,4,6 |
CK_BBOOL |
CK_TRUE if key has always had the CKA_SENSITIVE attribute set to CK_TRUE |
|
CKA_NEVER_EXTRACTABLE2,4,6 |
CK_BBOOL |
CK_TRUE if key has never had the CKA_EXTRACTABLE attribute set to CK_TRUE |
|
CKA_CHECK_VALUE |
Byte array |
Key checksum |
|
CKA_WRAP_WITH_TRUSTED11 |
CK_BBOOL |
CK_TRUE if the key can only be wrapped with a wrapping key that has CKA_TRUSTED set to CK_TRUE. Default is CK_FALSE. |
|
CKA_TRUSTED10 |
CK_BBOOL |
The wrapping key can be used to wrap keys with CKA_WRAP_WITH_TRUSTED set to CK_TRUE. |
|
CKA_WRAP_TEMPLATE |
CK_ATTRIBUTE_PTR |
For wrapping keys. The attribute template to match against any keys wrapped using this wrapping key. Keys that do not match cannot be wrapped. The number of attributes in the array is the ulValueLen component of the attribute divided by the size of CK_ATTRIBUTE |
|
CKA_UNWRAP_TEMPLATE |
CK_ATTRIBUTE_PTR |
For wrapping keys. The attribute template to apply to any keys unwrapped using this wrapping key. Any user supplied template is applied after this template as if the object has already been created. The number of attributes in the array is the ulValueLen component of the attribute divided by the size of CK_ATTRIBUTE. |
- Refer to Table 10 for footnotes
If the CKA_SENSITIVE attribute is CK_TRUE, or if the CKA_EXTRACTABLE attribute is CK_FALSE, then certain attributes of the secret key cannot be revealed in plaintext outside the token. Which attributes these are is specified for each type of secret key in the attribute table in the section describing that type of key.
The key check value (KCV) attribute for symmetric key objects to be called CKA_CHECK_VALUE, of type byte array, length 3 bytes, operates like a fingerprint, or checksum of the key. They are intended to be used to cross-check symmetric keys against other systems where the same key is shared, and as a validity check after manual key entry or restore from backup. Refer to object definitions of specific key types for KCV algorithms.
Properties:
The attribute is optional, but if supported, regardless of how the key object is created or derived, the value of the attribute is always supplied. It SHALL be supplied even if the encryption operation for the key is forbidden (i.e. when CKA_ENCRYPT is set to CK_FALSE).
If a value is supplied in the application template (allowed but never necessary) then, if supported, it MUST match what the library calculates it to be or the library returns a CKR_ATTRIBUTE_VALUE_INVALID. If the library does not support the attribute then it should ignore it. Allowing the attribute in the template this way does no harm and allows the attribute to be treated like any other attribute for the purposes of key wrap and unwrap where the attributes are preserved also.
The generation of the KCV may be prevented by the application supplying the attribute in the template as a no-value (0 length) entry. The application can query the value at any time like any other attribute using C_GetAttributeValue. C_SetAttributeValue may be used to destroy the attribute, by supplying no-value.
Unless otherwise specified for the object definition, the value of this attribute is derived from the key object by taking the first three bytes of an encryption of a single block of null (0x00) bytes, using the default cipher and mode (e.g. ECB) associated with the key type of the secret key object.
This section defines the object class CKO_DOMAIN_PARAMETERS for type CK_OBJECT_CLASS as used in the CKA_CLASS attribute of objects.
This object class was created to support the storage of certain algorithm's extended parameters. DSA and DH both use domain parameters in the key-pair generation step. In particular, some libraries support the generation of domain parameters (originally out of scope for PKCS11) so the object class was added.
To use a domain parameter object you MUST extract the attributes into a template and supply them (still in the template) to the corresponding key-pair generation function.
Domain parameter objects (object class CKO_DOMAIN_PARAMETERS) hold public domain parameters.
The following table defines the attributes common to domain parameter objects in addition to the common attributes defined for this object class:
Table 28, Common Domain Parameter Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_KEY_TYPE1 |
CK_KEY_TYPE |
Type of key the domain parameters can be used to generate. |
|
CKA_LOCAL2,4 |
CK_BBOOL |
CK_TRUE only if domain parameters were either · generated locally (i.e., on the token) with a C_GenerateKey · created with a C_CopyObject call as a copy of domain parameters which had its CKA_LOCAL attribute set to CK_TRUE |
- Refer to Table 10 for footnotes
The CKA_LOCAL attribute has the value CK_TRUE if and only if the values of the domain parameters were originally generated on the token by a C_GenerateKey call.
This section defines the object class CKO_MECHANISM for type CK_OBJECT_CLASS as used in the CKA_CLASS attribute of objects.
Mechanism objects provide information about mechanisms supported by a device beyond that given by the CK_MECHANISM_INFO structure.
When searching for objects using C_FindObjectsInit and C_FindObjects, mechanism objects are not returned unless the CKA_CLASS attribute in the template has the value CKO_MECHANISM. This protects applications written to previous versions of Cryptoki from finding objects that they do not understand.
Table 29, Common Mechanism Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_MECHANISM_TYPE |
CK_MECHANISM_TYPE |
The type of mechanism object |
The CKA_MECHANISM_TYPE attribute may not be set.
Cryptoki's functions are organized into the following categories:
· general-purpose functions (4 functions)
· slot and token management functions (9 functions)
· session management functions (8 functions)
· object management functions (9 functions)
· encryption functions (4 functions)
· decryption functions (4 functions)
· message digesting functions (5 functions)
· signing and MACing functions (6 functions)
· functions for verifying signatures and MACs (6 functions)
· dual-purpose cryptographic functions (4 functions)
· key management functions (5 functions)
· random number generation functions (2 functions)
· parallel function management functions (2 functions)
In addition to these functions, Cryptoki can use application-supplied callback functions to notify an application of certain events, and can also use application-supplied functions to handle mutex objects for safe multi-threaded library access.
The Cryptoki API functions are presented in the following table:
Table 30, Summary of Cryptoki Functions
|
Category |
Function |
Description |
|
General |
C_Initialize |
initializes Cryptoki |
|
purpose functions |
C_Finalize |
clean up miscellaneous Cryptoki-associated resources |
|
|
C_GetInfo |
obtains general information about Cryptoki |
|
|
C_GetFunctionList |
obtains entry points of Cryptoki library functions |
|
Slot and token |
C_GetSlotList |
obtains a list of slots in the system |
|
management |
C_GetSlotInfo |
obtains information about a particular slot |
|
functions |
C_GetTokenInfo |
obtains information about a particular token |
|
|
C_WaitForSlotEvent |
waits for a slot event (token insertion, removal, etc.) to occur |
|
|
C_GetMechanismList |
obtains a list of mechanisms supported by a token |
|
|
C_GetMechanismInfo |
obtains information about a particular mechanism |
|
|
C_InitToken |
initializes a token |
|
|
C_InitPIN |
initializes the normal user’s PIN |
|
|
C_SetPIN |
modifies the PIN of the current user |
|
Session management functions |
C_OpenSession |
opens a connection between an application and a particular token or sets up an application callback for token insertion |
|
|
C_CloseSession |
closes a session |
|
|
C_CloseAllSessions |
closes all sessions with a token |
|
|
C_GetSessionInfo |
obtains information about the session |
|
|
C_GetOperationState |
obtains the cryptographic operations state of a session |
|
|
C_SetOperationState |
sets the cryptographic operations state of a session |
|
|
C_Login |
logs into a token |
|
|
C_Logout |
logs out from a token |
|
Object |
C_CreateObject |
creates an object |
|
management |
C_CopyObject |
creates a copy of an object |
|
functions |
C_DestroyObject |
destroys an object |
|
|
C_GetObjectSize |
obtains the size of an object in bytes |
|
|
C_GetAttributeValue |
obtains an attribute value of an object |
|
|
C_SetAttributeValue |
modifies an attribute value of an object |
|
|
C_FindObjectsInit |
initializes an object search operation |
|
|
C_FindObjects |
continues an object search operation |
|
|
C_FindObjectsFinal |
finishes an object search operation |
|
Encryption |
C_EncryptInit |
initializes an encryption operation |
|
functions |
C_Encrypt |
encrypts single-part data |
|
|
C_EncryptUpdate |
continues a multiple-part encryption operation |
|
|
C_EncryptFinal |
finishes a multiple-part encryption operation |
|
Decryption |
C_DecryptInit |
initializes a decryption operation |
|
functions |
C_Decrypt |
decrypts single-part encrypted data |
|
|
C_DecryptUpdate |
continues a multiple-part decryption operation |
|
|
C_DecryptFinal |
finishes a multiple-part decryption operation |
|
Message |
C_DigestInit |
initializes a message-digesting operation |
|
digesting |
C_Digest |
digests single-part data |
|
functions |
C_DigestUpdate |
continues a multiple-part digesting operation |
|
|
C_DigestKey |
digests a key |
|
|
C_DigestFinal |
finishes a multiple-part digesting operation |
|
Signing |
C_SignInit |
initializes a signature operation |
|
and MACing |
C_Sign |
signs single-part data |
|
functions |
C_SignUpdate |
continues a multiple-part signature operation |
|
|
C_SignFinal |
finishes a multiple-part signature operation |
|
|
C_SignRecoverInit |
initializes a signature operation, where the data can be recovered from the signature |
|
|
C_SignRecover |
signs single-part data, where the data can be recovered from the signature |
|
Functions for verifying |
C_VerifyInit |
initializes a verification operation |
|
signatures |
C_Verify |
verifies a signature on single-part data |
|
and MACs |
C_VerifyUpdate |
continues a multiple-part verification operation |
|
|
C_VerifyFinal |
finishes a multiple-part verification operation |
|
|
C_VerifyRecoverInit |
initializes a verification operation where the data is recovered from the signature |
|
|
C_VerifyRecover |
verifies a signature on single-part data, where the data is recovered from the signature |
|
Dual-purpose cryptographic |
C_DigestEncryptUpdate |
continues simultaneous multiple-part digesting and encryption operations |
|
functions |
C_DecryptDigestUpdate |
continues simultaneous multiple-part decryption and digesting operations |
|
|
C_SignEncryptUpdate |
continues simultaneous multiple-part signature and encryption operations |
|
|
C_DecryptVerifyUpdate |
continues simultaneous multiple-part decryption and verification operations |
|
Key |
C_GenerateKey |
generates a secret key |
|
management |
C_GenerateKeyPair |
generates a public-key/private-key pair |
|
functions |
C_WrapKey |
wraps (encrypts) a key |
|
|
C_UnwrapKey |
unwraps (decrypts) a key |
|
|
C_DeriveKey |
derives a key from a base key |
|
Random number generation |
C_SeedRandom |
mixes in additional seed material to the random number generator |
|
functions |
C_GenerateRandom |
generates random data |
|
Parallel function management |
C_GetFunctionStatus |
legacy function which always returns CKR_FUNCTION_NOT_PARALLEL |
|
functions |
C_CancelFunction |
legacy function which always returns CKR_FUNCTION_NOT_PARALLEL |
|
Callback function |
|
application-supplied function to process notifications from Cryptoki |
Execution of a Cryptoki function call is in general an all-or-nothing affair, i.e., a function call accomplishes either its entire goal, or nothing at all.
· If a Cryptoki function executes successfully, it returns the value CKR_OK.
· If a Cryptoki function does not execute successfully, it returns some value other than CKR_OK, and the token is in the same state as it was in prior to the function call. If the function call was supposed to modify the contents of certain memory addresses on the host computer, these memory addresses may have been modified, despite the failure of the function.
· In unusual (and extremely unpleasant!) circumstances, a function can fail with the return value CKR_GENERAL_ERROR. When this happens, the token and/or host computer may be in an inconsistent state, and the goals of the function may have been partially achieved.
There are a small number of Cryptoki functions whose return values do not behave precisely as described above; these exceptions are documented individually with the description of the functions themselves.
A Cryptoki library need not support every function in the Cryptoki API. However, even an unsupported function MUST have a “stub” in the library which simply returns the value CKR_FUNCTION_NOT_SUPPORTED. The function’s entry in the library’s CK_FUNCTION_LIST structure (as obtained by C_GetFunctionList) should point to this stub function (see Section 3.6).
The Cryptoki interface possesses a large number of functions and return values. In Section 5.1, we enumerate the various possible return values for Cryptoki functions; most of the remainder of Section 5.1 details the behavior of Cryptoki functions, including what values each of them may return.
Because of the complexity of the Cryptoki specification, it is recommended that Cryptoki applications attempt to give some leeway when interpreting Cryptoki functions’ return values. We have attempted to specify the behavior of Cryptoki functions as completely as was feasible; nevertheless, there are presumably some gaps. For example, it is possible that a particular error code which might apply to a particular Cryptoki function is unfortunately not actually listed in the description of that function as a possible error code. It is conceivable that the developer of a Cryptoki library might nevertheless permit his/her implementation of that function to return that error code. It would clearly be somewhat ungraceful if a Cryptoki application using that library were to terminate by abruptly dumping core upon receiving that error code for that function. It would be far preferable for the application to examine the function’s return value, see that it indicates some sort of error (even if the application doesn’t know precisely what kind of error), and behave accordingly.
See Section 5.1.8 for some specific details on how a developer might attempt to make an application that accommodates a range of behaviors from Cryptoki libraries.
Any Cryptoki function can return any of the following values:
· CKR_GENERAL_ERROR: Some horrible, unrecoverable error has occurred. In the worst case, it is possible that the function only partially succeeded, and that the computer and/or token is in an inconsistent state.
· CKR_HOST_MEMORY: The computer that the Cryptoki library is running on has insufficient memory to perform the requested function.
· CKR_FUNCTION_FAILED: The requested function could not be performed, but detailed information about why not is not available in this error return. If the failed function uses a session, it is possible that the CK_SESSION_INFO structure that can be obtained by calling C_GetSessionInfo will hold useful information about what happened in its ulDeviceError field. In any event, although the function call failed, the situation is not necessarily totally hopeless, as it is likely to be when CKR_GENERAL_ERROR is returned. Depending on what the root cause of the error actually was, it is possible that an attempt to make the exact same function call again would succeed.
· CKR_OK: The function executed successfully. Technically, CKR_OK is not quite a “universal” return value; in particular, the legacy functions C_GetFunctionStatus and C_CancelFunction (see Section 5.15) cannot return CKR_OK.
The relative priorities of these errors are in the order listed above, e.g., if either of CKR_GENERAL_ERROR or CKR_HOST_MEMORY would be an appropriate error return, then CKR_GENERAL_ERROR should be returned.
Any Cryptoki function that takes a session handle as one of its arguments (i.e., any Cryptoki function except for C_Initialize, C_Finalize, C_GetInfo, C_GetFunctionList, C_GetSlotList, C_GetSlotInfo, C_GetTokenInfo, C_WaitForSlotEvent, C_GetMechanismList, C_GetMechanismInfo, C_InitToken, C_OpenSession, and C_CloseAllSessions) can return the following values:
· CKR_SESSION_HANDLE_INVALID: The specified session handle was invalid at the time that the function was invoked. Note that this can happen if the session’s token is removed before the function invocation, since removing a token closes all sessions with it.
· CKR_DEVICE_REMOVED: The token was removed from its slot during the execution of the function.
· CKR_SESSION_CLOSED: The session was closed during the execution of the function. Note that, as stated in [PKCS11-UG], the behavior of Cryptoki is undefined if multiple threads of an application attempt to access a common Cryptoki session simultaneously. Therefore, there is actually no guarantee that a function invocation could ever return the value CKR_SESSION_CLOSED. An example of multiple threads accessing a common session simultaneously is where one thread is using a session when another thread closes that same session.
The relative priorities of these errors are in the order listed above, e.g., if either of CKR_SESSION_HANDLE_INVALID or CKR_DEVICE_REMOVED would be an appropriate error return, then CKR_SESSION_HANDLE_INVALID should be returned.
In practice, it is often not crucial (or possible) for a Cryptoki library to be able to make a distinction between a token being removed before a function invocation and a token being removed during a function execution.