The rsocket_sni class provides a specialized interface for collecting a group of SNI (Server Name Identifier) contexts for TLS connections. More...

#include <randolf/rsocket_sni>

Collaboration diagram for randolf::rsocket_sni:

Public Member Functions
	rsocket_sni (SSL_CTX *ctx=nullptr, const bool is_server_method=true)
	Instantiate a new rsocket_sni object.

	~rsocket_sni () noexcept
	Destructor for rsocket_sni object, which deletes all SNI hostnames and their associated TLS contexts, updating OpenSSL's internal TLS context reference counters accordingly.

rsocket_sni &	add (const std::string &hostname)
	Add one new hostname, which will be associated with the current TLS context. SNI wildcards are supported (e.g., `*.example.com`).

template<class... Hs>
rsocket_sni &	add (const std::string &hostname, Hs... hostnames)
	Add one or more new hostnames, which will be associated with the current TLS context. SNI wildcards are supported (e.g., `*.example.com`).

rsocket_sni &	del (const std::string &hostname)
	Delete one hostname.

template<class... Hs>
rsocket_sni &	del (const std::string &hostname, Hs... hostnames)
	Delete one or more hostnames.

SSL_CTX *	get_ctx (const std::string &hostname, const bool enable_sni_wildcards=true, SSL_CTX *default_tls_ctx=nullptr)
	Return the TLS context for a given hostname. If any SNI wildcards satisfy hostname-matching criteria (e.g., `www.example.com` matches a `*.example.com` wildcard), the respective TLS context for it will be returned (as expected).

SSL_CTX *	tls_ctx () noexcept
	Find out what the current TLS context is set to.

rsocket_sni &	tls_ctx (SSL_CTX *ctx, const bool is_server_method=true)
	Set the current TLS context to a specific context or create a new one.

rsocket_sni &	tls_ctx_check_privatekey ()
	Check the private key it to ensure it's consistent with the corresponding TLS certificate chain.

rsocket_sni &	tls_ctx_use_certificate_chain_and_privatekey_files (const char chain_file, const char key_file)
	Load a TLS certificate chain and private key in PEM format from text files and use them in the TLS context.

rsocket_sni &	tls_ctx_use_certificate_chain_and_privatekey_files (const std::string &chain_file, const std::string &key_file)
	Load a TLS certificate chain and private key in PEM format from text files and use them in the TLS context.

rsocket_sni &	tls_ctx_use_certificate_chain_and_privatekey_pems (const char cert_pem_data, const char key_pem_data, size_t cert_len=0, size_t key_len=0, const bool random_fill=true)
	Load a TLS certificate chain and a TLS private key in PEM format from memory and use them in the TLS context.

rsocket_sni &	tls_ctx_use_certificate_chain_file (const char *file)
	Load a TLS certificate chain in PEM format from a text file and use it in the TLS context.

rsocket_sni &	tls_ctx_use_certificate_chain_file (const std::string &file)
	Load a TLS certificate chain in PEM format from a text file and use it in the TLS context.

rsocket_sni &	tls_ctx_use_certificate_chain_pem (const char *pem_data, size_t len=0, const bool random_fill=true)
	Load a TLS certificate chain in PEM format from memory and use it in the TLS context.

rsocket_sni &	tls_ctx_use_privatekey_file (const char *file)
	Load a TLS private key in PEM format from a text file and use it in the TLS context.

rsocket_sni &	tls_ctx_use_privatekey_file (const std::string &file)
	Load a TLS private key in PEM format from a text file and use it in the TLS context.

rsocket_sni &	tls_ctx_use_privatekey_pem (const char *pem_data, size_t len=0, const bool random_fill=true)
	Load a TLS private key in PEM format from memory and use it in the TLS context.

Detailed Description

The rsocket_sni class provides a specialized interface for collecting a group of SNI (Server Name Identifier) contexts for TLS connections.

Note: There's no maximum limit on the number of SNI entries that can be added (aside from system memory limits, of course).

