cryptkrn.h

cryptlib是功能强大的安全工具集。允许开发人员快速在自己的软件中集成加密和认证服务。

		( createObjectInfo )->cryptOwner = CRYPT_ERROR; \
		( createObjectInfo )->arg1 = ( a1 ); \
		}

#define setMessageCreateObjectIndirectInfo( createObjectInfo, data, dataLen, type ) \
		{ \
		memset( createObjectInfo, 0, sizeof( MESSAGE_CREATEOBJECT_INFO ) ); \
		( createObjectInfo )->cryptHandle = CRYPT_ERROR; \
		( createObjectInfo )->cryptOwner = CRYPT_ERROR; \
		( createObjectInfo )->strArg1 = ( data ); \
		( createObjectInfo )->strArgLen1 = ( dataLen ); \
		( createObjectInfo )->arg1 = ( type ); \
		}

/* Key management messages, used to set, get and delete keys.  The item type,
   keyIDtype, keyID, and keyIDlength are mandatory, the aux.info depends on
   the type of message (optional password for private key get/set, state
   information for get next cert, null otherwise), and the flags are
   generally only required where the keyset can hold multiple types of keys
   (for example a crypto device acting as a keyset, or a PKCS #15 token).

   An itemType of KEYMGMT_ITEM_PUBLICKEY is somewhat more general than its
   name implies in that keysets/devices that store private key information
   alongside public-key data may delete both types of items if asked to
   delete a KEYMGMT_ITEM_PUBLICKEY since the two items are (implicitly)
   connected.

   In addition to the flags that are used to handle various special-case
   read accesses, we can also specify a usage preference (e.g.
   confidentiality vs.signature) for cases where we may have multiple keys
   with the same keyID that differ only in required usage */

typedef enum {
	KEYMGMT_ITEM_NONE,			/* No item type */
	KEYMGMT_ITEM_PUBLICKEY,		/* Access public key */
	KEYMGMT_ITEM_PRIVATEKEY,	/* Access private key */
	KEYMGMT_ITEM_SECRETKEY,		/* Access secret key */
	KEYMGMT_ITEM_REQUEST,		/* Access cert request */
	KEYMGMT_ITEM_PKIUSER,		/* Access PKI user info */
	KEYMGMT_ITEM_REVOCATIONINFO,/* Access revocation info/CRL */
	KEYMGMT_ITEM_DATA,			/* Other data (for PKCS #15 tokens) */
	KEYMGMT_ITEM_LAST			/* Last item type */
	} KEYMGMT_ITEM_TYPE;

#define KEYMGMT_FLAG_NONE			0x0000	/* No flag */
#define KEYMGMT_FLAG_CHECK_ONLY		0x0001	/* Perform existence check only */
#define KEYMGMT_FLAG_LABEL_ONLY		0x0002	/* Get key label only */
#define KEYMGMT_FLAG_UPDATE			0x0004	/* Update existing (allow dups) */
#define KEYMGMT_FLAG_DATAONLY_CERT	0x0008	/* Create data-only certs */
#define KEYMGMT_FLAG_USAGE_CRYPT	0x0010	/* Prefer encryption key */
#define KEYMGMT_FLAG_USAGE_SIGN		0x0020	/* Prefer signature key */
#define KEYMGMT_FLAG_GETISSUER		0x0040	/* Get issuing PKI user for cert */
#define KEYMGMT_FLAG_LAST			0x0080	/* Last valid flag */

#define KEYMGMT_MASK_USAGEOPTIONS	( KEYMGMT_FLAG_USAGE_CRYPT | \
									  KEYMGMT_FLAG_USAGE_SIGN )
#define KEYMGMT_MASK_CERTOPTIONS	( KEYMGMT_FLAG_DATAONLY_CERT | \
									  KEYMGMT_FLAG_USAGE_CRYPT | \
									  KEYMGMT_FLAG_USAGE_SIGN )
typedef struct {
	CRYPT_HANDLE cryptHandle;	/* Returned key */
	CRYPT_KEYID_TYPE keyIDtype;	/* Key ID type */
	const void *keyID;			/* Key ID */
	int keyIDlength;
	void *auxInfo;				/* Aux.info (e.g.password for private key) */
	int auxInfoLength;
	int flags;					/* Access options */
	} MESSAGE_KEYMGMT_INFO;

