src/libtls/tls.h

   1 /*
   2  * Copyright (C) 2021 Tobias Brunner
   3  * Copyright (C) 2020-2021 Pascal Knecht
   4  * Copyright (C) 2010 Martin Willi
   5  *
   6  * Copyright (C) secunet Security Networks AG
   7  *
   8  * This program is free software; you can redistribute it and/or modify it
   9  * under the terms of the GNU General Public License as published by the
  10  * Free Software Foundation; either version 2 of the License, or (at your
  11  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  15  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16  * for more details.
  17  */
  18
  19 /**
  20  * @defgroup libtls libtls
  21  *
  22  * @addtogroup libtls
  23  * TLS implementation on top of libstrongswan
  24  *
  25  * @defgroup tls tls
  26  * @{ @ingroup libtls
  27  */
  28
  29 #ifndef TLS_H_
  30 #define TLS_H_
  31
  32 /**
  33  * Maximum size of a TLS fragment
  34  * as defined by section 6.2.1. "Fragmentation" of RFC 5246 TLS 1.2
  35  */
  36 #define TLS_MAX_FRAGMENT_LEN    16384
  37
  38 typedef enum tls_version_t tls_version_t;
  39 typedef enum tls_content_type_t tls_content_type_t;
  40 typedef enum tls_handshake_type_t tls_handshake_type_t;
  41 typedef enum tls_purpose_t tls_purpose_t;
  42 typedef enum tls_flag_t tls_flag_t;
  43 typedef struct tls_t tls_t;
  44
  45 #include <library.h>
  46
  47 #include "tls_application.h"
  48 #include "tls_cache.h"
  49
  50 /**
  51  * TLS/SSL version numbers
  52  */
  53 enum tls_version_t {
  54         TLS_UNSPEC = 0,
  55         SSL_2_0 = 0x0200,
  56         SSL_3_0 = 0x0300,
  57         TLS_1_0 = 0x0301,
  58         TLS_SUPPORTED_MIN = TLS_1_0,
  59         TLS_1_1 = 0x0302,
  60         TLS_1_2 = 0x0303,
  61         TLS_1_3 = 0x0304,
  62         TLS_SUPPORTED_MAX = TLS_1_3,
  63 };
  64
  65 /**
  66  * Enum names for tls_version_t
  67  */
  68 extern enum_name_t *tls_version_names;
  69
  70 /**
  71  * Simple, numeric enum names for tls_version_t (only supported versions)
  72  */
  73 extern enum_name_t *tls_numeric_version_names;
  74
  75 /**
  76  * TLS higher level content type
  77  */
  78 enum tls_content_type_t {
  79         TLS_CHANGE_CIPHER_SPEC = 20,
  80         TLS_ALERT = 21,
  81         TLS_HANDSHAKE = 22,
  82         TLS_APPLICATION_DATA = 23,
  83 };
  84
  85 /**
  86  * Enum names for tls_content_type_t
  87  */
  88 extern enum_name_t *tls_content_type_names;
  89
  90 /**
  91  * TLS handshake subtype
  92  */
  93 enum tls_handshake_type_t {
  94         TLS_HELLO_REQUEST = 0,
  95         TLS_CLIENT_HELLO = 1,
  96         TLS_SERVER_HELLO = 2,
  97         TLS_HELLO_VERIFY_REQUEST = 3,
  98         TLS_NEW_SESSION_TICKET = 4,
  99         TLS_END_OF_EARLY_DATA = 5,
 100         TLS_HELLO_RETRY_REQUEST = 6,
 101         TLS_ENCRYPTED_EXTENSIONS = 8,
 102         TLS_CERTIFICATE = 11,
 103         TLS_SERVER_KEY_EXCHANGE = 12,
 104         TLS_CERTIFICATE_REQUEST = 13,
 105         TLS_SERVER_HELLO_DONE = 14,
 106         TLS_CERTIFICATE_VERIFY = 15,
 107         TLS_CLIENT_KEY_EXCHANGE = 16,
 108         TLS_FINISHED = 20,
 109         TLS_CERTIFICATE_URL = 21,
 110         TLS_CERTIFICATE_STATUS = 22,
 111         TLS_SUPPLEMENTAL_DATA = 23,
 112         TLS_KEY_UPDATE = 24,
 113         TLS_MESSAGE_HASH = 254,
 114 };
 115
 116 /**
 117  * Enum names for tls_handshake_type_t
 118  */
 119 extern enum_name_t *tls_handshake_type_names;
 120
 121 /**
 122  * Purpose the TLS stack is initiated for.
 123  */
 124 enum tls_purpose_t {
 125         /** authentication in EAP-TLS */
 126         TLS_PURPOSE_EAP_TLS,
 127         /** outer authentication and protection in EAP-TTLS */
 128         TLS_PURPOSE_EAP_TTLS,
 129         /** outer authentication and protection in EAP-PEAP */
 130         TLS_PURPOSE_EAP_PEAP,
 131         /** non-EAP TLS */
 132         TLS_PURPOSE_GENERIC,
 133         /** EAP binding for TNC */
 134         TLS_PURPOSE_EAP_TNC
 135 };
 136
 137 /**
 138  * TLS Handshake extension types.
 139  */
 140 enum tls_extension_t {
 141         /** Server name the client wants to talk to */
 142         TLS_EXT_SERVER_NAME = 0,
 143         /** request a maximum fragment size */
 144         TLS_EXT_MAX_FRAGMENT_LENGTH = 1,
 145         /** indicate client certificate URL support */
 146         TLS_EXT_CLIENT_CERTIFICATE_URL = 2,
 147         /** list of CA the client trusts */
 148         TLS_EXT_TRUSTED_CA_KEYS = 3,
 149         /** request MAC truncation to 80-bit */
 150         TLS_EXT_TRUNCATED_HMAC = 4,
 151         /** list of OCSP responders the client trusts */
 152         TLS_EXT_STATUS_REQUEST = 5,
 153         /** list of supported groups, in legacy tls: elliptic curves */
 154         TLS_EXT_SUPPORTED_GROUPS = 10,
 155         /** supported point formats */
 156         TLS_EXT_EC_POINT_FORMATS = 11,
 157         /** list supported signature algorithms */
 158         TLS_EXT_SIGNATURE_ALGORITHMS = 13,
 159         /** indicate usage of Datagram Transport Layer Security (DTLS) */
 160         TLS_EXT_USE_SRTP = 14,
 161         /** indicate usage of heartbeat */
 162         TLS_EXT_HEARTBEAT = 15,
 163         /** indicate usage of application-layer protocol negotiation */
 164         TLS_EXT_APPLICATION_LAYER_PROTOCOL_NEGOTIATION = 16,
 165         /** exchange raw public key, client side*/
 166         TLS_CLIENT_CERTIFICATE_TYPE = 19,
 167         /** exchange raw public key, server side*/
 168         TLS_SERVER_CERTIFICATE_TYPE = 20,
 169         /** use encrypt-then-MAC security mechanism RFC 7366 */
 170         TLS_EXT_ENCRYPT_THEN_MAC = 22,
 171         /** bind master secret to handshake data RFC 7627 */
 172         TLS_EXT_EXTENDED_MASTER_SECRET = 23,
 173         /** session resumption without server-side state RFC 5077 */
 174         TLS_EXT_SESSION_TICKET = 35,
 175         /** negotiate identity of the psk **/
 176         TLS_EXT_PRE_SHARED_KEY = 41,
 177         /** send data in 0-RTT when psk is used and early data is allowed **/
 178         TLS_EXT_EARLY_DATA = 42,
 179         /** negotiate supported tls versions **/
 180         TLS_EXT_SUPPORTED_VERSIONS = 43,
 181         /** identify client **/
 182         TLS_EXT_COOKIE = 44,
 183         /** psk modes supported by the client **/
 184         TLS_EXT_PSK_KEY_EXCHANGE_MODES = 45,
 185         /** indicate supported ca's by endpoint **/
 186         TLS_EXT_CERTIFICATE_AUTHORITIES = 47,
 187         /** provide oid/value pairs to match client's certificate **/
 188         TLS_EXT_OID_FILTERS = 48,
 189         /** willing to perform post-handshake authentication **/
 190         TLS_EXT_POST_HANDSHAKE_AUTH = 49,
 191         /** list supported signature algorithms to verify certificates **/
 192         TLS_EXT_SIGNATURE_ALGORITHMS_CERT = 50,
 193         /** list endpoint's cryptographic parameters **/
 194         TLS_EXT_KEY_SHARE = 51,
 195         /** cryptographic binding for RFC 5746 renegotiation indication */
 196         TLS_EXT_RENEGOTIATION_INFO = 65281,
 197 };
 198
 199 enum tls_name_type_t {
 200         TLS_NAME_TYPE_HOST_NAME = 0,
 201 };
 202
 203 /**
 204  * Flags that control the behavior of the stack
 205  */
 206 enum tls_flag_t {
 207         /** set if cipher suites with null encryption are acceptable */
 208         TLS_FLAG_ENCRYPTION_OPTIONAL = 1,
 209         /** set if client authentication is optional even if cert req sent */
 210         TLS_FLAG_CLIENT_AUTH_OPTIONAL = 2,
 211 };
 212
 213 /**
 214  * Enum names for tls_extension_t
 215  */
 216 extern enum_name_t *tls_extension_names;
 217
 218 /**
 219  * Magic value (SHA-256 of "HelloRetryRequest") for Random to differentiate
 220  * ServerHello from HelloRetryRequest.
 221  */
 222 extern chunk_t tls_hello_retry_request_magic;
 223
 224 /**
 225  * Magic values for downgrade protection (see RFC 8446, section 4.1.3)
 226  */
 227 extern chunk_t tls_downgrade_protection_tls11;
 228 extern chunk_t tls_downgrade_protection_tls12;
 229
 230 /**
 231  * A bottom-up driven TLS stack, suitable for EAP implementations.
 232  */
 233 struct tls_t {
 234
 235         /**
 236          * Process one or more TLS records, pass it to upper layers.
 237          *
 238          * @param buf           TLS record data, including headers
 239          * @param buflen        number of bytes in buf to process
 240          * @return
 241          *                                      - SUCCESS if TLS negotiation complete
 242          *                                      - FAILED if TLS handshake failed
 243          *                                      - NEED_MORE if more invocations to process/build needed
 244          */
 245         status_t (*process)(tls_t *this, void *buf, size_t buflen);
 246
 247         /**
 248          * Query upper layer for one or more TLS records, build fragments.
 249          *
 250          * The TLS stack automatically fragments the records to the given buffer
 251          * size. Fragmentation is indicated by the reclen output parameter and
 252          * the return value. For the first fragment of a TLS record, a non-zero
 253          * record length is returned in reclen. If more fragments follow, NEED_MORE
 254          * is returned. A return value of ALREADY_DONE indicates that the final
 255          * fragment has been returned.
 256          *
 257          * @param buf           buffer to write TLS record fragments to
 258          * @param buflen        size of buffer, receives bytes written
 259          * @param msglen        receives size of all TLS fragments
 260          * @return
 261          *                                      - SUCCESS if TLS negotiation complete
 262          *                                      - FAILED if TLS handshake failed
 263          *                                      - INVALID_STATE if more input data required
 264          *                                      - NEED_MORE if more fragments available
 265          *                                      - ALREADY_DONE if the last available fragment returned
 266          */
 267         status_t (*build)(tls_t *this, void *buf, size_t *buflen, size_t *msglen);
 268
 269         /**
 270          * Check if TLS stack is acting as a server.
 271          *
 272          * @return                      TRUE if server, FALSE if peer
 273          */
 274         bool (*is_server)(tls_t *this);
 275
 276         /**
 277          * Return the server identity.
 278          *
 279          * @return                      server identity
 280          */
 281         identification_t* (*get_server_id)(tls_t *this);
 282
 283         /**
 284          * Set the peer identity.
 285          *
 286          * @param id            peer identity
 287          */
 288         void (*set_peer_id)(tls_t *this, identification_t *id);
 289
 290         /**
 291          * Return the peer identity.
 292          *
 293          * @return                      peer identity
 294          */
 295         identification_t* (*get_peer_id)(tls_t *this);
 296
 297         /**
 298          * Get the maximum and negotiated TLS version.
 299          *
 300          * @return                      max and negotiated TLS version
 301          */
 302         tls_version_t (*get_version_max)(tls_t *this);
 303
 304         /**
 305         * Get the minimum TLS version.
 306         *
 307         * @return                       min TLS version
 308         */
 309         tls_version_t (*get_version_min)(tls_t *this);
 310
 311         /**
 312          * Set the initial minimum/maximum TLS version, or set both to the same
 313          * value once negotiated.
 314          *
 315          * @param min_version   minimum (or negotiated) TLS version
 316          * @param max_version   maximum (or negotiated) TLS version
 317          * @return                              TRUE if version(s) acceptable
 318          */
 319         bool (*set_version)(tls_t *this, tls_version_t min_version,
 320                                                 tls_version_t max_version);
 321
 322         /**
 323          * Get the purpose of this TLS stack instance.
 324          *
 325          * @return                      purpose given during construction
 326          */
 327         tls_purpose_t (*get_purpose)(tls_t *this);
 328
 329         /**
 330          * Get the flags controlling this TLS stack instance.
 331          *
 332          * @return                      flags given during construction
 333          */
 334         tls_flag_t (*get_flags)(tls_t *this);
 335
 336         /**
 337          * Check if TLS negotiation completed successfully.
 338          *
 339          * @return                      TRUE if TLS negotiation and authentication complete
 340          */
 341         bool (*is_complete)(tls_t *this);
 342
 343         /**
 344          * Get the MSK for EAP-TLS.
 345          *
 346          * @return                      MSK, internal data
 347          */
 348         chunk_t (*get_eap_msk)(tls_t *this);
 349
 350         /**
 351          * Get the authentication details after completing the handshake.
 352          *
 353          * @return                      authentication details, internal data
 354          */
 355         auth_cfg_t* (*get_auth)(tls_t *this);
 356
 357         /**
 358          * Destroy a tls_t.
 359          */
 360         void (*destroy)(tls_t *this);
 361 };
 362
 363 /**
 364  * Dummy libtls initialization function needed for integrity test
 365  */
 366 void libtls_init(void);
 367
 368 /**
 369  * Create a tls instance.
 370  *
 371  * @param is_server                     TRUE to act as server, FALSE for client
 372  * @param server                        server identity
 373  * @param peer                          peer identity, NULL for no client authentication
 374  * @param purpose                       purpose this TLS stack instance is used for
 375  * @param application           higher layer application or NULL if none
 376  * @param cache                         session cache to use, or NULL
 377  * @param flags                         flags that control the behavior of the TLS stack
 378  * @return                                      TLS stack
 379  */
 380 tls_t *tls_create(bool is_server, identification_t *server,
 381                                   identification_t *peer, tls_purpose_t purpose,
 382                                   tls_application_t *application, tls_cache_t *cache,
 383                                   tls_flag_t flags);
 384
 385 #endif /** TLS_H_ @}*/