michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: /*
michael@0:  * Copyright (C) 1994-1999 RSA Security Inc. Licence to copy this document
michael@0:  * is granted provided that it is identified as "RSA Security In.c Public-Key
michael@0:  * Cryptography Standards (PKCS)" in all material mentioning or referencing
michael@0:  * this document.
michael@0:  *
michael@0:  * The latest version of this header can be found at:
michael@0:  *    http://www.rsalabs.com/pkcs/pkcs-11/index.html
michael@0:  */
michael@0: #ifndef _PKCS11_H_
michael@0: #define _PKCS11_H_ 1
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: extern "C" {
michael@0: #endif
michael@0: 
michael@0: /* Before including this file (pkcs11.h) (or pkcs11t.h by
michael@0:  * itself), 6 platform-specific macros must be defined.  These
michael@0:  * macros are described below, and typical definitions for them
michael@0:  * are also given.  Be advised that these definitions can depend
michael@0:  * on both the platform and the compiler used (and possibly also
michael@0:  * on whether a PKCS #11 library is linked statically or
michael@0:  * dynamically).
michael@0:  *
michael@0:  * In addition to defining these 6 macros, the packing convention
michael@0:  * for PKCS #11 structures should be set.  The PKCS #11
michael@0:  * convention on packing is that structures should be 1-byte
michael@0:  * aligned.
michael@0:  *
michael@0:  * In a Win32 environment, this might be done by using the
michael@0:  * following preprocessor directive before including pkcs11.h
michael@0:  * or pkcs11t.h:
michael@0:  *
michael@0:  * #pragma pack(push, cryptoki, 1)
michael@0:  *
michael@0:  * and using the following preprocessor directive after including
michael@0:  * pkcs11.h or pkcs11t.h:
michael@0:  *
michael@0:  * #pragma pack(pop, cryptoki)
michael@0:  *
michael@0:  * In a UNIX environment, you're on your own here.  You might
michael@0:  * not need to do anything.
michael@0:  *
michael@0:  *
michael@0:  * Now for the macros:
michael@0:  *
michael@0:  *
michael@0:  * 1. CK_PTR: The indirection string for making a pointer to an
michael@0:  * object.  It can be used like this:
michael@0:  *
michael@0:  * typedef CK_BYTE CK_PTR CK_BYTE_PTR;
michael@0:  *
michael@0:  * In a Win32 environment, it might be defined by
michael@0:  *
michael@0:  * #define CK_PTR *
michael@0:  *
michael@0:  * In a UNIX environment, it might be defined by
michael@0:  *
michael@0:  * #define CK_PTR *
michael@0:  *
michael@0:  *
michael@0:  * 2. CK_DEFINE_FUNCTION(returnType, name): A macro which makes
michael@0:  * an exportable PKCS #11 library function definition out of a
michael@0:  * return type and a function name.  It should be used in the
michael@0:  * following fashion to define the exposed PKCS #11 functions in
michael@0:  * a PKCS #11 library:
michael@0:  *
michael@0:  * CK_DEFINE_FUNCTION(CK_RV, C_Initialize)(
michael@0:  *   CK_VOID_PTR pReserved
michael@0:  * )
michael@0:  * {
michael@0:  *   ...
michael@0:  * }
michael@0:  *
michael@0:  * For defining a function in a Win32 PKCS #11 .dll, it might be
michael@0:  * defined by
michael@0:  *
michael@0:  * #define CK_DEFINE_FUNCTION(returnType, name) \
michael@0:  *   returnType __declspec(dllexport) name
michael@0:  *
michael@0:  * In a UNIX environment, it might be defined by
michael@0:  *
michael@0:  * #define CK_DEFINE_FUNCTION(returnType, name) \
michael@0:  *   returnType name
michael@0:  *
michael@0:  *
michael@0:  * 3. CK_DECLARE_FUNCTION(returnType, name): A macro which makes
michael@0:  * an importable PKCS #11 library function declaration out of a
michael@0:  * return type and a function name.  It should be used in the
michael@0:  * following fashion:
michael@0:  *
michael@0:  * extern CK_DECLARE_FUNCTION(CK_RV, C_Initialize)(
michael@0:  *   CK_VOID_PTR pReserved
michael@0:  * );
michael@0:  *
michael@0:  * For declaring a function in a Win32 PKCS #11 .dll, it might
michael@0:  * be defined by
michael@0:  *
michael@0:  * #define CK_DECLARE_FUNCTION(returnType, name) \
michael@0:  *   returnType __declspec(dllimport) name
michael@0:  *
michael@0:  * In a UNIX environment, it might be defined by
michael@0:  *
michael@0:  * #define CK_DECLARE_FUNCTION(returnType, name) \
michael@0:  *   returnType name
michael@0:  *
michael@0:  *
michael@0:  * 4. CK_DECLARE_FUNCTION_POINTER(returnType, name): A macro
michael@0:  * which makes a PKCS #11 API function pointer declaration or
michael@0:  * function pointer type declaration out of a return type and a
michael@0:  * function name.  It should be used in the following fashion:
michael@0:  *
michael@0:  * // Define funcPtr to be a pointer to a PKCS #11 API function
michael@0:  * // taking arguments args and returning CK_RV.
michael@0:  * CK_DECLARE_FUNCTION_POINTER(CK_RV, funcPtr)(args);
michael@0:  *
michael@0:  * or
michael@0:  *
michael@0:  * // Define funcPtrType to be the type of a pointer to a
michael@0:  * // PKCS #11 API function taking arguments args and returning
michael@0:  * // CK_RV, and then define funcPtr to be a variable of type
michael@0:  * // funcPtrType.
michael@0:  * typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, funcPtrType)(args);
michael@0:  * funcPtrType funcPtr;
michael@0:  *
michael@0:  * For accessing functions in a Win32 PKCS #11 .dll, in might be
michael@0:  * defined by
michael@0:  *
michael@0:  * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \
michael@0:  *   returnType __declspec(dllimport) (* name)
michael@0:  *
michael@0:  * In a UNIX environment, it might be defined by
michael@0:  *
michael@0:  * #define CK_DECLARE_FUNCTION_POINTER(returnType, name) \
michael@0:  *   returnType (* name)
michael@0:  *
michael@0:  *
michael@0:  * 5. CK_CALLBACK_FUNCTION(returnType, name): A macro which makes
michael@0:  * a function pointer type for an application callback out of
michael@0:  * a return type for the callback and a name for the callback.
michael@0:  * It should be used in the following fashion:
michael@0:  *
michael@0:  * CK_CALLBACK_FUNCTION(CK_RV, myCallback)(args);
michael@0:  *
michael@0:  * to declare a function pointer, myCallback, to a callback
michael@0:  * which takes arguments args and returns a CK_RV.  It can also
michael@0:  * be used like this:
michael@0:  *
michael@0:  * typedef CK_CALLBACK_FUNCTION(CK_RV, myCallbackType)(args);
michael@0:  * myCallbackType myCallback;
michael@0:  *
michael@0:  * In a Win32 environment, it might be defined by
michael@0:  *
michael@0:  * #define CK_CALLBACK_FUNCTION(returnType, name) \
michael@0:  *   returnType (* name)
michael@0:  *
michael@0:  * In a UNIX environment, it might be defined by
michael@0:  *
michael@0:  * #define CK_CALLBACK_FUNCTION(returnType, name) \
michael@0:  *   returnType (* name)
michael@0:  *
michael@0:  *
michael@0:  * 6. NULL_PTR: This macro is the value of a NULL pointer.
michael@0:  *
michael@0:  * In any ANSI/ISO C environment (and in many others as well),
michael@0:  * this should be defined by
michael@0:  *
michael@0:  * #ifndef NULL_PTR
michael@0:  * #define NULL_PTR 0
michael@0:  * #endif
michael@0:  */
michael@0: 
michael@0: 
michael@0: /* All the various PKCS #11 types and #define'd values are in the
michael@0:  * file pkcs11t.h. */
michael@0: #include "pkcs11t.h"
michael@0: 
michael@0: #define __PASTE(x,y)      x##y
michael@0: 
michael@0: 
michael@0: /* packing defines */
michael@0: #include "pkcs11p.h"
michael@0: /* ==============================================================
michael@0:  * Define the "extern" form of all the entry points.
michael@0:  * ==============================================================
michael@0:  */
michael@0: 
michael@0: #define CK_NEED_ARG_LIST  1
michael@0: #define CK_PKCS11_FUNCTION_INFO(name) \
michael@0:   CK_DECLARE_FUNCTION(CK_RV, name)
michael@0: 
michael@0: /* pkcs11f.h has all the information about the PKCS #11
michael@0:  * function prototypes. */
michael@0: #include "pkcs11f.h"
michael@0: 
michael@0: #undef CK_NEED_ARG_LIST
michael@0: #undef CK_PKCS11_FUNCTION_INFO
michael@0: 
michael@0: 
michael@0: /* ==============================================================
michael@0:  * Define the typedef form of all the entry points.  That is, for
michael@0:  * each PKCS #11 function C_XXX, define a type CK_C_XXX which is
michael@0:  * a pointer to that kind of function.
michael@0:  * ==============================================================
michael@0:  */
michael@0: 
michael@0: #define CK_NEED_ARG_LIST  1
michael@0: #define CK_PKCS11_FUNCTION_INFO(name) \
michael@0:   typedef CK_DECLARE_FUNCTION_POINTER(CK_RV, __PASTE(CK_,name))
michael@0: 
michael@0: /* pkcs11f.h has all the information about the PKCS #11
michael@0:  * function prototypes. */
michael@0: #include "pkcs11f.h"
michael@0: 
michael@0: #undef CK_NEED_ARG_LIST
michael@0: #undef CK_PKCS11_FUNCTION_INFO
michael@0: 
michael@0: 
michael@0: /* ==============================================================
michael@0:  * Define structed vector of entry points.  A CK_FUNCTION_LIST
michael@0:  * contains a CK_VERSION indicating a library's PKCS #11 version
michael@0:  * and then a whole slew of function pointers to the routines in
michael@0:  * the library.  This type was declared, but not defined, in
michael@0:  * pkcs11t.h.
michael@0:  * ==============================================================
michael@0:  */
michael@0: 
michael@0: #define CK_PKCS11_FUNCTION_INFO(name) \
michael@0:   __PASTE(CK_,name) name;
michael@0:   
michael@0: struct CK_FUNCTION_LIST {
michael@0: 
michael@0:   CK_VERSION    version;  /* PKCS #11 version */
michael@0: 
michael@0: /* Pile all the function pointers into the CK_FUNCTION_LIST. */
michael@0: /* pkcs11f.h has all the information about the PKCS #11
michael@0:  * function prototypes. */
michael@0: #include "pkcs11f.h" 
michael@0: 
michael@0: };
michael@0: 
michael@0: #undef CK_PKCS11_FUNCTION_INFO
michael@0: 
michael@0: 
michael@0: #undef __PASTE
michael@0: 
michael@0: /* unpack */
michael@0: #include "pkcs11u.h"
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: }
michael@0: #endif
michael@0: 
michael@0: #endif