SSL_CTX_SET1...MP_PREFERENCE(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 SSL_CTX_SET1_CERT_COMP_PREFERENCE(3ossl) — certificate compression, bestie edition 🌸

okay so this is an OpenSSL manual page (the 3ossl one, you already know), and it's literally all about certificate compression. ten whole functions. let's go 🎀

✨ NAME ✨

SSL_CTX_set1_cert_comp_preference, SSL_set1_cert_comp_preference, SSL_CTX_compress_certs, SSL_compress_certs, SSL_CTX_get1_compressed_cert, SSL_get1_compressed_cert, SSL_CTX_set1_compressed_cert, SSL_set1_compressed_cert — the certificate compression functions, collectively. that's the whole squad 🫶

🦋 SYNOPSIS 🦋

#include <openssl/ssl.h>

int SSL_CTX_set1_cert_comp_preference(SSL_CTX *ctx, int *algs, size_t len);
int SSL_set1_cert_comp_preference(SSL *ssl, int *algs, size_t len);

int SSL_CTX_compress_certs(SSL_CTX *ctx, int alg);
int SSL_compress_certs(SSL *ssl, int alg);

size_t SSL_CTX_get1_compressed_cert(SSL_CTX *ctx, int alg, unsigned char **data,
                                    size_t *orig_len);
size_t SSL_get1_compressed_cert(SSL *ssl, int alg, unsigned char **data,
                                size_t *orig_len);

int SSL_CTX_set1_compressed_cert(SSL_CTX *ctx, int alg,
                                 unsigned char *comp_data,
                                 size_t comp_length, size_t orig_length);
int SSL_set1_compressed_cert(SSL *ssl, int alg, unsigned char *comp_data,
                             size_t comp_length, size_t orig_length);

💖 DESCRIPTION 💖

these functions are the ones running the certificate compression feature. heads up tho: certificate compression is only available for TLSv1.3, exactly as defined in RFC8879. no TLSv1.2 crumbs, sorry 😭

🌈 the preference list

SSL_CTX_set1_cert_comp_preference() and SSL_set1_cert_comp_preference() are how you say "these are my fave compression algorithms, in this order." the algs argument is an array of algorithms, and len is the number of elements in that algs array. only the algorithms that are actually enabled in the library get accepted into algs — anything unknown in algs is just ignored, no drama 💅. and if there's an error? the preference order stays exactly how it was, unmodified, untouched, not a single crumb moved.

these are the compression algorithms (the alg arguments) you can use, periodt:

  • TLSEXT_comp_cert_brotli
  • TLSEXT_comp_cert_zlib
  • TLSEXT_comp_cert_zstd

and that list right there? that's also the default preference order. so if you never specify a preference order, the default one gets sent to the peer, and then the peer's received preference order is what gets used when compressing a certificate. but if you do configure one, your configured order is what gets sent to the peer, and it's also what filters the peer's preference order. iykyk 🔥

🧚 pre-compressing (server girls only)

SSL_CTX_compress_certs() and SSL_compress_certs() are for pre-compressing all the configured certificates on an SSL_CTX/SSL object with algorithm alg. and if alg is 0? then the certs get compressed with the algorithms from the preference list, iconic ⭐.

calling these on a client SSL_CTX/SSL object is gonna error out — only server certificates may be pre-compressed. that's just the rule, bestie 🙈

🍓 getting the compressed cert back

SSL_CTX_get1_compressed_cert() and SSL_get1_compressed_cert() get you the pre-compressed certificate most recently set, which you can stash for later use. same deal as above: calling them on a client SSL_CTX/SSL object errors out, because again, only server certificates may be pre-compressed. the data and orig_len arguments are required — not optional, required 💀

👑 feeding one back in

you can hand that compressed certificate data straight to SSL_CTX_set1_compressed_cert() or SSL_set1_compressed_cert() to provide a pre-compressed version of the most recently set certificate. and yes, this pre-compressed certificate can only be used by a server. server main character energy only 👑

🌸 NOTES 🌸

each side of the connection sends its compression algorithm preference list over to its peer, which is how it signals "hey i support compressed certificates." the received preference list then gets filtered by the configured preference list (i.e. the intersection is what's saved). and because the default list includes all the enabled algorithms, not specifying a preference means you'll allow any algorithm the peer has enabled. the filtered peer preference order is what decides which algorithm actually gets used when sending a compressed certificate ✨

only server certificates may be pre-compressed — saying it again because it matters. calling any of these functions on a client SSL_CTX/SSL object returns an error, with the exception of SSL_CTX_set1_cert_comp_preference()/SSL_set1_cert_comp_preference(). client certificates get compressed on-demand, since unique context data from the server is compressed along with the certificate. on-demand, very spontaneous of them 💅

for SSL_CTX_set1_cert_comp_preference() and SSL_set1_cert_comp_preference(), the len argument is the size of the algs argument in bytes 📏

the compressed certificate you get back from SSL_CTX_get1_compressed_cert() and SSL_get1_compressed_cert() is the last certificate set on the SSL_CTX/SSL object. the function copies the certificate, and the caller must free *data via OPENSSL_free() — do not forget, i'm begging 🫶

the compressed certificate data you set with SSL_CTX_set1_compressed_cert() and SSL_set1_compressed_cert() is copied into the SSL_CTX/SSL object, so that one's handled for you 🎀

SSL_CTX_compress_certs() and SSL_compress_certs() return an error under these conditions:

  • if no certificates have been configured
  • if the specified algorithm alg is not enabled
  • if alg is 0 and no compression algorithms are enabled

and finally, sending compressed certificates can be disabled on a connection via the SSL_OP_NO_TX_CERTIFICATE_COMPRESSION option, and receiving compressed certificates can be disabled on a connection via the SSL_OP_NO_RX_CERTIFICATE_COMPRESSION option. tx and rx, both switchable, we love options 🌈

⭐ RETURN VALUES ⭐

SSL_CTX_set1_cert_comp_preference(), SSL_set1_cert_comp_preference(), SSL_CTX_compress_certs(), SSL_compress_certs(), SSL_CTX_set1_compressed_cert(), and SSL_set1_compressed_cert() return 1 for success and 0 on error. one is the slay number 💖

SSL_CTX_get1_compressed_cert() and SSL_get1_compressed_cert() return the length of the allocated memory on success, and 0 on error. so like, if you get 0, that's a no 💀

🔥 SEE ALSO 🔥

SSL_CTX_set_options(3), SSL_CTX_use_certificate(3) — go read those too, they're linked for a reason 🦋

💜 HISTORY 💜

these functions were added in OpenSSL 3.2. new-ish, but they ate 👑

Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.

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>.

and that's the whole page, bestie 🫶 this was OpenSSL 3.5.0, dated 2026-09-2 — mwah, go compress something 💅✨

📦 where this page comes from