pgpkeys.h

PGP8.0源码 请认真阅读您的文件包然后写出其具体功能

/*____________________________________________________________________________
	Copyright (C) 2002 PGP Corporation
	All rights reserved.
	
	$Id: pgpKeys.h,v 1.57 2002/08/06 20:11:16 dallen Exp $
____________________________________________________________________________*/

#ifndef Included_pgpKeys_h	/* [ */
#define Included_pgpKeys_h

#include "pgpPubTypes.h"
#include "pgpHash.h"
#include "pgpOptionList.h"

/* Key ordering */

enum PGPKeyOrdering_
{
	kPGPKeyOrdering_Invalid				= 0,
	kPGPKeyOrdering_Any					= 1,
	kPGPKeyOrdering_UserID				= 2,
	kPGPKeyOrdering_KeyID				= 3,
	kPGPKeyOrdering_Validity			= 4,
	kPGPKeyOrdering_Trust				= 5,
	kPGPKeyOrdering_EncryptionKeySize	= 6,
	kPGPKeyOrdering_SigningKeySize		= 7,
	kPGPKeyOrdering_CreationDate		= 8,
	kPGPKeyOrdering_ExpirationDate		= 9,
	
	PGP_ENUM_FORCE( PGPKeyOrdering_ )
} ;
PGPENUM_TYPEDEF( PGPKeyOrdering_, PGPKeyOrdering );


/* Key properties */

enum PGPKeyDBObjProperty_
{
	kPGPKeyDBObjProperty_Invalid 				= 0,
	
	/* Generic numeric properties */
	kPGPKeyDBObjProperty_ObjectType				= 20,
	
	/* Key boolean properties */	
	kPGPKeyProperty_IsSecret 					= 100,
	kPGPKeyProperty_IsAxiomatic					= 101,
	kPGPKeyProperty_IsRevoked					= 102,
	kPGPKeyProperty_IsDisabled					= 103,
	kPGPKeyProperty_IsNotCorrupt				= 104,
	kPGPKeyProperty_IsExpired					= 105,
	kPGPKeyProperty_NeedsPassphrase				= 106,
	kPGPKeyProperty_HasUnverifiedRevocation		= 107,
	kPGPKeyProperty_CanEncrypt					= 108,
	kPGPKeyProperty_CanDecrypt					= 109,
	kPGPKeyProperty_CanSign						= 110,
	kPGPKeyProperty_CanVerify					= 111,
	kPGPKeyProperty_IsEncryptionKey				= 112,
	kPGPKeyProperty_IsSigningKey				= 113,
	kPGPKeyProperty_IsSecretShared				= 114,
	kPGPKeyProperty_IsRevocable					= 115,
	kPGPKeyProperty_HasThirdPartyRevocation		= 116,
	kPGPKeyProperty_HasCRL						= 117,
	kPGPKeyProperty_IsOnToken					= 118,

	/* Key numeric properties */	
	kPGPKeyProperty_AlgorithmID 				= 200,
	kPGPKeyProperty_Bits						= 201,	
	kPGPKeyProperty_Trust						= 202,
	kPGPKeyProperty_Validity					= 203,
	kPGPKeyProperty_LockingAlgorithmID			= 204,
	kPGPKeyProperty_LockingBits					= 205,
	kPGPKeyProperty_Flags						= 206,
	kPGPKeyProperty_HashAlgorithmID				= 207,
	kPGPKeyProperty_Version						= 208,
	kPGPKeyProperty_KeyServerPreferences		= 209,
	kPGPKeyProperty_TokenNum					= 210, 

	/* Key time properties */	
	kPGPKeyProperty_Creation 					= 300,
	kPGPKeyProperty_Expiration					= 301,
	kPGPKeyProperty_CRLThisUpdate				= 302,
	kPGPKeyProperty_CRLNextUpdate				= 303,

	/* Key data (variable sized) properties */
	kPGPKeyProperty_Fingerprint					= 401,
	kPGPKeyProperty_KeyID						= 402,
	kPGPKeyProperty_PreferredAlgorithms			= 403,
	kPGPKeyProperty_ThirdPartyRevocationKeyID 	= 404,
	kPGPKeyProperty_KeyData						= 405,
	kPGPKeyProperty_X509MD5Hash					= 406,
	kPGPKeyProperty_PreferredKeyServer			= 407,
	
