vlc | branch: master | Rémi Denis-Courmont <[email protected]> | Sun Feb 26 12:41:07 2017 +0200| [18e0428b175a881db5f0e93442b77c22aea9bb6c] | committer: Rémi Denis-Courmont
tls: reorganize and update documentation > http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=18e0428b175a881db5f0e93442b77c22aea9bb6c --- include/vlc_network.h | 61 +++++++++++++-- include/vlc_tls.h | 197 +++++++++++++++++++++++++++++++------------------ src/posix/filesystem.c | 18 ----- 3 files changed, 183 insertions(+), 93 deletions(-) diff --git a/include/vlc_network.h b/include/vlc_network.h index b1c2185..08c4f06 100644 --- a/include/vlc_network.h +++ b/include/vlc_network.h @@ -28,11 +28,13 @@ # define VLC_NETWORK_H /** - * \ingroup file - * \defgroup sockets Internet sockets + * \ingroup os + * \defgroup net Networking * @{ * \file * Definitions for sockets and low-level networking + * \defgroup sockets Internet sockets + * @{ */ #include <sys/types.h> @@ -64,11 +66,58 @@ # define MSG_NOSIGNAL 0 #endif -VLC_API int vlc_socket (int, int, int, bool nonblock) VLC_USED; -VLC_API int vlc_socketpair (int, int, int, int [2], bool nonblock); +/** + * Creates a socket file descriptor. + * + * This function creates a socket, similar to the standard socket() function. + * However, the new file descriptor has the close-on-exec flag set atomically, + * so as to avoid leaking the descriptor to child processes. + * + * The non-blocking flag can also optionally be set. + * + * @param pf protocol family + * @param type socket type + * @param proto network protocol + * @param nonblock true to create a non-blocking socket + * @return a new file descriptor or -1 on error + */ +VLC_API int vlc_socket(int pf, int type, int proto, bool nonblock) VLC_USED; + +/** + * Creates a pair of socket file descriptors. + * + * This function creates a pair of sockets that are mutually connected, + * much like the standard socketpair() function. However, the new file + * descriptors have the close-on-exec flag set atomically. + * See also vlc_socket(). + * + * @param pf protocol family + * @param type socket type + * @param proto network protocol + * @param nonblock true to create non-blocking sockets + * @retval 0 on success + * @retval -1 on failure + */ +VLC_API int vlc_socketpair(int pf, int type, int proto, int fds[2], + bool nonblock); struct sockaddr; -VLC_API int vlc_accept( int, struct sockaddr *, socklen_t *, bool ) VLC_USED; + +/** + * Accepts an inbound connection request on a listening socket. + * + * This function creates a connected socket from a listening socket, much like + * the standard accept() function. However, the new file descriptor has the + * close-on-exec flag set atomically. See also vlc_socket(). + * + * @param lfd listening socket file descriptor + * @param addr pointer to the peer address or NULL [OUT] + * @param alen pointer to the length of the peer address or NULL [OUT] + * @param nonblock whether to put the new socket in non-blocking mode + * @return a new file descriptor or -1 on error + */ +VLC_API int vlc_accept(int lfd, struct sockaddr *addr, socklen_t *alen, + bool nonblock) VLC_USED; # ifdef __cplusplus extern "C" { @@ -137,6 +186,8 @@ VLC_API ssize_t net_vaPrintf( vlc_object_t *p_this, int fd, const char *psz_fmt, VLC_API int vlc_close(int); +/** @} */ + /* Portable network names/addresses resolution layer */ #define NI_MAXNUMERICHOST 64 diff --git a/include/vlc_tls.h b/include/vlc_tls.h index 3a00b40..3f9c118 100644 --- a/include/vlc_tls.h +++ b/include/vlc_tls.h @@ -23,20 +23,23 @@ # define VLC_TLS_H /** - * \ingroup sockets - * \defgroup tls Transport Layer Security + * \ingroup net + * \defgroup transport Transport layer sockets + * Network stream abstraction + * + * Originally intended for the TLS protocol (Transport Layer Security), + * the Transport Layer Sockets now provides a generic abstraction + * for full-duplex I/O byte streams. + * * @{ * \file - * Transport Layer Security (TLS) functions + * Transport layer functions */ # include <vlc_network.h> -typedef struct vlc_tls vlc_tls_t; -typedef struct vlc_tls_creds vlc_tls_creds_t; - -/** TLS session */ -struct vlc_tls +/** Transport layer socket */ +typedef struct vlc_tls { int (*get_fd)(struct vlc_tls *); ssize_t (*readv)(struct vlc_tls *, struct iovec *, unsigned); @@ -45,7 +48,70 @@ struct vlc_tls void (*close)(struct vlc_tls *); struct vlc_tls *p; -}; +} vlc_tls_t; + +/** + * \defgroup tls Transport Layer Security + * @{ + */ + +/** + * TLS credentials + * + * This structure contains the credentials for establishing TLS sessions. + * This includes root Certificate Authorities (on client side), + * trust and cryptographic parameters, + * public certificates and private keys. + */ +typedef struct vlc_tls_creds +{ + VLC_COMMON_MEMBERS + + module_t *module; + void *sys; + + vlc_tls_t *(*open)(struct vlc_tls_creds *, vlc_tls_t *sock, + const char *host, const char *const *alpn); + int (*handshake)(struct vlc_tls_creds *, vlc_tls_t *session, + const char *hostname, const char *service, + char ** /*restrict*/ alp); +} vlc_tls_creds_t; + +/** + * Allocates TLS credentials for a client. + * Credentials can be cached and reused across multiple TLS sessions. + * + * @return TLS credentials object, or NULL on error. + **/ +VLC_API vlc_tls_creds_t *vlc_tls_ClientCreate(vlc_object_t *); + +/** + * Allocates server TLS credentials. + * + * @param cert path to an x509 certificate (required) + * @param key path to the PKCS private key for the certificate, + * or NULL to use cert path + * + * @return TLS credentials object, or NULL on error. + */ +VLC_API vlc_tls_creds_t *vlc_tls_ServerCreate(vlc_object_t *, const char *cert, + const char *key); + +static inline int vlc_tls_SessionHandshake (vlc_tls_creds_t *crd, + vlc_tls_t *tls) +{ + return crd->handshake(crd, tls, NULL, NULL, NULL); +} + +/** + * Releases TLS credentials. + * + * Releases data allocated with vlc_tls_ClientCreate() or + * vlc_tls_ServerCreate(). + * + * @param srv object to be destroyed (or NULL) + */ +VLC_API void vlc_tls_Delete(vlc_tls_creds_t *); /** * Initiates a client TLS session. @@ -100,6 +166,8 @@ VLC_API vlc_tls_t *vlc_tls_ClientSessionCreate(vlc_tls_creds_t *creds, VLC_API vlc_tls_t *vlc_tls_ServerSessionCreate(vlc_tls_creds_t *creds, int fd, const char *const *alpn); +/** @} */ + /** * Destroys a TLS session down. * @@ -120,22 +188,46 @@ static inline int vlc_tls_GetFD(vlc_tls_t *tls) } /** - * Receives data through a TLS session. + * Receives data through a socket. + * + * This dequeues incoming data from a transport layer socket. + * + * @param buf received buffer start address [OUT] + * @param len buffer length (in bytes) + * @param 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. + * + * @return the number of bytes actually dequeued, or -1 on error. */ VLC_API ssize_t vlc_tls_Read(vlc_tls_t *, void *buf, size_t len, bool waitall); + +/** + * Receives a text line through a socket. + * + * This dequeues one line of text from a transport layer socket. + * @return a heap-allocated nul-terminated string, or NULL on error + */ VLC_API char *vlc_tls_GetLine(vlc_tls_t *); /** - * Sends data through a TLS session. + * Sends data through a socket. */ VLC_API ssize_t vlc_tls_Write(vlc_tls_t *, const void *buf, size_t len); /** - * Terminates a TLS session. + * Shuts a connection down. * - * This sends the TLS session close notification to the other end, securely - * indicating that no further data will be sent. Data can still be received - * until a close notification is received from the other end. + * 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. * * @param duplex whether to stop receiving data as well * @retval 0 the session was terminated securely and cleanly @@ -153,9 +245,15 @@ static inline int vlc_tls_Shutdown(vlc_tls_t *tls, bool duplex) # define tls_Send(a,b,c) vlc_tls_Write(a,b,c) /** - * Closes a TLS session and underlying connection. + * Closes a connection and its underlying resources. * - * This function is non-blocking and is a cancellation point. + * 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. */ static inline void vlc_tls_Close(vlc_tls_t *session) { @@ -169,57 +267,6 @@ static inline void vlc_tls_Close(vlc_tls_t *session) while (session != NULL); } -/** TLS credentials (certificate, private and trust settings) */ -struct vlc_tls_creds -{ - VLC_COMMON_MEMBERS - - module_t *module; - void *sys; - - vlc_tls_t *(*open)(vlc_tls_creds_t *, vlc_tls_t *sock, - const char *host, const char *const *alpn); - int (*handshake)(vlc_tls_creds_t *, vlc_tls_t *session, const char *host, - const char *service, char ** /*restrict*/ alp); -}; - -/** - * Allocates TLS credentials for a client. - * Credentials can be cached and reused across multiple TLS sessions. - * - * @return TLS credentials object, or NULL on error. - **/ -VLC_API vlc_tls_creds_t *vlc_tls_ClientCreate (vlc_object_t *); - -/** - * Allocates server TLS credentials. - * - * @param cert path to an x509 certificate (required) - * @param key path to the PKCS private key for the certificate, - * or NULL to use cert path - * - * @return TLS credentials object, or NULL on error. - */ -VLC_API vlc_tls_creds_t *vlc_tls_ServerCreate (vlc_object_t *, - const char *cert, - const char *key); - -static inline int vlc_tls_SessionHandshake (vlc_tls_creds_t *crd, - vlc_tls_t *tls) -{ - return crd->handshake(crd, tls, NULL, NULL, NULL); -} - -/** - * Releases TLS credentials. - * - * Releases data allocated with vlc_tls_ClientCreate() or - * vlc_tls_ServerCreate(). - * - * @param srv object to be destroyed (or NULL) - */ -VLC_API void vlc_tls_Delete (vlc_tls_creds_t *); - /** * Creates a transport-layer stream from a socket. * @@ -229,6 +276,8 @@ VLC_API void vlc_tls_Delete (vlc_tls_creds_t *); * purposes. * * This function is not a cancellation point. + * + * @deprecated This function is transitional. Do not use it directly. */ VLC_API vlc_tls_t *vlc_tls_SocketOpen(int fd); @@ -242,7 +291,6 @@ struct addrinfo; /** * Creates a transport-layer stream from a struct addrinfo. * - * This is convenience wrapper for vlc_tls_SocketOpen(). * \note The function currently iterates through the addrinfo linked list. * Future versions may implement different behaviour (e.g. RFC6555). */ @@ -252,13 +300,22 @@ vlc_tls_t *vlc_tls_SocketOpenAddrInfo(vlc_object_t *obj, /** * Creates a transport-layer TCP stream from a name and port. * - * This is a convenience wrapper for vlc_tls_SocketOpenAddrInfo(). + * This function resolves a hostname, and attempts to establish a TCP/IP + * connection to the specified host and port number. + * + * @return a transport layer socket on success or NULL on error */ VLC_API vlc_tls_t *vlc_tls_SocketOpenTCP(vlc_object_t *obj, const char *hostname, unsigned port); /** * 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. + * + * See also vlc_tls_SocketOpenTCP() and vlc_tls_SessionCreate(). */ VLC_API vlc_tls_t *vlc_tls_SocketOpenTLS(vlc_tls_creds_t *crd, const char *hostname, unsigned port, diff --git a/src/posix/filesystem.c b/src/posix/filesystem.c index 728286d..0a7f0a7 100644 --- a/src/posix/filesystem.c +++ b/src/posix/filesystem.c @@ -293,15 +293,6 @@ static void vlc_socket_setup(int fd, bool nonblock) } #endif -/** - * Creates a socket file descriptor. The new file descriptor has the - * close-on-exec flag set. - * @param pf protocol family - * @param type socket type - * @param proto network protocol - * @param nonblock true to create a non-blocking socket - * @return a new file descriptor or -1 - */ int vlc_socket (int pf, int type, int proto, bool nonblock) { #ifdef SOCK_CLOEXEC @@ -348,15 +339,6 @@ int vlc_socketpair(int pf, int type, int proto, int fds[2], bool nonblock) return ret; } -/** - * Accepts an inbound connection request on a listening socket. - * The new file descriptor has the close-on-exec flag set. - * @param lfd listening socket file descriptor - * @param addr pointer to the peer address or NULL [OUT] - * @param alen pointer to the length of the peer address or NULL [OUT] - * @param nonblock whether to put the new socket in non-blocking mode - * @return a new file descriptor, or -1 on error. - */ int vlc_accept (int lfd, struct sockaddr *addr, socklen_t *alen, bool nonblock) { #ifdef HAVE_ACCEPT4 _______________________________________________ vlc-commits mailing list [email protected] https://mailman.videolan.org/listinfo/vlc-commits
