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 CHECK_RETVAL \ 55 int ( *CAP_SELFTEST_FUNCTION )( void ); 56 typedef CHECK_RETVAL STDC_NONNULL_ARG( ( 3 ) ) \ 57 int ( *CAP_GETINFO_FUNCTION )( IN_ENUM( CAPABILITY_INFO ) \ 58 const CAPABILITY_INFO_TYPE type, 59 INOUT_OPT CI_STRUCT *contextInfoPtr, 60 OUT void *data, 61 IN_INT_Z const int length ); 62 typedef RETVAL STDC_NONNULL_ARG( ( 1 ) ) \ 63 int ( *CAP_END_FUNCTION )( INOUT CI_STRUCT *contextInfoPtr ); 64 typedef CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \ 65 int ( *CAP_INITPARAMS_FUNCTION )( INOUT CI_STRUCT *contextInfoPtr, 66 IN_ENUM( KEYPARAM ) \ 67 const KEYPARAM_TYPE paramType, 68 IN_OPT const void *data, 69 IN_INT const int dataLength ); 70 typedef CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \ 71 int ( *CAP_INITKEY_FUNCTION )( INOUT CI_STRUCT *contextInfoPtr, 72 IN_BUFFER_OPT( keyLength ) const void *key, 73 IN_LENGTH_SHORT_Z const int keyLength ); 74 /* The key data can be NULL if it's a PKC 75 context whose key components have been 76 read directly into the context, which 77 is also why we can't use IN_LENGTH_KEY 78 for the length */ 79 typedef CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \ 80 int ( *CAP_GENERATEKEY_FUNCTION )( INOUT CI_STRUCT *contextInfoPtr, \ 81 IN_RANGE( bytesToBits( MIN_KEYSIZE ), 82 bytesToBits( CRYPT_MAX_PKCSIZE ) ) \ 83 const int keySizeBits ); 84 typedef CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \ 85 int ( *CAP_ENCRYPTSPECIAL_FUNCTION )( INOUT CI_STRUCT *contextInfoPtr, 86 INOUT_BUFFER_FIXED( length ) BYTE *buffer, 87 IN_LENGTH_Z int length ); 88 /* Length may be zero for hash functions */ 89 typedef CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \ 90 int ( *CAP_ENCRYPT_FUNCTION )( INOUT CI_STRUCT *contextInfoPtr, 91 INOUT_BUFFER_FIXED( length ) BYTE *buffer, 92 IN_LENGTH int length ); 93 typedef CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \ 94 int ( *CAP_SIGN_FUNCTION )( INOUT CI_STRUCT *contextInfoPtr, 95 INOUT_BUFFER_FIXED( length ) BYTE *buffer, 96 IN_LENGTH_SHORT_MIN( 32 ) int length ); 97 98 typedef struct CA { 99 /* Basic identification information for the algorithm */ 100 const CRYPT_ALGO_TYPE cryptAlgo;/* The encryption algorithm */ 101 const int blockSize; /* The basic block size of the algorithm */ 102 BUFFER_FIXED( algoNameLen ) \ 103 const char *algoName; /* Algorithm name */ 104 const int algoNameLen; /* Algorithm name length */ 105 106 /* Keying information. Note that the maximum sizes may vary (for 107 example for two-key triple DES vs.three-key triple DES) so the 108 crypt query functions should be used to determine the actual size 109 for a particular context rather than just using maxKeySize */ 110 const int minKeySize; /* Minimum key size in bytes */ 111 const int keySize; /* Recommended key size in bytes */ 112 const int maxKeySize; /* Maximum key size in bytes */ 113 114 /* The functions for implementing the algorithm */ 115 CAP_SELFTEST_FUNCTION selfTestFunction; 116 CAP_GETINFO_FUNCTION getInfoFunction; 117 CAP_END_FUNCTION endFunction; 118 CAP_INITPARAMS_FUNCTION initParamsFunction; 119 CAP_INITKEY_FUNCTION initKeyFunction; 120 CAP_GENERATEKEY_FUNCTION generateKeyFunction; 121 CAP_ENCRYPTSPECIAL_FUNCTION encryptFunction; 122 CAP_ENCRYPT_FUNCTION decryptFunction; 123 CAP_ENCRYPT_FUNCTION encryptCBCFunction, decryptCBCFunction; 124 CAP_ENCRYPT_FUNCTION encryptCFBFunction, decryptCFBFunction; 125 CAP_ENCRYPT_FUNCTION encryptGCMFunction, decryptGCMFunction; 126 CAP_SIGN_FUNCTION signFunction, sigCheckFunction; 127 128 /* Non-native implementations may require extra parameters (for example 129 to specify the algorithm and mode in the manner required by the 130 non-native implementation), the following values can be used to store 131 these parameters */ 132 const int param1, param2, param3, param4; 133 } CAPABILITY_INFO; 134 135 /* An encapsulating list type for the list of capabilities */ 136 137 typedef struct CL { 138 const CAPABILITY_INFO *info; 139 struct CL *next; 140 } CAPABILITY_INFO_LIST; 141 142 /* Since cryptlib's CAPABILITY_INFO is fixed, all of the fields are declared 143 const so that they'll be allocated in the code segment. This doesn't quite 144 work for some types of crypto devices since things like the available key 145 lengths can vary depending on the underlying hardware or software, so we 146 provide an equivalent structure that makes the variable fields non-const. 147 Once the fields are set up, the result is copied into a dynamically- 148 allocated CAPABILITY_INFO block at which point the fields are treated as 149 const by the code */ 150 151 typedef struct { 152 const CRYPT_ALGO_TYPE cryptAlgo; 153 const int blockSize; 154 BUFFER_FIXED( algoNameLen ) \ 155 const char *algoName; 156 const int algoNameLen; 157 158 int minKeySize; /* Non-const */ 159 int keySize; /* Non-const */ 160 int maxKeySize; /* Non-const */ 161 162 CAP_SELFTEST_FUNCTION selfTestFunction; 163 CAP_GETINFO_FUNCTION getInfoFunction; 164 CAP_END_FUNCTION endFunction; 165 CAP_INITPARAMS_FUNCTION initParamsFunction; 166 CAP_INITKEY_FUNCTION initKeyFunction; 167 CAP_GENERATEKEY_FUNCTION generateKeyFunction; 168 CAP_ENCRYPTSPECIAL_FUNCTION encryptFunction; 169 CAP_ENCRYPT_FUNCTION decryptFunction; 170 CAP_ENCRYPT_FUNCTION encryptCBCFunction, decryptCBCFunction; 171 CAP_ENCRYPT_FUNCTION encryptCFBFunction, decryptCFBFunction; 172 CAP_ENCRYPT_FUNCTION encryptGCMFunction, decryptGCMFunction; 173 CAP_SIGN_FUNCTION signFunction, sigCheckFunction; 174 175 int param1, param2, param3, param4; /* Non-const */ 176 } VARIABLE_CAPABILITY_INFO; 177 178 /**************************************************************************** 179 * * 180 * Internal API Functions * 181 * * 182 ****************************************************************************/ 183 184 /* Prototypes for capability access functions */ 185 186 typedef const CAPABILITY_INFO * ( *GETCAPABILITY_FUNCTION )( void ); 187 188 const CAPABILITY_INFO *get3DESCapability( void ); 189 const CAPABILITY_INFO *getAESCapability( void ); 190 const CAPABILITY_INFO *getCASTCapability( void ); 191 const CAPABILITY_INFO *getDESCapability( void ); 192 const CAPABILITY_INFO *getIDEACapability( void ); 193 const CAPABILITY_INFO *getRC2Capability( void ); 194 const CAPABILITY_INFO *getRC4Capability( void ); 195 196 const CAPABILITY_INFO *getMD5Capability( void ); 197 const CAPABILITY_INFO *getSHA1Capability( void ); 198 const CAPABILITY_INFO *getSHA2Capability( void ); 199 200 const CAPABILITY_INFO *getHmacMD5Capability( void ); 201 const CAPABILITY_INFO *getHmacSHA1Capability( void ); 202 const CAPABILITY_INFO *getHmacSHA2Capability( void ); 203 204 const CAPABILITY_INFO *getDHCapability( void ); 205 const CAPABILITY_INFO *getDSACapability( void ); 206 const CAPABILITY_INFO *getElgamalCapability( void ); 207 const CAPABILITY_INFO *getRSACapability( void ); 208 const CAPABILITY_INFO *getECDSACapability( void ); 209 const CAPABILITY_INFO *getECDHCapability( void ); 210 211 const CAPABILITY_INFO *getGenericSecretCapability( void ); 212 213 /* Prototypes for functions in cryptctx.c, used by devices to create native 214 contexts */ 215 216 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \ 217 int createContext( INOUT MESSAGE_CREATEOBJECT_INFO *createInfo, 218 IN const void *auxDataPtr, 219 IN_FLAGS_Z( CREATEOBJECT ) const int auxValue ); 220 221 /* Prototypes for capability functions in context/ctx_misc.c */ 222 223 CHECK_RETVAL_PTR STDC_NONNULL_ARG( ( 1 ) ) \ 224 const CAPABILITY_INFO FAR_BSS *findCapabilityInfo( 225 const CAPABILITY_INFO_LIST *capabilityInfoList, 226 IN_ALGO const CRYPT_ALGO_TYPE cryptAlgo ); 227 STDC_NONNULL_ARG( ( 1, 2 ) ) \ 228 void getCapabilityInfo( OUT CRYPT_QUERY_INFO *cryptQueryInfo, 229 const CAPABILITY_INFO FAR_BSS *capabilityInfoPtr ); 230 CHECK_RETVAL_BOOL STDC_NONNULL_ARG( ( 1 ) ) \ 231 BOOLEAN sanityCheckCapability( const CAPABILITY_INFO *capabilityInfoPtr ); 232 233 /* Fallback functions to handle context-specific information that isn't 234 specific to a particular context. The initial request goes to the 235 context, if that doesn't want to handle it it passes it on to the default 236 handler */ 237 238 CHECK_RETVAL STDC_NONNULL_ARG( ( 3 ) ) \ 239 int getDefaultInfo( IN_ENUM( CAPABILITY_INFO ) const CAPABILITY_INFO_TYPE type, 240 INOUT_OPT CI_STRUCT *contextInfoPtr, 241 OUT void *data, 242 IN_INT_Z const int length ); 243 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \ 244 int initGenericParams( INOUT CI_STRUCT *contextInfoPtr, 245 IN_ENUM( KEYPARAM ) const KEYPARAM_TYPE paramType, 246 IN_OPT const void *data, 247 IN_INT const int dataLength ); 248 249 #endif /* _CRYPTCAP_DEFINED */ 250