tortls.h File Reference

Headers for tortls.c. More...

#include "crypto_rsa.h"
#include "compat_openssl.h"
#include "compat.h"
#include "testsupport.h"

Include dependency graph for tortls.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	MIN_TOR_TLS_ERROR_VAL_   -9
#define	TOR_TLS_ERROR_MISC   -9
#define	TOR_TLS_ERROR_IO   -8
#define	TOR_TLS_ERROR_CONNREFUSED   -7
#define	TOR_TLS_ERROR_CONNRESET   -6
#define	TOR_TLS_ERROR_NO_ROUTE   -5
#define	TOR_TLS_ERROR_TIMEOUT   -4
#define	TOR_TLS_CLOSE   -3
#define	TOR_TLS_WANTREAD   -2
#define	TOR_TLS_WANTWRITE   -1
#define	TOR_TLS_DONE   0
#define	CASE_TOR_TLS_ERROR_ANY_NONIO
#define	CASE_TOR_TLS_ERROR_ANY
#define	TOR_TLS_IS_ERROR(rv)   ((rv) < TOR_TLS_CLOSE)
#define	TOR_TLS_CTX_IS_PUBLIC_SERVER   (1u<<0)
#define	TOR_TLS_CTX_USE_ECDHE_P256   (1u<<1)
#define	TOR_TLS_CTX_USE_ECDHE_P224   (1u<<2)
#define	tor_tls_free(tls)   FREE_AND_NULL(tor_tls_t, tor_tls_free_, (tls))
#define	check_no_tls_errors()   check_no_tls_errors_(__FILE__,__LINE__)
#define	tor_x509_cert_free(c)   FREE_AND_NULL(tor_x509_cert_t, tor_x509_cert_free_, (c))

Typedefs
typedef struct tor_tls_t	tor_tls_t
typedef struct tor_x509_cert_t	tor_x509_cert_t

Functions
tor_x509_cert_t *	tor_x509_cert_dup (const tor_x509_cert_t *cert)
const char *	tor_tls_err_to_string (int err)
void	tor_tls_get_state_description (tor_tls_t *tls, char *buf, size_t sz)
void	tor_tls_free_all (void)
int	tor_tls_context_init (unsigned flags, crypto_pk_t *client_identity, crypto_pk_t *server_identity, unsigned int key_lifetime)
tor_tls_t *	tor_tls_new (int sock, int is_server)
void	tor_tls_set_logged_address (tor_tls_t *tls, const char *address)
void	tor_tls_set_renegotiate_callback (tor_tls_t *tls, void(*cb)(tor_tls_t *, void *arg), void *arg)
int	tor_tls_is_server (tor_tls_t *tls)
void	tor_tls_free_ (tor_tls_t *tls)
int	tor_tls_peer_has_cert (tor_tls_t *tls)
	MOCK_DECL (tor_x509_cert_t *, tor_tls_get_peer_cert,(tor_tls_t *tls))
	MOCK_DECL (tor_x509_cert_t *, tor_tls_get_own_cert,(tor_tls_t *tls))
int	tor_tls_verify (int severity, tor_tls_t *tls, crypto_pk_t **identity)
int	tor_tls_check_lifetime (int severity, tor_tls_t *tls, time_t now, int past_tolerance, int future_tolerance)
	MOCK_DECL (int, tor_tls_read,(tor_tls_t *tls, char *cp, size_t len))
int	tor_tls_write (tor_tls_t *tls, const char *cp, size_t n)
int	tor_tls_handshake (tor_tls_t *tls)
int	tor_tls_finish_handshake (tor_tls_t *tls)
void	tor_tls_unblock_renegotiation (tor_tls_t *tls)
void	tor_tls_block_renegotiation (tor_tls_t *tls)
void	tor_tls_assert_renegotiation_unblocked (tor_tls_t *tls)
int	tor_tls_shutdown (tor_tls_t *tls)
int	tor_tls_get_pending_bytes (tor_tls_t *tls)
size_t	tor_tls_get_forced_write_size (tor_tls_t *tls)
void	tor_tls_get_n_raw_bytes (tor_tls_t *tls, size_t *n_read, size_t *n_written)
int	tor_tls_get_buffer_sizes (tor_tls_t *tls, size_t *rbuf_capacity, size_t *rbuf_bytes, size_t *wbuf_capacity, size_t *wbuf_bytes)
	MOCK_DECL (double, tls_get_write_overhead_ratio,(void))
