]>
Commit | Line | Data |
---|---|---|
3cdc8ad0 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, SSL_has_matching_session_id - manipulate generation of SSL session IDs (server only) | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id, | |
12 | unsigned int *id_len); | |
13 | ||
14 | int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb); | |
15 | int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb); | |
16 | int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id, | |
17 | unsigned int id_len); | |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
21 | SSL_CTX_set_generate_session_id() sets the callback function for generating | |
22 | new session ids for SSL/TLS sessions for B<ctx> to be B<cb>. | |
23 | ||
24 | SSL_set_generate_session_id() sets the callback function for generating | |
25 | new session ids for SSL/TLS sessions for B<ssl> to be B<cb>. | |
26 | ||
27 | SSL_has_matching_session_id() checks, whether a session with id B<id> | |
28 | (of length B<id_len>) is already contained in the internal session cache | |
29 | of the parent context of B<ssl>. | |
30 | ||
31 | =head1 NOTES | |
32 | ||
33 | When a new session is established between client and server, the server | |
34 | generates a session id. The session id is an arbitrary sequence of bytes. | |
45f55f6a KR |
35 | The length of the session id is between 1 and 32 bytes. The session id is not |
36 | security critical but must be unique for the server. Additionally, the session id is | |
3cdc8ad0 LJ |
37 | transmitted in the clear when reusing the session so it must not contain |
38 | sensitive information. | |
39 | ||
40 | Without a callback being set, an OpenSSL server will generate a unique | |
41 | session id from pseudo random numbers of the maximum possible length. | |
42 | Using the callback function, the session id can be changed to contain | |
43 | additional information like e.g. a host id in order to improve load balancing | |
44 | or external caching techniques. | |
45 | ||
46 | The callback function receives a pointer to the memory location to put | |
47 | B<id> into and a pointer to the maximum allowed length B<id_len>. The | |
48 | buffer at location B<id> is only guaranteed to have the size B<id_len>. | |
49 | The callback is only allowed to generate a shorter id and reduce B<id_len>; | |
50 | the callback B<must never> increase B<id_len> or write to the location | |
51 | B<id> exceeding the given limit. | |
52 | ||
3cdc8ad0 LJ |
53 | The location B<id> is filled with 0x00 before the callback is called, so the |
54 | callback may only fill part of the possible length and leave B<id_len> | |
55 | untouched while maintaining reproducibility. | |
56 | ||
57 | Since the sessions must be distinguished, session ids must be unique. | |
58 | Without the callback a random number is used, so that the probability | |
45f55f6a KR |
59 | of generating the same session id is extremely small (2^256 for SSLv3/TLSv1). |
60 | In order to assure the uniqueness of the generated session id, the callback must call | |
3cdc8ad0 LJ |
61 | SSL_has_matching_session_id() and generate another id if a conflict occurs. |
62 | If an id conflict is not resolved, the handshake will fail. | |
63 | If the application codes e.g. a unique host id, a unique process number, and | |
64 | a unique sequence number into the session id, uniqueness could easily be | |
65 | achieved without randomness added (it should however be taken care that | |
66 | no confidential information is leaked this way). If the application can not | |
67 | guarantee uniqueness, it is recommended to use the maximum B<id_len> and | |
68 | fill in the bytes not used to code special information with random data | |
69 | to avoid collisions. | |
70 | ||
71 | SSL_has_matching_session_id() will only query the internal session cache, | |
72 | not the external one. Since the session id is generated before the | |
73 | handshake is completed, it is not immediately added to the cache. If | |
74 | another thread is using the same internal session cache, a race condition | |
75 | can occur in that another thread generates the same session id. | |
76 | Collisions can also occur when using an external session cache, since | |
77 | the external cache is not tested with SSL_has_matching_session_id() | |
78 | and the same race condition applies. | |
79 | ||
3cdc8ad0 LJ |
80 | The callback must return 0 if it cannot generate a session id for whatever |
81 | reason and return 1 on success. | |
82 | ||
83 | =head1 EXAMPLES | |
84 | ||
85 | The callback function listed will generate a session id with the | |
86 | server id given, and will fill the rest with pseudo random bytes: | |
87 | ||
88 | const char session_id_prefix = "www-18"; | |
89 | ||
90 | #define MAX_SESSION_ID_ATTEMPTS 10 | |
91 | static int generate_session_id(const SSL *ssl, unsigned char *id, | |
92 | unsigned int *id_len) | |
93 | { | |
94 | unsigned int count = 0; | |
3cdc8ad0 LJ |
95 | do { |
96 | RAND_pseudo_bytes(id, *id_len); | |
97 | /* Prefix the session_id with the required prefix. NB: If our | |
98 | * prefix is too long, clip it - but there will be worse effects | |
99 | * anyway, eg. the server could only possibly create 1 session | |
100 | * ID (ie. the prefix!) so all future session negotiations will | |
101 | * fail due to conflicts. */ | |
102 | memcpy(id, session_id_prefix, | |
103 | (strlen(session_id_prefix) < *id_len) ? | |
104 | strlen(session_id_prefix) : *id_len); | |
105 | } | |
106 | while(SSL_has_matching_session_id(ssl, id, *id_len) && | |
107 | (++count < MAX_SESSION_ID_ATTEMPTS)); | |
108 | if(count >= MAX_SESSION_ID_ATTEMPTS) | |
109 | return 0; | |
110 | return 1; | |
111 | } | |
112 | ||
113 | ||
114 | =head1 RETURN VALUES | |
115 | ||
116 | SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id() | |
117 | always return 1. | |
118 | ||
119 | SSL_has_matching_session_id() returns 1 if another session with the | |
120 | same id is already in the cache. | |
121 | ||
122 | =head1 SEE ALSO | |
123 | ||
9b86974e | 124 | L<ssl(3)>, L<SSL_get_version(3)> |
3cdc8ad0 LJ |
125 | |
126 | =head1 HISTORY | |
127 | ||
128 | SSL_CTX_set_generate_session_id(), SSL_set_generate_session_id() | |
129 | and SSL_has_matching_session_id() have been introduced in | |
130 | OpenSSL 0.9.7. | |
131 | ||
132 | =cut |