envelope.h

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

/****************************************************************************
*																			*
*						 Enveloping Routines Header File					*
*						Copyright Peter Gutmann 1996-2004					*
*																			*
****************************************************************************/

#ifndef _ENV_DEFINED

#define _ENV_DEFINED

#ifndef _STREAM_DEFINED
  #if defined( INC_ALL )
	#include "stream.h"
  #elif defined INC_CHILD
	#include "../io/stream.h"
  #else
	#include "io/stream.h"
  #endif /* Compiler-specific includes */
#endif /* _STREAM_DEFINED */
#ifdef USE_COMPRESSION
  #if defined( INC_ALL )
	#include "zlib.h"
  #elif defined( INC_CHILD )
	#include "../zlib/zlib.h"
  #else
	#include "zlib/zlib.h"
  #endif /* Compiler-specific includes */
#endif /* USE_COMPRESSION */

/****************************************************************************
*																			*
*								Envelope Actions							*
*																			*
****************************************************************************/

/* Types of actions that can be performed on a piece of envelope data.  The 
   two key exchange actions are handled identically, but are given different 
   tags because we place PKC-based key exchange actions (which may be 
   handled automatically on de-enveloping) before conventional key exchange 
   actions (which usually require manual intervention for passphrases).  For 
   this reason the actions are given in their sort order (i.e. 
   ACTION_KEYEXCHANGE_PKC precedes ACTION_KEYEXCHANGE in the action list) */

typedef enum {
	ACTION_NONE,					/* Non-action */

	/* Pre-actions */
	ACTION_KEYEXCHANGE_PKC,			/* Generate/read PKC exchange information */
	ACTION_KEYEXCHANGE,				/* Generate/read key exchange information */

	/* Actions */
	ACTION_COMPRESS,				/* Compress */
	ACTION_HASH,					/* Hash */
	ACTION_MAC,						/* MAC */
	ACTION_CRYPT,					/* En/decrypt */

	/* Post-actions */
	ACTION_SIGN,					/* Generate/check signature */

	ACTION_LAST						/* Last valid action type */
	} ACTION_TYPE;

/* An 'action list' that defines what we need to do to the content when
   enveloping data.  There are three action lists, one for actions to perform
   before enveloping data, one to perform during enveloping (which is 
   actually just a single action rather than a list), and one to perform 
   after enveloping.  ACTION_KEYEXCHANGE and ACTION_KEYEXCHANGE_PKC are found 
   in the pre-enveloping list, ACTION_SIGN in the post-enveloping list, and 
   everything else in the during-enveloping list.

   Some actions are many-to-one, in which a number of controlling actions in
   one list may act on a single subject action in another list (for example a
   number of signature actions may sign the output from a single hash
   action).  This is handled by having the controlling actions maintain
   pointers to the subject action, for example a number of key export actions
   would point to one encryption action, with the export actions exporting
   the session key for the encryption action.

   The ACTION_NEEDSCONTROLLER flag records whether this is a subject action 
   that still requires a controlling action.  This allows us to identify 
   unused subject actions more easily than by scanning all controller->
   subject relationships.

   The ACTION_ADDEDAUTOMATICALLY flag records whether a subject action was 
   added automatically and invisibly to the caller as a result of adding a 
   controlling action, for example a hash action created when a signing 
   action is added.  This is to ensure that we don't return an error the 
   first time the caller adds an action which is identical to an 
   automatically added action */

#define ACTION_NEEDSCONTROLLER	0x01	/* Whether action reqs.controller */
#define ACTION_ADDEDAUTOMATICALLY 0x02	/* Whether action added automat.*/

typedef struct AI {
	/* Control and status information */
	ACTION_TYPE action;				/* Type of action to perform */
	int flags;						/* Action flags */
	struct AI *next;				/* Next item in the list */

	/* The controlling/subject action.  This points to the subject action 
	   associated with a controlling action if this is a controlling 
	   action */
	struct AI *associatedAction;	/* Associated action */

	/* Information related to the action.  These fields contain various
	   pieces of information required as part of the action.  The crypt
	   handle contains the encryption context needed to perform the action 
	   (e.g. encryption, hashing, signing).  If we're generating CMS 
	   signatures, there may be extra attribute data present which is 
	   included in the signature, and we may also have countersignature 
	   information present, typically a timestamping session object */
	CRYPT_CONTEXT iCryptHandle;		/* Encryption handle for action */
	CRYPT_CERTIFICATE iExtraData;	/* Extra attribute data for CMS sigs.*/
	CRYPT_SESSION iTspSession;		/* Timestamping session object */
	int encodedSize;				/* The encoded size of the action */
	} ACTION_LIST;

/* Result codes for the checkAction() function when adding an action to
   an action list.  The two 'action present' results are for the case where 
   the action is already present and shouldn't be added again, and where the 
   action is present from being added as an (invisible to the user) side-
   effect of another action being added, so that this attempt to add it 
   should be reported as CRYPT_OK rather than CRYPT_INITED */

typedef enum {
	ACTION_RESULT_OK,				/* Action not present, can be added */
	ACTION_RESULT_EMPTY,			/* Action list is empty */
	ACTION_RESULT_INITED,			/* Action present (CRYPT_ERROR_INITED) */
	ACTION_RESULT_PRESENT,			/* Action present (CRYPT_OK) */
	ACTION_RESULT_ERROR,			/* Arg.error (CRYPT_ARGERROR_NUM1) */
	ACTION_RESULT_LAST				/* Last valid action result type */
	} ACTION_RESULT;

