1.\"
2.\"	$OpenBSD: SSL_CTX_set_session_id_context.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $
3.\"
4.Dd $Mdocdate: November 5 2016 $
5.Dt SSL_CTX_SET_SESSION_ID_CONTEXT 3
6.Os
7.Sh NAME
8.Nm SSL_CTX_set_session_id_context ,
9.Nm SSL_set_session_id_context
10.Nd set context within which session can be reused (server side only)
11.Sh SYNOPSIS
12.In openssl/ssl.h
13.Ft int
14.Fo SSL_CTX_set_session_id_context
15.Fa "SSL_CTX *ctx"
16.Fa "const unsigned char *sid_ctx"
17.Fa "unsigned int sid_ctx_len"
18.Fc
19.Ft int
20.Fo SSL_set_session_id_context
21.Fa "SSL *ssl"
22.Fa "const unsigned char *sid_ctx"
23.Fa "unsigned int sid_ctx_len"
24.Fc
25.Sh DESCRIPTION
26.Fn SSL_CTX_set_session_id_context
27sets the context
28.Fa sid_ctx
29of length
30.Fa sid_ctx_len
31within which a session can be reused for the
32.Fa ctx
33object.
34.Pp
35.Fn SSL_set_session_id_context
36sets the context
37.Fa sid_ctx
38of length
39.Fa sid_ctx_len
40within which a session can be reused for the
41.Fa ssl
42object.
43.Sh NOTES
44Sessions are generated within a certain context.
45When exporting/importing sessions with
46.Xr i2d_SSL_SESSION 3
47and
48.Xr d2i_SSL_SESSION 3 ,
49it would be possible to re-import a session generated from another context
50(e.g., another application), which might lead to malfunctions.
51Therefore each application must set its own session id context
52.Fa sid_ctx
53which is used to distinguish the contexts and is stored in exported sessions.
54The
55.Fa sid_ctx
56can be any kind of binary data with a given length; it is therefore possible
57to use, for instance, the name of the application, the hostname, the service
58name...
59.Pp
60The session id context becomes part of the session.
61The session id context is set by the SSL/TLS server.
62The
63.Fn SSL_CTX_set_session_id_context
64and
65.Fn SSL_set_session_id_context
66functions are therefore only useful on the server side.
67.Pp
68OpenSSL clients will check the session id context returned by the server when
69reusing a session.
70.Pp
71The maximum length of the
72.Fa sid_ctx
73is limited to
74.Dv SSL_MAX_SSL_SESSION_ID_LENGTH .
75.Sh WARNINGS
76If the session id context is not set on an SSL/TLS server and client
77certificates are used, stored sessions will not be reused but a fatal error
78will be flagged and the handshake will fail.
79.Pp
80If a server returns a different session id context to an OpenSSL client
81when reusing a session, an error will be flagged and the handshake will
82fail.
83OpenSSL servers will always return the correct session id context,
84as an OpenSSL server checks the session id context itself before reusing
85a session as described above.
86.Sh RETURN VALUES
87.Fn SSL_CTX_set_session_id_context
88and
89.Fn SSL_set_session_id_context
90return the following values:
91.Bl -tag -width Ds
92.It 0
93The length
94.Fa sid_ctx_len
95of the session id context
96.Fa sid_ctx
97exceeded
98the maximum allowed length of
99.Dv SSL_MAX_SSL_SESSION_ID_LENGTH .
100The error is logged to the error stack.
101.It 1
102The operation succeeded.
103.El
104.Sh SEE ALSO
105.Xr ssl 3
106