tortls.h File Reference

#include "crypto.h"
#include "compat.h"

Go to the source code of this file.

Defines

#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 check_no_tls_errors()   _check_no_tls_errors(__FILE__,__LINE__)

Typedefs

typedef struct tor_tls_t tor_tls_t

Functions

const char * tor_tls_err_to_string (int err)

void tor_tls_free_all (void)

int tor_tls_context_new (crypto_pk_env_t *rsa, 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)

int tor_tls_verify (int severity, tor_tls_t *tls, crypto_pk_env_t **identity)

int tor_tls_check_lifetime (tor_tls_t *tls, int tolerance)

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_renegotiate (tor_tls_t *tls)

void tor_tls_block_renegotiation (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)

void 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)

int tor_tls_used_v1_handshake (tor_tls_t *tls)

void _check_no_tls_errors (const char *fname, int line)

Detailed Description

Headers for tortls.c.

Define Documentation

#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.

Referenced by connection_handle_write_impl(), and connection_tls_continue_handshake().

#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.

Referenced by connection_read_to_buf().

Function Documentation

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.

References LD_CRYPTO, LD_NET, and tls_log_errors().

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.)

Referenced by connection_or_tls_renegotiated_cb(), and connection_tls_finish_handshake().

int tor_tls_check_lifetime	(	tor_tls_t *	tls,
		int	tolerance
	)

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

NOTE: you should call tor_tls_verify before tor_tls_check_lifetime.

References LD_NET, log_cert_lifetime(), and tls_log_errors().

int tor_tls_context_new	(	crypto_pk_env_t *	identity,
		unsigned int	key_lifetime
	)

Create a new TLS context for use with Tor TLS handshakes. identity should be set to the identity key used to sign the certificate, and nickname set to the nickname to use.

You can call this function multiple times. Each time you call it, it generates new certificates; all new connections will use the new SSL context.

References _crypto_dh_env_get_dh(), _crypto_pk_env_get_evp_pkey(), always_accept_verify_cb(), crypto_dh_free(), crypto_dh_new(), crypto_free_pk_env(), crypto_new_pk_env(), crypto_pk_dup_key(), crypto_random_hostname(), tor_tls_context_t::ctx, IDENTITY_CERT_LIFETIME, tor_tls_context_t::key, LD_CRYPTO, LD_NET, tor_tls_context_t::my_cert, tor_tls_context_t::my_id_cert, tor_tls_context_t::refcnt, tls_log_errors(), tor_assert, tor_free, tor_tls_context_decref(), tor_tls_create_certificate(), tor_tls_init(), and use_unsafe_renegotiation_op.

Referenced by init_keys(), and run_scheduled_events().

const char* tor_tls_err_to_string ( int err )

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

Referenced by connection_read_to_buf(), and connection_tls_continue_handshake().

void tor_tls_free ( tor_tls_t * tls )

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

References LD_BUG, tor_tls_t::negotiated_callback, tor_assert, tor_free, and tor_tls_context_decref().

Referenced by _connection_free().

void tor_tls_free_all ( void )

Free all global TLS structures.

References CLIENT_CIPHER_DUMMIES, LD_MM, tor_free, and tor_tls_context_decref().

Referenced by tor_free_all().

void 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.

Referenced by dumpstats().

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.

References tor_tls_t::wantwrite_n.

Referenced by flush_chunk_tls().

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.

References tor_tls_t::last_read_count, tor_tls_t::last_write_count, and LD_BUG.

Referenced by connection_handle_write_impl(), and connection_read_to_buf().

int tor_tls_get_pending_bytes ( tor_tls_t * tls )

Return the number of bytes available for reading from tls.

References tor_assert.

Referenced by connection_or_process_cells_from_inbuf(), and connection_read_to_buf().

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.

References always_accept_verify_cb(), tor_tls_t::isServer, LD_BUG, LD_HANDSHAKE, SERVER_CIPHER_LIST, ssl_state_to_string(), STACK_OF(), tls_log_errors(), tor_assert, tor_tls_client_is_using_v2_ciphers(), tor_tls_get_error(), tor_tls_unblock_renegotiation(), and tor_tls_t::wasV2Handshake.

