cryptlib  3.4.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros
session.h
Go to the documentation of this file.
1 /****************************************************************************
2 * *
3 * Secure Session Routines Header File *
4 * Copyright Peter Gutmann 1998-2004 *
5 * *
6 ****************************************************************************/
7 
8 #ifndef _SES_DEFINED
9 
10 #define _SES_DEFINED
11 
12 #ifndef _STREAM_DEFINED
13  #if defined( INC_ALL )
14  #include "stream.h"
15  #else
16  #include "io/stream.h"
17  #endif /* Compiler-specific includes */
18 #endif /* _STREAM_DEFINED */
19 
20 /****************************************************************************
21 * *
22 * Session Types and Constants *
23 * *
24 ****************************************************************************/
25 
26 /* Session information flags. These are:
27 
28  SESSION_ISOPEN: The session is active.
29 
30  SESSION_PARTIALOPEN: The session is partially active pending
31  confirmation of credentials such as a username and password
32  or certificate. This means that the session remains in the
33  handshake state, with the handshake being completed once the
34  credentials have been confirmed.
35 
36  SESSION_SENDCLOSED: The remote system has closed its receive channel,
37  which means that no more data can be sent to it. This does not
38  however mean that no more data can be received on our receive
39  channel.
40 
41  SESSION_ISCLOSINGDOWN: The session is in the shutdown stage, if further
42  requests from the remote system arrive they should be NACK'd or
43  ignored.
44 
45  SESSION_NOREPORTERROR: Don't update the extended error information if
46  an error occurs, since this has already been set. This is
47  typically used when performing shutdown actions in response to
48  a protocol error, when a network error such as the other side
49  closing the connection would overwrite the details of the
50  error that caused the shutdown to be performed.
51 
52  SESSION_ISSERVER: The session is a server session.
53 
54  SESSION_ISSECURE_READ: The read/write channel is in the secure state,
55  SESSION_ISSECURE_WRITE: for secure data transport sessions. In other
56  words the session has passed the initial handshake stage and all
57  data is now being encrypted/MACd/whatever.
58 
59  SESSION_ISCRYPTLIB: The peer is also running cryptlib, which means that
60  we can apply cryptlib-specific optimistions and security
61  enhancements.
62 
63  SESSION_ISHTTPTRANSPORT: The session is using HTTP transport, for
64  request/response sessions.
65 
66  SESSION_USEALTTRANSPORT: The protocol usually uses HTTP but also
67  supports an alternative transport type, which should be used
68  in place of HTTP.
69 
70  SESSION_USEHTTPTUNNEL: The protocol is (potentially) tunneled over an
71  HTTP proxy. In other words if CRYPT_OPTION_NET_HTTP_PROXY is
72  set, the protocol talks through an HTTP proxy rather than a
73  direct connection */
74 
75 #define SESSION_NONE 0x0000 /* No session flags */
76 #define SESSION_ISOPEN 0x0001 /* Session is active */
77 #define SESSION_PARTIALOPEN 0x0002 /* Session is partially active */
78 #define SESSION_SENDCLOSED 0x0004 /* Send channel is closed */
79 #define SESSION_ISCLOSINGDOWN 0x0008 /* Session is in process of shutdown */
80 #define SESSION_NOREPORTERROR 0x0010 /* Don't report network-level errors */
81 #define SESSION_ISSERVER 0x0020 /* Session is server session */
82 #define SESSION_ISSECURE_READ 0x0040 /* Session read ch.in secure state */
83 #define SESSION_ISSECURE_WRITE 0x0080 /* Session write ch.in secure state */
84 #define SESSION_ISCRYPTLIB 0x0100 /* Peer is running cryptlib */
85 #define SESSION_ISHTTPTRANSPORT 0x0200 /* Session using HTTP transport */
86 #define SESSION_USEHTTPTUNNEL 0x0400 /* Session uses HTTP tunnel */
87 #define SESSION_USEALTTRANSPORT 0x0800 /* Use alternative to HTTP xport */
88 
89 /* Needed-information flags used by protocol-specific handlers to indicate
90  that the caller must set the given attributes in the session information
91  before the session can be activated. This allows it to be checked at the
92  general cryptses.c level rather than at the per-protocol level.
93 
94  Some session types have private keys optional but if present they must
95  meet certain requirements, this is indicated by omitting the presence-
96  check SESSION_NEEDS_PRIVATEKEY but specifying one or more of the
97  SESSION_NEEDS_PRIVKEYxxx options */
98 
99 #define SESSION_NEEDS_USERID 0x0001 /* Must have userID */
100 #define SESSION_NEEDS_PASSWORD 0x0002 /* Must have password */
101 #define SESSION_NEEDS_PRIVATEKEY 0x0004 /* Must have private key */
102 #define SESSION_NEEDS_PRIVKEYCRYPT 0x0008 /* Priv.key must have certificate */
103 #define SESSION_NEEDS_PRIVKEYSIGN 0x0010 /* Priv.key must have sig.capabil.*/
104 #define SESSION_NEEDS_PRIVKEYCERT 0x0020 /* Priv.key must have crypt capabil.*/
105 #define SESSION_NEEDS_PRIVKEYCACERT 0x0040 /* Priv key must have CA certificate */
106 #define SESSION_NEEDS_KEYORPASSWORD 0x0080 /* PW can be used in place of privK */
107 #define SESSION_NEEDS_REQUEST 0x0100 /* Must have request obj.*/
108 #define SESSION_NEEDS_KEYSET 0x0200 /* Must have certificate keyset */
109 #define SESSION_NEEDS_CERTSTORE 0x0400 /* Keyset must be certificate store */
110 
111 /* The minimum- and maximum-length fixed headers that we should see in
112  header-read code */
113 
114 #define FIXED_HEADER_MIN 5 /* SSL header */
115 #define FIXED_HEADER_MAX 21 /* TLS 1.1+ header with explicit
116  AES IV */
117 
118 /* When reading packets for a secure session protocol, we need to
119  communicate read state information which is more complex than the usual
120  length or error code. The following values modify the standard return
121  value (either a positive or zero byte count or a negative error value)
122  with additional context-specific information */
123 
124 typedef enum {
125  READINFO_NONE, /* No special handling */
126  READINFO_HEADERPAYLOAD, /* Header read got some payload data */
127  READINFO_NOOP, /* Packet was no-op, try again */
128  READINFO_PARTIAL, /* Partial packet, try again */
129  READINFO_FATAL, /* Treat errors as fatal */
130  READINFO_LAST /* Last possible read information */
131  } READSTATE_INFO;
132 
133 /* The control mechanism for authorisation in interactive sessions.
134  Normally when the server gets a user-authorisation request it'll return a
135  CRYPT_ENVELOPE_RESOURCE to tell the caller that they need to decide what
136  to do with the request. If they set it to AUTHRESPONSE_SUCCESS, we allow
137  the client authorisation, if they set it to AUTHRESPONSE_FAILURE we
138  disallow it and the client gets another go at authorising themselves.
139  The default setting of AUTHRESPONSE_NONE means we ask the user for
140  instructions */
141 
142 typedef enum {
143  AUTHRESPONSE_NONE, /* No authorisation response */
144  AUTHRESPONSE_SUCCESS, /* Allow authorisation */
145  AUTHRESPONSE_FAILURE, /* Disallow authorisation */
146  AUTHRESPONSE_LAST /* Last possible authorisation response */
147  } AUTHRESPONSE_TYPE;
148 
149 /****************************************************************************
150 * *
151 * Session Structures *
152 * *
153 ****************************************************************************/
154 
155 /* Protocol-specific information for each session. The alt.protocol
156  information can be used when a secondary transport protocol is available
157  (e.g. HTTP tunnel for SSL), if the URI type matches then the alt.protocol
158  type, port, and protocol flags are used, the mask is used to mask out
159  existing flags and the new flags value is used to set replacement flags */
160 
161 typedef struct {
162  const STREAM_PROTOCOL_TYPE type; /* Protocol type */
163  BUFFER_FIXED( uriTypeLen ) \
164  const char *uriType; /* Protocol URI type (e.g. "cmp://") */
165  const int uriTypeLen; /* Protocol URI type length */
166  const int port; /* Protocol port */
167  const int oldFlagsMask; /* Mask for current protocol flags */
168  const int newFlags; /* Replacement flags */
169  } ALTPROTOCOL_INFO;
170 
171 typedef struct {
172  /* Information required for all sessions: Whether this is a secure
173  session or request/response protocol, protocol-specific flags, the
174  default port for the protocol, flags for attributes required before
175  the session can be activated, the default protocol version and lowest
176  and highest allowed versions, and the transport-protocol client and
177  server content-types */
178  const BOOLEAN isReqResp; /* Whether session is req/resp session */
179  const int flags; /* Protocol flags */
180  const int port; /* Default port */
181  const int clientReqAttrFlags, serverReqAttrFlags; /* Required attributes */
182  const int version, minVersion, maxVersion;/* Protocol version/subtype */
183 
184  /* Session type-specific information: The send and receive buffer size,
185  the alternative transport protocol for request/response sessions if
186  HTTP isn't being used, the minimum allowed size for the server's
187  private key */
188  const int bufSize; /* Send/receive buffer sizes */
189  const int sendBufStartOfs; /* Payload data start */
190  const int maxPacketSize; /* Maximum packet (payload data) size */
191  const ALTPROTOCOL_INFO *altProtocolInfo; /* Alternative xport protocol */
192  } PROTOCOL_INFO;
193 
194 /* A value to initialise the session type-specific buffer size values to
195  default settings for request/response protocols */
196 
197 #define BUFFER_SIZE_DEFAULT 0, 0, 0
198 
199 /* Attribute flags. These are:
200 
201  FLAG_COMPOSITE: Composite attribute containing sub-attribute data in the
202  { value, valueLength } buffer. The attribute cursor can be
203  moved within the attribute using the internal virtual cursor.
204 
205  FLAG_CURSORMOVED: The attribute (group) cursor has moved, so the virtual
206  cursor within the attribute needs to be reset the next time that
207  it's referenced. This is used with composite attributes, whose
208  internal structure is opaque to the general session code.
209 
210  FLAG_ENCODEDVALUE: The attribute value is stored in cryptlib
211  XXXXX-XXXXX-... style encoding and needs to be converted to
212  binary form before use.
213 
214  FLAG_EPHEMERAL: The attribute is only valid for the current session
215  activation and is cleared between session re-activations.
216 
217  FLAG_MULTIVALUED: Multiple instances of the attribute are permitted.
218  This complements ATTR_FLAG_OVERWRITE in that instead of
219  overwriting the single existing instance, another instance is
220  created */
221 
222 #define ATTR_FLAG_NONE 0x00 /* No attribute flag */
223 #define ATTR_FLAG_ENCODEDVALUE 0x01 /* Value uses XXX-XXX encoding */
224 #define ATTR_FLAG_MULTIVALUED 0x02 /* Multiple instances permitted */
225 #define ATTR_FLAG_COMPOSITE 0x04 /* Composite attribute */
226 #define ATTR_FLAG_CURSORMOVED 0x08 /* Attribute virtual cursor reset */
227 #define ATTR_FLAG_EPHEMERAL 0x10 /* Only valid for current sess.act.*/
228 #define ATTR_FLAG_MAX 0x1F /* Maximum possible flag value */
229 
230 /* The helper function used to access session subtype-specific internal
231  attributes within an attribute list entry */
232 
233 struct AL; /* Forward declaration for attribute-list access function */
234 
235 typedef CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 3 ) ) \
236  int ( *ATTRACCESSFUNCTION )( INOUT struct AL *attributeListPtr,
237  IN_ENUM( ATTR ) const ATTR_TYPE attrGetType,
238  OUT_INT_Z int *value );
239 
240 /* An attribute list used to store session-related attributes such as
241  user names, passwords, and public keys. Since some of these can be
242  composite attributes (with information stored in the { value,
243  valueLength } buffer), we implement a virtual cursor that points to the
244  currently-selected sub-attribute within the composite attribute */
245 
246 typedef struct AL {
247  /* Identification and other information for this attribute */
248  CRYPT_ATTRIBUTE_TYPE groupID, attributeID; /* Attribute group and type */
249  ATTRACCESSFUNCTION accessFunction; /* Internal attribute access fn.*/
250  int flags; /* Attribute data flags */
251 
252  /* The data payload for this attribute. If it's numeric data such as
253  a small integer or context, we store it in the intValue member. If
254  it's a string or composite attribute data, we store it in the
255  variable-length buffer */
256  long intValue; /* Integer value for simple types */
257  BUFFER_OPT_FIXED( valueLength ) \
258  void *value; /* Attribute value */
259  int valueLength; /* Attribute value length */
260 
261  /* The previous and next list element in the linked list of elements */
262  struct AL *prev, *next; /* Prev, next item in the list */
263 
264  /* Variable-length storage for the attribute data */
265  DECLARE_VARSTRUCT_VARS;
266  } ATTRIBUTE_LIST;
267 
268 /* Deferred response information. When we get a request, we may be in the
269  middle of assembling or sending a data packet, so the response has to be
270  deferred until after the data packet has been completed and sent. The
271  following structure is used to hold the response data until the send
272  channel is clear */
273 
274 #define SSH_MAX_RESPONSESIZE 16 /* 2 * channelNo + 2 * param */
275 
276 typedef struct {
277  int type; /* Response type */
278  BUFFER( SSH_MAX_RESPONSESIZE, dataLen ) \
279  BYTE data[ SSH_MAX_RESPONSESIZE + 8 ]; /* Encoded response data */
280  int dataLen;
281  } SSH_RESPONSE_INFO;
282 
283 /* The internal fields in a session that hold data for the various session
284  types */
285 
286 typedef struct {
287  /* Session state information */
288  int sessionCacheID; /* Session cache ID for this session */
289  int minVersion; /* Minimum acceptable protocol version */
290  int ivSize; /* Explicit IV size for TLS 1.1+ */
291 
292  /* The incoming and outgoing packet sequence number, for detecting
293  insertion/deletion attacks */
294  long readSeqNo, writeSeqNo;
295 
296  /* The SSL MAC read/write secrets are required because SSL 3.0 uses a
297  proto-HMAC that isn't handled by cryptlib. We leave the data in
298  normal memory because it's only usable for an active attack, which
299  means that recovering it from swap afterwards isn't a problem */
300  BUFFER_FIXED( CRYPT_MAX_HASHSIZE ) \
301  BYTE macReadSecret[ CRYPT_MAX_HASHSIZE + 8 ];
302  BUFFER_FIXED( CRYPT_MAX_HASHSIZE ) \
303  BYTE macWriteSecret[ CRYPT_MAX_HASHSIZE + 8 ];
304 
305  /* TLS 1.2+ with GCM modes breaks the IV down into two parts, an
306  explicit portion that's sent with every packet and an implicit
307  portion that's derived from the master secret. To save space
308  we store this in the data block for the SSL 3.0 MAC read/write
309  secrets */
310  #define gcmReadSalt macReadSecret
311  #define gcmWriteSalt macWriteSecret
312  int gcmSaltSize;
313 
314  /* The session scoreboard, used for the SSL session cache */
315  void *scoreboardInfoPtr; /* Session scoreboard */
316 
317  /* A buffer for the SSL packet header, which is read out-of-band */
318  BUFFER_FIXED( 8 + CRYPT_MAX_IVSIZE ) \
319  BYTE headerBuffer[ 8 + CRYPT_MAX_IVSIZE + 8 ];
320  } SSL_INFO;
321 
322 typedef struct {
323  /* The packet type and padding length, which are extracted from the
324  packet header during header processing */
325  int packetType, padLength;
326 
327  /* The incoming and outgoing packet sequence number, for detecting
328  insertion/deletion attacks */
329  long readSeqNo, writeSeqNo;
330 
331  /* Per-channel state information */
332  int currReadChannel, currWriteChannel; /* Current active R/W channels */
333  int nextChannelNo; /* Next SSH channel no.to use */
334  int channelIndex; /* Current cryptlib unique channel ID */
335 
336  /* Deferred response data, used to enqueue responses when unwritten data
337  remains in the send buffer */
338  SSH_RESPONSE_INFO response;
339 
340  /* Whether an SSH user authentication packet has been read ready for the
341  server to act on */
342  BOOLEAN authRead;
343 
344  /* A buffer for the SSH packet header, which we receive in encrypted
345  form so that it needs to be decrypted, parts discarded, and the
346  remainder copied into the main buffer as payload data (ugh) */
347  BUFFER_FIXED( CRYPT_MAX_IVSIZE ) \
348  BYTE headerBuffer[ CRYPT_MAX_IVSIZE + 8 ];
349 
350  /* To keep track of the partially-processed data we need to augment the
351  standard pendingPacket indicators with an additional value that
352  tracks how much of the pending packet has already been processed as
353  part of the header read */
354  int partialPacketDataLength; /* Length of data already processed */
355 
356  /* The SSH spec allows authentication to be performed in lots of little
357  bits and pieces, which give an attacker lots of leeway to fiddle with
358  the credentials being submitted on different passes of the
359  authentication to try and confuse the server. To avoid this problem
360  we require that the userID and authentication method remain constant
361  over different iterations of authentication, which unfortunately
362  means recording a pile of server-side authentication state */
363  BUFFER_FIXED( KEYID_SIZE ) \
364  BYTE authUserNameHash[ KEYID_SIZE + 8 ]; /* Hashed userID */
365  int authType; /* Authentication method */
366  } SSH_INFO;
367 
368 typedef struct {
369  /* The message imprint (hash) algorithm and hash value */
370  CRYPT_ALGO_TYPE imprintAlgo;
371  BUFFER( CRYPT_MAX_HASHSIZE, imprintSize ) \
372  BYTE imprint[ CRYPT_MAX_HASHSIZE ];
373  int imprintSize;
374  } TSP_INFO;
375 
376 typedef struct {
377  /* CMP request subtype, user information and protocol flags */
378  int requestType; /* CMP request subtype */
379  CRYPT_CERTIFICATE userInfo; /* PKI user information */
380  int flags; /* Protocol flags */
381 
382  /* The saved MAC context from a previous transaction (if any). This is
383  saved across transactions in case the same user information is used
384  for subsequent transactions, see the comment in cmp.h for details */
385  CRYPT_CONTEXT savedMacContext; /* MAC context from prev.trans */
386  } CMP_INFO;
387 
388 typedef struct {
389  /* SCEP protocol flags */
390  int flags; /* Protocol flags */
391  } SCEP_INFO;
392 
393 /* Defines to make access to the union fields less messy */
394 
395 #define sessionSSH sessionInfo.sshInfo
396 #define sessionSSL sessionInfo.sslInfo
397 #define sessionTSP sessionInfo.tspInfo
398 #define sessionCMP sessionInfo.cmpInfo
399 #define sessionSCEP sessionInfo.scepInfo
400 
401 /* The structure that stores the information on a session */
402 
403 typedef struct SI {
404  /* Control and status information */
405  CRYPT_SESSION_TYPE type; /* Session type */
406  const PROTOCOL_INFO *protocolInfo; /* Session subtype information */
407  int version; /* Protocol version/subtype */
408  CRYPT_ALGO_TYPE cryptAlgo; /* Negotiated encryption algo */
409  CRYPT_ALGO_TYPE integrityAlgo; /* Negotiated integrity prot.algo */
410  int flags, protocolFlags; /* Session information, protocol-specific flags */
411  AUTHRESPONSE_TYPE authResponse; /* Response to user-auth request */
412 
413  /* Session type-specific information */
414  union {
415  SSL_INFO *sslInfo;
416  SSH_INFO *sshInfo;
417  TSP_INFO *tspInfo;
418  CMP_INFO *cmpInfo;
419  SCEP_INFO *scepInfo;
420  } sessionInfo;
421 
422  /* When we add generic attributes to the session, we occasionally need to
423  perform protocol-specific checking of the attributes being added. The
424  following values are used to tell the generic cryptses.c code which
425  checks need to be performed */
426  int clientReqAttrFlags, serverReqAttrFlags; /* Required attributes */
427 
428  /* The overall session status. If we run into a nonrecoverable error
429  (which for the encrypted session types means just about anything,
430  once we lose sync we're toast) we remember the status here so that
431  any further attempts to work with the session will return this
432  status. Since an error on one side of the channel (e.g. bad data on
433  read) doesn't necessarily affect the operation of the other side, we
434  keep track of the two sides independantly, and only set the error
435  state for both sides for network-related errors.
436 
437  In many cases there'll still be data in the internal buffer that the
438  user can read/write without triggering an error response so before we
439  set the error state we set the pending error state and only move the
440  pending state into the current state once all data still present in
441  the buffer has been read */
442  int readErrorState, writeErrorState;/* Current error state */
443  int pendingReadErrorState, pendingWriteErrorState;
444  /* Error state when buffer emptied */
445 
446  /* Data buffer information. In protocols that consist of single
447  messages sent back and forth only the receive buffer is used for
448  sending and receiving data, this buffer is somewhat more flexible
449  since it's associated with extra variables for handling the current
450  position in the buffer (bufPos) vs.the total amount of data present
451  (bufEnd) */
452  BUFFER( sendBufSize, sendBufPos ) \
453  BYTE *sendBuffer;
454  BUFFER_OPT( receiveBufSize, receiveBufEnd ) \
455  BYTE *receiveBuffer; /* Data buffer */
456  int sendBufSize, receiveBufSize; /* Total buffer size */
457  int sendBufPos, receiveBufPos; /* Current position in buffer */
458  int sendBufStartOfs, receiveBufStartOfs; /* Space for header in buffer */
459  int receiveBufEnd; /* Total data in buffer */
460  int maxPacketSize; /* Maximum packet (payload data) size */
461 
462  /* When reading encrypted data packets we typically end up with a partial
463  packet in the read buffer that we can't process until the remainder
464  arrives, the following variables holds the eventual length of the
465  pending data packet and the amount of data remaining to be read */
466  int pendingPacketLength; /* Lending of pending data packet */
467  int pendingPacketRemaining; /* Bytes remaining to be read */
468 
469  /* Unlike payload data, the packet header can't be read in sections but
470  must be read completely since all of the header information needs to
471  be processed at once. The following value is usually zero, if it's
472  nonzero it records how much of the header remains to be read */
473  int partialHeaderRemaining; /* Header bytes still to read */
474 
475  /* When sending data we can also end up with partially-processed packets
476  in the send buffer, but for sending we prevent further packets from
477  being added until the current one is flushed. To handle this all we
478  need is a simple high-water-mark indicator that indicates the start
479  position of any yet-to-be-written data */
480  BOOLEAN partialWrite; /* Unwritten data remains in buffer */
481  int sendBufPartialBufPos; /* Progress point of partial write */
482 
483  /* The session generally has various ephemeral contexts associated with
484  it, some short-term (e.g.public-key contexts used to establish the
485  session) and some long-term (e.g.encryption contexts used to perform
486  bulk data encryption). These contexts are ephemeral ones that are
487  created as part of the session, long-term ones (e.g.signature keys
488  used for authentication) are held elsewhere */
489  CRYPT_CONTEXT iKeyexCryptContext; /* Key exchange encryption */
490  CRYPT_CONTEXT iKeyexAuthContext; /* Key exchange authentication */
491  CRYPT_CONTEXT iCryptInContext, iCryptOutContext;
492  /* In/outgoing data encryption */
493  CRYPT_CONTEXT iAuthInContext, iAuthOutContext;
494  /* In/outgoing auth/integrity */
495  CRYPT_CERTIFICATE iCertRequest, iCertResponse;
496  /* Certificate request/response */
497  int cryptBlocksize, authBlocksize; /* Block size of crypt, auth.algos */
498 
499  /* The private key, which is required to authenticate the client or
500  server in some protocols */
501  CRYPT_CONTEXT privateKey; /* Authentication private key */
502 
503  /* Certificate store for certificate management protocols like OCSP and
504  CMP and private-key keyset for PnP PKI protocols */
505  CRYPT_KEYSET cryptKeyset; /* Certificate store */
506  CRYPT_HANDLE privKeyset; /* Private-key keyset/device */
507 
508  /* Session-related attributes, a current-position cursor in the
509  attribute list */
510  ATTRIBUTE_LIST *attributeList, *attributeListCurrent;
511 
512  /* Network connection information. The reason why the client and server
513  information require separate storage is that (on the server) we may
514  be binding to a specific interface (requiring a server name) and we
515  need to record where the remote system's connection is coming from
516  (requiring a client name) */
517  CRYPT_SESSION transportSession; /* Transport mechanism */
518  int networkSocket; /* User-supplied network socket */
519  int readTimeout, writeTimeout, connectTimeout;
520  /* Connect and data xfer.timeouts */
521  STREAM stream; /* Network I/O stream */
522 
523  /* Low-level error information */
524  ERROR_INFO errorInfo;
525 
526  /* Pointers to session access methods. Stateful sessions use the read/
527  write functions, stateless ones use the transact function */
528  STDC_NONNULL_ARG( ( 1 ) ) \
529  void ( *shutdownFunction )( INOUT struct SI *sessionInfoPtr );
530  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1 ) ) \
531  int ( *connectFunction )( INOUT struct SI *sessionInfoPtr );
532  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
533  int ( *getAttributeFunction )( INOUT struct SI *sessionInfoPtr,
534  OUT void *data,
535  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE type );
536  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
537  int ( *setAttributeFunction )( INOUT struct SI *sessionInfoPtr,
538  IN const void *data,
539  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE type );
540  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
541  int ( *checkAttributeFunction )( INOUT struct SI *sessionInfoPtr,
542  IN const void *data,
543  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE type );
544  CHECK_RETVAL_FNPTR STDC_NONNULL_ARG( ( 1 ) ) \
545  int ( *transactFunction )( INOUT struct SI *sessionInfoPtr );
546  CHECK_RETVAL_LENGTH_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
547  int ( *readHeaderFunction )( INOUT struct SI *sessionInfoPtr,
548  INOUT_ENUM( READSTATE ) READSTATE_INFO *readInfo );
549  CHECK_RETVAL_LENGTH_FNPTR STDC_NONNULL_ARG( ( 1, 2 ) ) \
550  int ( *processBodyFunction )( INOUT struct SI *sessionInfoPtr,
551  INOUT_ENUM( READSTATE ) READSTATE_INFO *readInfo );
552  CHECK_RETVAL_LENGTH_FNPTR STDC_NONNULL_ARG( ( 1 ) ) \
553  int ( *preparePacketFunction )( INOUT struct SI *sessionInfoPtr );
554 
555  /* Error information */
556  CRYPT_ATTRIBUTE_TYPE errorLocus;/* Error locus */
557  CRYPT_ERRTYPE_TYPE errorType; /* Error type */
558 
559  /* The object's handle and the handle of the user who owns this object.
560  The former is used when sending messages to the object when only the
561  xxx_INFO is available, the latter is used to avoid having to fetch the
562  same information from the system object table */
563  CRYPT_HANDLE objectHandle;
564  CRYPT_USER ownerHandle;
565 
566  /* Variable-length storage for the type-specific data */
567  DECLARE_VARSTRUCT_VARS;
568  } SESSION_INFO;
569 
570 /****************************************************************************
571 * *
572 * Session Functions *
573 * *
574 ****************************************************************************/
575 
576 /* Macros to make handling of error reporting on shutdown a bit more
577  obvious */
578 
579 #define disableErrorReporting( sessionInfoPtr ) \
580  ( sessionInfoPtr )->flags |= SESSION_NOREPORTERROR
581 #define enableErrorReporting( sessionInfoPtr ) \
582  ( sessionInfoPtr )->flags &= ~SESSION_NOREPORTERROR
583 
584 /* The SESSION_ISSERVER flag is checked so often that we define a macro to
585  handle it */
586 
587 #define isServer( sessionInfoPtr ) \
588  ( sessionInfoPtr->flags & SESSION_ISSERVER )
589 
590 /* Session attribute handling functions */
591 
592 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
593 int getSessionAttribute( INOUT SESSION_INFO *sessionInfoPtr,
594  OUT_INT_Z int *valuePtr,
595  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
596 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
597 int getSessionAttributeS( INOUT SESSION_INFO *sessionInfoPtr,
598  INOUT MESSAGE_DATA *msgData,
599  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
600 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
601 int setSessionAttribute( INOUT SESSION_INFO *sessionInfoPtr,
602  IN_INT_Z const int value,
603  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
604 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
605 int setSessionAttributeS( INOUT SESSION_INFO *sessionInfoPtr,
606  IN_BUFFER( dataLength ) const void *data,
607  IN_LENGTH const int dataLength,
608  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
609 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
610 int deleteSessionAttribute( INOUT SESSION_INFO *sessionInfoPtr,
611  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
612 
613 /* Session-specific attribute management functions */
614 
615 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
616 int addSessionInfo( INOUT_PTR ATTRIBUTE_LIST **listHeadPtr,
617  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attributeID,
618  IN_INT_Z const int value );
619 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 3 ) ) \
620 int addSessionInfoS( INOUT_PTR ATTRIBUTE_LIST **listHeadPtr,
621  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attributeID,
622  IN_BUFFER( dataLength ) const void *data,
623  IN_LENGTH_SHORT const int dataLength );
624 
625 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 3 ) ) \
626 int addSessionInfoEx( INOUT_PTR ATTRIBUTE_LIST **listHeadPtr,
627  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attributeID,
628  IN_BUFFER( dataLength ) const void *data,
629  IN_LENGTH_SHORT const int dataLength,
630  IN_FLAGS( ATTR ) const int flags );
631 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 3, 4 ) ) \
632 int addSessionInfoComposite( INOUT_PTR ATTRIBUTE_LIST **listHeadPtr,
633  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attributeID,
634  const ATTRACCESSFUNCTION accessFunction,
635  IN_BUFFER( dataLength ) const void *data,
636  IN_LENGTH_SHORT const int dataLength,
637  IN_FLAGS( ATTR ) const int flags );
638 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 3 ) ) \
639 int updateSessionInfo( INOUT_PTR ATTRIBUTE_LIST **listHeadPtr,
640  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attributeID,
641  IN_BUFFER( dataLength ) const void *data,
642  IN_LENGTH_SHORT const int dataLength,
643  IN_LENGTH_SHORT const int dataMaxLength,
644  IN_FLAGS( ATTR ) const int flags );
645 CHECK_RETVAL STDC_NONNULL_ARG( ( 4 ) ) \
646 int getSessionAttributeCursor( IN_OPT ATTRIBUTE_LIST *attributeListHead,
647  IN_OPT ATTRIBUTE_LIST *attributeListCursor,
648  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE sessionInfoType,
649  OUT_ATTRIBUTE_Z CRYPT_ATTRIBUTE_TYPE *valuePtr );
650 CHECK_RETVAL STDC_NONNULL_ARG( ( 2 ) ) \
651 int setSessionAttributeCursor( IN_OPT const ATTRIBUTE_LIST *attributeListHead,
652  INOUT_PTR ATTRIBUTE_LIST **attributeListCursorPtr,
653  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE sessionInfoType,
654  IN_RANGE( CRYPT_CURSOR_LAST, \
655  CRYPT_CURSOR_FIRST ) /* Values are -ve */
656  const int position );
657 CHECK_RETVAL_PTR \
658 const ATTRIBUTE_LIST *findSessionInfo( IN_OPT const ATTRIBUTE_LIST *attributeListPtr,
659  IN_ATTRIBUTE \
660  const CRYPT_ATTRIBUTE_TYPE attributeID );
661 CHECK_RETVAL_PTR STDC_NONNULL_ARG( ( 3 ) ) \
662 const ATTRIBUTE_LIST *findSessionInfoEx( IN_OPT const ATTRIBUTE_LIST *attributeListPtr,
663  IN_ATTRIBUTE \
664  const CRYPT_ATTRIBUTE_TYPE attributeID,
665  IN_BUFFER( valueLength ) const void *value,
666  IN_LENGTH_SHORT const int valueLength );
667 STDC_NONNULL_ARG( ( 1 ) ) \
668 void lockEphemeralAttributes( INOUT ATTRIBUTE_LIST *attributeListHead );
669 STDC_NONNULL_ARG( ( 1, 2, 3 ) ) \
670 int deleteSessionInfo( INOUT ATTRIBUTE_LIST **attributeListHead,
671  INOUT ATTRIBUTE_LIST **attributeListCurrent,
672  INOUT ATTRIBUTE_LIST *attributeListPtr );
673 STDC_NONNULL_ARG( ( 1, 2 ) ) \
674 void deleteSessionInfoAll( INOUT ATTRIBUTE_LIST **attributeListHead,
675  INOUT ATTRIBUTE_LIST **attributeListCurrent );
676 CHECK_RETVAL_ENUM( CRYPT_ATTRIBUTE ) \
677 CRYPT_ATTRIBUTE_TYPE checkMissingInfo( IN_OPT const ATTRIBUTE_LIST *attributeListHead,
678  const BOOLEAN isServer );
679 
680 /* Prototypes for functions in sess_rw.c */
681 
682 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
683 int readFixedHeaderAtomic( INOUT SESSION_INFO *sessionInfoPtr,
684  OUT_BUFFER_FIXED( headerLength ) void *headerBuffer,
685  IN_LENGTH_SHORT_MIN( FIXED_HEADER_MIN ) \
686  const int headerLength );
687 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
688 int readFixedHeader( INOUT SESSION_INFO *sessionInfoPtr,
689  OUT_BUFFER_FIXED( headerLength ) void *headerBuffer,
690  IN_LENGTH_SHORT_MIN( FIXED_HEADER_MIN ) \
691  const int headerLength );
692 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2, 4 ) ) \
693 int getSessionData( INOUT SESSION_INFO *sessionInfoPtr,
694  OUT_BUFFER( dataMaxLength, *bytesCopied ) void *data,
695  IN_LENGTH const int dataMaxLength,
696  OUT_LENGTH_Z int *bytesCopied );
697 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 4 ) ) \
698 int putSessionData( INOUT SESSION_INFO *sessionInfoPtr,
699  IN_BUFFER_OPT( dataLength ) const void *data,
700  IN_LENGTH_Z const int dataLength,
701  OUT_LENGTH_Z int *bytesCopied );
702 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
703 int readPkiDatagram( INOUT SESSION_INFO *sessionInfoPtr );
704 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
705 int writePkiDatagram( INOUT SESSION_INFO *sessionInfoPtr,
706  IN_BUFFER_OPT( contentTypeLength ) \
707  const char *contentType,
708  IN_LENGTH_SHORT_Z const int contentTypeLength );
709 
710 /* Prototypes for functions in session.c */
711 
712 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
713 int initSessionIO( INOUT SESSION_INFO *sessionInfoPtr );
714 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
715 int initSessionNetConnectInfo( const SESSION_INFO *sessionInfoPtr,
716  OUT NET_CONNECT_INFO *connectInfo );
717 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
718 BOOLEAN checkAttributesConsistent( INOUT SESSION_INFO *sessionInfoPtr,
719  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
720 CHECK_RETVAL STDC_NONNULL_ARG( ( 2, 3 ) ) \
721 int checkServerCertValid( const CRYPT_CERTIFICATE iServerCert,
722  OUT_ENUM_OPT( CRYPT_ATTRIBUTE ) \
723  CRYPT_ATTRIBUTE_TYPE *errorLocus,
724  OUT_ENUM_OPT( CRYPT_ERRTYPE ) \
725  CRYPT_ERRTYPE_TYPE *errorType );
726 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
727 int activateSession( INOUT SESSION_INFO *sessionInfoPtr );
728 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
729 int sendCloseNotification( INOUT SESSION_INFO *sessionInfoPtr,
730  IN_BUFFER_OPT( length ) const void *data,
731  IN_LENGTH_SHORT_Z const int length );
732 
733 /* Prototypes for session mapping functions */
734 
735 #ifdef USE_CERTSTORE
736  CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
737  int setAccessMethodCertstore( INOUT SESSION_INFO *sessionInfoPtr );
738 #else
739  #define setAccessMethodCertstore( x ) CRYPT_ARGERROR_NUM1
740 #endif /* USE_CERTSTORE */
741 #ifdef USE_CMP
742  CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
743  int setAccessMethodCMP( INOUT SESSION_INFO *sessionInfoPtr );
744 #else
745  #define setAccessMethodCMP( x ) CRYPT_ARGERROR_NUM1
746 #endif /* USE_CMP */
747 #ifdef USE_RTCS
748  CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
749  int setAccessMethodRTCS( INOUT SESSION_INFO *sessionInfoPtr );
750 #else
751  #define setAccessMethodRTCS( x ) CRYPT_ARGERROR_NUM1
752 #endif /* USE_RTCS */
753 #ifdef USE_OCSP
754  CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
755  int setAccessMethodOCSP( INOUT SESSION_INFO *sessionInfoPtr );
756 #else
757  #define setAccessMethodOCSP( x ) CRYPT_ARGERROR_NUM1
758 #endif /* USE_OCSP */
759 #ifdef USE_SCEP
760  CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
761  int setAccessMethodSCEP( INOUT SESSION_INFO *sessionInfoPtr );
762 #else
763  #define setAccessMethodSCEP( x ) CRYPT_ARGERROR_NUM1
764 #endif /* USE_SCEP */
765 #if defined( USE_SSH ) || defined( USE_SSH1 )
766  CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
767  int setAccessMethodSSH( INOUT SESSION_INFO *sessionInfoPtr );
768 #else
769  #define setAccessMethodSSH( x ) CRYPT_ARGERROR_NUM1
770 #endif /* USE_SSH || USE_SSH1 */
771 #ifdef USE_SSL
772  CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
773  int setAccessMethodSSL( INOUT SESSION_INFO *sessionInfoPtr );
774 #else
775  #define setAccessMethodSSL( x ) CRYPT_ARGERROR_NUM1
776 #endif /* USE_SSL */
777 #ifdef USE_TSP
778  CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
779  int setAccessMethodTSP( INOUT SESSION_INFO *sessionInfoPtr );
780 #else
781  #define setAccessMethodTSP( x ) CRYPT_ARGERROR_NUM1
782 #endif /* USE_TCP */
783 #endif /* _SES_DEFINED */
Generated on Thu Jan 10 2013 10:00:52 for cryptlib by   doxygen 1.8.2