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 #ifndef CK_PKCS11_3_0 183 /* remember that we set it so we can unset it at the end */ 184 #define __NSS_CK_PKCS11_3_IMPLICIT 1 185 #define CK_PKCS11_3_0 1 186 #endif 187 188 /* ============================================================== 189 * Define the "extern" form of all the entry points. 190 * ============================================================== 191 */ 192 193 #define CK_NEED_ARG_LIST 1 194 #define CK_PKCS11_FUNCTION_INFO(name) \ 195 CK_DECLARE_FUNCTION(CK_RV, name) 196 197 /* pkcs11f.h has all the information about the PKCS #11 198 * function prototypes. */ 199 #include "pkcs11f.h" 200 201 #undef CK_NEED_ARG_LIST 202 #undef CK_PKCS11_FUNCTION_INFO 203 204 /* ============================================================== 205 * Define the typedef form of all the entry points. That is, for 206 * each PKCS #11 function C_XXX, define a type CK_C_XXX which is 207 * a pointer to that kind of function. 208 * ============================================================== 209 */ 210 211 #define CK_NEED_ARG_LIST 1 212 #define CK_PKCS11_FUNCTION_INFO(name) \ 213 typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, __PASTE(CK_, name)) 214 215 /* pkcs11f.h has all the information about the PKCS #11 216 * function prototypes. */ 217 #include "pkcs11f.h" 218 219 #undef CK_NEED_ARG_LIST 220 #undef CK_PKCS11_FUNCTION_INFO 221 222 /* ============================================================== 223 * Define structed vector of entry points. A CK_FUNCTION_3_0_LIST 224 * contains a CK_VERSION indicating a library's PKCS #11 version 225 * and then a whole slew of function pointers to the routines in 226 * the library. This type was declared, but not defined, in 227 * pkcs11t.h. 228 * ============================================================== 229 */ 230 231 #define CK_PKCS11_FUNCTION_INFO(name) \ 232 __PASTE(CK_, name) \ 233 name; 234 235 #include "pkcs11p.h" 236 struct CK_FUNCTION_LIST_3_0 { 237 238 CK_VERSION version; /* PKCS #11 version */ 239 240 /* Pile all the function pointers into the CK_FUNCTION_LIST_3_0. */ 241 /* pkcs11f.h has all the information about the PKCS #11 242 * function prototypes. */ 243 #include "pkcs11f.h" 244 }; 245 246 #define CK_PKCS11_2_0_ONLY 1 247 248 /* now define the 2.0 function list */ 249 struct CK_FUNCTION_LIST { 250 251 CK_VERSION version; /* PKCS #11 version */ 252 253 /* Pile all the function pointers into the CK_FUNCTION_LIST. */ 254 /* pkcs11f.h has all the information about the PKCS #11 255 * function prototypes. */ 256 #include "pkcs11f.h" 257 }; 258 #include "pkcs11u.h" 259 260 #undef CK_PKCS11_FUNCTION_INFO 261 #undef CK_PKCS11_2_0_ONLY 262 263 #ifdef __NSS_CK_PKCS11_3_IMPLICIT 264 #undef CK_PKCS11_3_0 265 #undef __NSS_CK_PKCS11_3_IMPLICIT 266 #endif 267 268 #undef __PASTE 269 270 #ifdef __cplusplus 271 } 272 #endif 273 274 #endif 275