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