stream.h

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

	   in the connect/handshake phase or the data transfer phase.  The 
	   handshake phase is logically treated as part of the connect phase 
	   even though from the stream point of view it's part of the data 
	   transfer phase.  Initially the stream timeout is set to the connect
	   timeout and the saved timeout is set to the data transfer timeout.  
	   Once the connect/handshake has completed, the stream timeout is set 
	   to the saved data transfer timeout and the saved timeout is cleared */
	STREAM_PROTOCOL_TYPE protocol;/* Network protocol type */
	CRYPT_SESSION iTransportSession;/* cryptlib session as transport layer */
	char *host, *path;
	int port;					/* Host name, path on host, and port */
	int netSocket, listenSocket;/* Network socket */
	int timeout, savedTimeout;	/* Network comms timeout */
	char clientAddress[ 32 ];	/* Client IP address (dotted-decimal) */
	int clientPort;				/* Client port */

	/* Network streams require separate read/write buffers for packet
	   assembly/disassembly */
	BYTE *writeBuffer;			/* Write buffer */
	int writeBufSize;			/* Total size of buffer */
	int writeBufEnd;			/* Last buffer position with valid data */

	/* Network I/O access functions.  The general read and write functions
	   are for the higher-level network access routines such as HTTP and CMP
	   I/O, the transport I/O functions are for transport-level I/O that 
	   sits below the general I/O.  Finally, there's an intermediate function
	   that adds speculative read-ahead buffering to the transport-level 
	   read to improve performance for higher-level protocols like HTTP that
	   have to read a byte at a time in some places */
	int ( *writeFunction )( struct ST *stream, const void *buffer,
							const int length );
	int ( *readFunction )( struct ST *stream, void *buffer, int length );
	int ( *transportConnectFunction )( struct ST *stream, const char *server,
									   const int port );
	void ( *transportDisconnectFunction )( struct ST *stream, 
										   const BOOLEAN fullDisconnect );
	int ( *transportReadFunction )( struct ST *stream, BYTE *buffer,
									const int length, const int flags );
	int ( *transportWriteFunction )( struct ST *stream, const BYTE *buffer,
									 const int length, const int flags );
	BOOLEAN ( *transportOKFunction )( void );
	int ( *transportCheckFunction )( struct ST *stream );
	int ( *bufferedTransportReadFunction )( struct ST *stream, BYTE *buffer,
											const int length, 
											const int flags );
	int ( *bufferedTransportWriteFunction )( struct ST *stream, 
											 const BYTE *buffer,
											 const int length, 
											 const int flags );

	/* Protocol-specific infomation for network I/O */
	char contentType[ CRYPT_MAX_TEXTSIZE + 1 ];	/* HTTP content type */
	char *query;				/* HTTP query URI portion */
	int queryLen;
	CALLBACKFUNCTION callbackFunction;
	void *callbackParams;		/* Callback to change I/O buffer size */

	/* Last-error information returned from lower-level code.  Unlike its
	   use in high-level objects like keysets and devices, we dynamically
	   allocate the error message storage since it's only used for network
	   streams and would lead to a lot of wasted memory in memory streams,
	   which are used constantly throughout cryptlib */
	int errorCode;
	char *errorMessage;
#endif /* USE_TCP */
	} STREAM;

/* Parsed URL information */

typedef enum { URL_TYPE_NONE, URL_TYPE_HTTP, URL_TYPE_HTTPS, URL_TYPE_SSH,
			   URL_TYPE_CMP, URL_TYPE_TSP, URL_TYPE_LAST } URL_TYPE;

typedef struct {
	URL_TYPE type;
	const char *schema, *userInfo, *host, *location;
	int schemaLen, userInfoLen, hostLen, locationLen;
	int port;
	} URL_INFO;

/* Information required when connecting a network stream.  There are so many
   parameters required that we pack them into a struct to keep the interface
   more manageable */

typedef enum {
	NET_OPTION_NONE,			/* No connect option type */
	NET_OPTION_HOSTNAME,		/* Use host/interface name + port */
	NET_OPTION_HOSTNAME_TUNNEL,	/* Use host + port tunnelled via proxy */
	NET_OPTION_TRANSPORTSESSION,/* Use network transport session */
	NET_OPTION_NETWORKSOCKET,	/* Use user-supplied network socket */
	NET_OPTION_NETWORKSOCKET_DUMMY,	/* Dummy open to check socket OK */
	NET_OPTION_LAST				/* Last possible connect option type */
	} NET_OPTION_TYPE;

typedef struct {
	/* Network link information, either a remote host and port, a pre-
	   connected network socket, or a cryptlib transport session */
	const char *name;
	int nameLength;
	int port;					/* Host info */
	int networkSocket;			/* Pre-connected network socket */
	CRYPT_SESSION iCryptSession;/* cryptlib transport session */

	/* Auxiliary information: Owning user object, network status 
	   information, general option type */
	CRYPT_USER iUserObject;		/* Owning user object */
	int timeout, connectTimeout;/* Connect and data xfer.timeouts */
	NET_OPTION_TYPE options;	/* Connect options */
	} NET_CONNECT_INFO;

#define initNetConnectInfo( netConnectInfo, netUserObject, netTimeout, \
							netConnectTimeout, netOption ) \
	{ \
	memset( netConnectInfo, 0, sizeof( NET_CONNECT_INFO ) ); \
	( netConnectInfo )->networkSocket = CRYPT_ERROR; \
	( netConnectInfo )->iCryptSession = CRYPT_ERROR; \
	( netConnectInfo )->iUserObject = netUserObject; \
	( netConnectInfo )->timeout = netTimeout; \
	( netConnectInfo )->connectTimeout = netConnectTimeout; \
	( netConnectInfo )->options = netOption; \
	}

