Network stream abstraction. More...

Collaboration diagram for Transport layer sockets:

Modules
	Transport Layer Security

Files
file	vlc_tls.h

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

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

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

static int	vlc_tls_GetFD (vlc_tls_t *tls)

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_creds_t crd, const char hostname, unsigned port, const char service, const char const alpn, char *alp)
	Initiates a TLS session over TCP. More...

static vlc_tls_t *	vlc_tls_ClientSessionCreateFD (vlc_tls_creds_t crd, int fd, const char host, const char srv, const char const lp, char *p)

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.

Function Documentation

◆ vlc_tls_ClientSessionCreateFD()

static vlc_tls_t* vlc_tls_ClientSessionCreateFD	(	vlc_tls_creds_t *	crd,
		int	fd,
		const char *	host,
		const char *	srv,
		const char const	lp,
		char **	p
	)

inlinestatic

References p, unlikely, vlc_tls_ClientSessionCreate(), and vlc_tls_SocketOpen().

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

References vlc_tls::get_fd.

Referenced by httpd_ClientDestroy(), httpd_ServerIP(), vlc_https_recv(), vlc_https_send(), vlc_tls_ClientSessionCreate(), vlc_tls_ProxyGetFD(), vlc_tls_Read(), vlc_tls_WaitConnect(), and vlc_tls_Write().

◆ vlc_tls_GetLine()

char* vlc_tls_GetLine ( vlc_tls_t * )

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

ssize_t vlc_tls_Read	(	vlc_tls_t *	,
		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, POLLIN, vlc_tls::readv, vlc_killed(), vlc_poll_i11e(), and vlc_tls_GetFD().

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

Destroys a TLS session down.

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::close, vlc_restorecancel(), and vlc_savecancel().

Referenced by cleanup_tls(), 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::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 vlc_tls_ClientSessionCreateFD().

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

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.

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