buffers_tls.h File Reference

Header for buffers_tls.c. More...

Go to the source code of this file.

Functions
int	buf_read_from_tls (struct buf_t *buf, struct tor_tls_t *tls, size_t at_most)
int	buf_flush_to_tls (struct buf_t *buf, struct tor_tls_t *tls, size_t sz)

Detailed Description

Header for buffers_tls.c.

Definition in file buffers_tls.h.

Function Documentation

buf_flush_to_tls()

int buf_flush_to_tls	(	buf_t *	buf,
		tor_tls_t *	tls,
		size_t	flushlen
	)

As buf_flush_to_socket(), but writes data to a TLS connection. Can write more than flushlen bytes.

Definition at line 138 of file buffers_tls.c.

buf_read_from_tls()

int buf_read_from_tls	(	buf_t *	buf,
		tor_tls_t *	tls,
		size_t	at_most
	)

As read_to_buf, but reads from a TLS connection, and returns a TLS status value rather than the number of bytes read.

Using TLS on OR connections complicates matters in two ways.

First, a TLS stream has its own read buffer independent of the connection's read buffer. (TLS needs to read an entire frame from the network before it can decrypt any data. Thus, trying to read 1 byte from TLS can require that several KB be read from the network and decrypted. The extra data is stored in TLS's decrypt buffer.) Because the data hasn't been read by Tor (it's still inside the TLS), this means that sometimes a connection "has stuff to read" even when poll() didn't return POLLIN. The tor_tls_get_pending_bytes function is used in connection.c to detect TLS objects with non-empty internal buffers and read from them again.

Second, the TLS stream's events do not correspond directly to network events: sometimes, before a TLS stream can read, the network must be ready to write – or vice versa.

On success, return the number of bytes read. On error, a TOR_TLS_* negative code is returned (expect any of them except TOR_TLS_DONE).

Definition at line 67 of file buffers_tls.c.