diff options
Diffstat (limited to 'static/freebsd/man3/COMP_CTX_new.3')
| -rw-r--r-- | static/freebsd/man3/COMP_CTX_new.3 | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/static/freebsd/man3/COMP_CTX_new.3 b/static/freebsd/man3/COMP_CTX_new.3 new file mode 100644 index 00000000..feb38cd8 --- /dev/null +++ b/static/freebsd/man3/COMP_CTX_new.3 @@ -0,0 +1,223 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" 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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. 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 >0, 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 +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "COMP_CTX_NEW 3ossl" +.TH COMP_CTX_NEW 3ossl 2026-04-07 3.5.6 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 +COMP_CTX_new, +COMP_CTX_get_method, +COMP_CTX_get_type, +COMP_get_type, +COMP_get_name, +COMP_CTX_free, +COMP_compress_block, +COMP_expand_block, +COMP_zlib, +COMP_zlib_oneshot, +COMP_brotli, +COMP_brotli_oneshot, +COMP_zstd, +COMP_zstd_oneshot, +BIO_f_zlib, +BIO_f_brotli, +BIO_f_zstd +\&\- Compression support +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/comp.h> +\& +\& COMP_CTX *COMP_CTX_new(COMP_METHOD *meth); +\& void COMP_CTX_free(COMP_CTX *ctx); +\& const COMP_METHOD *COMP_CTX_get_method(const COMP_CTX *ctx); +\& int COMP_CTX_get_type(const COMP_CTX* comp); +\& int COMP_get_type(const COMP_METHOD *meth); +\& const char *COMP_get_name(const COMP_METHOD *meth); +\& +\& int COMP_compress_block(COMP_CTX *ctx, unsigned char *out, int olen, +\& unsigned char *in, int ilen); +\& int COMP_expand_block(COMP_CTX *ctx, unsigned char *out, int olen, +\& unsigned char *in, int ilen); +\& +\& COMP_METHOD *COMP_zlib(void); +\& COMP_METHOD *COMP_zlib_oneshot(void); +\& COMP_METHOD *COMP_brotli(void); +\& COMP_METHOD *COMP_brotli_oneshot(void); +\& COMP_METHOD *COMP_zstd(void); +\& COMP_METHOD *COMP_zstd_oneshot(void); +\& +\& const BIO_METHOD *BIO_f_zlib(void); +\& const BIO_METHOD *BIO_f_brotli(void); +\& const BIO_METHOD *BIO_f_zstd(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions provide compression support for OpenSSL. Compression is used within +the OpenSSL library to support TLS record and certificate compression. +.PP +\&\fBCOMP_CTX_new()\fR is used to create a new \fBCOMP_CTX\fR structure used to compress data. +.PP +\&\fBCOMP_CTX_free()\fR is used to free the returned \fBCOMP_CTX\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBCOMP_CTX_get_method()\fR returns the \fBCOMP_METHOD\fR of the given \fIctx\fR. +.PP +\&\fBCOMP_CTX_get_type()\fR and \fBCOMP_get_type()\fR return the NID for the \fBCOMP_CTX\fR and +\&\fBCOMP_METHOD\fR, respectively. \fBCOMP_get_name()\fR returns the name of the algorithm +of the given \fBCOMP_METHOD\fR. +.PP +\&\fBCOMP_compress_block()\fR compresses b<ilen> bytes from the buffer \fIin\fR into the +buffer b<out> of size \fIolen\fR using the algorithm specified by \fIctx\fR. +.PP +\&\fBCOMP_expand_block()\fR expands \fIilen\fR bytes from the buffer \fIin\fR into the +buffer \fIout\fR of size \fIolen\fR using the algorithm specified by \fIctx\fR. +.PP +Methods (\fBCOMP_METHOD\fR) may be specified by one of these functions. These functions +will be available even if their corresponding compression algorithm is not configured +into the OpenSSL library. In such a case, NULL will be returned. +.IP \(bu 4 +\&\fBCOMP_zlib()\fR returns a \fBCOMP_METHOD\fR for stream\-based ZLIB compression. +.IP \(bu 4 +\&\fBCOMP_zlib_oneshot()\fR returns a \fBCOMP_METHOD\fR for one\-shot ZLIB compression. +.IP \(bu 4 +\&\fBCOMP_brotli()\fR returns a \fBCOMP_METHOD\fR for stream\-based Brotli compression. +.IP \(bu 4 +\&\fBCOMP_brotli_oneshot()\fR returns a \fBCOMP_METHOD\fR for one\-shot Brotli compression. +.IP \(bu 4 +\&\fBCOMP_zstd()\fR returns a \fBCOMP_METHOD\fR for stream\-based Zstandard compression. +.IP \(bu 4 +\&\fBCOMP_zstd_oneshot()\fR returns a \fBCOMP_METHOD\fR for one\-shot Zstandard compression. +.PP +\&\fBBIO_f_zlib()\fR, \fBBIO_f_brotli()\fR \fBBIO_f_zstd()\fR each return a \fBBIO_METHOD\fR that may be used to +create a \fBBIO\fR via \fBBIO_new\|(3)\fR to read and write compressed files or streams. +The functions are only available if the corresponding algorithm is compiled into +the OpenSSL library. NULL may be returned if the algorithm fails to load dynamically. +.SH NOTES +.IX Header "NOTES" +While compressing non\-compressible data, the output may be larger than the +input. Care should be taken to size output buffers appropriate for both +compression and expansion. +.PP +Compression support and compression algorithms must be enabled and built into +the library before use. Refer to the INSTALL.md file when configuring OpenSSL. +.PP +ZLIB may be found at <https://zlib.net> +.PP +Brotli may be found at <https://github.com/google/brotli>. +.PP +Zstandard may be found at <https://github.com/facebook/zstd>. +.PP +Compression of SSL/TLS records is not recommended, as it has been +shown to lead to the CRIME attack <https://en.wikipedia.org/wiki/CRIME>. +It is disabled by default, and may be enabled by clearing the +SSL_OP_NO_COMPRESSION option and setting the security level as appropriate. +See the documentation for the \fBSSL_CTX_set_options\fR\|(3) and +\&\fBSSL_set_options\fR\|(3) functions. +.PP +Compression is also used to support certificate compression as described +in RFC8879 <https://datatracker.ietf.org/doc/html/rfc8879>. +It may be disabled via the SSL_OP_NO_TX_CERTIFICATE_COMPRESSION and +SSL_OP_NO_RX_CERTIFICATE_COMPRESSION options of the +\&\fBSSL_CTX_set_options\fR\|(3) or \fBSSL_set_options\fR\|(3) functions. +.PP +\&\fBCOMP_zlib()\fR, \fBCOMP_brotli()\fR and \fBCOMP_zstd()\fR are stream\-based compression methods. +Internal state (including compression dictionary) is maintained between calls. +If an error is returned, the stream is corrupted, and should be closed. +.PP +\&\fBCOMP_zlib_oneshot()\fR, \fBCOMP_brotli_oneshot()\fR and \fBCOMP_zstd_oneshot()\fR are not stream\-based. These +methods do not maintain state between calls. An error in one call does not affect +future calls. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCOMP_CTX_new()\fR returns a \fBCOMP_CTX\fR on success, or NULL on failure. +.PP +\&\fBCOMP_CTX_get_method()\fR, \fBCOMP_zlib()\fR, \fBCOMP_zlib_oneshot()\fR, \fBCOMP_brotli()\fR, \fBCOMP_brotli_oneshot()\fR, +\&\fBCOMP_zstd()\fR, and \fBCOMP_zstd_oneshot()\fR return a \fBCOMP_METHOD\fR on success, +or NULL on failure. +.PP +\&\fBCOMP_CTX_get_type()\fR and \fBCOMP_get_type()\fR return a NID value. On failure, +NID_undef is returned. +.PP +\&\fBCOMP_compress_block()\fR and \fBCOMP_expand_block()\fR return the number of +bytes stored in the output buffer \fIout\fR. This may be 0. On failure, +\&\-1 is returned. +.PP +\&\fBCOMP_get_name()\fR returns a \fBconst char *\fR that must not be freed +on success, or NULL on failure. +.PP +\&\fBBIO_f_zlib()\fR, \fBBIO_f_brotli()\fR and \fBBIO_f_zstd()\fR return NULL on error, and +a \fBBIO_METHOD\fR on success. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_new\fR\|(3), \fBSSL_CTX_set_options\fR\|(3), \fBSSL_set_options\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +Brotli and Zstandard functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (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 +<https://www.openssl.org/source/license.html>. |