TransportSecurity

class TransportSecurity : public std::enable_shared_from_this<TransportSecurity>

Manages the configuration and enforcement of TLS security settings for secure communication.

This class provides functionalities for managing certificates, configuring TLS settings, enforcing secure communication protocols, and handling TLS-related events. It is designed to ensure secure transport protocols are adhered to, supporting features like cipher suite customization, session renegotiation intervals, and restricting communication to trusted parties.

Public Functions

~TransportSecurity()

Destructor for the TransportSecurity class.

Clean up the TLS configuration structures

void setCertificate(const std::string &cert, const std::string &key, const std::string &passphrase = "")

load x509 certificate from file with (optional encrypted) key from file used to encrypt the connection

Parameters:

  • cert – path to certificate file

  • key – path to certificate private key file

  • passphrase – passphrase to decrypt the certificate private key

Throws:

std::invalid_argument – if loading the certificate, the key or decrypting the key fails

void setCACertificate(const std::string &cert)

load x509 certificate of trusted authority from file

Parameters:

cert – path to certificate file

Throws:

std::invalid_argument – if loading the certificate fails

void setCipherSuites(const std::vector<TLSCipherSuite> &ciphers)

Set the list of allowed TLS cipher suites for communication.

Parameters:

ciphers – A vector of TLSCipherSuite representing the allowed cipher suites.

Throws:

std::invalid_argument – if the configuration has already been finalized or if the provided cipher list is empty.

void setRenegotiationTime(const std::optional<std::chrono::milliseconds> &interval)

Set the interval for automatic TLS session renegotiation.

Parameters:

interval – The desired renegotiation interval in milliseconds. If no value is provided, automatic renegotiation is disabled by default.

Throws:

std::invalid_argument – if the configuration has already been passed to a client or server and can no longer be modified.

void setResumptionInterval(const std::optional<std::chrono::seconds> &interval)

Set the interval for session resumption in TLS configuration.

Parameters:

interval – The desired session resumption interval in seconds. If no value is provided, session resumption is disabled.

Throws:

std::invalid_argument – if the configuration has already been finalized or made read-only.

void addAllowedRemoteCertificate(const std::string &cert)

add a trusted communication partners x509 certificate from file

Parameters:

cert – path to certificate file

Throws:

std::invalid_argument – if loading the certificate fails

void setVersion(TLSConfigVersion min = TLS_VERSION_NOT_SELECTED, TLSConfigVersion max = TLS_VERSION_NOT_SELECTED)

set the supported min and/or max TLS version

Parameters:

  • min – minimum required TLS version for communication

  • max – maximum allowed TLS version for communication

TLSConfiguration get()

Retrieves the current TLS configuration for use by client and server instances.

Invoking this method transitions the associated TransportSecurity object to a readonly state. This transition is required because the client and server will invoke setupComplete, after which modifications are no longer allowed.

Returns:

The current TLSConfiguration object containing the TLS security settings.

inline std::string toString() const

Converts the TransportSecurity object to its string representation.

This method generates a string containing the memory address of the TransportSecurity object. Useful for debugging and logging purposes.

Returns:

A string describing the TransportSecurity object, including its memory address.

Public Static Functions

static inline std::shared_ptr<TransportSecurity> create(bool validate = true, bool only_known = true)

Creates a new instance of the TransportSecurity object with the specified configuration.

Parameters:

  • validate – Whether to enable validation for the TransportSecurity instance. Default is true.

  • only_known – Whether to restrict communication to only known and trusted certificates. Default is true.

Returns:

A shared pointer to the newly created TransportSecurity instance.

static void eventHandler(void *parameter, TLSEventLevel eventLevel, int eventCode, const char *msg, TLSConnection con)

Handles TLS-related events during the TransportSecurity lifetime.

Parameters:

  • parameter – A pointer to user-defined data or context associated with the event.

  • eventLevel – The severity level of the TLS event.

  • eventCode – A code representing the specific type of TLS event.

  • msg – A descriptive message providing details about the event.

  • con – The associated TLS connection instance for the event.