	/* SubKey boolean properties */	
	kPGPSubKeyProperty_IsRevoked				= 501,
	kPGPSubKeyProperty_IsNotCorrupt				= 502,
	kPGPSubKeyProperty_IsExpired				= 503,
	kPGPSubKeyProperty_NeedsPassphrase			= 504,
	kPGPSubKeyProperty_HasUnverifiedRevocation	= 505,
	kPGPSubKeyProperty_IsRevocable				= 506,
	kPGPSubKeyProperty_HasThirdPartyRevocation	= 507,
	kPGPSubKeyProperty_IsOnToken				= 508,

	/* SubKey numeric properties */
	kPGPSubKeyProperty_AlgorithmID 				= 600,
	kPGPSubKeyProperty_Bits						= 601,	
	kPGPSubKeyProperty_LockingAlgorithmID		= 602,
	kPGPSubKeyProperty_LockingBits				= 603,
	kPGPSubKeyProperty_Version					= 604,
	kPGPSubKeyProperty_Flags					= 605,

	/* SubKey time properties */	
	kPGPSubKeyProperty_Creation 				= 700,
	kPGPSubKeyProperty_Expiration				= 701,

	/* SubKey data (variable sized) properties */	
	kPGPSubKeyProperty_KeyData					= 800,
	kPGPSubKeyProperty_KeyID					= 801,

	/* User ID boolean properties */	
	kPGPUserIDProperty_IsAttribute				= 900,

	/* User ID numeric properties */	
	kPGPUserIDProperty_Validity 				= 1000,
	kPGPUserIDProperty_Confidence				= 1001,
	kPGPUserIDProperty_AttributeType			= 1002,

	/* No User ID time properties */	

	/* User ID data (variable sized) properties */
	kPGPUserIDProperty_Name 					= 1200,
	kPGPUserIDProperty_AttributeData			= 1201,
	kPGPUserIDProperty_CommonName				= 1202,
	kPGPUserIDProperty_EmailAddress				= 1203,
	
	/* Signature boolean properties */
	kPGPSigProperty_IsRevoked 					= 1300,
	kPGPSigProperty_IsNotCorrupt				= 1301,
	kPGPSigProperty_IsTried						= 1302,
	kPGPSigProperty_IsVerified					= 1303,
	kPGPSigProperty_IsMySig						= 1304,
	kPGPSigProperty_IsExportable				= 1305,
	kPGPSigProperty_HasUnverifiedRevocation		= 1306,
	kPGPSigProperty_IsExpired					= 1307,
	kPGPSigProperty_IsX509						= 1308,

	/* Signature numeric properties */
	kPGPSigProperty_AlgorithmID					= 1400,
	kPGPSigProperty_TrustLevel					= 1401,
	kPGPSigProperty_TrustValue					= 1402,
	
	/* Signature time properties */
	kPGPSigProperty_Creation 					= 1500,
	kPGPSigProperty_Expiration					= 1501,

	/* Signature data (variable sized) properties */
	kPGPSigProperty_KeyID 						= 1600,
	kPGPSigProperty_X509Certificate				= 1601,
	kPGPSigProperty_X509IASN					= 1602,
	kPGPSigProperty_X509LongName				= 1603,
	kPGPSigProperty_X509IssuerLongName			= 1604,
	kPGPSigProperty_X509DNSName					= 1605,
	kPGPSigProperty_X509IPAddress				= 1606,
	kPGPSigProperty_X509DERDName				= 1607,
	kPGPSigProperty_RegularExpression			= 1608,

	PGP_ENUM_FORCE( PGPKeyDBObjProperty_ )
} ;
PGPENUM_TYPEDEF( PGPKeyDBObjProperty_, PGPKeyDBObjProperty );


/* For kPGPKeyProperty_Version */
enum PGPKeyVersion_
{
	kPGPKeyVersion_V3					= 3,
	kPGPKeyVersion_V4					= 4,
	
	PGP_ENUM_FORCE( PGPKeyVersion_ )
} ;
PGPENUM_TYPEDEF( PGPKeyVersion_, PGPKeyVersion );


/* kPGPKeyPropFlags bits */

enum	/* PGPKeyPropertyFlags */
{
	kPGPKeyPropertyFlags_UsageSignUserIDs			= (1UL << 0 ),
	kPGPKeyPropertyFlags_UsageSignMessages			= (1UL << 1 ),
	kPGPKeyPropertyFlags_UsageEncryptCommunications	= (1UL << 2 ),
	kPGPKeyPropertyFlags_UsageEncryptStorage		= (1UL << 3 ),

