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 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 SSL library-specific backend interface 28 */ 29 30#ifndef CRYPTO_BACKEND_H_ 31#define CRYPTO_BACKEND_H_ 32 33#ifdef ENABLE_CRYPTO_OPENSSL 34#include "crypto_openssl.h" 35#endif 36#ifdef ENABLE_CRYPTO_POLARSSL 37#include "crypto_polarssl.h" 38#endif 39#include "basic.h" 40 41 42/* 43 * This routine should have additional OpenSSL crypto library initialisations 44 * used by both crypto and ssl components of OpenVPN. 45 */ 46void crypto_init_lib (void); 47 48void crypto_uninit_lib (void); 49 50void crypto_clear_error (void); 51 52/* 53 * Initialise the given named crypto engine. 54 */ 55void crypto_init_lib_engine (const char *engine_name); 56 57#ifdef DMALLOC 58/* 59 * OpenSSL memory debugging. If dmalloc debugging is enabled, tell 60 * OpenSSL to use our private malloc/realloc/free functions so that 61 * we can dispatch them to dmalloc. 62 */ 63void crypto_init_dmalloc (void); 64#endif /* DMALLOC */ 65 66/** 67 * Translate a data channel cipher name from the OpenVPN config file 68 * 'language' to the crypto library specific name. 69 */ 70const char * translate_cipher_name_from_openvpn (const char *cipher_name); 71 72/** 73 * Translate a data channel cipher name from the crypto library specific name 74 * to the OpenVPN config file 'language'. 75 */ 76const char * translate_cipher_name_from_openvpn (const char *cipher_name); 77 78void show_available_ciphers (void); 79 80void show_available_digests (void); 81 82void show_available_engines (void); 83 84/* 85 * 86 * Random number functions, used in cases where we want 87 * reasonably strong cryptographic random number generation 88 * without depleting our entropy pool. Used for random 89 * IV values and a number of other miscellaneous tasks. 90 * 91 */ 92 93/** 94 * Wrapper for secure random number generator. Retrieves len bytes of random 95 * data, and places it in output. 96 * 97 * @param output Output buffer 98 * @param len Length of the output buffer, in bytes 99 * 100 * @return \c 1 on success, \c 0 on failure 101 */ 102int rand_bytes (uint8_t *output, int len); 103 104/* 105 * 106 * Key functions, allow manipulation of keys. 107 * 108 */ 109 110 111/** 112 * Return number of DES cblocks (1 cblock = length of a single-DES key) for the 113 * current key type or 0 if not a DES cipher. 114 * 115 * @param kt Type of key 116 * 117 * @return Number of DES cblocks that the key consists of, or 0. 118 */ 119int key_des_num_cblocks (const cipher_kt_t *kt); 120 121/* 122 * Check the given DES key. Checks the given key's length, weakness and parity. 123 * 124 * @param key Key to check 125 * @param key_len Length of the key, in bytes 126 * @param ndc Number of DES cblocks that the key is made up of. 127 * 128 * @return \c true if the key is valid, \c false otherwise. 129 */ 130bool key_des_check (uint8_t *key, int key_len, int ndc); 131 132/* 133 * Fix the given DES key, setting its parity to odd. 134 * 135 * @param key Key to check 136 * @param key_len Length of the key, in bytes 137 * @param ndc Number of DES cblocks that the key is made up of. 138 */ 139void key_des_fixup (uint8_t *key, int key_len, int ndc); 140 141/** 142 * Encrypt the given block, using DES ECB mode 143 * 144 * @param key DES key to use. 145 * @param src Buffer containing the 8-byte source. 146 * @param dst Buffer containing the 8-byte destination 147 */ 148void cipher_des_encrypt_ecb (const unsigned char key[DES_KEY_LENGTH], 149 unsigned char src[DES_KEY_LENGTH], 150 unsigned char dst[DES_KEY_LENGTH]); 151 152/* 153 * 154 * Generic cipher key type functions 155 * 156 */ 157/* 158 * Max size in bytes of any cipher key that might conceivably be used. 159 * 160 * This value is checked at compile time in crypto.c to make sure 161 * it is always at least EVP_MAX_KEY_LENGTH. 162 * 163 * We define our own value, since this parameter 164 * is used to control the size of static key files. 165 * If the OpenSSL library increases EVP_MAX_KEY_LENGTH, 166 * we don't want our key files to be suddenly rendered 167 * unusable. 168 */ 169#define MAX_CIPHER_KEY_LENGTH 64 170 171/** 172 * Return cipher parameters, based on the given cipher name. The 173 * contents of these parameters are library-specific, and can be used to 174 * initialise encryption/decryption. 175 * 176 * @param ciphername Name of the cipher to retrieve parameters for (e.g. 177 * \c AES-128-CBC). 178 * 179 * @return A statically allocated structure containing parameters 180 * for the given cipher. 181 */ 182const cipher_kt_t * cipher_kt_get (const char *ciphername); 183 184/** 185 * Retrieve a string describing the cipher (e.g. \c AES-128-CBC). 186 * 187 * @param cipher_kt Static cipher parameters 188 * 189 * @return a statically allocated string describing the cipher. 190 */ 191const char * cipher_kt_name (const cipher_kt_t *cipher_kt); 192 193/** 194 * Returns the size of keys used by the cipher, in bytes. If the cipher has a 195 * variable key size, return the default key size. 196 * 197 * @param cipher_kt Static cipher parameters 198 * 199 * @return (Default) size of keys used by the cipher, in bytes. 200 */ 201int cipher_kt_key_size (const cipher_kt_t *cipher_kt); 202 203/** 204 * Returns the size of the IV used by the cipher, in bytes, or 0 if no IV is 205 * used. 206 * 207 * @param cipher_kt Static cipher parameters 208 * 209 * @return Size of the IV, in bytes, or 0 if the cipher does not 210 * use an IV. 211 */ 212int cipher_kt_iv_size (const cipher_kt_t *cipher_kt); 213 214/** 215 * Returns the block size of the cipher, in bytes. 216 * 217 * @param cipher_kt Static cipher parameters 218 * 219 * @return Block size, in bytes. 220 */ 221int cipher_kt_block_size (const cipher_kt_t *cipher_kt); 222 223/** 224 * Returns the mode that the cipher runs in. 225 * 226 * @param cipher_kt Static cipher parameters 227 * 228 * @return Cipher mode, either \c OPENVPN_MODE_CBC, \c 229 * OPENVPN_MODE_OFB or \c OPENVPN_MODE_CFB 230 */ 231int cipher_kt_mode (const cipher_kt_t *cipher_kt); 232 233 234/** 235 * 236 * Generic cipher functions 237 * 238 */ 239 240/** 241 * Initialise a cipher context, based on the given key and key type. 242 * 243 * @param ctx Cipher context. May not be NULL 244 * @param key Buffer containing the key to use 245 * @param key_len Length of the key, in bytes 246 * @param kt Static cipher parameters to use 247 * @param enc Whether to encrypt or decrypt (either 248 * \c POLARSSL_OP_ENCRYPT or \c POLARSSL_OP_DECRYPT). 249 */ 250void cipher_ctx_init (cipher_ctx_t *ctx, uint8_t *key, int key_len, 251 const cipher_kt_t *kt, int enc); 252 253/** 254 * Cleanup the specified context. 255 * 256 * @param ctx Cipher context to cleanup. 257 */ 258void cipher_ctx_cleanup (cipher_ctx_t *ctx); 259 260/** 261 * Returns the size of the IV used by the cipher, in bytes, or 0 if no IV is 262 * used. 263 * 264 * @param ctx The cipher's context 265 * 266 * @return Size of the IV, in bytes, or \c 0 if the cipher does not 267 * use an IV or ctx was NULL. 268 */ 269int cipher_ctx_iv_length (const cipher_ctx_t *ctx); 270 271/** 272 * Returns the block size of the cipher, in bytes. 273 * 274 * @param ctx The cipher's context 275 * 276 * @return Block size, in bytes, or 0 if ctx was NULL. 277 */ 278int cipher_ctx_block_size (const cipher_ctx_t *ctx); 279 280/** 281 * Returns the mode that the cipher runs in. 282 * 283 * @param ctx Cipher's context. May not be NULL. 284 * 285 * @return Cipher mode, either \c OPENVPN_MODE_CBC, \c 286 * OPENVPN_MODE_OFB or \c OPENVPN_MODE_CFB 287 */ 288int cipher_ctx_mode (const cipher_ctx_t *ctx); 289 290/** 291 * Resets the given cipher context, setting the IV to the specified value. 292 * Preserves the associated key information. 293 * 294 * @param ctx Cipher's context. May not be NULL. 295 * @param iv_buf The IV to use. 296 * 297 * @return \c 0 on failure, \c 1 on success. 298 */ 299int cipher_ctx_reset (cipher_ctx_t *ctx, uint8_t *iv_buf); 300 301/** 302 * Updates the given cipher context, encrypting data in the source buffer, and 303 * placing any complete blocks in the destination buffer. 304 * 305 * Note that if a complete block cannot be written, data is cached in the 306 * context, and emitted at a later call to \c cipher_ctx_update, or by a call 307 * to \c cipher_ctx_final(). This implies that dst should have enough room for 308 * src_len + \c cipher_ctx_block_size() - 1. 309 * 310 * @param ctx Cipher's context. May not be NULL. 311 * @param dst Destination buffer 312 * @param dst_len Length of the destination buffer, in bytes 313 * @param src Source buffer 314 * @param src_len Length of the source buffer, in bytes 315 * 316 * @return \c 0 on failure, \c 1 on success. 317 */ 318int cipher_ctx_update (cipher_ctx_t *ctx, uint8_t *dst, int *dst_len, 319 uint8_t *src, int src_len); 320 321/** 322 * Pads the final cipher block using PKCS padding, and output to the destination 323 * buffer. 324 * 325 * @param ctx Cipher's context. May not be NULL. 326 * @param dst Destination buffer 327 * @param dst_len Length of the destination buffer, in bytes 328 * 329 * @return \c 0 on failure, \c 1 on success. 330 */ 331int cipher_ctx_final (cipher_ctx_t *ctx, uint8_t *dst, int *dst_len); 332 333/* 334 * 335 * Generic message digest information functions 336 * 337 */ 338 339/* 340 * Max size in bytes of any HMAC key that might conceivably be used. 341 * 342 * This value is checked at compile time in crypto.c to make sure 343 * it is always at least EVP_MAX_MD_SIZE. We define our own value 344 * for the same reason as above. 345 */ 346#define MAX_HMAC_KEY_LENGTH 64 347 348/** 349 * Return message digest parameters, based on the given digest name. The 350 * contents of these parameters are library-specific, and can be used to 351 * initialise HMAC or message digest operations. 352 * 353 * @param digest Name of the digest to retrieve parameters for (e.g. 354 * \c MD5). 355 * 356 * @return A statically allocated structure containing parameters 357 * for the given message digest. 358 */ 359const md_kt_t * md_kt_get (const char *digest); 360 361/** 362 * Retrieve a string describing the digest digest (e.g. \c SHA1). 363 * 364 * @param kt Static message digest parameters 365 * 366 * @return Statically allocated string describing the message 367 * digest. 368 */ 369const char * md_kt_name (const md_kt_t *kt); 370 371/** 372 * Returns the size of the message digest, in bytes. 373 * 374 * @param kt Static message digest parameters 375 * 376 * @return Message digest size, in bytes, or 0 if ctx was NULL. 377 */ 378int md_kt_size (const md_kt_t *kt); 379 380 381/* 382 * 383 * Generic message digest functions 384 * 385 */ 386 387/* 388 * Calculates the message digest for the given buffer. 389 * 390 * @param kt Static message digest parameters 391 * @param src Buffer to digest. May not be NULL. 392 * @param src_len The length of the incoming buffer. 393 * @param dst Buffer to write the message digest to. May not be NULL. 394 * 395 * @return \c 1 on success, \c 0 on failure 396 */ 397int md_full (const md_kt_t *kt, const uint8_t *src, int src_len, uint8_t *dst); 398 399/* 400 * Initialises the given message digest context. 401 * 402 * @param ctx Message digest context 403 * @param kt Static message digest parameters 404 */ 405void md_ctx_init (md_ctx_t *ctx, const md_kt_t *kt); 406 407/* 408 * Free the given message digest context. 409 * 410 * @param ctx Message digest context 411 */ 412void md_ctx_cleanup(md_ctx_t *ctx); 413 414/* 415 * Returns the size of the message digest output by the given context 416 * 417 * @param ctx Message digest context. 418 * 419 * @return Size of the message digest, or \0 if ctx is NULL. 420 */ 421int md_ctx_size (const md_ctx_t *ctx); 422 423/* 424 * Process the given data for use in the message digest. 425 * 426 * @param ctx Message digest context. May not be NULL. 427 * @param src Buffer to digest. May not be NULL. 428 * @param src_len The length of the incoming buffer. 429 */ 430void md_ctx_update (md_ctx_t *ctx, const uint8_t *src, int src_len); 431 432/* 433 * Output the message digest to the given buffer. 434 * 435 * @param ctx Message digest context. May not be NULL. 436 * @param dst Buffer to write the message digest to. May not be NULL. 437 */ 438void md_ctx_final (md_ctx_t *ctx, uint8_t *dst); 439 440 441/* 442 * 443 * Generic HMAC functions 444 * 445 */ 446 447/* 448 * Initialises the given HMAC context, using the given digest 449 * and key. 450 * 451 * @param ctx HMAC context to intialise 452 * @param key The key to use for the HMAC 453 * @param key_len The key length to use 454 * @param kt Static message digest parameters 455 * 456 */ 457void hmac_ctx_init (hmac_ctx_t *ctx, const uint8_t *key, int key_length, 458 const md_kt_t *kt); 459 460/* 461 * Free the given HMAC context. 462 * 463 * @param ctx HMAC context 464 */ 465void hmac_ctx_cleanup(hmac_ctx_t *ctx); 466 467/* 468 * Returns the size of the HMAC output by the given HMAC Context 469 * 470 * @param ctx HMAC context. 471 * 472 * @return Size of the HMAC, or \0 if ctx is NULL. 473 */ 474int hmac_ctx_size (const hmac_ctx_t *ctx); 475 476/* 477 * Resets the given HMAC context, preserving the associated key information 478 * 479 * @param ctx HMAC context. May not be NULL. 480 */ 481void hmac_ctx_reset (hmac_ctx_t *ctx); 482 483/* 484 * Process the given data for use in the HMAC. 485 * 486 * @param ctx HMAC context. May not be NULL. 487 * @param src The buffer to HMAC. May not be NULL. 488 * @param src_len The length of the incoming buffer. 489 */ 490void hmac_ctx_update (hmac_ctx_t *ctx, const uint8_t *src, int src_len); 491 492/* 493 * Output the HMAC to the given buffer. 494 * 495 * @param ctx HMAC context. May not be NULL. 496 * @param dst buffer to write the HMAC to. May not be NULL. 497 */ 498void hmac_ctx_final (hmac_ctx_t *ctx, uint8_t *dst); 499 500#endif /* CRYPTO_BACKEND_H_ */ 501