tor  0.4.2.0-alpha-dev
Macros | Typedefs | Functions
tortls.h File Reference
#include "lib/crypt_ops/crypto_rsa.h"
#include "lib/testsupport/testsupport.h"
#include "lib/net/nettypes.h"

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()   STMT_NIL
 

Typedefs

typedef struct tor_tls_t tor_tls_t
 
typedef struct tor_tls_context_t tor_tls_context_t
 

Functions

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)
 
void tor_tls_init (void)
 
void tls_log_errors (tor_tls_t *tls, int severity, int domain, const char *doing)
 
int tor_tls_context_init (unsigned flags, crypto_pk_t *client_identity, crypto_pk_t *server_identity, unsigned int key_lifetime)
 
void tor_tls_context_incref (tor_tls_context_t *ctx)
 
void tor_tls_context_decref (tor_tls_context_t *ctx)
 
tor_tls_context_ttor_tls_context_get (int is_server)
 
tor_tls_ttor_tls_new (tor_socket_t 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_release_socket (tor_tls_t *tls)
 
void tor_tls_free_ (tor_tls_t *tls)
 
int tor_tls_peer_has_cert (tor_tls_t *tls)
 
 MOCK_DECL (struct tor_x509_cert_t *, tor_tls_get_peer_cert,(tor_tls_t *tls))
 
 MOCK_DECL (struct 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)
 
 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_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_cert_matches_key,(const tor_tls_t *tls, const struct tor_x509_cert_t *cert))
 
 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))
 
int tor_tls_get_my_certs (int server, const struct tor_x509_cert_t **link_cert_out, const struct tor_x509_cert_t **id_cert_out)
 
crypto_pk_ttor_tls_get_my_client_auth_key (void)
 
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.

Definition in file tortls.h.

Macro Definition Documentation

◆ CASE_TOR_TLS_ERROR_ANY

#define CASE_TOR_TLS_ERROR_ANY
Value:
case TOR_TLS_ERROR_IO
#define CASE_TOR_TLS_ERROR_ANY_NONIO
Definition: tortls.h:53

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

Definition at line 62 of file tortls.h.

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

Definition at line 53 of file tortls.h.

Typedef Documentation

◆ tor_tls_context_t

Holds a SSL_CTX object and related state used to configure TLS connections.

Definition at line 71 of file tortls.h.

Function Documentation

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

Definition at line 805 of file tortls_nss.c.

◆ tls_log_errors()

void tls_log_errors ( tor_tls_t tls,
int  severity,
int  domain,
const char *  doing 
)

Log all pending tls errors at level severity in log domain domain. Use doing to describe our current activities.

Definition at line 362 of file tortls_nss.c.

References tor_tls_t::address.

Referenced by tor_tls_get_pending_bytes().

◆ 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

Definition at line 627 of file tortls_nss.c.

References tor_assert().

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

Definition at line 620 of file tortls_nss.c.

References tor_assert().

Referenced by connection_or_block_renegotiation().

◆ tor_tls_context_decref()

void tor_tls_context_decref ( tor_tls_context_t ctx)

Remove a reference to ctx, and free it if it has no more references.

Definition at line 114 of file tortls.c.

References tor_assert().

Referenced by tor_tls_free_().

◆ tor_tls_context_get()

tor_tls_context_t* tor_tls_context_get ( int  is_server)

Return the appropriate TLS context.

Definition at line 40 of file tortls.c.

References server_tls_context.

Referenced by tor_tls_get_my_certs(), tor_tls_get_my_client_auth_key(), and tor_tls_new().

◆ tor_tls_context_incref()

void tor_tls_context_incref ( tor_tls_context_t ctx)

Increase the reference count of ctx.

Definition at line 106 of file tortls.c.

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

Definition at line 177 of file tortls.c.

◆ tor_tls_err_to_string()

const char* tor_tls_err_to_string ( int  err)

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

Definition at line 150 of file tortls.c.

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

Definition at line 604 of file tortls_nss.c.

References tor_assert().

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

Definition at line 384 of file tortls.c.

References tor_tls_t::address, tor_tls_t::ssl, tor_assert(), tor_free, tor_tls_context_decref(), and tor_tls_get_n_raw_bytes().

◆ tor_tls_free_all()

void tor_tls_free_all ( void  )

Free all global TLS structures.

Definition at line 132 of file tortls.c.

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

Definition at line 674 of file tortls_nss.c.

References tor_assert().

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

Definition at line 646 of file tortls_nss.c.

References tor_assert().

Referenced by flush_chunk_tls().

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

Definition at line 96 of file tortls.c.

References tor_tls_context_get().

Referenced by MOCK_IMPL().

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

Definition at line 654 of file tortls_nss.c.

References tor_tls_t::ssl, tor_assert(), and tor_get_prfiledesc_byte_counts().

Referenced by tor_tls_free_().

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

Definition at line 634 of file tortls_nss.c.

References LD_CRYPTO, LOG_WARN, tor_tls_t::ssl, tls_log_errors(), and tor_assert().

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

Definition at line 346 of file tortls_nss.c.

Referenced by connection_or_get_state_description().

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

Definition at line 586 of file tortls_nss.c.

References tor_tls_t::ssl, tor_tls_t::state, and tor_assert().

◆ tor_tls_init()

void tor_tls_init ( void  )

Initialize OpenSSL, unless it has already been initialized.

Definition at line 356 of file tortls_nss.c.

References tor_nss_countbytes_init().

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

Definition at line 374 of file tortls.c.

References tor_tls_t::isServer, and tor_assert().

Referenced by connection_or_nonopen_was_started_here().

◆ tor_tls_new()

tor_tls_t* tor_tls_new ( tor_socket_t  sock,
int  isServer 
)

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

Definition at line 396 of file tortls_nss.c.

References SOCKET_OK, tor_tls_context_get(), and tor_wrap_prfiledesc_with_byte_counter().

Referenced by MOCK_IMPL().

◆ tor_tls_peer_has_cert()

int tor_tls_peer_has_cert ( tor_tls_t tls)

Return true iff this TLS connection is authenticated.

Definition at line 509 of file tortls_nss.c.

References tor_tls_t::ssl.

◆ tor_tls_release_socket()

void tor_tls_release_socket ( tor_tls_t tls)

Tell the TLS library that the underlying socket for tls has been closed, and the library should not attempt to free that socket itself.

Definition at line 461 of file tortls_nss.c.

References SOCKET_OK, tor_open_socket_nonblocking(), and tor_socket_t.

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

Definition at line 706 of file tortls_nss.c.

References tor_assert().

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

Definition at line 364 of file tortls.c.

References tor_tls_t::address, tor_assert(), and tor_free.

◆ 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!

Definition at line 445 of file tortls_nss.c.

References tor_assert().

Referenced by connection_or_block_renegotiation().

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

Definition at line 613 of file tortls_nss.c.

References tor_assert().

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

Definition at line 697 of file tortls_nss.c.

References tor_assert().

◆ tor_tls_verify()

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

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.

Definition at line 411 of file tortls.c.

References LD_PROTOCOL, log_fn, tor_assert(), tor_tls_cert_get_key(), and tor_tls_cert_is_valid().

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

Definition at line 562 of file tortls_nss.c.

References tor_tls_t::ssl, and tor_assert().

Referenced by flush_chunk_tls().