cryptlib  3.4.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros
pkcs11_api.h
Go to the documentation of this file.
1 /****************************************************************************
2 * *
3 * cryptlib PKCS #11 API Interface *
4 * Copyright Peter Gutmann 1998-2006 *
5 * *
6 ****************************************************************************/
7 
8 #ifdef USE_PKCS11
9 
10 /* Before we can include the PKCS #11 headers we need to define a few OS-
11  specific things that are required by the headers */
12 
13 #ifdef __WINDOWS__
14  #ifdef __WIN16__
15  #pragma pack( 1 ) /* Struct packing */
16  #define CK_PTR far * /* Pointer type */
17  #define CK_DEFINE_FUNCTION( returnType, name ) \
18  returnType __export _far _pascal name
19  #define CK_DECLARE_FUNCTION( returnType, name ) \
20  returnType __export _far _pascal name
21  #define CK_DECLARE_FUNCTION_POINTER( returnType, name ) \
22  returnType __export _far _pascal (* name)
23  #define CK_CALLBACK_FUNCTION( returnType, name ) \
24  returnType (_far _pascal * name)
25  #else
26  #pragma pack( push, cryptoki, 1 ) /* Struct packing */
27  #define CK_PTR * /* Pointer type */
28  #define CK_DEFINE_FUNCTION( returnType, name ) \
29  returnType __declspec( dllexport ) name
30  #define CK_DECLARE_FUNCTION( returnType, name ) \
31  returnType __declspec( dllimport ) name
32  #define CK_DECLARE_FUNCTION_POINTER( returnType, name ) \
33  returnType __declspec( dllimport ) (* name)
34  #define CK_CALLBACK_FUNCTION( returnType, name ) \
35  returnType (* name)
36  #endif /* Win16 vs.Win32 */
37 #else
38  #define CK_PTR * /* Pointer type */
39  #define CK_DEFINE_FUNCTION( returnType, name ) \
40  returnType name
41  #define CK_DECLARE_FUNCTION( returnType, name ) \
42  returnType name
43  #define CK_DECLARE_FUNCTION_POINTER( returnType, name ) \
44  returnType (* name)
45  #define CK_CALLBACK_FUNCTION( returnType, name ) \
46  returnType (* name)
47 #endif /* __WINDOWS__ */
48 #ifndef NULL_PTR
49  #define NULL_PTR NULL
50 #endif /* NULL_PTR */
51 
52 /* Pull in the PKCS #11 headers */
53 
54 #if defined( INC_ALL )
55  #include "pkcs11.h"
56 #else
57  #include "device/pkcs11.h"
58 #endif /* Compiler-specific includes */
59 
60 /* Occasionally we need to read things into host memory from a device in a
61  manner that can't be handled by a dynBuf since the data is coming from a
62  device rather than a cryptlib object. The following value defines the
63  maximum size of the on-stack buffer, if the data is larger than this we
64  dynamically allocate the buffer (this almost never occurs) */
65 
66 #define MAX_BUFFER_SIZE 1024
67 
68 /* The use of dynamically bound function pointers vs.statically linked
69  functions requires a bit of sleight of hand since we can't give the
70  pointers the same names as prototyped functions. To get around this we
71  redefine the actual function names to the names of the pointers */
72 
73 #define C_CloseSession ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_CloseSession
74 #define C_CreateObject ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_CreateObject
75 #define C_Decrypt ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_Decrypt
76 #define C_DecryptInit ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_DecryptInit
77 #define C_DeriveKey ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_DeriveKey
78 #define C_DestroyObject ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_DestroyObject
79 #define C_Digest ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_Digest
80 #define C_DigestInit ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_DigestInit
81 #define C_Encrypt ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_Encrypt
82 #define C_EncryptInit ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_EncryptInit
83 #define C_Finalize ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_Finalize
84 #define C_FindObjects ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_FindObjects
85 #define C_FindObjectsFinal ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_FindObjectsFinal
86 #define C_FindObjectsInit ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_FindObjectsInit
87 #define C_GenerateKey ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_GenerateKey
88 #define C_GenerateKeyPair ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_GenerateKeyPair
89 #define C_GenerateRandom ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_GenerateRandom
90 #define C_GetAttributeValue ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_GetAttributeValue
91 #define C_GetMechanismInfo ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_GetMechanismInfo
92 #define C_GetInfo ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_GetInfo
93 #define C_GetSlotInfo ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_GetSlotInfo
94 #define C_GetSlotList ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_GetSlotList
95 #define C_GetTokenInfo ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_GetTokenInfo
96 #define C_Initialize ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_Initialize
97 #define C_InitPIN ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_InitPIN
98 #define C_InitToken ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_InitToken
99 #define C_Login ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_Login
100 #define C_Logout ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_Logout
101 #define C_OpenSession ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_OpenSession
102 #define C_SetAttributeValue ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_SetAttributeValue
103 #define C_SetPIN ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_SetPIN
104 #define C_Sign ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_Sign
105 #define C_SignFinal ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_SignFinal
106 #define C_SignInit ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_SignInit
107 #define C_SignUpdate ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_SignUpdate
108 #define C_Verify ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_Verify
109 #define C_VerifyInit ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_VerifyInit
110 #define C_WrapKey ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_WrapKey
111 #define C_UnwrapKey ( ( CK_FUNCTION_LIST_PTR )( pkcs11Info->functionListPtr ) )->C_UnwrapKey
112 
113 /* Mapping of PKCS #11 device capabilities to cryptlib capabilities. We
114  don't use the hash functions because they're always *much* faster in
115  software on the host system (as are the symmetric ciphers in most
116  cases) */
117 
118 typedef struct {
119  /* Mapping information. The mechanism type is the specific mechanism for
120  this algorithm and mode, for example CKM_DES_CFB64 (= { CRYPT_ALGO_DES,
121  CRYPT_MODE_CFB }, the default mechanism is the default mechanism for
122  the algorithm (without taking the mode into account), for example
123  CKM_DES_CBC. The reason why we specify both is that cryptlib records
124  a single capability for each algorithm while PKCS #11 has distinct
125  parameters for each mode of an algorithm. By recording the most common
126  algorithm+mode combination (CBC mode), we can short-circuit having to
127  search the PKCS #11 mechanism table for the common case where that mode
128  is being used */
129  const CK_MECHANISM_TYPE mechanism; /* Mechanism type for this algo/mode */
130  const CK_MECHANISM_TYPE keygenMechanism; /* Supplementary keygen mechanism */
131  const CK_MECHANISM_TYPE defaultMechanism;/* Default mechanism for this algo */
132  const CRYPT_ALGO_TYPE cryptAlgo; /* cryptlib algo and mode */
133  const CRYPT_MODE_TYPE cryptMode;
134 
135  /* Equivalent PKCS #11 parameters */
136  const CK_KEY_TYPE keyType; /* PKCS #11 key type */
137 
138  /* Function pointers */
139  STDC_NONNULL_ARG( ( 1 ) ) \
140  int ( *endFunction )( INOUT CONTEXT_INFO *contextInfoPtr );
141  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
142  int ( *initKeyFunction )( INOUT CONTEXT_INFO *contextInfoPtr,
143  IN_BUFFER( keyLength ) const void *key,
144  IN_LENGTH_SHORT const int keyLength );
145  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1 ) ) \
146  int ( *generateKeyFunction )( INOUT CONTEXT_INFO *contextInfoPtr, \
147  IN_LENGTH_SHORT const int keySizeBits );
148  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
149  int ( *encryptFunction )( INOUT CONTEXT_INFO *contextInfoPtr,
150  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
151  IN_LENGTH_Z int length );
152  /* Length may be zero for hash functions */
153  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
154  int ( *decryptFunction )( INOUT CONTEXT_INFO *contextInfoPtr,
155  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
156  IN_LENGTH int length );
157  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
158  int ( *signFunction )( INOUT CONTEXT_INFO *contextInfoPtr,
159  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
160  IN_LENGTH_SHORT_MIN( MIN_PKCSIZE ) int length );
161  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
162  int ( *sigCheckFunction )( INOUT CONTEXT_INFO *contextInfoPtr,
163  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
164  IN_LENGTH_SHORT_MIN( MIN_PKCSIZE ) int length );
165  } PKCS11_MECHANISM_INFO;
166 
167 /* Encryption contexts can store extra implementation-dependant parameters.
168  The following macro maps these generic parameter names to the PKCS #11
169  values */
170 
171 #define paramKeyType param1
172 #define paramKeyGen param2
173 #define paramDefaultMech param3
174 
175 /* Special non-mechanism/object types used as an EOF markers. Unfortunately
176  PKCS #11 uses all mechanisms down to 0 and it's an unsigned value so
177  there's no facility for a CKM_NONE value along the lines of CRYPT_ERROR,
178  and similarly object handles can also take any value, the best that we
179  can do is use CRYPT_ERROR (all ones) and hope that nothing decides to
180  return an object handle with this value. With mechanisms we're a bit
181  safer, it'd have to be some weird vendor-defined value to match
182  CKM_NONE */
183 
184 #define CKM_NONE ( ( CK_MECHANISM_TYPE ) CRYPT_ERROR )
185 #define CK_OBJECT_NONE ( ( CK_OBJECT_HANDLE ) CRYPT_ERROR )
186 #define CKA_NONE ( ( CK_ATTRIBUTE_TYPE ) CRYPT_ERROR )
187 
188 /* The HMAC mechanisms in PKCS #11 don't work because they have to be keyed
189  with generic secret keys (rather than specific HMAC keys) but generic
190  secret keys can't be used with HMAC operations. There are two possible
191  workarounds for this, either ignore the restrictions on generic secret
192  keys so that they can be used with HMAC objects or define vendor-specific
193  HMAC mechanisms and keys. The latter approach is used by nCipher, who
194  define their own CKA/CKM/CKK values based around a custom magic ID
195  value */
196 
197 #define VENDOR_NCIPHER 0xDE436972UL
198 #define CKA_NCIPHER ( CKA_VENDOR_DEFINED | VENDOR_NCIPHER )
199 #define CKM_NCIPHER ( CKM_VENDOR_DEFINED | VENDOR_NCIPHER )
200 #define CKK_NCIPHER ( CKK_VENDOR_DEFINED | VENDOR_NCIPHER )
201 
202 #ifdef NCIPHER_PKCS11
203  #define CKK_MD5_HMAC ( CKK_NCIPHER + 2 )
204  #define CKK_SHA_1_HMAC ( CKK_NCIPHER + 1 )
205  #define CKK_RIPEMD160_HMAC CKK_GENERIC_SECRET
206  #define CKK_SHA256_HMAC CKK_GENERIC_SECRET
207  #define CKM_MD5_HMAC_KEY_GEN ( CKM_NCIPHER + 6 )
208  #define CKM_SHA_1_HMAC_KEY_GEN ( CKM_NCIPHER + 3 )
209  #define CKM_RIPEMD160_HMAC_KEY_GEN CKK_GENERIC_SECRET
210  #define CKM_SHA256_HMAC_KEY_GEN CKK_GENERIC_SECRET
211 #else
212  #define CKK_MD5_HMAC CKK_GENERIC_SECRET
213  #define CKK_SHA_1_HMAC CKK_GENERIC_SECRET
214  #define CKK_RIPEMD160_HMAC CKK_GENERIC_SECRET
215  #define CKK_SHA256_HMAC CKK_GENERIC_SECRET
216  #define CKM_MD5_HMAC_KEY_GEN CKM_GENERIC_SECRET_KEY_GEN
217  #define CKM_SHA_1_HMAC_KEY_GEN CKM_GENERIC_SECRET_KEY_GEN
218  #define CKM_RIPEMD160_HMAC_KEY_GEN CKK_GENERIC_SECRET
219  #define CKM_SHA256_HMAC_KEY_GEN CKM_GENERIC_SECRET_KEY_GEN
220 #endif /* NCIPHER_PKCS11 */
221 
222 /* Prototypes for functions in pkcs11.c */
223 
224 CHECK_RETVAL \
225 int pkcs11MapError( const CK_RV errorCode,
226  IN_STATUS const int defaultError );
227 CHECK_RETVAL STDC_NONNULL_ARG( ( 2, 3 ) ) \
228 int getContextDeviceInfo( IN_HANDLE const CRYPT_HANDLE iCryptContext,
229  OUT_HANDLE_OPT CRYPT_DEVICE *iCryptDevice,
230  OUT_OPT_PTR PKCS11_INFO **pkcs11InfoPtrPtr );
231 STDC_NONNULL_ARG( ( 1 ) ) \
232 time_t getTokenTime( const CK_TOKEN_INFO *tokenInfo );
233 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
234 const PKCS11_MECHANISM_INFO *getMechanismInfoConv( OUT_LENGTH_SHORT int *mechanismInfoSize );
235 RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
236 int genericEndFunction( const CONTEXT_INFO *contextInfoPtr );
237 
238 /* Prototypes for functions in pkcs11_init.c */
239 
240 CHECK_RETVAL \
241 int initPKCS11Init( INOUT DEVICE_INFO *deviceInfo,
242  IN_BUFFER( nameLength ) \
243  const char *name, const int nameLength ) \
244  STDC_NONNULL_ARG( ( 1, 2 ) );
245 
246 /* Prototypes for functions in pkcs11_pkc.c */
247 
248 CHECK_RETVAL \
249 const PKCS11_MECHANISM_INFO *getMechanismInfoPKC( OUT int *mechanismInfoSize ) \
250  STDC_NONNULL_ARG( ( 1 ) );
251 
252 /* Prototypes for functions in pkcs11_rd/wr.c */
253 
254 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
255 int addIAndSToTemplate( INOUT_ARRAY_C( 2 ) CK_ATTRIBUTE *certTemplate,
256  IN_BUFFER( iAndSLength ) const void *iAndSPtr,
257  IN_LENGTH_SHORT const int iAndSLength );
258 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2, 3 ) ) \
259 int findObject( INOUT PKCS11_INFO *pkcs11Info,
260  OUT CK_OBJECT_HANDLE *hObject,
261  IN_ARRAY( templateCount ) \
262  const CK_ATTRIBUTE *objectTemplate,
263  IN_RANGE( 1, 64 ) const CK_ULONG templateCount );
264 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2, 3 ) ) \
265 int findObjectEx( INOUT PKCS11_INFO *pkcs11Info,
266  OUT CK_OBJECT_HANDLE *hObject,
267  IN_ARRAY( templateCount ) \
268  const CK_ATTRIBUTE *objectTemplate,
269  IN_RANGE( 1, 64 ) const CK_ULONG templateCount );
270 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 4 ) ) \
271 int findObjectFromObject( INOUT PKCS11_INFO *pkcs11Info,
272  const CK_OBJECT_HANDLE hSourceObject,
273  const CK_OBJECT_CLASS objectClass,
274  OUT CK_OBJECT_HANDLE *hObject );
275 void initPKCS11Read( INOUT DEVICE_INFO *deviceInfo ) \
276  STDC_NONNULL_ARG( ( 1 ) );
277 void initPKCS11Write( INOUT DEVICE_INFO *deviceInfo ) \
278  STDC_NONNULL_ARG( ( 1 ) );
279 
280 #endif /* USE_PKCS11 */
Generated on Thu Jan 10 2013 10:00:46 for cryptlib by   doxygen 1.8.2