]>
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 | ||
9f6ea716 LJ |
49 | If the session id context is not set on an SSL/TLS server and client |
50 | certificates are used, stored sessions | |
cd6aa710 LJ |
51 | will not be reused but a fatal error will be flagged and the handshake |
52 | will fail. | |
53 | ||
54 | If a server returns a different session id context to an OpenSSL client | |
55 | when reusing a session, an error will be flagged and the handshake will | |
56 | fail. OpenSSL servers will always return the correct session id context, | |
57 | as an OpenSSL server checks the session id context itself before reusing | |
58 | a session as described above. | |
59 | ||
60 | =head1 RETURN VALUES | |
61 | ||
62 | SSL_CTX_set_session_id_context() and SSL_set_session_id_context() | |
63 | return the following values: | |
64 | ||
65 | =over 4 | |
66 | ||
c8919dde | 67 | =item Z<>0 |
cd6aa710 LJ |
68 | |
69 | The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded | |
70 | the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error | |
71 | is logged to the error stack. | |
72 | ||
c8919dde | 73 | =item Z<>1 |
cd6aa710 LJ |
74 | |
75 | The operation succeeded. | |
76 | ||
77 | =back | |
78 | ||
79 | =head1 SEE ALSO | |
80 | ||
b97fdb57 | 81 | L<ssl(7)> |
cd6aa710 | 82 | |
e2f92610 RS |
83 | =head1 COPYRIGHT |
84 | ||
85 | Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. | |
86 | ||
4746f25a | 87 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
88 | this file except in compliance with the License. You can obtain a copy |
89 | in the file LICENSE in the source distribution or at | |
90 | L<https://www.openssl.org/source/license.html>. | |
91 | ||
92 | =cut |