Author: Randolf Richardson

Version: 1.00

History

2023-Mar-26 v1.00 Initial version
2024-Dec-28 v1.00 Minor improvements to internal documentation within the get_ctx method for easier future maintenance since SNI wildcard matching incurs significant degrees of complexity
2025-Feb-03 v1.00 Increased use of references and pointers

Constructor & Destructor Documentation

◆ rsocket_sni()

randolf::rsocket_sni::rsocket_sni	(	SSL_CTX *	ctx = nullptr,
		const bool	is_server_method = true )

inline

Instantiate a new rsocket_sni object.

See also: tls_ctx()

Parameters

ctx	OpenSSL's TLS context to use (if set to `nullptr`, this `rsocket's` TLS context will be paired with the specified hostname{s})
is_server_method	When `ctx` is `nullptr`, indicates whether to initialize the new TLS context with the `TLS_server_method()` or the `TLS_client_method()` function (the default is `true`, which is the .

◆ ~rsocket_sni()

randolf::rsocket_sni::~rsocket_sni ( )

inlinenoexcept

Destructor for rsocket_sni object, which deletes all SNI hostnames and their associated TLS contexts, updating OpenSSL's internal TLS context reference counters accordingly.

See also: del

Member Function Documentation

◆ add() [1/2]

rsocket_sni & randolf::rsocket_sni::add ( const std::string & hostname )

inline

Add one new hostname, which will be associated with the current TLS context. SNI wildcards are supported (e.g., *.example.com).

Note: If the specified hostname already exists, it will be updated with the newer TLS context because re-adding is accepted, by acclamation, as a replacement.

Returns: The same rsocket_sni object so as to facilitate stacking

See also: del; get_ctx; tls_ctx

Parameters

hostname Hostname to add

◆ add() [2/2]

template<class... Hs>

rsocket_sni & randolf::rsocket_sni::add	(	const std::string &	hostname,
		Hs...	hostnames )

inline

Add one or more new hostnames, which will be associated with the current TLS context. SNI wildcards are supported (e.g., *.example.com).

Note: If any specified hostnames already exist, they will be updated with the newer TLS context because re-adding is accepted, by acclamation, as a replacement.

Returns: The same rsocket_sni object so as to facilitate stacking

See also: del; get_ctx; tls_ctx

Parameters

hostname	First hostname (required)
hostnames	Additional hostnames (optional)

◆ del() [1/2]

rsocket_sni & randolf::rsocket_sni::del ( const std::string & hostname )

inline

Delete one hostname.

Note: If the specified hostname doesn't exist, nothing will happen.

Returns: The same rsocket_sni object so as to facilitate stacking

See also: add

Parameters

hostname Hostname to delete

◆ del() [2/2]

template<class... Hs>

rsocket_sni & randolf::rsocket_sni::del	(	const std::string &	hostname,
		Hs...	hostnames )

inline

Delete one or more hostnames.

Note: If any specified hostnames don't exist, then no deletion of them will occur.

Returns: The same rsocket_sni object so as to facilitate stacking

See also: add

Parameters

hostname	First hostname (required)
hostnames	Additional hostnames (optional)

◆ get_ctx()

SSL_CTX * randolf::rsocket_sni::get_ctx	(	const std::string &	hostname,
		const bool	enable_sni_wildcards = true,
		SSL_CTX *	default_tls_ctx = nullptr )

inline

Return the TLS context for a given hostname. If any SNI wildcards satisfy hostname-matching criteria (e.g., www.example.com matches a *.example.com wildcard), the respective TLS context for it will be returned (as expected).

For wildcard comparisons, OpenSSL's functions are used for matching to ensure consistency with what's expected, and in order to support any unforseen changes to future standards in wildcard naming rules. (In other words, we're relying on OpenSSL to do what it already does efficiently and correctly.)

Exact matches are always checked before wildcards because the exact matching algorithm is faster (uses fewer CPU cycles) than comparing wildcards.

Returns: TLS context, or nullptr (or default_tls_ctx override) if hostname doesn't match any SNI entries

See also: add

Parameters

hostname	Hostname
enable_sni_wildcards	SNI supports wildcards, but if an exact match is needed then setting this parameter to `false` will skip attempts to also match wildcards (the default is `true`)
default_tls_ctx	Override the default context `nullptr` that is returned to indicate that the hostname didn't match

◆ tls_ctx() [1/2]

SSL_CTX * randolf::rsocket_sni::tls_ctx ( )

inlinenoexcept

Find out what the current TLS context is set to.

Returns: TLS context

◆ tls_ctx() [2/2]

rsocket_sni & randolf::rsocket_sni::tls_ctx	(	SSL_CTX *	ctx,
		const bool	is_server_method = true )

inline

Set the current TLS context to a specific context or create a new one.

Returns: The same rsocket_sni object so as to facilitate stacking

Parameters

ctx	OpenSSL's TLS context to use (if set to `nullptr`, this `rsocket's` TLS context will be paired with the specified hostname{s})
is_server_method	When `ctx` is `nullptr`, indicates whether to initialize the new TLS context with the `TLS_server_method()`, which is the default. If set to `false`, then the `TLS_client_method()` function will be called as part of initializing a new TLS context.

