ssl.h

OpenVPN is a robust and highly flexible tunneling application that uses all of the encryption, authe

/*
 *  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-2004 James Yonan <[e-mail]>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  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 <openssl/ssl.h>
#include <openssl/bio.h>
#include <openssl/rand.h>
#include <openssl/err.h>

#include "basic.h"
#include "crypto.h"
#include "packet_id.h"
#include "session_id.h"
#include "reliable.h"
#include "socket.h"
#include "mtu.h"
#include "thread.h"

/*
 * Openvpn Protocol.
 *
 * TCP/UDP Packet:
 *   packet length (16 bits, unsigned) -- TCP only, always sent as plaintext
 *   packet opcode (high 5 bits, see P_ constants below)
 *   key_id (low 3 bits, see key_id in struct tls_session below for comment)
 *   payload (n bytes)
 *
 * P_CONTROL* and P_ACK Payload:
 *   session_id (random 64 bit value to identify session)
 *   hmac for authentication (usually 16 or 20 bytes)
 *   packet-id for replay protection (4 or 8 bytes, includes
 *     sequence number and optional time_t timestamp)
 *   acknowledge packet_id array length (1 byte)
 *   acknowledge packet-id array (if length > 0)
 *   acknowledge remote session_id (if length > 0)
 *   control packet-id (4 bytes)
 *   TLS ciphertext (n bytes) (only for P_CONTROL)
 *
 * TLS plaintext packet (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 must match)
 *
 * TLS plaintext packet (key_method >= 2):
 *   0 (4 bytes)
 *   key_method (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)
 *
 * P_DATA Payload:
 *   hmac of ciphertext IV + ciphertext (if enabled by --auth)
 *   ciphertext IV (size is cipher-dependent, if not disabled by --no-iv)
 *   P_DATA ciphertext
 *
 * P_DATA plaintext
 *   packet_id (4 or 8 bytes, if not disabled by --no-replay)
 *   user plaintext (n bytes)
 *
 * Notes:
 *   (1) Acknowledgements can be encoded in either the dedicated P_ACK record
 *       or they can be prepended to a P_CONTROL* record.
 *   (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.
 */

/* Used in the TLS PRF function */
#define KEY_EXPANSION_ID "OpenVPN"

/* 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 1024

/* Maximum length of common name */
#define TLS_CN_LEN 64

/*
 * 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

/* high 4 bits in key_method uint8_t is used for flags */
#define TLS_PASS_CONFIG_INFO 0x10

/*
 * 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 sockaddr_in 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 */
};

/*
 * 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;