| blob | bbc0102ad8f41bb679385ba4dd8c59ad4445a057 |
1 .\" $OpenBSD: SSL_CTX_set_session_id_context.3,v 1.5 2018/03/21 17:58:58 schwarze Exp $
2 .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3 .\"
4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
5 .\" Copyright (c) 2001, 2004 The OpenSSL Project. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\"
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
17 .\" distribution.
18 .\"
19 .\" 3. All advertising materials mentioning features or use of this
20 .\" software must display the following acknowledgment:
21 .\" "This product includes software developed by the OpenSSL Project
22 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23 .\"
24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25 .\" endorse or promote products derived from this software without
26 .\" prior written permission. For written permission, please contact
27 .\" openssl-core@openssl.org.
28 .\"
29 .\" 5. Products derived from this software may not be called "OpenSSL"
30 .\" nor may "OpenSSL" appear in their names without prior written
31 .\" permission of the OpenSSL Project.
32 .\"
33 .\" 6. Redistributions of any form whatsoever must retain the following
34 .\" acknowledgment:
35 .\" "This product includes software developed by the OpenSSL Project
36 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37 .\"
38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
50 .\"
51 .Dd $Mdocdate: March 21 2018 $
52 .Dt SSL_CTX_SET_SESSION_ID_CONTEXT 3
53 .Os
54 .Sh NAME
55 .Nm SSL_CTX_set_session_id_context ,
56 .Nm SSL_set_session_id_context
57 .Nd set context within which session can be reused (server side only)
58 .Sh SYNOPSIS
59 .In openssl/ssl.h
60 .Ft int
61 .Fo SSL_CTX_set_session_id_context
62 .Fa "SSL_CTX *ctx"
63 .Fa "const unsigned char *sid_ctx"
64 .Fa "unsigned int sid_ctx_len"
65 .Fc
66 .Ft int
67 .Fo SSL_set_session_id_context
68 .Fa "SSL *ssl"
69 .Fa "const unsigned char *sid_ctx"
70 .Fa "unsigned int sid_ctx_len"
71 .Fc
72 .Sh DESCRIPTION
73 .Fn SSL_CTX_set_session_id_context
74 sets the context
75 .Fa sid_ctx
76 of length
77 .Fa sid_ctx_len
78 within which a session can be reused for the
79 .Fa ctx
80 object.
81 .Pp
82 .Fn SSL_set_session_id_context
83 sets the context
84 .Fa sid_ctx
85 of length
86 .Fa sid_ctx_len
87 within which a session can be reused for the
88 .Fa ssl
89 object.
90 .Sh NOTES
91 Sessions are generated within a certain context.
92 When exporting/importing sessions with
93 .Xr i2d_SSL_SESSION 3
94 and
95 .Xr d2i_SSL_SESSION 3 ,
96 it would be possible to re-import a session generated from another context
97 (e.g., another application), which might lead to malfunctions.
98 Therefore each application must set its own session id context
99 .Fa sid_ctx
100 which is used to distinguish the contexts and is stored in exported sessions.
101 The
102 .Fa sid_ctx
103 can be any kind of binary data with a given length; it is therefore possible
104 to use, for instance, the name of the application, the hostname, the service
105 name...
106 .Pp
107 The session id context becomes part of the session.
108 The session id context is set by the SSL/TLS server.
109 The
110 .Fn SSL_CTX_set_session_id_context
111 and
112 .Fn SSL_set_session_id_context
113 functions are therefore only useful on the server side.
114 .Pp
115 OpenSSL clients will check the session id context returned by the server when
116 reusing a session.
117 .Pp
118 The maximum length of the
119 .Fa sid_ctx
120 is limited to
121 .Dv SSL_MAX_SSL_SESSION_ID_LENGTH .
122 .Sh WARNINGS
123 If the session id context is not set on an SSL/TLS server and client
124 certificates are used, stored sessions will not be reused but a fatal error
125 will be flagged and the handshake will fail.
126 .Pp
127 If a server returns a different session id context to an OpenSSL client
128 when reusing a session, an error will be flagged and the handshake will
129 fail.
130 OpenSSL servers will always return the correct session id context,
131 as an OpenSSL server checks the session id context itself before reusing
132 a session as described above.
133 .Sh RETURN VALUES
134 .Fn SSL_CTX_set_session_id_context
135 and
136 .Fn SSL_set_session_id_context
137 return the following values:
138 .Bl -tag -width Ds
139 .It 0
140 The length
141 .Fa sid_ctx_len
142 of the session id context
143 .Fa sid_ctx
144 exceeded
145 the maximum allowed length of
146 .Dv SSL_MAX_SSL_SESSION_ID_LENGTH .
147 The error is logged to the error stack.
148 .It 1
149 The operation succeeded.
150 .El
151 .Sh SEE ALSO
152 .Xr ssl 3 ,
153 .Xr SSL_SESSION_set1_id_context 3
154 .Sh HISTORY
155 .Fn SSL_set_session_id_context
156 first appeared in OpenSSL 0.9.2b.
157 .Fn SSL_CTX_set_session_id_context
158 first appeared in OpenSSL 0.9.3.
159 Both functions have been available since
160 .Ox 2.6 .