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 typedef enum tls_version_t tls_version_t;
  30 typedef enum tls_content_type_t tls_content_type_t;
  31 typedef enum tls_handshake_type_t tls_handshake_type_t;
  32 typedef struct tls_t tls_t;
  33
  34 #include <library.h>
  35
  36 /**
  37  * TLS/SSL version numbers
  38  */
  39 enum tls_version_t {
  40         SSL_2_0 = 0x0200,
  41         SSL_3_0 = 0x0300,
  42         TLS_1_0 = 0x0301,
  43         TLS_1_1 = 0x0302,
  44         TLS_1_2 = 0x0303,
  45 };
  46
  47 /**
  48  * Enum names for tls_version_t
  49  */
  50 extern enum_name_t *tls_version_names;
  51
  52 /**
  53  * TLS higher level content type
  54  */
  55 enum tls_content_type_t {
  56         TLS_CHANGE_CIPHER_SPEC = 20,
  57         TLS_ALERT = 21,
  58         TLS_HANDSHAKE = 22,
  59         TLS_APPLICATION_DATA = 23,
  60 };
  61
  62 /**
  63  * Enum names for tls_content_type_t
  64  */
  65 extern enum_name_t *tls_content_type_names;
  66
  67 /**
  68  * TLS handshake subtype
  69  */
  70 enum tls_handshake_type_t {
  71         TLS_HELLO_REQUEST = 0,
  72         TLS_CLIENT_HELLO = 1,
  73         TLS_SERVER_HELLO = 2,
  74         TLS_CERTIFICATE = 11,
  75         TLS_SERVER_KEY_EXCHANGE = 12,
  76         TLS_CERTIFICATE_REQUEST = 13,
  77         TLS_SERVER_HELLO_DONE = 14,
  78         TLS_CERTIFICATE_VERIFY = 15,
  79         TLS_CLIENT_KEY_EXCHANGE = 16,
  80         TLS_FINISHED = 20,
  81 };
  82
  83 /**
  84  * Enum names for tls_handshake_type_t
  85  */
  86 extern enum_name_t *tls_handshake_type_names;
  87
  88 /**
  89  * A bottom-up driven TLS stack, suitable for EAP implementations.
  90  */
  91 struct tls_t {
  92
  93         /**
  94          * Process a TLS record, pass it to upper layers.
  95          *
  96          * @param type          type of the TLS record to process
  97          * @param data          associated TLS record data
  98          * @return
  99          *                                      - SUCCESS if TLS negotiation complete
 100          *                                      - FAILED if TLS handshake failed
 101          *                                      - NEED_MORE if more invocations to process/build needed
 102          */
 103         status_t (*process)(tls_t *this, tls_content_type_t type, chunk_t data);
 104
 105         /**
 106          * Query upper layer for TLS record, build protected record.
 107          *
 108          * @param type          type of the built TLS record
 109          * @param data          allocated data of the built TLS record
 110          * @return
 111          *                                      - SUCCESS if TLS negotiation complete
 112          *                                      - FAILED if TLS handshake failed
 113          *                                      - NEED_MORE if upper layers have more records to send
 114          *                                      - INVALID_STATE if more input records required
 115          */
 116         status_t (*build)(tls_t *this, tls_content_type_t *type, chunk_t *data);
 117
 118         /**
 119          * Check if TLS stack is acting as a server.
 120          *
 121          * @return                      TRUE if server, FALSE if peer
 122          */
 123         bool (*is_server)(tls_t *this);
 124
 125         /**
 126          * Get the negotiated TLS/SSL version.
 127          *
 128          * @return                      negotiated TLS version
 129          */
 130         tls_version_t (*get_version)(tls_t *this);
 131
 132         /**
 133          * Set the negotiated TLS/SSL version.
 134          *
 135          * @param version       negotiated TLS version
 136          */
 137         void (*set_version)(tls_t *this, tls_version_t version);
 138
 139         /**
 140          * Check if TLS negotiation completed successfully.
 141          *
 142          * @return                      TRUE if TLS negotation and authentication complete
 143          */
 144         bool (*is_complete)(tls_t *this);
 145
 146         /**
 147          * Get the MSK for EAP-TLS.
 148          *
 149          * @return                      MSK, internal data
 150          */
 151         chunk_t (*get_eap_msk)(tls_t *this);
 152
 153         /**
 154          * Destroy a tls_t.
 155          */
 156         void (*destroy)(tls_t *this);
 157 };
 158
 159 /**
 160  * Create a tls instance.
 161  *
 162  * @param is_server             TRUE to act as server, FALSE for client
 163  * @param server                server identity
 164  * @param peer                  peer identity
 165  * @param msk_label             ASCII string constant used as seed for MSK PRF
 166  * @return                              TLS stack
 167  */
 168 tls_t *tls_create(bool is_server, identification_t *server,
 169                                   identification_t *peer, char *msk_label);
 170
 171 #endif /** TLS_H_ @}*/