doc/man3/SSL_CTX_set1_cert_comp_preference.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CTX_set1_cert_comp_preference,
   6 SSL_set1_cert_comp_preference,
   7 SSL_CTX_compress_certs,
   8 SSL_compress_certs,
   9 SSL_CTX_get1_compressed_cert,
  10 SSL_get1_compressed_cert,
  11 SSL_CTX_set1_compressed_cert,
  12 SSL_set1_compressed_cert - Certificate compression functions
  13
  14 =head1 SYNOPSIS
  15
  16  #include <openssl/ssl.h>
  17
  18  int SSL_CTX_set1_cert_comp_preference(SSL_CTX *ctx, int *algs, size_t len);
  19  int SSL_set1_cert_comp_preference(SSL *ssl, int *algs, size_t len);
  20
  21  int SSL_CTX_compress_certs(SSL_CTX *ctx, int alg);
  22  int SSL_compress_certs(SSL *ssl, int alg);
  23
  24  size_t SSL_CTX_get1_compressed_cert(SSL_CTX *ctx, int alg, unsigned char **data,
  25                                      size_t *orig_len);
  26  size_t SSL_get1_compressed_cert(SSL *ssl, int alg, unsigned char **data,
  27                                  size_t *orig_len);
  28
  29  int SSL_CTX_set1_compressed_cert(SSL_CTX *ctx, int alg,
  30                                   unsigned char *comp_data,
  31                                   size_t comp_length, size_t orig_length);
  32  int SSL_set1_compressed_cert(SSL *ssl, int alg, unsigned char *comp_data,
  33                               size_t comp_length, size_t orig_length);
  34
  35
  36 =head1 DESCRIPTION
  37
  38 These functions control the certificate compression feature. Certificate
  39 compression is only available for TLSv1.3 as defined in RFC8879.
  40
  41 SSL_CTX_set1_cert_comp_preference() and SSL_set1_cert_comp_preference() are used
  42 to specify the preferred compression algorithms. The B<algs> argument is an array
  43 of algorithms, and B<length> is number of elements in the B<algs> array. Only
  44 those algorithms enabled in the library will be accepted in B<algs>, unknown
  45 algorithms in B<algs> are ignored. On an error, the preference order is left
  46 unmodified.
  47
  48 The following compression algorithms (B<alg> arguments) may be used:
  49
  50 =over 4
  51
  52 =item * TLSEXT_comp_cert_brotli
  53
  54 =item * TLSEXT_comp_cert_zlib
  55
  56 =item * TLSEXT_comp_cert_zstd
  57
  58 =back
  59
  60 The above is also the default preference order. If a preference order is not
  61 specified, then the default preference order is sent to the peer and the
  62 received peer's preference order will be used when compressing a certificate.
  63 Otherwise, the configured preference order is sent to the peer and is used
  64 to filter the peer's preference order.
  65
  66 SSL_CTX_compress_certs() and SSL_compress_certs() are used to pre-compress all
  67 the configured certificates on an SSL_CTX/SSL object with algorithm B<alg>. If
  68 B<alg> is 0, then the certificates are compressed with the algorithms specified
  69 in the preference list. Calling these functions on a client SSL_CTX/SSL object
  70 will result in an error, as only server certificates may be pre-compressed.
  71
  72 SSL_CTX_get1_compressed_cert() and SSL_get1_compressed_cert() are used to get
  73 the pre-compressed certificate most recently set that may be stored for later
  74 use. Calling these functions on a client SSL_CTX/SSL object will result in an
  75 error, as only server certificates may be pre-compressed. The B<data> and
  76 B<orig_len> arguments are required.
  77
  78 The compressed certificate data may be passed to SSL_CTX_set1_compressed_cert()
  79 or SSL_set1_compressed_cert() to provide a pre-compressed version of the
  80 most recently set certificate. This pre-compressed certificate can only be used
  81 by a server.
  82
  83 =head1 NOTES
  84
  85 Each side of the connection sends their compression algorithm preference list
  86 to their peer indicating compressed certificate support. The received preference
  87 list is filtered by the configured preference list (i.e. the intersection is
  88 saved). As the default list includes all the enabled algorithms, not specifying
  89 a preference will allow any enabled algorithm by the peer. The filtered peer's
  90 preference order is used to determine what algorithm to use when sending a
  91 compressed certificate.
  92
  93 Only server certificates may be pre-compressed. Calling any of these functions
  94 (except SSL_CTX_set1_cert_comp_preference()/SSL_set1_cert_comp_preference())
  95 on a client SSL_CTX/SSL object will return an error. Client certificates are
  96 compressed on-demand as unique context data from the server is compressed along
  97 with the certificate.
  98
  99 For SSL_CTX_set1_cert_comp_preference() and SSL_set1_cert_comp_preference()
 100 the B<len> argument is the size of the B<algs> argument in bytes.
 101
 102 The compressed certificate returned by SSL_CTX_get1_compressed_cert() and
 103 SSL_get1_compressed_cert() is the last certificate set on the SSL_CTX/SSL object.
 104 The certificate is copied by the function and the caller must free B<*data> via
 105 OPENSSL_free().
 106
 107 The compressed certificate data set by SSL_CTX_set1_compressed_cert() and
 108 SSL_set1_compressed_cert() is copied into the SSL_CTX/SSL object.
 109
 110 SSL_CTX_compress_certs() and SSL_compress_certs() return an error under the
 111 following conditions:
 112
 113 =over 4
 114
 115 =item * If no certificates have been configured.
 116
 117 =item * If the specified algorithm B<alg> is not enabled.
 118
 119 =item * If B<alg> is 0 and no compression algorithms are enabled.
 120
 121 =back
 122
 123 Sending compressed certificates may be disabled on a connection via the
 124 SSL_OP_NO_TX_CERTIFICATE_COMPRESSION option. Receiving compressed certificates
 125 may be disabled on a connection via the SSL_OP_NO_RX_CERTIFICATE_COMPRESSION
 126 option.
 127
 128 =head1 RETURN VALUES
 129
 130 SSL_CTX_set1_cert_comp_preference(),
 131 SSL_set1_cert_comp_preference(),
 132 SSL_CTX_compress_certs(),
 133 SSL_compress_certs(),
 134 SSL_CTX_set1_compressed_cert(), and
 135 SSL_set1_compressed_cert()
 136 return 1 for success and 0 on error.
 137
 138 SSL_CTX_get1_compressed_cert() and
 139 SSL_get1_compressed_cert()
 140 return the length of the allocated memory on success and 0 on error.
 141
 142 =head1 SEE ALSO
 143
 144 L<SSL_CTX_set_options(3)>,
 145 L<SSL_CTX_use_certificate(3)>
 146
 147 =head1 HISTORY
 148
 149 These functions were added in OpenSSL 3.2.
 150
 151 =head1 COPYRIGHT
 152
 153 Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
 154
 155 Licensed under the Apache License 2.0 (the "License").  You may not use
 156 this file except in compliance with the License.  You can obtain a copy
 157 in the file LICENSE in the source distribution or at
 158 L<https://www.openssl.org/source/license.html>.
 159
 160 =cut