ssl_common.h

Go to the documentation of this file.

/*
 *  OpenVPN -- An application to securely tunnel IP networks
 *             over a single TCP/UDP port, with support for SSL/TLS-based
 *             session authentication and key exchange,
 *             packet encryption, packet authentication, and
 *             packet compression.
 *
 *  Copyright (C) 2002-2026 OpenVPN Inc <sales@openvpn.net>
 *  Copyright (C) 2010-2026 Sentyron B.V. <openvpn@sentyron.com>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License version 2
 *  as published by the Free Software Foundation.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef SSL_COMMON_H_
#define SSL_COMMON_H_
 
#include "session_id.h"
#include "socket_util.h"
#include "packet_id.h"
#include "crypto.h"
#include "options.h"
 
#include "ssl_backend.h"
 
/* passwords */
#define UP_TYPE_AUTH        "Auth"
#define UP_TYPE_PRIVATE_KEY "Private Key"
 
/* clang-format off */
#define S_ERROR         (-2)    
#define S_ERROR_PRE     (-1)    
#define S_UNDEF           0     
#define S_INITIAL         1     
#define S_PRE_START_SKIP  2     
#define S_PRE_START       3     
#define S_START           4     
#define S_SENT_KEY        5     
#define S_GOT_KEY         6     
#define S_ACTIVE          7     
#define S_GENERATED_KEYS  8     
/* clang-format on */
/* Note that earlier versions also had a S_OP_NORMAL state that was
 * virtually identical with S_ACTIVE and the code still assumes everything
 * >= S_ACTIVE to be fully operational */
struct key_source
{
    uint8_t pre_master[48]; 
    uint8_t random1[32];    
    uint8_t random2[32];    
};
 
 
struct key_source2
{
    struct key_source client; 
    struct key_source server; 
};
 
 
enum ks_auth_state
{
    KS_AUTH_FALSE,    
    KS_AUTH_DEFERRED, 
    KS_AUTH_TRUE      
};
 
struct auth_deferred_status
{
    char *auth_control_file;
    char *auth_pending_file;
    char *auth_failed_reason_file;
    unsigned int auth_control_status;
};
 
/* key_state_test_auth_control_file return values, these specify the
 * current status of a deferred authentication */
enum auth_deferred_result
{
    ACF_PENDING,   
    ACF_SUCCEEDED, 
    ACF_DISABLED,  
    ACF_FAILED     
};
 
enum dco_key_status
{
    DCO_NOT_INSTALLED,
    DCO_INSTALLED_PRIMARY,
    DCO_INSTALLED_SECONDARY
};
 
struct key_state
{
    int state;
    unsigned int auth_token_state_flags;
 
    int key_id;
 
    uint32_t peer_id;
 
    struct key_state_ssl ks_ssl;           /* contains SSL object and BIOs for the control channel */
 
    time_t initial;                        /* when we created this session */
    time_t established;                    /* when our state went S_ACTIVE */
    time_t must_negotiate;                 /* key negotiation times out if not finished before this time */
    time_t must_die;                       /* this object is destroyed at this time */
    time_t peer_last_packet;               /* Last time we received a packet in this control session */
 
    int initial_opcode;                    /* our initial P_ opcode */
    struct session_id session_id_remote;   /* peer's random session ID */
    struct link_socket_actual remote_addr; /* peer's IP addr */
 
    struct crypto_options crypto_options;  /* data channel crypto options */
 
    struct key_source2 *key_src;           /* source entropy for key expansion */
 
    struct buffer plaintext_read_buf;
    struct buffer plaintext_write_buf;
    struct buffer ack_write_buf;
 
    struct reliable *send_reliable; /* holds a copy of outgoing packets until ACK received */
    struct reliable *rec_reliable;  /* order incoming ciphertext packets before we pass to TLS */
    struct reliable_ack *rec_ack;   /* buffers all packet IDs we want to ACK back to sender */
    struct reliable_ack *lru_acks;  /* keeps the most recently acked packages*/
 
    struct buffer_list *paybuf;
    counter_type n_bytes;   /* how many bytes sent/recvd since last key exchange */
    counter_type n_packets; /* how many packets sent/recvd since last key exchange */
 
    /*
     * If bad username/password, TLS connection will come up but 'authenticated' will be false.
     */
    enum ks_auth_state authenticated;
    time_t auth_deferred_expire;
 
#ifdef ENABLE_MANAGEMENT
    unsigned int mda_key_id;
    enum auth_deferred_result mda_status;
#endif
    time_t acf_last_mod;
 
    struct auth_deferred_status plugin_auth;
    struct auth_deferred_status script_auth;
 
    enum dco_key_status dco_status;
};
 
struct tls_wrap_ctx
{
    enum
    {
        TLS_WRAP_NONE = 0,                  
        TLS_WRAP_AUTH,                      
        TLS_WRAP_CRYPT,                     
    } mode;                                 
    struct crypto_options opt;              
    struct buffer work;                     
    struct key_ctx tls_crypt_v2_server_key; 
    const struct buffer *tls_crypt_v2_wkc;  
    struct buffer tls_crypt_v2_metadata;    
    bool cleanup_key_ctx;                   
    struct key2 original_wrap_keydata;
};
 
