include/vlc_tls.h

   1 /*****************************************************************************
   2  * vlc_tls.h:
   3  *****************************************************************************
   4  * Copyright (C) 2004-2016 Rémi Denis-Courmont
   5  * Copyright (C) 2005-2006 VLC authors and VideoLAN
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU Lesser General Public License as published by
   9  * the Free Software Foundation; either version 2.1 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15  * GNU Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public License
  18  * along with this program; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  20  *****************************************************************************/
  21
  22 #ifndef VLC_TLS_H
  23 # define VLC_TLS_H
  24
  25 /**
  26  * \ingroup net
  27  * \defgroup transport Transport layer sockets
  28  * Network stream abstraction
  29  *
  30  * Originally intended for the TLS protocol (Transport Layer Security),
  31  * the Transport Layer Sockets now provides a generic abstraction
  32  * for connection-oriented full-duplex I/O byte streams, such as TCP/IP sockets
  33  * and TLS protocol sessions.
  34  *
  35  * @{
  36  * \file
  37  * Transport layer functions
  38  */
  39
  40 # include <vlc_network.h>
  41
  42 /** Transport layer socket */
  43 typedef struct vlc_tls
  44 {
  45     const struct vlc_tls_operations *ops;
  46     struct vlc_tls *p;
  47 } vlc_tls_t;
  48
  49 struct vlc_tls_operations
  50 {
  51     int (*get_fd)(struct vlc_tls *);
  52     ssize_t (*readv)(struct vlc_tls *, struct iovec *, unsigned);
  53     ssize_t (*writev)(struct vlc_tls *, const struct iovec *, unsigned);
  54     int (*shutdown)(struct vlc_tls *, bool duplex);
  55     void (*close)(struct vlc_tls *);
  56 };
  57
  58 /**
  59  * \defgroup tls Transport Layer Security
  60  * @{
  61  */
  62
  63 /**
  64  * TLS credentials
  65  *
  66  * This structure contains the credentials for establishing TLS sessions.
  67  * This includes root Certificate Authorities (on client side),
  68  * trust and cryptographic parameters,
  69  * public certificates and private keys.
  70  */
  71 typedef struct vlc_tls_creds
  72 {
  73     struct vlc_common_members obj;
  74
  75     module_t *module;
  76     void *sys;
  77
  78     vlc_tls_t *(*open)(struct vlc_tls_creds *, vlc_tls_t *sock,
  79                        const char *host, const char *const *alpn);
  80     int  (*handshake)(struct vlc_tls_creds *, vlc_tls_t *session,
  81                       const char *hostname, const char *service,
  82                       char ** /*restrict*/ alp);
  83 } vlc_tls_creds_t;
  84
  85 /**
  86  * Allocates TLS credentials for a client.
  87  * Credentials can be cached and reused across multiple TLS sessions.
  88  *
  89  * @return TLS credentials object, or NULL on error.
  90  **/
  91 VLC_API vlc_tls_creds_t *vlc_tls_ClientCreate(vlc_object_t *);
  92
  93 /**
  94  * Allocates server TLS credentials.
  95  *
  96  * @param cert path to an x509 certificate (required)
  97  * @param key path to the PKCS private key for the certificate,
  98  *            or NULL to use cert path
  99  *
 100  * @return TLS credentials object, or NULL on error.
 101  */
 102 VLC_API vlc_tls_creds_t *vlc_tls_ServerCreate(vlc_object_t *, const char *cert,
 103                                               const char *key);
 104
 105 static inline int vlc_tls_SessionHandshake (vlc_tls_creds_t *crd,
 106                                             vlc_tls_t *tls)
 107 {
 108     return crd->handshake(crd, tls, NULL, NULL, NULL);
 109 }
 110
 111 /**
 112  * Releases TLS credentials.
 113  *
 114  * Releases data allocated with vlc_tls_ClientCreate() or
 115  * vlc_tls_ServerCreate().
 116  *
 117  * @param srv object to be destroyed (or NULL)
 118  */
 119 VLC_API void vlc_tls_Delete(vlc_tls_creds_t *);
 120
 121 /**
 122  * Initiates a client TLS session.
 123  *
 124  * Initiates a Transport Layer Security (TLS) session as the client side, using
 125  * trusted root CAs previously loaded with vlc_tls_ClientCreate().
 126  *
 127  * This is a blocking network operation and may be a thread cancellation point.
 128  *
 129  * @param creds X.509 credentials, i.e. set of root certificates of trusted
 130  *              certificate authorities
 131  * @param sock socket through which to establish the secure channel
 132  * @param hostname expected server name, used both as Server Name Indication
 133  *                 and as expected Common Name of the peer certificate [IN]
 134  * @param service unique identifier for the service to connect to
 135  *                (only used locally for certificates database) [IN]
 136  * @param alpn NULL-terminated list of Application Layer Protocols
 137  *             to negotiate, or NULL to not negotiate protocols [IN]
 138  * @param alp storage space for the negotiated Application Layer
 139  *            Protocol or NULL if negotiation was not performed [OUT]
 140  *
 141  * @note The credentials must remain valid until the session is finished.
 142  *
 143  * @return TLS session, or NULL on error.
 144  **/
 145 VLC_API vlc_tls_t *vlc_tls_ClientSessionCreate(vlc_tls_creds_t *creds,
 146                                                vlc_tls_t *sock,
 147                                                const char *host,
 148                                                const char *service,
 149                                                const char *const *alpn,
 150                                                char **alp);
 151
 152 /**
 153  * Creates a TLS server session.
 154  *
 155  * Allocates a Transport Layer Security (TLS) session as the server side, using
 156  * cryptographic keys pair and X.509 certificates chain already loaded with
 157  * vlc_tls_ServerCreate().
 158  *
 159  * Unlike vlc_tls_ClientSessionCreate(), this function does not perform any
 160  * actual network I/O. vlc_tls_SessionHandshake() must be used to perform the
 161  * TLS handshake before sending and receiving data through the TLS session.
 162  *
 163  * This function is non-blocking and is not a cancellation point.
 164  *
 165  * @param creds server credentials, i.e. keys pair and X.509 certificates chain
 166  * @param alpn NULL-terminated list of Application Layer Protocols
 167  *             to negotiate, or NULL to not negotiate protocols
 168  *
 169  * @return TLS session, or NULL on error.
 170  */
 171 VLC_API vlc_tls_t *vlc_tls_ServerSessionCreate(vlc_tls_creds_t *creds,
 172                                                vlc_tls_t *sock,
 173                                                const char *const *alpn);
 174
 175 /** @} */
 176
 177 /**
 178  * Destroys a TLS session down.
 179  *
 180  * All resources associated with the TLS session are released.
 181  *
 182  * If the session was established successfully, then shutdown cleanly, the
 183  * underlying socket can be reused. Otherwise, it must be closed. Either way,
 184  * this function does not close the underlying socket: Use vlc_tls_Close()
 185  * instead to close it at the same.
 186  *
 187  * This function is non-blocking and is not a cancellation point.
 188  */
 189 VLC_API void vlc_tls_SessionDelete (vlc_tls_t *);
 190
 191 static inline int vlc_tls_GetFD(vlc_tls_t *tls)
 192 {
 193     return tls->ops->get_fd(tls);
 194 }
 195
 196 /**
 197  * Receives data through a socket.
 198  *
 199  * This dequeues incoming data from a transport layer socket.
 200  *
 201  * @param buf received buffer start address [OUT]
 202  * @param len buffer length (in bytes)
 203  * @param waitall whether to wait for the exact buffer length (true),
 204  *                or for any amount of data (false)
 205  *
 206  * @note At end of stream, the number of bytes returned may be shorter than
 207  * requested regardless of the "waitall" flag.
 208  *
 209  * @return the number of bytes actually dequeued, or -1 on error.
 210  */
 211 VLC_API ssize_t vlc_tls_Read(vlc_tls_t *, void *buf, size_t len, bool waitall);
 212
 213 /**
 214  * Receives a text line through a socket.
 215  *
 216  * This dequeues one line of text from a transport layer socket.
 217  * @return a heap-allocated nul-terminated string, or NULL on error
 218  */
 219 VLC_API char *vlc_tls_GetLine(vlc_tls_t *);
 220
 221 /**
 222  * Sends data through a socket.
 223  */
 224 VLC_API ssize_t vlc_tls_Write(vlc_tls_t *, const void *buf, size_t len);
 225
 226 /**
 227  * Shuts a connection down.
 228  *
 229  * This sends the connection close notification.
 230  *
 231  * If the TLS protocol is used, this provides a secure indication to the other
 232  * end that no further data will be sent. If using plain TCP/IP, this sets the
 233  * FIN flag.
 234  *
 235  * Data can still be received until a close notification is received from the
 236  * other end.
 237  *
 238  * @param duplex whether to stop receiving data as well
 239  * @retval 0 the session was terminated securely and cleanly
 240  *           (the underlying socket can be reused for other purposes)
 241  * @return -1 the session was terminated locally, but either a notification
 242  *            could not be sent or received (the underlying socket cannot be
 243  *            reused and must be closed)
 244  */
 245 static inline int vlc_tls_Shutdown(vlc_tls_t *tls, bool duplex)
 246 {
 247     return tls->ops->shutdown(tls, duplex);
 248 }
 249
 250 /**
 251  * Closes a connection and its underlying resources.
 252  *
 253  * This function closes the transport layer socket, and terminates any
 254  * underlying connection. For instance, if the TLS protocol is used over a TCP
 255  * stream, this function terminates both the TLS session, and then underlying
 256  * TCP/IP connection.
 257  *
 258  * To close a connection but retain any underlying resources, use
 259  * vlc_tls_SessionDelete() instead.
 260  */
 261 static inline void vlc_tls_Close(vlc_tls_t *session)
 262 {
 263     do
 264     {
 265         vlc_tls_t *p = session->p;
 266
 267         vlc_tls_SessionDelete(session);
 268         session = p;
 269     }
 270     while (session != NULL);
 271 }
 272
 273 /**
 274  * Creates a transport-layer stream from a socket.
 275  *
 276  * Creates a transport-layer I/O stream from a socket file descriptor.
 277  * Data will be sent and received directly through the socket. This can be used
 278  * either to share common code between non-TLS and TLS cases, or for testing
 279  * purposes.
 280  *
 281  * This function is not a cancellation point.
 282  *
 283  * @deprecated This function is transitional. Do not use it directly.
 284  */
 285 VLC_API vlc_tls_t *vlc_tls_SocketOpen(int fd);
 286
 287 /**
 288  * Creates a connected pair of transport-layer sockets.
 289  */
 290 VLC_API int vlc_tls_SocketPair(int family, int protocol, vlc_tls_t *[2]);
 291
 292 struct addrinfo;
 293
 294 /**
 295  * Creates a transport-layer stream from a struct addrinfo.
 296  *
 297  * This function tries to allocate a socket using the specified addrinfo
 298  * structure. Normally, the vlc_tls_SocketOpenTCP() function takes care of
 299  * this. But in some cases, it cannot be used, notably:
 300  * - if the remote destination is not resolved (directly) from getaddrinfo(),
 301  * - if the socket type is not SOCK_STREAM,
 302  * - if the transport protocol is not TCP (IPPROTO_TCP), or
 303  * - if TCP Fast Open should be attempted.
 304  *
 305  * @param ai a filled addrinfo structure (the ai_next member is ignored)
 306  * @param defer_connect whether to attempt a TCP Fast Open connection or not
 307  */
 308 VLC_API vlc_tls_t *vlc_tls_SocketOpenAddrInfo(const struct addrinfo *ai,
 309                                               bool defer_connect);
 310
 311 /**
 312  * Creates a transport-layer TCP stream from a name and port.
 313  *
 314  * This function resolves a hostname, and attempts to establish a TCP/IP
 315  * connection to the specified host and port number.
 316  *
 317  * @note The function currently iterates through the addrinfo linked list.
 318  * Future versions may implement different behaviour (e.g. RFC6555).
 319  *
 320  * @return a transport layer socket on success or NULL on error
 321  */
 322 VLC_API vlc_tls_t *vlc_tls_SocketOpenTCP(vlc_object_t *obj,
 323                                          const char *hostname, unsigned port);
 324
 325 /**
 326  * Initiates a TLS session over TCP.
 327  *
 328  * This function resolves a hostname, attempts to establish a TCP/IP
 329  * connection to the specified host and port number, and finally attempts to
 330  * establish a TLS session over the TCP/IP stream.
 331  *
 332  * See also vlc_tls_SocketOpenTCP() and vlc_tls_SessionCreate().
 333  */
 334 VLC_API vlc_tls_t *vlc_tls_SocketOpenTLS(vlc_tls_creds_t *crd,
 335                                          const char *hostname, unsigned port,
 336                                          const char *service,
 337                                          const char *const *alpn, char **alp);
 338
 339 /** @} */
 340
 341 #endif