src/include/tls.h

   1 #ifndef FR_TLS_H
   2 #define FR_TLS_H
   3
   4 #ifdef WITH_TLS
   5
   6 /*
   7  * @file tls.h
   8  * @brief Structures and prototypes for TLS wrappers
   9  * Version:     $Id$
  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 as published by
  13  *   the Free Software Foundation; either version 2 of the License, or
  14  *   (at your option) any later version.
  15  *
  16  *   This program is distributed in the hope that it will be useful,
  17  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  *   GNU General Public License for more details.
  20  *
  21  *   You should have received a copy of the GNU General Public License
  22  *   along with this program; if not, write to the Free Software
  23  *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  24  *
  25  * Copyright 2010 Network RADIUS SARL <info@networkradius.com>
  26  */
  27
  28 #include <freeradius-devel/ident.h>
  29 RCSIDH(tls_h, "$Id$")
  30
  31 #include <freeradius-devel/autoconf.h>
  32 #include <freeradius-devel/conffile.h>
  33
  34 /*
  35  *      For RH 9, which apparently needs this.
  36  */
  37 #ifndef OPENSSL_NO_KRB5
  38 #define OPENSSL_NO_KRB5
  39 #endif
  40 #include <openssl/err.h>
  41 #ifdef HAVE_OPENSSL_ENGINE_H
  42 #include <openssl/engine.h>
  43 #endif
  44 #include <openssl/ssl.h>
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 typedef struct fr_tls_server_conf_t fr_tls_server_conf_t;
  51
  52 typedef enum {
  53         FR_TLS_INVALID = 0,             /* invalid, don't reply */
  54         FR_TLS_REQUEST,                 /* request, ok to send, invalid to receive */
  55         FR_TLS_RESPONSE,                /* response, ok to receive, invalid to send */
  56         FR_TLS_SUCCESS,                 /* success, send success */
  57         FR_TLS_FAIL,                    /* fail, send fail */
  58         FR_TLS_NOOP,                    /* noop, continue */
  59
  60         FR_TLS_START,                   /* start, ok to send, invalid to receive */
  61         FR_TLS_OK,                      /* ok, continue */
  62         FR_TLS_ACK,                     /* acknowledge, continue */
  63         FR_TLS_FIRST_FRAGMENT,          /* first fragment */
  64         FR_TLS_MORE_FRAGMENTS,          /* more fragments, to send/receive */
  65         FR_TLS_LENGTH_INCLUDED,                 /* length included */
  66         FR_TLS_MORE_FRAGMENTS_WITH_LENGTH,   /* more fragments with length */
  67         FR_TLS_HANDLED                  /* tls code has handled it */
  68 } fr_tls_status_t;
  69
  70 #define MAX_RECORD_SIZE 16384
  71
  72 /*
  73  *      A single TLS record may be up to 16384 octets in length, but a
  74  *      TLS message may span multiple TLS records, and a TLS
  75  *      certificate message may in principle be as long as 16MB.
  76  *
  77  *      However, note that in order to protect against reassembly
  78  *      lockup and denial of service attacks, it may be desirable for
  79  *      an implementation to set a maximum size for one such group of
  80  *      TLS messages.
  81  *
  82  *      The TLS Message Length field is four octets, and provides the
  83  *      total length of the TLS message or set of messages that is
  84  *      being fragmented; this simplifies buffer allocation.
  85  */
  86
  87 /*
  88  * FIXME: Dynamic allocation of buffer to overcome MAX_RECORD_SIZE overflows.
  89  *      or configure TLS not to exceed MAX_RECORD_SIZE.
  90  */
  91 typedef struct _record_t {
  92         unsigned char data[MAX_RECORD_SIZE];
  93         unsigned int  used;
  94 } record_t;
  95
  96 typedef struct _tls_info_t {
  97         unsigned char   origin;
  98         unsigned char   content_type;
  99         unsigned char   handshake_type;
 100         unsigned char   alert_level;
 101         unsigned char   alert_description;
 102         char            info_description[256];
 103         size_t          record_len;
 104         int             version;
 105         char            initialized;
 106 } tls_info_t;
 107
 108 /*
 109  * tls_session_t Structure gets stored as opaque in EAP_HANDLER
 110  * This contains EAP-REQUEST specific data
 111  * (ie FR_TLS_DATA(fragment), EAPTLS-ALERT, EAPTLS-REQUEST ...)
 112  *
 113  * clean_in  - data that needs to be sent but only after it is soiled.
 114  * dirty_in  - data EAP server receives.
 115  * clean_out - data that is cleaned after receiving.
 116  * dirty_out - data EAP server sends.
 117  * offset    - current fragment size transmitted
 118  * fragment  - Flag, In fragment mode or not.
 119  * tls_msg_len - Actual/Total TLS message length.
 120  * length_flag - A flag to include length in every TLS Data/Alert packet
 121  *                                      if set to no then only the first fragment contains length
 122  */
 123 typedef struct _tls_session_t {
 124         SSL_CTX         *ctx;
 125         SSL             *ssl;
 126         tls_info_t      info;
 127
 128         BIO             *into_ssl;
 129         BIO             *from_ssl;
 130         record_t        clean_in;
 131         record_t        clean_out;
 132         record_t        dirty_in;
 133         record_t        dirty_out;
 134
 135         void            (*record_init)(record_t *buf);
 136         void            (*record_close)(record_t *buf);
 137         unsigned int    (*record_plus)(record_t *buf, const void *ptr,
 138                                        unsigned int size);
 139         unsigned int    (*record_minus)(record_t *buf, void *ptr,
 140                                         unsigned int size);
 141
 142
 143         /*
 144          * Framed-MTU attribute in RADIUS,
 145          * if present, can also be used to set this
 146          */
 147         unsigned int    offset;
 148         unsigned int    tls_msg_len;
 149         int             fragment;
 150         int             length_flag;
 151         int             peap_flag;
 152
 153         /*
 154          *      Used by TTLS & PEAP to keep track of other per-session
 155          *      data.
 156          */
 157         void            *opaque;
 158         void            (*free_opaque)(void *opaque);
 159
 160         const char      *prf_label;
 161         int             allow_session_resumption;
 162 } tls_session_t;
 163
 164
 165 /*
 166  *      RFC 2716, Section 4.2:
 167  *
 168  *         Flags
 169  *
 170  *      0 1 2 3 4 5 6 7 8
 171  *      +-+-+-+-+-+-+-+-+
 172  *      |L M S R R R R R|
 173  *      +-+-+-+-+-+-+-+-+
 174  *
 175  *      L = Length included
 176  *      M = More fragments
 177  *      S = EAP-TLS start
 178  *      R = Reserved
 179  */
 180 #define TLS_START(x)            (((x) & 0x20) != 0)
 181 #define TLS_MORE_FRAGMENTS(x)   (((x) & 0x40) != 0)
 182 #define TLS_LENGTH_INCLUDED(x)  (((x) & 0x80) != 0)
 183
 184 #define TLS_CHANGE_CIPHER_SPEC(x)       (((x) & 0x0014) == 0x0014)
 185 #define TLS_ALERT(x)                    (((x) & 0x0015) == 0x0015)
 186 #define TLS_HANDSHAKE(x)                (((x) & 0x0016) == 0x0016)
 187
 188 #define SET_START(x)            ((x) | (0x20))
 189 #define SET_MORE_FRAGMENTS(x)   ((x) | (0x40))
 190 #define SET_LENGTH_INCLUDED(x)  ((x) | (0x80))
 191
 192 /*
 193  *      Following enums from rfc2246
 194  *
 195  *      Hmm... since we dpeend on OpenSSL, it would be smarter to
 196  *      use the OpenSSL names for these.
 197  */
 198 enum ContentType {
 199         change_cipher_spec = 20,
 200         alert = 21,
 201         handshake = 22,
 202         application_data = 23
 203 };
 204
 205 enum AlertLevel {
 206         warning = 1,
 207         fatal = 2
 208 };
 209
 210 enum AlertDescription {
 211         close_notify = 0,
 212         unexpected_message = 10,
 213         bad_record_mac = 20,
 214         decryption_failed = 21,
 215         record_overflow = 22,
 216         decompression_failure = 30,
 217         handshake_failure = 40,
 218         bad_certificate = 42,
 219         unsupported_certificate = 43,
 220         certificate_revoked = 44,
 221         certificate_expired = 45,
 222         certificate_unknown = 46,
 223         illegal_parameter = 47,
 224         unknown_ca = 48,
 225         access_denied = 49,
 226         decode_error = 50,
 227         decrypt_error = 51,
 228         export_restriction = 60,
 229         protocol_version = 70,
 230         insufficient_security = 71,
 231         internal_error = 80,
 232         user_canceled = 90,
 233         no_renegotiation = 100
 234 };
 235
 236 enum HandshakeType {
 237         hello_request = 0,
 238         client_hello = 1,
 239         server_hello = 2,
 240         certificate = 11,
 241         server_key_exchange  = 12,
 242         certificate_request = 13,
 243         server_hello_done = 14,
 244         certificate_verify = 15,
 245         client_key_exchange = 16,
 246         finished = 20
 247 };
 248
 249
 250 /*
 251  * From rfc
 252    Flags
 253
 254       0 1 2 3 4 5 6 7 8
 255       +-+-+-+-+-+-+-+-+
 256       |L M S R R R R R|
 257       +-+-+-+-+-+-+-+-+
 258
 259       L = Length included
 260       M = More fragments
 261       S = EAP-TLS start
 262       R = Reserved
 263
 264       The L bit (length included) is set to indicate the presence of the
 265       four octet TLS Message Length field, and MUST be set for the first
 266       fragment of a fragmented TLS message or set of messages. The M bit
 267       (more fragments) is set on all but the last fragment. The S bit
 268       (EAP-TLS start) is set in an EAP-TLS Start message.  This
 269       differentiates the EAP-TLS Start message from a fragment
 270       acknowledgement.
 271
 272    TLS Message Length
 273
 274       The TLS Message Length field is four octets, and is present only
 275       if the L bit is set. This field provides the total length of the
 276       TLS message or set of messages that is being fragmented.
 277
 278    TLS data
 279
 280       The TLS data consists of the encapsulated TLS packet in TLS record
 281       format.
 282  *
 283  * The data structures present here
 284  * maps only to the typedata in the EAP packet
 285  *
 286  * Based on the L bit flag, first 4 bytes of data indicate the length
 287  */
 288
 289 /* Callbacks */
 290 int             cbtls_password(char *buf, int num, int rwflag, void *userdata);
 291 void            cbtls_info(const SSL *s, int where, int ret);
 292 void            cbtls_msg(int write_p, int msg_version, int content_type,
 293                         const void *buf, size_t len, SSL *ssl, void *arg);
 294 int             cbtls_verify(int ok, X509_STORE_CTX *ctx);
 295
 296 /* TLS */
 297 tls_session_t *tls_new_session(fr_tls_server_conf_t *conf, REQUEST *request,
 298                                int client_cert);
 299 tls_session_t   *tls_new_client_session(fr_tls_server_conf_t *conf, int fd);
 300 fr_tls_server_conf_t *tls_server_conf_parse(CONF_SECTION *cs);
 301 fr_tls_server_conf_t *tls_client_conf_parse(CONF_SECTION *cs);
 302 void tls_server_conf_free(fr_tls_server_conf_t *conf);
 303 int             tls_handshake_recv(REQUEST *, tls_session_t *ssn);
 304 int             tls_handshake_send(REQUEST *, tls_session_t *ssn);
 305 void            tls_session_information(tls_session_t *ssn);
 306
 307 /*
 308  *      Low-level TLS stuff
 309  */
 310 int tls_success(tls_session_t *ssn, REQUEST *request);
 311 void tls_fail(tls_session_t *ssn);
 312 fr_tls_status_t tls_ack_handler(tls_session_t *tls_session, REQUEST *request);
 313 fr_tls_status_t tls_application_data(tls_session_t *ssn, REQUEST *request);
 314
 315 /* Session */
 316 void            session_free(void *ssn);
 317 void            session_close(tls_session_t *ssn);
 318 void            session_init(tls_session_t *ssn);
 319
 320 #define FR_TLS_EX_INDEX_HANDLER (0)
 321 #define FR_TLS_EX_INDEX_CONF    (1)
 322 #define FR_TLS_EX_INDEX_REQUEST (2)
 323 #define FR_TLS_EX_INDEX_CERTS   (3)
 324 #define FR_TLS_EX_INDEX_IDENTITY (4)
 325 #define FR_TLS_EX_INDEX_STORE   (6)
 326
 327 /* configured values goes right here */
 328 struct fr_tls_server_conf_t {
 329         SSL_CTX         *ctx;
 330         CONF_SECTION    *cs;
 331
 332         char            *private_key_password;
 333         char            *private_key_file;
 334         char            *certificate_file;
 335         char            *random_file;
 336         char            *ca_path;
 337         char            *ca_file;
 338         char            *dh_file;
 339         char            *rsa_file;
 340         char            *make_cert_command;
 341         int             rsa_key;
 342         int             dh_key;
 343         int             rsa_key_length;
 344         int             dh_key_length;
 345         int             verify_depth;
 346         int             file_type;
 347         int             include_length;
 348
 349         /*
 350          *      Always < 4096 (due to radius limit), 0 by default = 2048
 351          */
 352         int             fragment_size;
 353         int             check_crl;
 354         int             allow_expired_crl;
 355         char            *check_cert_cn;
 356         char            *cipher_list;
 357         char            *check_cert_issuer;
 358
 359         int             session_cache_enable;
 360         int             session_timeout;
 361         int             session_cache_size;
 362         char            *session_id_name;
 363         char            session_context_id[SSL_MAX_SSL_SESSION_ID_LENGTH];
 364         time_t          session_last_flushed;
 365
 366         char            *verify_tmp_dir;
 367         char            *verify_client_cert_cmd;
 368         int             require_client_cert;
 369
 370 #ifdef HAVE_OPENSSL_OCSP_H
 371         /*
 372          * OCSP Configuration
 373          */
 374         int             ocsp_enable;
 375         int             ocsp_override_url;
 376         char            *ocsp_url;
 377         X509_STORE      *ocsp_store;
 378 #endif
 379
 380 #if OPENSSL_VERSION_NUMBER >= 0x0090800fL
 381 #ifndef OPENSSL_NO_ECDH
 382         char            *ecdh_curve;
 383 #endif
 384 #endif
 385
 386 #ifdef PSK_MAX_IDENTITY_LEN
 387         char            *psk_identity;
 388         char            *psk_password;
 389 #endif
 390
 391 };
 392
 393 #ifdef __cplusplus
 394 }
 395 #endif
 396
 397 #endif  /* WITH_TLS */
 398 #endif /* FR_TLS_H */