doc/session.doc

   1 I have just checked over and re-worked the session stuff.
   2 The following brief example will ignore all setup information to do with
   3 authentication.
   4
   5 Things operate as follows.
   6
   7 The SSL environment has a 'context', a SSL_CTX structure.  This holds the
   8 cached SSL_SESSIONS (which can be reused) and the certificate lookup
   9 information.  Each SSL structure needs to be associated with a SSL_CTX.
  10 Normally only one SSL_CTX structure is needed per program.
  11
  12 SSL_CTX *SSL_CTX_new(void );
  13 void    SSL_CTX_free(SSL_CTX *);
  14 These 2 functions create and destroy SSL_CTX structures
  15
  16 The SSL_CTX has a session_cache_mode which is by default,
  17 in SSL_SESS_CACHE_SERVER mode.  What this means is that the library
  18 will automatically add new session-id's to the cache apon sucsessful
  19 SSL_accept() calls.
  20 If SSL_SESS_CACHE_CLIENT is set, then client certificates are also added
  21 to the cache.
  22 SSL_set_session_cache_mode(ctx,mode)  will set the 'mode' and
  23 SSL_get_session_cache_mode(ctx) will get the cache 'mode'.
  24 The modes can be
  25 SSL_SESS_CACHE_OFF      - no caching
  26 SSL_SESS_CACHE_CLIENT   - only SSL_connect()
  27 SSL_SESS_CACHE_SERVER   - only SSL_accept()
  28 SSL_SESS_NO_CACHE_BOTH  - Either SSL_accept() or SSL_connect().
  29 If SSL_SESS_CACHE_NO_AUTO_CLEAR is set, old timed out sessions are
  30 not automatically removed each 255, SSL_connect()s or SSL_accept()s.
  31
  32 By default, apon every 255 successful SSL_connect() or SSL_accept()s,
  33 the cache is flush.  Please note that this could be expensive on
  34 a heavily loaded SSL server, in which case, turn this off and
  35 clear the cache of old entries 'manually' (with one of the functions
  36 listed below) every few hours.  Perhaps I should up this number, it is hard
  37 to say.  Remember, the '255' new calls is just a mechanims to get called
  38 every now and then, in theory at most 255 new session-id's will have been
  39 added but if 100 are added every minute, you would still have
  40 500 in the cache before any would start being flushed (assuming a 3 minute
  41 timeout)..
  42
  43 int SSL_CTX_sess_hits(SSL_CTX *ctx);
  44 int SSL_CTX_sess_misses(SSL_CTX *ctx);
  45 int SSL_CTX_sess_timeouts(SSL_CTX *ctx);
  46 These 3 functions return statistics about the SSL_CTX.  These 3 are the
  47 number of session id reuses.  hits is the number of reuses, misses are the
  48 number of lookups that failed, and timeouts is the number of cached
  49 entries ignored because they had timeouted.
  50
  51 ctx->new_session_cb is a function pointer to a function of type
  52 int new_session_callback(SSL *ssl,SSL_SESSION *new);
  53 This function, if set in the SSL_CTX structure is called whenever a new
  54 SSL_SESSION is added to the cache.  If the callback returns non-zero, it
  55 means that the application will have to do a SSL_SESSION_free()
  56 on the structure (this is
  57 to do with the cache keeping the reference counts correct, without the
  58 application needing to know about it.
  59 The 'active' parameter is the current SSL session for which this connection
  60 was created.
  61
  62 void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,int (*cb)());
  63 to set the callback,
  64 int (*cb)() SSL_CTX_sess_get_new_cb(SSL_CTX *ctx)
  65 to get the callback.
  66
  67 If the 'get session' callback is set, when a session id is looked up and
  68 it is not in the session-id cache, this callback is called.  The callback is
  69 of the form
  70 SSL_SESSION *get_session_callback(unsigned char *sess_id,int sess_id_len,
  71         int *copy);
  72
  73 The get_session_callback is intended to return null if no session id is found.
  74 The reference count on the SSL_SESSION in incremented by the SSL library,
  75 if copy is 1.  Otherwise, the reference count is not modified.
  76
  77 void SSL_CTX_sess_set_get_cb(ctx,cb) sets the callback and
  78 int (*cb)()SSL_CTX_sess_get_get_cb(ctx) returns the callback.
  79
  80 These callbacks are basically indended to be used by processes to
  81 send their session-id's to other processes.  I currently have not implemented
  82 non-blocking semantics for these callbacks, it is upto the appication
  83 to make the callbacks effiecent if they require blocking (perhaps
  84 by 'saving' them and then 'posting them' when control returns from
  85 the SSL_accept().
  86
  87 LHASH *SSL_CTX_sessions(SSL_CTX *ctx)
  88 This returns the session cache.  The lhash strucutre can be accessed for
  89 statistics about the cache.
  90
  91 void lh_stats(LHASH *lh, FILE *out);
  92 void lh_node_stats(LHASH *lh, FILE *out);
  93 void lh_node_usage_stats(LHASH *lh, FILE *out);
  94
  95 can be used to print details about it's activity and current state.
  96 You can also delve directly into the lhash structure for 14 different
  97 counters that are kept against the structure.  When I wrote the lhash library,
  98 I was interested in gathering statistics :-).
  99 Have a read of doc/lhash.doc in the SSLeay distribution area for more details
 100 on the lhash library.
 101
 102 Now as mentioned ealier, when a SSL is created, it needs a SSL_CTX.
 103 SSL *   SSL_new(SSL_CTX *);
 104
 105 This stores a session.  A session is secret information shared between 2
 106 SSL contexts.  It will only be created if both ends of the connection have
 107 authenticated their peer to their satisfaction.  It basically contains
 108 the information required to use a particular secret key cipher.
 109
 110 To retrieve the SSL_CTX being used by a SSL,
 111 SSL_CTX *SSL_get_SSL_CTX(SSL *s);
 112
 113 Now when a SSL session is established between to programs, the 'session'
 114 information that is cached in the SSL_CTX can me manipulated by the
 115 following functions.
 116 int SSL_set_session(SSL *s, SSL_SESSION *session);
 117 This will set the SSL_SESSION to use for the next SSL_connect().  If you use
 118 this function on an already 'open' established SSL connection, 'bad things
 119 will happen'.  This function is meaning-less when used on a ssl strucutre
 120 that is just about to be used in a SSL_accept() call since the
 121 SSL_accept() will either create a new session or retrieve one from the
 122 cache.
 123
 124 SSL_SESSION *SSL_get_session(SSL *s);
 125 This will return the SSL_SESSION for the current SSL, NULL if there is
 126 no session associated with the SSL structure.
 127
 128 The SSL sessions are kept in the SSL_CTX in a hash table, to remove a
 129 session
 130 void    SSL_CTX_remove_session(SSL_CTX *,SSL_SESSION *c);
 131 and to add one
 132 int    SSL_CTX_add_session(SSL_CTX *s, SSL_SESSION *c);
 133 SSL_CTX_add_session() returns 1 if the session was already in the cache (so it
 134 was not added).
 135 Whenever a new session is created via SSL_connect()/SSL_accept(),
 136 they are automatically added to the cache, depending on the session_cache_mode
 137 settings.  SSL_set_session()
 138 does not add it to the cache.  Just call SSL_CTX_add_session() if you do want the
 139 session added.  For a 'client' this would not normally be the case.
 140 SSL_CTX_add_session() is not normally ever used, except for doing 'evil' things
 141 which the next 2 funtions help you do.
 142
 143 int     i2d_SSL_SESSION(SSL_SESSION *in,unsigned char **pp);
 144 SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a,unsigned char **pp,long length);
 145 These 2 functions are in the standard ASN1 library form and can be used to
 146 load and save to a byte format, the SSL_SESSION structure.
 147 With these functions, you can save and read these structures to a files or
 148 arbitary byte string.
 149 The PEM_write_SSL_SESSION(fp,x) and PEM_read_SSL_SESSION(fp,x,cb) will
 150 write to a file pointer in base64 encoding.
 151
 152 What you can do with this, is pass session information between separate
 153 processes.  Please note, that you will probably also need to modify the
 154 timeout information on the SSL_SESSIONs.
 155
 156 long SSL_get_time(SSL_SESSION *s)
 157 will return the 'time' that the session
 158 was loaded.  The timeout is relative to this time.  This information is
 159 saved when the SSL_SESSION is converted to binarary but it is stored
 160 in as a unix long, which is rather OS dependant, but easy to convert back.
 161
 162 long SSL_set_time(SSL_SESSION *s,long t) will set the above mentioned time.
 163 The time value is just the value returned from time(3), and should really
 164 be defined by be to be time_t.
 165
 166 long SSL_get_timeout(SSL_SESSION *s);
 167 long SSL_set_timeout(SSL_SESSION *s,long t);
 168 These 2 retrieve and set the timeout which is just a number of secconds
 169 from the 'SSL_get_time()' value.  When this time period has elapesed,
 170 the session will no longer be in the cache (well it will actually be removed
 171 the next time it is attempted to be retrieved, so you could 'bump'
 172 the timeout so it remains valid).
 173 The 'time' and 'timeout' are set on a session when it is created, not reset
 174 each time it is reused.  If you did wish to 'bump it', just after establishing
 175 a connection, do a
 176 SSL_set_time(ssl,time(NULL));
 177
 178 You can also use
 179 SSL_CTX_set_timeout(SSL_CTX *ctx,unsigned long t) and
 180 SSL_CTX_get_timeout(SSL_CTX *ctx) to manipulate the default timeouts for
 181 all SSL connections created against a SSL_CTX.  If you set a timeout in
 182 an SSL_CTX, all new SSL's created will inherit the timeout.  It can be over
 183 written by the SSL_set_timeout(SSL *s,unsigned long t) function call.
 184 If you 'set' the timeout back to 0, the system default will be used.
 185
 186 SSL_SESSION *SSL_SESSION_new();
 187 void SSL_SESSION_free(SSL_SESSION *ses);
 188 These 2 functions are used to create and dispose of SSL_SESSION functions.
 189 You should not ever normally need to use them unless you are using
 190 i2d_SSL_SESSION() and/or d2i_SSL_SESSION().  If you 'load' a SSL_SESSION
 191 via d2i_SSL_SESSION(), you will need to SSL_SESSION_free() it.
 192 Both SSL_set_session() and SSL_CTX_add_session() will 'take copies' of the
 193 structure (via reference counts) when it is passed to them.
 194
 195 SSL_CTX_flush_sessions(ctx,time);
 196 The first function will clear all sessions from the cache, which have expired
 197 relative to 'time' (which could just be time(NULL)).
 198
 199 SSL_CTX_flush_sessions(ctx,0);
 200 This is a special case that clears everything.
 201
 202 As a final comment, a 'session' is not enough to establish a new
 203 connection.  If a session has timed out, a certificate and private key
 204 need to have been associated with the SSL structure.
 205 SSL_copy_session_id(SSL *to,SSL *from); will copy not only the session
 206 strucutre but also the private key and certificate associated with
 207 'from'.
 208
 209 EXAMPLES.
 210
 211 So lets play at being a wierd SSL server.
 212
 213 /* setup a context */
 214 ctx=SSL_CTX_new();
 215
 216 /* Lets load some session from binary into the cache, why one would do
 217  * this is not toally clear, but passing between programs does make sense
 218  * Perhaps you are using 4096 bit keys and are happy to keep them
 219  * valid for a week, to avoid the RSA overhead of 15 seconds, I'm not toally
 220  * sure, perhaps this is a process called from an SSL inetd and this is being
 221  * passed to the application. */
 222 session=d2i_SSL_SESSION(....)
 223 SSL_CTX_add_session(ctx,session);
 224
 225 /* Lets even add a session from a file */
 226 session=PEM_read_SSL_SESSION(....)
 227 SSL_CTX_add_session(ctx,session);
 228
 229 /* create a new SSL structure */
 230 ssl=SSL_new(ctx);
 231
 232 /* At this point we want to be able to 'create' new session if
 233  * required, so we need a certificate and RSAkey. */
 234 SSL_use_RSAPrivateKey_file(ssl,...)
 235 SSL_use_certificate_file(ssl,...)
 236
 237 /* Now since we are a server, it make little sence to load a session against
 238  * the ssl strucutre since a SSL_accept() will either create a new session or
 239  * grab an existing one from the cache. */
 240
 241 /* grab a socket descriptor */
 242 fd=accept(...);
 243
 244 /* associated it with the ssl strucutre */
 245 SSL_set_fd(ssl,fd);
 246
 247 SSL_accept(ssl); /* 'do' SSL using out cert and RSA key */
 248
 249 /* Lets print out the session details or lets save it to a file,
 250  * perhaps with a secret key cipher, so that we can pass it to the FBI
 251  * when they want to decode the session :-).  While we have RSA
 252  * this does not matter much but when I do SSLv3, this will allow a mechanism
 253  * for the server/client to record the information needed to decode
 254  * the traffic that went over the wire, even when using Diffie-Hellman */
 255 PEM_write_SSL_SESSION(SSL_get_session(ssl),stdout,....)
 256
 257 Lets 'connect' back to the caller using the same session id.
 258
 259 ssl2=SSL_new(ctx);
 260 fd2=connect(them);
 261 SSL_set_fd(ssl2,fd2);
 262 SSL_set_session(ssl2,SSL_get_session(ssl));
 263 SSL_connect(ssl2);
 264
 265 /* what the hell, lets accept no more connections using this session */
 266 SSL_CTX_remove_session(SSL_get_SSL_CTX(ssl),SSL_get_session(ssl));
 267
 268 /* we could have just as easily used ssl2 since they both are using the
 269  * same session.
 270  * You will note that both ssl and ssl2 are still using the session, and
 271  * the SSL_SESSION structure will be free()ed when both ssl and ssl2
 272  * finish using the session.  Also note that you could continue to initiate
 273  * connections using this session by doing SSL_get_session(ssl) to get the
 274  * existing session, but SSL_accept() will not be able to find it to
 275  * use for incoming connections.
 276  * Of corse, the session will timeout at the far end and it will no
 277  * longer be accepted after a while.  The time and timeout are ignored except
 278  * by SSL_accept(). */
 279
 280 /* Since we have had our server running for 10 weeks, and memory is getting
 281  * short, perhaps we should clear the session cache to remove those
 282  * 100000 session entries that have expired.  Some may consider this
 283  * a memory leak :-) */
 284
 285 SSL_CTX_flush_sessions(ctx,time(NULL));
 286
 287 /* Ok, after a bit more time we wish to flush all sessions from the cache
 288  * so that all new connections will be authenticated and incure the
 289  * public key operation overhead */
 290
 291 SSL_CTX_flush_sessions(ctx,0);
 292
 293 /* As a final note, to copy everything to do with a SSL, use */
 294 SSL_copy_session_id(SSL *to,SSL *from);
 295 /* as this also copies the certificate and RSA key so new session can
 296  * be established using the same details */
 297