MQTTClient_SSLOptions(3)

💖 MQTTClient_SSLOptions(3) 💖

okay bestie, gather round, because this one is from the Library Functions Manual and it's literally the blueprint for making your MQTT client talk TLS without getting clowned on. this is the MQTTClient_SSLOptions page, and yes it is as iconic as it sounds. 🎀

---

✨ NAME ✨

MQTTClient_SSLOptions — the struct that holds all your SSL/TLS settings, no cap

---

✨ SYNOPSIS ✨

#include <MQTTClient.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 🌈

so MQTTClient_sslProperties is the whole vibe-check list of settings you need to establish an SSL/TLS connection using the OpenSSL library. it covers these three scenarios, and they are not the same energy:

• Server authentication 💅 — your client needs the digital certificate of the server. it lives in a store containing trusted material (also known as a "trust store", cute name honestly).
• Mutual authentication 🤝 — both client and server get authenticated during the SSL handshake. so on top of the server's digital certificate sitting in a trust store, the client also needs its own digital certificate, plus the private key used to sign its digital certificate, all stored in a "key store".
• Anonymous connection 🙈 — neither client nor server gets authenticated, and no credentials are needed to establish an SSL connection. note that this scenario is not fully secure, because it is subject to man-in-the-middle attacks. like, it's giving exposed. be careful.

---

🦋 Field Documentation 🦋

💜 char struct_id[4]

the eyecatcher for this structure. it must be MQTS. that's it, that's the whole job, it's the little name tag so the struct knows who it is.

💜 int struct_version

the version number of this structure. it must be 0, 1, 2, 3, 4 or 5. and here's the breakdown of what each one is missing:

• 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 containing the public digital certificates trusted by the client. this is your trust store, your ride-or-die list of who's allowed in. 🫶

💜 const char* keyStore

the file in PEM format containing the public certificate chain of the client. it may also include the client's private key, which is lowkey convenient but do keep track of it.

💜 const char* privateKey

if it's not included in the sslKeyStore, this setting points to the file in PEM format containing the client's private key. it's giving "you left it at home so here's the address". 🏠

💜 const char* privateKeyPassword

the password to load the client's privateKey if it's encrypted. yes bestie, secrets get locked up sometimes.

💜 const char* enabledCipherSuites

the list of cipher suites that the 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 omitted, 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

True/False option to enable verification of the server certificate. like a bouncer checking IDs at the door. 👑

💜 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)
• 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. ✨

💜 void* ssl_error_context

application-specific context 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 context 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 are 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 the documentation for SSL_CTX_set_alpn_protos. exists only if struct_version >= 5. 😭 (yes, all of that. read it twice.)

💜 unsigned int protos_len

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

---

🌟 Author 🌟

generated automatically by Doxygen for Paho MQTT C Client Library from the source code. shoutout to the robot that wrote this, it ate and left no crumbs. 🤖💅

---

and that's the whole page bestie!! go forth and TLS responsibly 🧚🌸

okay bye, this was Paho MQTT C Client Library, dated Tue Jun 2 2026 00:00:00, and it remains MQTTClient_SSLOptions(3) forever and ever, periodt. 💖✨🎀