]>
Commit | Line | Data |
---|---|---|
8cbceba6 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, | |
1bc74519 | 12 | int (*new_session_cb)(SSL *, SSL_SESSION *)); |
8cbceba6 | 13 | void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, |
e9b77246 BB |
14 | void (*remove_session_cb)(SSL_CTX *ctx, |
15 | SSL_SESSION *)); | |
8cbceba6 | 16 | void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, |
e9b77246 BB |
17 | SSL_SESSION (*get_session_cb)(SSL *, |
18 | const unsigned char *, | |
19 | int, int *)); | |
20 | ||
21 | int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, | |
22 | SSL_SESSION *sess); | |
23 | void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, | |
24 | SSL_SESSION *sess); | |
25 | SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, | |
26 | const unsigned char *data, | |
27 | int len, int *copy); | |
8cbceba6 LJ |
28 | |
29 | =head1 DESCRIPTION | |
30 | ||
31 | SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically | |
32 | called whenever a new session was negotiated. | |
33 | ||
34 | SSL_CTX_sess_set_remove_cb() sets the callback function, which is | |
35 | automatically called whenever a session is removed by the SSL engine, | |
36 | because it is considered faulty or the session has become obsolete because | |
37 | of exceeding the timeout value. | |
38 | ||
39 | SSL_CTX_sess_set_get_cb() sets the callback function which is called, | |
40 | whenever a SSL/TLS client proposed to resume a session but the session | |
41 | could not be found in the internal session cache (see | |
9b86974e | 42 | L<SSL_CTX_set_session_cache_mode(3)>). |
8cbceba6 LJ |
43 | (SSL/TLS server only.) |
44 | ||
45 | SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and | |
6e501c47 P |
46 | SSL_CTX_sess_get_get_cb() retrieve the function pointers set by the |
47 | corresponding set callback functions. If a callback function has not been | |
48 | set, the NULL pointer is returned. | |
8cbceba6 LJ |
49 | |
50 | =head1 NOTES | |
51 | ||
52 | In order to allow external session caching, synchronization with the internal | |
53 | session cache is realized via callback functions. Inside these callback | |
54 | functions, session can be saved to disk or put into a database using the | |
9b86974e | 55 | L<d2i_SSL_SESSION(3)> interface. |
8cbceba6 LJ |
56 | |
57 | The new_session_cb() is called, whenever a new session has been negotiated | |
58 | and session caching is enabled (see | |
9b86974e | 59 | L<SSL_CTX_set_session_cache_mode(3)>). |
8cbceba6 | 60 | The new_session_cb() is passed the B<ssl> connection and the ssl session |
0bc6597d | 61 | B<sess>. If the callback returns B<0>, the session will be immediately |
5b3e5f00 | 62 | removed again. Note that in TLSv1.3, sessions are established after the main |
6ff71494 MC |
63 | handshake has completed. The server decides when to send the client the session |
64 | information and this may occur some time after the end of the handshake (or not | |
65 | at all). This means that applications should expect the new_session_cb() | |
66 | function to be invoked during the handshake (for <= TLSv1.2) or after the | |
67 | handshake (for TLSv1.3). It is also possible in TLSv1.3 for multiple sessions to | |
68 | be established with a single connection. In these case the new_session_cb() | |
69 | function will be invoked multiple times. | |
70 | ||
71 | In TLSv1.3 it is recommended that each SSL_SESSION object is only used for | |
b8964668 MC |
72 | resumption once. One way of enforcing that is for applications to call |
73 | L<SSL_CTX_remove_session(3)> after a session has been used. | |
8cbceba6 LJ |
74 | |
75 | The remove_session_cb() is called, whenever the SSL engine removes a session | |
423b1a84 LJ |
76 | from the internal cache. This happens when the session is removed because |
77 | it is expired or when a connection was not shutdown cleanly. It also happens | |
78 | for all sessions in the internal session cache when | |
9b86974e | 79 | L<SSL_CTX_free(3)> is called. The remove_session_cb() is passed |
423b1a84 | 80 | the B<ctx> and the ssl session B<sess>. It does not provide any feedback. |
8cbceba6 LJ |
81 | |
82 | The get_session_cb() is only called on SSL/TLS servers with the session id | |
83 | proposed by the client. The get_session_cb() is always called, also when | |
84 | session caching was disabled. The get_session_cb() is passed the | |
85 | B<ssl> connection, the session id of length B<length> at the memory location | |
86 | B<data>. With the parameter B<copy> the callback can require the | |
56fa8e69 LJ |
87 | SSL engine to increment the reference count of the SSL_SESSION object, |
88 | Normally the reference count is not incremented and therefore the | |
89 | session must not be explicitly freed with | |
9b86974e | 90 | L<SSL_SESSION_free(3)>. |
8cbceba6 | 91 | |
1f13ad31 PY |
92 | =head1 RETURN VALUES |
93 | ||
94 | SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb() and SSL_CTX_sess_get_get_cb() | |
95 | return different callback function pointers respectively. | |
96 | ||
8cbceba6 LJ |
97 | =head1 SEE ALSO |
98 | ||
b97fdb57 | 99 | L<ssl(7)>, L<d2i_SSL_SESSION(3)>, |
9b86974e RS |
100 | L<SSL_CTX_set_session_cache_mode(3)>, |
101 | L<SSL_CTX_flush_sessions(3)>, | |
102 | L<SSL_SESSION_free(3)>, | |
103 | L<SSL_CTX_free(3)> | |
8cbceba6 | 104 | |
e2f92610 RS |
105 | =head1 COPYRIGHT |
106 | ||
61f805c1 | 107 | Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 108 | |
4746f25a | 109 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
110 | this file except in compliance with the License. You can obtain a copy |
111 | in the file LICENSE in the source distribution or at | |
112 | L<https://www.openssl.org/source/license.html>. | |
113 | ||
114 | =cut |