/* * 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-2005 OpenVPN Solutions LLC * * 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 (see the file COPYING included with this * distribution); if not, write to the Free Software Foundation, Inc., * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ #ifndef OPENVPN_SSL_H #define OPENVPN_SSL_H #if defined(USE_CRYPTO) && defined(USE_SSL) #include #include #include #include #include #include #include "basic.h" #include "common.h" #include "crypto.h" #include "packet_id.h" #include "session_id.h" #include "reliable.h" #include "socket.h" #include "mtu.h" #include "thread.h" #include "options.h" #include "plugin.h" /* * OpenVPN Protocol, taken from ssl.h in OpenVPN source code. * * TCP/UDP Packet: This represents the top-level encapsulation. * * TCP/UDP packet format: * * Packet length (16 bits, unsigned) -- TCP only, always sent as * plaintext. Since TCP is a stream protocol, the packet * length words define the packetization of the stream. * * Packet opcode/key_id (8 bits) -- TLS only, not used in * pre-shared secret mode. * packet message type, a P_* constant (high 5 bits) * key_id (low 3 bits, see key_id in struct tls_session * below for comment). The key_id refers to an * already negotiated TLS session. OpenVPN seamlessly * renegotiates the TLS session by using a new key_id * for the new session. Overlap (controlled by * user definable parameters) between old and new TLS * sessions is allowed, providing a seamless transition * during tunnel operation. * * Payload (n bytes), which may be a P_CONTROL, P_ACK, or P_DATA * message. * * Message types: * * P_CONTROL_HARD_RESET_CLIENT_V1 -- Key method 1, initial key from * client, forget previous state. * * P_CONTROL_HARD_RESET_SERVER_V1 -- Key method 2, initial key * from server, forget previous state. * * P_CONTROL_SOFT_RESET_V1 -- New key, with a graceful transition * from old to new key in the sense that a transition window * exists where both the old or new key_id can be used. OpenVPN * uses two different forms of key_id. The first form is 64 bits * and is used for all P_CONTROL messages. P_DATA messages on the * other hand use a shortened key_id of 3 bits for efficiency * reasons since the vast majority of OpenVPN packets in an * active tunnel will be P_DATA messages. The 64 bit form * is referred to as a session_id, while the 3 bit form is * referred to as a key_id. * * P_CONTROL_V1 -- Control channel packet (usually TLS ciphertext). * * P_ACK_V1 -- Acknowledgement for P_CONTROL packets received. * * P_DATA_V1 -- Data channel packet containing actual tunnel data * ciphertext. * * P_CONTROL_HARD_RESET_CLIENT_V2 -- Key method 2, initial key from * client, forget previous state. * * P_CONTROL_HARD_RESET_SERVER_V2 -- Key method 2, initial key from * server, forget previous state. * * P_CONTROL* and P_ACK Payload: The P_CONTROL message type * indicates a TLS ciphertext packet which has been encapsulated * inside of a reliability layer. The reliability layer is * implemented as a straightforward ACK and retransmit model. * * P_CONTROL message format: * * local session_id (random 64 bit value to identify TLS session). * HMAC signature of entire encapsulation header for integrity * check if --tls-auth is specified (usually 16 or 20 bytes). * packet-id for replay protection (4 or 8 bytes, includes * sequence number and optional time_t timestamp). * P_ACK packet_id array length (1 byte). * P_ACK packet-id array (if length > 0). * P_ACK remote session_id (if length > 0). * message packet-id (4 bytes). * TLS payload ciphertext (n bytes) (only for P_CONTROL). * * Once the TLS session has been initialized and authenticated, * the TLS channel is used to exchange random key material for * bidirectional cipher and HMAC keys which will be * used to secure actual tunnel packets. OpenVPN currently * implements two key methods. Key method 1 directly * derives keys using random bits obtained from the RAND_bytes * OpenSSL function. Key method 2 mixes random key material * from both sides of the connection using the TLS PRF mixing * function. Key method 2 is the preferred method and is the default * for OpenVPN 2.0. * * TLS plaintext content: * * TLS plaintext packet (if key_method == 1): * * Cipher key length in bytes (1 byte). * Cipher key (n bytes). * HMAC key length in bytes (1 byte). * HMAC key (n bytes). * Options string (n bytes, null terminated, client/server options * string should match). * * TLS plaintext packet (if key_method == 2): * * Literal 0 (4 bytes). * key_method type (1 byte). * key_source structure (pre_master only defined for client -> * server). * options_string_length, including null (2 bytes). * Options string (n bytes, null terminated, client/server options * string must match). * [The username/password data below is optional, record can end * at this point.] * username_string_length, including null (2 bytes). * Username string (n bytes, null terminated). * password_string_length, including null (2 bytes). * Password string (n bytes, null terminated). * * The P_DATA payload represents encrypted, encapsulated tunnel * packets which tend to be either IP packets or Ethernet frames. * This is essentially the "payload" of the VPN. * * P_DATA message content: * HMAC of ciphertext IV + ciphertext (if not disabled by * --auth none). * Ciphertext IV (size is cipher-dependent, if not disabled by * --no-iv). * Tunnel packet ciphertext. * * P_DATA plaintext * packet_id (4 or 8 bytes, if not disabled by --no-replay). * In SSL/TLS mode, 4 bytes are used because the implementation * can force a TLS renegotation before 2^32 packets are sent. * In pre-shared key mode, 8 bytes are used (sequence number * and time_t value) to allow long-term key usage without * packet_id collisions. * User plaintext (n bytes). * * Notes: * (1) ACK messages can be encoded in either the dedicated * P_ACK record or they can be prepended to a P_CONTROL message. * (2) P_DATA and P_CONTROL/P_ACK use independent packet-id * sequences because P_DATA is an unreliable channel while * P_CONTROL/P_ACK is a reliable channel. Each use their * own independent HMAC keys. * (3) Note that when --tls-auth is used, all message types are * protected with an HMAC signature, even the initial packets * of the TLS handshake. This makes it easy for OpenVPN to * throw away bogus packets quickly, without wasting resources * on attempting a TLS handshake which will ultimately fail. */ /* Used in the TLS PRF function */ #define KEY_EXPANSION_ID "OpenVPN" /* passwords */ #define UP_TYPE_AUTH "Auth" #define UP_TYPE_PRIVATE_KEY "Private Key" /* packet opcode (high 5 bits) and key-id (low 3 bits) are combined in one byte */ #define P_KEY_ID_MASK 0x07 #define P_OPCODE_SHIFT 3 /* packet opcodes -- the V1 is intended to allow protocol changes in the future */ #define P_CONTROL_HARD_RESET_CLIENT_V1 1 /* initial key from client, forget previous state */ #define P_CONTROL_HARD_RESET_SERVER_V1 2 /* initial key from server, forget previous state */ #define P_CONTROL_SOFT_RESET_V1 3 /* new key, graceful transition from old to new key */ #define P_CONTROL_V1 4 /* control channel packet (usually TLS ciphertext) */ #define P_ACK_V1 5 /* acknowledgement for packets received */ #define P_DATA_V1 6 /* data channel packet */ /* indicates key_method >= 2 */ #define P_CONTROL_HARD_RESET_CLIENT_V2 7 /* initial key from client, forget previous state */ #define P_CONTROL_HARD_RESET_SERVER_V2 8 /* initial key from server, forget previous state */ /* define the range of legal opcodes */ #define P_FIRST_OPCODE 1 #define P_LAST_OPCODE 8 /* key negotiation states */ #define S_ERROR -1 #define S_UNDEF 0 #define S_INITIAL 1 /* tls_init() was called */ #define S_PRE_START 2 /* waiting for initial reset & acknowledgement */ #define S_START 3 /* ready to exchange keys */ #define S_SENT_KEY 4 /* client does S_SENT_KEY -> S_GOT_KEY */ #define S_GOT_KEY 5 /* server does S_GOT_KEY -> S_SENT_KEY */ #define S_ACTIVE 6 /* ready to exchange data channel packets */ #define S_NORMAL 7 /* normal operations */ /* * Are we ready to receive data channel packets? * * Also, if true, we can safely assume session has been * authenticated by TLS. * * NOTE: Assumes S_SENT_KEY + 1 == S_GOT_KEY. */ #define DECRYPT_KEY_ENABLED(multi, ks) ((ks)->state >= (S_GOT_KEY - (multi)->opt.server)) /* Should we aggregate TLS acknowledgements, and tack them onto control packets? */ #define TLS_AGGREGATE_ACK /* * If TLS_AGGREGATE_ACK, set the * max number of acknowledgments that * can "hitch a ride" on an outgoing * non-P_ACK_V1 control packet. */ #define CONTROL_SEND_ACK_MAX 4 /* * Define number of buffers for send and receive in the reliability layer. */ #define TLS_RELIABLE_N_SEND_BUFFERS 4 /* also window size for reliablity layer */ #define TLS_RELIABLE_N_REC_BUFFERS 8 /* * Various timeouts */ #define TLS_MULTI_REFRESH 15 /* call tls_multi_process once every n seconds */ #define TLS_MULTI_HORIZON 2 /* call tls_multi_process frequently for n seconds after every packet sent/received action */ /* The SSL/TLS worker thread will wait at most this many seconds for the interprocess communication pipe to the main thread to be ready to accept writes. */ #define TLS_MULTI_THREAD_SEND_TIMEOUT 5 /* * Buffer sizes (also see mtu.h). */ #define PLAINTEXT_BUFFER_SIZE TLS_CHANNEL_BUF_SIZE /* Maximum length of common name */ #define TLS_CN_LEN 64 /* Legal characters in an X509 or common name */ #define X509_NAME_CHAR_CLASS (CC_ALNUM|CC_UNDERBAR|CC_DASH|CC_DOT|CC_AT|CC_COLON|CC_SLASH|CC_EQUAL) #define COMMON_NAME_CHAR_CLASS (CC_ALNUM|CC_UNDERBAR|CC_DASH|CC_DOT|CC_AT) /* Maximum length of OCC options string passed as part of auth handshake */ #define TLS_OPTIONS_LEN 512 /* * Range of key exchange methods */ #define KEY_METHOD_MIN 1 #define KEY_METHOD_MAX 2 /* key method taken from lower 4 bits */ #define KEY_METHOD_MASK 0x0F /* * Measure success rate of TLS handshakes, for debugging only */ /* #define MEASURE_TLS_HANDSHAKE_STATS */ /* * Key material, used as source for PRF-based * key expansion. */ struct key_source { uint8_t pre_master[48]; /* client generated */ uint8_t random1[32]; /* generated by both client and server */ uint8_t random2[32]; /* generated by both client and server */ }; struct key_source2 { struct key_source client; struct key_source server; }; /* * Represents a single instantiation of a TLS negotiation and * data channel key exchange. 4 keys are kept: encrypt hmac, * decrypt hmac, encrypt cipher, and decrypt cipher. The TLS * control channel is used to exchange these keys. * Each hard or soft reset will build * a fresh key_state. Normally an openvpn session will contain two * key_state objects, one for the current TLS connection, and other * for the retiring or "lame duck" key. The lame duck key_state is * used to maintain transmission continuity on the data-channel while * a key renegotiation is taking place. */ struct key_state { int state; int key_id; /* inherited from struct tls_session below */ SSL *ssl; /* SSL object -- new obj created for each new key */ BIO *ssl_bio; /* read/write plaintext from here */ BIO *ct_in; /* write ciphertext to here */ BIO *ct_out; /* read ciphertext from here */ 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 */ 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 packet_id packet_id; /* for data channel, to prevent replay attacks */ struct key_ctx_bi key; /* data channel keys for encrypt/decrypt/hmac */ 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 */ int n_bytes; /* how many bytes sent/recvd since last key exchange */ int 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. */ bool authenticated; }; /* * Our const options, obtained directly or derived from * command line options. */ struct tls_options { /* our master SSL_CTX from which all SSL objects derived */ SSL_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; #ifdef ENABLE_OCC /* local and remote options strings that must match between client and server */ const char *local_options; const char *remote_options; #endif /* from command line */ int key_method; bool replay; bool single_session; #ifdef ENABLE_OCC bool disable_occ; #endif int transition_window; int handshake_window; interval_t packet_timeout; int renegotiate_bytes; int renegotiate_packets; interval_t renegotiate_seconds; /* cert verification parms */ const char *verify_command; const char *verify_x509name; const char *crl_file; int ns_cert_type; unsigned remote_cert_ku[MAX_PARMS]; const char *remote_cert_eku; /* allow openvpn config info to be passed over control channel */ bool pass_config_info; /* struct crypto_option flags */ unsigned int crypto_flags_and; unsigned int crypto_flags_or; int replay_window; /* --replay-window parm */ int replay_time; /* --replay-window parm */ /* packet authentication for TLS handshake */ struct crypto_options tls_auth; struct key_ctx_bi tls_auth_key; /* frame parameters for TLS control channel */ struct frame frame; /* used for username/password authentication */ const char *auth_user_pass_verify_script; bool auth_user_pass_verify_script_via_file; const char *tmp_dir; bool username_as_common_name; /* use the client-config-dir as a positive authenticator */ const char *client_config_dir_exclusive; /* instance-wide environment variable set */ struct env_set *es; const struct plugin_list *plugins; /* --gremlin bits */ int gremlin; }; /* index into tls_session.key */ #define KS_PRIMARY 0 /* the primary key */ #define KS_LAME_DUCK 1 /* the key that's going to retire soon */ #define KS_SIZE 2 /* * A tls_session lives through multiple key_state life-cycles. Soft resets * will reuse a tls_session object, but hard resets or errors will require * that a fresh object be built. Normally three tls_session objects are maintained * by an active openvpn session. The first is the current, TLS authenticated * session, the second is used to process connection requests from a new * client that would usurp the current session if successfully authenticated, * and the third is used as a repository for a "lame-duck" key in the event * that the primary session resets due to error while the lame-duck key still * has time left before its expiration. Lame duck keys are used to maintain * the continuity of the data channel connection while a new key is being * negotiated. */ struct tls_session { /* const options and config info */ const struct tls_options *opt; /* during hard reset used to control burst retransmit */ bool burst; /* authenticate control packets */ struct crypto_options tls_auth; struct packet_id tls_auth_pid; int initial_opcode; /* our initial P_ opcode */ struct session_id session_id; /* our random session ID */ int key_id; /* increments with each soft reset (for key renegotiation) */ int limit_next; /* used for traffic shaping on the control channel */ int verify_maxlevel; char *common_name; 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]; }; /* index into tls_multi.session */ #define TM_ACTIVE 0 #define TM_UNTRUSTED 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 /* * An openvpn session running with TLS enabled has one tls_multi object. */ 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; /* * A list of key_state objects in the order they should be * scanned by data channel encrypt and decrypt routines. */ struct key_state* key_scan[KEY_SCAN_SIZE]; /* * 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; /* * Number of sessions negotiated thus far. */ int n_sessions; /* * 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 */ /* * Our locked common name (cannot change during the life of this tls_multi object) */ char *locked_cn; /* * Our session objects. */ struct tls_session session[TM_SIZE]; }; /* * Used in --mode server mode to check tls-auth signature on initial * packets received from new clients. */ struct tls_auth_standalone { struct key_ctx_bi tls_auth_key; struct crypto_options tls_auth_options; struct frame frame; }; void init_ssl_lib (void); void free_ssl_lib (void); /* Build master SSL_CTX object that serves for the whole of openvpn instantiation */ SSL_CTX *init_ssl (const struct options *options); struct tls_multi *tls_multi_init (struct tls_options *tls_options); struct tls_auth_standalone *tls_auth_standalone_init (struct tls_options *tls_options, struct gc_arena *gc); void tls_auth_standalone_finalize (struct tls_auth_standalone *tas, const struct frame *frame); void tls_multi_init_finalize(struct tls_multi *multi, const struct frame *frame); void tls_multi_init_set_options(struct tls_multi* multi, const char *local, const char *remote); bool tls_multi_process (struct tls_multi *multi, struct buffer *to_link, struct link_socket_actual **to_link_addr, struct link_socket_info *to_link_socket_info, interval_t *wakeup); void tls_multi_free (struct tls_multi *multi, bool clear); bool tls_pre_decrypt (struct tls_multi *multi, const struct link_socket_actual *from, struct buffer *buf, struct crypto_options *opt); bool tls_pre_decrypt_lite (const struct tls_auth_standalone *tas, const struct link_socket_actual *from, const struct buffer *buf); void tls_pre_encrypt (struct tls_multi *multi, struct buffer *buf, struct crypto_options *opt); void tls_post_encrypt (struct tls_multi *multi, struct buffer *buf); void show_available_tls_ciphers (void); void get_highest_preference_tls_cipher (char *buf, int size); void pem_password_setup (const char *auth_file); int pem_password_callback (char *buf, int size, int rwflag, void *u); void auth_user_pass_setup (const char *auth_file); void ssl_set_auth_nocache (void); void ssl_purge_auth (void); void tls_set_verify_command (const char *cmd); void tls_set_crl_verify (const char *crl); void tls_set_verify_x509name (const char *x509name); void tls_adjust_frame_parameters(struct frame *frame); bool tls_send_payload (struct tls_multi *multi, const uint8_t *data, int size); bool tls_rec_payload (struct tls_multi *multi, struct buffer *buf); const char *tls_common_name (struct tls_multi* multi, bool null); void tls_set_common_name (struct tls_multi *multi, const char *common_name); void tls_lock_common_name (struct tls_multi *multi); bool tls_authenticated (struct tls_multi *multi); void tls_deauthenticate (struct tls_multi *multi); /* * inline functions */ static inline int tls_test_payload_len (const struct tls_multi *multi) { if (multi) { const struct key_state *ks = &multi->session[TM_ACTIVE].key[KS_PRIMARY]; if (ks->state >= S_ACTIVE) return BLEN (&ks->plaintext_read_buf); } return 0; } static inline void tls_set_single_session (struct tls_multi *multi) { if (multi) multi->opt.single_session = true; } /* * protocol_dump() flags */ #define PD_TLS_AUTH_HMAC_SIZE_MASK 0xFF #define PD_SHOW_DATA (1<<8) #define PD_TLS (1<<9) #define PD_VERBOSE (1<<10) const char *protocol_dump (struct buffer *buffer, unsigned int flags, struct gc_arena *gc); /* * debugging code */ #ifdef MEASURE_TLS_HANDSHAKE_STATS void show_tls_performance_stats(void); #endif /*#define EXTRACT_X509_FIELD_TEST*/ void extract_x509_field_test (void); #endif /* USE_CRYPTO && USE_SSL */ #endif