Pkcs #11: Cryptographic Token Interface Standard rsa laboratories

Random number generation functions

Download 1.99 Mb.

Page	32/50
Date	28.01.2017
Size	1.99 Mb.
	#9297

1 ... 28 29 30 31 32 33 34 35 ... 50

10.15. Random number generation functions

Cryptoki provides the following functions for generating random numbers:

C_SeedRandom

CK_DEFINE_FUNCTION(CK_RV, C_SeedRandom)(
CK_SESSION_HANDLE hSession,
CK_BYTE_PTR pSeed,
CK_ULONG ulSeedLen
);

C_SeedRandom mixes additional seed material into the token’s random number generator. hSession is the session’s handle; pSeed points to the seed material; and ulSeedLen is the length in bytes of the seed material.

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_ACTIVE, CKR_RANDOM_SEED_NOT_SUPPORTED, CKR_RANDOM_NO_RNG, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Example: see C_GenerateRandom.

C_GenerateRandom

CK_DEFINE_FUNCTION(CK_RV, C_GenerateRandom)(

CK_SESSION_HANDLE hSession,

CK_BYTE_PTR pRandomData,

CK_ULONG ulRandomLen

);

C_GenerateRandom generates random or pseudo-random data. hSession is the session’s handle; pRandomData points to the location that receives the random data; and ulRandomLen is the length in bytes of the random or pseudo-random data to be generated.

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_ACTIVE, CKR_RANDOM_NO_RNG, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

Example:

CK_SESSION_HANDLE hSession;

CK_BYTE seed[] = {...};

CK_BYTE randomData[] = {...};

CK_RV rv;
.

rv = C_SeedRandom(hSession, seed, sizeof(seed));

if (rv != CKR_OK) {

.

.

}

rv = C_GenerateRandom(hSession, randomData, sizeof(randomData));

if (rv == CKR_OK) {

}

10.16. Parallel function management functions

Cryptoki provides the following functions for managing parallel execution of cryptographic functions. These functions exist only for backwards compatibility.

C_GetFunctionStatus

CK_DEFINE_FUNCTION(CK_RV, C_GetFunctionStatus)(
CK_SESSION_HANDLE hSession
);

In previous versions of Cryptoki, C_GetFunctionStatus obtained the status of a function running in parallel with an application. Now, however, C_GetFunctionStatus is a legacy function which should simply return the value CKR_FUNCTION_NOT_PARALLEL.

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_FUNCTION_FAILED, CKR_FUNCTION_NOT_PARALLEL, CKR_GENERAL_ERROR, CKR_HOST_MEMORY.

C_CancelFunction

CK_DEFINE_FUNCTION(CK_RV, C_CancelFunction)(
CK_SESSION_HANDLE hSession
);

In previous versions of Cryptoki, C_CancelFunction cancelled a function running in parallel with an application. Now, however, C_CancelFunction is a legacy function which should simply return the value CKR_FUNCTION_NOT_PARALLEL.

Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_FUNCTION_FAILED, CKR_FUNCTION_NOT_PARALLEL, CKR_GENERAL_ERROR, CKR_HOST_MEMORY.

10.17. Callback functions

Cryptoki sessions can use function pointers of type CK_NOTIFY to notify the application of certain events.

10.17.1. Surrender callbacks

Cryptographic functions (i.e., any functions falling under one of these categories: encryption functions; decryption functions; message digesting functions; signing and MACing functions; functions for verifying signatures and MACs; dual-purpose cryptographic functions; key management functions; random number generation functions) executing in Cryptoki sessions can periodically surrender control to the application who called them if the session they are executing in had a notification callback function associated with it when it was opened. They do this by calling the session’s callback with the arguments (hSession, CKN_SURRENDER, pApplication), where hSession is the session’s handle and pApplication was supplied to C_OpenSession when the session was opened. Surrender callbacks should return either the value CKR_OK (to indicate that Cryptoki should continue executing the function) or the value CKR_CANCEL (to indicate that Cryptoki should abort execution of the function). Of course, before returning one of these values, the callback function can perform some computation, if desired.