/* Content information flags.  These are:

	CONTENTLIST_ISSIGOBJ: The contentInfo union contains information from a 
			signature object, otherwise it contains data from an encryption
			object.

	CONTENTLIST_PROCESSED: The signature object has been processed by having
			the signature verified (or at least attempted to be verified).
			The verification result is stored/cached with the content info 
			for later use.

	CONTENTLIST_EXTERNALKEY: The signature-check key was supplied by the user
			rather than being instantiated internally from certificates
			associated with the signature */

#define CONTENTLIST_ISSIGOBJ	0x01	/* Item is signature object */
#define CONTENTLIST_PROCESSED	0x02	/* Whether object has been processed */
#define CONTENTLIST_EXTERNALKEY	0x04	/* Whether key was added externally */

/* A 'content list' which is used to store objects found in the non-data
   portion of the envelope until we can do something with them when de-
   enveloping data.  If the envelope contains encrypted data this list
   contains the key exchange information until we get a key exchange key to
   recover the session key.  If the envelope contains signed data this list
   contains the signature(s) until we get signature keys to check them.  The
   same list is used for two purposes at different times */

#define clEncrInfo	contentInfo.contentEncrInfo
#define clSigInfo	contentInfo.contentSigInfo

typedef struct {
	/* Signature algorithm/key information */
	CRYPT_ALGO_TYPE hashAlgo;		/* Hash algo.for signed data */
	CRYPT_HANDLE iSigCheckKey;		/* Signature check key */

	/* Authenticated/unauthenticated attribute information */
	CRYPT_CERTIFICATE iExtraData;	/* Authent.attrib.in CMS signatures */
	void *extraData;				/* Authent.attrib.in PGP signatures */
	int extraDataLength;
	CRYPT_ENVELOPE iTimestamp;		/* Unauth.attrib.in CMS signatures */
	void *extraData2;				/* Unauthenticated attributes */
	int extraData2Length;

	/* We only need to process a signed object once, once we've done this we 
	   store the processing result so that any further attempts to process 
	   the object will return the previously obtained result (an object can 
	   be processed multiple times if the user wanders up and down the 
	   content list using the cursor management capabilities) */
	int processingResult;			/* Result of processing */
	
	/* To allow positioning of the cursor within this item (== attribute 
	   group), we have to keep track of the virtual position within the
	   group.  The virtual attribute order is result -> key -> auth.
	   attr -> timestamp */
	CRYPT_ATTRIBUTE_TYPE attributeCursorEntry;
	} CONTENT_SIG_INFO;

typedef struct {
	/* Encryption algorithm/key information */
	CRYPT_ALGO_TYPE cryptAlgo;		/* Encryption algo.for this object */
	CRYPT_MODE_TYPE cryptMode;		/* Encrytion mode for this object */

	/* Encryption key setup information */
	BYTE saltOrIV[ CRYPT_MAX_HASHSIZE ];/* Salt for password-derived key or */
	int saltOrIVsize;				/*	   IV for session encr.context */
	CRYPT_ALGO_TYPE keySetupAlgo;	/* Hash algo.for pw-derived key */
	int keySetupIterations;			/* Iterations for pw-derived key */
	} CONTENT_ENCR_INFO;	

typedef struct CL {
	/* Control and status information */
	CRYPT_ATTRIBUTE_TYPE envInfo;	/* Env.info required to continue */
	CRYPT_FORMAT_TYPE formatType;	/* Data format */
	int flags;						/* Item flags */
	struct CL *prev, *next;			/* Prev, next items in the list */

	/* The object contained in this list element.  All object type-specific
	   pointers in the xxxInfo data point into fields inside this data */
	void *object;					/* The object data */
	int objectSize;					/* Size of the object */

	/* Details on the object.  Here we store whatever is required to process
	   the object without having to call queryXXXObject() for the details */
	BYTE keyID[ CRYPT_MAX_HASHSIZE ];/* cryptlib key ID */
	int keyIDsize;
	void *issuerAndSerialNumber;	/* CMS key ID */
	int issuerAndSerialNumberSize;
	void *payload;					/* Payload data (e.g. encr.key) */
	int payloadSize;
	union {
		CONTENT_ENCR_INFO contentEncrInfo;	/* Encryption obj-specific infor.*/
		CONTENT_SIG_INFO contentSigInfo;	/* Signature obj-specific info.*/
		} contentInfo;
	} CONTENT_LIST;

/****************************************************************************
*																			*
*								De-envelope Actions							*
*																			*
****************************************************************************/

/* The current state of the (de)enveloping.  The states are the predata state
   (when we're performing final setup steps and handling header information
   in the envelope), the data state (when we're enveloping data), the
   postdata state (when we're handling trailer information), and the
   extradata state (when we're processing out-of-band data such as the data
   associated with detached signatures) */

typedef enum {
	STATE_PREDATA,					/* Emitting header information */
	STATE_DATA,						/* During (de)enveloping of data */
	STATE_POSTDATA,					/* After (de)enveloping of data */
	STATE_EXTRADATA,				/* Additional out-of-band data */
	STATE_FINISHED,					/* Finished processing */
	STATE_LAST						/* Last valid enveloping state */
	} ENVELOPE_STATE;

/* The current state of the processing of CMS headers that contain non-data
   during the enveloping process.  Before the enveloping of data begins, the