xref: /freebsd/crypto/openssl/doc/man3/COMP_CTX_new.pod (revision e7be843b4a162e68651d3911f0357ed464915629) 
1*e7be843bSPierre Pronchery=pod
2*e7be843bSPierre Pronchery
3*e7be843bSPierre Pronchery=head1 NAME
4*e7be843bSPierre Pronchery
5*e7be843bSPierre ProncheryCOMP_CTX_new,
6*e7be843bSPierre ProncheryCOMP_CTX_get_method,
7*e7be843bSPierre ProncheryCOMP_CTX_get_type,
8*e7be843bSPierre ProncheryCOMP_get_type,
9*e7be843bSPierre ProncheryCOMP_get_name,
10*e7be843bSPierre ProncheryCOMP_CTX_free,
11*e7be843bSPierre ProncheryCOMP_compress_block,
12*e7be843bSPierre ProncheryCOMP_expand_block,
13*e7be843bSPierre ProncheryCOMP_zlib,
14*e7be843bSPierre ProncheryCOMP_zlib_oneshot,
15*e7be843bSPierre ProncheryCOMP_brotli,
16*e7be843bSPierre ProncheryCOMP_brotli_oneshot,
17*e7be843bSPierre ProncheryCOMP_zstd,
18*e7be843bSPierre ProncheryCOMP_zstd_oneshot,
19*e7be843bSPierre ProncheryBIO_f_zlib,
20*e7be843bSPierre ProncheryBIO_f_brotli,
21*e7be843bSPierre ProncheryBIO_f_zstd
22*e7be843bSPierre Pronchery- Compression support
23*e7be843bSPierre Pronchery
24*e7be843bSPierre Pronchery=head1 SYNOPSIS
25*e7be843bSPierre Pronchery
26*e7be843bSPierre Pronchery #include <openssl/comp.h>
27*e7be843bSPierre Pronchery
28*e7be843bSPierre Pronchery COMP_CTX *COMP_CTX_new(COMP_METHOD *meth);
29*e7be843bSPierre Pronchery void COMP_CTX_free(COMP_CTX *ctx);
30*e7be843bSPierre Pronchery const COMP_METHOD *COMP_CTX_get_method(const COMP_CTX *ctx);
31*e7be843bSPierre Pronchery int COMP_CTX_get_type(const COMP_CTX* comp);
32*e7be843bSPierre Pronchery int COMP_get_type(const COMP_METHOD *meth);
33*e7be843bSPierre Pronchery const char *COMP_get_name(const COMP_METHOD *meth);
34*e7be843bSPierre Pronchery
35*e7be843bSPierre Pronchery int COMP_compress_block(COMP_CTX *ctx, unsigned char *out, int olen,
36*e7be843bSPierre Pronchery                         unsigned char *in, int ilen);
37*e7be843bSPierre Pronchery int COMP_expand_block(COMP_CTX *ctx, unsigned char *out, int olen,
38*e7be843bSPierre Pronchery                       unsigned char *in, int ilen);
39*e7be843bSPierre Pronchery
40*e7be843bSPierre Pronchery COMP_METHOD *COMP_zlib(void);
41*e7be843bSPierre Pronchery COMP_METHOD *COMP_zlib_oneshot(void);
42*e7be843bSPierre Pronchery COMP_METHOD *COMP_brotli(void);
43*e7be843bSPierre Pronchery COMP_METHOD *COMP_brotli_oneshot(void);
44*e7be843bSPierre Pronchery COMP_METHOD *COMP_zstd(void);
45*e7be843bSPierre Pronchery COMP_METHOD *COMP_zstd_oneshot(void);
46*e7be843bSPierre Pronchery
47*e7be843bSPierre Pronchery const BIO_METHOD *BIO_f_zlib(void);
48*e7be843bSPierre Pronchery const BIO_METHOD *BIO_f_brotli(void);
49*e7be843bSPierre Pronchery const BIO_METHOD *BIO_f_zstd(void);
50*e7be843bSPierre Pronchery
51*e7be843bSPierre Pronchery=head1 DESCRIPTION
52*e7be843bSPierre Pronchery
53*e7be843bSPierre ProncheryThese functions provide compression support for OpenSSL. Compression is used within
54*e7be843bSPierre Proncherythe OpenSSL library to support TLS record and certificate compression.
55*e7be843bSPierre Pronchery
56*e7be843bSPierre ProncheryCOMP_CTX_new() is used to create a new B<COMP_CTX> structure used to compress data.
57*e7be843bSPierre Pronchery
58*e7be843bSPierre ProncheryCOMP_CTX_free() is used to free the returned B<COMP_CTX>.
59*e7be843bSPierre ProncheryIf the argument is NULL, nothing is done.
60*e7be843bSPierre Pronchery
61*e7be843bSPierre ProncheryCOMP_CTX_get_method() returns the B<COMP_METHOD> of the given I<ctx>.
62*e7be843bSPierre Pronchery
63*e7be843bSPierre ProncheryCOMP_CTX_get_type() and COMP_get_type() return the NID for the B<COMP_CTX> and
64*e7be843bSPierre ProncheryB<COMP_METHOD>, respectively. COMP_get_name() returns the name of the algorithm
65*e7be843bSPierre Proncheryof the given B<COMP_METHOD>.
66*e7be843bSPierre Pronchery
67*e7be843bSPierre ProncheryCOMP_compress_block() compresses b<ilen> bytes from the buffer I<in> into the
68*e7be843bSPierre Proncherybuffer b<out> of size I<olen> using the algorithm specified by I<ctx>.
69*e7be843bSPierre Pronchery
70*e7be843bSPierre ProncheryCOMP_expand_block() expands I<ilen> bytes from the buffer I<in> into the
71*e7be843bSPierre Proncherybuffer I<out> of size I<olen> using the algorithm specified by I<ctx>.
72*e7be843bSPierre Pronchery
73*e7be843bSPierre ProncheryMethods (B<COMP_METHOD>) may be specified by one of these functions. These functions
74*e7be843bSPierre Proncherywill be available even if their corresponding compression algorithm is not configured
75*e7be843bSPierre Proncheryinto the OpenSSL library. In such a case, NULL will be returned.
76*e7be843bSPierre Pronchery
77*e7be843bSPierre Pronchery=over 4
78*e7be843bSPierre Pronchery
79*e7be843bSPierre Pronchery=item *
80*e7be843bSPierre Pronchery
81*e7be843bSPierre ProncheryCOMP_zlib() returns a B<COMP_METHOD> for stream-based ZLIB compression.
82*e7be843bSPierre Pronchery
83*e7be843bSPierre Pronchery=item *
84*e7be843bSPierre Pronchery
85*e7be843bSPierre ProncheryCOMP_zlib_oneshot() returns a B<COMP_METHOD> for one-shot ZLIB compression.
86*e7be843bSPierre Pronchery
87*e7be843bSPierre Pronchery=item *
88*e7be843bSPierre Pronchery
89*e7be843bSPierre ProncheryCOMP_brotli() returns a B<COMP_METHOD> for stream-based Brotli compression.
90*e7be843bSPierre Pronchery
91*e7be843bSPierre Pronchery=item *
92*e7be843bSPierre Pronchery
93*e7be843bSPierre ProncheryCOMP_brotli_oneshot() returns a B<COMP_METHOD> for one-shot Brotli compression.
94*e7be843bSPierre Pronchery
95*e7be843bSPierre Pronchery=item *
96*e7be843bSPierre Pronchery
97*e7be843bSPierre ProncheryCOMP_zstd() returns a B<COMP_METHOD> for stream-based Zstandard compression.
98*e7be843bSPierre Pronchery
99*e7be843bSPierre Pronchery=item *
100*e7be843bSPierre Pronchery
101*e7be843bSPierre ProncheryCOMP_zstd_oneshot() returns a B<COMP_METHOD> for one-shot Zstandard compression.
102*e7be843bSPierre Pronchery
103*e7be843bSPierre Pronchery=back
104*e7be843bSPierre Pronchery
105*e7be843bSPierre ProncheryBIO_f_zlib(), BIO_f_brotli() BIO_f_zstd() each return a B<BIO_METHOD> that may be used to
106*e7be843bSPierre Proncherycreate a B<BIO> via B<BIO_new(3)> to read and write compressed files or streams.
107*e7be843bSPierre ProncheryThe functions are only available if the corresponding algorithm is compiled into
108*e7be843bSPierre Proncherythe OpenSSL library. NULL may be returned if the algorithm fails to load dynamically.
109*e7be843bSPierre Pronchery
110*e7be843bSPierre Pronchery=head1 NOTES
111*e7be843bSPierre Pronchery
112*e7be843bSPierre ProncheryWhile compressing non-compressible data, the output may be larger than the
113*e7be843bSPierre Proncheryinput. Care should be taken to size output buffers appropriate for both
114*e7be843bSPierre Proncherycompression and expansion.
115*e7be843bSPierre Pronchery
116*e7be843bSPierre ProncheryCompression support and compression algorithms must be enabled and built into
117*e7be843bSPierre Proncherythe library before use. Refer to the INSTALL.md file when configuring OpenSSL.
118*e7be843bSPierre Pronchery
119*e7be843bSPierre ProncheryZLIB may be found at L<https://zlib.net>
120*e7be843bSPierre Pronchery
121*e7be843bSPierre ProncheryBrotli may be found at L<https://github.com/google/brotli>.
122*e7be843bSPierre Pronchery
123*e7be843bSPierre ProncheryZstandard may be found at L<https://github.com/facebook/zstd>.
124*e7be843bSPierre Pronchery
125*e7be843bSPierre ProncheryCompression of SSL/TLS records is not recommended, as it has been
126*e7be843bSPierre Proncheryshown to lead to the CRIME attack L<https://en.wikipedia.org/wiki/CRIME>.
127*e7be843bSPierre ProncheryIt is disabled by default, and may be enabled by clearing the
128*e7be843bSPierre ProncherySSL_OP_NO_COMPRESSION option and setting the security level as appropriate.
129*e7be843bSPierre ProncherySee the documentation for the L<SSL_CTX_set_options(3)> and
130*e7be843bSPierre ProncheryL<SSL_set_options(3)> functions.
131*e7be843bSPierre Pronchery
132*e7be843bSPierre ProncheryCompression is also used to support certificate compression as described
133*e7be843bSPierre Proncheryin RFC8879 L<https://datatracker.ietf.org/doc/html/rfc8879>.
134*e7be843bSPierre ProncheryIt may be disabled via the SSL_OP_NO_TX_CERTIFICATE_COMPRESSION and
135*e7be843bSPierre ProncherySSL_OP_NO_RX_CERTIFICATE_COMPRESSION options of the
136*e7be843bSPierre ProncheryL<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions.
137*e7be843bSPierre Pronchery
138*e7be843bSPierre ProncheryCOMP_zlib(), COMP_brotli() and COMP_zstd() are stream-based compression methods.
139*e7be843bSPierre ProncheryInternal state (including compression dictionary) is maintained between calls.
140*e7be843bSPierre ProncheryIf an error is returned, the stream is corrupted, and should be closed.
141*e7be843bSPierre Pronchery
142*e7be843bSPierre ProncheryCOMP_zlib_oneshot(), COMP_brotli_oneshot() and COMP_zstd_oneshot() are not stream-based. These
143*e7be843bSPierre Proncherymethods do not maintain state between calls. An error in one call does not affect
144*e7be843bSPierre Proncheryfuture calls.
145*e7be843bSPierre Pronchery
146*e7be843bSPierre Pronchery=head1 RETURN VALUES
147*e7be843bSPierre Pronchery
148*e7be843bSPierre ProncheryCOMP_CTX_new() returns a B<COMP_CTX> on success, or NULL on failure.
149*e7be843bSPierre Pronchery
150*e7be843bSPierre ProncheryCOMP_CTX_get_method(), COMP_zlib(), COMP_zlib_oneshot(), COMP_brotli(), COMP_brotli_oneshot(),
151*e7be843bSPierre ProncheryCOMP_zstd(), and COMP_zstd_oneshot() return a B<COMP_METHOD> on success,
152*e7be843bSPierre Proncheryor NULL on failure.
153*e7be843bSPierre Pronchery
154*e7be843bSPierre ProncheryCOMP_CTX_get_type() and COMP_get_type() return a NID value. On failure,
155*e7be843bSPierre ProncheryNID_undef is returned.
156*e7be843bSPierre Pronchery
157*e7be843bSPierre ProncheryCOMP_compress_block() and COMP_expand_block() return the number of
158*e7be843bSPierre Proncherybytes stored in the output buffer I<out>. This may be 0. On failure,
159*e7be843bSPierre Pronchery-1 is returned.
160*e7be843bSPierre Pronchery
161*e7be843bSPierre ProncheryCOMP_get_name() returns a B<const char *> that must not be freed
162*e7be843bSPierre Proncheryon success, or NULL on failure.
163*e7be843bSPierre Pronchery
164*e7be843bSPierre ProncheryBIO_f_zlib(), BIO_f_brotli() and BIO_f_zstd() return NULL on error, and
165*e7be843bSPierre Proncherya B<BIO_METHOD> on success.
166*e7be843bSPierre Pronchery
167*e7be843bSPierre Pronchery=head1 SEE ALSO
168*e7be843bSPierre Pronchery
169*e7be843bSPierre ProncheryL<BIO_new(3)>, L<SSL_CTX_set_options(3)>, L<SSL_set_options(3)>
170*e7be843bSPierre Pronchery
171*e7be843bSPierre Pronchery=head1 HISTORY
172*e7be843bSPierre Pronchery
173*e7be843bSPierre ProncheryBrotli and Zstandard functions were added in OpenSSL 3.2.
174*e7be843bSPierre Pronchery
175*e7be843bSPierre Pronchery=head1 COPYRIGHT
176*e7be843bSPierre Pronchery
177*e7be843bSPierre ProncheryCopyright 2022-2024 The OpenSSL Project Authors. All Rights Reserved.
178*e7be843bSPierre Pronchery
179*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
180*e7be843bSPierre Proncherythis file except in compliance with the License.  You can obtain a copy
181*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at
182*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>.
183*e7be843bSPierre Pronchery
184*e7be843bSPierre Pronchery=cut
185