stream.h

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

/****************************************************************************
*																			*
*						STREAM Class Constants and Structures				*
*						  Copyright Peter Gutmann 1993-2005					*
*																			*
****************************************************************************/

#ifndef _STREAM_DEFINED

#define _STREAM_DEFINED

#if defined( INC_ALL )
  #include "crypt.h"
#elif defined( INC_CHILD )
  #include "../crypt.h"
#else
  #include "crypt.h"
#endif /* Compiler-specific includes */
#if defined( __WIN32__ ) || defined( __WINCE__ )
  /* Includes are always handled via the normal system includes */
#elif defined( __UNIX__ ) || defined( __BEOS__ ) || defined( __XMK__ )
  #include <unistd.h>		/* For lseek() codes */
#elif defined( __MAC__ )
  #include <Files.h>
#elif defined( __PALMOS__ )
  #include <VFSMgr.h>
#elif defined( __UCOSII__ )
  #include <fs_api.h>
#elif !defined( CONFIG_NO_STDIO )
  #include <stdio.h>
#endif /* System-specific file I/O headers */

/****************************************************************************
*																			*
*								STREAM Constants							*
*																			*
****************************************************************************/

/* The stream types */

typedef enum {
	STREAM_TYPE_NONE,					/* No stream type */
	STREAM_TYPE_NULL,					/* Null stream (/dev/nul) */
	STREAM_TYPE_MEMORY,					/* Memory stream */
	STREAM_TYPE_FILE,					/* File stream */
	STREAM_TYPE_NETWORK,				/* Network stream */
	STREAM_TYPE_LAST					/* Last possible stream type */
	} STREAM_TYPE;

/* General-purpose stream flags.  The PARTIALREAD flag is used for network 
   reads to handle timeouts and for file streams when we don't know the full 
   extent of a file stream, when it's set and we ask for a read of n bytes 
   and there isn't sufficient data present in the file to satisfy the 
   request the stream code returns 0...n bytes rather than an underflow error.
   The PARTIALWRITE flag is used for network streams when performing bulk 
   data transfers, in this case the write may time out and can be restarted
   later rather than returning a timeout error */

#define STREAM_FLAG_READONLY	0x0001	/* Read-only stream */
#define STREAM_FLAG_PARTIALREAD 0x0002	/* Allow read of less than req.amount */
#define STREAM_FLAG_PARTIALWRITE 0x0004	/* Allow write of less than req.amount */
#define STREAM_FLAG_MASK		0x0007	/* Mask for general-purpose flags */

/* File stream flags */

#define STREAM_FFLAG_DIRTY		0x0010	/* Stream contains unwritten data */
#define STREAM_FFLAG_EOF		0x0020	/* EOF reached on stream */
#define STREAM_FFLAG_POSCHANGED	0x0040	/* File stream position has changed */
#define STREAM_FFLAG_POSCHANGED_NOSKIP 0x0080	/* New stream pos.is in following block */
#define STREAM_FFLAG_MMAPPED	0x0100	/* File stream is memory-mapped */
#define STREAM_FFLAG_MASK		( 0x01F0 | STREAM_FLAG_MASK )	
										/* Mask for file-only flags */

/* Network stream flags.  The ENCAPS flag indicates that the protocol is 
   running over a lower encapsulation layer that provides additional packet
   control information, typically packet size and flow control information.
   If this flag is set, the lower-level read code overrides some error 
   handling that normally takes place at a higher level.  For example if a 
   read of n bytes is requested and the encapsulation layer reports that 
   only m bytes, m < n is present, this isn't treated as a read/timeout 
   error */

#define STREAM_NFLAG_ISSERVER	0x01000	/* Stream is server rather than client */
#define STREAM_NFLAG_USERSOCKET	0x02000	/* Network socket was supplied by user */
#define STREAM_NFLAG_HTTP10		0x04000	/* HTTP 1.0 stream */
#define STREAM_NFLAG_HTTPPROXY	0x08000	/* Use HTTP proxy format for requests */
#define STREAM_NFLAG_HTTPTUNNEL	0x10000	/* Use HTTP proxy tunnel for connect */
#define STREAM_NFLAG_IDEMPOTENT	0x20000	/* Allow idempotent HTTP queries only */
#define STREAM_NFLAG_LASTMSG	0x40000	/* Last message in exchange */
#define STREAM_NFLAG_ENCAPS		0x80000	/* Network transport is encapsulated */
#define STREAM_NFLAG_MASK		( 0x0FF000 | STREAM_FLAG_MASK )
										/* Mask for network-only flags */

