doc/man3/COMP_CTX_new.pod

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