1=pod
2
3=head1 NAME
4
5SSL_CTX_set1_cert_comp_preference,
6SSL_set1_cert_comp_preference,
7SSL_CTX_compress_certs,
8SSL_compress_certs,
9SSL_CTX_get1_compressed_cert,
10SSL_get1_compressed_cert,
11SSL_CTX_set1_compressed_cert,
12SSL_set1_compressed_cert - Certificate compression functions
13
14=head1 SYNOPSIS
15
16 #include <openssl/ssl.h>
17
18 int SSL_CTX_set1_cert_comp_preference(SSL_CTX *ctx, int *algs, size_t len);
19 int SSL_set1_cert_comp_preference(SSL *ssl, int *algs, size_t len);
20
21 int SSL_CTX_compress_certs(SSL_CTX *ctx, int alg);
22 int SSL_compress_certs(SSL *ssl, int alg);
23
24 size_t SSL_CTX_get1_compressed_cert(SSL_CTX *ctx, int alg, unsigned char **data,
25                                     size_t *orig_len);
26 size_t SSL_get1_compressed_cert(SSL *ssl, int alg, unsigned char **data,
27                                 size_t *orig_len);
28
29 int SSL_CTX_set1_compressed_cert(SSL_CTX *ctx, int alg,
30                                  unsigned char *comp_data,
31                                  size_t comp_length, size_t orig_length);
32 int SSL_set1_compressed_cert(SSL *ssl, int alg, unsigned char *comp_data,
33                              size_t comp_length, size_t orig_length);
34
35
36=head1 DESCRIPTION
37
38These functions control the certificate compression feature. Certificate
39compression is only available for TLSv1.3 as defined in RFC8879.
40
41SSL_CTX_set1_cert_comp_preference() and SSL_set1_cert_comp_preference() are used
42to specify the preferred compression algorithms. The B<algs> argument is an array
43of algorithms, and B<length> is number of elements in the B<algs> array. Only
44those algorithms enabled in the library will be accepted in B<algs>, unknown
45algorithms in B<algs> are ignored. On an error, the preference order is left
46unmodified.
47
48The following compression algorithms (B<alg> arguments) may be used:
49
50=over 4
51
52=item * TLSEXT_comp_cert_brotli
53
54=item * TLSEXT_comp_cert_zlib
55
56=item * TLSEXT_comp_cert_zstd
57
58=back
59
60The above is also the default preference order. If a preference order is not
61specified, then the default preference order is sent to the peer and the
62received peer's preference order will be used when compressing a certificate.
63Otherwise, the configured preference order is sent to the peer and is used
64to filter the peer's preference order.
65
66SSL_CTX_compress_certs() and SSL_compress_certs() are used to pre-compress all
67the configured certificates on an SSL_CTX/SSL object with algorithm B<alg>. If
68B<alg> is 0, then the certificates are compressed with the algorithms specified
69in the preference list. Calling these functions on a client SSL_CTX/SSL object
70will result in an error, as only server certificates may be pre-compressed.
71
72SSL_CTX_get1_compressed_cert() and SSL_get1_compressed_cert() are used to get
73the pre-compressed certificate most recently set that may be stored for later
74use. Calling these functions on a client SSL_CTX/SSL object will result in an
75error, as only server certificates may be pre-compressed. The B<data> and
76B<orig_len> arguments are required.
77
78The compressed certificate data may be passed to SSL_CTX_set1_compressed_cert()
79or SSL_set1_compressed_cert() to provide a pre-compressed version of the
80most recently set certificate. This pre-compressed certificate can only be used
81by a server.
82
83=head1 NOTES
84
85Each side of the connection sends their compression algorithm preference list
86to their peer indicating compressed certificate support. The received preference
87list is filtered by the configured preference list (i.e. the intersection is
88saved). As the default list includes all the enabled algorithms, not specifying
89a preference will allow any enabled algorithm by the peer. The filtered peer's
90preference order is used to determine what algorithm to use when sending a
91compressed certificate.
92
93Only server certificates may be pre-compressed. Calling any of these functions
94(except SSL_CTX_set1_cert_comp_preference()/SSL_set1_cert_comp_preference())
95on a client SSL_CTX/SSL object will return an error. Client certificates are
96compressed on-demand as unique context data from the server is compressed along
97with the certificate.
98
99For SSL_CTX_set1_cert_comp_preference() and SSL_set1_cert_comp_preference()
100the B<len> argument is the size of the B<algs> argument in bytes.
101
102The compressed certificate returned by SSL_CTX_get1_compressed_cert() and
103SSL_get1_compressed_cert() is the last certificate set on the SSL_CTX/SSL object.
104The certificate is copied by the function and the caller must free B<*data> via
105OPENSSL_free().
106
107The compressed certificate data set by SSL_CTX_set1_compressed_cert() and
108SSL_set1_compressed_cert() is copied into the SSL_CTX/SSL object.
109
110SSL_CTX_compress_certs() and SSL_compress_certs() return an error under the
111following conditions:
112
113=over 4
114
115=item * If no certificates have been configured.
116
117=item * If the specified algorithm B<alg> is not enabled.
118
119=item * If B<alg> is 0 and no compression algorithms are enabled.
120
121=back
122
123Sending compressed certificates may be disabled on a connection via the
124SSL_OP_NO_TX_CERTIFICATE_COMPRESSION option. Receiving compressed certificates
125may be disabled on a connection via the SSL_OP_NO_RX_CERTIFICATE_COMPRESSION
126option.
127
128=head1 RETURN VALUES
129
130SSL_CTX_set1_cert_comp_preference(),
131SSL_set1_cert_comp_preference(),
132SSL_CTX_compress_certs(),
133SSL_compress_certs(),
134SSL_CTX_set1_compressed_cert(), and
135SSL_set1_compressed_cert()
136return 1 for success and 0 on error.
137
138SSL_CTX_get1_compressed_cert() and
139SSL_get1_compressed_cert()
140return the length of the allocated memory on success and 0 on error.
141
142=head1 SEE ALSO
143
144L<SSL_CTX_set_options(3)>,
145L<SSL_CTX_use_certificate(3)>
146
147=head1 HISTORY
148
149These functions were added in OpenSSL 3.2.
150
151=head1 COPYRIGHT
152
153Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
154
155Licensed under the Apache License 2.0 (the "License").  You may not use
156this file except in compliance with the License.  You can obtain a copy
157in the file LICENSE in the source distribution or at
158L<https://www.openssl.org/source/license.html>.
159
160=cut
161