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
8
* Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net>
9
* Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
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.
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.
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
27
* @file Control Channel SSL library backend module
31
#ifndef SSL_BACKEND_H_
32
#define SSL_BACKEND_H_
36
#ifdef ENABLE_CRYPTO_OPENSSL
37
#include "ssl_openssl.h"
38
#include "ssl_verify_openssl.h"
40
#ifdef ENABLE_CRYPTO_POLARSSL
41
#include "ssl_polarssl.h"
42
#include "ssl_verify_polarssl.h"
47
* Get a tls_cipher_name_pair containing OpenSSL and IANA names for supplied TLS cipher name
49
* @param cipher_name Can be either OpenSSL or IANA cipher name
50
* @return tls_cipher_name_pair* if found, NULL otherwise
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);
57
* Functions implemented in ssl.c for use by the backend SSL library
62
* Callback to retrieve the user's password
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
69
int pem_password_callback (char *buf, int size, int rwflag, void *u);
73
* Functions used in ssl.c which must be implemented by the backend SSL library
78
* Perform any static initialisation necessary by the library.
79
* Called on OpenVPN initialisation
84
* Free any global SSL library-specific data structures.
88
* Clear the underlying SSL library's error state.
90
void tls_clear_error();
93
* Initialise a library-specific TLS context for a server.
95
* @param ctx TLS context to initialise
97
void tls_ctx_server_new(struct tls_root_ctx *ctx);
100
* Initialises a library-specific TLS context for a client.
102
* @param ctx TLS context to initialise
104
void tls_ctx_client_new(struct tls_root_ctx *ctx);
107
* Frees the library-specific TLSv1 context
109
* @param ctx TLS context to free
111
void tls_ctx_free(struct tls_root_ctx *ctx);
114
* Checks whether the given TLS context is initialised
116
* @param ctx TLS context to check
118
* @return true if the context is initialised, false if not.
120
bool tls_ctx_initialised(struct tls_root_ctx *ctx);
123
* Set any library specific options.
125
* Examples include disabling session caching, the password callback to use,
126
* and session verification parameters.
128
* @param ctx TLS context to set options on
129
* @param ssl_flags SSL flags to set
131
void tls_ctx_set_options (struct tls_root_ctx *ctx, unsigned int ssl_flags);
134
* Restrict the list of ciphers that can be used within the TLS context.
136
* @param ctx TLS context to restrict
137
* @param ciphers String containing : delimited cipher names.
139
void tls_ctx_restrict_ciphers(struct tls_root_ctx *ctx, const char *ciphers);
142
* Load Diffie Hellman Parameters, and load them into the library-specific
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
150
void tls_ctx_load_dh_params(struct tls_root_ctx *ctx, const char *dh_file,
151
const char *dh_file_inline);
154
* Load PKCS #12 file for key, cert and (optionally) CA certs, and add to
155
* library-specific TLS context.
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
162
* @return 1 if an error occurred, 0 if parsing was
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
170
* Use Windows cryptoapi for key and cert, and add to library-specific TLS
173
* @param ctx TLS context to use
174
* @param crypto_api_cert String representing the certificate to load.
176
#ifdef ENABLE_CRYPTOAPI
177
void tls_ctx_load_cryptoapi(struct tls_root_ctx *ctx, const char *cryptoapi_cert);
181
* Load certificate file into the given TLS context. If the given certificate
182
* file contains a certificate chain, load the whole chain.
184
* If the x509 parameter is not NULL, the certificate will be returned in it.
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.
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
200
* Free the given certificate
202
* @param x509 certificate to free
204
void tls_ctx_free_cert_file (openvpn_x509_cert_t *x509);
207
* Load private key file into the given TLS context.
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
214
* @return 1 if an error occurred, 0 if parsing was
217
int tls_ctx_load_priv_file (struct tls_root_ctx *ctx, const char *priv_key_file,
218
const char *priv_key_file_inline
221
#ifdef MANAGMENT_EXTERNAL_KEY
224
* Tell the management interface to load the external private key matching
225
* the given certificate.
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.
231
* @return 1 if an error occurred, 0 if parsing was
234
int tls_ctx_use_external_private_key (struct tls_root_ctx *ctx, openvpn_x509_cert_t *cert);
239
* Load certificate authority certificates from the given file or path.
241
* Note that not all SSL libraries support loading from a path.
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
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
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.
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
264
void tls_ctx_load_extra_certs (struct tls_root_ctx *ctx, const char *extra_certs_file,
265
const char *extra_certs_file_inline
268
#ifdef ENABLE_CRYPTO_POLARSSL
270
* Add a personalisation string to the PolarSSL RNG, based on the certificate
271
* loaded into the given context.
273
* @param ctx TLS context to use
275
void tls_ctx_personalise_random(struct tls_root_ctx *ctx);
278
/* **************************************
280
* Key-state specific functions
282
***************************************/
285
* Initialise the SSL channel part of the given key state. Settings will be
286
* loaded from a previously initialised TLS context.
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
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);
297
* Free the SSL channel part of the given key state.
299
* @param ks_ssl The SSL channel's state info to free
301
void key_state_ssl_free(struct key_state_ssl *ks_ssl);
303
/**************************************************************************/
304
/** @addtogroup control_tls
307
/** @name Functions for packets to be sent to a remote OpenVPN peer
311
* Insert a plaintext buffer into the TLS module.
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.
316
* @param ks_ssl - The security parameter state for this %key
318
* @param buf - The plaintext message to process.
320
* @return The return value indicates whether the data was successfully
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.
327
int key_state_write_plaintext (struct key_state_ssl *ks_ssl, struct buffer *buf);
330
* Insert plaintext data into the TLS module.
332
* @param ks_ssl - The security parameter state for this %key
334
* @param data - A pointer to the data to process.
335
* @param len - The length in bytes of the data to process.
337
* @return The return value indicates whether the data was successfully
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.
344
int key_state_write_plaintext_const (struct key_state_ssl *ks_ssl,
345
const uint8_t *data, int len);
348
* Extract ciphertext data from the TLS module.
350
* If the \a buf buffer has a length other than zero, this function does
351
* not perform any action and returns 0.
353
* @param ks_ssl - The security parameter state for this %key
355
* @param buf - A buffer in which to store the ciphertext.
356
* @param maxlen - The maximum number of bytes to extract.
358
* @return The return value indicates whether the data was successfully
360
* - \c 1: Data was extracted successfully.
361
* - \c 0: No data was extracted, this function should be called again
363
* - \c -1: An error occurred.
365
int key_state_read_ciphertext (struct key_state_ssl *ks_ssl, struct buffer *buf,
368
/** @} name Functions for packets to be sent to a remote OpenVPN peer */
371
/** @name Functions for packets received from a remote OpenVPN peer
375
* Insert a ciphertext buffer into the TLS module.
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.
380
* @param ks_ssl - The security parameter state for this %key
382
* @param buf - The ciphertext message to process.
384
* @return The return value indicates whether the data was successfully
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.
391
int key_state_write_ciphertext (struct key_state_ssl *ks_ssl,
395
* Extract plaintext data from the TLS module.
397
* If the \a buf buffer has a length other than zero, this function does
398
* not perform any action and returns 0.
400
* @param ks_ssl - The security parameter state for this %key
402
* @param buf - A buffer in which to store the plaintext.
403
* @param maxlen - The maximum number of bytes to extract.
405
* @return The return value indicates whether the data was successfully
407
* - \c 1: Data was extracted successfully.
408
* - \c 0: No data was extracted, this function should be called again
410
* - \c -1: An error occurred.
412
int key_state_read_plaintext (struct key_state_ssl *ks_ssl, struct buffer *buf,
415
/** @} name Functions for packets received from a remote OpenVPN peer */
417
/** @} addtogroup control_tls */
419
/* **************************************
421
* Information functions
423
* Print information for the end user.
425
***************************************/
428
* Print a one line summary of SSL/TLS session handshake.
430
void print_details (struct key_state_ssl * ks_ssl, const char *prefix);
433
* Show the TLS ciphers that are available for us to use in the OpenSSL
436
void show_available_tls_ciphers ();
439
* The OpenSSL library has a notion of preference in TLS ciphers. Higher
440
* preference == more secure. Return the highest preference cipher.
442
void get_highest_preference_tls_cipher (char *buf, int size);
444
#endif /* SSL_BACKEND_H_ */
added
removed
src/openvpn/ssl_backend.h
