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