]>
Commit | Line | Data |
---|---|---|
cd6aa710 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only) | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx, | |
12 | unsigned int sid_ctx_len); | |
13 | int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx, | |
14 | unsigned int sid_ctx_len); | |
15 | ||
16 | =head1 DESCRIPTION | |
17 | ||
18 | SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length | |
19 | B<sid_ctx_len> within which a session can be reused for the B<ctx> object. | |
20 | ||
21 | SSL_set_session_id_context() sets the context B<sid_ctx> of length | |
22 | B<sid_ctx_len> within which a session can be reused for the B<ssl> object. | |
23 | ||
24 | =head1 NOTES | |
25 | ||
26 | Sessions are generated within a certain context. When exporting/importing | |
27 | sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible, | |
28 | to re-import a session generated from another context (e.g. another | |
29 | application), which might lead to malfunctions. Therefore each application | |
30 | must set its own session id context B<sid_ctx> which is used to distinguish | |
31 | the contexts and is stored in exported sessions. The B<sid_ctx> can be | |
32 | any kind of binary data with a given length, it is therefore possible | |
33 | to use e.g. the name of the application and/or the hostname and/or service | |
34 | name ... | |
35 | ||
36 | The session id context becomes part of the session. The session id context | |
37 | is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and | |
38 | SSL_set_session_id_context() functions are therefore only useful on the | |
39 | server side. | |
40 | ||
41 | OpenSSL clients will check the session id context returned by the server | |
42 | when reusing a session. | |
43 | ||
44 | The maximum length of the B<sid_ctx> is limited to | |
45 | B<SSL_MAX_SSL_SESSION_ID_LENGTH>. | |
46 | ||
47 | =head1 WARNINGS | |
48 | ||
49 | If the session id context is not set on an SSL/TLS server, stored sessions | |
50 | will not be reused but a fatal error will be flagged and the handshake | |
51 | will fail. | |
52 | ||
53 | If a server returns a different session id context to an OpenSSL client | |
54 | when reusing a session, an error will be flagged and the handshake will | |
55 | fail. OpenSSL servers will always return the correct session id context, | |
56 | as an OpenSSL server checks the session id context itself before reusing | |
57 | a session as described above. | |
58 | ||
59 | =head1 RETURN VALUES | |
60 | ||
61 | SSL_CTX_set_session_id_context() and SSL_set_session_id_context() | |
62 | return the following values: | |
63 | ||
64 | =over 4 | |
65 | ||
66 | =item 0 | |
67 | ||
68 | The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded | |
69 | the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error | |
70 | is logged to the error stack. | |
71 | ||
72 | =item 1 | |
73 | ||
74 | The operation succeeded. | |
75 | ||
76 | =back | |
77 | ||
78 | =head1 SEE ALSO | |
79 | ||
80 | L<ssl(3)|ssl(3)> | |
81 | ||
82 | =cut |