rsocket_sni

#pragma once
 
#include <randolf/rex>
 
#include <atomic>
#include <cstring>            // std::strlen
#include <filesystem>         // std::filesystem::temp_directory_path
#include <iostream>           // std::put_date
#include <unordered_map>      // std::unordered_map
 
#include <unistd.h>
 
#include <linux/fs.h>         // Flags for ioctl()
 
#include <openssl/err.h>
#include <openssl/ossl_typ.h>
#include <openssl/ssl.h>
#include <openssl/x509v3.h>
 
#include <sys/ioctl.h>
#include <sys/stat.h>         // fchmod()
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  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
  @par History
  2023-Mar-26 v1.00 Initial version
  *///=========================================================================
  class rsocket_sni {
 
    private:
      // --------------------------------------------------------------------------
      // Internal variables.
      // --------------------------------------------------------------------------
      SSL_CTX*                                                 __tls_ctx = nullptr; // Current TLS context
      std::unordered_map<std::string, SSL_CTX*>                __tls_ctx_map; // SNI map between hostnames and TLS contexts
      std::unordered_map<std::string, SSL_CTX*>                __tls_ctx_map_w; // SNI map with wildcards
      inline static std::atomic_int                            __fn_counter = 0; // Used in generating unique-and-threadsafe temporary filenames
 
    public:
      /*======================================================================*//**
      @brief
      Instantiate a new rsocket_sni object.
      @see tls_ctx()
      *///=========================================================================
      rsocket_sni(
      /// OpenSSL's TLS context to use (if set to @c nullptr, this @c rsocket's TLS
      /// context will be paired with the specified hostname{s})
      SSL_CTX* ctx = nullptr,
      /// When @c ctx is @c nullptr, indicates whether to initialize the new TLS
      /// context with the @c TLS_server_method() or the @c TLS_client_method()
      /// function (the default is @c true, which is the .
      const bool is_server_method = true) {
        tls_ctx(ctx, is_server_method);
      }; // -x- constructor rsocket_sni -x-
 
      /*======================================================================*//**
      @brief
      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 del
      *///=========================================================================
      ~rsocket_sni() noexcept {
 
        // --------------------------------------------------------------------------
        // Remove all entries so that OpenSSL's internal counters are accounted for.
        // --------------------------------------------------------------------------
        for (auto& sni: __tls_ctx_map)   del(sni.first);
        for (auto& sni: __tls_ctx_map_w) del(sni.first);
 
      }; // -x- constructor rsocket_sni -x-
 
      /*======================================================================*//**
      @brief
      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 del
      @see get_ctx
      @see tls_ctx
      *///=========================================================================
      rsocket_sni* add(
      /// Hostname to add
      std::string hostname) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        bool w = hostname.find("*") != std::string::npos;
 
        // --------------------------------------------------------------------------
        // Replace hostname if it already exists and the TLS context is different,
        // then update OpenSSL's internal reference counters accordingly.
        // --------------------------------------------------------------------------
        try {
          SSL_CTX* ctx = (w ? __tls_ctx_map_w : __tls_ctx_map).at(hostname); // Throws std::out_of_range exception if key doesn't exist
          if (ctx == __tls_ctx) return this; // The TLS context didn't change, so return now to save CPU cycles (optimization)
          SSL_CTX_free(ctx); // Decrement SSL_CTX's internal reference count
          (w ? __tls_ctx_map_w : __tls_ctx_map)[hostname] = __tls_ctx;
          SSL_CTX_up_ref(__tls_ctx); // Increment SSL_CTX's internal reference count
        } catch (const std::out_of_range e) {}
 
        // --------------------------------------------------------------------------
        // Add hostname with current TLS context.
        // --------------------------------------------------------------------------
        (w ? __tls_ctx_map_w : __tls_ctx_map).insert({hostname, __tls_ctx});
        SSL_CTX_up_ref(__tls_ctx); // Increment SSL_CTX's internal reference count
 
        return this;
      }; // -x- rsocket_sni* add -x-
 
      /*======================================================================*//**
      @brief
      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 del
      @see get_ctx
      @see tls_ctx
      *///=========================================================================
      template<class... Hs> rsocket_sni* add(
      /// First hostname (required)
      std::string hostname,
      /// Additional hostnames (optional)
      Hs... hostnames) {
 
        // --------------------------------------------------------------------------
        // Recursively loop through the variable arguments.
        // --------------------------------------------------------------------------
        add(hostname);
        add(hostnames...);
 
        return this;
      }; // -x- rsocket_sni* add -x-
 
      /*======================================================================*//**
      @brief
      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 add
      *///=========================================================================
      rsocket_sni* del(
      /// Hostname to delete
      std::string hostname) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        bool w = hostname.find("*") != std::string::npos; // Used to determine which map to delete from
 
        // --------------------------------------------------------------------------
        // If hostname exists, delete it and update OpenSSL's internal reference
        // counters accordingly.
        // --------------------------------------------------------------------------
        try {
          SSL_CTX* ctx = (w ? __tls_ctx_map_w : __tls_ctx_map).at(hostname); // Throws std::out_of_range exception if key doesn't exist
          SSL_CTX_free(ctx); // Decrement SSL_CTX's internal reference count
          (w ? __tls_ctx_map_w : __tls_ctx_map).erase(hostname);
        } catch (const std::out_of_range e) {}
 
        return this;
      }; // -x- rsocket_sni* del -x-
 
      /*======================================================================*//**
      @brief
      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 add
      *///=========================================================================
      template<class... Hs> rsocket_sni* del(
      /// First hostname (required)
      std::string hostname,
      /// Additional hostnames (optional)
      Hs... hostnames) {
 
        // --------------------------------------------------------------------------
        // Recursively loop through the variable arguments.
        // --------------------------------------------------------------------------
        del(hostname);
        del(hostnames...);
 
        return this;
      }; // -x- rsocket_sni* del -x-
 
      /*======================================================================*//**
      @brief
      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 @c nullptr (or @c default_tls_ctx override) if
      hostname doesn't match any SNI entries
      @see add
      *///=========================================================================
      SSL_CTX* get_ctx(
      /// Hostname
      std::string hostname,
      /// SNI supports wildcards, but if an exact match is needed then setting this
      /// parameter to @c false will skip attempts to also match wildcards (the
      /// default is @c true)
      const bool enable_sni_wildcards = true,
      /// Override the default context @c nullptr that is returned to indicate that
      /// the hostname didn't match
      SSL_CTX* default_tls_ctx = nullptr) {
 
        // --------------------------------------------------------------------------
        // Retrieve exact match.  If SNI wildcard checking is disabled, and an exact
        // match could not be retrieved, then just return the default TLS context.
        // --------------------------------------------------------------------------
        try {
          return __tls_ctx_map.at(hostname); // Throws std::out_of_range exception if key doesn't exist
        } catch (const std::out_of_range e) {
          if (!enable_sni_wildcards) return default_tls_ctx; // No wildcard checks, so return default
        }
 
        // --------------------------------------------------------------------------
        // Find wildcard match -- this takes longer, which is why we started with the
        // exact match first.
        //
        // We're relying on OpenSSL to do all the heavy-lifting when parsing wildcard
        // labels, which is best because OpenSSL does this efficiently and correctly.
        // --------------------------------------------------------------------------
        for (auto& sni: __tls_ctx_map_w) {
          X509*    cert    = SSL_CTX_get0_certificate(sni.second); // Debug: X509_NAME* subject = X509_get_subject_name(cert); std::cout << "Subject:  " << X509_NAME_oneline(subject, nullptr, 0) << std::endl;
          char*    peername = nullptr;
          int rc = X509_check_host(cert, hostname.data(), hostname.length(), 0, &peername); // TO DO:  Support flags:  https://www.openssl.org/docs/man1.1.1/man3/X509_check_host.html (TODO)
          // Debug: std::cout << "SNI -> key=" << sni.first << " peername=" << (peername != nullptr ? peername : "nullptr") << " hostname=" << hostname << std::endl;
          if (peername != nullptr) OPENSSL_free(peername); // Memory management
          if (rc == 1) return sni.second; // Wildcard match successful, so we're finished with all of this now
        } // -x- foreach sni -x-
 
        return default_tls_ctx;
      }; // -x- SSL_CTX* get_ctx -x-
 
      /*======================================================================*//**
      @brief
      Find out what the current TLS context is set to.
      @returns TLS context
      *///=========================================================================
      SSL_CTX* tls_ctx() noexcept {
        return __tls_ctx;
      }; // -x- SSL_CTX* tls_ctx -x-
 
      /*======================================================================*//**
      @brief
      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
      *///=========================================================================
      rsocket_sni* tls_ctx(
      /// OpenSSL's TLS context to use (if set to @c nullptr, this @c rsocket's TLS
      /// context will be paired with the specified hostname{s})
      SSL_CTX* ctx,
      /// When @c ctx is @c nullptr, indicates whether to initialize the new TLS
      /// context with the @c TLS_server_method(), which is the default.  If set to
      /// @c false, then the @c TLS_client_method() function will be called as part
      /// of initializing a new TLS context.
      const bool is_server_method = true) {
 
        // --------------------------------------------------------------------------
        // Save (ctx != nullptr) or create (ctx == nullptr) OpenSSL context.
        // --------------------------------------------------------------------------
        __tls_ctx = ctx == nullptr ? SSL_CTX_new(is_server_method ? TLS_server_method() : TLS_client_method()) // Create anew (default)
                                   : ctx; // Use OpenSSL context that was provided
        if (__tls_ctx == nullptr) randolf::rex::mk_exception("Cannot create TLS context", 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
 
        return this;
      }; // -x- rsocket_sni* tls_ctx -x-
 
      /*======================================================================*//**
      @brief
      Check the private key it to ensure it's consistent with the corresponding TLS
      certificate chain.
 
      @throws 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 tls_ctx_use_privatekey_file
      @see tls_ctx_use_privatekey_pem
      *///=========================================================================
      rsocket_sni* tls_ctx_check_privatekey() {
        if (!SSL_CTX_check_private_key(__tls_ctx)) randolf::rex::mk_exception("Cannot validate consistency between certificate chain and private key", 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
        return this;
      }; // -x- rsocket_sni* tls_ctx_check_privatekey -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS certificate chain and private key in PEM format from text files
      and use them in the TLS context.
 
      @throws 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 tls_ctx_use_certificate_chain_and_privatekey_pems
      @see tls_ctx_use_certificate_chain_file
      @see tls_ctx_use_certificate_chain_pem
      @see tls_ctx_use_privatekey_file
      @see tls_ctx_use_privatekey_pem
      @see tls_ctx_check_privatekey
      *///=========================================================================
      rsocket_sni* tls_ctx_use_certificate_chain_and_privatekey_files(
      /// Pointer to ASCIIZ path and filename to certificate chain file (@c nullptr
      /// will simply be ignored)
      const char* chain_file,
      /// Pointer to ASCIIZ path and filename to private key file (@c nullptr will
      /// simply be ignored)
      const char* key_file) {
        if (chain_file != nullptr) tls_ctx_use_certificate_chain_file(chain_file);
        if (  key_file != nullptr) tls_ctx_use_privatekey_file(         key_file);
        return this;
      }; // -x- rsocket_sni* tls_ctx_use_certificate_chain_and_privatekey_files -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS certificate chain and private key in PEM format from text files
      and use them in the TLS context.
 
      @throws 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 tls_ctx_use_certificate_chain_and_privatekey_pems
      @see tls_ctx_use_certificate_chain_file
      @see tls_ctx_use_certificate_chain_pem
      @see tls_ctx_use_privatekey_file
      @see tls_ctx_use_privatekey_pem
      @see tls_ctx_check_privatekey
      *///=========================================================================
      rsocket_sni* tls_ctx_use_certificate_chain_and_privatekey_files(
      /// Pointer to ASCIIZ path and filename to certificate chain file (an empty
      /// string will simply be ignored)
      const std::string chain_file,
      /// Pointer to ASCIIZ path and filename to private key file (an empty string
      /// will simply be ignored)
      const std::string key_file) {
        if (!chain_file.empty()) tls_ctx_use_certificate_chain_file(chain_file);
        if (  !key_file.empty()) tls_ctx_use_privatekey_file(         key_file);
        return this;
      }; // -x- rsocket_sni* tls_ctx_use_certificate_chain_and_privatekey_files -x-
 
      /*======================================================================*//**
      @brief
      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 @ref tls_ctx_use_certificate_chain_and_privatekey_files() methods, but
      without needing the PEM-formatted certificate chain stored in files
      beforehand.
 
      @note
      The @c 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).
 
      @throws 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 tls_ctx_use_certificate_chain_and_privatekey_files
      @see tls_ctx_use_certificate_chain_file
      @see tls_ctx_use_certificate_chain_pem
      @see tls_ctx_use_privatekey_file
      @see tls_ctx_use_privatekey_pem
      @see tls_ctx_check_privatekey
      *///=========================================================================
      rsocket_sni* tls_ctx_use_certificate_chain_and_privatekey_pems(
      /// Pointer to certificate chain data in PEM format
      const char* cert_pem_data,
      /// Pointer to private key data in PEM format
      const char* key_pem_data,
      /// Length of cert_pem_data (in bytes), or 0 to auto-detect length if cert_pem_data is an ASCIIZ string
      size_t cert_len = 0,
      /// Length of key_pem_data (in bytes), or 0 to auto-detect length if key_pem_data is an ASCIIZ string
      size_t key_len = 0,
      /// Whether to overwrite the temporary files with random data before deleting them
      const bool random_fill = true) {
        tls_ctx_use_certificate_chain_pem(cert_pem_data, cert_len, random_fill);
        tls_ctx_use_privatekey_pem(        key_pem_data,  key_len, random_fill);
        return this;
      }; // -x- rsocket_sni* tls_ctx_use_certificate_chain_and_privatekey_pems -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS certificate chain in PEM format from a text file and use it in the
      TLS context.
 
      @throws 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 tls_ctx_use_certificate_chain_pem
      @see tls_ctx_check_privatekey
      *///=========================================================================
      rsocket_sni* tls_ctx_use_certificate_chain_file(
      /// Pointer to ASCIIZ path and filename to certificate chain file
      const char* file) {
        if (SSL_CTX_use_certificate_chain_file(__tls_ctx, file) != 1) randolf::rex::mk_exception(std::string("Cannot use certificate chain file ") + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
        return this;
      }; // -x- rsocket_sni* tls_ctx_use_certificate_chain_file -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS certificate chain in PEM format from a text file and use it in the
      TLS context.
 
      @throws 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 tls_ctx_use_certificate_chain_pem
      @see tls_ctx_check_privatekey
      *///=========================================================================
      rsocket_sni* tls_ctx_use_certificate_chain_file(
      /// Path and filename to certificate chain file
      const std::string file) {
        if (SSL_CTX_use_certificate_chain_file(__tls_ctx, file.c_str()) != 1) randolf::rex::mk_exception("Cannot use certificate chain file " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
        return this;
      }; // -x- rsocket_sni* tls_ctx_use_certificate_chain_file -x-
 
      /*======================================================================*//**
      @brief
      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 @ref tls_ctx_use_certificate_chain_file() methods, but without needing
      the PEM-formatted certificate chain stored in a file beforehand.
 
      @note
      The @c 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).
 
      @throws 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 tls_ctx_use_certificate_chain_file
      @see tls_ctx_check_privatekey
      *///=========================================================================
      rsocket_sni* tls_ctx_use_certificate_chain_pem(
      /// Pointer to certificate chain data in PEM format
      const char* pem_data,
      /// Length of pem_data (in bytes), or 0 to auto-detect length if pem_data is an ASCIIZ string
      size_t len = 0,
      /// Whether to overwrite the temporary file with random data before deleting it
      const bool random_fill = true) {
 
        // --------------------------------------------------------------------------
        // Measure size of certificate chain if an ASCIIZ string was indicated.
        // --------------------------------------------------------------------------
        if (len == 0) len = std::strlen(pem_data);
 
        // --------------------------------------------------------------------------
        // Generate filename for temporary use.
        // --------------------------------------------------------------------------
        std::string file = std::filesystem::temp_directory_path();
        file.append("/rsocket_sni.")
            .append(std::to_string(::getpid()))
            .append(".")
            .append(std::to_string(__fn_counter.fetch_add(1, std::memory_order_relaxed)));
 
        // --------------------------------------------------------------------------
        // Open temporary file.
        // --------------------------------------------------------------------------
        FILE* fp = fopen(file.c_str(), "w+");
        if (fp == nullptr) randolf::rex::mk_exception("Cannot open temporary file (to use certificate chain) " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO);
        { int attr;
          ioctl(fileno(fp), FS_IOC_GETFLAGS, &attr);
          attr |= FS_NOATIME_FL // Don't update access time attribute
               |  FS_NODUMP_FL  // Don't include in filesystem backup dumps
               |  FS_SECRM_FL;  // Mark file for secure deletion (where supported)
          ioctl(fileno(fp), FS_IOC_SETFLAGS, &attr);
        }
        fchmod(fileno(fp), S_IRUSR | S_IWUSR);
        if (fputs(pem_data, fp) == EOF) {
          fclose(fp);
          randolf::rex::mk_exception("Cannot write to temporary file (to use certificate chain) " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO);
        } // -x- if !fputs -x-
        fflush(fp);
 
        // --------------------------------------------------------------------------
        // Attempt to load certificate chain file, but save the error code for later
        // because we need to clean up the temporary file before possibly throwing an
        // exception.
        // --------------------------------------------------------------------------
        int rc = SSL_CTX_use_certificate_chain_file(__tls_ctx, file.c_str());
 
        // --------------------------------------------------------------------------
        // Overwrite the contenst of the temporary file before deleting it so as to
        // sabotage a simple attempt to undelete the file and access the certificate.
        //
        // We're also re-using the "len" local variable because it's not needed once
        // we get the loop started, and it's more optimal to not allocate yet another
        // local variable while "len" goes to waste.  :D
        // --------------------------------------------------------------------------
        if (random_fill) { // This option is configurable
          fseek(fp, 0, SEEK_SET);                         // File file position pointer to the beginning
          ::srand(::time(0) + __fn_counter);              // Current time + atomic __fn_counter value helps add variety
          for (int i = len / sizeof(int) + (::rand() & 127); i >= 0; i--) {  // Fill contents of file with random data
            len = ::rand() + (len >> (sizeof(int) >> 2)); // Bias random data toward containing more set bits (more 1's)
            fwrite(&len, sizeof(int), 1, fp);             // Write one integer at a time
          } // -x- for i -x-
        } // -x- if randfill -x-
        fchmod(fileno(fp), 0);                            // Remove all permissions
        fclose(fp);                                       // Close file handle
        unlink(file.c_str());                              // Delete temporary file
 
        // --------------------------------------------------------------------------
        // Error check ... was delayed here until after temporary file cleanup.
        // --------------------------------------------------------------------------
        if (rc != 1) randolf::rex::mk_exception("Cannot use certificate chain file " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
 
        return this;
      }; // -x- rsocket_sni* tls_ctx_use_certificate_chain_pem -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS private key in PEM format from a text file and use it in the TLS
      context.
 
      @throws 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 tls_ctx_use_privatekey_pem
      @see tls_ctx_check_privatekey
      *///=========================================================================
      rsocket_sni* tls_ctx_use_privatekey_file(
      /// Pointer to ASCIIZ path and filename to private key file
      const char* file) {
        if (SSL_CTX_use_PrivateKey_file(__tls_ctx, file, SSL_FILETYPE_PEM) != 1) randolf::rex::mk_exception(std::string("Cannot use private key file ") + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
 
        return this;
      }; // -x- rsocket_sni* tls_ctx_use_privatekey_file -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS private key in PEM format from a text file and use it in the TLS
      context.
 
      @throws 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 tls_ctx_use_privatekey_pem
      @see tls_ctx_check_privatekey
      *///=========================================================================
      rsocket_sni* tls_ctx_use_privatekey_file(
      /// Path and filename to private key file
      const std::string file) {
        if (SSL_CTX_use_PrivateKey_file(__tls_ctx, file.c_str(), SSL_FILETYPE_PEM) != 1) randolf::rex::mk_exception("Cannot use private key file " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
 
        return this;
      }; // -x- rsocket_sni* tls_ctx_use_privatekey_file -x-
 
      /*======================================================================*//**
      @brief
      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 @ref tls_ctx_use_privatekey_file() methods, but without needing the
      PEM-formatted private key stored in a file beforehand.
 
      @note
      The @c 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).
 
      @throws 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 tls_ctx_use_privatekey_file
      @see tls_ctx_check_privatekey
      *///=========================================================================
      rsocket_sni* tls_ctx_use_privatekey_pem(
      /// Pointer to private key data in PEM format
      const char* pem_data,
      /// Length of pem_data (in bytes), or 0 to auto-detect length if pem_data is an ASCIIZ string
      size_t len = 0,
      /// Whether to overwrite the temporary file with random data before deleting it
      const bool random_fill = true) {
 
        // --------------------------------------------------------------------------
        // Measure size of private key if an ASCIIZ string was indicated.
        // --------------------------------------------------------------------------
        if (len == 0) len = std::strlen(pem_data);
 
        // --------------------------------------------------------------------------
        // Generate filename for temporary use.
        // --------------------------------------------------------------------------
        std::string file = std::filesystem::temp_directory_path();
        file.append("/rsocket_sni.")
            .append(std::to_string(::getpid()))
            .append(".")
            .append(std::to_string(__fn_counter.fetch_add(1, std::memory_order_relaxed)));
 
        // --------------------------------------------------------------------------
        // Open temporary file.
        // --------------------------------------------------------------------------
        FILE* fp = fopen(file.c_str(), "w+");
        if (fp == nullptr) randolf::rex::mk_exception("Cannot cannot open temporary file (to use private key) " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO);
        fchmod(fileno(fp), S_IRUSR | S_IWUSR);
        if (fputs(pem_data, fp) == EOF) {
          fclose(fp);
          randolf::rex::mk_exception("Cannot cannot write to temporary file (to use private key) " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO);
        } // -x- if !fputs -x-
        fflush(fp);
 
        // --------------------------------------------------------------------------
        // Attempt to load private key file, but save the error code for later
        // because we need to clean up the temporary file before possibly throwing an
        // exception.
        // --------------------------------------------------------------------------
        int rc = SSL_CTX_use_PrivateKey_file(__tls_ctx, file.c_str(), SSL_FILETYPE_PEM);
 
        // --------------------------------------------------------------------------
        // Overwrite the contenst of the temporary file before deleting it so as to
        // sabotage a simple attempt to undelete the file and access the certificate.
        //
        // We're also re-using the "len" local variable because it's not needed once
        // we get the loop started, and it's more optimal to not allocate yet another
        // local variable while "len" goes to waste.  :D
        // --------------------------------------------------------------------------
        if (random_fill) { // This option is configurable
          fseek(fp, 0, SEEK_SET);                         // File file position pointer to the beginning
          ::srand(::time(0) + __fn_counter);              // Current time + atomic __fn_counter value helps add variety
          for (int i = len / sizeof(int) + (::rand() & 127); i >= 0; i--) {  // Fill contents of file with random data
            len = ::rand() + (len >> (sizeof(int) >> 2)); // Bias random data toward containing more set bits (more 1's)
            fwrite(&len, sizeof(int), 1, fp);             // Write one integer at a time
          } // -x- for i -x-
        } // -x- if randfill -x-
        fchmod(fileno(fp), 0);                            // Remove all permissions
        fclose(fp);                                       // Close file handle
        unlink(file.c_str());                              // Delete temporary file
 
        // --------------------------------------------------------------------------
        // Error check ... was delayed here until after temporary file cleanup.
        // --------------------------------------------------------------------------
        if (rc != 1) randolf::rex::mk_exception("Cannot use private key file " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
 
        return this;
      }; // -x- rsocket_sni* tls_ctx_use_privatekey_pem -x-
 
  }; // -x- class rsocket_sni -x-
 
}; // -x- namespace randolf -x-