rtitls_openssl.h

/*
 * Copyright (c) 2009-2024 Real-Time Innovations, Inc. All rights reserved.
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or revisions thereof,
 * must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */
 
#ifndef rtitls_openssl_h
#define rtitls_openssl_h
 
  #ifndef rtitls_dll_h
    #include "rtitls/rtitls_dll.h"
  #endif
 
  #ifndef dds_c_infrastructure_h
    #include "dds_c/dds_c_infrastructure.h"
  #endif
 
/* if required, include openssl/ssl.h before this file */
#ifndef SSL_ERROR_NONE
  #define X509_STORE_CTX   void
  #define SSL_CTX          void
#endif
 
#ifdef __cplusplus
    extern "C" {
#endif
 
/* {{{ Doxygen group definitions
 * ------------------------------------------------------------------------- */
 
/*e \defgroup RTITLS_Plugin RTI TLS Support
  @brief OpenSSL configuration interfaces and definitions. 
  <br>TLS Support is included with some RTI purchases and must be downloaded and installed separately.
*/
 
/* }}} */
 
/*i \file 
    \ingroup RTITLS_Plugin
    \brief TLS Transport OpenSSL configuration interfaces and definitions.
    <br>TLS Support is included with some RTI purchases and must be downloaded and installed separately.
*/
 
/*e \ingroup RTITLS_Plugin
    \brief Callback used to verify peer certificates.
 
    See the OpenSSL manual page for SSL_CTX_set_verify for more information.
 */
typedef int (* RTITLS_Verify_Callback)
    (int preverify_ok, X509_STORE_CTX *x509_ctx);
 
/*e \ingroup RTITLS_Plugin
    \brief Set of TLS properties for certificate authorities (CAs) and verification
 */
struct RTITLS_Verification {
    /*e
     * \brief Name of file containing Certificate Authority certificates
     *
     *  File should be in PEM format. See the OpenSSL manual page for
     *  SSL_load_verify_locations for more information.
     *
     *  At least one of ca_file and ca_path must be specified; both may be
     *  specified.
     *
     * \default NULL
     */
    char *ca_file;
    /*e
     * \brief Paths to directories containing Certificate Authority certificates
     *
     *  Files should be in PEM format, and follow the OpenSSL-required naming
     *  conventions. See the OpenSSL manual page for SSL_CTX_load_verify_locations
     *  for more information.
     *
     *  At least one of ca_file and ca_path must be specified; both may be
     *  specified.
     *
     * \default NULL
     */
    char *ca_path;
    /*e
     * \brief List of Certificate Authority certificates
     *
     *  Certificates should be in PEM format, and follow the OpenSSL-required naming
     *  conventions. See the OpenSSL manual page for X509_STORE_add_cert
     *  for more information.
     *
     *  ca_file and ca_path have precedence if specified. If not, ca must be
     *  specified.
     *
     * \default NULL
     */
    char *ca;
    
    /*e
     * \brief Maximum certificate chain length for verification
     *
     *  \default -1 (no limit)
     */
    DDS_Long verify_depth;
    /*e
     * \brief Callback used to verify peer certificates
     *
     *  See the OpenSSL manual page for SSL_set_verify for more information.
     *  There are a number of default callbacks included in the Secure
     *  Transport.  See RTITLS_default_verify_callback() ,
     *  RTITLS_verbose_verify_callback() .
     *
     * \default NULL (use RTITLS_default_verify_callback() )
     */
    RTITLS_Verify_Callback callback;
    /*e
     * \brief Name of file containing Certificate Revocation List
     *
     *  File should be in PEM format.
     *
     * \default NULL
     */
    char *crl_file;
};
 
/*e \ingroup RTITLS_Plugin
    \brief Set of TLS properties for identity
 */
struct RTITLS_Identity {
    /*e \brief String containing identifying certificate (in PEM format) or
     * certificate chain (appending intermediate CA certs in order).
     *
     * An identifying certificate is required for secure communication.
     * The string must be sorted starting with the certificate to the highest
     * level (root CA).  If this is specified certificate_chain_file must be
     * empty.
     *
     * \default NULL
     */
    char *certificate_chain;
 
    /*e \brief File containing identifying certificate (in PEM format) or
     * certificate chain (appending intermediate CA certs in order).
     *
     * An identifying certificate is required for secure communication.
     * The file must be sorted starting with the certificate to the highest
     * level (root CA).  If this is specified certificate_chain must be
     * empty.
     *
     * Optionally, a private key may be appended to this file.  If no private
     * key option is specified, this file will be used to load a private key.
     *
     * \default NULL
     */
    char *certificate_chain_file;
 
    /*e @brief Password for private key
     *
     * \default NULL (no password)
     */
    char *private_key_password;
 
    /*e \brief String containing private key (in PEM format)
     *
     * At most one of private_key and private_key_file may be specified.  If no
     * private key is specified (all values are NULL), the private key will be read
     * from the certificate chain file.
     * 
     * \default NULL
     */
    char *private_key;
 
    /*e \brief File containing private key (in PEM format)
     *
     * At most one of private_key and private_key_file may be specified.  If no
     * private key is specified (all values are NULL), the private key will be read
     * from the certificate chain file.
     * 
     * \default NULL
     */
    char *private_key_file;
 
    /*e \brief String containing additional RSA private key (in PEM format)
     *
     * For use if both an RSA and non-RSA key are required for the selected cipher.
     * At most one of rsa_private_key and rsa_private_key_file may be specified.
     * 
     * \default NULL
     */
    char *rsa_private_key;
 
    /*e \brief File containing additional RSA private key (in PEM format)
     *
     * For use if both an RSA and non-RSA key are required for the selected cipher.
     * At most one of rsa_private_key and rsa_private_key_file may be specified.
     * 
     * \default NULL
     */
    char *rsa_private_key_file;
};
 
/*e \ingroup RTITLS_Plugin
    \brief Name of a Diffie-Helman (DH) key file and the length of the
      contained key in bits
 */
struct RTITLS_DHParamFile {
    /*e \brief Name of DH key file
     *
     * \default 0
     */
    char *file;
 
    /*e \brief Length of DH key in bits
     *
     * \default NULL
     */
    DDS_Long bits;
};
 
/*e \ingroup RTITLS_Plugin
    \brief Set of TLS properties for cipher configuration
 */
struct RTITLS_Ciphers {
    /*e \brief List of available TLS ciphers for TLS 1.2 or below
     *
     * See the OpenSSL manual page for SSL_set_cipher_list(3) or ciphers(1)
     * for more information on the format of this string.  Some typical
     * values are defined: RTITLS_Plugin#RTITLS_CIPHER_LIST_DEFAULT,
     * RTITLS_Plugin#RTITLS_CIPHER_LIST_ENCRYPT_HIGH, and
     * RTITLS_Plugin#RTITLS_CIPHER_LIST_UNENCRYPTED.
     *
     * \default NULL
     */
    char *cipher_list; /* cipher list in OpenSSL format */
 
    /*e \brief List of available TLS ciphersuites for TLS 1.3 or below
     *
     * See the OpenSSL manual page for SSL_CTX_set_ciphersuites
     * for more information on the format of this string.
     *
     * \default NULL
     */
    char *ciphersuites; /* ciphersuites in OpenSSL format */
 
    /*e \brief Number of DH key files supplied
     *
     * Must not be greater than 1 if RTI_SUPPORT_OSSL_DECODER is defined.
     *
     * \default 0
     */
    DDS_Long dh_param_files_length;
 
    /*e \brief List of available DH key files
     *
     * OpenSSL 3 does not allow generating a file with fewer than 512 bits.
     * According to
     * https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set0_tmp_dh_pkey.html ,
     * "Applications may supply their own DH parameters instead of using the
     * built-in values. This approach is discouraged and applications should in
     * preference use the built-in parameter support described above." So
     * setting these files is not recommended.
     *
     * \default NULL
     */
    struct RTITLS_DHParamFile *dh_param_files;
 
    /*e \brief ID of OpenSSL cipher engine to request
     *
     * \default NULL
     */
    char *engine_id;
 
    /*i \brief pre-load commands: length, name/parameter pairs */
    DDS_Long engine_pre_cmd_length;
    const char **engine_pre_cmd_names, **engine_pre_cmd_parameters;
    /*i \brief post-load commands: length, name/parameter pairs */
    DDS_Long engine_post_cmd_length;
    const char **engine_post_cmd_names, **engine_post_cmd_parameters;
};
 
/*i \ingroup RTITLS_Plugin
    \brief Set of TLS properties for required renegotiation.
 */
struct RTITLS_Renegotiate {
    /*i \brief Force renegotiation after connection open for time period
     *
     * \default DDS_DURATION_INFINITE
     */
    struct DDS_Duration_t force_after_time;
 
    /*i \brief Force renegotiation after amount of data transferred
     *
     * Data sent or received, measured in total unencryted length (0 = no force)
     *
     * \default 0
     */
    DDS_UnsignedLong force_after_Kbytes;
 
    /*i \brief Require renegotiation to complete with this period
     *
     * \default DDS_DURATION_INFINITE
     */
    struct DDS_Duration_t completion_period;
};
 
/*i */
typedef enum {
    RTITLS_PROTOCOL_TLS = 0,
    RTITLS_PROTOCOL_DTLS = 1
} RTITLS_Protocol_t;
 
/*e \ingroup RTITLS_Plugin
    \brief Full set of TLS properties
    
    Should be initialized with RTITLS_Plugin#RTITLS_OPENSSL_CONFIGURATION_DEFAULT
 */
struct RTITLS_OpenSSL_Configuration {
    /*e \brief Verification properties */
    struct RTITLS_Verification   verify;
    /*e \brief Identity properties */
    struct RTITLS_Identity       identity;
    /*e \brief Cipher properties */
    struct RTITLS_Ciphers        cipher;
    /*i \brief Renegotiation properties */
    struct RTITLS_Renegotiate    renegotiate;
};
 
/*e \ingroup RTITLS_Plugin
  \brief Use this to initialize a RTITLS_Verfication structure.
 
  \showinitializer
*/
#define RTITLS_VERIFY_DEFAULT { \
    NULL, NULL, NULL, /* ca_file, ca_path, ca */ \
    -1, /* verify_depth (no depth limit) */ \
    NULL, /* callback (use default verify callback) */ \
    NULL /* crl_file */ }
 
