SSL_CTX_SET1_CERT_COMP_PREFERENCE(3ossl) OpenSSL
NAME
SSL_CTX_set1_cert_comp_preference, SSL_set1_cert_comp_preference,
SSL_CTX_compress_certs, SSL_compress_certs,
SSL_CTX_get1_compressed_cert, SSL_get1_compressed_cert,
SSL_CTX_set1_compressed_cert, SSL_set1_compressed_cert - Certificate
compression functions
SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_set1_cert_comp_preference(SSL_CTX *ctx, int *algs, size_t len);
int SSL_set1_cert_comp_preference(SSL *ssl, int *algs, size_t len);
int SSL_CTX_compress_certs(SSL_CTX *ctx, int alg);
int SSL_compress_certs(SSL *ssl, int alg);
size_t SSL_CTX_get1_compressed_cert(SSL_CTX *ctx, int alg, unsigned char **data,
size_t *orig_len);
size_t SSL_get1_compressed_cert(SSL *ssl, int alg, unsigned char **data,
size_t *orig_len);
int SSL_CTX_set1_compressed_cert(SSL_CTX *ctx, int alg,
unsigned char *comp_data,
size_t comp_length, size_t orig_length);
int SSL_set1_compressed_cert(SSL *ssl, int alg, unsigned char *comp_data,
size_t comp_length, size_t orig_length);
DESCRIPTION
These functions control the certificate compression feature.
Certificate compression is only available for TLSv1.3 as defined in
RFC8879.
SSL_CTX_set1_cert_comp_preference(3) and SSL_set1_cert_comp_preference()
are used to specify the preferred compression algorithms. The algs
argument is an array of algorithms, and length is number of elements in
the algs array. Only those algorithms enabled in the library will be
accepted in algs, unknown algorithms in algs are ignored. On an error,
the preference order is left unmodified.
The following compression algorithms (alg arguments) may be used:
o TLSEXT_comp_cert_brotli
o TLSEXT_comp_cert_zlib
o TLSEXT_comp_cert_zstd
The above is also the default preference order. If a preference order
is not specified, then the default preference order is sent to the peer
and the received peer's preference order will be used when compressing
a certificate. Otherwise, the configured preference order is sent to
the peer and is used to filter the peer's preference order.
SSL_CTX_compress_certs() and SSL_compress_certs() are used to
pre-compress all the configured certificates on an SSL_CTX/SSL object
with algorithm alg. If alg is 0, then the certificates are compressed
with the algorithms specified in the preference list. Calling these
functions on a client SSL_CTX/SSL object will result in an error, as
only server certificates may be pre-compressed.
SSL_CTX_get1_compressed_cert() and SSL_get1_compressed_cert() are used
to get the pre-compressed certificate most recently set that may be
stored for later use. Calling these functions on a client SSL_CTX/SSL
object will result in an error, as only server certificates may be
pre-compressed. The data and orig_len arguments are required.
The compressed certificate data may be passed to
SSL_CTX_set1_compressed_cert() or SSL_set1_compressed_cert() to provide
a pre-compressed version of the most recently set certificate. This
pre-compressed certificate can only be used by a server.
NOTES
Each side of the connection sends their compression algorithm
preference list to their peer indicating compressed certificate
support. The received preference list is filtered by the configured
preference list (i.e. the intersection is saved). As the default list
includes all the enabled algorithms, not specifying a preference will
allow any enabled algorithm by the peer. The filtered peer's preference
order is used to determine what algorithm to use when sending a
compressed certificate.
Only server certificates may be pre-compressed. Calling any of these
functions (except
SSL_CTX_set1_cert_comp_preference(3)/SSL_set1_cert_comp_preference()) on
a client SSL_CTX/SSL object will return an error. Client certificates
are compressed on-demand as unique context data from the server is
compressed along with the certificate.
For SSL_CTX_set1_cert_comp_preference(3) and
SSL_set1_cert_comp_preference() the len argument is the size of the
algs argument in bytes.
The compressed certificate returned by SSL_CTX_get1_compressed_cert()
and SSL_get1_compressed_cert() is the last certificate set on the
SSL_CTX/SSL object. The certificate is copied by the function and the
caller must free *data via OPENSSL_free().
The compressed certificate data set by SSL_CTX_set1_compressed_cert()
and SSL_set1_compressed_cert() is copied into the SSL_CTX/SSL object.
SSL_CTX_compress_certs() and SSL_compress_certs() return an error under
the following conditions:
o If no certificates have been configured.
o If the specified algorithm alg is not enabled.
o If alg is 0 and no compression algorithms are enabled.
Sending compressed certificates may be disabled on a connection via the
SSL_OP_NO_TX_CERTIFICATE_COMPRESSION option. Receiving compressed
certificates may be disabled on a connection via the
SSL_OP_NO_RX_CERTIFICATE_COMPRESSION option.
RETURN VALUES
SSL_CTX_set1_cert_comp_preference(3), SSL_set1_cert_comp_preference(),
SSL_CTX_compress_certs(), SSL_compress_certs(),
SSL_CTX_set1_compressed_cert(), and SSL_set1_compressed_cert() return 1
for success and 0 on error.
SSL_CTX_get1_compressed_cert() and SSL_get1_compressed_cert() return
the length of the allocated memory on success and 0 on error.
SEE ALSO
SSL_CTX_set_options(3), SSL_CTX_use_certificate(3)
HISTORY
These functions were added in OpenSSL 3.2.
COPYRIGHT
Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.
3.3.2 2024-09-04
SSL_CTX_SET1_CERT_COMP_PREFERENCE(3ossl)
openssl 3.3.2 - Generated Sun Sep 22 06:44:16 CDT 2024