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-2018 OpenVPN Inc <sales@openvpn.net> 9 * Copyright (C) 2010-2018 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 along 21 * with this program; if not, write to the Free Software Foundation, Inc., 22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 23 */ 24 25 /** 26 * @file Data Channel Cryptography SSL library-specific backend interface 27 */ 28 29 #ifndef CRYPTO_BACKEND_H_ 30 #define CRYPTO_BACKEND_H_ 31 32 #ifdef ENABLE_CRYPTO_OPENSSL 33 #include "crypto_openssl.h" 34 #endif 35 #ifdef ENABLE_CRYPTO_MBEDTLS 36 #include "crypto_mbedtls.h" 37 #endif 38 #include "basic.h" 39 #include "buffer.h" 40 41 /* TLS uses a tag of 128 bytes, let's do the same for OpenVPN */ 42 #define OPENVPN_AEAD_TAG_LENGTH 16 43 44 /* Maximum cipher block size (bytes) */ 45 #define OPENVPN_MAX_CIPHER_BLOCK_SIZE 32 46 47 /* Maximum HMAC digest size (bytes) */ 48 #define OPENVPN_MAX_HMAC_SIZE 64 49 50 /** Types referencing specific message digest hashing algorithms */ 51 typedef enum { 52 MD_SHA1, 53 MD_SHA256 54 } hash_algo_type; 55 56 /** Struct used in cipher name translation table */ 57 typedef struct { 58 const char *openvpn_name; /**< Cipher name used by OpenVPN */ 59 const char *lib_name; /**< Cipher name used by crypto library */ 60 } cipher_name_pair; 61 62 /** Cipher name translation table */ 63 extern const cipher_name_pair cipher_name_translation_table[]; 64 extern const size_t cipher_name_translation_table_count; 65 66 /* 67 * This routine should have additional OpenSSL crypto library initialisations 68 * used by both crypto and ssl components of OpenVPN. 69 */ 70 void crypto_init_lib(void); 71 72 void crypto_uninit_lib(void); 73 74 void crypto_clear_error(void); 75 76 /* 77 * Initialise the given named crypto engine. 78 */ 79 void crypto_init_lib_engine(const char *engine_name); 80 81 #ifdef DMALLOC 82 /* 83 * OpenSSL memory debugging. If dmalloc debugging is enabled, tell 84 * OpenSSL to use our private malloc/realloc/free functions so that 85 * we can dispatch them to dmalloc. 86 */ 87 void crypto_init_dmalloc(void); 88 89 #endif /* DMALLOC */ 90 91 /** 92 * Translate a data channel cipher name from the OpenVPN config file 93 * 'language' to the crypto library specific name. 94 */ 95 const char *translate_cipher_name_from_openvpn(const char *cipher_name); 96 97 /** 98 * Translate a data channel cipher name from the crypto library specific name 99 * to the OpenVPN config file 'language'. 100 */ 101 const char *translate_cipher_name_from_openvpn(const char *cipher_name); 102 103 void show_available_ciphers(void); 104 105 void show_available_digests(void); 106 107 void show_available_engines(void); 108 109 /** 110 * Encode binary data as PEM. 111 * 112 * @param name The name to use in the PEM header/footer. 113 * @param dst Destination buffer for PEM-encoded data. Must be a valid 114 * pointer to an uninitialized buffer structure. Iff this 115 * function returns true, the buffer will contain memory 116 * allocated through the supplied gc. 117 * @param src Source buffer. 118 * @param gc The garbage collector to use when allocating memory for dst. 119 * 120 * @return true iff PEM encode succeeded. 121 */ 122 bool crypto_pem_encode(const char *name, struct buffer *dst, 123 const struct buffer *src, struct gc_arena *gc); 124 125 /** 126 * Decode a PEM buffer to binary data. 127 * 128 * @param name The name expected in the PEM header/footer. 129 * @param dst Destination buffer for decoded data. 130 * @param src Source buffer (PEM data). 131 * 132 * @return true iff PEM decode succeeded. 133 */ 134 bool crypto_pem_decode(const char *name, struct buffer *dst, 135 const struct buffer *src); 136 137 /* 138 * 139 * Random number functions, used in cases where we want 140 * reasonably strong cryptographic random number generation 141 * without depleting our entropy pool. Used for random 142 * IV values and a number of other miscellaneous tasks. 143 * 144 */ 145 146 /** 147 * Wrapper for secure random number generator. Retrieves len bytes of random 148 * data, and places it in output. 149 * 150 * @param output Output buffer 151 * @param len Length of the output buffer, in bytes 152 * 153 * @return \c 1 on success, \c 0 on failure 154 */ 155 int rand_bytes(uint8_t *output, int len); 156 157 /* 158 * 159 * Key functions, allow manipulation of keys. 160 * 161 */ 162 163 164 /** 165 * Return number of DES cblocks (1 cblock = length of a single-DES key) for the 166 * current key type or 0 if not a DES cipher. 167 * 168 * @param kt Type of key 169 * 170 * @return Number of DES cblocks that the key consists of, or 0. 171 */ 172 int key_des_num_cblocks(const cipher_kt_t *kt); 173 174 /* 175 * Check the given DES key. Checks the given key's length, weakness and parity. 176 * 177 * @param key Key to check 178 * @param key_len Length of the key, in bytes 179 * @param ndc Number of DES cblocks that the key is made up of. 180 * 181 * @return \c true if the key is valid, \c false otherwise. 182 */ 183 bool key_des_check(uint8_t *key, int key_len, int ndc); 184 185 /* 186 * Fix the given DES key, setting its parity to odd. 187 * 188 * @param key Key to check 189 * @param key_len Length of the key, in bytes 190 * @param ndc Number of DES cblocks that the key is made up of. 191 */ 192 void key_des_fixup(uint8_t *key, int key_len, int ndc); 193 194 /** 195 * Encrypt the given block, using DES ECB mode 196 * 197 * @param key DES key to use. 198 * @param src Buffer containing the 8-byte source. 199 * @param dst Buffer containing the 8-byte destination 200 */ 201 void cipher_des_encrypt_ecb(const unsigned char key[DES_KEY_LENGTH], 202 unsigned char src[DES_KEY_LENGTH], 203 unsigned char dst[DES_KEY_LENGTH]); 204 205 /* 206 * 207 * Generic cipher key type functions 208 * 209 */ 210 /* 211 * Max size in bytes of any cipher key that might conceivably be used. 212 * 213 * This value is checked at compile time in crypto.c to make sure 214 * it is always at least EVP_MAX_KEY_LENGTH. 215 * 216 * We define our own value, since this parameter 217 * is used to control the size of static key files. 218 * If the OpenSSL library increases EVP_MAX_KEY_LENGTH, 219 * we don't want our key files to be suddenly rendered 220 * unusable. 221 */ 222 #define MAX_CIPHER_KEY_LENGTH 64 223 224 /** 225 * Return cipher parameters, based on the given cipher name. The 226 * contents of these parameters are library-specific, and can be used to 227 * initialise encryption/decryption. 228 * 229 * @param ciphername Name of the cipher to retrieve parameters for (e.g. 230 * \c AES-128-CBC). Will be translated to the library name 231 * from the openvpn config name if needed. 232 * 233 * @return A statically allocated structure containing parameters 234 * for the given cipher, or NULL if no matching parameters 235 * were found. 236 */ 237 const cipher_kt_t *cipher_kt_get(const char *ciphername); 238 239 /** 240 * Retrieve a string describing the cipher (e.g. \c AES-128-CBC). 241 * The returned name is normalised to the OpenVPN config name in case the 242 * name differs from the name used by the crypto library. 243 * 244 * Returns [null-cipher] in case the cipher_kt is NULL. 245 * 246 * @param cipher_kt Static cipher parameters 247 * 248 * @return a statically allocated string describing the cipher. 249 */ 250 const char *cipher_kt_name(const cipher_kt_t *cipher_kt); 251 252 /** 253 * Returns the size of keys used by the cipher, in bytes. If the cipher has a 254 * variable key size, return the default key size. 255 * 256 * @param cipher_kt Static cipher parameters 257 * 258 * @return (Default) size of keys used by the cipher, in bytes. 259 */ 260 int cipher_kt_key_size(const cipher_kt_t *cipher_kt); 261 262 /** 263 * Returns the size of the IV used by the cipher, in bytes, or 0 if no IV is 264 * used. 265 * 266 * @param cipher_kt Static cipher parameters 267 * 268 * @return Size of the IV, in bytes, or 0 if the cipher does not 269 * use an IV. 270 */ 271 int cipher_kt_iv_size(const cipher_kt_t *cipher_kt); 272 273 /** 274 * Returns the block size of the cipher, in bytes. 275 * 276 * @param cipher_kt Static cipher parameters 277 * 278 * @return Block size, in bytes. 279 */ 280 int cipher_kt_block_size(const cipher_kt_t *cipher_kt); 281 282 /** 283 * Returns the MAC tag size of the cipher, in bytes. 284 * 285 * @param ctx Static cipher parameters. 286 * 287 * @return Tag size in bytes, or 0 if the tag size could not be 288 * determined. 289 */ 290 int cipher_kt_tag_size(const cipher_kt_t *cipher_kt); 291 292 /** 293 * Returns true if we consider this cipher to be insecure. 294 */ 295 bool cipher_kt_insecure(const cipher_kt_t *cipher); 296 297 /** 298 * Returns the mode that the cipher runs in. 299 * 300 * @param cipher_kt Static cipher parameters. May not be NULL. 301 * 302 * @return Cipher mode, either \c OPENVPN_MODE_CBC, \c 303 * OPENVPN_MODE_OFB or \c OPENVPN_MODE_CFB 304 */ 305 int cipher_kt_mode(const cipher_kt_t *cipher_kt); 306 307 /** 308 * Check if the supplied cipher is a supported CBC mode cipher. 309 * 310 * @param cipher Static cipher parameters. 311 * 312 * @return true iff the cipher is a CBC mode cipher. 313 */ 314 bool cipher_kt_mode_cbc(const cipher_kt_t *cipher); 315 316 /** 317 * Check if the supplied cipher is a supported OFB or CFB mode cipher. 318 * 319 * @param cipher Static cipher parameters. 320 * 321 * @return true iff the cipher is a OFB or CFB mode cipher. 322 */ 323 bool cipher_kt_mode_ofb_cfb(const cipher_kt_t *cipher); 324 325 /** 326 * Check if the supplied cipher is a supported AEAD mode cipher. 327 * 328 * @param cipher Static cipher parameters. 329 * 330 * @return true iff the cipher is a AEAD mode cipher. 331 */ 332 bool cipher_kt_mode_aead(const cipher_kt_t *cipher); 333 334 335 /** 336 * 337 * Generic cipher functions 338 * 339 */ 340 341 /** 342 * Allocate a new cipher context 343 * 344 * @return a new cipher context 345 */ 346 cipher_ctx_t *cipher_ctx_new(void); 347 348 /** 349 * Cleanup and free a cipher context 350 * 351 * @param ctx Cipher context. 352 */ 353 void cipher_ctx_free(cipher_ctx_t *ctx); 354 355 /** 356 * Initialise a cipher context, based on the given key and key type. 357 * 358 * @param ctx Cipher context. May not be NULL 359 * @param key Buffer containing the key to use 360 * @param key_len Length of the key, in bytes 361 * @param kt Static cipher parameters to use 362 * @param enc Whether to encrypt or decrypt (either 363 * \c MBEDTLS_OP_ENCRYPT or \c MBEDTLS_OP_DECRYPT). 364 */ 365 void cipher_ctx_init(cipher_ctx_t *ctx, const uint8_t *key, int key_len, 366 const cipher_kt_t *kt, int enc); 367 368 /** 369 * Returns the size of the IV used by the cipher, in bytes, or 0 if no IV is 370 * used. 371 * 372 * @param ctx The cipher's context 373 * 374 * @return Size of the IV, in bytes, or \c 0 if the cipher does not 375 * use an IV or ctx was NULL. 376 */ 377 int cipher_ctx_iv_length(const cipher_ctx_t *ctx); 378 379 /** 380 * Gets the computed message authenticated code (MAC) tag for this cipher. 381 * 382 * @param ctx The cipher's context 383 * @param tag The buffer to write computed tag in. 384 * @param tag_size The tag buffer size, in bytes. 385 */ 386 int cipher_ctx_get_tag(cipher_ctx_t *ctx, uint8_t *tag, int tag_len); 387 388 /** 389 * Returns the block size of the cipher, in bytes. 390 * 391 * @param ctx The cipher's context 392 * 393 * @return Block size, in bytes, or 0 if ctx was NULL. 394 */ 395 int cipher_ctx_block_size(const cipher_ctx_t *ctx); 396 397 /** 398 * Returns the mode that the cipher runs in. 399 * 400 * @param ctx Cipher's context. May not be NULL. 401 * 402 * @return Cipher mode, either \c OPENVPN_MODE_CBC, \c 403 * OPENVPN_MODE_OFB or \c OPENVPN_MODE_CFB 404 */ 405 int cipher_ctx_mode(const cipher_ctx_t *ctx); 406 407 /** 408 * Returns the static cipher parameters for this context. 409 * 410 * @param ctx Cipher's context. 411 * 412 * @return Static cipher parameters for the supplied context, or 413 * NULL if unable to determine cipher parameters. 414 */ 415 const cipher_kt_t *cipher_ctx_get_cipher_kt(const cipher_ctx_t *ctx); 416 417 /** 418 * Resets the given cipher context, setting the IV to the specified value. 419 * Preserves the associated key information. 420 * 421 * @param ctx Cipher's context. May not be NULL. 422 * @param iv_buf The IV to use. 423 * 424 * @return \c 0 on failure, \c 1 on success. 425 */ 426 int cipher_ctx_reset(cipher_ctx_t *ctx, const uint8_t *iv_buf); 427 428 /** 429 * Updates the given cipher context, providing additional data (AD) for 430 * authenticated encryption with additional data (AEAD) cipher modes. 431 * 432 * @param ctx Cipher's context. May not be NULL. 433 * @param src Source buffer 434 * @param src_len Length of the source buffer, in bytes 435 * 436 * @return \c 0 on failure, \c 1 on success. 437 */ 438 int cipher_ctx_update_ad(cipher_ctx_t *ctx, const uint8_t *src, int src_len); 439 440 /** 441 * Updates the given cipher context, encrypting data in the source buffer, and 442 * placing any complete blocks in the destination buffer. 443 * 444 * Note that if a complete block cannot be written, data is cached in the 445 * context, and emitted at a later call to \c cipher_ctx_update, or by a call 446 * to \c cipher_ctx_final(). This implies that dst should have enough room for 447 * src_len + \c cipher_ctx_block_size(). 448 * 449 * @param ctx Cipher's context. May not be NULL. 450 * @param dst Destination buffer 451 * @param dst_len Length of the destination buffer, in bytes 452 * @param src Source buffer 453 * @param src_len Length of the source buffer, in bytes 454 * 455 * @return \c 0 on failure, \c 1 on success. 456 */ 457 int cipher_ctx_update(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len, 458 uint8_t *src, int src_len); 459 460 /** 461 * Pads the final cipher block using PKCS padding, and output to the destination 462 * buffer. 463 * 464 * @param ctx Cipher's context. May not be NULL. 465 * @param dst Destination buffer 466 * @param dst_len Length of the destination buffer, in bytes 467 * 468 * @return \c 0 on failure, \c 1 on success. 469 */ 470 int cipher_ctx_final(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len); 471 472 /** 473 * Like \c cipher_ctx_final, but check the computed authentication tag against 474 * the supplied (expected) tag. This function reports failure when the tags 475 * don't match. 476 * 477 * @param ctx Cipher's context. May not be NULL. 478 * @param dst Destination buffer. 479 * @param dst_len Length of the destination buffer, in bytes. 480 * @param tag The expected authentication tag. 481 * @param tag_len The length of tag, in bytes. 482 * 483 * @return \c 0 on failure, \c 1 on success. 484 */ 485 int cipher_ctx_final_check_tag(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len, 486 uint8_t *tag, size_t tag_len); 487 488 489 /* 490 * 491 * Generic message digest information functions 492 * 493 */ 494 495 /* 496 * Max size in bytes of any HMAC key that might conceivably be used. 497 * 498 * This value is checked at compile time in crypto.c to make sure 499 * it is always at least EVP_MAX_MD_SIZE. We define our own value 500 * for the same reason as above. 501 */ 502 #define MAX_HMAC_KEY_LENGTH 64 503 504 /** 505 * Return message digest parameters, based on the given digest name. The 506 * contents of these parameters are library-specific, and can be used to 507 * initialise HMAC or message digest operations. 508 * 509 * @param digest Name of the digest to retrieve parameters for (e.g. 510 * \c MD5). 511 * 512 * @return A statically allocated structure containing parameters 513 * for the given message digest. 514 */ 515 const md_kt_t *md_kt_get(const char *digest); 516 517 /** 518 * Retrieve a string describing the digest digest (e.g. \c SHA1). 519 * 520 * @param kt Static message digest parameters 521 * 522 * @return Statically allocated string describing the message 523 * digest. 524 */ 525 const char *md_kt_name(const md_kt_t *kt); 526 527 /** 528 * Returns the size of the message digest, in bytes. 529 * 530 * @param kt Static message digest parameters 531 * 532 * @return Message digest size, in bytes, or 0 if ctx was NULL. 533 */ 534 unsigned char md_kt_size(const md_kt_t *kt); 535 536 537 /* 538 * 539 * Generic message digest functions 540 * 541 */ 542 543 /* 544 * Calculates the message digest for the given buffer. 545 * 546 * @param kt Static message digest parameters 547 * @param src Buffer to digest. May not be NULL. 548 * @param src_len The length of the incoming buffer. 549 * @param dst Buffer to write the message digest to. May not be NULL. 550 * 551 * @return \c 1 on success, \c 0 on failure 552 */ 553 int md_full(const md_kt_t *kt, const uint8_t *src, int src_len, uint8_t *dst); 554 555 /* 556 * Allocate a new message digest context 557 * 558 * @return a new zeroed MD context 559 */ 560 md_ctx_t *md_ctx_new(void); 561 562 /* 563 * Free an existing, non-null message digest context 564 * 565 * @param ctx Message digest context 566 */ 567 void md_ctx_free(md_ctx_t *ctx); 568 569 /* 570 * Initialises the given message digest context. 571 * 572 * @param ctx Message digest context 573 * @param kt Static message digest parameters 574 */ 575 void md_ctx_init(md_ctx_t *ctx, const md_kt_t *kt); 576 577 /* 578 * Free the given message digest context. 579 * 580 * @param ctx Message digest context 581 */ 582 void md_ctx_cleanup(md_ctx_t *ctx); 583 584 /* 585 * Returns the size of the message digest output by the given context 586 * 587 * @param ctx Message digest context. 588 * 589 * @return Size of the message digest, or \0 if ctx is NULL. 590 */ 591 int md_ctx_size(const md_ctx_t *ctx); 592 593 /* 594 * Process the given data for use in the message digest. 595 * 596 * @param ctx Message digest context. May not be NULL. 597 * @param src Buffer to digest. May not be NULL. 598 * @param src_len The length of the incoming buffer. 599 */ 600 void md_ctx_update(md_ctx_t *ctx, const uint8_t *src, int src_len); 601 602 /* 603 * Output the message digest to the given buffer. 604 * 605 * @param ctx Message digest context. May not be NULL. 606 * @param dst Buffer to write the message digest to. May not be NULL. 607 */ 608 void md_ctx_final(md_ctx_t *ctx, uint8_t *dst); 609 610 611 /* 612 * 613 * Generic HMAC functions 614 * 615 */ 616 617 /* 618 * Create a new HMAC context 619 * 620 * @return A new HMAC context 621 */ 622 hmac_ctx_t *hmac_ctx_new(void); 623 624 /* 625 * Free an existing HMAC context 626 * 627 * @param ctx HMAC context to free 628 */ 629 void hmac_ctx_free(hmac_ctx_t *ctx); 630 631 /* 632 * Initialises the given HMAC context, using the given digest 633 * and key. 634 * 635 * @param ctx HMAC context to initialise 636 * @param key The key to use for the HMAC 637 * @param key_len The key length to use 638 * @param kt Static message digest parameters 639 * 640 */ 641 void hmac_ctx_init(hmac_ctx_t *ctx, const uint8_t *key, int key_length, 642 const md_kt_t *kt); 643 644 /* 645 * Free the given HMAC context. 646 * 647 * @param ctx HMAC context 648 */ 649 void hmac_ctx_cleanup(hmac_ctx_t *ctx); 650 651 /* 652 * Returns the size of the HMAC output by the given HMAC Context 653 * 654 * @param ctx HMAC context. 655 * 656 * @return Size of the HMAC, or \0 if ctx is NULL. 657 */ 658 int hmac_ctx_size(const hmac_ctx_t *ctx); 659 660 /* 661 * Resets the given HMAC context, preserving the associated key information 662 * 663 * @param ctx HMAC context. May not be NULL. 664 */ 665 void hmac_ctx_reset(hmac_ctx_t *ctx); 666 667 /* 668 * Process the given data for use in the HMAC. 669 * 670 * @param ctx HMAC context. May not be NULL. 671 * @param src The buffer to HMAC. May not be NULL. 672 * @param src_len The length of the incoming buffer. 673 */ 674 void hmac_ctx_update(hmac_ctx_t *ctx, const uint8_t *src, int src_len); 675 676 /* 677 * Output the HMAC to the given buffer. 678 * 679 * @param ctx HMAC context. May not be NULL. 680 * @param dst buffer to write the HMAC to. May not be NULL. 681 */ 682 void hmac_ctx_final(hmac_ctx_t *ctx, uint8_t *dst); 683 684 /** 685 * Translate an OpenVPN cipher name to a crypto library cipher name. 686 * 687 * @param cipher_name An OpenVPN cipher name 688 * 689 * @return The corresponding crypto library cipher name, or NULL 690 * if no matching cipher name was found. 691 */ 692 const char *translate_cipher_name_from_openvpn(const char *cipher_name); 693 694 /** 695 * Translate a crypto library cipher name to an OpenVPN cipher name. 696 * 697 * @param cipher_name A crypto library cipher name 698 * 699 * @return The corresponding OpenVPN cipher name, or NULL if no 700 * matching cipher name was found. 701 */ 702 const char *translate_cipher_name_to_openvpn(const char *cipher_name); 703 704 705 /** 706 * Calculates the TLS 1.0-1.1 PRF function. For the exact specification of the 707 * function definition see the TLS RFCs like RFC 4346. 708 * 709 * @param seed seed to use 710 * @param seed_len length of the seed 711 * @param secret secret to use 712 * @param secret_len length of the secret 713 * @param output output destination 714 * @param output_len length of output/number of bytes to generate 715 * 716 * @return true if successful, false on any error 717 */ 718 bool ssl_tls1_PRF(const uint8_t *seed, int seed_len, const uint8_t *secret, 719 int secret_len, uint8_t *output, int output_len); 720 721 #endif /* CRYPTO_BACKEND_H_ */ 722