security/nss/lib/softoken/pkcs11.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is the Netscape security libraries.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Netscape Communications Corporation.
  18  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   RSA Labs
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37 /*
  38  * Copyright (C) 1994-1999 RSA Security Inc. Licence to copy this document
  39  * is granted provided that it is identified as "RSA Security In.c Public-Key
  40  * Cryptography Standards (PKCS)" in all material mentioning or referencing
  41  * this document.
  42  *
  43  * The latest version of this header can be found at:
  44  *    http://www.rsalabs.com/pkcs/pkcs-11/index.html
  45  */
  46 #ifndef _PKCS11_H_
  47 #define _PKCS11_H_ 1
  48
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif
  52
  53 /* Before including this file (pkcs11.h) (or pkcs11t.h by
  54  * itself), 6 platform-specific macros must be defined.  These
  55  * macros are described below, and typical definitions for them
  56  * are also given.  Be advised that these definitions can depend
  57  * on both the platform and the compiler used (and possibly also
  58  * on whether a PKCS #11 library is linked statically or
  59  * dynamically).
  60  *
  61  * In addition to defining these 6 macros, the packing convention
  62  * for PKCS #11 structures should be set.  The PKCS #11
  63  * convention on packing is that structures should be 1-byte
  64  * aligned.
  65  *
  66  * In a Win32 environment, this might be done by using the
  67  * following preprocessor directive before including pkcs11.h
  68  * or pkcs11t.h:
  69  *
  70  * #pragma pack(push, cryptoki, 1)
  71  *
  72  * and using the following preprocessor directive after including
  73  * pkcs11.h or pkcs11t.h:
  74  *
  75  * #pragma pack(pop, cryptoki)
  76  *
  77  * In a Win16 environment, this might be done by using the
  78  * following preprocessor directive before including pkcs11.h
  79  * or pkcs11t.h:
  80  *
  81  * #pragma pack(1)
  82  *
  83  * In a UNIX environment, you're on your own here.  You might
  84  * not need to do anything.
  85  *
  86  *
  87  * Now for the macros:
  88  *
  89  *
  90  * 1. CK_PTR: The indirection string for making a pointer to an
  91  * object.  It can be used like this:
  92  *
  93  * typedef CK_BYTE CK_PTR CK_BYTE_PTR;
  94  *
  95  * In a Win32 environment, it might be defined by
  96  *
  97  * #define CK_PTR *
  98  *
  99  * In a Win16 environment, it might be defined by
 100  *
 101  * #define CK_PTR far *
 102  *
 103  * In a UNIX environment, it might be defined by
 104  *
 105  * #define CK_PTR *
 106  *
 107  *
 108  * 2. CK_DEFINE_FUNCTION(returnType, name): A macro which makes
 109  * an exportable PKCS #11 library function definition out of a
 110  * return type and a function name.  It should be used in the
 111  * following fashion to define the exposed PKCS #11 functions in
 112  * a PKCS #11 library:
 113  *
 114  * CK_DEFINE_FUNCTION(CK_RV, C_Initialize)(
 115  *   CK_VOID_PTR pReserved
 116  * )
 117  * {
 118  *   ...
 119  * }
 120  *
 121  * For defining a function in a Win32 PKCS #11 .dll, it might be
 122  * defined by
 123  *
 124  * #define CK_DEFINE_FUNCTION(returnType, name) \
 125  *   returnType __declspec(dllexport) name
 126  *
 127  * For defining a function in a Win16 PKCS #11 .dll, it might be
 128  * defined by
 129  *
 130  * #define CK_DEFINE_FUNCTION(returnType, name) \
 131  *   returnType __export _far _pascal name
 132  *
 133  * In a UNIX environment, it might be defined by
 134  *
 135  * #define CK_DEFINE_FUNCTION(returnType, name) \
 136  *   returnType name
 137  *
 138  *
 139  * 3. CK_DECLARE_FUNCTION(returnType, name): A macro which makes
 140  * an importable PKCS #11 library function declaration out of a
 141  * return type and a function name.  It should be used in the
 142  * following fashion:
 143  *
 144  * extern CK_DECLARE_FUNCTION(CK_RV, C_Initialize)(
 145  *   CK_VOID_PTR pReserved
 146  * );
 147  *
 148  * For declaring a function in a Win32 PKCS #11 .dll, it might
 149  * be defined by
 150  *
 151  * #define CK_DECLARE_FUNCTION(returnType, name) \
 152  *   returnType __declspec(dllimport) name
 153  *
 154  * For declaring a function in a Win16 PKCS #11 .dll, it might
 155  * be defined by
 156  *
 157  * #define CK_DECLARE_FUNCTION(returnType, name) \
 158  *   returnType __export _far _pascal name
 159  *
 160  * In a UNIX environment, it might be defined by
 161  *
 162  * #define CK_DECLARE_FUNCTION(returnType, name) \
 163  *   returnType name
 164  *
 165  *
 166  * 4. CK_DECLARE_FUNCTION_POINTER(returnType, name): A macro
 167  * which makes a PKCS #11 API function pointer declaration or
 168  * function pointer type declaration out of a return type and a
 169  * function name.  It should be used in the following fashion:
 170  *
 171  * // Define funcPtr to be a pointer to a PKCS #11 API function
 172  * // taking arguments args and returning CK_RV.
 173  * CK_DECLARE_FUNCTION_POINTER(CK_RV, funcPtr)(args);
 174  *
 175  * or
 176  *
 177  * // Define funcPtrType to be the type of a pointer to a
 178  * // PKCS #11 API function taking arguments args and returning
 179  * // CK_RV, and then define funcPtr to be a variable of type
 180  * // funcPtrType.
 181  * typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, funcPtrType)(args);
 182  * funcPtrType funcPtr;
 183  *
 184  * For accessing functions in a Win32 PKCS #11 .dll, in might be
 185  * defined by
 186  *
 187  * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \
 188  *   returnType __declspec(dllimport) (* name)
 189  *
 190  * For accessing functions in a Win16 PKCS #11 .dll, it might be
 191  * defined by
 192  *
 193  * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \
 194  *   returnType __export _far _pascal (* name)
 195  *
 196  * In a UNIX environment, it might be defined by
 197  *
 198  * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \
 199  *   returnType (* name)
 200  *
 201  *
 202  * 5. CK_CALLBACK_FUNCTION(returnType, name): A macro which makes
 203  * a function pointer type for an application callback out of
 204  * a return type for the callback and a name for the callback.
 205  * It should be used in the following fashion:
 206  *
 207  * CK_CALLBACK_FUNCTION(CK_RV, myCallback)(args);
 208  *
 209  * to declare a function pointer, myCallback, to a callback
 210  * which takes arguments args and returns a CK_RV.  It can also
 211  * be used like this:
 212  *
 213  * typedef CK_CALLBACK_FUNCTION(CK_RV, myCallbackType)(args);
 214  * myCallbackType myCallback;
 215  *
 216  * In a Win32 environment, it might be defined by
 217  *
 218  * #define CK_CALLBACK_FUNCTION(returnType, name) \
 219  *   returnType (* name)
 220  *
 221  * In a Win16 environment, it might be defined by
 222  *
 223  * #define CK_CALLBACK_FUNCTION(returnType, name) \
 224  *   returnType _far _pascal (* name)
 225  *
 226  * In a UNIX environment, it might be defined by
 227  *
 228  * #define CK_CALLBACK_FUNCTION(returnType, name) \
 229  *   returnType (* name)
 230  *
 231  *
 232  * 6. NULL_PTR: This macro is the value of a NULL pointer.
 233  *
 234  * In any ANSI/ISO C environment (and in many others as well),
 235  * this should be defined by
 236  *
 237  * #ifndef NULL_PTR
 238  * #define NULL_PTR 0
 239  * #endif
 240  */
 241
 242
 243 /* All the various PKCS #11 types and #define'd values are in the
 244  * file pkcs11t.h. */
 245 #include "pkcs11t.h"
 246
 247 #define __PASTE(x,y)      x##y
 248
 249
 250 /* packing defines */
 251 #include "pkcs11p.h"
 252 /* ==============================================================
 253  * Define the "extern" form of all the entry points.
 254  * ==============================================================
 255  */
 256
 257 #define CK_NEED_ARG_LIST  1
 258 #define CK_PKCS11_FUNCTION_INFO(name) \
 259   CK_DECLARE_FUNCTION(CK_RV, name)
 260
 261 /* pkcs11f.h has all the information about the PKCS #11
 262  * function prototypes. */
 263 #include "pkcs11f.h"
 264
 265 #undef CK_NEED_ARG_LIST
 266 #undef CK_PKCS11_FUNCTION_INFO
 267
 268
 269 /* ==============================================================
 270  * Define the typedef form of all the entry points.  That is, for
 271  * each PKCS #11 function C_XXX, define a type CK_C_XXX which is
 272  * a pointer to that kind of function.
 273  * ==============================================================
 274  */
 275
 276 #define CK_NEED_ARG_LIST  1
 277 #define CK_PKCS11_FUNCTION_INFO(name) \
 278   typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, __PASTE(CK_,name))
 279
 280 /* pkcs11f.h has all the information about the PKCS #11
 281  * function prototypes. */
 282 #include "pkcs11f.h"
 283
 284 #undef CK_NEED_ARG_LIST
 285 #undef CK_PKCS11_FUNCTION_INFO
 286
 287
 288 /* ==============================================================
 289  * Define structed vector of entry points.  A CK_FUNCTION_LIST
 290  * contains a CK_VERSION indicating a library's PKCS #11 version
 291  * and then a whole slew of function pointers to the routines in
 292  * the library.  This type was declared, but not defined, in
 293  * pkcs11t.h.
 294  * ==============================================================
 295  */
 296
 297 #define CK_PKCS11_FUNCTION_INFO(name) \
 298   __PASTE(CK_,name) name;
 299
 300 struct CK_FUNCTION_LIST {
 301
 302   CK_VERSION    version;  /* PKCS #11 version */
 303
 304 /* Pile all the function pointers into the CK_FUNCTION_LIST. */
 305 /* pkcs11f.h has all the information about the PKCS #11
 306  * function prototypes. */
 307 #include "pkcs11f.h"
 308
 309 };
 310
 311 #undef CK_PKCS11_FUNCTION_INFO
 312
 313
 314 #undef __PASTE
 315
 316 /* unpack */
 317 #include "pkcs11u.h"
 318
 319 #ifdef __cplusplus
 320 }
 321 #endif
 322
 323 #endif