#define setMessageKeymgmtInfo( keymgmtInfo, idType, id, idLength, aux, auxLen, keyFlags ) \
		{ \
		( keymgmtInfo )->cryptHandle = CRYPT_ERROR; \
		( keymgmtInfo )->keyIDtype = ( idType ); \
		( keymgmtInfo )->keyID = ( id ); \
		( keymgmtInfo )->keyIDlength = ( idLength ); \
		( keymgmtInfo )->auxInfo = ( aux ); \
		( keymgmtInfo )->auxInfoLength = ( auxLen ); \
		( keymgmtInfo )->flags = ( keyFlags ); \
		}

/* Cert management messages used to handle CA operations.  All fields are
   mandatory, however the cryptCert and request fields may be set to
   CRYPT_UNUSED to indicate 'don't care' conditions */

typedef struct {
	CRYPT_CERTIFICATE cryptCert;	/* Returned cert */
	CRYPT_CONTEXT caKey;			/* CA key to sign item */
	CRYPT_CERTIFICATE request;		/* Request for operation */
	} MESSAGE_CERTMGMT_INFO;

#define setMessageCertMgmtInfo( certMgmtInfo, mgmtCaKey, mgmtRequest ) \
		{ \
		( certMgmtInfo )->cryptCert = CRYPT_ERROR; \
		( certMgmtInfo )->caKey = ( mgmtCaKey ); \
		( certMgmtInfo )->request = ( mgmtRequest ); \
		}

/****************************************************************************
*																			*
*								Kernel Functions							*
*																			*
****************************************************************************/

/* cryptlib initialistion/shutdown functions */

int initCryptlib( void );
int endCryptlib( void );
#if defined( __PALMOS__ ) || defined( __WIN32__ ) || defined( __WINCE__ )
  void preInit( void );
  void postShutdown( void );
#endif /* Systems with OS-specific pre-init/post-shutdown facilities */

/* Prototype for an object's message-handling function */

typedef int ( *MESSAGE_FUNCTION )( const void *objectInfoPtr,
								   const MESSAGE_TYPE message,
								   void *messageDataPtr,
								   const int messageValue );

/* Object management functions.  A dummy object is one that exists but
   doesn't have the capabilities of the actual object, for example an
   encryption context that just maps to underlying crypto hardware.  This
   doesn't affect krnlCreateObject(), but is used by the object-type-specific
   routines that decorate the results of krnlCreateObject() with object-
   specific extras */

#define CREATEOBJECT_FLAG_NONE		0x00	/* No create-object flags */
#define CREATEOBJECT_FLAG_SECUREMALLOC \
									0x01	/* Use krnlMemAlloc() to alloc.*/
#define CREATEOBJECT_FLAG_DUMMY		0x02	/* Dummy obj.used as placeholder */

int krnlCreateObject( void **objectDataPtr, const int objectDataSize,
					  const OBJECT_TYPE type, const int subType,
					  const int createObjectFlags, const CRYPT_USER owner,
					  const int actionFlags,
					  MESSAGE_FUNCTION messageFunction );
int krnlSendMessage( const int objectHandle, const MESSAGE_TYPE message,
					 void *messageDataPtr, const int messageValue );

/* Since some messages contain no data but act only as notifiers, we define
   the following macro to make using them less messy */

#define krnlSendNotifier( handle, message ) \
		krnlSendMessage( handle, message, NULL, 0 )

/* In some rare cases we have to access an object directly without sending
   it a message.  This happens either with certs where we're already
   processing a message for one cert and need to access internal data in
   another cert, when we're working with a crypto device tied to a context
   where we need access to both context and device internals at the same
   time, or when we're updating config data in a user object.  This type of
   access is handled by the following function, which also explicitly
   disallows any access types apart from the three described here */

int krnlAcquireObject( const int objectHandle, const OBJECT_TYPE type,
					   void **objectPtr, const int errorCode );
int krnlReleaseObject( const int objectHandle );

