[vlc-commits] tls: reorganize and update documentation
Rémi Denis-Courmont
git at videolan.org
Sun Feb 26 12:10:02 CET 2017
vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | 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
More information about the vlc-commits
mailing list