src/libtls/tls.h

   1 /*
   2  * Copyright (C) 2010 Martin Willi
   3  * Copyright (C) 2010 revosec AG
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  */
  15
  16 /**
  17  * @defgroup libtls libtls
  18  *
  19  * @addtogroup libtls
  20  * TLS implementation on top of libstrongswan
  21  *
  22  * @defgroup tls tls
  23  * @{ @ingroup libtls
  24  */
  25
  26 #ifndef TLS_H_
  27 #define TLS_H_
  28
  29 /**
  30  * Maximum size of a TLS fragment
  31  * as defined by section 6.2.1. "Fragmentation" of RFC 5246 TLS 1.2
  32  */
  33 #define TLS_MAX_FRAGMENT_LEN    16384
  34
  35 typedef enum tls_version_t tls_version_t;
  36 typedef enum tls_content_type_t tls_content_type_t;
  37 typedef enum tls_handshake_type_t tls_handshake_type_t;
  38 typedef enum tls_purpose_t tls_purpose_t;
  39 typedef struct tls_t tls_t;
  40
  41 #include <library.h>
  42
  43 #include "tls_application.h"
  44 #include "tls_cache.h"
  45
  46 /**
  47  * TLS/SSL version numbers
  48  */
  49 enum tls_version_t {
  50         SSL_2_0 = 0x0200,
  51         SSL_3_0 = 0x0300,
  52         TLS_1_0 = 0x0301,
  53         TLS_1_1 = 0x0302,
  54         TLS_1_2 = 0x0303,
  55 };
  56
  57 /**
  58  * Enum names for tls_version_t
  59  */
  60 extern enum_name_t *tls_version_names;
  61
  62 /**
  63  * TLS higher level content type
  64  */
  65 enum tls_content_type_t {
  66         TLS_CHANGE_CIPHER_SPEC = 20,
  67         TLS_ALERT = 21,
  68         TLS_HANDSHAKE = 22,
  69         TLS_APPLICATION_DATA = 23,
  70 };
  71
  72 /**
  73  * Enum names for tls_content_type_t
  74  */
  75 extern enum_name_t *tls_content_type_names;
  76
  77 /**
  78  * TLS handshake subtype
  79  */
  80 enum tls_handshake_type_t {
  81         TLS_HELLO_REQUEST = 0,
  82         TLS_CLIENT_HELLO = 1,
  83         TLS_SERVER_HELLO = 2,
  84         TLS_CERTIFICATE = 11,
  85         TLS_SERVER_KEY_EXCHANGE = 12,
  86         TLS_CERTIFICATE_REQUEST = 13,
  87         TLS_SERVER_HELLO_DONE = 14,
  88         TLS_CERTIFICATE_VERIFY = 15,
  89         TLS_CLIENT_KEY_EXCHANGE = 16,
  90         TLS_FINISHED = 20,
  91 };
  92
  93 /**
  94  * Enum names for tls_handshake_type_t
  95  */
  96 extern enum_name_t *tls_handshake_type_names;
  97
  98 /**
  99  * Purpose the TLS stack is initiated for.
 100  */
 101 enum tls_purpose_t {
 102         /** authentication in EAP-TLS */
 103         TLS_PURPOSE_EAP_TLS,
 104         /** outer authentication and protection in EAP-TTLS */
 105         TLS_PURPOSE_EAP_TTLS,
 106         /** outer authentication and protection in EAP-PEAP */
 107         TLS_PURPOSE_EAP_PEAP,
 108         /** non-EAP TLS */
 109         TLS_PURPOSE_GENERIC,
 110         /** non-EAP TLS accepting NULL encryption */
 111         TLS_PURPOSE_GENERIC_NULLOK,
 112         /** EAP binding for TNC */
 113         TLS_PURPOSE_EAP_TNC
 114 };
 115
 116 /**
 117  * TLS Hello extension types.
 118  */
 119 enum tls_extension_t {
 120         /** Server name the client wants to talk to */
 121         TLS_EXT_SERVER_NAME = 0,
 122         /** request a maximum fragment size */
 123         TLS_EXT_MAX_FRAGMENT_LENGTH = 1,
 124         /** indicate client certificate URL support */
 125         TLS_EXT_CLIENT_CERTIFICATE_URL = 2,
 126         /** list of CA the client trusts */
 127         TLS_EXT_TRUSTED_CA_KEYS = 3,
 128         /** request MAC truncation to 80-bit */
 129         TLS_EXT_TRUNCATED_HMAC = 4,
 130         /** list of OCSP responders the client trusts */
 131         TLS_EXT_STATUS_REQUEST = 5,
 132         /** list of supported elliptic curves */
 133         TLS_EXT_ELLIPTIC_CURVES = 10,
 134         /** supported point formats */
 135         TLS_EXT_EC_POINT_FORMATS = 11,
 136         /** list supported signature algorithms */
 137         TLS_EXT_SIGNATURE_ALGORITHMS = 13,
 138         /** cryptographic binding for RFC 5746 renegotiation indication */
 139         TLS_EXT_RENEGOTIATION_INFO = 65281,
 140 };
 141
 142 enum tls_name_type_t {
 143         TLS_NAME_TYPE_HOST_NAME = 0,
 144 };
 145
 146 /**
 147  * Enum names for tls_extension_t
 148  */
 149 extern enum_name_t *tls_extension_names;
 150
 151 /**
 152  * A bottom-up driven TLS stack, suitable for EAP implementations.
 153  */
 154 struct tls_t {
 155
 156         /**
 157          * Process one or more TLS records, pass it to upper layers.
 158          *
 159          * @param buf           TLS record data, including headers
 160          * @param buflen        number of bytes in buf to process
 161          * @return
 162          *                                      - SUCCESS if TLS negotiation complete
 163          *                                      - FAILED if TLS handshake failed
 164          *                                      - NEED_MORE if more invocations to process/build needed
 165          */
 166         status_t (*process)(tls_t *this, void *buf, size_t buflen);
 167
 168         /**
 169          * Query upper layer for one or more TLS records, build fragments.
 170          *
 171          * The TLS stack automatically fragments the records to the given buffer
 172          * size. Fragmentation is indicated by the reclen output parameter and
 173          * the return value. For the first fragment of a TLS record, a non-zero
 174          * record length is returned in reclen. If more fragments follow, NEED_MORE
 175          * is returned. A return value of ALREADY_DONE indicates that the final
 176          * fragment has been returned.
 177          *
 178          * @param buf           buffer to write TLS record fragments to
 179          * @param buflen        size of buffer, receives bytes written
 180          * @param msglen        receives size of all TLS fragments
 181          * @return
 182          *                                      - SUCCESS if TLS negotiation complete
 183          *                                      - FAILED if TLS handshake failed
 184          *                                      - INVALID_STATE if more input data required
 185          *                                      - NEED_MORE if more fragments available
 186          *                                      - ALREADY_DONE if the last available fragment returned
 187          */
 188         status_t (*build)(tls_t *this, void *buf, size_t *buflen, size_t *msglen);
 189
 190         /**
 191          * Check if TLS stack is acting as a server.
 192          *
 193          * @return                      TRUE if server, FALSE if peer
 194          */
 195         bool (*is_server)(tls_t *this);
 196
 197         /**
 198          * Return the server identity.
 199          *
 200          * @return                      server identity
 201          */
 202         identification_t* (*get_server_id)(tls_t *this);
 203
 204         /**
 205          * Set the peer identity.
 206          *
 207          * @param id            peer identity
 208          */
 209         void (*set_peer_id)(tls_t *this, identification_t *id);
 210
 211         /**
 212          * Return the peer identity.
 213          *
 214          * @return                      peer identity
 215          */
 216         identification_t* (*get_peer_id)(tls_t *this);
 217
 218         /**
 219          * Get the negotiated TLS/SSL version.
 220          *
 221          * @return                      negotiated TLS version
 222          */
 223         tls_version_t (*get_version)(tls_t *this);
 224
 225         /**
 226          * Set the negotiated TLS/SSL version.
 227          *
 228          * @param version       negotiated TLS version
 229          * @return                      TRUE if version acceptable
 230          */
 231         bool (*set_version)(tls_t *this, tls_version_t version);
 232
 233         /**
 234          * Get the purpose of this TLS stack instance.
 235          *
 236          * @return                      purpose given during construction
 237          */
 238         tls_purpose_t (*get_purpose)(tls_t *this);
 239
 240         /**
 241          * Check if TLS negotiation completed successfully.
 242          *
 243          * @return                      TRUE if TLS negotiation and authentication complete
 244          */
 245         bool (*is_complete)(tls_t *this);
 246
 247         /**
 248          * Get the MSK for EAP-TLS.
 249          *
 250          * @return                      MSK, internal data
 251          */
 252         chunk_t (*get_eap_msk)(tls_t *this);
 253
 254         /**
 255          * Get the authentication details after completing the handshake.
 256          *
 257          * @return                      authentication details, internal data
 258          */
 259         auth_cfg_t* (*get_auth)(tls_t *this);
 260
 261         /**
 262          * Destroy a tls_t.
 263          */
 264         void (*destroy)(tls_t *this);
 265 };
 266
 267 /**
 268  * Dummy libtls initialization function needed for integrity test
 269  */
 270 void libtls_init(void);
 271
 272 /**
 273  * Create a tls instance.
 274  *
 275  * @param is_server                     TRUE to act as server, FALSE for client
 276  * @param server                        server identity
 277  * @param peer                          peer identity, NULL for no client authentication
 278  * @param purpose                       purpose this TLS stack instance is used for
 279  * @param application           higher layer application or NULL if none
 280  * @param cache                         session cache to use, or NULL
 281  * @return                                      TLS stack
 282  */
 283 tls_t *tls_create(bool is_server, identification_t *server,
 284                                   identification_t *peer, tls_purpose_t purpose,
 285                                   tls_application_t *application, tls_cache_t *cache);
 286
 287 #endif /** TLS_H_ @}*/