/*e \ingroup RTITLS_Plugin
  \brief Use this to initialize a RTITLS_Identity structure.
 
  \showinitializer
*/
#define RTITLS_IDENTITY_DEFAULT { \
    NULL, /* certificate_chain */ \
    NULL, /* certificate_chain_file */ \
    NULL, /* private_key_password */ \
    NULL, /* private_key */ \
    NULL, /* private_key_file */ \
    NULL, /* rsa_private_key */ \
    NULL /* rsa_private_key_file */ }
 
/*e \ingroup RTITLS_Plugin 
  \brief Cipher list string for default channel (encrypted) */
#define RTITLS_CIPHER_LIST_DEFAULT          "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH"
 
/*e \ingroup RTITLS_Plugin 
  \brief Cipher list string for default channel (encrypted, no low-strength) */
#define RTITLS_CIPHER_LIST_ENCRYPT_HIGH     "AES:ALL:!aNULL:!eNULL:!LOW:!EXP:+RC4:@STRENGTH"
 
/*e \ingroup RTITLS_Plugin 
  \brief Cipher list string for authentication-only channel (no encryption) */
#define RTITLS_CIPHER_LIST_UNENCRYPTED      "aNULL"
 
/*e \ingroup RTITLS_Plugin
  \brief Use this to initialize a RTITLS_Ciphers structure.
 
  \showinitializer
*/
#define RTITLS_CIPHER_DEFAULT { \
    NULL, /* cipher_list */ \
    NULL, /* ciphersuites */ \
    0, NULL, /* dh_param_files_length, dh_param_files (no DH params) */ \
    NULL, /* engine_id (no engine) */ \
    0, NULL, NULL, /* engine_pre_cmd_length, engine_pre_cmd_names, engine_pre_cmd_parameters */ \
    0, NULL, NULL /* engine_post_cmd_length, engine_post_cmd_names, engeine_post_cmd_parameters */ }
 