/* Network transport-specific flags.  The flush flag is used in writes to
   flush data in the stream, the blocking/nonblocking flags are used to
   override the stream default behaviour on reads */

#define TRANSPORT_FLAG_NONE		0x00	/* No transport flag */
#define TRANSPORT_FLAG_FLUSH	0x01	/* Flush data on write */
#define TRANSPORT_FLAG_NONBLOCKING 0x02	/* Explicitly perform nonblocking read */
#define TRANSPORT_FLAG_BLOCKING	0x04	/* Explicitly perform blocking read */

/* Occasionally we want to connect a memory stream to a fixed-length buffer
   whose size is (by definition) big enough for the data it needs to hold, 
   but of an unknown length (this is currently only used in keyex.c when 
   writing a wrapped key to an output buffer and in sign.c when writing a 
   signature to an output buffer, in both cases with data passed in by the
   user through the cryptlib 2.0-era legacy functions).  Using the following 
   as the length will avoid various checks on the input length */

/* #define STREAMSIZE_UNKNOWN	-1 */

/* When we're reading data of unknown size from an external source, we may
   need to dynamically increase the I/O buffer size during the read.  The 
   following callback function is used to increase the I/O buffer size */

typedef int ( *CALLBACKFUNCTION )( void *callbackParams, void **bufPtr, \
								   const int bufSize );

/* Access/option flags for the file stream open call.  The exclusive access
   flag locks the file so that other threads/processes can't open it until
   the current thread/process closes it.  This flag is implicitly set if the
   file R/W bits are FILE_WRITE, which creates a new file.  The difference
   between the private and sensitive flags is that some data may be private
   for a given user but not sensitive (e.g.config info) while other data may
   be private and sensitive (e.g.private keys).  The sensitive flag only has
   an effect on special systems where data can be committed to secure
   storage, since there's usually a very limited amount of this available we
   only use it for sensitive data but not generic private data */

#define FILE_READ			0x01	/* Open file for read access */
#define FILE_WRITE			0x02	/* Open file for write access */
#define FILE_EXCLUSIVE_ACCESS 0x04	/* Don't allow others access */
#define FILE_PRIVATE		0x08	/* Set ACL's to allow owner access only */
#define FILE_SENSITIVE		0x10	/* Use secure storage if available */
#define FILE_RW_MASK		0x03	/* Mask for R/W bits */

/* Options for the build-path call */

typedef enum {
	BUILDPATH_NONE,					/* No option type */
	BUILDPATH_CREATEPATH,			/* Get path to config file, create if nec.*/
	BUILDPATH_GETPATH,				/* Get path to config file */
	BUILDPATH_RNDSEEDFILE,			/* Get path to random seed file */
	BUILDPATH_LAST					/* Last valid option type */
	} BUILDPATH_OPTION_TYPE;

/* Stream IOCTL types */

typedef enum {
	STREAM_IOCTL_NONE,				/* No IOCTL type */
	STREAM_IOCTL_IOBUFFER,			/* Working buffer for file streams */
	STREAM_IOCTL_PARTIALREAD,		/* Allow read of less than req.amount */
	STREAM_IOCTL_PARTIALWRITE,		/* Allow write of less then req.amount */
	STREAM_IOCTL_READTIMEOUT,		/* Network read timeout */
	STREAM_IOCTL_WRITETIMEOUT,		/* Network write timeout */
	STREAM_IOCTL_HANDSHAKECOMPLETE,	/* Toggle handshake vs.data timeout */
	STREAM_IOCTL_CONNSTATE,			/* Connection state (open/closed) */
	STREAM_IOCTL_GETCLIENTNAME,		/* Get client name */
	STREAM_IOCTL_GETCLIENTPORT,		/* Get client port */
	STREAM_IOCTL_CONTENTTYPE,		/* HTTP content type */
	STREAM_IOCTL_QUERY,				/* HTTP query portion of URL */
	STREAM_IOCTL_IDEMPOTENT,		/* Allow idempotent HTTP queries only */
	STREAM_IOCTL_LASTMESSAGE,		/* CMP last message in transaction */
	STREAM_IOCTL_CALLBACKFUNCTION,	/* Callback function address */
	STREAM_IOCTL_CALLBACKPARAMS,	/* Callback function parameters */
	STREAM_IOCTL_CLOSESENDCHANNEL,	/* Close send side of channel */
	STREAM_IOCTL_LAST				/* Last possible IOCTL type */
	} STREAM_IOCTL_TYPE;

