Net iD – PKCS#11

PKCS#11 is an open standard for cryptographic operations. More information and the standard document may be downloaded from RSA Laboratories http://www.rsa.com/rsalabs/.

Example
The example will test three standard operations with a smart card: create/verify a digital signature, encrypt/decrypt a message and wrap/unwrap a secret key. The example uses Microsoft Developer Studio, but is written in standard C and should be possible to compile using any compiler. Download sample code

If using the PKCS#11 path you link to the Net iD file called ”iidp11.dll/libiidp11.so/libiidp11.dylib” and then start reading at the RSA Labs website: http://www.rsa.com/rsalabs/node.asp?id=2133 (Version 2.11.) You should list all available slots (C_GetSlotList), and then open a session for every found slot and serach for all certificates in all slots. When all certificates have been collected check them against the rules set up by your application and the context. If you get more than one hit you should present a descent dialog where the user can select a certificate. Then proceed with the desired operations.

Version
The current version of the standard is 2.20, but our implementation will return 2.11 as version information. The difference between the two versions is algorithm extensions not concerning smart cards and changed suggestion for handling multiple PINs (see below). The suggestion regarding multiple PINs is useless and will be removed in future versions of the standard. The implementation in Net iD Enterprise will be upgraded when version 2.30 is released. Applications implementing the standard should only be concerned with the major version (2) and minor versions adding support for specific algorithms which are needed, i.e. in those rare cases where a new specific algorithm is mandatory.

Third-party Package
The PKCS#11 library may be installed in any location; it has no other binary dependencies, and only needs the configuration file for license information. For library version 5.4 and later the configuration file may be included in the binary, there is no need for a separate file.

PKCS#11 Error Codes

