Network stream abstraction. More...

Collaboration diagram for Transport layer sockets:

Modules
	Transport Layer Security

Files
file	stream.c
	Transport-layer stream abstraction.

file	vlc_tls.h
	Transport layer functions.

Data Structures
struct	vlc_tls
	Transport layer socket. More...

struct	vlc_tls_operations

Typedefs
typedef struct vlc_tls	vlc_tls_t
	Transport layer socket. More...

Functions
void	vlc_tls_SessionDelete (vlc_tls_t *)
	Destroys a TLS session. More...

static int	vlc_tls_GetPollFD (vlc_tls_t tls, short events)
	Generates an event polling description. More...

static int	vlc_tls_GetFD (vlc_tls_t *tls)
	Returns the underlying file descriptor. More...

ssize_t	vlc_tls_Read (vlc_tls_t , void buf, size_t len, bool waitall)
	Receives data through a socket. More...

char *	vlc_tls_GetLine (vlc_tls_t *)
	Receives a text line through a socket. More...

ssize_t	vlc_tls_Write (vlc_tls_t , const void buf, size_t len)
	Sends data through a socket. More...

static int	vlc_tls_Shutdown (vlc_tls_t *tls, bool duplex)
	Shuts a connection down. More...

static void	vlc_tls_Close (vlc_tls_t *session)
	Closes a connection and its underlying resources. More...

vlc_tls_t *	vlc_tls_SocketOpen (int fd)
	Creates a transport-layer stream from a socket. More...

int	vlc_tls_SocketPair (int family, int protocol, vlc_tls_t *[2])
	Creates a connected pair of transport-layer sockets. More...

vlc_tls_t *	vlc_tls_SocketOpenAddrInfo (const struct addrinfo *ai, bool defer_connect)
	Creates a transport-layer stream from a struct addrinfo. More...

vlc_tls_t *	vlc_tls_SocketOpenTCP (vlc_object_t obj, const char hostname, unsigned port)
	Creates a transport-layer TCP stream from a name and port. More...

vlc_tls_t *	vlc_tls_SocketOpenTLS (vlc_tls_client_t crd, const char hostname, unsigned port, const char service, const char const alpn, char *alp)
	Initiates a TLS session over TCP. More...

Detailed Description

Network stream abstraction.

Originally intended for the TLS protocol (Transport Layer Security), the Transport Layer Sockets now provides a generic abstraction for connection-oriented full-duplex I/O byte streams, such as TCP/IP sockets and TLS protocol sessions.

Typedef Documentation

◆ vlc_tls_t

typedef struct vlc_tls vlc_tls_t

Transport layer socket.

Transport layer sockets are full-duplex, meaning data can be sent and received at the same time. As such, it is permitted for two threads to use the same TLS simultaneously, if one thread is receiving data while the other is sending data. However receiving or sending data from two threads concurrently is undefined behaviour.

The following functions are treated as sending data:

The following functions are treated as receiving data:

vlc_tls_Read(),
vlc_tls_GetLine(),
callback vlc_tls_operations.readv,
vlc_tls_Shutdown() if the duplex flag is true,
callback vlc_tls_operations.shutdown if the duplex flag is true.

Function Documentation

◆ vlc_tls_Close()

static void vlc_tls_Close ( vlc_tls_t * session )

inlinestatic

Closes a connection and its underlying resources.

This function closes the transport layer socket, and terminates any underlying connection. For instance, if the TLS protocol is used over a TCP stream, this function terminates both the TLS session, and then underlying TCP/IP connection.

To close a connection but retain any underlying resources, use vlc_tls_SessionDelete() instead.

References vlc_tls::p, p, and vlc_tls_SessionDelete().

Referenced by httpd_ClientDestroy(), httpdLoop(), vlc_h1_conn_destroy(), vlc_h1_stream_fatal(), vlc_h2_conn_destroy(), vlc_https_connect_proxy(), and vlc_https_request().

◆ vlc_tls_GetFD()

static int vlc_tls_GetFD ( vlc_tls_t * tls )

inlinestatic

Returns the underlying file descriptor.

This function returns the file descriptor underlying the transport layer stream object. This function is reentrant and is not a cancellation point.

References vlc_tls_GetPollFD().

Referenced by httpd_ClientIP(), httpd_ServerIP(), and vlc_tls_WaitConnect().

◆ vlc_tls_GetLine()

char * vlc_tls_GetLine ( vlc_tls_t * session )

Receives a text line through a socket.

This dequeues one line of text from a transport layer socket.

Returns: a heap-allocated nul-terminated string, or NULL on error

References unlikely, and vlc_tls_Read().

Referenced by vlc_chunked_read().

◆ vlc_tls_GetPollFD()

static int vlc_tls_GetPollFD	(	vlc_tls_t *	tls,
		short *	events
	)

inlinestatic

Generates an event polling description.

This function provides the necessary information to make an event polling description for use with poll() or similar event multiplexing functions.

This function is necessary both for receiving and sending data, therefore it is reentrant. It is not a cancellation point.

Parameters

events a pointer to a mask of poll events (e.g. POLLIN, POLLOUT) [IN/OUT]

Returns: the file descriptor to poll

References vlc_tls_operations::get_fd, and vlc_tls::ops.

Referenced by httpdLoop(), vlc_https_recv(), vlc_https_send(), vlc_tls_ClientSessionCreate(), vlc_tls_GetFD(), vlc_tls_ProxyGetFD(), vlc_tls_Read(), and vlc_tls_Write().

◆ vlc_tls_Read()

ssize_t vlc_tls_Read	(	vlc_tls_t *	session,
		void *	buf,
		size_t	len,
		bool	waitall
	)

Receives data through a socket.

