.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SSL_CTX_SET1_CERT_COMP_PREFERENCE 3ossl"
.TH SSL_CTX_SET1_CERT_COMP_PREFERENCE 3ossl "2024-06-04" "3.3.1" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions control the certificate compression feature. Certificate
compression is only available for TLSv1.3 as defined in \s-1RFC8879.\s0
.PP
\&\fISSL_CTX_set1_cert_comp_preference()\fR and \fISSL_set1_cert_comp_preference()\fR are used
to specify the preferred compression algorithms. The \fBalgs\fR argument is an array
of algorithms, and \fBlength\fR is number of elements in the \fBalgs\fR array. Only
those algorithms enabled in the library will be accepted in \fBalgs\fR, unknown
algorithms in \fBalgs\fR are ignored. On an error, the preference order is left
unmodified.
.PP
The following compression algorithms (\fBalg\fR arguments) may be used:
.IP "\(bu" 4
TLSEXT_comp_cert_brotli
.IP "\(bu" 4
TLSEXT_comp_cert_zlib
.IP "\(bu" 4
TLSEXT_comp_cert_zstd
.PP
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.
.PP
\&\fISSL_CTX_compress_certs()\fR and \fISSL_compress_certs()\fR are used to pre-compress all
the configured certificates on an \s-1SSL_CTX/SSL\s0 object with algorithm \fBalg\fR. If
\&\fBalg\fR is 0, then the certificates are compressed with the algorithms specified
in the preference list. Calling these functions on a client \s-1SSL_CTX/SSL\s0 object
will result in an error, as only server certificates may be pre-compressed.
.PP
\&\fISSL_CTX_get1_compressed_cert()\fR and \fISSL_get1_compressed_cert()\fR are used to get
the pre-compressed certificate most recently set that may be stored for later
use. Calling these functions on a client \s-1SSL_CTX/SSL\s0 object will result in an
error, as only server certificates may be pre-compressed. The \fBdata\fR and
\&\fBorig_len\fR arguments are required.
.PP
The compressed certificate data may be passed to \fISSL_CTX_set1_compressed_cert()\fR
or \fISSL_set1_compressed_cert()\fR to provide a pre-compressed version of the
most recently set certificate. This pre-compressed certificate can only be used
by a server.
.SH "NOTES"
.IX Header "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.
.PP
Only server certificates may be pre-compressed. Calling any of these functions
(except \fISSL_CTX_set1_cert_comp_preference()\fR/\fISSL_set1_cert_comp_preference()\fR)
on a client \s-1SSL_CTX/SSL\s0 object will return an error. Client certificates are
compressed on-demand as unique context data from the server is compressed along
with the certificate.
.PP
For \fISSL_CTX_set1_cert_comp_preference()\fR and \fISSL_set1_cert_comp_preference()\fR
the \fBlen\fR argument is the size of the \fBalgs\fR argument in bytes.
.PP
The compressed certificate returned by \fISSL_CTX_get1_compressed_cert()\fR and
\&\fISSL_get1_compressed_cert()\fR is the last certificate set on the \s-1SSL_CTX/SSL\s0 object.
The certificate is copied by the function and the caller must free \fB*data\fR via
\&\fIOPENSSL_free()\fR.
.PP
The compressed certificate data set by \fISSL_CTX_set1_compressed_cert()\fR and
\&\fISSL_set1_compressed_cert()\fR is copied into the \s-1SSL_CTX/SSL\s0 object.
.PP
\&\fISSL_CTX_compress_certs()\fR and \fISSL_compress_certs()\fR return an error under the
following conditions:
.IP "\(bu" 4
If no certificates have been configured.
.IP "\(bu" 4
If the specified algorithm \fBalg\fR is not enabled.
.IP "\(bu" 4
If \fBalg\fR is 0 and no compression algorithms are enabled.
.PP
Sending compressed certificates may be disabled on a connection via the
\&\s-1SSL_OP_NO_TX_CERTIFICATE_COMPRESSION\s0 option. Receiving compressed certificates
may be disabled on a connection via the \s-1SSL_OP_NO_RX_CERTIFICATE_COMPRESSION\s0
option.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fISSL_CTX_set1_cert_comp_preference()\fR,
\&\fISSL_set1_cert_comp_preference()\fR,
\&\fISSL_CTX_compress_certs()\fR,
\&\fISSL_compress_certs()\fR,
\&\fISSL_CTX_set1_compressed_cert()\fR, and
\&\fISSL_set1_compressed_cert()\fR
return 1 for success and 0 on error.
.PP
\&\fISSL_CTX_get1_compressed_cert()\fR and
\&\fISSL_get1_compressed_cert()\fR
return the length of the allocated memory on success and 0 on error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fISSL_CTX_set_options\fR\|(3),
\&\fISSL_CTX_use_certificate\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
These functions were added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.