src/include/tls-h

   1 /*
   2  *   This program is free software; you can redistribute it and/or modify
   3  *   it under the terms of the GNU General Public License as published by
   4  *   the Free Software Foundation; either version 2 of the License, or
   5  *   (at your option) any later version.
   6  *
   7  *   This program is distributed in the hope that it will be useful,
   8  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   9  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10  *   GNU General Public License for more details.
  11  *
  12  *   You should have received a copy of the GNU General Public License
  13  *   along with this program; if not, write to the Free Software
  14  *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  15  */
  16 #ifndef FR_TLS_H
  17 #define FR_TLS_H
  18
  19 #ifdef WITH_TLS
  20 /*
  21  * $Id$
  22  *
  23  * @file tls.h
  24  * @brief Structures and prototypes for TLS wrappers
  25  *
  26  * @copyright 2010 Network RADIUS SARL <info@networkradius.com>
  27  */
  28
  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_t
 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, void const *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         char const      *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(SSL const *s, int where, int ret);
 291 void            cbtls_msg(int write_p, int msg_version, int content_type, void const *buf, size_t len, SSL *ssl,
 292                           void *arg);
 293 int             cbtls_verify(int ok, X509_STORE_CTX *ctx);
 294
 295 /* TLS */
 296 int             tls_global_init(bool allow_vulnerable);
 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 int             tls_handshake_recv(REQUEST *, tls_session_t *ssn);
 303 int             tls_handshake_send(REQUEST *, tls_session_t *ssn);
 304 void            tls_session_information(tls_session_t *ssn);
 305
 306 /*
 307  *      Low-level TLS stuff
 308  */
 309 int tls_success(tls_session_t *ssn, REQUEST *request);
 310 void tls_fail(tls_session_t *ssn);
 311 fr_tls_status_t tls_ack_handler(tls_session_t *tls_session, REQUEST *request);
 312 fr_tls_status_t tls_application_data(tls_session_t *ssn, REQUEST *request);
 313
 314 /* Session */
 315 void            session_free(void *ssn);
 316 void            session_close(tls_session_t *ssn);
 317 void            session_init(tls_session_t *ssn);
 318
 319 #define FR_TLS_EX_INDEX_HANDLER (0)
 320 #define FR_TLS_EX_INDEX_CONF    (1)
 321 #define FR_TLS_EX_INDEX_REQUEST (2)
 322 #define FR_TLS_EX_INDEX_CERTS   (3)
 323 #define FR_TLS_EX_INDEX_IDENTITY (4)
 324 #define FR_TLS_EX_INDEX_STORE   (6)
 325 #define FR_TLS_EX_INDEX_SSN     (7)
 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         bool            rsa_key;
 341         bool            dh_key;
 342         int             rsa_key_length;
 343         int             dh_key_length;
 344         int             verify_depth;
 345         bool            file_type;
 346         bool            include_length;
 347
 348         /*
 349          *      Always < 4096 (due to radius limit), 0 by default = 2048
 350          */
 351         int             fragment_size;
 352         bool            check_crl;
 353         bool            allow_expired_crl;
 354         char            *check_cert_cn;
 355         char            *cipher_list;
 356         char            *check_cert_issuer;
 357
 358         bool            session_cache_enable;
 359         int             session_timeout;
 360         int             session_cache_size;
 361         char            *session_id_name;
 362         char            *session_cache_path;
 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         bool            require_client_cert;
 369
 370 #ifdef HAVE_OPENSSL_OCSP_H
 371         /*
 372          * OCSP Configuration
 373          */
 374         bool            ocsp_enable;
 375         bool            ocsp_override_url;
 376         char            *ocsp_url;
 377         bool            ocsp_use_nonce;
 378         X509_STORE      *ocsp_store;
 379         int             ocsp_timeout;
 380         bool            ocsp_softfail;
 381 #endif
 382
 383 #if OPENSSL_VERSION_NUMBER >= 0x0090800fL
 384 #ifndef OPENSSL_NO_ECDH
 385         char            *ecdh_curve;
 386 #endif
 387 #endif
 388
 389 #ifdef PSK_MAX_IDENTITY_LEN
 390         char            *psk_identity;
 391         char            *psk_password;
 392 #endif
 393
 394 };
 395
 396 #ifdef __cplusplus
 397 }
 398 #endif
 399
 400 #endif  /* WITH_TLS */
 401 #endif /* FR_TLS_H */