Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set1_cert_comp_preference.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_SET1_CERT_COMP_PREFERENCE 3SSL"
58 .TH SSL_CTX_SET1_CERT_COMP_PREFERENCE 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_set1_cert_comp_preference,
65 SSL_set1_cert_comp_preference,
66 SSL_CTX_compress_certs,
67 SSL_compress_certs,
68 SSL_CTX_get1_compressed_cert,
69 SSL_get1_compressed_cert,
70 SSL_CTX_set1_compressed_cert,
71 SSL_set1_compressed_cert \- Certificate compression functions
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 1
75 \& #include <openssl/ssl.h>
76 \&
77 \& int SSL_CTX_set1_cert_comp_preference(SSL_CTX *ctx, int *algs, size_t len);
78 \& int SSL_set1_cert_comp_preference(SSL *ssl, int *algs, size_t len);
79 \&
80 \& int SSL_CTX_compress_certs(SSL_CTX *ctx, int alg);
81 \& int SSL_compress_certs(SSL *ssl, int alg);
82 \&
83 \& size_t SSL_CTX_get1_compressed_cert(SSL_CTX *ctx, int alg, unsigned char **data,
84 \& size_t *orig_len);
85 \& size_t SSL_get1_compressed_cert(SSL *ssl, int alg, unsigned char **data,
86 \& size_t *orig_len);
87 \&
88 \& int SSL_CTX_set1_compressed_cert(SSL_CTX *ctx, int alg,
89 \& unsigned char *comp_data,
90 \& size_t comp_length, size_t orig_length);
91 \& int SSL_set1_compressed_cert(SSL *ssl, int alg, unsigned char *comp_data,
92 \& size_t comp_length, size_t orig_length);
93 .Ve
94 .SH DESCRIPTION
95 .IX Header "DESCRIPTION"
96 These functions control the certificate compression feature. Certificate
97 compression is only available for TLSv1.3 as defined in RFC8879.
98 .PP
99 \&\fBSSL_CTX_set1_cert_comp_preference()\fR and \fBSSL_set1_cert_comp_preference()\fR are used
100 to specify the preferred compression algorithms. The \fBalgs\fR argument is an array
101 of algorithms, and \fBlength\fR is number of elements in the \fBalgs\fR array. Only
102 those algorithms enabled in the library will be accepted in \fBalgs\fR, unknown
103 algorithms in \fBalgs\fR are ignored. On an error, the preference order is left
104 unmodified.
105 .PP
106 The following compression algorithms (\fBalg\fR arguments) may be used:
107 .IP \(bu 4
108 TLSEXT_comp_cert_brotli
109 .IP \(bu 4
110 TLSEXT_comp_cert_zlib
111 .IP \(bu 4
112 TLSEXT_comp_cert_zstd
113 .PP
114 The above is also the default preference order. If a preference order is not
115 specified, then the default preference order is sent to the peer and the
116 received peer's preference order will be used when compressing a certificate.
117 Otherwise, the configured preference order is sent to the peer and is used
118 to filter the peer's preference order.
119 .PP
120 \&\fBSSL_CTX_compress_certs()\fR and \fBSSL_compress_certs()\fR are used to pre-compress all
121 the configured certificates on an SSL_CTX/SSL object with algorithm \fBalg\fR. If
122 \&\fBalg\fR is 0, then the certificates are compressed with the algorithms specified
123 in the preference list. Calling these functions on a client SSL_CTX/SSL object
124 will result in an error, as only server certificates may be pre-compressed.
125 .PP
126 \&\fBSSL_CTX_get1_compressed_cert()\fR and \fBSSL_get1_compressed_cert()\fR are used to get
127 the pre-compressed certificate most recently set that may be stored for later
128 use. Calling these functions on a client SSL_CTX/SSL object will result in an
129 error, as only server certificates may be pre-compressed. The \fBdata\fR and
130 \&\fBorig_len\fR arguments are required.
131 .PP
132 The compressed certificate data may be passed to \fBSSL_CTX_set1_compressed_cert()\fR
133 or \fBSSL_set1_compressed_cert()\fR to provide a pre-compressed version of the
134 most recently set certificate. This pre-compressed certificate can only be used
135 by a server.
136 .SH NOTES
137 .IX Header "NOTES"
138 Each side of the connection sends their compression algorithm preference list
139 to their peer indicating compressed certificate support. The received preference
140 list is filtered by the configured preference list (i.e. the intersection is
141 saved). As the default list includes all the enabled algorithms, not specifying
142 a preference will allow any enabled algorithm by the peer. The filtered peer's
143 preference order is used to determine what algorithm to use when sending a
144 compressed certificate.
145 .PP
146 Only server certificates may be pre-compressed. Calling any of these functions
147 (except \fBSSL_CTX_set1_cert_comp_preference()\fR/\fBSSL_set1_cert_comp_preference()\fR)
148 on a client SSL_CTX/SSL object will return an error. Client certificates are
149 compressed on-demand as unique context data from the server is compressed along
150 with the certificate.
151 .PP
152 For \fBSSL_CTX_set1_cert_comp_preference()\fR and \fBSSL_set1_cert_comp_preference()\fR
153 the \fBlen\fR argument is the size of the \fBalgs\fR argument in bytes.
154 .PP
155 The compressed certificate returned by \fBSSL_CTX_get1_compressed_cert()\fR and
156 \&\fBSSL_get1_compressed_cert()\fR is the last certificate set on the SSL_CTX/SSL object.
157 The certificate is copied by the function and the caller must free \fB*data\fR via
158 \&\fBOPENSSL_free()\fR.
159 .PP
160 The compressed certificate data set by \fBSSL_CTX_set1_compressed_cert()\fR and
161 \&\fBSSL_set1_compressed_cert()\fR is copied into the SSL_CTX/SSL object.
162 .PP
163 \&\fBSSL_CTX_compress_certs()\fR and \fBSSL_compress_certs()\fR return an error under the
164 following conditions:
165 .IP \(bu 4
166 If no certificates have been configured.
167 .IP \(bu 4
168 If the specified algorithm \fBalg\fR is not enabled.
169 .IP \(bu 4
170 If \fBalg\fR is 0 and no compression algorithms are enabled.
171 .PP
172 Sending compressed certificates may be disabled on a connection via the
173 SSL_OP_NO_TX_CERTIFICATE_COMPRESSION option. Receiving compressed certificates
174 may be disabled on a connection via the SSL_OP_NO_RX_CERTIFICATE_COMPRESSION
175 option.
176 .SH "RETURN VALUES"
177 .IX Header "RETURN VALUES"
178 \&\fBSSL_CTX_set1_cert_comp_preference()\fR,
179 \&\fBSSL_set1_cert_comp_preference()\fR,
180 \&\fBSSL_CTX_compress_certs()\fR,
181 \&\fBSSL_compress_certs()\fR,
182 \&\fBSSL_CTX_set1_compressed_cert()\fR, and
183 \&\fBSSL_set1_compressed_cert()\fR
184 return 1 for success and 0 on error.
185 .PP
186 \&\fBSSL_CTX_get1_compressed_cert()\fR and
187 \&\fBSSL_get1_compressed_cert()\fR
188 return the length of the allocated memory on success and 0 on error.
189 .SH "SEE ALSO"
190 .IX Header "SEE ALSO"
191 \&\fBSSL_CTX_set_options\fR\|(3),
192 \&\fBSSL_CTX_use_certificate\fR\|(3)
193 .SH HISTORY
194 .IX Header "HISTORY"
195 These functions were added in OpenSSL 3.2.
196 .SH COPYRIGHT
197 .IX Header "COPYRIGHT"
198 Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
199 .PP
200 Licensed under the Apache License 2.0 (the "License"). You may not use
201 this file except in compliance with the License. You can obtain a copy
202 in the file LICENSE in the source distribution or at
203 <https://www.openssl.org/source/license.html>.