src/common/tortls.h

   1 /* Copyright (c) 2003, Roger Dingledine
   2  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   3  * Copyright (c) 2007-2013, 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.h"
  16 #include "testsupport.h"
  17
  18 /* Opaque structure to hold a TLS connection. */
  19 typedef struct tor_tls_t tor_tls_t;
  20
  21 /* Opaque structure to hold an X509 certificate. */
  22 typedef struct tor_cert_t tor_cert_t;
  23
  24 /* Possible return values for most tor_tls_* functions. */
  25 #define MIN_TOR_TLS_ERROR_VAL_     -9
  26 #define TOR_TLS_ERROR_MISC         -9
  27 /* Rename to unexpected close or something. XXXX */
  28 #define TOR_TLS_ERROR_IO           -8
  29 #define TOR_TLS_ERROR_CONNREFUSED  -7
  30 #define TOR_TLS_ERROR_CONNRESET    -6
  31 #define TOR_TLS_ERROR_NO_ROUTE     -5
  32 #define TOR_TLS_ERROR_TIMEOUT      -4
  33 #define TOR_TLS_CLOSE              -3
  34 #define TOR_TLS_WANTREAD           -2
  35 #define TOR_TLS_WANTWRITE          -1
  36 #define TOR_TLS_DONE                0
  37
  38 /** Collection of case statements for all TLS errors that are not due to
  39  * underlying IO failure. */
  40 #define CASE_TOR_TLS_ERROR_ANY_NONIO            \
  41   case TOR_TLS_ERROR_MISC:                      \
  42   case TOR_TLS_ERROR_CONNREFUSED:               \
  43   case TOR_TLS_ERROR_CONNRESET:                 \
  44   case TOR_TLS_ERROR_NO_ROUTE:                  \
  45   case TOR_TLS_ERROR_TIMEOUT
  46
  47 /** Use this macro in a switch statement to catch _any_ TLS error.  That way,
  48  * if more errors are added, your switches will still work. */
  49 #define CASE_TOR_TLS_ERROR_ANY                  \
  50   CASE_TOR_TLS_ERROR_ANY_NONIO:                 \
  51   case TOR_TLS_ERROR_IO
  52
  53 #define TOR_TLS_IS_ERROR(rv) ((rv) < TOR_TLS_CLOSE)
  54 const char *tor_tls_err_to_string(int err);
  55 void tor_tls_get_state_description(tor_tls_t *tls, char *buf, size_t sz);
  56
  57 void tor_tls_free_all(void);
  58
  59 #define TOR_TLS_CTX_IS_PUBLIC_SERVER (1u<<0)
  60 #define TOR_TLS_CTX_USE_ECDHE_P256   (1u<<1)
  61 #define TOR_TLS_CTX_USE_ECDHE_P224   (1u<<2)
  62
  63 int tor_tls_context_init(unsigned flags,
  64                          crypto_pk_t *client_identity,
  65                          crypto_pk_t *server_identity,
  66                          unsigned int key_lifetime);
  67 tor_tls_t *tor_tls_new(int sock, int is_server);
  68 void tor_tls_set_logged_address(tor_tls_t *tls, const char *address);
  69 void tor_tls_set_renegotiate_callback(tor_tls_t *tls,
  70                                       void (*cb)(tor_tls_t *, void *arg),
  71                                       void *arg);
  72 int tor_tls_is_server(tor_tls_t *tls);
  73 void tor_tls_free(tor_tls_t *tls);
  74 int tor_tls_peer_has_cert(tor_tls_t *tls);
  75 tor_cert_t *tor_tls_get_peer_cert(tor_tls_t *tls);
  76 int tor_tls_verify(int severity, tor_tls_t *tls, crypto_pk_t **identity);
  77 int tor_tls_check_lifetime(int severity,
  78                            tor_tls_t *tls, int past_tolerance,
  79                            int future_tolerance);
  80 int tor_tls_read(tor_tls_t *tls, char *cp, size_t len);
  81 int tor_tls_write(tor_tls_t *tls, const char *cp, size_t n);
  82 int tor_tls_handshake(tor_tls_t *tls);
  83 int tor_tls_finish_handshake(tor_tls_t *tls);
  84 int tor_tls_renegotiate(tor_tls_t *tls);
  85 void tor_tls_unblock_renegotiation(tor_tls_t *tls);
  86 void tor_tls_block_renegotiation(tor_tls_t *tls);
  87 void tor_tls_assert_renegotiation_unblocked(tor_tls_t *tls);
  88 int tor_tls_shutdown(tor_tls_t *tls);
  89 int tor_tls_get_pending_bytes(tor_tls_t *tls);
  90 size_t tor_tls_get_forced_write_size(tor_tls_t *tls);
  91
  92 void tor_tls_get_n_raw_bytes(tor_tls_t *tls,
  93                              size_t *n_read, size_t *n_written);
  94
  95 void tor_tls_get_buffer_sizes(tor_tls_t *tls,
  96                               size_t *rbuf_capacity, size_t *rbuf_bytes,
  97                               size_t *wbuf_capacity, size_t *wbuf_bytes);
  98
  99 MOCK_DECL(double, tls_get_write_overhead_ratio, (void));
 100
 101 int tor_tls_used_v1_handshake(tor_tls_t *tls);
 102 int tor_tls_received_v3_certificate(tor_tls_t *tls);
 103 int tor_tls_get_num_server_handshakes(tor_tls_t *tls);
 104 int tor_tls_server_got_renegotiate(tor_tls_t *tls);
 105 int tor_tls_get_tlssecrets(tor_tls_t *tls, uint8_t *secrets_out);
 106
 107 /* Log and abort if there are unhandled TLS errors in OpenSSL's error stack.
 108  */
 109 #define check_no_tls_errors() check_no_tls_errors_(__FILE__,__LINE__)
 110
 111 void check_no_tls_errors_(const char *fname, int line);
 112 void tor_tls_log_one_error(tor_tls_t *tls, unsigned long err,
 113                            int severity, int domain, const char *doing);
 114
 115 #ifdef USE_BUFFEREVENTS
 116 int tor_tls_start_renegotiating(tor_tls_t *tls);
 117 struct bufferevent *tor_tls_init_bufferevent(tor_tls_t *tls,
 118                                      struct bufferevent *bufev_in,
 119                                       evutil_socket_t socket, int receiving,
 120                                      int filter);
 121 #endif
 122
 123 void tor_cert_free(tor_cert_t *cert);
 124 tor_cert_t *tor_cert_decode(const uint8_t *certificate,
 125                             size_t certificate_len);
 126 void tor_cert_get_der(const tor_cert_t *cert,
 127                       const uint8_t **encoded_out, size_t *size_out);
 128 const digests_t *tor_cert_get_id_digests(const tor_cert_t *cert);
 129 const digests_t *tor_cert_get_cert_digests(const tor_cert_t *cert);
 130 int tor_tls_get_my_certs(int server,
 131                          const tor_cert_t **link_cert_out,
 132                          const tor_cert_t **id_cert_out);
 133 crypto_pk_t *tor_tls_get_my_client_auth_key(void);
 134 crypto_pk_t *tor_tls_cert_get_key(tor_cert_t *cert);
 135 int tor_tls_cert_matches_key(const tor_tls_t *tls, const tor_cert_t *cert);
 136 int tor_tls_cert_is_valid(int severity,
 137                           const tor_cert_t *cert,
 138                           const tor_cert_t *signing_cert,
 139                           int check_rsa_1024);
 140 const char *tor_tls_get_ciphersuite_name(tor_tls_t *tls);
 141
 142 #endif
 143