pgpsdkdriver.h

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

/*____________________________________________________________________________
	Copyright (C) 2002 PGP Corporation
	All rights reserved.

	pgpUtilityDriverWin32.h - header for callers of Win32 PGP Utility Driver


	$Id: PGPsdkDriver.h,v 1.10 2002/08/06 20:11:23 dallen Exp $

____________________________________________________________________________*/

#ifndef _pgpUtilityDriverWin32_h
#define _pgpUtilityDriverWin32_h

#if ! PGP_WIN32
#error this file should only be used for PGP_WIN32
#endif

#ifndef PGPSDK_DRIVER
#define PGPSDK_DRIVER 0
#endif

#define kPGPUDMaxVersionStringLength			80
#define kPGPUDMaxCacheIndexLength				64
#define kPGPUDMaxCacheDataLength				64

/* driver-specific error codes */
#define kPGPUDError_NoErr						0x0000
#define kPGPUDError_UndefinedOperation			0x0001
#define kPGPUDError_BadParams					0x0002
#define kPGPUDError_MemAllocError				0x0003
#define kPGPUDError_BufferTooSmall				0x0004
#define kPGPUDError_DriverUninitialized			0x0005

#define kPGPUDError_MemLockError				0x0101
#define kPGPUDError_MemUnlockError				0x0102
#define kPGPUDError_LockListError				0x0103

#define kPGPUDError_WipePending					0x0201

#define kPGPUDError_ItemNotFound				0x0301


/* virtual memory paging in Win32 (Intel) uses 4K byte pages (2^12) */
#define WIN32PAGESIZE	12

/* Define the various device type values.  Note that values used by Microsoft
   Corporation are in the range 0-32767, and 32768-65535 are reserved for use
   by customers. */

#define FILE_DEVICE_PGPUTILITY					0x00008001

/* Macro definition for defining IOCTL and FSCTL function control codes.  Note
   that function codes 0-2047 are reserved for Microsoft Corporation, and
   2048-4095 are reserved for customers. */

#define PGPUTILITY_IOCTL_INDEX					0x800

/* For defining our own private IOCTLs */
#define METHOD_BUFFERED							0
#define FILE_ANY_ACCESS							0

#define CTL_CODE( DeviceType, Function, Method, Access ) (                 \
    ((DeviceType) << 16) | ((Access) << 14) | ((Function) << 2) | (Method) \
)

/*____________________________________________________________________________

	Generic driver functions

	The calling Win32 application should initialize a PGPGENERICSTRUCT with
	an operation code and then pass the address of the structure to the driver
	via a call to DeviceIOControl.

	Currently these generic operations are supported:

		kPGPUDOperation_QueryVersion
			the driver will copy a null-terminated version string to ucBuffer.
		kPGPUDOperation_QueryStatus
			the driver will return status flags in ulFlags.

	Possible return values of ulError :
		kPGPUDError_NoErr
		kPGPUDError_UndefinedOperation


	Example:
		PGPGENERICSTRUCT	pgs;
		DWORD				dw;

		pgs.ulOperation = kPGPUDOperation_QueryVersion;
		bDIOreturn = DeviceIoControl(	hPGPUtilityDriver,
										IOCTL_PGPUTIL_GENERIC,
										&pgs,
										sizeof( pgs ),
										&pgs,
										sizeof( pgs ),
										&dw,
										NULL );
		if ( !bDIOreturn )
		{
			// this is an error communicating with the driver
		}

		else
		{
			if ( pgs.ulError != kPGPUDError_NoErr )
			{
				// this is an error internal to the driver
			}
			else
			{
				printf ("\nDriver version : %s\n", pgs.ucBuffer);
			}
		}

____________________________________________________________________________*/

#define IOCTL_PGPUTIL_GENERIC			CTL_CODE(FILE_DEVICE_PGPUTILITY, \
                                                 PGPUTILITY_IOCTL_INDEX,  \
                                                 METHOD_BUFFERED,     \
                                                 FILE_ANY_ACCESS)