/*
 * Our const options, obtained directly or derived from
 * command line options.
 */
struct tls_options
{
    /* our master TLS context from which all SSL objects are derived,
     * this context is shared between all instances in p2pm with
     * inherit_context_child. */
    struct tls_root_ctx *ssl_ctx;
 
    /* data channel cipher, hmac, and key lengths */
    struct key_type key_type;
 
    /* true if we are a TLS server, client otherwise */
    bool server;
 
    /* if true, don't xmit until first packet from peer is received */
    bool xmit_hold;
 
    /* local and remote options strings
     * that must match between client and server */
    const char *local_options;
    const char *remote_options;
 
    /* from command line */
    bool single_session;
    int mode;
    bool pull;
    int push_peer_info_detail;
    int transition_window;
    int handshake_window;
    interval_t packet_timeout;
    int64_t renegotiate_bytes;
    int64_t renegotiate_packets;
    uint64_t aead_usage_limit;
    interval_t renegotiate_seconds;
 
    /* cert verification parms */
    const char *verify_command;
    int verify_x509_type;
    const char *verify_x509_name;
    const char *crl_file;
    bool crl_file_inline;
    int ns_cert_type;
    unsigned remote_cert_ku[MAX_PARMS];
    const char *remote_cert_eku;
    struct verify_hash_list *verify_hash;
    int verify_hash_depth;
    bool verify_hash_no_ca;
    hash_algo_type verify_hash_algo;
    char *x509_username_field[MAX_PARMS];
 
    /* struct crypto_option flags */
    unsigned int crypto_flags;
 
    int replay_window; /* --replay-window parm */
    int replay_time;   /* --replay-window parm */
 
    const char *config_ciphername;
    const char *config_ncp_ciphers;
 
    bool data_epoch_supported;
 
    bool tls_crypt_v2;
    const char *tls_crypt_v2_verify_script;
    int tls_crypt_v2_max_age;
 
    struct tls_wrap_ctx tls_wrap;
 
    struct frame frame;
 
    /* used for username/password authentication */
    const char *auth_user_pass_verify_script;
    const char *client_crresponse_script;
    bool auth_user_pass_verify_script_via_file;
    const char *tmp_dir;
    const char *export_peer_cert_dir;
    const char *auth_user_pass_file;
    bool auth_user_pass_file_inline;
 
    bool auth_token_generate;  
    bool auth_token_call_auth; 
    unsigned int auth_token_lifetime;
    unsigned int auth_token_renewal;
 
    struct key_ctx auth_token_key;
 
    /* use the client-config-dir as a positive authenticator */
    const char *client_config_dir_exclusive;
 
    /* instance-wide environment variable set */
    struct env_set *es;
    openvpn_net_ctx_t *net_ctx;
    const struct plugin_list *plugins;
 
    /* compression parms */
#ifdef USE_COMP
    struct compress_options comp_options;
#endif
 
    /* configuration file SSL-related boolean and low-permutation options */
#define SSLF_CLIENT_CERT_NOT_REQUIRED (1u << 0)
#define SSLF_CLIENT_CERT_OPTIONAL     (1u << 1)
#define SSLF_USERNAME_AS_COMMON_NAME  (1u << 2)
#define SSLF_AUTH_USER_PASS_OPTIONAL  (1u << 3)
/* (1u << 4) free for usage */
#define SSLF_CRL_VERIFY_DIR           (1u << 5)
#define SSLF_TLS_VERSION_MIN_SHIFT    6
#define SSLF_TLS_VERSION_MIN_MASK     0xFu /* (uses bit positions 6 to 9) */
#define SSLF_TLS_VERSION_MAX_SHIFT    10
#define SSLF_TLS_VERSION_MAX_MASK     0xFu /* (uses bit positions 10 to 13) */
#define SSLF_TLS_DEBUG_ENABLED        (1u << 14)
    unsigned int ssl_flags;
 
#ifdef ENABLE_MANAGEMENT
    struct man_def_auth_context *mda_context;
#endif
 
    const struct x509_track *x509_track;
 
#ifdef ENABLE_MANAGEMENT
    const struct static_challenge_info *sci;
#endif
 
    /* --gremlin bits */
    int gremlin;
 
    /* Keying Material Exporter [RFC 5705] parameters */
    const char *ekm_label;
    size_t ekm_label_size;
    size_t ekm_size;
 
    bool dco_enabled; 
};
 
#define KS_PRIMARY 0 
#define KS_LAME_DUCK                                        \
    1                
#define KS_SIZE 2    
struct tls_session
{
    /* const options and config info */
    struct tls_options *opt;
 
    /* during hard reset used to control burst retransmit */
    bool burst;
 
