Debian Codegraph @

upstream/debian-unstable/man3/COMP_CTX_new.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "COMP_CTX_NEW 3SSL"
58 .TH COMP_CTX_NEW 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 COMP_CTX_new,
65 COMP_CTX_get_method,
66 COMP_CTX_get_type,
67 COMP_get_type,
68 COMP_get_name,
69 COMP_CTX_free,
70 COMP_compress_block,
71 COMP_expand_block,
72 COMP_zlib,
73 COMP_zlib_oneshot,
74 COMP_brotli,
75 COMP_brotli_oneshot,
76 COMP_zstd,
77 COMP_zstd_oneshot,
78 BIO_f_zlib,
79 BIO_f_brotli,
80 BIO_f_zstd
81 \&\- Compression support
82 .SH SYNOPSIS
83 .IX Header "SYNOPSIS"
84 .Vb 1
85 \& #include <openssl/comp.h>
86 \&
87 \& COMP_CTX *COMP_CTX_new(COMP_METHOD *meth);
88 \& void COMP_CTX_free(COMP_CTX *ctx);
89 \& const COMP_METHOD *COMP_CTX_get_method(const COMP_CTX *ctx);
90 \& int COMP_CTX_get_type(const COMP_CTX* comp);
91 \& int COMP_get_type(const COMP_METHOD *meth);
92 \& const char *COMP_get_name(const COMP_METHOD *meth);
93 \&
94 \& int COMP_compress_block(COMP_CTX *ctx, unsigned char *out, int olen,
95 \& unsigned char *in, int ilen);
96 \& int COMP_expand_block(COMP_CTX *ctx, unsigned char *out, int olen,
97 \& unsigned char *in, int ilen);
98 \&
99 \& COMP_METHOD *COMP_zlib(void);
100 \& COMP_METHOD *COMP_zlib_oneshot(void);
101 \& COMP_METHOD *COMP_brotli(void);
102 \& COMP_METHOD *COMP_brotli_oneshot(void);
103 \& COMP_METHOD *COMP_zstd(void);
104 \& COMP_METHOD *COMP_zstd_oneshot(void);
105 \&
106 \& const BIO_METHOD *BIO_f_zlib(void);
107 \& const BIO_METHOD *BIO_f_brotli(void);
108 \& const BIO_METHOD *BIO_f_zstd(void);
109 .Ve
110 .SH DESCRIPTION
111 .IX Header "DESCRIPTION"
112 These functions provide compression support for OpenSSL. Compression is used within
113 the OpenSSL library to support TLS record and certificate compression.
114 .PP
115 \&\fBCOMP_CTX_new()\fR is used to create a new \fBCOMP_CTX\fR structure used to compress data.
116 .PP
117 \&\fBCOMP_CTX_free()\fR is used to free the returned \fBCOMP_CTX\fR.
118 If the argument is NULL, nothing is done.
119 .PP
120 \&\fBCOMP_CTX_get_method()\fR returns the \fBCOMP_METHOD\fR of the given \fIctx\fR.
121 .PP
122 \&\fBCOMP_CTX_get_type()\fR and \fBCOMP_get_type()\fR return the NID for the \fBCOMP_CTX\fR and
123 \&\fBCOMP_METHOD\fR, respectively. \fBCOMP_get_name()\fR returns the name of the algorithm
124 of the given \fBCOMP_METHOD\fR.
125 .PP
126 \&\fBCOMP_compress_block()\fR compresses \fBilen\fR bytes from the buffer \fIin\fR into the
127 buffer \fBout\fR of size \fIolen\fR using the algorithm specified by \fIctx\fR.
128 .PP
129 \&\fBCOMP_expand_block()\fR expands \fIilen\fR bytes from the buffer \fIin\fR into the
130 buffer \fIout\fR of size \fIolen\fR using the algorithm specified by \fIctx\fR.
131 .PP
132 Methods (\fBCOMP_METHOD\fR) may be specified by one of these functions. These functions
133 will be available even if their corresponding compression algorithm is not configured
134 into the OpenSSL library. In such a case, NULL will be returned.
135 .IP \(bu 4
136 \&\fBCOMP_zlib()\fR returns a \fBCOMP_METHOD\fR for stream-based ZLIB compression.
137 .IP \(bu 4
138 \&\fBCOMP_zlib_oneshot()\fR returns a \fBCOMP_METHOD\fR for one-shot ZLIB compression.
139 .IP \(bu 4
140 \&\fBCOMP_brotli()\fR returns a \fBCOMP_METHOD\fR for stream-based Brotli compression.
141 .IP \(bu 4
142 \&\fBCOMP_brotli_oneshot()\fR returns a \fBCOMP_METHOD\fR for one-shot Brotli compression.
143 .IP \(bu 4
144 \&\fBCOMP_zstd()\fR returns a \fBCOMP_METHOD\fR for stream-based Zstandard compression.
145 .IP \(bu 4
146 \&\fBCOMP_zstd_oneshot()\fR returns a \fBCOMP_METHOD\fR for one-shot Zstandard compression.
147 .PP
148 \&\fBBIO_f_zlib()\fR, \fBBIO_f_brotli()\fR \fBBIO_f_zstd()\fR each return a \fBBIO_METHOD\fR that may be used to
149 create a \fBBIO\fR via \fBBIO_new\|(3)\fR to read and write compressed files or streams.
150 The functions are only available if the corresponding algorithm is compiled into
151 the OpenSSL library. NULL may be returned if the algorithm fails to load dynamically.
152 .SH NOTES
153 .IX Header "NOTES"
154 While compressing non-compressible data, the output may be larger than the
155 input. Care should be taken to size output buffers appropriate for both
156 compression and expansion.
157 .PP
158 Compression support and compression algorithms must be enabled and built into
159 the library before use. Refer to the INSTALL.md file when configuring OpenSSL.
160 .PP
161 ZLIB may be found at <https://zlib.net>
162 .PP
163 Brotli may be found at <https://github.com/google/brotli>.
164 .PP
165 Zstandard may be found at <https://github.com/facebook/zstd>.
166 .PP
167 Compression of SSL/TLS records is not recommended, as it has been
168 shown to lead to the CRIME attack <https://en.wikipedia.org/wiki/CRIME>.
169 It is disabled by default, and may be enabled by clearing the
170 SSL_OP_NO_COMPRESSION option and setting the security level as appropriate.
171 See the documentation for the \fBSSL_CTX_set_options\fR\|(3) and
172 \&\fBSSL_set_options\fR\|(3) functions.
173 .PP
174 Compression is also used to support certificate compression as described
175 in RFC8879 <https://datatracker.ietf.org/doc/html/rfc8879>.
176 It may be disabled via the SSL_OP_NO_TX_CERTIFICATE_COMPRESSION and
177 SSL_OP_NO_RX_CERTIFICATE_COMPRESSION options of the
178 \&\fBSSL_CTX_set_options\fR\|(3) or \fBSSL_set_options\fR\|(3) functions.
179 .PP
180 \&\fBCOMP_zlib()\fR, \fBCOMP_brotli()\fR and \fBCOMP_zstd()\fR are stream-based compression methods.
181 Internal state (including compression dictionary) is maintained between calls.
182 If an error is returned, the stream is corrupted, and should be closed.
183 .PP
184 \&\fBCOMP_zlib_oneshot()\fR, \fBCOMP_brotli_oneshot()\fR and \fBCOMP_zstd_oneshot()\fR are not stream-based. These
185 methods do not maintain state between calls. An error in one call does not affect
186 future calls.
187 .SH "RETURN VALUES"
188 .IX Header "RETURN VALUES"
189 \&\fBCOMP_CTX_new()\fR returns a \fBCOMP_CTX\fR on success, or NULL on failure.
190 .PP
191 \&\fBCOMP_CTX_get_method()\fR, \fBCOMP_zlib()\fR, \fBCOMP_zlib_oneshot()\fR, \fBCOMP_brotli()\fR, \fBCOMP_brotli_oneshot()\fR,
192 \&\fBCOMP_zstd()\fR, and \fBCOMP_zstd_oneshot()\fR return a \fBCOMP_METHOD\fR on success,
193 or NULL on failure.
194 .PP
195 \&\fBCOMP_CTX_get_type()\fR and \fBCOMP_get_type()\fR return a NID value. On failure,
196 NID_undef is returned.
197 .PP
198 \&\fBCOMP_compress_block()\fR and \fBCOMP_expand_block()\fR return the number of
199 bytes stored in the output buffer \fIout\fR. This may be 0. On failure,
200 \&\-1 is returned.
201 .PP
202 \&\fBCOMP_get_name()\fR returns a \fBconst char *\fR that must not be freed
203 on success, or NULL on failure.
204 .PP
205 \&\fBBIO_f_zlib()\fR, \fBBIO_f_brotli()\fR and \fBBIO_f_zstd()\fR return NULL on error, and
206 a \fBBIO_METHOD\fR on success.
207 .SH "SEE ALSO"
208 .IX Header "SEE ALSO"
209 \&\fBBIO_new\fR\|(3), \fBSSL_CTX_set_options\fR\|(3), \fBSSL_set_options\fR\|(3)
210 .SH HISTORY
211 .IX Header "HISTORY"
212 Brotli and Zstandard functions were added in OpenSSL 3.2.
213 .SH COPYRIGHT
214 .IX Header "COPYRIGHT"
215 Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved.
216 .PP
217 Licensed under the Apache License 2.0 (the "License"). You may not use
218 this file except in compliance with the License. You can obtain a copy
219 in the file LICENSE in the source distribution or at
220 <https://www.openssl.org/source/license.html>.