#define kPGPUDOperation_QueryVersion			0x0000
#define kPGPUDOperation_QueryStatus				0x0001

#define kPGPUDFlag_MemlockInitialized			0x0001
#define kPGPUDFlag_WipeDeleteInitialized		0x0002
#define kPGPUDFlag_KeyboardHookInstalled		0x0004
#define kPGPUDFlag_MouseHookInstalled			0x0008
#define kPGPUDFlag_KeyboardHookCalled			0x0010
#define kPGPUDFlag_MouseHookCalled				0x0020
#define kPGPUDFlag_InactivityTimerRunning		0x0040

typedef struct {
	ULONG	ulOperation;
	ULONG	ulError;
	ULONG	ulFlags;
	UCHAR	ucBuffer[kPGPUDMaxVersionStringLength];
} PGPGENERICSTRUCT, *PPGPGENERICSTRUCT;


/*____________________________________________________________________________

	Memory locking functions

	This kernel mode device driver is used to lock memory pages into RAM
	so that they will not get copied to the system page file.  This
	functionality is desired when allocating buffers that will contain
	sensitive information (e.g. passwords) which could present a security
	hazard if copied to the page file.

	The calling application should initialize a PGPMEMLOCKSTRUCT and pass
	the address of the structure to the driver via a call to DeviceIoControl.

	Currently these memory locking operations are supported:

		kPGPUDOperation_LockMemory
			The driver will lock the memory, preventing it from being paged
			out to the paging file.  The calling application must set these
			values in the PGPMEMLOCKSTRUCT :

			pMem		- address of memory block to be locked
			ulNumBytes	- number of bytes in memory block to be locked

		kPGPUDOperation_UnlockMemory
			The driver will unlock the specified memory block.  The calling
			application must set these values in the PGPMEMLOCKSTRUCT :

			pMem		- address of memory block to be unlocked
			ulNumBytes	- number of bytes in memory block to be unlocked

  	Possible return values of ulError :
		kPGPUDError_NoErr
		kPGPUDError_UndefinedOperation
		kPGPUDError_DriverUninitialized
		kPGPUDError_MemLockError
		kPGPUDError_MemUnlockError
		kPGPUDError_LockListError
		kPGPUDError_MemAllocError


	Example :

		PGPMEMLOCKSTRUCT	pmls;
		DWORD				dw;
		BOOL				bDIOreturn;
		PVOID				pMem;
		ULONG				ulNumBytes;

		// allocate the memory
		ulNumBytes = number_of_bytes_to_allocate;
		pMem = VirtualAlloc ( NULL, ulNumBytes, MEM_COMMIT, PAGE_READWRITE );

		// lock the memory
		pmls.ulOperation	= kPGPUDOperation_LockMemory
		pmls.pMem			= pMem;
		pmls.ulNumBytes		= ulNumBytes;

		bDIOreturn = DeviceIoControl(	hPGPUtilityDriver,
										IOCTL_PGPUTIL_MEMLOCK,
										&pmls,
										sizeof( pmls ),
										&pmls,
										sizeof( pmls ),
										&dw,
										NULL );
		if ( !bDIOreturn )
		{
			// this is an error communicating with the driver
		}

		else
		{
			if ( mls.ulError != kPGPUDError_NoErr )
			{
				// this is an error internal to the driver
			}
			else
			{
				// successfully locked!
			}
		}


		// unlocking the memory
		pmls.ulOperation	= kPGPUDOperation_UnlockMemory
		pmls.pMem			= pMem;
		pmls.ulNumBytes		= ulNumBytes;
		bDIOreturn = DeviceIoControl(	hPGPUtilityDriver,
										IOCTL_PGPUTIL_MEMLOCK,
										&pmls,
										sizeof( pmls ),
										&pmls,
										sizeof( pmls ),
										&dw,
										NULL );
		if ( !bDIOreturn )
		{
			// this is an error communicating with the driver
		}

		else
		{
			if ( mls.ulError != kPGPUDError_NoErr )
			{
				// this is an error internal to the driver
			}
			else
			{
				// successfully unlocked!
			}
		}

		// free the memory
		VirtualFree( pMem, 0, MEM_RELEASE );


____________________________________________________________________________*/

