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