/*i \ingroup RTITLS_Plugin
  \brief Use this to initialize a RTITLS_Renegotiate structure.
 
  \showinitializer
*/
#define RTITLS_RENEGOTIATE_DEFAULT { \
    DDS_DURATION_INFINITE_VALUE, /* force_after_time */ \
    0, /* force_after_Kbytes */ \
    DDS_DURATION_INFINITE_VALUE /* completion_period */ }
 
/*e \ingroup RTITLS_Plugin
  \brief Use this to initialize a RTITLS_OpenSSL_Configuration structure.
 
  \showinitializer
*/
#define RTITLS_OPENSSL_CONFIGURATION_DEFAULT { \
    RTITLS_VERIFY_DEFAULT, /* verify */ \
    RTITLS_IDENTITY_DEFAULT, /* identity */ \
    RTITLS_CIPHER_DEFAULT, /* cipher */ \
    RTITLS_RENEGOTIATE_DEFAULT /* renegotiate */ }
 
/*e \ingroup RTITLS_Plugin
  \brief clean up OpenSSL resources for current thread (call before exit)
*/
extern RTITLSDllExport
void RTITLS_thread_exit(void);
 
/*e \ingroup RTITLS_Plugin
  \brief Default verify callback: log errors when verification fails
 
  See the OpenSSL manual page for SSL_CTX_set_verify for more information.
*/
extern int RTITLS_default_verify_callback(int ok, X509_STORE_CTX *store);
 
/*e \ingroup RTITLS_Plugin
  \brief Verbose verify callback: log information about successful verification
    as well as errors when verification fails
 
  See the OpenSSL manual page for SSL_CTX_set_verify for more information.
*/
extern int RTITLS_verbose_verify_callback(int ok, X509_STORE_CTX *store);
 
/*
 * tls is only compiled with OpenSSL support.
 * In the future this may change to support WolfSSL.
 */
#if defined(RTI_OPENSSL_ARCHITECTURE) || defined(RTI_OPENSSL3_ARCHITECTURE)
  /* methods below only supported on TLS architectures */
 
/*i \brief verify protocol configuration struct */
extern RTITLSDllExport
int RTITLS_configuration_verify(
    const struct RTITLS_OpenSSL_Configuration *config);
 
/*i \brief configure protocol, identity based on configuration struct */
extern RTITLSDllExport
SSL_CTX *RTITLS_context_init(
    RTITLS_Protocol_t protocol,
    const struct RTITLS_OpenSSL_Configuration *config);
 
/*i \brief clean up OpenSSL resources for context */
extern RTITLSDllExport
void RTITLS_context_done(SSL_CTX *context);
 
/* ================================================================= */
#endif /* RTI_OPENSSL_ARCHITECTURE || RTI_OPENSSL3_ARCHITECTURE */
 
#ifdef __cplusplus
    }   /* extern "C" */
#endif
 
#endif /* rtitls_openssl_h */