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