Back to index

lightning-sunbird  0.9+nobinonly
pkcs11.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *   RSA Labs
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 /*
00038  * Copyright (C) 1994-1999 RSA Security Inc. Licence to copy this document
00039  * is granted provided that it is identified as "RSA Security In.c Public-Key
00040  * Cryptography Standards (PKCS)" in all material mentioning or referencing
00041  * this document.
00042  *
00043  * The latest version of this header can be found at:
00044  *    http://www.rsalabs.com/pkcs/pkcs-11/index.html
00045  */
00046 #ifndef _PKCS11_H_
00047 #define _PKCS11_H_ 1
00048 
00049 #ifdef __cplusplus
00050 extern "C" {
00051 #endif
00052 
00053 /* Before including this file (pkcs11.h) (or pkcs11t.h by
00054  * itself), 6 platform-specific macros must be defined.  These
00055  * macros are described below, and typical definitions for them
00056  * are also given.  Be advised that these definitions can depend
00057  * on both the platform and the compiler used (and possibly also
00058  * on whether a PKCS #11 library is linked statically or
00059  * dynamically).
00060  *
00061  * In addition to defining these 6 macros, the packing convention
00062  * for PKCS #11 structures should be set.  The PKCS #11
00063  * convention on packing is that structures should be 1-byte
00064  * aligned.
00065  *
00066  * In a Win32 environment, this might be done by using the
00067  * following preprocessor directive before including pkcs11.h
00068  * or pkcs11t.h:
00069  *
00070  * #pragma pack(push, cryptoki, 1)
00071  *
00072  * and using the following preprocessor directive after including
00073  * pkcs11.h or pkcs11t.h:
00074  *
00075  * #pragma pack(pop, cryptoki)
00076  *
00077  * In a Win16 environment, this might be done by using the
00078  * following preprocessor directive before including pkcs11.h
00079  * or pkcs11t.h:
00080  *
00081  * #pragma pack(1)
00082  *
00083  * In a UNIX environment, you're on your own here.  You might
00084  * not need to do anything.
00085  *
00086  *
00087  * Now for the macros:
00088  *
00089  *
00090  * 1. CK_PTR: The indirection string for making a pointer to an
00091  * object.  It can be used like this:
00092  *
00093  * typedef CK_BYTE CK_PTR CK_BYTE_PTR;
00094  *
00095  * In a Win32 environment, it might be defined by
00096  *
00097  * #define CK_PTR *
00098  *
00099  * In a Win16 environment, it might be defined by
00100  *
00101  * #define CK_PTR far *
00102  *
00103  * In a UNIX environment, it might be defined by
00104  *
00105  * #define CK_PTR *
00106  *
00107  *
00108  * 2. CK_DEFINE_FUNCTION(returnType, name): A macro which makes
00109  * an exportable PKCS #11 library function definition out of a
00110  * return type and a function name.  It should be used in the
00111  * following fashion to define the exposed PKCS #11 functions in
00112  * a PKCS #11 library:
00113  *
00114  * CK_DEFINE_FUNCTION(CK_RV, C_Initialize)(
00115  *   CK_VOID_PTR pReserved
00116  * )
00117  * {
00118  *   ...
00119  * }
00120  *
00121  * For defining a function in a Win32 PKCS #11 .dll, it might be
00122  * defined by
00123  *
00124  * #define CK_DEFINE_FUNCTION(returnType, name) \
00125  *   returnType __declspec(dllexport) name
00126  *
00127  * For defining a function in a Win16 PKCS #11 .dll, it might be
00128  * defined by
00129  *
00130  * #define CK_DEFINE_FUNCTION(returnType, name) \
00131  *   returnType __export _far _pascal name
00132  *
00133  * In a UNIX environment, it might be defined by
00134  *
00135  * #define CK_DEFINE_FUNCTION(returnType, name) \
00136  *   returnType name
00137  *
00138  *
00139  * 3. CK_DECLARE_FUNCTION(returnType, name): A macro which makes
00140  * an importable PKCS #11 library function declaration out of a
00141  * return type and a function name.  It should be used in the
00142  * following fashion:
00143  *
00144  * extern CK_DECLARE_FUNCTION(CK_RV, C_Initialize)(
00145  *   CK_VOID_PTR pReserved
00146  * );
00147  *
00148  * For declaring a function in a Win32 PKCS #11 .dll, it might
00149  * be defined by
00150  *
00151  * #define CK_DECLARE_FUNCTION(returnType, name) \
00152  *   returnType __declspec(dllimport) name
00153  *
00154  * For declaring a function in a Win16 PKCS #11 .dll, it might
00155  * be defined by
00156  *
00157  * #define CK_DECLARE_FUNCTION(returnType, name) \
00158  *   returnType __export _far _pascal name
00159  *
00160  * In a UNIX environment, it might be defined by
00161  *
00162  * #define CK_DECLARE_FUNCTION(returnType, name) \
00163  *   returnType name
00164  *
00165  *
00166  * 4. CK_DECLARE_FUNCTION_POINTER(returnType, name): A macro
00167  * which makes a PKCS #11 API function pointer declaration or
00168  * function pointer type declaration out of a return type and a
00169  * function name.  It should be used in the following fashion:
00170  *
00171  * // Define funcPtr to be a pointer to a PKCS #11 API function
00172  * // taking arguments args and returning CK_RV.
00173  * CK_DECLARE_FUNCTION_POINTER(CK_RV, funcPtr)(args);
00174  *
00175  * or
00176  *
00177  * // Define funcPtrType to be the type of a pointer to a
00178  * // PKCS #11 API function taking arguments args and returning
00179  * // CK_RV, and then define funcPtr to be a variable of type
00180  * // funcPtrType.
00181  * typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, funcPtrType)(args);
00182  * funcPtrType funcPtr;
00183  *
00184  * For accessing functions in a Win32 PKCS #11 .dll, in might be
00185  * defined by
00186  *
00187  * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \
00188  *   returnType __declspec(dllimport) (* name)
00189  *
00190  * For accessing functions in a Win16 PKCS #11 .dll, it might be
00191  * defined by
00192  *
00193  * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \
00194  *   returnType __export _far _pascal (* name)
00195  *
00196  * In a UNIX environment, it might be defined by
00197  *
00198  * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \
00199  *   returnType (* name)
00200  *
00201  *
00202  * 5. CK_CALLBACK_FUNCTION(returnType, name): A macro which makes
00203  * a function pointer type for an application callback out of
00204  * a return type for the callback and a name for the callback.
00205  * It should be used in the following fashion:
00206  *
00207  * CK_CALLBACK_FUNCTION(CK_RV, myCallback)(args);
00208  *
00209  * to declare a function pointer, myCallback, to a callback
00210  * which takes arguments args and returns a CK_RV.  It can also
00211  * be used like this:
00212  *
00213  * typedef CK_CALLBACK_FUNCTION(CK_RV, myCallbackType)(args);
00214  * myCallbackType myCallback;
00215  *
00216  * In a Win32 environment, it might be defined by
00217  *
00218  * #define CK_CALLBACK_FUNCTION(returnType, name) \
00219  *   returnType (* name)
00220  *
00221  * In a Win16 environment, it might be defined by
00222  *
00223  * #define CK_CALLBACK_FUNCTION(returnType, name) \
00224  *   returnType _far _pascal (* name)
00225  *
00226  * In a UNIX environment, it might be defined by
00227  *
00228  * #define CK_CALLBACK_FUNCTION(returnType, name) \
00229  *   returnType (* name)
00230  *
00231  *
00232  * 6. NULL_PTR: This macro is the value of a NULL pointer.
00233  *
00234  * In any ANSI/ISO C environment (and in many others as well),
00235  * this should be defined by
00236  *
00237  * #ifndef NULL_PTR
00238  * #define NULL_PTR 0
00239  * #endif
00240  */
00241 
00242 
00243 /* All the various PKCS #11 types and #define'd values are in the
00244  * file pkcs11t.h. */
00245 #include "pkcs11t.h"
00246 
00247 #define __PASTE(x,y)      x##y
00248 
00249 
00250 /* packing defines */
00251 #include "pkcs11p.h"
00252 /* ==============================================================
00253  * Define the "extern" form of all the entry points.
00254  * ==============================================================
00255  */
00256 
00257 #define CK_NEED_ARG_LIST  1
00258 #define CK_PKCS11_FUNCTION_INFO(name) \
00259   CK_DECLARE_FUNCTION(CK_RV, name)
00260 
00261 /* pkcs11f.h has all the information about the PKCS #11
00262  * function prototypes. */
00263 #include "pkcs11f.h"
00264 
00265 #undef CK_NEED_ARG_LIST
00266 #undef CK_PKCS11_FUNCTION_INFO
00267 
00268 
00269 /* ==============================================================
00270  * Define the typedef form of all the entry points.  That is, for
00271  * each PKCS #11 function C_XXX, define a type CK_C_XXX which is
00272  * a pointer to that kind of function.
00273  * ==============================================================
00274  */
00275 
00276 #define CK_NEED_ARG_LIST  1
00277 #define CK_PKCS11_FUNCTION_INFO(name) \
00278   typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, __PASTE(CK_,name))
00279 
00280 /* pkcs11f.h has all the information about the PKCS #11
00281  * function prototypes. */
00282 #include "pkcs11f.h"
00283 
00284 #undef CK_NEED_ARG_LIST
00285 #undef CK_PKCS11_FUNCTION_INFO
00286 
00287 
00288 /* ==============================================================
00289  * Define structed vector of entry points.  A CK_FUNCTION_LIST
00290  * contains a CK_VERSION indicating a library's PKCS #11 version
00291  * and then a whole slew of function pointers to the routines in
00292  * the library.  This type was declared, but not defined, in
00293  * pkcs11t.h.
00294  * ==============================================================
00295  */
00296 
00297 #define CK_PKCS11_FUNCTION_INFO(name) \
00298   __PASTE(CK_,name) name;
00299   
00300 struct CK_FUNCTION_LIST {
00301 
00302   CK_VERSION    version;  /* PKCS #11 version */
00303 
00304 /* Pile all the function pointers into the CK_FUNCTION_LIST. */
00305 /* pkcs11f.h has all the information about the PKCS #11
00306  * function prototypes. */
00307 #include "pkcs11f.h" 
00308 
00309 };
00310 
00311 #undef CK_PKCS11_FUNCTION_INFO
00312 
00313 
00314 #undef __PASTE
00315 
00316 /* unpack */
00317 #include "pkcs11u.h"
00318 
00319 #ifdef __cplusplus
00320 }
00321 #endif
00322 
00323 #endif