◆ tls_ctx_check_privatekey()

rsocket_sni & randolf::rsocket_sni::tls_ctx_check_privatekey ( )

inline

Check the private key it to ensure it's consistent with the corresponding TLS certificate chain.

Exceptions

randolf::rex::xALL Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned)

Returns: The same rsocket_sni object so as to facilitate stacking

See also: tls_ctx_use_privatekey_file; tls_ctx_use_privatekey_pem

◆ tls_ctx_use_certificate_chain_and_privatekey_files() [1/2]

rsocket_sni & randolf::rsocket_sni::tls_ctx_use_certificate_chain_and_privatekey_files	(	const char *	chain_file,
		const char *	key_file )

inline

Load a TLS certificate chain and private key in PEM format from text files and use them in the TLS context.

Exceptions

randolf::rex::xALL Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned)

Returns: The same rsocket_sni object so as to facilitate stacking

See also: tls_ctx_use_certificate_chain_and_privatekey_pems; tls_ctx_use_certificate_chain_file; tls_ctx_use_certificate_chain_pem; tls_ctx_use_privatekey_file; tls_ctx_use_privatekey_pem; tls_ctx_check_privatekey

Parameters

chain_file	Pointer to ASCIIZ path and filename to certificate chain file (`nullptr` will simply be ignored)
key_file	Pointer to ASCIIZ path and filename to private key file (`nullptr` will simply be ignored)

◆ tls_ctx_use_certificate_chain_and_privatekey_files() [2/2]

rsocket_sni & randolf::rsocket_sni::tls_ctx_use_certificate_chain_and_privatekey_files	(	const std::string &	chain_file,
		const std::string &	key_file )

inline

Load a TLS certificate chain and private key in PEM format from text files and use them in the TLS context.

Exceptions

randolf::rex::xALL Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned)

Returns: The same rsocket_sni object so as to facilitate stacking

See also: tls_ctx_use_certificate_chain_and_privatekey_pems; tls_ctx_use_certificate_chain_file; tls_ctx_use_certificate_chain_pem; tls_ctx_use_privatekey_file; tls_ctx_use_privatekey_pem; tls_ctx_check_privatekey

Parameters

chain_file	Pointer to ASCIIZ path and filename to certificate chain file (an empty string will simply be ignored)
key_file	Pointer to ASCIIZ path and filename to private key file (an empty string will simply be ignored)

◆ tls_ctx_use_certificate_chain_and_privatekey_pems()

rsocket_sni & randolf::rsocket_sni::tls_ctx_use_certificate_chain_and_privatekey_pems	(	const char *	cert_pem_data,
		const char *	key_pem_data,
		size_t	cert_len = 0,
		size_t	key_len = 0,
		const bool	random_fill = true )

inline