#define IOCTL_PGPUTIL_MEMLOCK			CTL_CODE(FILE_DEVICE_PGPUTILITY,  \
                                                 PGPUTILITY_IOCTL_INDEX+1,\
                                                 METHOD_BUFFERED,     \
                                                 FILE_ANY_ACCESS)

#define kPGPUDOperation_LockMemory				0x0000
#define kPGPUDOperation_UnlockMemory			0x0001

#if PGP_WIN32
#pragma pack(8)
#endif
typedef struct {
	ULONG	ulOperation;
	ULONG	ulError;
	PVOID	pMem;
	ULONG	ulNumBytes;
} PGPMEMLOCKSTRUCT, *PPGPMEMLOCKSTRUCT;
#if PGP_WIN32
#pragma pack()
#endif



/*____________________________________________________________________________

	Keyboard/mouse entropy functions

	These functions are used to request entropy from the driver.  The driver
	continuously monitors keyboard and mouse events and derives cryptographic
	quality entropy from them.

	The calling application should initialize a PGPENTROPYSTRUCT and pass the
	address of the structure to the driver via a call to DeviceIoControl.

	Currently these entropy operations are supported:

		kPGPUDOperation_QueryEntropy
			The driver will inform the caller of the number of bits of entropy
			currently present in the entropy pool.  The number of bits will
			be returned in ulEntropyBits.

		kPGPUDOperation_GetEntropy
			The driver will attempt to provide the requested amount of entropy
			to the caller.  The driver will always fill the buffer with the
			requested number of random bytes and will return, in ulEntropyBits,
			the amount of entropy provided.  The caller should set these
			parameters in the PGPENTROPYSTRUCT :

			ulBufferLength		- length of buffer (in bytes) to fill with
								  random data


  	Possible return values of ulError :
		kPGPUDError_NoErr
		kPGPUDError_UndefinedOperation


	Example:

		PGPENTROPYSTRUCT*		ppes;
		DWORD					dw;
		INT						iNumberOfBytes;
		INT						iStructSize;

		iNumberOfBytes	= max_number_of_bytes_of_entropy_needed;
		iStructSize		= sizeof(PGPENTROPYSTRUCT) + iNumberOfBytes -1;

		ppes = malloc (iStructSize);
		ppes->ulOperation = kPGPUDOperation_QueryEntropy;

		bDIOreturn = DeviceIoControl(	hPGPUtilityDriver,
										IOCTL_PGPUTIL_ENTROPY,
										ppes,
										iStructSize,
										ppes,
										iStructSize,
										&dw,
										NULL );
		if ( !bDIOreturn )
		{
			// this is an error communicating with the driver
		}

		else
		{
			if ( pgs.ulError != kPGPUDError_NoErr )
			{
				// this is an error internal to the driver
			}
			else
			{
				// driver successfully queried, now get the random data
				if (ppes->ulEntropyBits >= bits_needed)
				{
					ppes->ulOperation		= kPGPUDOperation_GetEntropy;
					ppes->ulBufferLength	= bits_needed/8 +1;

					bDIOreturn = DeviceIoControl(	hPGPUtilityDriver,
													IOCTL_PGPUTIL_ENTROPY,
													ppes,
													iStructSize,
													ppes,
													iStructSize,
													&dw,
													NULL );

					if ( !bDIOreturn )
					{
						// this is an error communicating with the driver
					}

					else
					{
						if ( pgs.ulError != kPGPUDError_NoErr )
						{
							// this is an error internal to the driver
						}
						else
						{
							// see if we really got the data
							if (ppes->ulEntropyBits >= bits_needed)
							{
								// success!
							}
						}
					}
				}
			}
		}

____________________________________________________________________________*/


