tls/tests/pkcs11/pkcs11.h

   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 /* packing defines */
 183 #include "pkcs11p.h"
 184 /* ==============================================================
 185  * Define the "extern" form of all the entry points.
 186  * ==============================================================
 187  */
 188
 189 #define CK_NEED_ARG_LIST 1
 190 #define CK_PKCS11_FUNCTION_INFO(name) \
 191     CK_DECLARE_FUNCTION(CK_RV, name)
 192
 193 /* pkcs11f.h has all the information about the PKCS #11
 194  * function prototypes. */
 195 #include "pkcs11f.h"
 196
 197 #undef CK_NEED_ARG_LIST
 198 #undef CK_PKCS11_FUNCTION_INFO
 199
 200 /* ==============================================================
 201  * Define the typedef form of all the entry points.  That is, for
 202  * each PKCS #11 function C_XXX, define a type CK_C_XXX which is
 203  * a pointer to that kind of function.
 204  * ==============================================================
 205  */
 206
 207 #define CK_NEED_ARG_LIST 1
 208 #define CK_PKCS11_FUNCTION_INFO(name) \
 209     typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, __PASTE(CK_, name))
 210
 211 /* pkcs11f.h has all the information about the PKCS #11
 212  * function prototypes. */
 213 #include "pkcs11f.h"
 214
 215 #undef CK_NEED_ARG_LIST
 216 #undef CK_PKCS11_FUNCTION_INFO
 217
 218 /* ==============================================================
 219  * Define structed vector of entry points.  A CK_FUNCTION_LIST
 220  * contains a CK_VERSION indicating a library's PKCS #11 version
 221  * and then a whole slew of function pointers to the routines in
 222  * the library.  This type was declared, but not defined, in
 223  * pkcs11t.h.
 224  * ==============================================================
 225  */
 226
 227 #define CK_PKCS11_FUNCTION_INFO(name) \
 228     __PASTE(CK_, name)                \
 229     name;
 230
 231 struct CK_FUNCTION_LIST {
 232
 233     CK_VERSION version; /* PKCS #11 version */
 234
 235 /* Pile all the function pointers into the CK_FUNCTION_LIST. */
 236 /* pkcs11f.h has all the information about the PKCS #11
 237  * function prototypes. */
 238 #include "pkcs11f.h"
 239 };
 240
 241 #undef CK_PKCS11_FUNCTION_INFO
 242
 243 #undef __PASTE
 244
 245 /* unpack */
 246 #include "pkcs11u.h"
 247
 248 #ifdef __cplusplus
 249 }
 250 #endif
 251
 252 #endif