A typical use of a surrender callback might be to give an application user feedback during a lengthy key pair generation operation. Each time the application receives a callback, it could display an additional “.” to the user. It might also examine the keyboard’s activity since the last surrender callback, and abort the key pair generation operation (probably by returning the value CKR_CANCEL) if the user hit .

A Cryptoki library is not required to make any surrender callbacks.

10.17.2. Vendor-defined callbacks

Library vendors can also define additional types of callbacks. Because of this extension capability, application-supplied notification callback routines should examine each callback they receive, and if they are unfamiliar with the type of that callback, they should immediately give control back to the library by returning with the value CKR_OK.

11. Mechanisms

A mechanism specifies precisely how a certain cryptographic process is to be performed.

The following table shows which Cryptoki mechanisms are supported by different cryptographic operations. For any particular token, of course, a particular operation may well support only a subset of the mechanisms listed. There is also no guarantee that a token which supports one mechanism for some operation supports any other mechanism for any other operation (or even supports that same mechanism for any other operation). For example, even if a token is able to create RSA digital signatures with the CKM_RSA_PKCS mechanism, it may or may not be the case that the same token can also perform RSA encryption with CKM_RSA_PKCS.

Table , Mechanisms vs. Functions

	Functions
Mechanism	Encrypt & Decrypt	Sign & Verify	SR & VR¹	Digest	Gen. Key/ Key Pair	Wrap & Unwrap	Derive
CKM_RSA_PKCS_KEY_PAIR_GEN					
CKM_RSA_PKCS	²	²				
CKM_RSA_9796		²	
CKM_RSA_X_509	²	²				
CKM_MD2_RSA_PKCS		
CKM_MD5_RSA_PKCS		
CKM_SHA1_RSA_PKCS		
CKM_DSA_KEY_PAIR_GEN					
CKM_DSA		²
CKM_DSA_SHA1		
CKM_FORTEZZA_TIMESTAMP		²
CKM_ECDSA_KEY_PAIR_GEN					
CKM_ECDSA		²
CKM_ECDSA_SHA1		
CKM_DH_PKCS_KEY_PAIR_GEN					
CKM_DH_PKCS_DERIVE							
CKM_KEA_KEY_PAIR_GEN					
CKM_KEA_KEY_DERIVE							
CKM_GENERIC_SECRET_KEY_GEN					
CKM_RC2_KEY_GEN					
CKM_RC2_ECB						
CKM_RC2_CBC						
CKM_RC2_CBC_PAD						
CKM_RC2_MAC_GENERAL		
CKM_RC2_MAC		
CKM_RC4_KEY_GEN					
CKM_RC4	
CKM_RC5_KEY_GEN					
CKM_RC5_ECB						
CKM_RC5_CBC						
CKM_RC5_CBC_PAD						
CKM_RC5_MAC_GENERAL		
CKM_RC5_MAC		
CKM_DES_KEY_GEN					
CKM_DES_ECB						
CKM_DES_CBC						
CKM_DES_CBC_PAD						
CKM_DES_MAC_GENERAL		
CKM_DES_MAC		
CKM_DES2_KEY_GEN					
CKM_DES3_KEY_GEN					
CKM_DES3_ECB						
CKM_DES3_CBC						
CKM_DES3_CBC_PAD						
CKM_DES3_MAC_GENERAL		
CKM_DES3_MAC		
CKM_CAST_KEY_GEN					
CKM_CAST_ECB						
CKM_CAST_CBC						
CKM_CAST_CBC_PAD						
CKM_CAST_MAC_GENERAL		
CKM_CAST_MAC		
CKM_CAST3_KEY_GEN					
CKM_CAST3_ECB						
CKM_CAST3_CBC						
CKM_CAST3_CBC_PAD						
CKM_CAST3_MAC_GENERAL		
CKM_CAST3_MAC		
CKM_CAST128_KEY_GEN (CKM_CAST5_KEY_GEN)					
CKM_CAST128_ECB (CKM_CAST5_ECB)						
CKM_CAST128_CBC (CKM_CAST5_CBC)						
CKM_CAST128_CBC_PAD (CKM_CAST5_CBC_PAD)						
CKM_CAST128_MAC_GENERAL (CKM_CAST5_MAC_GENERAL)		
CKM_CAST128_MAC (CKM_CAST5_MAC)		
CKM_IDEA_KEY_GEN					
CKM_IDEA_ECB						
CKM_IDEA_CBC						
CKM_IDEA_CBC_PAD						
CKM_IDEA_MAC_GENERAL		
CKM_IDEA_MAC		
CKM_CDMF_KEY_GEN					
CKM_CDMF_ECB						
CKM_CDMF_CBC						
CKM_CDMF_CBC_PAD						
CKM_CDMF_MAC_GENERAL		
CKM_CDMF_MAC		
CKM_SKIPJACK_KEY_GEN					
CKM_SKIPJACK_ECB64	
CKM_SKIPJACK_CBC64	
CKM_SKIPJACK_OFB64	
CKM_SKIPJACK_CFB64	
CKM_SKIPJACK_CFB32	
CKM_SKIPJACK_CFB16	
CKM_SKIPJACK_CFB8	
CKM_SKIPJACK_WRAP						
CKM_SKIPJACK_PRIVATE_WRAP						
CKM_SKIPJACK_RELAYX						³
CKM_BATON_KEY_GEN					
CKM_BATON_ECB128	
CKM_BATON_ECB96	
CKM_BATON_CBC128	
CKM_BATON_COUNTER	
CKM_BATON_SHUFFLE	
CKM_BATON_WRAP						
CKM_JUNIPER_KEY_GEN					
CKM_JUNIPER_ECB128	
CKM_JUNIPER_CBC128	
CKM_JUNIPER_COUNTER	
CKM_JUNIPER_SHUFFLE	
CKM_JUNIPER_WRAP						
CKM_MD2				
CKM_MD2_HMAC_GENERAL		
CKM_MD2_HMAC		
CKM_MD2_KEY_DERIVATION							
CKM_MD5				
CKM_MD5_HMAC_GENERAL		
CKM_MD5_HMAC		
CKM_MD5_KEY_DERIVATION							
CKM_SHA_1				
CKM_SHA_1_HMAC_GENERAL		
CKM_SHA_1_HMAC		
CKM_SHA1_KEY_DERIVATION							
CKM_FASTHASH				
CKM_PBE_MD2_DES_CBC					
CKM_PBE_MD5_DES_CBC					
CKM_PBE_MD5_CAST_CBC					
CKM_PBE_MD5_CAST3_CBC					
CKM_PBE_MD5_CAST128_CBC (CKM_PBE_MD5_CAST5_CBC)					
CKM_PBE_SHA1_CAST128_CBC (CKM_PBE_SHA1_CAST5_CBC)					
CKM_PBE_SHA1_RC4_128					
CKM_PBE_SHA1_RC4_40					
CKM_PBE_SHA1_DES3_EDE_CBC					
CKM_PBE_SHA1_DES2_EDE_CBC					
CKM_PBE_SHA1_RC2_128_CBC					
CKM_PBE_SHA1_RC2_40_CBC					
CKM_PBA_SHA1_WITH_SHA1_HMAC					
CKM_KEY_WRAP_SET_OAEP						
CKM_KEY_WRAP_LYNKS						
CKM_SSL3_PRE_MASTER_KEY_GEN					
CKM_SSL3_MASTER_KEY_DERIVE							
CKM_SSL3_KEY_AND_MAC_DERIVE							
CKM_SSL3_MD5_MAC		
CKM_SSL3_SHA1_MAC		
CKM_CONCATENATE_BASE_AND_KEY							
CKM_CONCATENATE_BASE_AND_DATA							
CKM_CONCATENATE_DATA_AND_BASE							
CKM_XOR_BASE_AND_DATA							
CKM_EXTRACT_KEY_FROM_KEY							

¹ SR = SignRecover, VR = VerifyRecover.

² Single-part operations only.

³ Mechanism can only be used for wrapping, not unwrapping.

The remainder of Section will present in detail the mechanisms supported by Cryptoki Version 2.01 and the parameters which are supplied to them.

In general, if a mechanism makes no mention of the ulMinKeyLen and ulMaxKeyLen fields of the CK_MECHANISM_INFO structure, then those fields have no meaning for that particular mechanism.

Download 1.99 Mb.

Share with your friends:

1 ... 28 29 30 31 32 33 34 35 ... 50