release/src/router/openvpn/src/openvpn/ssl_backend.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 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  */
  52 typedef struct { const char *openssl_name; const char *iana_name; } tls_cipher_name_pair;
  53 const 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  */
  69 int 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  */
  81 void tls_init_lib();
  82
  83 /**
  84  * Free any global SSL library-specific data structures.
  85  */
  86 void tls_free_lib();
  87 /**
  88  * Clear the underlying SSL library's error state.
  89  */
  90 void tls_clear_error();
  91
  92 /**
  93  * Initialise a library-specific TLS context for a server.
  94  *
  95  * @param ctx           TLS context to initialise
  96  */
  97 void 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  */
 104 void 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  */
 111 void 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  */
 120 bool 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  */
 131 void 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  */
 139 void 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  */
 150 void 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  */
 165 int 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
 177 void 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  */
 195 void 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  */
 204 void 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  */
 217 int 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  */
 234 int 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  */
 249 void 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  */
 264 void 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  */
 275 void 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  */
 293 void 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  */
 301 void 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  */
 327 int 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  */
 344 int 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  */
 365 int 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  */
 391 int 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  */
 412 int 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  */
 430 void 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  */
 436 void 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  */
 442 void get_highest_preference_tls_cipher (char *buf, int size);
 443
 444 #endif /* SSL_BACKEND_H_ */