1 /* Copyright (c) 2003, Roger Dingledine
2 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
3 * Copyright (c) 2007-2016, The Tor Project, Inc. */
4 /* See LICENSE for licensing information */
11 * \brief Headers for tortls.c
15 #include "compat_openssl.h"
17 #include "testsupport.h"
19 /* Opaque structure to hold a TLS connection. */
20 typedef struct tor_tls_t tor_tls_t
;
22 /* Opaque structure to hold an X509 certificate. */
23 typedef struct tor_x509_cert_t tor_x509_cert_t
;
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
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
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: \
54 #define TOR_TLS_IS_ERROR(rv) ((rv) < TOR_TLS_CLOSE)
57 #define TOR_TLS_MAGIC 0x71571571
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
64 #define tor_tls_state_bitfield_t ENUM_BF(tor_tls_state_t)
66 /** Holds a SSL_CTX object and related state used to configure TLS
69 typedef struct tor_tls_context_t
{
72 tor_x509_cert_t
*my_link_cert
;
73 tor_x509_cert_t
*my_id_cert
;
74 tor_x509_cert_t
*my_auth_cert
;
75 crypto_pk_t
*link_key
;
76 crypto_pk_t
*auth_key
;
79 /** Structure that we use for a single certificate. */
80 struct tor_x509_cert_t
{
84 unsigned pkey_digests_set
: 1;
85 common_digests_t cert_digests
;
86 common_digests_t pkey_digests
;
89 /** Holds a SSL object and its associated data. Members are only
90 * accessed from within tortls.c.
94 tor_tls_context_t
*context
; /** A link to the context object for this tls. */
95 SSL
*ssl
; /**< An OpenSSL SSL object. */
96 int socket
; /**< The underlying file descriptor for this TLS connection. */
97 char *address
; /**< An address to log when describing this connection. */
98 tor_tls_state_bitfield_t state
: 3; /**< The current SSL state,
99 * depending on which operations
100 * have completed successfully. */
101 unsigned int isServer
:1; /**< True iff this is a server-side connection */
102 unsigned int wasV2Handshake
:1; /**< True iff the original handshake for
103 * this connection used the updated version
104 * of the connection protocol (client sends
105 * different cipher list, server sends only
106 * one certificate). */
107 /** True iff we should call negotiated_callback when we're done reading. */
108 unsigned int got_renegotiate
:1;
109 /** Return value from tor_tls_classify_client_ciphers, or 0 if we haven't
110 * called that function yet. */
111 int8_t client_cipher_list_type
;
112 /** Incremented every time we start the server side of a handshake. */
113 uint8_t server_handshake_count
;
114 size_t wantwrite_n
; /**< 0 normally, >0 if we returned wantwrite last
116 /** Last values retrieved from BIO_number_read()/write(); see
117 * tor_tls_get_n_raw_bytes() for usage.
119 unsigned long last_write_count
;
120 unsigned long last_read_count
;
121 /** If set, a callback to invoke whenever the client tries to renegotiate
123 void (*negotiated_callback
)(tor_tls_t
*tls
, void *arg
);
124 /** Argument to pass to negotiated_callback. */
128 STATIC
int tor_errno_to_tls_error(int e
);
129 STATIC
int tor_tls_get_error(tor_tls_t
*tls
, int r
, int extra
,
130 const char *doing
, int severity
, int domain
);
131 STATIC tor_tls_t
*tor_tls_get_by_ssl(const SSL
*ssl
);
132 STATIC
void tor_tls_allocate_tor_tls_object_ex_data_index(void);
133 STATIC
int always_accept_verify_cb(int preverify_ok
, X509_STORE_CTX
*x509_ctx
);
134 STATIC
int tor_tls_classify_client_ciphers(const SSL
*ssl
,
135 STACK_OF(SSL_CIPHER
) *peer_ciphers
);
136 STATIC
int tor_tls_client_is_using_v2_ciphers(const SSL
*ssl
);
137 MOCK_DECL(STATIC
void, try_to_extract_certs_from_tls
,
138 (int severity
, tor_tls_t
*tls
, X509
**cert_out
, X509
**id_cert_out
));
139 #ifndef HAVE_SSL_SESSION_GET_MASTER_KEY
140 STATIC
size_t SSL_SESSION_get_master_key(SSL_SESSION
*s
, uint8_t *out
,
143 STATIC
void tor_tls_debug_state_callback(const SSL
*ssl
, int type
, int val
);
144 STATIC
void tor_tls_server_info_callback(const SSL
*ssl
, int type
, int val
);
145 STATIC
int tor_tls_session_secret_cb(SSL
*ssl
, void *secret
,
147 STACK_OF(SSL_CIPHER
) *peer_ciphers
,
148 CONST_IF_OPENSSL_1_1_API SSL_CIPHER
**cipher
,
150 STATIC
int find_cipher_by_id(const SSL
*ssl
, const SSL_METHOD
*m
,
152 MOCK_DECL(STATIC X509
*, tor_tls_create_certificate
,(crypto_pk_t
*rsa
,
153 crypto_pk_t
*rsa_sign
,
155 const char *cname_sign
,
156 unsigned int cert_lifetime
));
157 STATIC tor_tls_context_t
*tor_tls_context_new(crypto_pk_t
*identity
,
158 unsigned int key_lifetime
, unsigned flags
, int is_client
);
159 MOCK_DECL(STATIC tor_x509_cert_t
*, tor_x509_cert_new
,(X509
*x509_cert
));
160 STATIC
int tor_tls_context_init_one(tor_tls_context_t
**ppcontext
,
161 crypto_pk_t
*identity
,
162 unsigned int key_lifetime
,
165 STATIC
void tls_log_errors(tor_tls_t
*tls
, int severity
, int domain
,
168 #ifdef TOR_UNIT_TESTS
169 extern int tor_tls_object_ex_data_index
;
170 extern tor_tls_context_t
*server_tls_context
;
171 extern tor_tls_context_t
*client_tls_context
;
172 extern uint16_t v2_cipher_list
[];
173 extern uint64_t total_bytes_written_over_tls
;
174 extern uint64_t total_bytes_written_by_tls
;
177 #endif /* endif TORTLS_PRIVATE */
179 tor_x509_cert_t
*tor_x509_cert_dup(const tor_x509_cert_t
*cert
);
180 const char *tor_tls_err_to_string(int err
);
181 void tor_tls_get_state_description(tor_tls_t
*tls
, char *buf
, size_t sz
);
183 void tor_tls_free_all(void);
185 #define TOR_TLS_CTX_IS_PUBLIC_SERVER (1u<<0)
186 #define TOR_TLS_CTX_USE_ECDHE_P256 (1u<<1)
187 #define TOR_TLS_CTX_USE_ECDHE_P224 (1u<<2)
189 int tor_tls_context_init(unsigned flags
,
190 crypto_pk_t
*client_identity
,
191 crypto_pk_t
*server_identity
,
192 unsigned int key_lifetime
);
193 tor_tls_t
*tor_tls_new(int sock
, int is_server
);
194 void tor_tls_set_logged_address(tor_tls_t
*tls
, const char *address
);
195 void tor_tls_set_renegotiate_callback(tor_tls_t
*tls
,
196 void (*cb
)(tor_tls_t
*, void *arg
),
198 int tor_tls_is_server(tor_tls_t
*tls
);
199 void tor_tls_free(tor_tls_t
*tls
);
200 int tor_tls_peer_has_cert(tor_tls_t
*tls
);
201 MOCK_DECL(tor_x509_cert_t
*,tor_tls_get_peer_cert
,(tor_tls_t
*tls
));
202 int tor_tls_verify(int severity
, tor_tls_t
*tls
, crypto_pk_t
**identity
);
203 int tor_tls_check_lifetime(int severity
,
204 tor_tls_t
*tls
, time_t now
,
206 int future_tolerance
);
207 MOCK_DECL(int, tor_tls_read
, (tor_tls_t
*tls
, char *cp
, size_t len
));
208 int tor_tls_write(tor_tls_t
*tls
, const char *cp
, size_t n
);
209 int tor_tls_handshake(tor_tls_t
*tls
);
210 int tor_tls_finish_handshake(tor_tls_t
*tls
);
211 void tor_tls_unblock_renegotiation(tor_tls_t
*tls
);
212 void tor_tls_block_renegotiation(tor_tls_t
*tls
);
213 void tor_tls_assert_renegotiation_unblocked(tor_tls_t
*tls
);
214 int tor_tls_shutdown(tor_tls_t
*tls
);
215 int tor_tls_get_pending_bytes(tor_tls_t
*tls
);
216 size_t tor_tls_get_forced_write_size(tor_tls_t
*tls
);
218 void tor_tls_get_n_raw_bytes(tor_tls_t
*tls
,
219 size_t *n_read
, size_t *n_written
);
221 int tor_tls_get_buffer_sizes(tor_tls_t
*tls
,
222 size_t *rbuf_capacity
, size_t *rbuf_bytes
,
223 size_t *wbuf_capacity
, size_t *wbuf_bytes
);
225 MOCK_DECL(double, tls_get_write_overhead_ratio
, (void));
227 int tor_tls_used_v1_handshake(tor_tls_t
*tls
);
228 int tor_tls_get_num_server_handshakes(tor_tls_t
*tls
);
229 int tor_tls_server_got_renegotiate(tor_tls_t
*tls
);
230 MOCK_DECL(int,tor_tls_get_tlssecrets
,(tor_tls_t
*tls
, uint8_t *secrets_out
));
231 MOCK_DECL(int,tor_tls_export_key_material
,(
232 tor_tls_t
*tls
, uint8_t *secrets_out
,
233 const uint8_t *context
,
237 /* Log and abort if there are unhandled TLS errors in OpenSSL's error stack.
239 #define check_no_tls_errors() check_no_tls_errors_(__FILE__,__LINE__)
241 void check_no_tls_errors_(const char *fname
, int line
);
242 void tor_tls_log_one_error(tor_tls_t
*tls
, unsigned long err
,
243 int severity
, int domain
, const char *doing
);
245 void tor_x509_cert_free(tor_x509_cert_t
*cert
);
246 tor_x509_cert_t
*tor_x509_cert_decode(const uint8_t *certificate
,
247 size_t certificate_len
);
248 void tor_x509_cert_get_der(const tor_x509_cert_t
*cert
,
249 const uint8_t **encoded_out
, size_t *size_out
);
250 const common_digests_t
*tor_x509_cert_get_id_digests(
251 const tor_x509_cert_t
*cert
);
252 const common_digests_t
*tor_x509_cert_get_cert_digests(
253 const tor_x509_cert_t
*cert
);
254 int tor_tls_get_my_certs(int server
,
255 const tor_x509_cert_t
**link_cert_out
,
256 const tor_x509_cert_t
**id_cert_out
);
257 crypto_pk_t
*tor_tls_get_my_client_auth_key(void);
258 crypto_pk_t
*tor_tls_cert_get_key(tor_x509_cert_t
*cert
);
259 MOCK_DECL(int,tor_tls_cert_matches_key
,(const tor_tls_t
*tls
,
260 const tor_x509_cert_t
*cert
));
261 int tor_tls_cert_is_valid(int severity
,
262 const tor_x509_cert_t
*cert
,
263 const tor_x509_cert_t
*signing_cert
,
266 const char *tor_tls_get_ciphersuite_name(tor_tls_t
*tls
);
268 int evaluate_ecgroup_for_tls(const char *ecgroup
);