/* In even rarer cases, we have to allow a second thread access to an object
   when another thread has it locked.  This only occurs in one case, when a
   background polling thread is adding entropy to the system device.  The way
   this works is that the calling thread hands ownership over to the polling
   thread and suspends itself until the polling thread completes.  When the
   polling thread has completed, it terminates, whereupon ownership passes
   back to the original thread.  The value passed to the release call is
   actually a thread ID, but since this isn't visible outside the kernel we
   just us a generic int */

int krnlRelinquishSystemObject( const int /*THREAD_HANDLE*/ objectOwnerThread );
int krnlReacquireSystemObject( void );

/* When the kernel is closing down, any cryptlib-internal threads should exit
   as quickly as possible.  For threads coming in from the outside this 
   happens automatically because any message it tries to send fails, but for
   internal worker threads (for example the async driver-binding thread or
   randomness polling threads) that don't perform many kernel calls, the 
   thread has to periodically check whether the kernel is still active.  The
   following function is used to indicate whether the kernel is shutting
   down */

BOOLEAN krnlIsExiting( void );

/* Semaphores and mutexes */

typedef enum {
	SEMAPHORE_NONE,					/* No semaphore */
	SEMAPHORE_DRIVERBIND,			/* Async driver bind */
	SEMAPHORE_LAST					/* Last semaphore */
	} SEMAPHORE_TYPE;

typedef enum {
	MUTEX_NONE,						/* No mutex */
	MUTEX_SESSIONCACHE,				/* SSL/TLS session cache */
	MUTEX_SOCKETPOOL,				/* Network socket pool */
	MUTEX_LAST						/* Last mutex */
	} MUTEX_TYPE;

/* Execute a function in a background thread.  This takes a pointer to the
   function to execute in the background thread, a set of parameters to pass
   to the function, and an optional semaphore ID to set once the thread is
   started.  A function is run via a background thread as follows:

	void threadFunction( const THREAD_FUNCTION_PARAMS *threadParams )
		{
		}

	initThreadParams( &threadParams, ptrParam, intParam );
	krnlDispatchThread( threadFunction, &threadParams, SEMAPHORE_ID );

   Note that the parameters must be held in static storage because the
   caller's stack frame may have long since disappeared before the thread
   gets to access them.  To emphasise this, we define the storage specifier
   STATIC_THREADPARAM_STORAGE for when we declare the variables */

struct TF;

typedef void ( *THREAD_FUNCTION )( const struct TF *threadParams );

typedef struct TF {
	THREAD_FUNCTION threadFunction;	/* Function to call from thread */
	void *ptrParam;					/* Thread function parameters */
	int intParam;
	SEMAPHORE_TYPE semaphore;		/* Optional semaphore to set */
	long syncHandle;				/* Handle to use for thread sync */
	} THREAD_FUNCTION_PARAMS;

#define STATIC_THREADPARAM_STORAGE	static

#define initThreadParams( threadParams, pParam, iParam ) \
		memset( ( threadParams ), 0, sizeof( THREAD_FUNCTION_PARAMS ) ); \
		( threadParams )->ptrParam = ( void * )( pParam ); \
		( threadParams )->intParam = ( iParam );

int krnlDispatchThread( THREAD_FUNCTION threadFunction,
						THREAD_FUNCTION_PARAMS *threadParams,
						const SEMAPHORE_TYPE semaphore );

/* Wait on a semaphore, enter and exit a mutex */

BOOLEAN krnlWaitSemaphore( const SEMAPHORE_TYPE semaphore );
void krnlEnterMutex( const MUTEX_TYPE mutex );
void krnlExitMutex( const MUTEX_TYPE mutex );

/* Secure memory handling functions */

int krnlMemalloc( void **pointer, int size );
void krnlMemfree( void **pointer );
int krnlMemsize( const void *pointer );

#ifdef NEED_ENUMFIX
  #undef OBJECT_TYPE_LAST
  #undef MESSAGE_COMPARE_LAST
  #undef MESSAGE_CHECK_LAST
  #undef MESSAGE_CHANGENOTIFY_LAST
  #undef MECHANISM_LAST
  #undef KEYMGMT_ITEM_LAST
  #undef SEMAPHORE_LAST
  #undef MUTEX_LAST
#endif /* NEED_ENUMFIX */
#endif /* _CRYPTKRN_DEFINED */