src/lib/tls/tortls.h

   1 /* Copyright (c) 2003, Roger Dingledine
   2  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   3  * Copyright (c) 2007-2021, 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 "lib/crypt_ops/crypto_rsa.h"
  15 #include "lib/testsupport/testsupport.h"
  16 #include "lib/net/nettypes.h"
  17
  18 /* Opaque structure to hold a TLS connection. */
  19 typedef struct tor_tls_t tor_tls_t;
  20
  21 #ifdef TORTLS_PRIVATE
  22 #ifdef ENABLE_OPENSSL
  23 struct ssl_st;
  24 struct ssl_ctx_st;
  25 struct ssl_session_st;
  26 typedef struct ssl_ctx_st tor_tls_context_impl_t;
  27 typedef struct ssl_st tor_tls_impl_t;
  28 #else /* !defined(ENABLE_OPENSSL) */
  29 struct PRFileDesc;
  30 typedef struct PRFileDesc tor_tls_context_impl_t;
  31 typedef struct PRFileDesc tor_tls_impl_t;
  32 #endif /* defined(ENABLE_OPENSSL) */
  33 #endif /* defined(TORTLS_PRIVATE) */
  34
  35 struct tor_x509_cert_t;
  36
  37 /* Possible return values for most tor_tls_* functions. */
  38 #define MIN_TOR_TLS_ERROR_VAL_     -9
  39 #define TOR_TLS_ERROR_MISC         -9
  40 /* Rename to unexpected close or something. XXXX */
  41 #define TOR_TLS_ERROR_IO           -8
  42 #define TOR_TLS_ERROR_CONNREFUSED  -7
  43 #define TOR_TLS_ERROR_CONNRESET    -6
  44 #define TOR_TLS_ERROR_NO_ROUTE     -5
  45 #define TOR_TLS_ERROR_TIMEOUT      -4
  46 #define TOR_TLS_CLOSE              -3
  47 #define TOR_TLS_WANTREAD           -2
  48 #define TOR_TLS_WANTWRITE          -1
  49 #define TOR_TLS_DONE                0
  50
  51 /** Collection of case statements for all TLS errors that are not due to
  52  * underlying IO failure. */
  53 #define CASE_TOR_TLS_ERROR_ANY_NONIO            \
  54   case TOR_TLS_ERROR_MISC:                      \
  55   case TOR_TLS_ERROR_CONNREFUSED:               \
  56   case TOR_TLS_ERROR_CONNRESET:                 \
  57   case TOR_TLS_ERROR_NO_ROUTE:                  \
  58   case TOR_TLS_ERROR_TIMEOUT
  59
  60 /** Use this macro in a switch statement to catch _any_ TLS error.  That way,
  61  * if more errors are added, your switches will still work. */
  62 #define CASE_TOR_TLS_ERROR_ANY                  \
  63   CASE_TOR_TLS_ERROR_ANY_NONIO:                 \
  64   case TOR_TLS_ERROR_IO
  65
  66 #define TOR_TLS_IS_ERROR(rv) ((rv) < TOR_TLS_CLOSE)
  67
  68 /** Holds a SSL_CTX object and related state used to configure TLS
  69  * connections.
  70  */
  71 typedef struct tor_tls_context_t tor_tls_context_t;
  72
  73 const char *tor_tls_err_to_string(int err);
  74 void tor_tls_get_state_description(tor_tls_t *tls, char *buf, size_t sz);
  75 void tor_tls_free_all(void);
  76
  77 #define TOR_TLS_CTX_IS_PUBLIC_SERVER (1u<<0)
  78 #define TOR_TLS_CTX_USE_ECDHE_P256   (1u<<1)
  79 #define TOR_TLS_CTX_USE_ECDHE_P224   (1u<<2)
  80
  81 void tor_tls_init(void);
  82 void tls_log_errors(tor_tls_t *tls, int severity, int domain,
  83                     const char *doing);
  84 const char *tor_tls_get_last_error_msg(const tor_tls_t *tls);
  85 int tor_tls_context_init(unsigned flags,
  86                          crypto_pk_t *client_identity,
  87                          crypto_pk_t *server_identity,
  88                          unsigned int key_lifetime);
  89 void tor_tls_context_incref(tor_tls_context_t *ctx);
  90 void tor_tls_context_decref(tor_tls_context_t *ctx);
  91 tor_tls_context_t *tor_tls_context_get(int is_server);
  92 tor_tls_t *tor_tls_new(tor_socket_t sock, int is_server);
  93 void tor_tls_set_logged_address(tor_tls_t *tls, const char *address);
  94 void tor_tls_set_renegotiate_callback(tor_tls_t *tls,
  95                                       void (*cb)(tor_tls_t *, void *arg),
  96                                       void *arg);
  97 int tor_tls_is_server(tor_tls_t *tls);
  98 void tor_tls_release_socket(tor_tls_t *tls);
  99 void tor_tls_free_(tor_tls_t *tls);
 100 #define tor_tls_free(tls) FREE_AND_NULL(tor_tls_t, tor_tls_free_, (tls))
 101 int tor_tls_peer_has_cert(tor_tls_t *tls);
 102 MOCK_DECL(struct tor_x509_cert_t *,tor_tls_get_peer_cert,(tor_tls_t *tls));
 103 MOCK_DECL(struct tor_x509_cert_t *,tor_tls_get_own_cert,(tor_tls_t *tls));
 104 int tor_tls_verify(int severity, tor_tls_t *tls, crypto_pk_t **identity);
 105 MOCK_DECL(int, tor_tls_read, (tor_tls_t *tls, char *cp, size_t len));
 106 int tor_tls_write(tor_tls_t *tls, const char *cp, size_t n);
 107 int tor_tls_handshake(tor_tls_t *tls);
 108 int tor_tls_finish_handshake(tor_tls_t *tls);
 109 void tor_tls_unblock_renegotiation(tor_tls_t *tls);
 110 void tor_tls_block_renegotiation(tor_tls_t *tls);
 111 int tor_tls_get_pending_bytes(tor_tls_t *tls);
 112 size_t tor_tls_get_forced_write_size(tor_tls_t *tls);
 113
 114 void tor_tls_get_n_raw_bytes(tor_tls_t *tls,
 115                              size_t *n_read, size_t *n_written);
 116
 117 int tor_tls_get_buffer_sizes(tor_tls_t *tls,
 118                               size_t *rbuf_capacity, size_t *rbuf_bytes,
 119                               size_t *wbuf_capacity, size_t *wbuf_bytes);
 120
 121 MOCK_DECL(double, tls_get_write_overhead_ratio, (void));
 122
 123 int tor_tls_used_v1_handshake(tor_tls_t *tls);
 124 int tor_tls_get_num_server_handshakes(tor_tls_t *tls);
 125 int tor_tls_server_got_renegotiate(tor_tls_t *tls);
 126 MOCK_DECL(int,tor_tls_cert_matches_key,(const tor_tls_t *tls,
 127                                         const struct tor_x509_cert_t *cert));
 128 MOCK_DECL(int,tor_tls_get_tlssecrets,(tor_tls_t *tls, uint8_t *secrets_out));
 129 #ifdef ENABLE_OPENSSL
 130 /* OpenSSL lets us see these master secrets; NSS sensibly does not. */
 131 #define HAVE_WORKING_TOR_TLS_GET_TLSSECRETS
 132 #endif
 133 MOCK_DECL(int,tor_tls_export_key_material,(
 134                      tor_tls_t *tls, uint8_t *secrets_out,
 135                      const uint8_t *context,
 136                      size_t context_len,
 137                      const char *label));
 138
 139 #ifdef ENABLE_OPENSSL
 140 /* Log and abort if there are unhandled TLS errors in OpenSSL's error stack.
 141  */
 142 #define check_no_tls_errors() check_no_tls_errors_(__FILE__,__LINE__)
 143 void check_no_tls_errors_(const char *fname, int line);
 144
 145 void tor_tls_log_one_error(tor_tls_t *tls, unsigned long err,
 146                            int severity, int domain, const char *doing);
 147 #else /* !defined(ENABLE_OPENSSL) */
 148 #define check_no_tls_errors() STMT_NIL
 149 #endif /* defined(ENABLE_OPENSSL) */
 150
 151 int tor_tls_get_my_certs(int server,
 152                          const struct tor_x509_cert_t **link_cert_out,
 153                          const struct tor_x509_cert_t **id_cert_out);
 154 crypto_pk_t *tor_tls_get_my_client_auth_key(void);
 155
 156 const char *tor_tls_get_ciphersuite_name(tor_tls_t *tls);
 157
 158 int evaluate_ecgroup_for_tls(const char *ecgroup);
 159
 160 #endif /* !defined(TOR_TORTLS_H) */