src/openvpn/crypto.h

   1 /*
   2  *  OpenVPN -- An application to securely tunnel IP networks
   3  *             over a single TCP/UDP port, with support for SSL/TLS-based
   4  *             session authentication and key exchange,
   5  *             packet encryption, packet authentication, and
   6  *             packet compression.
   7  *
   8  *  Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net>
   9  *  Copyright (C) 2010-2014 Fox Crypto B.V. <openvpn@fox-it.com>
  10  *
  11  *  This program is free software; you can redistribute it and/or modify
  12  *  it under the terms of the GNU General Public License version 2
  13  *  as published by the Free Software Foundation.
  14  *
  15  *  This program is distributed in the hope that it will be useful,
  16  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  *  GNU General Public License for more details.
  19  *
  20  *  You should have received a copy of the GNU General Public License
  21  *  along with this program (see the file COPYING included with this
  22  *  distribution); if not, write to the Free Software Foundation, Inc.,
  23  *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24  */
  25
  26 /**
  27  * @file Data Channel Cryptography Module
  28  *
  29  * @addtogroup data_crypto Data Channel Crypto module
  30  *
  31  * @par Crypto packet formats
  32  * The Data Channel Crypto module supports a number of crypto modes and
  33  * configurable options. The actual packet format depends on these options. A
  34  * Data Channel packet can consist of:
  35  *  - \b Opcode, one byte specifying the packet type (see @ref network_protocol
  36  *    "Network protocol").
  37  *  - \b Peer-id, if using the v2 data channel packet format (see @ref
  38  *    network_protocol "Network protocol").
  39  *  - \b HMAC, covering the ciphertext IV + ciphertext. The HMAC size depends
  40  *    on the \c \-\-auth option. If \c \-\-auth \c none is specified, there is no
  41  *    HMAC at all.
  42  *  - \b Ciphertext \b IV, if not disabled by \c \-\-no-iv. The IV size depends on
  43  *    the \c \-\-cipher option.
  44  *  - \b Packet \b ID, a 32-bit incrementing packet counter that provides replay
  45  *    protection (if not disabled by \c \-\-no-replay).
  46  *  - \b Timestamp, a 32-bit timestamp of the current time.
  47  *  - \b Payload, the plain text network packet to be encrypted (unless
  48  *    encryption is disabled by using \c \-\-cipher \c none). The payload might
  49  *    already be compressed (see @ref compression "Compression module").
  50  *
  51  * @par
  52  * This section does not discuss the opcode and peer-id, since those do not
  53  * depend on the data channel crypto. See @ref network_protocol
  54  * "Network protocol" for more information on those.
  55  *
  56  * @par
  57  * \e Legenda \n
  58  * <tt>[ xxx ]</tt> = unprotected \n
  59  * <tt>[ - xxx - ]</tt> = authenticated \n
  60  * <tt>[ * xxx * ]</tt> = encrypted and authenticated
  61  *
  62  * @par
  63  * <b>CBC data channel cypto format</b> \n
  64  * In CBC mode, both TLS-mode and static key mode are supported. The IV
  65  * consists of random bits to provide unpredictable IVs. \n
  66  * <i>CBC IV format:</i> \n
  67  * <tt> [ - random - ] </tt> \n
  68  * <i>CBC data channel crypto format in TLS-mode:</i> \n
  69  * <tt> [ HMAC ] [ - IV - ] [ * packet ID * ] [ * packet payload * ] </tt> \n
  70  * <i>CBC data channel crypto format in static key mode:</i> \n
  71  * <tt> [ HMAC ] [ - IV - ] [ * packet ID * ] [ * timestamp * ]
  72  * [ * packet payload * ] </tt>
  73  *
  74  * @par
  75  * <b>CFB/OFB data channel crypto format</b> \n
  76  * CFB and OFB modes are only supported in TLS mode. In these modes, the IV
  77  * consists of the packet counter and a timestamp. If the IV is more than 8
  78  * bytes long, the remaining space is filled with zeroes. The packet counter may
  79  * not roll over within a single TLS sessions. This results in a unique IV for
  80  * each packet, as required by the CFB and OFB cipher modes.
  81  *
  82  * @par
  83  * <i>CFB/OFB IV format:</i> \n
  84  * <tt>   [ - packet ID - ] [ - timestamp - ] [ - opt: zero-padding - ] </tt>\n
  85  * <i>CFB/OFB data channel crypto format:</i> \n
  86  * <tt>   [ HMAC ] [ - IV - ] [ * packet payload * ] </tt>
  87  *
  88  * @par
  89  * <b>GCM data channel crypto format</b> \n
  90  * GCM modes are only supported in TLS mode.  In these modes, the IV consists of
  91  * the 32-bit packet counter followed by data from the HMAC key.  The HMAC key
  92  * can be used as IV, since in GCM and CCM modes the HMAC key is not used for
  93  * the HMAC.  The packet counter may not roll over within a single TLS sessions.
  94  * This results in a unique IV for each packet, as required by GCM.
  95  *
  96  * @par
  97  * The HMAC key data is pre-shared during the connection setup, and thus can be
  98  * omitted in on-the-wire packets, saving 8 bytes per packet (for GCM and CCM).
  99  *
 100  * @par
 101  * In GCM mode, P_DATA_V2 headers (the opcode and peer-id) are also
 102  * authenticated as Additional Data.
 103  *
 104  * @par
 105  * <i>GCM IV format:</i> \n
 106  * <tt>   [ - packet ID - ] [ - HMAC key data - ] </tt>\n
 107  * <i>P_DATA_V1 GCM data channel crypto format:</i> \n
 108  * <tt>   [ opcode ] [ - packet ID - ] [ TAG ] [ * packet payload * ] </tt>
 109  * <i>P_DATA_V2 GCM data channel crypto format:</i> \n
 110  * <tt>   [ - opcode/peer-id - ] [ - packet ID - ] [ TAG ] [ * packet payload * ] </tt>
 111  *
 112  * @par
 113  * <b>No-crypto data channel format</b> \n
 114  * In no-crypto mode (\c \-\-cipher \c none is specified), both TLS-mode and
 115  * static key mode are supported. No encryption will be performed on the packet,
 116  * but packets can still be authenticated. This mode does not require an IV.\n
 117  * <i>No-crypto data channel crypto format in TLS-mode:</i> \n
 118  * <tt> [ HMAC ] [ - packet ID - ] [ - packet payload - ] </tt> \n
 119  * <i>No-crypto data channel crypto format in static key mode:</i> \n
 120  * <tt> [ HMAC ] [ - packet ID - ] [ - timestamp - ] [ - packet payload - ] </tt>
 121  *
 122  */
 123
 124 #ifndef CRYPTO_H
 125 #define CRYPTO_H
 126
 127 #ifdef ENABLE_CRYPTO
 128
 129 #include "crypto_backend.h"
 130 #include "basic.h"
 131 #include "buffer.h"
 132 #include "packet_id.h"
 133 #include "mtu.h"
 134
 135 /** Wrapper struct to pass around MD5 digests */
 136 struct md5_digest {
 137   uint8_t digest[MD5_DIGEST_LENGTH];
 138 };
 139
 140 /*
 141  * Defines a key type and key length for both cipher and HMAC.
 142  */
 143 struct key_type
 144 {
 145   uint8_t cipher_length;        /**< Cipher length, in bytes */
 146   uint8_t hmac_length;          /**< HMAC length, in bytes */
 147   const cipher_kt_t *cipher;    /**< Cipher static parameters */
 148   const md_kt_t *digest;        /**< Message digest static parameters */
 149 };
 150
 151 /**
 152  * Container for unidirectional cipher and HMAC %key material.
 153  * @ingroup control_processor
 154  */
 155 struct key
 156 {
 157   uint8_t cipher[MAX_CIPHER_KEY_LENGTH];
 158                                 /**< %Key material for cipher operations. */
 159   uint8_t hmac[MAX_HMAC_KEY_LENGTH];
 160                                 /**< %Key material for HMAC operations. */
 161 };
 162
 163
 164 /**
 165  * Container for one set of cipher and/or HMAC contexts.
 166  * @ingroup control_processor
 167  */
 168 struct key_ctx
 169 {
 170   cipher_ctx_t *cipher;         /**< Generic cipher %context. */
 171   hmac_ctx_t *hmac;             /**< Generic HMAC %context. */
 172   uint8_t implicit_iv[OPENVPN_MAX_IV_LENGTH];
 173                                 /**< The implicit part of the IV */
 174   size_t implicit_iv_len;       /**< The length of implicit_iv */
 175 };
 176
 177 #define KEY_DIRECTION_BIDIRECTIONAL 0 /* same keys for both directions */
 178 #define KEY_DIRECTION_NORMAL        1 /* encrypt with keys[0], decrypt with keys[1] */
 179 #define KEY_DIRECTION_INVERSE       2 /* encrypt with keys[1], decrypt with keys[0] */
 180
 181 /**
 182  * Container for bidirectional cipher and HMAC %key material.
 183  * @ingroup control_processor
 184  */
 185 struct key2
 186 {
 187   int n;                        /**< The number of \c key objects stored
 188                                  *   in the \c key2.keys array. */
 189   struct key keys[2];           /**< Two unidirectional sets of %key
 190                                  *   material. */
 191 };
 192
 193 /**
 194  * %Key ordering of the \c key2.keys array.
 195  * @ingroup control_processor
 196  *
 197  * This structure takes care of correct ordering when using unidirectional
 198  * or bidirectional %key material, and allows the same shared secret %key
 199  * file to be loaded in the same way by client and server by having one of
 200  * the hosts use an reversed ordering.
 201  */
 202 struct key_direction_state
 203 {
 204   int out_key;                  /**< Index into the \c key2.keys array for
 205                                  *   the sending direction. */
 206   int in_key;                   /**< Index into the \c key2.keys array for
 207                                  *   the receiving direction. */
 208   int need_keys;                /**< The number of key objects necessary
 209                                  *   to support both sending and
 210                                  *   receiving.
 211                                  *
 212                                  *   This will be 1 if the same keys are
 213                                  *   used in both directions, or 2 if
 214                                  *   there are two sets of unidirectional
 215                                  *   keys. */
 216 };
 217
 218 /**
 219  * Container for two sets of OpenSSL cipher and/or HMAC contexts for both
 220  * sending and receiving directions.
 221  * @ingroup control_processor
 222  */
 223 struct key_ctx_bi
 224 {
 225   struct key_ctx encrypt;       /**< Cipher and/or HMAC contexts for sending
 226                                  *   direction. */
 227   struct key_ctx decrypt;       /**< cipher and/or HMAC contexts for
 228                                  *   receiving direction. */
 229 };
 230
 231 /**
 232  * Security parameter state for processing data channel packets.
 233  * @ingroup data_crypto
 234  */
 235 struct crypto_options
 236 {
 237   struct key_ctx_bi key_ctx_bi;
 238                                 /**< OpenSSL cipher and HMAC contexts for
 239                                  *   both sending and receiving
 240                                  *   directions. */
 241   struct packet_id packet_id;   /**< Current packet ID state for both
 242                                  *   sending and receiving directions. */
 243   struct packet_id_persist *pid_persist;
 244                                 /**< Persistent packet ID state for
 245                                  *   keeping state between successive
 246                                  *   OpenVPN process startups. */
 247
 248 # define CO_PACKET_ID_LONG_FORM  (1<<0)
 249                                 /**< Bit-flag indicating whether to use
 250                                  *   OpenVPN's long packet ID format. */
 251 # define CO_USE_IV               (1<<1)
 252                                 /**< Bit-flag indicating whether to
 253                                  *   generate a pseudo-random IV for each
 254                                  *   packet being encrypted. */
 255 # define CO_IGNORE_PACKET_ID     (1<<2)
 256                                 /**< Bit-flag indicating whether to ignore
 257                                  *   the packet ID of a received packet.
 258                                  *   This flag is used during processing
 259                                  *   of the first packet received from a
 260                                  *   client. */
 261 # define CO_MUTE_REPLAY_WARNINGS (1<<3)
 262                                 /**< Bit-flag indicating not to display
 263                                  *   replay warnings. */
 264   unsigned int flags;           /**< Bit-flags determining behavior of
 265                                  *   security operation functions. */
 266 };
 267
 268 /**
 269  * Minimal IV length for AEAD mode ciphers (in bytes):
 270  * 4-byte packet id + 8 bytes implicit IV.
 271  */
 272 #define OPENVPN_AEAD_MIN_IV_LEN (sizeof (packet_id_type) + 8)
 273
 274 #define RKF_MUST_SUCCEED (1<<0)
 275 #define RKF_INLINE       (1<<1)
 276 void read_key_file (struct key2 *key2, const char *file, const unsigned int flags);
 277
 278 int write_key_file (const int nkeys, const char *filename);
 279
 280 int read_passphrase_hash (const char *passphrase_file,
 281                           const md_kt_t *digest,
 282                           uint8_t *output,
 283                           int len);
 284
 285 void generate_key_random (struct key *key, const struct key_type *kt);
 286
 287 void check_replay_iv_consistency(const struct key_type *kt, bool packet_id, bool use_iv);
 288
 289 bool check_key (struct key *key, const struct key_type *kt);
 290
 291 void fixup_key (struct key *key, const struct key_type *kt);
 292
 293 bool write_key (const struct key *key, const struct key_type *kt,
 294                 struct buffer *buf);
 295
 296 int read_key (struct key *key, const struct key_type *kt, struct buffer *buf);
 297
 298 void init_key_type (struct key_type *kt, const char *ciphername,
 299     bool ciphername_defined, const char *authname, bool authname_defined,
 300     int keysize, bool tls_mode, bool warn);
 301
 302 /*
 303  * Key context functions
 304  */
 305
 306 void init_key_ctx (struct key_ctx *ctx, struct key *key,
 307                    const struct key_type *kt, int enc,
 308                    const char *prefix);
 309
 310 void free_key_ctx (struct key_ctx *ctx);
 311
 312 void free_key_ctx_bi (struct key_ctx_bi *ctx);
 313
 314
 315 /**************************************************************************/
 316 /** @name Functions for performing security operations on data channel packets
 317  *  @{ */
 318
 319 /**
 320  * Encrypt and HMAC sign a packet so that it can be sent as a data channel
 321  * VPN tunnel packet to a remote OpenVPN peer.
 322  * @ingroup data_crypto
 323  *
 324  * This function handles encryption and HMAC signing of a data channel
 325  * packet before it is sent to its remote OpenVPN peer.  It receives the
 326  * necessary security parameters in the \a opt argument, which should have
 327  * been set to the correct values by the \c tls_pre_encrypt() function.
 328  *
 329  * This function calls the \c EVP_Cipher* and \c HMAC_* functions of the
 330  * OpenSSL library to perform the actual security operations.
 331  *
 332  * If an error occurs during processing, then the \a buf %buffer is set to
 333  * empty.
 334  *
 335  * @param buf          - The %buffer containing the packet on which to
 336  *                       perform security operations.
 337  * @param work         - An initialized working %buffer.
 338  * @param opt          - The security parameter state for this VPN tunnel.
 339  *
 340  * @return This function returns void.\n On return, the \a buf argument
 341  *     will point to the resulting %buffer.  This %buffer will either
 342  *     contain the processed packet ready for sending, or be empty if an
 343  *     error occurred.
 344  */
 345 void openvpn_encrypt (struct buffer *buf, struct buffer work,
 346                       struct crypto_options *opt);
 347
 348
 349 /**
 350  * HMAC verify and decrypt a data channel packet received from a remote
 351  * OpenVPN peer.
 352  * @ingroup data_crypto
 353  *
 354  * This function handles authenticating and decrypting a data channel
 355  * packet received from a remote OpenVPN peer.  It receives the necessary
 356  * security parameters in the \a opt argument, which should have been set
 357  * to the correct values by the \c tls_pre_decrypt() function.
 358  *
 359  * This function calls the \c EVP_Cipher* and \c HMAC_* functions of the
 360  * OpenSSL library to perform the actual security operations.
 361  *
 362  * If an error occurs during processing, then the \a buf %buffer is set to
 363  * empty.
 364  *
 365  * @param buf          - The %buffer containing the packet received from a
 366  *                       remote OpenVPN peer on which to perform security
 367  *                       operations.
 368  * @param work         - A working %buffer.
 369  * @param opt          - The security parameter state for this VPN tunnel.
 370  * @param frame        - The packet geometry parameters for this VPN
 371  *                       tunnel.
 372  * @param ad_start     - A pointer into buf, indicating from where to start
 373  *                       authenticating additional data (AEAD mode only).
 374  *
 375  * @return
 376  * @li True, if the packet was authenticated and decrypted successfully.
 377  * @li False, if an error occurred. \n On return, the \a buf argument will
 378  *     point to the resulting %buffer.  This %buffer will either contain
 379  *     the plaintext packet ready for further processing, or be empty if
 380  *     an error occurred.
 381  */
 382 bool openvpn_decrypt (struct buffer *buf, struct buffer work,
 383                       struct crypto_options *opt, const struct frame* frame,
 384                       const uint8_t *ad_start);
 385
 386 /** @} name Functions for performing security operations on data channel packets */
 387
 388 void crypto_adjust_frame_parameters(struct frame *frame,
 389                                     const struct key_type* kt,
 390                                     bool cipher_defined,
 391                                     bool use_iv,
 392                                     bool packet_id,
 393                                     bool packet_id_long_form);
 394
 395
 396 /* Minimum length of the nonce used by the PRNG */
 397 #define NONCE_SECRET_LEN_MIN 16
 398
 399 /* Maximum length of the nonce used by the PRNG */
 400 #define NONCE_SECRET_LEN_MAX 64
 401
 402 /** Number of bytes of random to allow before resetting the nonce */
 403 #define PRNG_NONCE_RESET_BYTES 1024
 404
 405 /**
 406  * Pseudo-random number generator initialisation.
 407  * (see \c prng_rand_bytes())
 408  *
 409  * @param md_name                       Name of the message digest to use
 410  * @param nonce_secret_len_param        Length of the nonce to use
 411  */
 412 void prng_init (const char *md_name, const int nonce_secret_len_parm);
 413
 414 /*
 415  * Message digest-based pseudo random number generator.
 416  *
 417  * If the PRNG was initialised with a certain message digest, uses the digest
 418  * to calculate the next random number, and prevent depletion of the entropy
 419  * pool.
 420  *
 421  * This PRNG is aimed at IV generation and similar miscellaneous tasks. Use
 422  * \c rand_bytes() for higher-assurance functionality.
 423  *
 424  * Retrieves len bytes of pseudo random data, and places it in output.
 425  *
 426  * @param output        Output buffer
 427  * @param len           Length of the output buffer
 428  */
 429 void prng_bytes (uint8_t *output, int len);
 430
 431 void prng_uninit ();
 432
 433 void test_crypto (struct crypto_options *co, struct frame* f);
 434
 435
 436 /* key direction functions */
 437
 438 void key_direction_state_init (struct key_direction_state *kds, int key_direction);
 439
 440 void verify_fix_key2 (struct key2 *key2, const struct key_type *kt, const char *shared_secret_file);
 441
 442 void must_have_n_keys (const char *filename, const char *option, const struct key2 *key2, int n);
 443
 444 int ascii2keydirection (int msglevel, const char *str);
 445
 446 const char *keydirection2ascii (int kd, bool remote);
 447
 448 /* print keys */
 449 void key2_print (const struct key2* k,
 450                  const struct key_type *kt,
 451                  const char* prefix0,
 452                  const char* prefix1);
 453
 454 #define GHK_INLINE  (1<<0)
 455 void get_tls_handshake_key (const struct key_type *key_type,
 456                             struct key_ctx_bi *ctx,
 457                             const char *passphrase_file,
 458                             const int key_direction,
 459                             const unsigned int flags);
 460
 461 /*
 462  * Inline functions
 463  */
 464
 465 static inline bool
 466 key_ctx_bi_defined(const struct key_ctx_bi* key)
 467 {
 468   return key->encrypt.cipher || key->encrypt.hmac || key->decrypt.cipher || key->decrypt.hmac;
 469 }
 470
 471
 472 #endif /* ENABLE_CRYPTO */
 473 #endif /* CRYPTO_H */