int	tor_tls_used_v1_handshake (tor_tls_t *tls)
int	tor_tls_get_num_server_handshakes (tor_tls_t *tls)
int	tor_tls_server_got_renegotiate (tor_tls_t *tls)
	MOCK_DECL (int, tor_tls_get_tlssecrets,(tor_tls_t *tls, uint8_t *secrets_out))
	MOCK_DECL (int, tor_tls_export_key_material,(tor_tls_t *tls, uint8_t *secrets_out, const uint8_t *context, size_t context_len, const char *label))
void	check_no_tls_errors_ (const char *fname, int line)
void	tor_tls_log_one_error (tor_tls_t *tls, unsigned long err, int severity, int domain, const char *doing)
void	tor_x509_cert_free_ (tor_x509_cert_t *cert)
tor_x509_cert_t *	tor_x509_cert_decode (const uint8_t *certificate, size_t certificate_len)
void	tor_x509_cert_get_der (const tor_x509_cert_t *cert, const uint8_t **encoded_out, size_t *size_out)
const common_digests_t *	tor_x509_cert_get_id_digests (const tor_x509_cert_t *cert)
const common_digests_t *	tor_x509_cert_get_cert_digests (const tor_x509_cert_t *cert)
int	tor_tls_get_my_certs (int server, const tor_x509_cert_t **link_cert_out, const tor_x509_cert_t **id_cert_out)
crypto_pk_t *	tor_tls_get_my_client_auth_key (void)
crypto_pk_t *	tor_tls_cert_get_key (tor_x509_cert_t *cert)
	MOCK_DECL (int, tor_tls_cert_matches_key,(const tor_tls_t *tls, const tor_x509_cert_t *cert))
int	tor_tls_cert_is_valid (int severity, const tor_x509_cert_t *cert, const tor_x509_cert_t *signing_cert, time_t now, int check_rsa_1024)
const char *	tor_tls_get_ciphersuite_name (tor_tls_t *tls)
int	evaluate_ecgroup_for_tls (const char *ecgroup)

Detailed Description

Headers for tortls.c.

Macro Definition Documentation

CASE_TOR_TLS_ERROR_ANY

#define CASE_TOR_TLS_ERROR_ANY

Value:

CASE_TOR_TLS_ERROR_ANY_NONIO:                 \
  case TOR_TLS_ERROR_IO

Use this macro in a switch statement to catch any TLS error. That way, if more errors are added, your switches will still work.

CASE_TOR_TLS_ERROR_ANY_NONIO

#define CASE_TOR_TLS_ERROR_ANY_NONIO

Value:

case TOR_TLS_ERROR_MISC:                      \
  case TOR_TLS_ERROR_CONNREFUSED:               \
  case TOR_TLS_ERROR_CONNRESET:                 \
  case TOR_TLS_ERROR_NO_ROUTE:                  \
  case TOR_TLS_ERROR_TIMEOUT

Collection of case statements for all TLS errors that are not due to underlying IO failure.

Function Documentation

check_no_tls_errors_()

void check_no_tls_errors_	(	const char *	fname,
		int	line
	)

Implement check_no_tls_errors: If there are any pending OpenSSL errors, log an error message.

evaluate_ecgroup_for_tls()

int evaluate_ecgroup_for_tls

(

const char *

ecgroup

)

Check whether the ECC group requested is supported by the current OpenSSL library instance. Return 1 if the group is supported, and 0 if not.

tor_tls_assert_renegotiation_unblocked()

void tor_tls_assert_renegotiation_unblocked

(

tor_tls_t *

tls

)

Assert that the flags that allow legacy renegotiation are still set

tor_tls_block_renegotiation()

void tor_tls_block_renegotiation

(

tor_tls_t *

tls

)

