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 Control Channel SSL library backend module 28 */ 29 30 31#ifndef SSL_BACKEND_H_ 32#define SSL_BACKEND_H_ 33 34#include "buffer.h" 35 36#ifdef ENABLE_CRYPTO_OPENSSL 37#include "ssl_openssl.h" 38#include "ssl_verify_openssl.h" 39#endif 40#ifdef ENABLE_CRYPTO_POLARSSL 41#include "ssl_polarssl.h" 42#include "ssl_verify_polarssl.h" 43#endif 44 45 46/** 47 * Get a tls_cipher_name_pair containing OpenSSL and IANA names for supplied TLS cipher name 48 * 49 * @param cipher_name Can be either OpenSSL or IANA cipher name 50 * @return tls_cipher_name_pair* if found, NULL otherwise 51 */ 52typedef struct { const char *openssl_name; const char *iana_name; } tls_cipher_name_pair; 53const tls_cipher_name_pair *tls_get_cipher_name_pair (const char *cipher_name, size_t len); 54 55/* 56 * 57 * Functions implemented in ssl.c for use by the backend SSL library 58 * 59 */ 60 61/** 62 * Callback to retrieve the user's password 63 * 64 * @param buf Buffer to return the password in 65 * @param size Size of the buffer 66 * @param rwflag Unused, needed for OpenSSL compatibility 67 * @param u Unused, needed for OpenSSL compatibility 68 */ 69int pem_password_callback (char *buf, int size, int rwflag, void *u); 70 71/* 72 * 73 * Functions used in ssl.c which must be implemented by the backend SSL library 74 * 75 */ 76 77/** 78 * Perform any static initialisation necessary by the library. 79 * Called on OpenVPN initialisation 80 */ 81void tls_init_lib(); 82 83/** 84 * Free any global SSL library-specific data structures. 85 */ 86void tls_free_lib(); 87/** 88 * Clear the underlying SSL library's error state. 89 */ 90void tls_clear_error(); 91 92/** 93 * Initialise a library-specific TLS context for a server. 94 * 95 * @param ctx TLS context to initialise 96 */ 97void tls_ctx_server_new(struct tls_root_ctx *ctx); 98 99/** 100 * Initialises a library-specific TLS context for a client. 101 * 102 * @param ctx TLS context to initialise 103 */ 104void tls_ctx_client_new(struct tls_root_ctx *ctx); 105 106/** 107 * Frees the library-specific TLSv1 context 108 * 109 * @param ctx TLS context to free 110 */ 111void tls_ctx_free(struct tls_root_ctx *ctx); 112 113/** 114 * Checks whether the given TLS context is initialised 115 * 116 * @param ctx TLS context to check 117 * 118 * @return true if the context is initialised, false if not. 119 */ 120bool tls_ctx_initialised(struct tls_root_ctx *ctx); 121 122/** 123 * Set any library specific options. 124 * 125 * Examples include disabling session caching, the password callback to use, 126 * and session verification parameters. 127 * 128 * @param ctx TLS context to set options on 129 * @param ssl_flags SSL flags to set 130 */ 131void tls_ctx_set_options (struct tls_root_ctx *ctx, unsigned int ssl_flags); 132 133/** 134 * Restrict the list of ciphers that can be used within the TLS context. 135 * 136 * @param ctx TLS context to restrict 137 * @param ciphers String containing : delimited cipher names. 138 */ 139void tls_ctx_restrict_ciphers(struct tls_root_ctx *ctx, const char *ciphers); 140 141/** 142 * Load Diffie Hellman Parameters, and load them into the library-specific 143 * TLS context. 144 * 145 * @param ctx TLS context to use 146 * @param dh_file The file name to load the parameters from, or 147 * "[[INLINE]]" in the case of inline files. 148 * @param dh_file_inline A string containing the parameters 149 */ 150void tls_ctx_load_dh_params(struct tls_root_ctx *ctx, const char *dh_file, 151 const char *dh_file_inline); 152 153/** 154 * Load PKCS #12 file for key, cert and (optionally) CA certs, and add to 155 * library-specific TLS context. 156 * 157 * @param ctx TLS context to use 158 * @param pkcs12_file The file name to load the information from, or 159 * "[[INLINE]]" in the case of inline files. 160 * @param pkcs12_file_inline A string containing the information 161 * 162 * @return 1 if an error occurred, 0 if parsing was 163 * successful. 164 */ 165int tls_ctx_load_pkcs12(struct tls_root_ctx *ctx, const char *pkcs12_file, 166 const char *pkcs12_file_inline, bool load_ca_file 167 ); 168 169/** 170 * Use Windows cryptoapi for key and cert, and add to library-specific TLS 171 * context. 172 * 173 * @param ctx TLS context to use 174 * @param crypto_api_cert String representing the certificate to load. 175 */ 176#ifdef ENABLE_CRYPTOAPI 177void tls_ctx_load_cryptoapi(struct tls_root_ctx *ctx, const char *cryptoapi_cert); 178#endif /* WIN32 */ 179 180/** 181 * Load certificate file into the given TLS context. If the given certificate 182 * file contains a certificate chain, load the whole chain. 183 * 184 * If the x509 parameter is not NULL, the certificate will be returned in it. 185 * 186 * @param ctx TLS context to use 187 * @param cert_file The file name to load the certificate from, or 188 * "[[INLINE]]" in the case of inline files. 189 * @param cert_file_inline A string containing the certificate 190 * @param x509 An optional certificate, if x509 is NULL, 191 * do nothing, if x509 is not NULL, *x509 will be 192 * allocated and filled with the loaded certificate. 193 * *x509 must be NULL. 194 */ 195void tls_ctx_load_cert_file (struct tls_root_ctx *ctx, const char *cert_file, 196 const char *cert_file_inline, openvpn_x509_cert_t **x509 197 ); 198 199/** 200 * Free the given certificate 201 * 202 * @param x509 certificate to free 203 */ 204void tls_ctx_free_cert_file (openvpn_x509_cert_t *x509); 205 206/** 207 * Load private key file into the given TLS context. 208 * 209 * @param ctx TLS context to use 210 * @param priv_key_file The file name to load the private key from, or 211 * "[[INLINE]]" in the case of inline files. 212 * @param priv_key_file_inline A string containing the private key 213 * 214 * @return 1 if an error occurred, 0 if parsing was 215 * successful. 216 */ 217int tls_ctx_load_priv_file (struct tls_root_ctx *ctx, const char *priv_key_file, 218 const char *priv_key_file_inline 219 ); 220 221#ifdef MANAGMENT_EXTERNAL_KEY 222 223/** 224 * Tell the management interface to load the external private key matching 225 * the given certificate. 226 * 227 * @param ctx TLS context to use 228 * @param cert The certificate file to load the private key for 229 * "[[INLINE]]" in the case of inline files. 230 * 231 * @return 1 if an error occurred, 0 if parsing was 232 * successful. 233 */ 234int tls_ctx_use_external_private_key (struct tls_root_ctx *ctx, openvpn_x509_cert_t *cert); 235#endif 236 237 238/** 239 * Load certificate authority certificates from the given file or path. 240 * 241 * Note that not all SSL libraries support loading from a path. 242 * 243 * @param ctx TLS context to use 244 * @param ca_file The file name to load the CAs from, or 245 * "[[INLINE]]" in the case of inline files. 246 * @param ca_file_inline A string containing the CAs 247 * @param ca_path The path to load the CAs from 248 */ 249void tls_ctx_load_ca (struct tls_root_ctx *ctx, const char *ca_file, 250 const char *ca_file_inline, const char *ca_path, bool tls_server 251 ); 252 253/** 254 * Load extra certificate authority certificates from the given file or path. 255 * These Load extra certificates that are part of our own certificate 256 * chain but shouldn't be included in the verify chain. 257 * 258 * 259 * @param ctx TLS context to use 260 * @param extra_certs_file The file name to load the certs from, or 261 * "[[INLINE]]" in the case of inline files. 262 * @param extra_certs_file_inline A string containing the certs 263 */ 264void tls_ctx_load_extra_certs (struct tls_root_ctx *ctx, const char *extra_certs_file, 265 const char *extra_certs_file_inline 266 ); 267 268#ifdef ENABLE_CRYPTO_POLARSSL 269/** 270 * Add a personalisation string to the PolarSSL RNG, based on the certificate 271 * loaded into the given context. 272 * 273 * @param ctx TLS context to use 274 */ 275void tls_ctx_personalise_random(struct tls_root_ctx *ctx); 276#endif 277 278/* ************************************** 279 * 280 * Key-state specific functions 281 * 282 ***************************************/ 283 284/** 285 * Initialise the SSL channel part of the given key state. Settings will be 286 * loaded from a previously initialised TLS context. 287 * 288 * @param ks_ssl The SSL channel's state info to initialise 289 * @param ssl_ctx The TLS context to use when initialising the channel. 290 * @param is_server Initialise a server? 291 * @param session The session associated with the given key_state 292 */ 293void key_state_ssl_init(struct key_state_ssl *ks_ssl, 294 const struct tls_root_ctx *ssl_ctx, bool is_server, void *session); 295 296/** 297 * Free the SSL channel part of the given key state. 298 * 299 * @param ks_ssl The SSL channel's state info to free 300 */ 301void key_state_ssl_free(struct key_state_ssl *ks_ssl); 302 303/**************************************************************************/ 304/** @addtogroup control_tls 305 * @{ */ 306 307/** @name Functions for packets to be sent to a remote OpenVPN peer 308 * @{ */ 309 310/** 311 * Insert a plaintext buffer into the TLS module. 312 * 313 * After successfully processing the data, the data in \a buf is zeroized, 314 * its length set to zero, and a value of \c 1 is returned. 315 * 316 * @param ks_ssl - The security parameter state for this %key 317 * session. 318 * @param buf - The plaintext message to process. 319 * 320 * @return The return value indicates whether the data was successfully 321 * processed: 322 * - \c 1: All the data was processed successfully. 323 * - \c 0: The data was not processed, this function should be called 324 * again later to retry. 325 * - \c -1: An error occurred. 326 */ 327int key_state_write_plaintext (struct key_state_ssl *ks_ssl, struct buffer *buf); 328 329/** 330 * Insert plaintext data into the TLS module. 331 * 332 * @param ks_ssl - The security parameter state for this %key 333 * session. 334 * @param data - A pointer to the data to process. 335 * @param len - The length in bytes of the data to process. 336 * 337 * @return The return value indicates whether the data was successfully 338 * processed: 339 * - \c 1: All the data was processed successfully. 340 * - \c 0: The data was not processed, this function should be called 341 * again later to retry. 342 * - \c -1: An error occurred. 343 */ 344int key_state_write_plaintext_const (struct key_state_ssl *ks_ssl, 345 const uint8_t *data, int len); 346 347/** 348 * Extract ciphertext data from the TLS module. 349 * 350 * If the \a buf buffer has a length other than zero, this function does 351 * not perform any action and returns 0. 352 * 353 * @param ks_ssl - The security parameter state for this %key 354 * session. 355 * @param buf - A buffer in which to store the ciphertext. 356 * @param maxlen - The maximum number of bytes to extract. 357 * 358 * @return The return value indicates whether the data was successfully 359 * processed: 360 * - \c 1: Data was extracted successfully. 361 * - \c 0: No data was extracted, this function should be called again 362 * later to retry. 363 * - \c -1: An error occurred. 364 */ 365int key_state_read_ciphertext (struct key_state_ssl *ks_ssl, struct buffer *buf, 366 int maxlen); 367 368/** @} name Functions for packets to be sent to a remote OpenVPN peer */ 369 370 371/** @name Functions for packets received from a remote OpenVPN peer 372 * @{ */ 373 374/** 375 * Insert a ciphertext buffer into the TLS module. 376 * 377 * After successfully processing the data, the data in \a buf is zeroized, 378 * its length set to zero, and a value of \c 1 is returned. 379 * 380 * @param ks_ssl - The security parameter state for this %key 381 * session. 382 * @param buf - The ciphertext message to process. 383 * 384 * @return The return value indicates whether the data was successfully 385 * processed: 386 * - \c 1: All the data was processed successfully. 387 * - \c 0: The data was not processed, this function should be called 388 * again later to retry. 389 * - \c -1: An error occurred. 390 */ 391int key_state_write_ciphertext (struct key_state_ssl *ks_ssl, 392 struct buffer *buf); 393 394/** 395 * Extract plaintext data from the TLS module. 396 * 397 * If the \a buf buffer has a length other than zero, this function does 398 * not perform any action and returns 0. 399 * 400 * @param ks_ssl - The security parameter state for this %key 401 * session. 402 * @param buf - A buffer in which to store the plaintext. 403 * @param maxlen - The maximum number of bytes to extract. 404 * 405 * @return The return value indicates whether the data was successfully 406 * processed: 407 * - \c 1: Data was extracted successfully. 408 * - \c 0: No data was extracted, this function should be called again 409 * later to retry. 410 * - \c -1: An error occurred. 411 */ 412int key_state_read_plaintext (struct key_state_ssl *ks_ssl, struct buffer *buf, 413 int maxlen); 414 415/** @} name Functions for packets received from a remote OpenVPN peer */ 416 417/** @} addtogroup control_tls */ 418 419/* ************************************** 420 * 421 * Information functions 422 * 423 * Print information for the end user. 424 * 425 ***************************************/ 426 427/* 428 * Print a one line summary of SSL/TLS session handshake. 429 */ 430void print_details (struct key_state_ssl * ks_ssl, const char *prefix); 431 432/* 433 * Show the TLS ciphers that are available for us to use in the OpenSSL 434 * library. 435 */ 436void show_available_tls_ciphers (); 437 438/* 439 * The OpenSSL library has a notion of preference in TLS ciphers. Higher 440 * preference == more secure. Return the highest preference cipher. 441 */ 442void get_highest_preference_tls_cipher (char *buf, int size); 443 444#endif /* SSL_BACKEND_H_ */ 445