Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_session_id_context.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET_SESSION_ID_CONTEXT 3SSL"
58 .TH SSL_CTX_SET_SESSION_ID_CONTEXT 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_CTX_set_session_id_context, SSL_set_session_id_context \- set context within which session can be reused (server side only)
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ssl.h>
69 \&
70 \& int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx,
71 \& unsigned int sid_ctx_len);
72 \& int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx,
73 \& unsigned int sid_ctx_len);
74 .Ve
75 .SH DESCRIPTION
76 .IX Header "DESCRIPTION"
77 \&\fBSSL_CTX_set_session_id_context()\fR sets the context \fBsid_ctx\fR of length
78 \&\fBsid_ctx_len\fR within which a session can be reused for the \fBctx\fR object.
79 .PP
80 \&\fBSSL_set_session_id_context()\fR sets the context \fBsid_ctx\fR of length
81 \&\fBsid_ctx_len\fR within which a session can be reused for the \fBssl\fR object.
82 .SH NOTES
83 .IX Header "NOTES"
84 Sessions are generated within a certain context. When exporting/importing
85 sessions with \fBi2d_SSL_SESSION\fR/\fBd2i_SSL_SESSION\fR it would be possible,
86 to re-import a session generated from another context (e.g. another
87 application), which might lead to malfunctions. Therefore, each application
88 must set its own session id context \fBsid_ctx\fR which is used to distinguish
89 the contexts and is stored in exported sessions. The \fBsid_ctx\fR can be
90 any kind of binary data with a given length, it is therefore possible
91 to use e.g. the name of the application and/or the hostname and/or service
92 name ...
93 .PP
94 The session id context becomes part of the session. The session id context
95 is set by the SSL/TLS server. The \fBSSL_CTX_set_session_id_context()\fR and
96 \&\fBSSL_set_session_id_context()\fR functions are therefore only useful on the
97 server side.
98 .PP
99 OpenSSL clients will check the session id context returned by the server
100 when reusing a session.
101 .PP
102 The maximum length of the \fBsid_ctx\fR is limited to
103 \&\fBSSL_MAX_SID_CTX_LENGTH\fR.
104 .SH WARNINGS
105 .IX Header "WARNINGS"
106 If the session id context is not set on an SSL/TLS server and client
107 certificates are used, stored sessions
108 will not be reused but a fatal error will be flagged and the handshake
109 will fail.
110 .PP
111 If a server returns a different session id context to an OpenSSL client
112 when reusing a session, an error will be flagged and the handshake will
113 fail. OpenSSL servers will always return the correct session id context,
114 as an OpenSSL server checks the session id context itself before reusing
115 a session as described above.
116 .SH "RETURN VALUES"
117 .IX Header "RETURN VALUES"
118 \&\fBSSL_CTX_set_session_id_context()\fR and \fBSSL_set_session_id_context()\fR
119 return the following values:
120 .IP 0 4
121 The length \fBsid_ctx_len\fR of the session id context \fBsid_ctx\fR exceeded
122 the maximum allowed length of \fBSSL_MAX_SID_CTX_LENGTH\fR. The error
123 is logged to the error stack.
124 .IP 1 4
125 .IX Item "1"
126 The operation succeeded.
127 .SH "SEE ALSO"
128 .IX Header "SEE ALSO"
129 \&\fBssl\fR\|(7)
130 .SH COPYRIGHT
131 .IX Header "COPYRIGHT"
132 Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved.
133 .PP
134 Licensed under the Apache License 2.0 (the "License"). You may not use
135 this file except in compliance with the License. You can obtain a copy
136 in the file LICENSE in the source distribution or at
137 <https://www.openssl.org/source/license.html>.