If this version of openssl supports it, turn off renegotiation on tls. (Our protocol never requires this for security, but it's nice to use belt-and-suspenders here.)

Here is the caller graph for this function:

tor_tls_cert_get_key()

crypto_pk_t* tor_tls_cert_get_key

(

tor_x509_cert_t *

cert

)

Return a newly allocated copy of the public key that a certificate certifies. Watch out! This returns NULL if the cert's key is not RSA.

Here is the call graph for this function:

tor_tls_cert_is_valid()

int tor_tls_cert_is_valid	(	int	severity,
		const tor_x509_cert_t *	cert,
		const tor_x509_cert_t *	signing_cert,
		time_t	now,
		int	check_rsa_1024
	)

Check whether cert is well-formed, currently live, and correctly signed by the public key in signing_cert. If check_rsa_1024, make sure that it has an RSA key with 1024 bits; otherwise, just check that the key is long enough. Return 1 if the cert is good, and 0 if it's bad or we couldn't check it.

tor_tls_check_lifetime()

int tor_tls_check_lifetime	(	int	severity,
		tor_tls_t *	tls,
		time_t	now,
		int	past_tolerance,
		int	future_tolerance
	)

Check whether the certificate set on the connection tls is expired give or take past_tolerance seconds, or not-yet-valid give or take future_tolerance seconds. Return 0 for valid, -1 for failure.

NOTE: you should call tor_tls_verify before tor_tls_check_lifetime.

tor_tls_context_init()

int tor_tls_context_init	(	unsigned	flags,
		crypto_pk_t *	client_identity,
		crypto_pk_t *	server_identity,
		unsigned int	key_lifetime
	)

Create new global client and server TLS contexts.

If server_identity is NULL, this will not generate a server TLS context. If TOR_TLS_CTX_IS_PUBLIC_SERVER is set in flags, use the same TLS context for incoming and outgoing connections, and ignore client_identity. If one of TOR_TLS_CTX_USE_ECDHE_P{224,256} is set in flags, use that ECDHE group if possible; otherwise use the default ECDHE group.

tor_tls_err_to_string()

const char* tor_tls_err_to_string

(

int

err

)

Given a TOR_TLS_* error code, return a string equivalent.

tor_tls_finish_handshake()

int tor_tls_finish_handshake

(

tor_tls_t *

tls

)

Perform the final part of the initial TLS handshake on tls. This should be called for the first handshake only: it determines whether the v1 or the v2 handshake was used, and adjusts things for the renegotiation handshake as appropriate.

tor_tls_handshake() calls this on its own; you only need to call this if bufferevent is doing the handshake for you.

tor_tls_free_()

void tor_tls_free_

(

tor_tls_t *

tls

)

Release resources associated with a TLS object. Does not close the underlying file descriptor.

Here is the call graph for this function:

tor_tls_free_all()

void tor_tls_free_all

(

void

)

Free all global TLS structures.

tor_tls_get_buffer_sizes()

int tor_tls_get_buffer_sizes	(	tor_tls_t *	tls,
		size_t *	rbuf_capacity,
		size_t *	rbuf_bytes,
		size_t *	wbuf_capacity,
		size_t *	wbuf_bytes
	)

Examine the amount of memory used and available for buffers in tls. Set *rbuf_capacity to the amount of storage allocated for the read buffer and *rbuf_bytes to the amount actually used. Set *wbuf_capacity to the amount of storage allocated for the write buffer and *wbuf_bytes to the amount actually used.

Return 0 on success, -1 on failure.

tor_tls_get_forced_write_size()

size_t tor_tls_get_forced_write_size

(

tor_tls_t *

tls

)

If tls requires that the next write be of a particular size, return that size. Otherwise, return 0.

tor_tls_get_my_certs()

int tor_tls_get_my_certs	(	int	server,
		const tor_x509_cert_t **	link_cert_out,
		const tor_x509_cert_t **	id_cert_out
	)

Set *link_cert_out and *id_cert_out to the link certificate and ID certificate that we're currently using for our V3 in-protocol handshake's certificate chain. If server is true, provide the certs that we use in server mode (auth, ID); otherwise, provide the certs that we use in client mode. (link, ID)

Here is the caller graph for this function:

tor_tls_get_my_client_auth_key()

crypto_pk_t* tor_tls_get_my_client_auth_key

(

void

)

Return the authentication key that we use to authenticate ourselves as a client in the V3 in-protocol handshake.

Here is the caller graph for this function:

tor_tls_get_n_raw_bytes()

void tor_tls_get_n_raw_bytes	(	tor_tls_t *	tls,
		size_t *	n_read,
		size_t *	n_written
	)

Sets n_read and n_written to the number of bytes read and written, respectively, on the raw socket used by tls since the last time this function was called on tls.

Here is the caller graph for this function:

tor_tls_get_num_server_handshakes()

int tor_tls_get_num_server_handshakes

(

tor_tls_t *

tls

)

Return the number of server handshakes that we've noticed doing on tls.

tor_tls_get_pending_bytes()

int tor_tls_get_pending_bytes

(

tor_tls_t *

tls

)

Return the number of bytes available for reading from tls.

tor_tls_get_state_description()

void tor_tls_get_state_description	(	tor_tls_t *	tls,
		char *	buf,
		size_t	sz
	)

Write a description of the current state of tls into the sz-byte buffer at buf.

tor_tls_handshake()

int tor_tls_handshake

(

tor_tls_t *

tls

)

Perform initial handshake on tls. When finished, returns TOR_TLS_DONE. On failure, returns TOR_TLS_ERROR, TOR_TLS_WANTREAD, or TOR_TLS_WANTWRITE.

tor_tls_is_server()

int tor_tls_is_server

(

tor_tls_t *

tls

)

Return whether this tls initiated the connect (client) or received it (server).

Here is the caller graph for this function:

tor_tls_log_one_error()

void tor_tls_log_one_error	(	tor_tls_t *	tls,
		unsigned long	err,
		int	severity,
		int	domain,
		const char *	doing
	)

Log a single error err as returned by ERR_get_error(), which was received while performing an operation doing on tls. Log the message at severity, in log domain domain.

Here is the call graph for this function:

Here is the caller graph for this function:

tor_tls_new()

tor_tls_t* tor_tls_new	(	int	sock,
		int	isServer
	)

Create a new TLS object from a file descriptor, and a flag to determine whether it is functioning as a server.

tor_tls_peer_has_cert()

int tor_tls_peer_has_cert

(

tor_tls_t *

tls

)

Return true iff this TLS connection is authenticated.

Here is the call graph for this function:

tor_tls_server_got_renegotiate()

int tor_tls_server_got_renegotiate

(

tor_tls_t *

tls

)

Return true iff the server TLS connection tls got the renegotiation request it was waiting for.

tor_tls_set_logged_address()

void tor_tls_set_logged_address	(	tor_tls_t *	tls,
		const char *	address
	)

Make future log messages about tls display the address address.

tor_tls_set_renegotiate_callback()

void tor_tls_set_renegotiate_callback	(	tor_tls_t *	tls,
		void(*)(tor_tls_t *, void *arg)	cb,
		void *	arg
	)

Set cb to be called with argument arg whenever tls next gets a client-side renegotiate in the middle of a read. Do not invoke this function until after initial handshaking is done!

Here is the call graph for this function:

Here is the caller graph for this function:

tor_tls_shutdown()

int tor_tls_shutdown

(

tor_tls_t *

tls

)

Shut down an open tls connection tls. When finished, returns TOR_TLS_DONE. On failure, returns TOR_TLS_ERROR, TOR_TLS_WANTREAD, or TOR_TLS_WANTWRITE.

tor_tls_unblock_renegotiation()

void tor_tls_unblock_renegotiation

(

tor_tls_t *

tls

)

If this version of openssl requires it, turn on renegotiation on tls.

tor_tls_used_v1_handshake()

int tor_tls_used_v1_handshake

(

tor_tls_t *

tls

)

Return true iff the initial TLS connection at tls did not use a v2 TLS handshake. Output is undefined if the handshake isn't finished.

tor_tls_verify()

int tor_tls_verify	(	int	severity,
		tor_tls_t *	tls,
		crypto_pk_t **	identity_key
	)

If the provided tls connection is authenticated and has a certificate chain that is currently valid and signed, then set *identity_key to the identity certificate's key and return 0. Else, return -1 and log complaints with log-level severity.

tor_tls_write()

int tor_tls_write	(	tor_tls_t *	tls,
		const char *	cp,
		size_t	n
	)

Underlying function for TLS writing. Write up to n characters from cp onto tls. On success, returns the number of characters written. On failure, returns TOR_TLS_ERROR, TOR_TLS_WANTREAD, or TOR_TLS_WANTWRITE.

tor_x509_cert_decode()

tor_x509_cert_t* tor_x509_cert_decode	(	const uint8_t *	certificate,
		size_t	certificate_len
	)

Read a DER-encoded X509 cert, of length exactly certificate_len, from a certificate. Return a newly allocated tor_x509_cert_t on success and NULL on failure.

tor_x509_cert_dup()

tor_x509_cert_t* tor_x509_cert_dup

(

const tor_x509_cert_t *

cert

)

Return a new copy of cert.

tor_x509_cert_free_()

void tor_x509_cert_free_

(

tor_x509_cert_t *

cert

)

Free all storage held in cert

Here is the call graph for this function:

tor_x509_cert_get_cert_digests()

const common_digests_t* tor_x509_cert_get_cert_digests

(

const tor_x509_cert_t *

cert

)

Return a set of digests for the public key in cert.

tor_x509_cert_get_der()

void tor_x509_cert_get_der	(	const tor_x509_cert_t *	cert,
		const uint8_t **	encoded_out,
		size_t *	size_out
	)

Set *encoded_out and *size_out to cert's encoded DER representation and length, respectively.

tor_x509_cert_get_id_digests()

const common_digests_t* tor_x509_cert_get_id_digests

(

const tor_x509_cert_t *

cert

)

Return a set of digests for the public key in cert, or NULL if this cert's public key is not one we know how to take the digest of.

Here is the caller graph for this function: