cryptlib  3.4.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros
capabil.h
Go to the documentation of this file.
1 /****************************************************************************
2 * *
3 * cryptlib Encryption Capability Header File *
4 * Copyright Peter Gutmann 1992-2005 *
5 * *
6 ****************************************************************************/
7 
8 #ifndef _CRYPTCAP_DEFINED
9 
10 #define _CRYPTCAP_DEFINED
11 
12 /* The information processed by the initParams() function */
13 
14 typedef enum {
15  KEYPARAM_NONE, /* No crypto paramter type */
16  KEYPARAM_MODE, /* Encryption mode */
17  KEYPARAM_IV, /* Initialisation vector */
18  KEYPARAM_BLOCKSIZE, /* Hash/MAC output size */
19  KEYPARAM_AAD, /* AAD for authenticated-encr.modes */
20  KEYPARAM_LAST /* Last possible crypto parameter type */
21  } KEYPARAM_TYPE;
22 
23 /* The CONTEXT_INFO structure is only visible inside modules that have access
24  to context internals, if we use it anywhere else we just treat it as a
25  generic void *. In addition since the CONTEXT_INFO contains the
26  capability info struct, it can't be declared yet at this point so we have
27  to provide a forward declaration for it */
28 
29 #ifdef _CRYPTCTX_DEFINED
30  struct CI;
31  #define CI_STRUCT struct CI
32 #else
33  #define CI_STRUCT void
34 #endif /* _CRYPTCTX_DEFINED */
35 
36 /* The information returned by the capability get-info function */
37 
38 typedef enum {
39  CAPABILITY_INFO_NONE, /* No info */
40  CAPABILITY_INFO_STATESIZE, /* Size of algorithm state info */
41  CAPABILITY_INFO_STATEALIGNTYPE, /* Alignment requirements for state info */
42  CAPABILITY_INFO_ICV, /* ICV for authenticated-encr.modes */
43  CAPABILITY_INFO_LAST /* Last possible capability info type */
44  } CAPABILITY_INFO_TYPE;
45 
46 /****************************************************************************
47 * *
48 * Data Structures *
49 * *
50 ****************************************************************************/
51 
52 /* The structure used to store information about the crypto capabilities */
53 
54 typedef struct CA {
55  /* Basic identification information for the algorithm */
56  const CRYPT_ALGO_TYPE cryptAlgo;/* The encryption algorithm */
57  const int blockSize; /* The basic block size of the algorithm */
58  BUFFER_FIXED( algoNameLen ) \
59  const char *algoName; /* Algorithm name */
60  const int algoNameLen; /* Algorithm name length */
61 
62  /* Keying information. Note that the maximum sizes may vary (for
63  example for two-key triple DES vs.three-key triple DES) so the
64  crypt query functions should be used to determine the actual size
65  for a particular context rather than just using maxKeySize */
66  const int minKeySize; /* Minimum key size in bytes */
67  const int keySize; /* Recommended key size in bytes */
68  const int maxKeySize; /* Maximum key size in bytes */
69 
70  /* The functions for implementing the algorithm */
71  CHECK_RETVAL_FNPTR \
72  int ( *selfTestFunction )( void );
73  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 3 ) ) \
74  int ( *getInfoFunction )( IN_ENUM( CAPABILITY_INFO ) \
75  const CAPABILITY_INFO_TYPE type,
76  INOUT_OPT CI_STRUCT *contextInfoPtr,
77  OUT void *data,
78  IN_INT_Z const int length );
79  STDC_NONNULL_ARG( ( 1 ) ) \
80  int ( *endFunction )( INOUT CI_STRUCT *contextInfoPtr );
81  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1 ) ) \
82  int ( *initParamsFunction) ( INOUT CI_STRUCT *contextInfoPtr,
83  IN_ENUM( KEYPARAM ) \
84  const KEYPARAM_TYPE paramType,
85  IN_OPT const void *data,
86  IN_INT const int dataLength );
87  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1 ) ) \
88  int ( *initKeyFunction )( INOUT CI_STRUCT *contextInfoPtr,
89  IN_BUFFER_OPT( keyLength ) const void *key,
90  IN_LENGTH_SHORT_Z const int keyLength );
91  /* The key data can be NULL if it's a PKC
92  context whose key components have been read
93  directly into the context, which is also
94  why we can't use IN_LENGTH_KEY for the
95  length */
96  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1 ) ) \
97  int ( *generateKeyFunction )( INOUT CI_STRUCT *contextInfoPtr, \
98  IN_RANGE( bytesToBits( MIN_KEYSIZE ),
99  bytesToBits( CRYPT_MAX_PKCSIZE ) ) \
100  const int keySizeBits );
101  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
102  int ( *encryptFunction )( INOUT CI_STRUCT *contextInfoPtr,
103  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
104  IN_LENGTH_Z int length );
105  /* Length may be zero for hash functions */
106  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
107  int ( *decryptFunction )( INOUT CI_STRUCT *contextInfoPtr,
108  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
109  IN_LENGTH int length );
110  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
111  int ( *encryptCBCFunction )( INOUT CI_STRUCT *contextInfoPtr,
112  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
113  IN_LENGTH int length );
114  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
115  int ( *decryptCBCFunction )( INOUT CI_STRUCT *contextInfoPtr,
116  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
117  IN_LENGTH int length );
118  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
119  int ( *encryptCFBFunction )( INOUT CI_STRUCT *contextInfoPtr,
120  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
121  IN_LENGTH int length );
122  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
123  int ( *decryptCFBFunction )( INOUT CI_STRUCT *contextInfoPtr,
124  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
125  IN_LENGTH int length );
126  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
127  int ( *encryptOFBFunction )( INOUT CI_STRUCT *contextInfoPtr,
128  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
129  IN_LENGTH int length );
130  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
131  int ( *decryptOFBFunction )( INOUT CI_STRUCT *contextInfoPtr,
132  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
133  IN_LENGTH int length );
134  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
135  int ( *encryptGCMFunction )( INOUT CI_STRUCT *contextInfoPtr,
136  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
137  IN_LENGTH int length );
138  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
139  int ( *decryptGCMFunction )( INOUT CI_STRUCT *contextInfoPtr,
140  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
141  IN_LENGTH int length );
142  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
143  int ( *signFunction )( INOUT CI_STRUCT *contextInfoPtr,
144  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
145  IN_LENGTH_SHORT_MIN( MIN_PKCSIZE ) int length );
146  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
147  int ( *sigCheckFunction )( INOUT CI_STRUCT *contextInfoPtr,
148  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
149  IN_LENGTH_SHORT_MIN( MIN_PKCSIZE ) int length );
150 
151  /* Non-native implementations may require extra parameters (for example
152  to specify the algorithm and mode in the manner required by the
153  non-native implementation), the following values can be used to store
154  these parameters */
155  const int param1, param2, param3, param4;
156  } CAPABILITY_INFO;
157 
158 /* An encapsulating list type for the list of capabilities */
159 
160 typedef struct CL {
161  const CAPABILITY_INFO *info;
162  struct CL *next;
163  } CAPABILITY_INFO_LIST;
164 
165 /* Since cryptlib's CAPABILITY_INFO is fixed, all of the fields are declared
166  const so that they'll be allocated in the code segment. This doesn't quite
167  work for some types of crypto devices since things like the available key
168  lengths can vary depending on the underlying hardware or software, so we
169  provide an equivalent structure that makes the variable fields non-const.
170  Once the fields are set up, the result is copied into a dynamically-
171  allocated CAPABILITY_INFO block at which point the fields are treated as
172  const by the code */
173 
174 typedef struct {
175  const CRYPT_ALGO_TYPE cryptAlgo;
176  const int blockSize;
177  BUFFER_FIXED( algoNameLen ) \
178  const char *algoName;
179  const int algoNameLen;
180 
181  int minKeySize; /* Non-const */
182  int keySize; /* Non-const */
183  int maxKeySize; /* Non-const */
184 
185  CHECK_RETVAL_FNPTR \
186  int ( *selfTestFunction )( void );
187  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 3 ) ) \
188  int ( *getInfoFunction )( IN_ENUM( CAPABILITY_INFO ) \
189  const CAPABILITY_INFO_TYPE type,
190  INOUT_OPT CI_STRUCT *contextInfoPtr,
191  OUT void *data,
192  IN_INT_Z const int length );
193  STDC_NONNULL_ARG( ( 1 ) ) \
194  int ( *endFunction )( INOUT CI_STRUCT *contextInfoPtr );
195  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1 ) ) \
196  int ( *initParamsFunction) ( INOUT CI_STRUCT *contextInfoPtr,
197  IN_ENUM( KEYPARAM ) \
198  const KEYPARAM_TYPE paramType,
199  IN_OPT const void *data,
200  IN_INT const int dataLength );
201  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1 ) ) \
202  int ( *initKeyFunction )( INOUT CI_STRUCT *contextInfoPtr,
203  IN_BUFFER_OPT( keyLength ) const void *key,
204  IN_LENGTH_SHORT_Z const int keyLength );
205  /* The key data can be NULL if it's a PKC
206  context whose key components have been read
207  directly into the context */
208  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1 ) ) \
209  int ( *generateKeyFunction )( INOUT CI_STRUCT *contextInfoPtr, \
210  IN_LENGTH_SHORT const int keySizeBits );
211  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
212  int ( *encryptFunction )( INOUT CI_STRUCT *contextInfoPtr,
213  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
214  IN_LENGTH_Z int length );
215  /* Length may be zero for hash functions */
216  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
217  int ( *decryptFunction )( INOUT CI_STRUCT *contextInfoPtr,
218  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
219  IN_LENGTH int length );
220  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
221  int ( *encryptCBCFunction )( INOUT CI_STRUCT *contextInfoPtr,
222  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
223  IN_LENGTH int length );
224  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
225  int ( *decryptCBCFunction )( INOUT CI_STRUCT *contextInfoPtr,
226  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
227  IN_LENGTH int length );
228  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
229  int ( *encryptCFBFunction )( INOUT CI_STRUCT *contextInfoPtr,
230  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
231  IN_LENGTH int length );
232  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
233  int ( *decryptCFBFunction )( INOUT CI_STRUCT *contextInfoPtr,
234  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
235  IN_LENGTH int length );
236  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
237  int ( *encryptOFBFunction )( INOUT CI_STRUCT *contextInfoPtr,
238  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
239  IN_LENGTH int length );
240  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
241  int ( *decryptOFBFunction )( INOUT CI_STRUCT *contextInfoPtr,
242  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
243  IN_LENGTH int length );
244  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
245  int ( *encryptGCMFunction )( INOUT CI_STRUCT *contextInfoPtr,
246  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
247  IN_LENGTH int length );
248  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
249  int ( *decryptGCMFunction )( INOUT CI_STRUCT *contextInfoPtr,
250  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
251  IN_LENGTH int length );
252  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
253  int ( *signFunction )( INOUT CI_STRUCT *contextInfoPtr,
254  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
255  IN_LENGTH_SHORT_MIN( MIN_PKCSIZE ) int length );
256  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
257  int ( *sigCheckFunction )( INOUT CI_STRUCT *contextInfoPtr,
258  INOUT_BUFFER_FIXED( length ) BYTE *buffer,
259  IN_LENGTH_SHORT_MIN( MIN_PKCSIZE ) int length );
260 
261  int param1, param2, param3, param4; /* Non-const */
262  } VARIABLE_CAPABILITY_INFO;
263 
264 /****************************************************************************
265 * *
266 * Internal API Functions *
267 * *
268 ****************************************************************************/
269 
270 /* Prototypes for capability access functions */
271 
272 typedef const CAPABILITY_INFO * ( *GETCAPABILITY_FUNCTION )( void );
273 
274 const CAPABILITY_INFO *get3DESCapability( void );
275 const CAPABILITY_INFO *getAESCapability( void );
276 const CAPABILITY_INFO *getBlowfishCapability( void );
277 const CAPABILITY_INFO *getDESCapability( void );
278 const CAPABILITY_INFO *getIDEACapability( void );
279 const CAPABILITY_INFO *getRC2Capability( void );
280 const CAPABILITY_INFO *getRC4Capability( void );
281 const CAPABILITY_INFO *getRC5Capability( void );
282 
283 const CAPABILITY_INFO *getMD5Capability( void );
284 const CAPABILITY_INFO *getRipemd160Capability( void );
285 const CAPABILITY_INFO *getSHA1Capability( void );
286 const CAPABILITY_INFO *getSHA2Capability( void );
287 
288 const CAPABILITY_INFO *getHmacMD5Capability( void );
289 const CAPABILITY_INFO *getHmacRipemd160Capability( void );
290 const CAPABILITY_INFO *getHmacSHA1Capability( void );
291 const CAPABILITY_INFO *getHmacSHA2Capability( void );
292 
293 const CAPABILITY_INFO *getDHCapability( void );
294 const CAPABILITY_INFO *getDSACapability( void );
295 const CAPABILITY_INFO *getElgamalCapability( void );
296 const CAPABILITY_INFO *getRSACapability( void );
297 const CAPABILITY_INFO *getECDSACapability( void );
298 const CAPABILITY_INFO *getECDHCapability( void );
299 
300 const CAPABILITY_INFO *getGenericSecretCapability( void );
301 
302 /* Prototypes for functions in cryptctx.c, used by devices to create native
303  contexts */
304 
305 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
306 int createContext( INOUT MESSAGE_CREATEOBJECT_INFO *createInfo,
307  IN const void *auxDataPtr,
308  IN_FLAGS_Z( CREATEOBJECT ) const int auxValue );
309 
310 /* Prototypes for capability functions in context/ctx_misc.c */
311 
312 CHECK_RETVAL_PTR STDC_NONNULL_ARG( ( 1 ) ) \
313 const CAPABILITY_INFO FAR_BSS *findCapabilityInfo(
314  const CAPABILITY_INFO_LIST *capabilityInfoList,
315  IN_ALGO const CRYPT_ALGO_TYPE cryptAlgo );
316 STDC_NONNULL_ARG( ( 1, 2 ) ) \
317 void getCapabilityInfo( OUT CRYPT_QUERY_INFO *cryptQueryInfo,
318  const CAPABILITY_INFO FAR_BSS *capabilityInfoPtr );
319 CHECK_RETVAL_BOOL STDC_NONNULL_ARG( ( 1 ) ) \
320 BOOLEAN sanityCheckCapability( const CAPABILITY_INFO *capabilityInfoPtr,
321  const BOOLEAN asymmetricOK );
322  /* The asymmetricOK flag indicates that the capabilities can have
323  asymmetric functionality, for example sign is supported but sig.
324  check isn't (this is required for some tinkertoy implementations
325  in crypto tokens which support bare-minimum functionality such as
326  RSA private-key ops and nothing else) */
327 
328 /* Fallback functions to handle context-specific information that isn't
329  specific to a particular context. The initial request goes to the
330  context, if that doesn't want to handle it it passes it on to the default
331  handler */
332 
333 CHECK_RETVAL STDC_NONNULL_ARG( ( 3 ) ) \
334 int getDefaultInfo( IN_ENUM( CAPABILITY_INFO ) const CAPABILITY_INFO_TYPE type,
335  INOUT_OPT CI_STRUCT *contextInfoPtr,
336  OUT void *data,
337  IN_INT_Z const int length );
338 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
339 int initGenericParams( INOUT CI_STRUCT *contextInfoPtr,
340  IN_ENUM( KEYPARAM ) const KEYPARAM_TYPE paramType,
341  IN_OPT const void *data,
342  IN_INT const int dataLength );
343 
344 #endif /* _CRYPTCAP_DEFINED */
Generated on Thu Jan 10 2013 10:00:46 for cryptlib by   doxygen 1.8.2