/* Stream network protocol types.  The difference between PROTOCOL_HTTP and
   PROTOCOL_HTTP_TRANSACTION is that the former is a read-only stream that
   performs a (transparent) GET followed by a read of the response while the
   latter is a read/write stream which expects a write that performs a POST
   followed by a read that fetches the response */

typedef enum {
	STREAM_PROTOCOL_NONE,			/* No protocol type */
	STREAM_PROTOCOL_TCPIP,			/* TCP/IP */
	STREAM_PROTOCOL_HTTP,			/* HTTP fetch */
	STREAM_PROTOCOL_HTTP_TRANSACTION,/* HTTP POST+fetch */
	STREAM_PROTOCOL_CMP,			/* TCP/IP with CMP packets */
	STREAM_PROTOCOL_LAST			/* Last possible protocol type */
	} STREAM_PROTOCOL_TYPE;

/* The size of the I/O buffer used to read/write data from/to streams backed 
   by persistent files.  These are allocated on-demand on the stack, so they
   shouldn't be made too big.  In addition since they may corespond directly
   to underlying storage media blocks (e.g. disk sectors or flash memory
   segments) they shouldn't be made smaller than the underlying blocksize
   either.  Finally, they should be a power of two (this isn't a strict
   requirement of the code, but is in a good idea in general because of 
   storage media constraints) */

#ifdef CONFIG_CONSERVE_MEMORY
  #define STREAM_BUFSIZE	512
#else
  #define STREAM_BUFSIZE	4096
#endif /* CONFIG_CONSERVE_MEMORY */

/****************************************************************************
*																			*
*							STREAM Class Structures							*
*																			*
****************************************************************************/

/* The STREAM data type */

typedef struct ST {
	/* General information for the stream */
	STREAM_TYPE type;			/* The stream type */
	int flags;					/* Stream flags */
	int status;					/* Current stream status (clib error code) */

	/* Information for memory I/O */
	BYTE *buffer;				/* Buffer to R/W to */
	int bufSize;				/* Total size of buffer */
	int bufPos;					/* Current position in buffer */
	int bufEnd;					/* Last buffer position with valid data */

	/* Information for file I/O */
	int bufCount;				/* File position quantised by buffer size */
#if defined( __WIN32__ ) || defined( __WINCE__ )
	HANDLE hFile;				/* Backing file for the stream */
#elif defined( __AMX__ ) || defined( __BEOS__ ) || defined( __ECOS__ ) || \
	  defined( __RTEMS__ ) || defined( __SYMBIAN32__ ) || \
	  defined( __TANDEM_NSK__ ) || defined( __TANDEM_OSS__ ) || \
	  defined( __UNIX__ ) || defined( __VXWORKS__ ) || defined( __XMK__ )
	int fd;						/* Backing file for the stream */
#elif defined( __MAC__ )
	short refNum;				/* File stream reference number */
	FSSpec fsspec;				/* File system specification */
#elif defined( __PALMOS__ )
	FileRef fileRef;			/* File reference number */
#elif defined( __UCOSII__ )
	FS_FILE *pFile;				/* File associated with this stream */
#elif defined( CONFIG_NO_STDIO )
  #if defined( __IBM4758__ )
	char name[ 8 + 1 ];			/* Data item associated with stream */
	BOOLEAN isSensitive;		/* Whether stream contains sensitive data */
  #elif defined( __VMCMS__ )
	char name[ FILENAME_MAX ];	/* Data item associated with stream */
  #endif /* Nonstandard I/O enviroments */
#else
	FILE *filePtr;				/* The file associated with this stream */
#endif /* System-specific file I/O information */

#ifdef USE_TCP
	/* Information for network I/O.  The server FQDN is held in dynamically-
	   allocated storage, the optional path for HTTP is a pointer into the
	   host string at the appropriate location.  For a server, the
	   listenSocket is the (possibly shared) common socket that the server
	   is listening on, the netSocket is the ephemeral socket used for
	   communications.  The timeout value depends on whether the stream is