cryptkrn.h

cryptlib安全工具包

		}

#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_FLAG_MAX			0x008F	/* Maximum possible flag value */

#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 */
	BUFFER_OPT_FIXED( keyIDlength ) \
	const void *keyID;			/* Key ID */
	int keyIDlength;
	BUFFER_OPT_FIXED( auxInfoLength ) \
	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 )( INOUT void *objectInfoPtr,
								   const MESSAGE_TYPE message,
								   void *messageDataPtr,
								   const int messageValue ) \
								   STDC_NONNULL_ARG( ( 1 ) );

/* If the message-handler can unlock an object to allow other threads 
   access, it has to be able to inform the kernel of this.  The following
   structure and macros allow this information to be passed back to the
   kernel via the message function's objectInfoPtr */

typedef struct {
	void *objectInfoPtr;					/* Original objectInfoPtr */
	BOOLEAN isUnlocked;						/* Whether obj.is now unlocked */
	} MESSAGE_FUNCTION_EXTINFO;

#define initMessageExtInfo( messageExtInfo, objectInfo ) \
		{ \
		memset( messageExtInfo, 0, sizeof( MESSAGE_FUNCTION_EXTINFO ) ); \
		( messageExtInfo )->objectInfoPtr = objectInfo; \
		}
#define setMessageObjectLocked( messageExtInfo ) \
		( messageExtInfo )->isUnlocked = FALSE
#define setMessageObjectUnlocked( messageExtInfo ) \
		( messageExtInfo )->isUnlocked = TRUE
#define isMessageObjectUnlocked( messageExtInfo ) \
		( ( messageExtInfo )->isUnlocked )

/* 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 */
#define CREATEOBJECT_FLAG_PERSISTENT 0x04	/* Obj.backed by key in device */
#define CREATEOBJECT_FLAG_MAX		0x0F	/* Maximum possible flag value */

CHECK_RETVAL \
int krnlCreateObject( OUT_HANDLE_OPT int *objectHandle,
					  OUT_PTR void **objectDataPtr, const int objectDataSize,
					  const OBJECT_TYPE type, const OBJECT_SUBTYPE subType,
					  const int createObjectFlags, const CRYPT_USER owner,
					  const int actionFlags,
					  CALLBACK_FUNCTION MESSAGE_FUNCTION messageFunction ) \
					  STDC_NONNULL_ARG( ( 1, 2, 9 ) );
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 */

CHECK_RETVAL \
int krnlAcquireObject( const int objectHandle, const OBJECT_TYPE type,
					   OUT_PTR void **objectPtr, const int errorCode ) \
					   STDC_NONNULL_ARG( ( 3 ) );
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, providing a (somewhat crude) mechanism
   for making kernel calls interruptible and resumable.  This only occurs in
   two cases, for the system object when a background polling thread is
   adding entropy to the system device and for the user object when we're
   saving configuration data to persistent storage (we temporarily unlock it
   to allow other threads access, since the act of writing the marshalled
   data to storage doesn't require the user object) */

int krnlSuspendObject( const int objectHandle, OUT int *refCount ) \
					   STDC_NONNULL_ARG( ( 2 ) );
CHECK_RETVAL \
int krnlResumeObject( const int objectHandle, const int refCount );

/* 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 */

CHECK_RETVAL \
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_SCOREBOARD,				/* Session scoreboard */
	MUTEX_SOCKETPOOL,				/* Network socket pool */
	MUTEX_RANDOM,					/* Randomness subsystem */
	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 block of memory for 
   thread state storage, a set of parameters to pass to the thread 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_PARAMS *threadParams )
		{
		}

	krnlDispatchThread( threadFunction, &threadState, ptrParam, intParam, 
						SEMAPHORE_ID );

   Note that the thread 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 */

struct TF;

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

typedef BYTE THREAD_STATE[ 48 ];

typedef struct TF {
	void *ptrParam;					/* Pointer parameter */
	int intParam;					/* Integer parameter */
	} THREAD_PARAMS;

CHECK_RETVAL \
int krnlDispatchThread( THREAD_FUNCTION threadFunction,
						THREAD_STATE threadState, void *ptrParam, 
						const int intParam, const SEMAPHORE_TYPE semaphore ) \
						STDC_NONNULL_ARG( ( 1 ) );

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

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

/* Secure memory handling functions */

CHECK_RETVAL \
int krnlMemalloc( OUT_PTR void **pointer, int size ) \
				  STDC_NONNULL_ARG( ( 1 ) );
void krnlMemfree( OUT_PTR void **pointer ) \
				  STDC_NONNULL_ARG( ( 1 ) );

#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 */