#define IOCTL_PGPUTIL_ENTROPY			CTL_CODE(FILE_DEVICE_PGPUTILITY, \
                                                 PGPUTILITY_IOCTL_INDEX+2,  \
                                                 METHOD_BUFFERED,     \
                                                 FILE_ANY_ACCESS)

#define kPGPUDOperation_QueryEntropy			0x0000
#define kPGPUDOperation_GetEntropy				0x0001

#if PGP_WIN32
#pragma pack(8)
#endif
typedef struct {
	ULONG	ulOperation;
	ULONG	ulError;
	ULONG	ulEntropyBits;
	ULONG	ulBufferLength;
	UCHAR	ucEntropyBuffer[1];
} PGPENTROPYSTRUCT, *PPGPENTROPYSTRUCT;
#if PGP_WIN32
#pragma pack()
#endif

/*____________________________________________________________________________

	Passkey cache functions

	These functions are used to cache passkeys for signing and decryption.

	The calling application should initialize a PGPCACHESTRUCT and pass the
	address of the structure to the driver via a call to DeviceIoControl.

	Currently these cache operations are supported:

		kPGPUDOperation_PurgeCache
			The driver will purge the contents of the specified cache.  The
			caller must specify the cache type (kPGPUDCache_Signing or
			kPGPUDCache_Decryption) in ulCache.

		kPGPUDOperation_SetCacheValue
			The driver will insert the index and data into the specified cache
			and begin timing the cache entry using the specified time value.
			After the specified number of seconds have elapsed without the
			entry having been accessed, the entry will be removed from the
			cache.  The caller must specify these values :

			ulCache			- cache to use (kPGPUDCache_Signing or
							  kPGPUDCache_Decryption)
			ulSeconds		- cache entry duration
			ulIndexLength	- length of cache index
			ucIndex			- buffer of data to use as index
			ulDataLength	- passkey length
			ucData			- passkey data buffer

		kPGPUDOperation_QueryCacheValue
			The driver will search the specified cache for the specified index
			value.  If a match is found, the data from the cache is copied to
			the ucData buffer and ulDataLength is set.  The caller must specify
			these values :

			ulCache			- cache to search (kPGPUDCache_Signing or
							  kPGPUDCache_Decryption)
			ulIndexLength	- length of cache index
			ucIndex			- buffer of data to use as index

  	Possible return values of ulError :
		kPGPUDError_NoErr
		kPGPUDError_UndefinedOperation
		kPGPUDError_ItemNotFound
		kPGPUDError_MemAllocError


	Example:

		struct {
			INT			keyalg;
			PGPKeyID	keyid;
		} datastruct;

		PGPCACHESTRUCT		pcs;
		DWORD				dw;

		// add entry to cache
		pcs.ulOperation		= kPGPUDOperation_SetCacheValue;
		pcs.ulCache			= kPGPUDCache_Signing;
		pcs.ulSeconds		= duration;
		pcs.ulIndexLength	= sizeof(datastruct);
		memcpy (&pcs.ucIndex, &datastruct, sizeof(datastruct));
		ulDataLength		= passkeylength;
		memcpy (&pcs.ucData, pPasskey, passkeylength);

		bDIOreturn = DeviceIoControl(	hPGPUtilityDriver,
										IOCTL_PGPUTIL_CACHE,
										&pcs,
										sizeof( pcs ),
										&pcs,
										sizeof( pcs ),
										&dw,
										NULL );
		if ( !bDIOreturn )
		{
			// this is an error communicating with the driver
		}

		else
		{
			if ( pgs.ulError != kPGPUDError_NoErr )
			{
				// this is an error internal to the driver
			}
			else
			{
				// entry added to cache successfully
			}
		}