=pod

=head1 NAME

SSL_cert_compress_cb_fn, SSL_cert_decompress_cb_fn,
SSL_add_cert_compression_alg, SSL_CTX_add_cert_compression_alg,
SSL_get_cert_compression_compress_id, SSL_get_cert_compression_decompress_id
- TLS certificate compression methods

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 typedef int (*SSL_cert_compress_cb_fn)(SSL *s,
                    const unsigned char *in, size_t inlen,
                    unsigned char *out, size_t *outlen);
 typedef int (*SSL_cert_decompress_cb_fn)(SSL *s,
                    const unsigned char *in, size_t inlen,
                    unsigned char *out, size_t outlen);

 int SSL_add_cert_compression_alg(SSL *s, int alg_id,
                                 SSL_cert_compress_cb_fn compress,
                                 SSL_cert_decompress_cb_fn decompress);
 int SSL_CTX_add_cert_compression_alg(SSL_CTX *ctx, int alg_id,
                                     SSL_cert_compress_cb_fn compress,
                                     SSL_cert_decompress_cb_fn decompress);

 int SSL_get_cert_compression_compress_id(SSL *s);
 int SSL_get_cert_compression_decompress_id(SSL *s);

=head1 DESCRIPTION

B<SSL_cert_compress_cb_fn> is a pointer to a function that performs compression.
It must write the compressed representation of B<in> to B<out>. B<inlen> is
the byte length of the buffer B<in>. B<*outlen> is the total size of the buffer
B<out>. Upon exit, B<*outlen> is the actual size of the compressed buffer
B<out>. Note that if B<out> is NULL, it only computes the length of the
compressed buffer B<out> and write it to B<*outlen>. It returns 1 on success
or 0 on error.

B<SSL_cert_decompress_cb_fn> is a pointer to a function that performs
decompression. The compressed data is passed as B<in> with length B<inlen>
and the decompressed result must be exactly B<outlen> bytes long. It returns
1 on success, in which case B<*out> must be set to the result of decompressing
B<in>, or 0 on error.

SSL_add_cert_compression_alg() registers a certificate compression algorithm
on B<s> with algorithm identifier B<alg_id>. The compress callback B<compress>
is used to compress the Certificate message, and decompress callback
B<decompress> is used to decompress compressed Certificate message in
CompressedCertificate message. These callbacks can be NULL. Algorithms are
registered in preference order with the most preferable first.

RFC 8879 defines zlib, brotli and zstd compression algorithms corresponding to
the following compression algorithm:

=over 4

=item TLSEXT_cert_compression_zlib

ZLIB compression algorithm, as defined in RFC1950.

=item TLSEXT_cert_compression_brotli

Brotli compression algorithm, as defined in RFC7932.

=item TLSEXT_cert_compression_zstd

Zstandard compression algorithm, as defined in RFC8478.

=back

The algorithm id, 1-255 should be allocated under "IETF Review", under
"Specification Required" policy for values 256-16383, 16384-65535 can be used
for user-defined compression algorithms or others.

SSL_get_cert_compression_compress_id() returns the identifier of compression
algorithm which has been used.

SSL_get_cert_compression_decompress_id() returns the identifier of
decompression algorithm which has been used.

=head1 RETURN VALUES

SSL_add_cert_compression_alg() and SSL_CTX_add_cert_compression_alg() return
1 on success or 0 on error.

SSL_get_cert_compression_compress_id() return the used identifier of
compression algorithm, if no compression algorithm is used, 0 is
returned.

SSL_get_cert_compression_decompress_id() return the used identifier of
decompression algorithm, if no decompression algorithm is used, 0 is
returned.

=head1 SEE ALSO

L<ssl(7)>

=head1 COPYRIGHT

Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache-2.0 license (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
L<http://www.apache.org/licenses/LICENSE-2.0>.

=cut