/****************************************************************************
*																			*
*							Stream Function Prototypes						*
*																			*
****************************************************************************/

/* Functions corresponding to traditional/stdio-type I/O.  Apart from the
   convenience factor, the use of a macro for stell() also lets it 
   automatically adjust itself to int vs. long data types */

int sputc( STREAM *stream, const int ch );
int sgetc( STREAM *stream );
int sread( STREAM *stream, void *buffer, const int length );
int swrite( STREAM *stream, const void *buffer, const int length );
int sflush( STREAM *stream );
int sseek( STREAM *stream, const long position );
#define stell( stream )	\
		( ( ( stream )->bufCount * ( stream )->bufSize ) + ( stream )->bufPos )
int sioctl( STREAM *stream, const STREAM_IOCTL_TYPE type, void *data,
			const int dataLen );

/* Nonstandard functions: Skip a number of bytes in a stream, peek at the
   next value in the stream */

int sSkip( STREAM *stream, const long offset );
int sPeek( STREAM *stream );

/* Inquire as to the health of a stream */

#define sGetStatus( stream )		( stream )->status
#define sStatusOK( stream )			cryptStatusOK( ( stream )->status )

/* Set/clear user-defined error state for the stream.  The reason for the
   slightly convoluted code in sSetError() is because a conventional if
   statement would cause problems with dangling elses.  In addition this
   construct allows the expression to have a value, so it can be used in
   return statements (a common usage) */

#define sSetError( stream, error )	\
		( stream )->status = ( ( ( stream )->status == CRYPT_OK ) ? \
								 ( error ) : ( stream )->status )
#define sClearError( stream )		( stream )->status = CRYPT_OK

/* Return after setting extended error information for the stream.  We use a 
   macro to make it match the standard return statement, the slightly unusual
   form is required to handle the fact that the helper function is a varargs
   function */

int retExtStreamFn( STREAM *stream, const int status, 
					const char *format, ... ) PRINTF_FN;
#define retExtStream	return retExtStreamFn

/* Stream query functions to determine whether a stream is a null stream or
   a memory-mapped file stream.  This is used to short-circuit unnecessary 
   data transfers in higher-level code where writing to a null stream is 
   used to determine overall data sizes and when we can eliminate extra
   buffer allocation if all data is available in memory */

#define sIsNullStream( stream )		( ( stream )->type == STREAM_TYPE_NULL )
#define sIsMemMappedStream( stream ) \
		( ( ( stream )->type == STREAM_TYPE_FILE ) && \
		  ( ( stream )->flags & STREAM_FFLAG_MMAPPED ) )

/* Determine the total size of a memory stream, the amount of data left to be
   read, and return a pointer to the current position in a streams internal
   memory buffer.  The latter is used by some routines that need to process
   data in a stream buffer after it's been written to the wire format */

#define sMemBufSize( stream )	( ( stream )->bufSize )
#define sMemDataLeft( stream )	( ( ( stream )->type == STREAM_TYPE_NULL ) ? 0 : \
								  ( stream )->bufSize - ( stream )->bufPos )
#define sMemBufPtr( stream )	( ( ( stream )->type == STREAM_TYPE_NULL ) ? NULL : \
								  ( stream )->buffer + ( stream )->bufPos )

/* Functions to work with memory streams */

int sMemOpen( STREAM *stream, void *buffer, const int length );
int sMemClose( STREAM *stream );
int sMemConnect( STREAM *stream, const void *buffer, const int length );
int sMemDisconnect( STREAM *stream );

/* Functions to work with file streams */

int sFileOpen( STREAM *stream, const char *fileName, const int mode );
int sFileClose( STREAM *stream );

/* Convert a file stream to a memory stream */

int sFileToMemStream( STREAM *memStream, STREAM *fileStream,
					  void **bufPtrPtr, const int length );

/* Functions to work with network streams */

int sNetParseURL( URL_INFO *urlInfo, const char *url, const int urlLen );
int sNetConnect( STREAM *stream, const STREAM_PROTOCOL_TYPE protocol,
				 const NET_CONNECT_INFO *connectInfo, char *errorMessage, 
				 int *errorCode );
int sNetListen( STREAM *stream, const STREAM_PROTOCOL_TYPE protocol,
				const NET_CONNECT_INFO *connectInfo, char *errorMessage,
				int *errorCode );
int sNetDisconnect( STREAM *stream );
void sNetGetErrorInfo( STREAM *stream, char *errorString, int *errorCode );

/* Special-case file I/O calls */

BOOLEAN fileReadonly( const char *fileName );
void fileClearToEOF( const STREAM *stream );
void fileErase( const char *fileName );
void fileBuildCryptlibPath( char *path, const char *fileName,
							const BUILDPATH_OPTION_TYPE option );

/* Initialisation/shutdown functions for network stream interfaces */

#ifdef USE_TCP
  int netInitTCP( void );
  void netSignalShutdown( void );
  void netEndTCP( void );
#else
  #define netInitTCP()						CRYPT_OK
  #define netSignalShutdown()
  #define netEndTCP()
#endif /* NET_TCP */

/* Prototypes for network mapping functions */

#ifdef USE_TCP
  int setAccessMethodTCP( STREAM *stream );
  int setStreamLayerHTTP( STREAM *stream );
  int setStreamLayerCMP( STREAM *stream );
#endif /* USE_TCP */
#endif /* _STREAM_DEFINED */