SSL_CTX_SET1...MP_PREFERENCE(3SSL)

📦

version 4.0.3 · 6 versions

💖 SSL_CTX_SET1...MP_PREFERENCE(3SSL) — the OpenSSL girls' guide to certificate compression 💖

okay bestie, sit down, hydrate, and let me tell you about the eight functions that let you squeeze certificates like you're packing for a flight with only a personal item. this is OpenSSL, this is manual page 3SSL, and this one is literally all about certificate compression. 🎀

✨ 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 — Certificate compression functions. yes, that's eight (8) whole functions, we are FED today. 💅

🌸 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);

notice how every one of these comes in a duo: one flavor that takes an SSL_CTX *ctx and one that takes an SSL *ssl. it's giving twin energy, it's giving "we do everything twice". iykyk ✨

🦋 DESCRIPTION 🦋

so these functions are the whole control panel for the certificate compression feature. and listen, this is only available for TLSv1.3, as defined in RFC8879. no TLSv1.2 sneaking in here, bestie, the door is closed. 🚪

💫 setting your preference order

SSL_CTX_set1_cert_comp_preference() and SSL_set1_cert_comp_preference() are how you tell OpenSSL which compression algorithms you'd like, in what order. the algs argument is an array of algorithms, and length is the number of elements in the algs array.

only algorithms that are enabled in the library will be accepted in algs 🌈
unknown algorithms in algs are just... ignored 🙈
on an error, the preference order is left unmodified — nothing gets half-written, we love a clean rollback ✨

🎀 the algorithms (the `alg` arguments)

the following compression algorithms may be used:

TLSEXT_comp_cert_brotli
TLSEXT_comp_cert_zlib
TLSEXT_comp_cert_zstd

and plot twist: that's also the default preference order. 👑

if you don't specify a preference order, the default preference order is sent to the peer, and the received peer's preference order will be used when compressing a certificate. otherwise (i.e. if you did configure one), your configured preference order is sent to the peer and is used to filter the peer's preference order. so it's not "my way or the highway", it's a collab. 🫶

🔥 pre-compressing everything

SSL_CTX_compress_certs() and SSL_compress_certs() are used to pre-compress all the configured certificates on an SSL_CTX/SSL object with algorithm alg.

if alg is 0, then the certificates are compressed with the algorithms specified in the preference list
calling these on a client SSL_CTX/SSL object will result in an error, because only server certificates may be pre-compressed 💀

🍓 getting the pre-compressed cert back

SSL_CTX_get1_compressed_cert() and SSL_get1_compressed_cert() are used to get the pre-compressed certificate most recently set, that may be stored for later use.

calling these on a client SSL_CTX/SSL object will result in an error, again because only server certificates may be pre-compressed 😤
the data and orig_len arguments are required. no cap.

💜 shoving your own compressed bytes in

the compressed certificate data may be passed to SSL_CTX_set1_compressed_cert() or SSL_set1_compressed_cert() to provide a pre-compressed version of the most recently set certificate. this pre-compressed certificate can only be used by a server. periodt. 👑

🌈 NOTES 🌈

each side of the connection sends their compression algorithm preference list to their peer, indicating compressed certificate support. the received preference list is filtered by the configured preference list (i.e. the intersection is saved — set math, but make it TLS ✨).

and because the default list includes all the enabled algorithms, not specifying a preference will allow any enabled algorithm by the peer. the filtered peer's preference order is what determines which algorithm gets used when sending a compressed certificate. it's a whole negotiation arc, honestly.

⚠️ only server certificates may be pre-compressed. calling any of these functions — except SSL_CTX_set1_cert_comp_preference()/SSL_set1_cert_comp_preference() — on a client SSL_CTX/SSL object will return an error. client certificates are compressed on-demand, because unique context data from the server gets compressed along with the certificate. 🧚

okay but here's a lil gotcha that trips people UP:

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. 🫠 yes, bytes.

the compressed certificate returned by SSL_CTX_get1_compressed_cert() and SSL_get1_compressed_cert() is the last certificate set on the SSL_CTX/SSL object. the certificate is copied by the function, and the caller must free *data via OPENSSL_free(). do not forget this. do not ghost the free. 👻

the compressed certificate data set by SSL_CTX_set1_compressed_cert() and SSL_set1_compressed_cert() is copied into the SSL_CTX/SSL object. so your buffer is yours, bestie, it gets a lil clone. 💅

💀 `SSL_CTX_compress_certs()` and `SSL_compress_certs()` return an error when:

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

🚦 turning compression on and off

sending compressed certificates may be disabled on a connection via the SSL_OP_NO_TX_CERTIFICATE_COMPRESSION option
receiving compressed certificates may be disabled on a connection via the SSL_OP_NO_RX_CERTIFICATE_COMPRESSION option

tx and rx, send and receive, the iconic duo 🫶

⭐ RETURN VALUES ⭐

so here's the scoreboard:

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. classic bool-coded behavior.
SSL_CTX_get1_compressed_cert() and SSL_get1_compressed_cert() return the length of the allocated memory on success and 0 on error. giving main character energy with that size return. ✨

👀 SEE ALSO 👀

go read those next, bestie, they're in the same universe 🌸

📜 HISTORY 📜

these functions were added in OpenSSL 3.2. new-ish, but already iconic. 💜

💖 COPYRIGHT 💖

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

okay that's the whole page, you ate it, no crumbs 🍓 this was written against OpenSSL 4.0.3, dated 2026-09-29 — she's fresh, she's fine, she's sourced straight from the OpenSSL project. now go compress something responsibly, and remember: free your *data with OPENSSL_free(). mwah 💅✨

</bold> </bold> </bold>

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

SSL_CTX_SET1...MP_PREFERENCE(3SSL)