#define CKM_RSA_PKCS_KEY_PAIR_GEN 0x00000000
#define CKM_RSA_PKCS 0x00000001
#define CKM_RSA_9796 0x00000002
#define CKM_RSA_X_509 0x00000003
#define CKM_MD2_RSA_PKCS 0x00000004
#define CKM_MD5_RSA_PKCS 0x00000005
#define CKM_SHA1_RSA_PKCS 0x00000006
#define CKM_DSA_KEY_PAIR_GEN 0x00000010
#define CKM_DSA 0x00000011
#define CKM_DSA_SHA1 0x00000012
#define CKM_DH_PKCS_KEY_PAIR_GEN 0x00000020
#define CKM_DH_PKCS_DERIVE 0x00000021
#define CKM_RC2_KEY_GEN 0x00000100
#define CKM_RC2_ECB 0x00000101
#define CKM_RC2_CBC 0x00000102
#define CKM_RC2_MAC 0x00000103
#define CKM_RC2_MAC_GENERAL 0x00000104
#define CKM_RC2_CBC_PAD 0x00000105
#define CKM_RC4_KEY_GEN 0x00000110
#define CKM_RC4 0x00000111
#define CKM_DES_KEY_GEN 0x00000120
#define CKM_DES_ECB 0x00000121
#define CKM_DES_CBC 0x00000122
#define CKM_DES_MAC 0x00000123
#define CKM_DES_MAC_GENERAL 0x00000124
#define CKM_DES_CBC_PAD 0x00000125
#define CKM_DES2_KEY_GEN 0x00000130
#define CKM_DES3_KEY_GEN 0x00000131
#define CKM_DES3_ECB 0x00000132
#define CKM_DES3_CBC 0x00000133
#define CKM_DES3_MAC 0x00000134
#define CKM_DES3_MAC_GENERAL 0x00000135
#define CKM_DES3_CBC_PAD 0x00000136
#define CKM_CDMF_KEY_GEN 0x00000140
#define CKM_CDMF_ECB 0x00000141
#define CKM_CDMF_CBC 0x00000142
#define CKM_CDMF_MAC 0x00000143
#define CKM_CDMF_MAC_GENERAL 0x00000144
#define CKM_CDMF_CBC_PAD 0x00000145
#define CKM_MD2 0x00000200
#define CKM_MD2_HMAC 0x00000201
#define CKM_MD2_HMAC_GENERAL 0x00000202
#define CKM_MD5 0x00000210
#define CKM_MD5_HMAC 0x00000211
#define CKM_MD5_HMAC_GENERAL 0x00000212
#define CKM_SHA_1 0x00000220
#define CKM_SHA_1_HMAC 0x00000221
#define CKM_SHA_1_HMAC_GENERAL 0x00000222
#define CKM_CAST_KEY_GEN 0x00000300
#define CKM_CAST_ECB 0x00000301
#define CKM_CAST_CBC 0x00000302
#define CKM_CAST_MAC 0x00000303
#define CKM_CAST_MAC_GENERAL 0x00000304
#define CKM_CAST_CBC_PAD 0x00000305
#define CKM_CAST3_KEY_GEN 0x00000310
#define CKM_CAST3_ECB 0x00000311
#define CKM_CAST3_CBC 0x00000312
#define CKM_CAST3_MAC 0x00000313
#define CKM_CAST3_MAC_GENERAL 0x00000314
#define CKM_CAST3_CBC_PAD 0x00000315
#define CKM_CAST5_KEY_GEN 0x00000320
#define CKM_CAST128_KEY_GEN 0x00000320
#define CKM_CAST5_ECB 0x00000321
#define CKM_CAST128_ECB 0x00000321
#define CKM_CAST5_CBC 0x00000322
#define CKM_CAST128_CBC 0x00000322
#define CKM_CAST5_MAC 0x00000323
#define CKM_CAST128_MAC 0x00000323
#define CKM_CAST5_MAC_GENERAL 0x00000324
#define CKM_CAST128_MAC_GENERAL 0x00000324
#define CKM_CAST5_CBC_PAD 0x00000325
#define CKM_CAST128_CBC_PAD 0x00000325
#define CKM_RC5_KEY_GEN 0x00000330
#define CKM_RC5_ECB 0x00000331
#define CKM_RC5_CBC 0x00000332
#define CKM_RC5_MAC 0x00000333
#define CKM_RC5_MAC_GENERAL 0x00000334
#define CKM_RC5_CBC_PAD 0x00000335
#define CKM_IDEA_KEY_GEN 0x00000340
#define CKM_IDEA_ECB 0x00000341
#define CKM_IDEA_CBC 0x00000342
#define CKM_IDEA_MAC 0x00000343
#define CKM_IDEA_MAC_GENERAL 0x00000344
#define CKM_IDEA_CBC_PAD 0x00000345
#define CKM_GENERIC_SECRET_KEY_GEN 0x00000350
#define CKM_CONCATENATE_BASE_AND_KEY 0x00000360
#define CKM_CONCATENATE_BASE_AND_DATA 0x00000362
#define CKM_CONCATENATE_DATA_AND_BASE 0x00000363
#define CKM_XOR_BASE_AND_DATA 0x00000364
#define CKM_EXTRACT_KEY_FROM_KEY 0x00000365
#define CKM_SSL3_PRE_MASTER_KEY_GEN 0x00000370
#define CKM_SSL3_MASTER_KEY_DERIVE 0x00000371
#define CKM_SSL3_KEY_AND_MAC_DERIVE 0x00000372
#define CKM_SSL3_MD5_MAC 0x00000380
#define CKM_SSL3_SHA1_MAC 0x00000381
#define CKM_MD5_KEY_DERIVATION 0x00000390
#define CKM_MD2_KEY_DERIVATION 0x00000391
#define CKM_SHA1_KEY_DERIVATION 0x00000392
#define CKM_PBE_MD2_DES_CBC 0x000003A0
#define CKM_PBE_MD5_DES_CBC 0x000003A1
#define CKM_PBE_MD5_CAST_CBC 0x000003A2
#define CKM_PBE_MD5_CAST3_CBC 0x000003A3
#define CKM_PBE_MD5_CAST5_CBC 0x000003A4
#define CKM_PBE_MD5_CAST128_CBC 0x000003A4
#define CKM_PBE_SHA1_CAST5_CBC 0x000003A5
#define CKM_PBE_SHA1_CAST128_CBC 0x000003A5
#define CKM_PBE_SHA1_RC4_128 0x000003A6
#define CKM_PBE_SHA1_RC4_40 0x000003A7
#define CKM_PBE_SHA1_DES3_EDE_CBC 0x000003A8
#define CKM_PBE_SHA1_DES2_EDE_CBC 0x000003A9
#define CKM_PBE_SHA1_RC2_128_CBC 0x000003AA
#define CKM_PBE_SHA1_RC2_40_CBC 0x000003AB
#define CKM_PBA_SHA1_WITH_SHA1_HMAC 0x000003C0
#define CKM_KEY_WRAP_LYNKS 0x00000400
#define CKM_KEY_WRAP_SET_OAEP 0x00000401
#define CKM_SKIPJACK_KEY_GEN 0x00001000
#define CKM_SKIPJACK_ECB64 0x00001001
#define CKM_SKIPJACK_CBC64 0x00001002
#define CKM_SKIPJACK_OFB64 0x00001003
#define CKM_SKIPJACK_CFB64 0x00001004
#define CKM_SKIPJACK_CFB32 0x00001005
#define CKM_SKIPJACK_CFB16 0x00001006
#define CKM_SKIPJACK_CFB8 0x00001007
#define CKM_SKIPJACK_WRAP 0x00001008
#define CKM_SKIPJACK_PRIVATE_WRAP 0x00001009
#define CKM_SKIPJACK_RELAYX 0x0000100a
#define CKM_KEA_KEY_PAIR_GEN 0x00001010
#define CKM_KEA_KEY_DERIVE 0x00001011
#define CKM_FORTEZZA_TIMESTAMP 0x00001020
#define CKM_BATON_KEY_GEN 0x00001030
#define CKM_BATON_ECB128 0x00001031
#define CKM_BATON_ECB96 0x00001032
#define CKM_BATON_CBC128 0x00001033
#define CKM_BATON_COUNTER 0x00001034
#define CKM_BATON_SHUFFLE 0x00001035
#define CKM_BATON_WRAP 0x00001036
#define CKM_ECDSA_KEY_PAIR_GEN 0x00001040
#define CKM_ECDSA 0x00001041
#define CKM_ECDSA_SHA1 0x00001042
#define CKM_JUNIPER_KEY_GEN 0x00001060
#define CKM_JUNIPER_ECB128 0x00001061
#define CKM_JUNIPER_CBC128 0x00001062
#define CKM_JUNIPER_COUNTER 0x00001063
#define CKM_JUNIPER_SHUFFLE 0x00001064
#define CKM_JUNIPER_WRAP 0x00001065
#define CKM_FASTHASH 0x00001070
#define CKM_VENDOR_DEFINED 0x80000000

