Android_verify/third_party/android-libs/share/man/man3/COMP_CTX_new.3ossl

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "COMP_CTX_NEW 3ossl"
.TH COMP_CTX_NEW 3ossl "2024-09-03" "3.3.2" "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 \s-1TLS\s0 record and certificate compression.
.PP
\&\fBCOMP_CTX_new()\fR is used to create a new \fB\s-1COMP_CTX\s0\fR structure used to compress data.
.PP
\&\fBCOMP_CTX_free()\fR is used to free the returned \fB\s-1COMP_CTX\s0\fR.
If the argument is \s-1NULL,\s0 nothing is done.
.PP
\&\fBCOMP_CTX_get_method()\fR returns the \fB\s-1COMP_METHOD\s0\fR of the given \fIctx\fR.
.PP
\&\fBCOMP_CTX_get_type()\fR and \fBCOMP_get_type()\fR return the \s-1NID\s0 for the \fB\s-1COMP_CTX\s0\fR and
\&\fB\s-1COMP_METHOD\s0\fR, respectively. \fBCOMP_get_name()\fR returns the name of the algorithm
of the given \fB\s-1COMP_METHOD\s0\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 (\fB\s-1COMP_METHOD\s0\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, \s-1NULL\s0 will be returned.
.IP "\(bu" 4
\&\fBCOMP_zlib()\fR returns a \fB\s-1COMP_METHOD\s0\fR for stream-based \s-1ZLIB\s0 compression.
.IP "\(bu" 4
\&\fBCOMP_zlib_oneshot()\fR returns a \fB\s-1COMP_METHOD\s0\fR for one-shot \s-1ZLIB\s0 compression.
.IP "\(bu" 4
\&\fBCOMP_brotli()\fR returns a \fB\s-1COMP_METHOD\s0\fR for stream-based Brotli compression.
.IP "\(bu" 4
\&\fBCOMP_brotli_oneshot()\fR returns a \fB\s-1COMP_METHOD\s0\fR for one-shot Brotli compression.
.IP "\(bu" 4
\&\fBCOMP_zstd()\fR returns a \fB\s-1COMP_METHOD\s0\fR for stream-based Zstandard compression.
.IP "\(bu" 4
\&\fBCOMP_zstd_oneshot()\fR returns a \fB\s-1COMP_METHOD\s0\fR for one-shot Zstandard compression.
.PP
\&\fBBIO_f_zlib()\fR, \fBBIO_f_brotli()\fR \fBBIO_f_zstd()\fR each return a \fB\s-1BIO_METHOD\s0\fR that may be used to
create a \fB\s-1BIO\s0\fR via \fB\fBBIO_new\fB\|(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. \s-1NULL\s0 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 \s-1INSTALL\s0.md file when configuring OpenSSL.
.PP
\&\s-1ZLIB\s0 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 \s-1SSL/TLS\s0 records is not recommended, as it has been
shown to lead to the \s-1CRIME\s0 attack <https://en.wikipedia.org/wiki/CRIME>.
It is disabled by default, and may be enabled by clearing the
\&\s-1SSL_OP_NO_COMPRESSION\s0 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 \s-1RFC8879\s0 <https://datatracker.ietf.org/doc/html/rfc8879>.
It may be disabled via the \s-1SSL_OP_NO_TX_CERTIFICATE_COMPRESSION\s0 and
\&\s-1SSL_OP_NO_RX_CERTIFICATE_COMPRESSION\s0 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 \fB\s-1COMP_CTX\s0\fR on success, or \s-1NULL\s0 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 \fB\s-1COMP_METHOD\s0\fR on success,
or \s-1NULL\s0 on failure.
.PP
\&\fBCOMP_CTX_get_type()\fR and \fBCOMP_get_type()\fR return a \s-1NID\s0 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 \s-1NULL\s0 on failure.
.PP
\&\fBBIO_f_zlib()\fR, \fBBIO_f_brotli()\fR and \fBBIO_f_zstd()\fR return \s-1NULL\s0 on error, and
a \fB\s-1BIO_METHOD\s0\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 \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.