	kPGPKeyPropertyFlags_PrivateSplit				= (1UL << 4 ),
	kPGPKeyPropertyFlags_PrivateShared				= (1UL << 7 )
} ;
typedef PGPFlags		PGPKeyPropertyFlags;
#define kPGPKeyPropertyFlags_UsageSign \
					(kPGPKeyPropertyFlags_UsageSignUserIDs | \
					 kPGPKeyPropertyFlags_UsageSignMessages)
#define kPGPKeyPropertyFlags_UsageEncrypt \
					(kPGPKeyPropertyFlags_UsageEncryptCommunications | \
					 kPGPKeyPropertyFlags_UsageEncryptStorage)
#define kPGPKeyPropertyFlags_UsageSignEncrypt \
					(kPGPKeyPropertyFlags_UsageSign | \
					 kPGPKeyPropertyFlags_UsageEncrypt)

/* Attribute types, for use with kPGPUserIDPropAttributeType */
enum PGPAttributeType_
{
	kPGPAttribute_Image						= 1,
	kPGPAttribute_IPAddress					= 10,
	kPGPAttribute_DNSName					= 11,
	kPGPAttribute_Notation					= 20,

	PGP_ENUM_FORCE( PGPAttributeType_ )
} ;
PGPENUM_TYPEDEF( PGPAttributeType_, PGPAttributeType );

/* Key DB object types for the property kPGPKeyDBObjProperty_ObjectType */ 
enum PGPKeyDBObjType_
{
	kPGPKeyDBObjType_Invalid	= 0,
	kPGPKeyDBObjType_Key		= (1UL << 0),
	kPGPKeyDBObjType_SubKey		= (1UL << 1),
	kPGPKeyDBObjType_UserID		= (1UL << 2),
	kPGPKeyDBObjType_Signature	= (1UL << 3),
#ifdef __MVS__
	kPGPKeyDBObjType_Any		= -1,
#else
	kPGPKeyDBObjType_Any		= 0xFFFFFFFF,
#endif

	PGP_ENUM_FORCE( PGPKeyDBObjType_ )
} ;
PGPENUM_TYPEDEF( PGPKeyDBObjType_, PGPKeyDBObjType );
	
/*
 * Used by filtering functions to specify type of match.
 */

enum PGPMatchCriterion_
{
	kPGPMatchCriterion_Equal 			= 1,	/* searched == val */
	kPGPMatchCriterion_GreaterOrEqual	= 2,	/* searched >= val */
	kPGPMatchCriterion_LessOrEqual 		= 3,	/* searched <= val */
	kPGPMatchCriterion_SubString 		= 4,	/* searched is contained in supplied */

	PGP_ENUM_FORCE( PGPMatchCriterion_ )
} ;
PGPENUM_TYPEDEF( PGPMatchCriterion_, PGPMatchCriterion );


/* This is the value of the expiration time which means "never expires" */
#define kPGPExpirationTime_Never	( (PGPTime)0 )

enum PGPOpenKeyDBFileOptions_
{
	kPGPOpenKeyDBFileOptions_None		= 0,
	kPGPOpenKeyDBFileOptions_Mutable	= (1UL << 0 ),
	kPGPOpenKeyDBFileOptions_Create		= (1UL << 1 ),

	PGP_ENUM_FORCE( PGPOpenKeyDBFileOptions_ )
} ;

PGPENUM_TYPEDEF( PGPOpenKeyDBFileOptions_, PGPOpenKeyDBFileOptions );

/* Public entry points */

PGP_BEGIN_C_DECLARATIONS

/*____________________________________________________________________________
	Key DB functions
____________________________________________________________________________*/

/* Creat a new, in-memory temporary key DB */
PGPError	PGPNewKeyDB( PGPContextRef context, PGPKeyDBRef *keyDBRef );

/* Open a (possibly) existing key ring pair on disk */
PGPError	PGPOpenKeyDBFile( PGPContextRef context,
					PGPOpenKeyDBFileOptions options,
					PGPFileSpecRef pubKeysFileSpec,
					PGPFileSpecRef privKeysFileSpec,
					PGPKeyDBRef *keyDBRef );
 
PGPError	PGPFreeKeyDB( PGPKeyDBRef keyDBRef );

PGPError	PGPFlushKeyDB( PGPKeyDBRef keyDBRef );

PGPError	PGPIncKeyDBRefCount( PGPKeyDBRef keyDBRef );

PGPBoolean	PGPKeyDBIsMutable( PGPKeyDBRef keyDBRef );

