Import of old SSLeay release: SSLeay 0.8.1b
[openssl.git] / 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