This dequeues incoming data from a transport layer socket.

Parameters

buf	received buffer start address [OUT]
len	buffer length (in bytes)
waitall	whether to wait for the exact buffer length (true), or for any amount of data (false)

Note: At end of stream, the number of bytes returned may be shorter than requested regardless of the "waitall" flag.

Returns: the number of bytes actually dequeued, or -1 on error.

References pollfd::events, pollfd::fd, vlc_tls::ops, POLLIN, vlc_tls_operations::readv, vlc_killed(), vlc_poll_i11e(), and vlc_tls_GetPollFD().

Referenced by vlc_chunked_read(), vlc_h1_stream_read(), vlc_https_headers_recv(), and vlc_tls_GetLine().

◆ vlc_tls_SessionDelete()

void vlc_tls_SessionDelete ( vlc_tls_t * session )

Destroys a TLS session.

All resources associated with the TLS session are released.

If the session was established successfully, then shutdown cleanly, the underlying socket can be reused. Otherwise, it must be closed. Either way, this function does not close the underlying socket: Use vlc_tls_Close() instead to close it at the same.

This function is non-blocking and is not a cancellation point.

References vlc_tls_operations::close, vlc_tls::ops, vlc_restorecancel(), and vlc_savecancel().

Referenced by cleanup_tls(), httpdLoop(), vlc_h1_request(), vlc_tls_ClientSessionCreate(), vlc_tls_Close(), vlc_tls_SocketOpenAddrInfo(), vlc_tls_SocketOpenTLS(), and vlc_tls_SocketPair().

◆ vlc_tls_Shutdown()

static int vlc_tls_Shutdown	(	vlc_tls_t *	tls,
		bool	duplex
	)

inlinestatic

Shuts a connection down.

This sends the connection close notification.

If the TLS protocol is used, this provides a secure indication to the other end that no further data will be sent. If using plain TCP/IP, this sets the FIN flag.

Data can still be received until a close notification is received from the other end.

Parameters

duplex whether to stop receiving data as well

Return values

0	the session was terminated securely and cleanly (the underlying socket can be reused for other purposes)

Returns: -1 the session was terminated locally, but either a notification could not be sent or received (the underlying socket cannot be reused and must be closed)

References vlc_tls::ops, and vlc_tls_operations::shutdown.

Referenced by vlc_h1_conn_destroy(), vlc_h1_stream_fatal(), vlc_h2_conn_destroy(), and vlc_tls_ProxyShutdown().

◆ vlc_tls_SocketOpen()

vlc_tls_t * vlc_tls_SocketOpen ( int fd )

Creates a transport-layer stream from a socket.

Creates a transport-layer I/O stream from a socket file descriptor. Data will be sent and received directly through the socket. This can be used either to share common code between non-TLS and TLS cases, or for testing purposes.

This function is not a cancellation point.

Deprecated:: This function is transitional. Do not use it directly.

References vlc_tls_SocketAlloc().

Referenced by httpdLoop().

◆ vlc_tls_SocketOpenAddrInfo()

vlc_tls_t * vlc_tls_SocketOpenAddrInfo	(	const struct addrinfo *	ai,
		bool	defer_connect
	)

Creates a transport-layer stream from a struct addrinfo.

This function tries to allocate a socket using the specified addrinfo structure. Normally, the vlc_tls_SocketOpenTCP() function takes care of this. But in some cases, it cannot be used, notably:

if the remote destination is not resolved (directly) from getaddrinfo(),
if the socket type is not SOCK_STREAM,
if the transport protocol is not TCP (IPPROTO_TCP), or
if TCP Fast Open should be attempted.

Note: If the defer_connect flag is true , data must be sent with a data sending function (other than vlc_tls_Shutdown()) before data can be received. Notwithstanding the thread-safety and reentrancy promises of vlc_tls_t, the owner of the stream object is responsible for ensuring that data will be sent at least once before any attempt to receive data. Otherwise defer_connect must be false .

Parameters

ai	a filled addrinfo structure (the ai_next member is ignored)
defer_connect	whether to attempt a TCP Fast Open connection or not

◆ vlc_tls_SocketOpenTCP()

vlc_tls_t * vlc_tls_SocketOpenTCP	(	vlc_object_t *	obj,
		const char *	hostname,
		unsigned	port
	)

Creates a transport-layer TCP stream from a name and port.

This function resolves a hostname, and attempts to establish a TCP/IP connection to the specified host and port number.

Parameters

obj	optional object to log errors (may be NULL)
hostname	remote host name or IP address literal to connect to
port	remote TCP port number to connect to

Note: The function currently iterates through the addrinfo linked list. Future versions may implement different behaviour (e.g. RFC6555).

Returns: a transport layer socket on success or NULL on error

References msg_Dbg, msg_Err, name, p, vlc_getaddrinfo_i11e(), vlc_strerror_c(), and vlc_tls_SocketOpenAddrInfo().

Referenced by vlc_https_connect_proxy().

◆ vlc_tls_SocketOpenTLS()

vlc_tls_t * vlc_tls_SocketOpenTLS	(	vlc_tls_client_t *	crd,
		const char *	hostname,
		unsigned	port,
		const char *	service,
		const char const	alpn,
		char **	alp
	)

Initiates a TLS session over TCP.

This function resolves a hostname, attempts to establish a TCP/IP connection to the specified host and port number, and finally attempts to establish a TLS session over the TCP/IP stream.

References msg_Dbg, msg_Err, name, p, vlc_getaddrinfo_i11e(), vlc_strerror_c(), vlc_tls_ClientSessionCreate(), vlc_tls_SessionDelete(), and vlc_tls_SocketOpenAddrInfo().

Referenced by vlc_https_connect().