src/common/tortls.h

   1 /* Copyright (c) 2003, Roger Dingledine
   2  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   3  * Copyright (c) 2007-2017, The Tor Project, Inc. */
   4 /* See LICENSE for licensing information */
   5
   6 #ifndef TOR_TORTLS_H
   7 #define TOR_TORTLS_H
   8
   9 /**
  10  * \file tortls.h
  11  * \brief Headers for tortls.c
  12  **/
  13
  14 #include "crypto.h"
  15 #include "compat_openssl.h"
  16 #include "compat.h"
  17 #include "testsupport.h"
  18
  19 /* Opaque structure to hold a TLS connection. */
  20 typedef struct tor_tls_t tor_tls_t;
  21
  22 /* Opaque structure to hold an X509 certificate. */
  23 typedef struct tor_x509_cert_t tor_x509_cert_t;
  24
  25 /* Possible return values for most tor_tls_* functions. */
  26 #define MIN_TOR_TLS_ERROR_VAL_     -9
  27 #define TOR_TLS_ERROR_MISC         -9
  28 /* Rename to unexpected close or something. XXXX */
  29 #define TOR_TLS_ERROR_IO           -8
  30 #define TOR_TLS_ERROR_CONNREFUSED  -7
  31 #define TOR_TLS_ERROR_CONNRESET    -6
  32 #define TOR_TLS_ERROR_NO_ROUTE     -5
  33 #define TOR_TLS_ERROR_TIMEOUT      -4
  34 #define TOR_TLS_CLOSE              -3
  35 #define TOR_TLS_WANTREAD           -2
  36 #define TOR_TLS_WANTWRITE          -1
  37 #define TOR_TLS_DONE                0
  38
  39 /** Collection of case statements for all TLS errors that are not due to
  40  * underlying IO failure. */
  41 #define CASE_TOR_TLS_ERROR_ANY_NONIO            \
  42   case TOR_TLS_ERROR_MISC:                      \
  43   case TOR_TLS_ERROR_CONNREFUSED:               \
  44   case TOR_TLS_ERROR_CONNRESET:                 \
  45   case TOR_TLS_ERROR_NO_ROUTE:                  \
  46   case TOR_TLS_ERROR_TIMEOUT
  47
  48 /** Use this macro in a switch statement to catch _any_ TLS error.  That way,
  49  * if more errors are added, your switches will still work. */
  50 #define CASE_TOR_TLS_ERROR_ANY                  \
  51   CASE_TOR_TLS_ERROR_ANY_NONIO:                 \
  52   case TOR_TLS_ERROR_IO
  53
  54 #define TOR_TLS_IS_ERROR(rv) ((rv) < TOR_TLS_CLOSE)
  55
  56 #ifdef TORTLS_PRIVATE
  57 #define TOR_TLS_MAGIC 0x71571571
  58
  59 typedef enum {
  60     TOR_TLS_ST_HANDSHAKE, TOR_TLS_ST_OPEN, TOR_TLS_ST_GOTCLOSE,
  61     TOR_TLS_ST_SENTCLOSE, TOR_TLS_ST_CLOSED, TOR_TLS_ST_RENEGOTIATE,
  62     TOR_TLS_ST_BUFFEREVENT
  63 } tor_tls_state_t;
  64 #define tor_tls_state_bitfield_t ENUM_BF(tor_tls_state_t)
  65
  66 struct x509_st;
  67 struct ssl_st;
  68 struct ssl_ctx_st;
  69 struct ssl_session_st;
  70
  71 /** Holds a SSL_CTX object and related state used to configure TLS
  72  * connections.
  73  */
  74 typedef struct tor_tls_context_t {
  75   int refcnt;
  76   struct ssl_ctx_st *ctx;
  77   tor_x509_cert_t *my_link_cert;
  78   tor_x509_cert_t *my_id_cert;
  79   tor_x509_cert_t *my_auth_cert;
  80   crypto_pk_t *link_key;
  81   crypto_pk_t *auth_key;
  82 } tor_tls_context_t;
  83
  84 /** Structure that we use for a single certificate. */
  85 struct tor_x509_cert_t {
  86   struct x509_st *cert;
  87   uint8_t *encoded;
  88   size_t encoded_len;
  89   unsigned pkey_digests_set : 1;
  90   common_digests_t cert_digests;
  91   common_digests_t pkey_digests;
  92 };
  93
  94 /** Holds a SSL object and its associated data.  Members are only
  95  * accessed from within tortls.c.
  96  */
  97 struct tor_tls_t {
  98   uint32_t magic;
  99   tor_tls_context_t *context; /** A link to the context object for this tls. */
 100   struct ssl_st *ssl; /**< An OpenSSL SSL object. */
 101   int socket; /**< The underlying file descriptor for this TLS connection. */
 102   char *address; /**< An address to log when describing this connection. */
 103   tor_tls_state_bitfield_t state : 3; /**< The current SSL state,
 104                                        * depending on which operations
 105                                        * have completed successfully. */
 106   unsigned int isServer:1; /**< True iff this is a server-side connection */
 107   unsigned int wasV2Handshake:1; /**< True iff the original handshake for
 108                                   * this connection used the updated version
 109                                   * of the connection protocol (client sends
 110                                   * different cipher list, server sends only
 111                                   * one certificate). */
 112   /** True iff we should call negotiated_callback when we're done reading. */
 113   unsigned int got_renegotiate:1;
 114   /** Return value from tor_tls_classify_client_ciphers, or 0 if we haven't
 115    * called that function yet. */
 116   int8_t client_cipher_list_type;
 117   /** Incremented every time we start the server side of a handshake. */
 118   uint8_t server_handshake_count;
 119   size_t wantwrite_n; /**< 0 normally, >0 if we returned wantwrite last
 120                        * time. */
 121   /** Last values retrieved from BIO_number_read()/write(); see
 122    * tor_tls_get_n_raw_bytes() for usage.
 123    */
 124   unsigned long last_write_count;
 125   unsigned long last_read_count;
 126   /** If set, a callback to invoke whenever the client tries to renegotiate
 127    * the handshake. */
 128   void (*negotiated_callback)(tor_tls_t *tls, void *arg);
 129   /** Argument to pass to negotiated_callback. */
 130   void *callback_arg;
 131 };
 132
 133 STATIC int tor_errno_to_tls_error(int e);
 134 STATIC int tor_tls_get_error(tor_tls_t *tls, int r, int extra,
 135                   const char *doing, int severity, int domain);
 136 STATIC tor_tls_t *tor_tls_get_by_ssl(const struct ssl_st *ssl);
 137 STATIC void tor_tls_allocate_tor_tls_object_ex_data_index(void);
 138 #ifdef TORTLS_OPENSSL_PRIVATE
 139 STATIC int always_accept_verify_cb(int preverify_ok, X509_STORE_CTX *x509_ctx);
 140 STATIC int tor_tls_classify_client_ciphers(const struct ssl_st *ssl,
 141                                            STACK_OF(SSL_CIPHER) *peer_ciphers);
 142 #endif
 143 STATIC int tor_tls_client_is_using_v2_ciphers(const struct ssl_st *ssl);
 144 MOCK_DECL(STATIC void, try_to_extract_certs_from_tls,
 145           (int severity, tor_tls_t *tls, struct x509_st **cert_out,
 146            struct x509_st **id_cert_out));
 147 #ifndef HAVE_SSL_SESSION_GET_MASTER_KEY
 148 STATIC size_t SSL_SESSION_get_master_key(struct ssl_session_st *s,
 149                                          uint8_t *out,
 150                                          size_t len);
 151 #endif
 152 STATIC void tor_tls_debug_state_callback(const struct ssl_st *ssl,
 153                                          int type, int val);
 154 STATIC void tor_tls_server_info_callback(const struct ssl_st *ssl,
 155                                          int type, int val);
 156 #ifdef TORTLS_OPENSSL_PRIVATE
 157 STATIC int tor_tls_session_secret_cb(struct ssl_st *ssl, void *secret,
 158                             int *secret_len,
 159                             STACK_OF(SSL_CIPHER) *peer_ciphers,
 160                             CONST_IF_OPENSSL_1_1_API SSL_CIPHER **cipher,
 161                             void *arg);
 162 STATIC int find_cipher_by_id(const SSL *ssl, const SSL_METHOD *m,
 163                              uint16_t cipher);
 164 #endif
 165 MOCK_DECL(STATIC struct x509_st *, tor_tls_create_certificate,
 166                                                    (crypto_pk_t *rsa,
 167                                                     crypto_pk_t *rsa_sign,
 168                                                     const char *cname,
 169                                                     const char *cname_sign,
 170                                                   unsigned int cert_lifetime));
 171 STATIC tor_tls_context_t *tor_tls_context_new(crypto_pk_t *identity,
 172                    unsigned int key_lifetime, unsigned flags, int is_client);
 173 MOCK_DECL(STATIC tor_x509_cert_t *, tor_x509_cert_new,
 174           (struct x509_st *x509_cert));
 175 STATIC int tor_tls_context_init_one(tor_tls_context_t **ppcontext,
 176                                     crypto_pk_t *identity,
 177                                     unsigned int key_lifetime,
 178                                     unsigned int flags,
 179                                     int is_client);
 180 STATIC void tls_log_errors(tor_tls_t *tls, int severity, int domain,
 181                            const char *doing);
 182
 183 #ifdef TOR_UNIT_TESTS
 184 extern int tor_tls_object_ex_data_index;
 185 extern tor_tls_context_t *server_tls_context;
 186 extern tor_tls_context_t *client_tls_context;
 187 extern uint16_t v2_cipher_list[];
 188 extern uint64_t total_bytes_written_over_tls;
 189 extern uint64_t total_bytes_written_by_tls;
 190
 191 STATIC tor_x509_cert_t *tor_x509_cert_replace_expiration(
 192                                                const tor_x509_cert_t *inp,
 193                                                time_t new_expiration_time,
 194                                                crypto_pk_t *signing_key);
 195 #endif
 196
 197 #endif /* endif TORTLS_PRIVATE */
 198
 199 tor_x509_cert_t *tor_x509_cert_dup(const tor_x509_cert_t *cert);
 200 const char *tor_tls_err_to_string(int err);
 201 void tor_tls_get_state_description(tor_tls_t *tls, char *buf, size_t sz);
 202
 203 void tor_tls_free_all(void);
 204
 205 #define TOR_TLS_CTX_IS_PUBLIC_SERVER (1u<<0)
 206 #define TOR_TLS_CTX_USE_ECDHE_P256   (1u<<1)
 207 #define TOR_TLS_CTX_USE_ECDHE_P224   (1u<<2)
 208
 209 int tor_tls_context_init(unsigned flags,
 210                          crypto_pk_t *client_identity,
 211                          crypto_pk_t *server_identity,
 212                          unsigned int key_lifetime);
 213 tor_tls_t *tor_tls_new(int sock, int is_server);
 214 void tor_tls_set_logged_address(tor_tls_t *tls, const char *address);
 215 void tor_tls_set_renegotiate_callback(tor_tls_t *tls,
 216                                       void (*cb)(tor_tls_t *, void *arg),
 217                                       void *arg);
 218 int tor_tls_is_server(tor_tls_t *tls);
 219 void tor_tls_free(tor_tls_t *tls);
 220 int tor_tls_peer_has_cert(tor_tls_t *tls);
 221 MOCK_DECL(tor_x509_cert_t *,tor_tls_get_peer_cert,(tor_tls_t *tls));
 222 int tor_tls_verify(int severity, tor_tls_t *tls, crypto_pk_t **identity);
 223 int tor_tls_check_lifetime(int severity,
 224                            tor_tls_t *tls, time_t now,
 225                            int past_tolerance,
 226                            int future_tolerance);
 227 MOCK_DECL(int, tor_tls_read, (tor_tls_t *tls, char *cp, size_t len));
 228 int tor_tls_write(tor_tls_t *tls, const char *cp, size_t n);
 229 int tor_tls_handshake(tor_tls_t *tls);
 230 int tor_tls_finish_handshake(tor_tls_t *tls);
 231 void tor_tls_unblock_renegotiation(tor_tls_t *tls);
 232 void tor_tls_block_renegotiation(tor_tls_t *tls);
 233 void tor_tls_assert_renegotiation_unblocked(tor_tls_t *tls);
 234 int tor_tls_shutdown(tor_tls_t *tls);
 235 int tor_tls_get_pending_bytes(tor_tls_t *tls);
 236 size_t tor_tls_get_forced_write_size(tor_tls_t *tls);
 237
 238 void tor_tls_get_n_raw_bytes(tor_tls_t *tls,
 239                              size_t *n_read, size_t *n_written);
 240
 241 int tor_tls_get_buffer_sizes(tor_tls_t *tls,
 242                               size_t *rbuf_capacity, size_t *rbuf_bytes,
 243                               size_t *wbuf_capacity, size_t *wbuf_bytes);
 244
 245 MOCK_DECL(double, tls_get_write_overhead_ratio, (void));
 246
 247 int tor_tls_used_v1_handshake(tor_tls_t *tls);
 248 int tor_tls_get_num_server_handshakes(tor_tls_t *tls);
 249 int tor_tls_server_got_renegotiate(tor_tls_t *tls);
 250 MOCK_DECL(int,tor_tls_get_tlssecrets,(tor_tls_t *tls, uint8_t *secrets_out));
 251 MOCK_DECL(int,tor_tls_export_key_material,(
 252                      tor_tls_t *tls, uint8_t *secrets_out,
 253                      const uint8_t *context,
 254                      size_t context_len,
 255                      const char *label));
 256
 257 /* Log and abort if there are unhandled TLS errors in OpenSSL's error stack.
 258  */
 259 #define check_no_tls_errors() check_no_tls_errors_(__FILE__,__LINE__)
 260
 261 void check_no_tls_errors_(const char *fname, int line);
 262 void tor_tls_log_one_error(tor_tls_t *tls, unsigned long err,
 263                            int severity, int domain, const char *doing);
 264
 265 void tor_x509_cert_free(tor_x509_cert_t *cert);
 266 tor_x509_cert_t *tor_x509_cert_decode(const uint8_t *certificate,
 267                             size_t certificate_len);
 268 void tor_x509_cert_get_der(const tor_x509_cert_t *cert,
 269                       const uint8_t **encoded_out, size_t *size_out);
 270 const common_digests_t *tor_x509_cert_get_id_digests(
 271                       const tor_x509_cert_t *cert);
 272 const common_digests_t *tor_x509_cert_get_cert_digests(
 273                       const tor_x509_cert_t *cert);
 274 int tor_tls_get_my_certs(int server,
 275                          const tor_x509_cert_t **link_cert_out,
 276                          const tor_x509_cert_t **id_cert_out);
 277 crypto_pk_t *tor_tls_get_my_client_auth_key(void);
 278 crypto_pk_t *tor_tls_cert_get_key(tor_x509_cert_t *cert);
 279 MOCK_DECL(int,tor_tls_cert_matches_key,(const tor_tls_t *tls,
 280                                         const tor_x509_cert_t *cert));
 281 int tor_tls_cert_is_valid(int severity,
 282                           const tor_x509_cert_t *cert,
 283                           const tor_x509_cert_t *signing_cert,
 284                           time_t now,
 285                           int check_rsa_1024);
 286 const char *tor_tls_get_ciphersuite_name(tor_tls_t *tls);
 287
 288 int evaluate_ecgroup_for_tls(const char *ecgroup);
 289
 290 #endif
 291