Load a TLS certificate chain and a TLS private key in PEM format from memory and use them in the TLS context.

Although this functionality doesn't exist in OpenSSL (at the time of writing this method), it's provided here in a manner that has exactly the same effect as the tls_ctx_use_certificate_chain_and_privatekey_files() methods, but without needing the PEM-formatted certificate chain stored in files beforehand.

Note: The cert_pem_data and key_pem_data parameters are pointers to the memory locations that holds the PEM formatted certificate chain data and private key data, respectively. If the corresponding lengths of each of these data aren't specified or are set to zero (default), then they will be treated as multiline ASCIIZ strings.

Behind the scenes, we're just writing the cert_pem_data and key_pem_data memory to temporary files with severely-limited permissions (), then optionally overwriting those temporary files with random data prior to deleting them (this is the default, since better security practices should be the default, but on a secured system it may not be necessary and so this option can also be disabled to save CPU cycles and reduce overall disk-write I/O operations).

Exceptions

randolf::rex::xALL Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned)

Returns: The same rsocket_sni object so as to facilitate stacking

See also: tls_ctx_use_certificate_chain_and_privatekey_files; tls_ctx_use_certificate_chain_file; tls_ctx_use_certificate_chain_pem; tls_ctx_use_privatekey_file; tls_ctx_use_privatekey_pem; tls_ctx_check_privatekey

Parameters

cert_pem_data	Pointer to certificate chain data in PEM format
key_pem_data	Pointer to private key data in PEM format
cert_len	Length of cert_pem_data (in bytes), or 0 to auto-detect length if cert_pem_data is an ASCIIZ string
key_len	Length of key_pem_data (in bytes), or 0 to auto-detect length if key_pem_data is an ASCIIZ string
random_fill	Whether to overwrite the temporary files with random data before deleting them

◆ tls_ctx_use_certificate_chain_file() [1/2]

rsocket_sni & randolf::rsocket_sni::tls_ctx_use_certificate_chain_file ( const char * file )

inline

Load a TLS certificate chain in PEM format from a text file and use it in the TLS context.

Exceptions

randolf::rex::xALL Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned)

Returns: The same rsocket_sni object so as to facilitate stacking

See also: tls_ctx_use_certificate_chain_pem; tls_ctx_check_privatekey

Parameters

file	Pointer to ASCIIZ path and filename to certificate chain file

◆ tls_ctx_use_certificate_chain_file() [2/2]

rsocket_sni & randolf::rsocket_sni::tls_ctx_use_certificate_chain_file ( const std::string & file )

inline

Load a TLS certificate chain in PEM format from a text file and use it in the TLS context.

Exceptions

randolf::rex::xALL Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned)

Returns: The same rsocket_sni object so as to facilitate stacking

See also: tls_ctx_use_certificate_chain_pem; tls_ctx_check_privatekey

Parameters

file	Path and filename to certificate chain file

◆ tls_ctx_use_certificate_chain_pem()

rsocket_sni & randolf::rsocket_sni::tls_ctx_use_certificate_chain_pem	(	const char *	pem_data,
		size_t	len = 0,
		const bool	random_fill = true )

inline

Load a TLS certificate chain in PEM format from memory and use it in the TLS context.

Although this functionality doesn't exist in OpenSSL (at the time of writing this method), it's provided here in a manner that has exactly the same effect as the tls_ctx_use_certificate_chain_file() methods, but without needing the PEM-formatted certificate chain stored in a file beforehand.

Note: The pem_data parameter is a pointer to the memory location that holds the PEM formatted certificate chain data. If the length of this data isn't specified or is set to zero (default), then it will be treated as a multiline ASCIIZ string.

Behind the scenes, we're just writing the pem_data memory to a temporary file with severely-limited permissions (), then optionally overwriting that temporary file with random data prior to deleting it (this is the default, since better security practices should be the default, but on a secured system it may not be necessary and so this option can also be disabled to save CPU cycles and reduce overall disk-write I/O operations).

Exceptions

