1 /* pkcs11.h include file for PKCS #11. */ 2 /* $Revision: 1.4 $ */ 3 4 /* License to copy and use this software is granted provided that it is 5 * identified as "RSA Security Inc. PKCS #11 Cryptographic Token Interface 6 * (Cryptoki)" in all material mentioning or referencing this software. 7 8 * License is also granted to make and use derivative works provided that 9 * such works are identified as "derived from the RSA Security Inc. PKCS #11 10 * Cryptographic Token Interface (Cryptoki)" in all material mentioning or 11 * referencing the derived work. 12 13 * RSA Security Inc. makes no representations concerning either the 14 * merchantability of this software or the suitability of this software for 15 * any particular purpose. It is provided "as is" without express or implied 16 * warranty of any kind. 17 */ 18 19 #ifndef _PKCS11_H_ 20 #define _PKCS11_H_ 1 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /* Before including this file (pkcs11.h) (or pkcs11t.h by 27 * itself), 6 platform-specific macros must be defined. These 28 * macros are described below, and typical definitions for them 29 * are also given. Be advised that these definitions can depend 30 * on both the platform and the compiler used (and possibly also 31 * on whether a Cryptoki library is linked statically or 32 * dynamically). 33 * 34 * In addition to defining these 6 macros, the packing convention 35 * for Cryptoki structures should be set. The Cryptoki 36 * convention on packing is that structures should be 1-byte 37 * aligned. 38 * 39 * If you're using Microsoft Developer Studio 5.0 to produce 40 * Win32 stuff, this might be done by using the following 41 * preprocessor directive before including pkcs11.h or pkcs11t.h: 42 * 43 * #pragma pack(push, cryptoki, 1) 44 * 45 * and using the following preprocessor directive after including 46 * pkcs11.h or pkcs11t.h: 47 * 48 * #pragma pack(pop, cryptoki) 49 * 50 * If you're using an earlier version of Microsoft Developer 51 * Studio to produce Win16 stuff, this might be done by using 52 * the following preprocessor directive before including 53 * pkcs11.h or pkcs11t.h: 54 * 55 * #pragma pack(1) 56 * 57 * In a UNIX environment, you're on your own for this. You might 58 * not need to do (or be able to do!) anything. 59 * 60 * 61 * Now for the macros: 62 * 63 * 64 * 1. CK_PTR: The indirection string for making a pointer to an 65 * object. It can be used like this: 66 * 67 * typedef CK_BYTE CK_PTR CK_BYTE_PTR; 68 * 69 * If you're using Microsoft Developer Studio 5.0 to produce 70 * Win32 stuff, it might be defined by: 71 * 72 * #define CK_PTR * 73 * 74 * If you're using an earlier version of Microsoft Developer 75 * Studio to produce Win16 stuff, it might be defined by: 76 * 77 * #define CK_PTR far * 78 * 79 * In a typical UNIX environment, it might be defined by: 80 * 81 * #define CK_PTR * 82 * 83 * 84 * 2. CK_DEFINE_FUNCTION(returnType, name): A macro which makes 85 * an exportable Cryptoki library function definition out of a 86 * return type and a function name. It should be used in the 87 * following fashion to define the exposed Cryptoki functions in 88 * a Cryptoki library: 89 * 90 * CK_DEFINE_FUNCTION(CK_RV, C_Initialize)( 91 * CK_VOID_PTR pReserved 92 * ) 93 * { 94 * ... 95 * } 96 * 97 * If you're using Microsoft Developer Studio 5.0 to define a 98 * function in a Win32 Cryptoki .dll, it might be defined by: 99 * 100 * #define CK_DEFINE_FUNCTION(returnType, name) \ 101 * returnType __declspec(dllexport) name 102 * 103 * If you're using an earlier version of Microsoft Developer 104 * Studio to define a function in a Win16 Cryptoki .dll, it 105 * might be defined by: 106 * 107 * #define CK_DEFINE_FUNCTION(returnType, name) \ 108 * returnType __export _far _pascal name 109 * 110 * In a UNIX environment, it might be defined by: 111 * 112 * #define CK_DEFINE_FUNCTION(returnType, name) \ 113 * returnType name 114 * 115 * 116 * 3. CK_DECLARE_FUNCTION(returnType, name): A macro which makes 117 * an importable Cryptoki library function declaration out of a 118 * return type and a function name. It should be used in the 119 * following fashion: 120 * 121 * extern CK_DECLARE_FUNCTION(CK_RV, C_Initialize)( 122 * CK_VOID_PTR pReserved 123 * ); 124 * 125 * If you're using Microsoft Developer Studio 5.0 to declare a 126 * function in a Win32 Cryptoki .dll, it might be defined by: 127 * 128 * #define CK_DECLARE_FUNCTION(returnType, name) \ 129 * returnType __declspec(dllimport) name 130 * 131 * If you're using an earlier version of Microsoft Developer 132 * Studio to declare a function in a Win16 Cryptoki .dll, it 133 * might be defined by: 134 * 135 * #define CK_DECLARE_FUNCTION(returnType, name) \ 136 * returnType __export _far _pascal name 137 * 138 * In a UNIX environment, it might be defined by: 139 * 140 * #define CK_DECLARE_FUNCTION(returnType, name) \ 141 * returnType name 142 * 143 * 144 * 4. CK_DECLARE_FUNCTION_POINTER(returnType, name): A macro 145 * which makes a Cryptoki API function pointer declaration or 146 * function pointer type declaration out of a return type and a 147 * function name. It should be used in the following fashion: 148 * 149 * // Define funcPtr to be a pointer to a Cryptoki API function 150 * // taking arguments args and returning CK_RV. 151 * CK_DECLARE_FUNCTION_POINTER(CK_RV, funcPtr)(args); 152 * 153 * or 154 * 155 * // Define funcPtrType to be the type of a pointer to a 156 * // Cryptoki API function taking arguments args and returning 157 * // CK_RV, and then define funcPtr to be a variable of type 158 * // funcPtrType. 159 * typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, funcPtrType)(args); 160 * funcPtrType funcPtr; 161 * 162 * If you're using Microsoft Developer Studio 5.0 to access 163 * functions in a Win32 Cryptoki .dll, in might be defined by: 164 * 165 * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \ 166 * returnType __declspec(dllimport) (* name) 167 * 168 * If you're using an earlier version of Microsoft Developer 169 * Studio to access functions in a Win16 Cryptoki .dll, it might 170 * be defined by: 171 * 172 * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \ 173 * returnType __export _far _pascal (* name) 174 * 175 * In a UNIX environment, it might be defined by: 176 * 177 * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \ 178 * returnType (* name) 179 * 180 * 181 * 5. CK_CALLBACK_FUNCTION(returnType, name): A macro which makes 182 * a function pointer type for an application callback out of 183 * a return type for the callback and a name for the callback. 184 * It should be used in the following fashion: 185 * 186 * CK_CALLBACK_FUNCTION(CK_RV, myCallback)(args); 187 * 188 * to declare a function pointer, myCallback, to a callback 189 * which takes arguments args and returns a CK_RV. It can also 190 * be used like this: 191 * 192 * typedef CK_CALLBACK_FUNCTION(CK_RV, myCallbackType)(args); 193 * myCallbackType myCallback; 194 * 195 * If you're using Microsoft Developer Studio 5.0 to do Win32 196 * Cryptoki development, it might be defined by: 197 * 198 * #define CK_CALLBACK_FUNCTION(returnType, name) \ 199 * returnType (* name) 200 * 201 * If you're using an earlier version of Microsoft Developer 202 * Studio to do Win16 development, it might be defined by: 203 * 204 * #define CK_CALLBACK_FUNCTION(returnType, name) \ 205 * returnType _far _pascal (* name) 206 * 207 * In a UNIX environment, it might be defined by: 208 * 209 * #define CK_CALLBACK_FUNCTION(returnType, name) \ 210 * returnType (* name) 211 * 212 * 213 * 6. NULL_PTR: This macro is the value of a NULL pointer. 214 * 215 * In any ANSI/ISO C environment (and in many others as well), 216 * this should best be defined by 217 * 218 * #ifndef NULL_PTR 219 * #define NULL_PTR 0 220 * #endif 221 */ 222 223 224 /* All the various Cryptoki types and #define'd values are in the 225 * file pkcs11t.h. */ 226 #include "pkcs11t.h" 227 228 #define __PASTE(x,y) x##y 229 230 231 /* ============================================================== 232 * Define the "extern" form of all the entry points. 233 * ============================================================== 234 */ 235 236 #define CK_NEED_ARG_LIST 1 237 #define CK_PKCS11_FUNCTION_INFO(name) \ 238 extern CK_DECLARE_FUNCTION(CK_RV, name) 239 240 /* pkcs11f.h has all the information about the Cryptoki 241 * function prototypes. */ 242 #include "pkcs11f.h" 243 244 #undef CK_NEED_ARG_LIST 245 #undef CK_PKCS11_FUNCTION_INFO 246 247 248 /* ============================================================== 249 * Define the typedef form of all the entry points. That is, for 250 * each Cryptoki function C_XXX, define a type CK_C_XXX which is 251 * a pointer to that kind of function. 252 * ============================================================== 253 */ 254 255 #define CK_NEED_ARG_LIST 1 256 #define CK_PKCS11_FUNCTION_INFO(name) \ 257 typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, __PASTE(CK_,name)) 258 259 /* pkcs11f.h has all the information about the Cryptoki 260 * function prototypes. */ 261 #include "pkcs11f.h" 262 263 #undef CK_NEED_ARG_LIST 264 #undef CK_PKCS11_FUNCTION_INFO 265 266 267 /* ============================================================== 268 * Define structed vector of entry points. A CK_FUNCTION_LIST 269 * contains a CK_VERSION indicating a library's Cryptoki version 270 * and then a whole slew of function pointers to the routines in 271 * the library. This type was declared, but not defined, in 272 * pkcs11t.h. 273 * ============================================================== 274 */ 275 276 #define CK_PKCS11_FUNCTION_INFO(name) \ 277 __PASTE(CK_,name) name; 278 279 struct CK_FUNCTION_LIST { 280 281 CK_VERSION version; /* Cryptoki version */ 282 283 /* Pile all the function pointers into the CK_FUNCTION_LIST. */ 284 /* pkcs11f.h has all the information about the Cryptoki 285 * function prototypes. */ 286 #include "pkcs11f.h" 287 288 }; 289 290 #undef CK_PKCS11_FUNCTION_INFO 291 292 293 #undef __PASTE 294 295 #ifdef __cplusplus 296 } 297 #endif 298 299 #endif 300