tls: reorganize and update documentation
authorRémi Denis-Courmont <remi@remlab.net>
Sun, 26 Feb 2017 10:41:07 +0000 (12:41 +0200)
committerRémi Denis-Courmont <remi@remlab.net>
Sun, 26 Feb 2017 10:41:07 +0000 (12:41 +0200)
include/vlc_network.h
include/vlc_tls.h
src/posix/filesystem.c

index b1c2185..08c4f06 100644 (file)
 # 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>
 # 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
index 3a00b40..3f9c118 100644 (file)
 # 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,
index 728286d..0a7f0a7 100644 (file)
@@ -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