PGPError 	PGPFindKeyByKeyID( PGPKeyDBRef keyDBRef, const PGPKeyID * keyID,
					PGPKeyDBObjRef *keyRef);

PGPError 	PGPCountKeysInKeyDB( PGPKeyDBRef keyDBRef, PGPUInt32 *numKeys );

PGPError	PGPKeyDBIsUpdated( PGPKeyDBRef keyDBRef, PGPBoolean *isUpdated );

/* Cache a keydb in memory for specified number of seconds */
PGPError	PGPCacheKeyDB( PGPKeyDBRef keyDBRef, PGPUInt32 timeoutSeconds );

/* Remove all cached keydbs from memory */
PGPError	PGPPurgeKeyDBCache( PGPContextRef context );

/*____________________________________________________________________________
	Key set functions
____________________________________________________________________________*/

/* Create a new key set containing all of the keys in the key DB */
PGPError  	PGPNewKeySet( PGPKeyDBRef keyDB, PGPKeySetRef *keySet );
						
/* Create a new, empty key set */
PGPError  	PGPNewEmptyKeySet( PGPKeyDBRef keyDB, PGPKeySetRef *keySet );

/* Create a new key set containing a single key */
PGPError  	PGPNewOneKeySet( PGPKeyDBObjRef key, PGPKeySetRef *keySet );

PGPError 	PGPFreeKeySet( PGPKeySetRef keys);

PGPError 	PGPIncKeySetRefCount( PGPKeySetRef keys);

PGPBoolean 	PGPKeySetIsMember( PGPKeyDBObjRef key, PGPKeySetRef set );

PGPError 	PGPCountKeys( PGPKeySetRef keys, PGPUInt32 *numKeys );

PGPError 	PGPAddKey( PGPKeyDBObjRef keyToAdd, PGPKeySetRef set );

PGPError 	PGPAddKeys( PGPKeySetRef keysToAdd, PGPKeySetRef set );

PGPKeyDBRef		PGPPeekKeySetKeyDB( PGPKeySetRef keySet );
PGPKeySetRef	PGPPeekKeyDBRootKeySet( PGPKeyDBRef keyDB );

/*____________________________________________________________________________
	Key DB object properties
____________________________________________________________________________*/

PGPError	PGPGetKeyDBObjBooleanProperty( PGPKeyDBObjRef key,
					PGPKeyDBObjProperty whichProperty, PGPBoolean *prop );

PGPError 	PGPGetKeyDBObjNumericProperty( PGPKeyDBObjRef key,
					PGPKeyDBObjProperty whichProperty, PGPInt32 *prop );

PGPError 	PGPGetKeyDBObjTimeProperty( PGPKeyDBObjRef key,
					PGPKeyDBObjProperty whichProperty, PGPTime *prop);
/*
**	Get the data for a binary property. Returns kPGPError_BufferTooSmall if
**	the buffer is too small. Both buffer and dataSize can be NULL.
*/

PGPError 	PGPGetKeyDBObjDataProperty( PGPKeyDBObjRef key,
					PGPKeyDBObjProperty whichProperty, void *buffer,
					PGPSize bufferSize, PGPSize *dataSize);
/*
**	Get the data for a binary property using an allocated output buffer. The
**	allocated buffer must be freed with PGPFreeData(). For convenience, the
**	allocated buffer is null-terminated. The terminating null byte is NOT included
**	is the output dataSize parameter.
*/

PGPError 	PGPGetKeyDBObjAllocatedDataProperty( PGPKeyDBObjRef key,
					PGPKeyDBObjProperty whichProperty, void **buffer,
					PGPSize *dataSize);

PGPError 	PGPSetKeyEnabled( PGPKeyDBObjRef key, PGPBoolean enable );

PGPError	PGPSetKeyAxiomatic( PGPKeyDBObjRef key, PGPBoolean setAxiomatic,
					PGPOptionListRef firstOption, ...);

/*____________________________________________________________________________
	Key DB object property convenience functions
____________________________________________________________________________*/

/* Get the key ID of a key or subkey key DB object */
PGPError	PGPGetKeyID( PGPKeyDBObjRef key, PGPKeyID *keyID );

PGPError  	PGPGetPrimaryUserID( PGPKeyDBObjRef key, PGPKeyDBObjRef *outRef );

PGPError	PGPGetPrimaryAttributeUserID (PGPKeyDBObjRef key,
						PGPAttributeType attributeType, PGPKeyDBObjRef *outRef);