PKCS#11
|
| Cryptographic Token Interface Standard |
PKCS#11 |
| Symbol | Definition |
| N/A | Not applicable |
| R/O | Read-only |
| R/W | Read/write |
The following prefixes are used in this standard:
| 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:
| 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, a flag is a Boolean flag that can be TRUE or FALSE. A zero value means the flag is FALSE, and a nonzero value means the flag is TRUE. Cryptoki defines these macros, if needed:
#ifndef FALSE #define FALSE 0 #endif #ifndef TRUE #define TRUE (!FALSE) #endif
Portable computing devices such as smart cards, PCMCIA cards, and smart diskettes are ideal tools for implementing public-key cryptography, as they provide a way to store the private-key component of a public-key/private-key pair securely, under the control of a single user. With such a device, a cryptographic application, rather than performing cryptographic operations itself, utilizes the device to perform the operations, with sensitive information such as private keys never being revealed. As more applications are developed for public-key cryptography, a standard programming interface for these devices becomes increasingly valuable. This standard addresses this need.