randolf::rex::xALL Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned)

Returns: The same rsocket_sni object so as to facilitate stacking

See also: tls_ctx_use_certificate_chain_file; tls_ctx_check_privatekey

Parameters

pem_data	Pointer to certificate chain data in PEM format
len	Length of pem_data (in bytes), or 0 to auto-detect length if pem_data is an ASCIIZ string
random_fill	Whether to overwrite the temporary file with random data before deleting it

◆ tls_ctx_use_privatekey_file() [1/2]

rsocket_sni & randolf::rsocket_sni::tls_ctx_use_privatekey_file ( const char * file )

inline

Load a TLS private key in PEM format from a text file and use it in the TLS context.

Exceptions

randolf::rex::xALL Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned)

Returns: The same rsocket_sni object so as to facilitate stacking

See also: tls_ctx_use_privatekey_pem; tls_ctx_check_privatekey

Parameters

file	Pointer to ASCIIZ path and filename to private key file

◆ tls_ctx_use_privatekey_file() [2/2]

rsocket_sni & randolf::rsocket_sni::tls_ctx_use_privatekey_file ( const std::string & file )

inline

Load a TLS private key in PEM format from a text file and use it in the TLS context.

Exceptions

randolf::rex::xALL Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned)

Returns: The same rsocket_sni object so as to facilitate stacking

See also: tls_ctx_use_privatekey_pem; tls_ctx_check_privatekey

Parameters

file	Path and filename to private key file

◆ tls_ctx_use_privatekey_pem()

rsocket_sni & randolf::rsocket_sni::tls_ctx_use_privatekey_pem	(	const char *	pem_data,
		size_t	len = 0,
		const bool	random_fill = true )

inline

Load a TLS private key in PEM format from memory and use it in the TLS context.

Although this functionality doesn't exist in OpenSSL (at the time of writing this method), it's provided here in a manner that has exactly the same effect as the tls_ctx_use_privatekey_file() methods, but without needing the PEM-formatted private key stored in a file beforehand.

Note: The pem_data parameter is a pointer to the memory location that holds the PEM formatted private key data. If the length of this data isn't specified or is set to zero (default), then it will be treated as a multiline ASCIIZ string.

Behind the scenes, we're just writing the pem_data memory to a temporary file (with severely-limited permissions), then optionally overwriting that temporary file with random data prior to deleting it (this is the default, since better security practices should be the default, but on a secured system it may not be necessary and so this option can also be disabled to save CPU cycles and reduce overall disk-write I/O operations).

Exceptions

randolf::rex::xALL Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned)

Returns: The same rsocket_sni object so as to facilitate stacking

See also: tls_ctx_use_privatekey_file; tls_ctx_check_privatekey

Parameters

pem_data	Pointer to private key data in PEM format
len	Length of pem_data (in bytes), or 0 to auto-detect length if pem_data is an ASCIIZ string
random_fill	Whether to overwrite the temporary file with random data before deleting it

The documentation for this class was generated from the following file:

randolf/rsocket_sni

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ rsocket_sni()

◆ ~rsocket_sni()

Member Function Documentation

◆ add() [1/2]

◆ add() [2/2]

◆ del() [1/2]

◆ del() [2/2]

◆ get_ctx()

◆ tls_ctx() [1/2]

◆ tls_ctx() [2/2]

◆ tls_ctx_check_privatekey()

◆ tls_ctx_use_certificate_chain_and_privatekey_files() [1/2]

◆ tls_ctx_use_certificate_chain_and_privatekey_files() [2/2]

◆ tls_ctx_use_certificate_chain_and_privatekey_pems()

◆ tls_ctx_use_certificate_chain_file() [1/2]

◆ tls_ctx_use_certificate_chain_file() [2/2]

◆ tls_ctx_use_certificate_chain_pem()

◆ tls_ctx_use_privatekey_file() [1/2]

◆ tls_ctx_use_privatekey_file() [2/2]

◆ tls_ctx_use_privatekey_pem()