Referenced by connection_tls_continue_handshake().

int tor_tls_is_server ( tor_tls_t * tls )

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

References tor_tls_t::isServer, and tor_assert.

Referenced by connection_or_nonopen_was_started_here(), and connection_tls_continue_handshake().

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.

References CLIENT_CIPHER_LIST, crypto_random_hostname(), tor_tls_context_t::ctx, tor_tls_t::isServer, tor_tls_t::last_read_count, tor_tls_t::last_write_count, LD_NET, rectify_client_ciphers(), SERVER_CIPHER_LIST, tls_log_errors(), tor_assert, tor_free, tor_tls_context_incref(), tor_tls_server_info_callback(), and tor_tls_t::wantwrite_n.

Referenced by connection_tls_start_handshake().

int tor_tls_peer_has_cert ( tor_tls_t * tls )

Return true iff this TLS connection is authenticated.

References LD_HANDSHAKE, and tls_log_errors().

Referenced by connection_or_check_valid_tls_handshake().

int tor_tls_read	(	tor_tls_t *	tls,
		char *	cp,
		size_t	len
	)

Underlying function for TLS reading. Reads up to len characters from tls into cp. On success, returns the number of characters read. On failure, returns TOR_TLS_ERROR, TOR_TLS_CLOSE, TOR_TLS_WANTREAD, or TOR_TLS_WANTWRITE.

References tor_tls_t::callback_arg, tor_tls_t::got_renegotiate, LD_NET, tor_tls_t::negotiated_callback, tor_assert, and tor_tls_get_error().

Referenced by read_to_chunk_tls().

int tor_tls_renegotiate ( tor_tls_t * tls )

Client only: Renegotiate a TLS session. When finished, returns TOR_TLS_DONE. On failure, returns TOR_TLS_ERROR, TOR_TLS_WANTREAD, or TOR_TLS_WANTWRITE.

References tor_tls_t::isServer, LD_HANDSHAKE, tor_assert, and tor_tls_get_error().

Referenced by connection_tls_continue_handshake().

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

Make future log messages about tls display the address address.

References tor_assert, and tor_free.

Referenced by connection_tls_start_handshake().

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!

References tor_tls_t::callback_arg, tor_tls_t::got_renegotiate, tor_tls_t::negotiated_callback, and tor_tls_server_info_callback().

Referenced by connection_or_tls_renegotiated_cb(), and connection_tls_continue_handshake().

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.

References LD_NET, tor_assert, and tor_tls_get_error().

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.

References tor_tls_t::isServer, and tor_tls_t::wasV2Handshake.

Referenced by connection_tls_continue_handshake(), and connection_tls_finish_handshake().

int tor_tls_verify	(	int	severity,
		tor_tls_t *	tls,
		crypto_pk_env_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.

References _crypto_new_pk_env_rsa(), LD_HANDSHAKE, LD_PROTOCOL, tls_log_errors(), and try_to_extract_certs_from_tls().

Referenced by connection_or_check_valid_tls_handshake().

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.

References LD_NET, tor_assert, tor_tls_get_error(), and tor_tls_t::wantwrite_n.

Referenced by flush_chunk_tls().


Defines
#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	check_no_tls_errors() _check_no_tls_errors(__FILE__,__LINE__)
Typedefs
typedef struct tor_tls_t	tor_tls_t
Functions
const char *	tor_tls_err_to_string (int err)
void	tor_tls_free_all (void)
int	tor_tls_context_new (crypto_pk_env_t *rsa, 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)
int	tor_tls_verify (int severity, tor_tls_t tls, crypto_pk_env_t *identity)
int	tor_tls_check_lifetime (tor_tls_t *tls, int tolerance)
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_renegotiate (tor_tls_t *tls)
void	tor_tls_block_renegotiation (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)
void	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)
int	tor_tls_used_v1_handshake (tor_tls_t *tls)
void	_check_no_tls_errors (const char *fname, int line)