#define CKR_OK 0x00000000
#define CKR_CANCEL 0x00000001
#define CKR_HOST_MEMORY 0x00000002
#define CKR_SLOT_ID_INVALID 0x00000003
#define CKR_GENERAL_ERROR 0x00000005
#define CKR_FUNCTION_FAILED 0x00000006
#define CKR_ARGUMENTS_BAD 0x00000007
#define CKR_NO_EVENT 0x00000008
#define CKR_NEED_TO_CREATE_THREADS 0x00000009
#define CKR_CANT_LOCK 0x0000000A
#define CKR_ATTRIBUTE_READ_ONLY 0x00000010
#define CKR_ATTRIBUTE_SENSITIVE 0x00000011
#define CKR_ATTRIBUTE_TYPE_INVALID 0x00000012
#define CKR_ATTRIBUTE_VALUE_INVALID 0x00000013
#define CKR_DATA_INVALID 0x00000020
#define CKR_DATA_LEN_RANGE 0x00000021
#define CKR_DEVICE_ERROR 0x00000030
#define CKR_DEVICE_MEMORY 0x00000031
#define CKR_DEVICE_REMOVED 0x00000032
#define CKR_ENCRYPTED_DATA_INVALID 0x00000040
#define CKR_ENCRYPTED_DATA_LEN_RANGE 0x00000041
#define CKR_FUNCTION_CANCELED 0x00000050
#define CKR_FUNCTION_NOT_PARALLEL 0x00000051
#define CKR_FUNCTION_NOT_SUPPORTED 0x00000054
#define CKR_KEY_HANDLE_INVALID 0x00000060
#define CKR_KEY_SIZE_RANGE 0x00000062
#define CKR_KEY_TYPE_INCONSISTENT 0x00000063
#define CKR_KEY_NOT_NEEDED 0x00000064
#define CKR_KEY_CHANGED 0x00000065
#define CKR_KEY_NEEDED 0x00000066
#define CKR_KEY_INDIGESTIBLE 0x00000067
#define CKR_KEY_FUNCTION_NOT_PERMITTED 0x00000068
#define CKR_KEY_NOT_WRAPPABLE 0x00000069
#define CKR_KEY_UNEXTRACTABLE 0x0000006A
#define CKR_MECHANISM_INVALID 0x00000070
#define CKR_MECHANISM_PARAM_INVALID 0x00000071
#define CKR_OBJECT_HANDLE_INVALID 0x00000082
#define CKR_OPERATION_ACTIVE 0x00000090
#define CKR_OPERATION_NOT_INITIALIZED 0x00000091
#define CKR_PIN_INCORRECT 0x000000A0
#define CKR_PIN_INVALID 0x000000A1
#define CKR_PIN_LEN_RANGE 0x000000A2
#define CKR_PIN_EXPIRED 0x000000A3
#define CKR_PIN_LOCKED 0x000000A4
#define CKR_SESSION_CLOSED 0x000000B0
#define CKR_SESSION_COUNT 0x000000B1
#define CKR_SESSION_HANDLE_INVALID 0x000000B3
#define CKR_SESSION_PARALLEL_NOT_SUPPORTED 0x000000B4
#define CKR_SESSION_READ_ONLY 0x000000B5
#define CKR_SESSION_EXISTS 0x000000B6
#define CKR_SESSION_READ_ONLY_EXISTS 0x000000B7
#define CKR_SESSION_READ_WRITE_SO_EXISTS 0x000000B8
#define CKR_SIGNATURE_INVALID 0x000000C0
#define CKR_SIGNATURE_LEN_RANGE 0x000000C1
#define CKR_TEMPLATE_INCOMPLETE 0x000000D0
#define CKR_TEMPLATE_INCONSISTENT 0x000000D1
#define CKR_TOKEN_NOT_PRESENT 0x000000E0
#define CKR_TOKEN_NOT_RECOGNIZED 0x000000E1
#define CKR_TOKEN_WRITE_PROTECTED 0x000000E2
#define CKR_UNWRAPPING_KEY_HANDLE_INVALID 0x000000F0
#define CKR_UNWRAPPING_KEY_SIZE_RANGE 0x000000F1
#define CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT 0x000000F2
#define CKR_USER_ALREADY_LOGGED_IN 0x00000100
#define CKR_USER_NOT_LOGGED_IN 0x00000101
#define CKR_USER_PIN_NOT_INITIALIZED 0x00000102
#define CKR_USER_TYPE_INVALID 0x00000103
#define CKR_USER_ANOTHER_ALREADY_LOGGED_IN 0x00000104
#define CKR_USER_TOO_MANY_TYPES 0x00000105
#define CKR_WRAPPED_KEY_INVALID 0x00000110
#define CKR_WRAPPED_KEY_LEN_RANGE 0x00000112
#define CKR_WRAPPING_KEY_HANDLE_INVALID 0x00000113
#define CKR_WRAPPING_KEY_SIZE_RANGE 0x00000114
#define CKR_WRAPPING_KEY_TYPE_INCONSISTENT 0x00000115
#define CKR_RANDOM_SEED_NOT_SUPPORTED 0x00000120
#define CKR_RANDOM_NO_RNG 0x00000121
#define CKR_DOMAIN_PARAMS_INVALID 0x00000130
#define CKR_BUFFER_TOO_SMALL 0x00000150
#define CKR_SAVED_STATE_INVALID 0x00000160
#define CKR_INFORMATION_SENSITIVE 0x00000170
#define CKR_STATE_UNSAVEABLE 0x00000180
#define CKR_CRYPTOKI_NOT_INITIALIZED 0x00000190
#define CKR_CRYPTOKI_ALREADY_INITIALIZED 0x00000191
#define CKR_MUTEX_BAD 0x000001A0
#define CKR_MUTEX_NOT_LOCKED 0x000001A1
#define CKR_VENDOR_DEFINED 0x80000000

Mechanism types CKM_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their mechanism types through the PKCS process.