    /* authenticate control packets */
    struct tls_wrap_ctx tls_wrap;
 
    /* Specific tls-crypt for renegotiations, if this is valid,
     * tls_wrap_reneg.mode is TLS_WRAP_CRYPT, otherwise ignore it */
    struct tls_wrap_ctx tls_wrap_reneg;
 
    int initial_opcode;           /* our initial P_ opcode */
    struct session_id session_id; /* our random session ID */
 
    int key_id;
 
    int verify_maxlevel;
 
    char *common_name;
 
    struct cert_hash_set *cert_hash_set;
 
    bool verified; /* true if peer certificate was verified against CA */
 
    /* not-yet-authenticated incoming client */
    struct link_socket_actual untrusted_addr;
 
    struct key_state key[KS_SIZE];
};
 
#define TM_ACTIVE 0    
#define TM_INITIAL                                           \
    1                  
#define TM_LAME_DUCK 2 
#define TM_SIZE                                              \
    3                  
/*
 * The number of keys we will scan on encrypt or decrypt.  The first
 * is the "active" key.  The second is the lame_duck or retiring key
 * associated with the active key's session ID.  The third is a detached
 * lame duck session that only occurs in situations where a key renegotiate
 * failed on the active key, but a lame duck key was still valid.  By
 * preserving the lame duck session, we can be assured of having a data
 * channel key available even when network conditions are so bad that
 * we can't negotiate a new key within the time allotted.
 */
#define KEY_SCAN_SIZE 3
 
 
/* multi state (originally client authentication state (=CAS))
 * CAS_NOT_CONNECTED must be 0 since non multi code paths still check
 * this variable but do not explicitly initialise it and depend
 * on zero initialisation */
 
/* CAS_NOT_CONNECTED is the initial state for every context. When the *first*
 * tls_session reaches S_ACTIVE, this state machine moves to CAS_PENDING (server)
 * or CAS_CONNECT_DONE (client/p2p) as clients skip the stages associated with
 * connect scripts/plugins */
enum multi_status
{
    CAS_NOT_CONNECTED,
    CAS_WAITING_AUTH,             
    CAS_PENDING,                  
    CAS_PENDING_DEFERRED,         
    CAS_PENDING_DEFERRED_PARTIAL, 
    CAS_FAILED,                   
    CAS_WAITING_OPTIONS_IMPORT,   
    CAS_RECONNECT_PENDING,
    CAS_CONNECT_DONE,
};
 
 
struct tls_multi
{
    /* used to coordinate access between main thread and TLS thread */
    /*MUTEX_PTR_DEFINE (mutex);*/
 
    /* const options and config info */
    struct tls_options opt;
 
    /*
     * used by tls_pre_encrypt to communicate the encrypt key
     * to tls_post_encrypt()
     */
    struct key_state *save_ks; /* temporary pointer used between pre/post routines */
 
    /*
     * Used to return outgoing address from
     * tls_multi_process.
     */
    struct link_socket_actual to_link_addr;
 
    int n_sessions; 
    enum multi_status multi_state;
 
    /*
     * Number of errors.
     */
    int n_hard_errors; /* errors due to TLS negotiation failure */
    int n_soft_errors; /* errors due to unrecognized or failed-to-authenticate incoming packets */
 
    char *locked_cn;
 
    char *locked_username;
 
    char *locked_original_username;
 
    struct cert_hash_set *locked_cert_hash_set;
 
    time_t tas_cache_last_update;
 
    unsigned int tas_cache_num_updates;
 
    char *client_reason;
 
    char *peer_info;
    char *auth_token;
    char *auth_token_initial;
 
#define AUTH_TOKEN_HMAC_OK         (1 << 0)
#define AUTH_TOKEN_EXPIRED         (1 << 1)
#define AUTH_TOKEN_VALID_EMPTYUSER (1 << 2)
 
    /* For P_DATA_V2 */
    uint32_t peer_id;
    bool use_peer_id;
 
    char *remote_ciphername; 
    bool remote_usescomp;    
    /*
     * Our session objects.
     */
    struct tls_session session[TM_SIZE];
 
    /* Only used when DCO is used to remember how many keys we installed
     * for this session */
    int dco_keys_installed;
    int dco_peer_id;
 
    dco_context_t *dco;
};
 
static inline struct key_state *
get_key_scan(struct tls_multi *multi, int index)
{
    switch (index)
    {
        case 0:
            return &multi->session[TM_ACTIVE].key[KS_PRIMARY];
 
        case 1:
            return &multi->session[TM_ACTIVE].key[KS_LAME_DUCK];
 
        case 2:
            return &multi->session[TM_LAME_DUCK].key[KS_LAME_DUCK];
 
        default:
            ASSERT(false);
            return NULL; /* NOTREACHED */
    }
}
 
static inline const struct key_state *
get_primary_key(const struct tls_multi *multi)
{
    return &multi->session[TM_ACTIVE].key[KS_PRIMARY];
}
 
#endif /* SSL_COMMON_H_ */