MQTTAsync_SSLOptions(3)

💖 MQTTAsync_SSLOptions(3) 💖

okay bestie, so this is a page from the Library Functions Manual, and the whole thing is about MQTTAsync_SSLOptions — the struct that holds literally every knob you can twist for SSL/TLS stuff. no cap. ✨

---

✨ SYNOPSIS ✨

#include <MQTTAsync.h>

🎀 Data Fields

char struct_id [4]
int struct_version
const char * trustStore
const char * keyStore
const char * privateKey
const char * privateKeyPassword
const char * enabledCipherSuites
int enableServerCertAuth
int sslVersion
int verify
const char * CApath
int(* ssl_error_cb )(const char *str, size_t len, void *u)
void * ssl_error_context
unsigned int(* ssl_psk_cb )(const char *hint, char *identity, unsigned
    int max_identity_len, unsigned char *psk, unsigned int max_psk_len,
    void *u)
void * ssl_psk_context
int disableDefaultTrustStore
const unsigned char * protos
unsigned int protos_len

---

🌸 Detailed Description 🌸

MQTTAsync_sslProperties is the vibe-setter for your SSL/TLS connection when you're rolling with the OpenSSL library. it's giving customization. 💅 it covers these scenarios:

• Server authentication 🛡️ — your client needs the server's digital certificate, and that cert lives in a store full of trusted material (we call it a "trust store", cute right?).
• Mutual authentication 🤝 — both client and server get authenticated during the SSL handshake. so besides the server's digital certificate sitting in the trust store, your client also needs its own digital certificate and the private key used to sign that digital certificate, and those two hang out in a "key store".
• Anonymous connection 🫥 — neither side gets authenticated, no credentials needed at all to establish the SSL connection. > heads up bestie: this scenario is not fully secure, because it's subject to man-in-the-middle attacks. 😭 not the vibe you want in prod.

---

👑 Field Documentation 👑

char struct_id[4]

the eyecatcher for this structure. must be MQTS. no substitutes, periodt.

int struct_version

the version number of this structure. must be 0, 1, 2, 3, 4 or 5.

• 0 means no sslVersion
• 1 means no verify, CApath
• 2 means no ssl_error_context, ssl_error_cb
• 3 means no ssl_psk_cb, ssl_psk_context, disableDefaultTrustStore
• 4 means no protos, protos_len

const char* trustStore

the file in PEM format holding the public digital certificates that your client trusts. 🫶

const char* keyStore

the file in PEM format holding the public certificate chain of the client. it may also include the client's private key. two-for-one, iconic.

const char* privateKey

if it's not included in the sslKeyStore, this setting points at the file in PEM format that has the client's private key. 🔑

const char* privateKeyPassword

the password to load the client's privateKey if it's encrypted. 🤫

const char* enabledCipherSuites

the list of cipher suites your client will present to the server during the SSL handshake. for a full explanation of the cipher list format, please see the OpenSSL on-line documentation:

http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT

if this setting is ommitted, its default value will be "ALL", that is, all the cipher suites -excluding those offering no encryption- will be considered. this setting can be used to set an SSL anonymous connection (the "aNULL" string value, for instance). 🦋

int enableServerCertAuth

a True/False option to enable verification of the server certificate. ⭐

int sslVersion

the SSL/TLS version to use. specify one of MQTT_SSL_VERSION_DEFAULT (0), MQTT_SSL_VERSION_TLS_1_0 (1), MQTT_SSL_VERSION_TLS_1_1 (2) or MQTT_SSL_VERSION_TLS_1_2 (3). only used if struct_version is >= 1. 🌈

int verify

whether to carry out post-connect checks, including that a certificate matches the given host name. exists only if struct_version >= 2. 🔍

const char* CApath

from the OpenSSL documentation: if CApath is not NULL, it points to a directory containing CA certificates in PEM format. exists only if struct_version >= 2. 🎀

int(* ssl_error_cb) (const char *str, size_t len, void *u)

callback function for the OpenSSL error handler ERR_print_errors_cb. exists only if struct_version >= 3. 😭 (you'll be glad it's there)

void* ssl_error_context

application-specific contex for the OpenSSL error handler ERR_print_errors_cb. exists only if struct_version >= 3.

unsigned int(* ssl_psk_cb) (const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len, void *u)

callback function for setting TLS-PSK options. the parameters correspond to that of SSL_CTX_set_psk_client_callback, except for u, which is the pointer ssl_psk_context. exists only if struct_version >= 4. 🔐

void* ssl_psk_context

application-specific contex for ssl_psk_cb. exists only if struct_version >= 4.

int disableDefaultTrustStore

don't load the default SSL CA. should be used together with PSK to make sure regular servers with a certificate in place is not accepted. exists only if struct_version >= 4. 🙈

const unsigned char* protos

the protocol-lists must be in wire-format, which is defined as a vector of non-empty, 8-bit length-prefixed, byte strings. the length-prefix byte is not included in the length. each string is limited to 255 bytes. a byte-string length of 0 is invalid. a truncated byte-string is invalid. check documentation for SSL_CTX_set_alpn_protos. exists only if struct_version >= 5. 🧚

unsigned int protos_len

the length of the vector protos vector. exists only if struct_version >= 5. 📏

---

💜 Author 💜

Generated automatically by Doxygen for Paho Asynchronous MQTT C Client Library from the source code.

---

okay and for the lil sign-off moment: this whole page came out of the Paho Asynchronous MQTT C Client Library manual (the Paho Asynchronous MQTT C... bit at the bottom, dated Tue Jun 2 2026 00:00:00), so that's your source and your date, bestie. go forth and configure your TLS 💖✨🦋