include/vlc_tls.h

   1 /*****************************************************************************
   2  * vlc_tls.h: Transport Layer Security API
   3  *****************************************************************************
   4  * Copyright (C) 2004-2011 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 sockets
  27  * \defgroup tls Transport Layer Security
  28  * @{
  29  * \file
  30  * Transport Layer Security (TLS) functions
  31  */
  32
  33 # include <vlc_network.h>
  34
  35 typedef struct vlc_tls vlc_tls_t;
  36 typedef struct vlc_tls_creds vlc_tls_creds_t;
  37
  38 /** TLS session */
  39 struct vlc_tls
  40 {
  41     vlc_object_t *obj;
  42     void *sys;
  43     int fd;
  44
  45     ssize_t (*recv)(struct vlc_tls *, void *, size_t);
  46     ssize_t (*send)(struct vlc_tls *, const void *, size_t);
  47     int (*shutdown)(struct vlc_tls *, bool duplex);
  48     void (*close)(vlc_tls_t *);
  49 };
  50
  51 /**
  52  * Initiates a client TLS session.
  53  *
  54  * Performs client side of TLS handshake through a connected socket, and
  55  * establishes a secure channel. This is a blocking network operation and may
  56  * be a thread cancellation point.
  57  *
  58  * @param fd socket through which to establish the secure channel
  59  * @param hostname expected server name, used both as Server Name Indication
  60  *                 and as expected Common Name of the peer certificate
  61  * @param service unique identifier for the service to connect to
  62  *                (only used locally for certificates database)
  63  * @param alpn NULL-terminated list of Application Layer Protocols
  64  *             to negotiate, or NULL to not negotiate protocols
  65  * @param alp storage space for the negotiated Application Layer
  66  *            Protocol or NULL if negotiation was not performed[OUT]
  67  *
  68  * @return TLS session, or NULL on error.
  69  **/
  70 VLC_API vlc_tls_t *vlc_tls_ClientSessionCreate (vlc_tls_creds_t *, int fd,
  71                                          const char *host, const char *service,
  72                                          const char *const *alpn, char **alp);
  73
  74 VLC_API vlc_tls_t *vlc_tls_SessionCreate (vlc_tls_creds_t *, int fd,
  75                                           const char *host,
  76                                           const char *const *alpn);
  77
  78 /**
  79  * Destroys a TLS session down.
  80  *
  81  * All resources associated with the TLS session are released.
  82  *
  83  * If the session was established succesfully, then shutdown cleanly, the
  84  * underlying socket can be reused. Otherwise, it must be closed. Either way,
  85  * this function does not close the underlying socket: Use vlc_tls_Close()
  86  * instead to close it at the same.
  87  *
  88  * This function is non-blocking and is not a cancellation point.
  89  */
  90 VLC_API void vlc_tls_SessionDelete (vlc_tls_t *);
  91
  92 /**
  93  * Receives data through a TLS session.
  94  */
  95 VLC_API ssize_t vlc_tls_Read(vlc_tls_t *, void *buf, size_t len, bool waitall);
  96 VLC_API char *vlc_tls_GetLine(vlc_tls_t *);
  97
  98 /**
  99  * Sends data through a TLS session.
 100  */
 101 VLC_API ssize_t vlc_tls_Write(vlc_tls_t *, const void *buf, size_t len);
 102
 103 /**
 104  * Terminates a TLS session.
 105  *
 106  * This sends the TLS session close notification to the other end, securely
 107  * indicating that no further data will be sent. Data can still be received
 108  * until a close notification is received from the other end.
 109  *
 110  * @param duplex whether to stop receiving data as well
 111  * @retval 0 the session was terminated securely and cleanly
 112  *           (the underlying socket can be reused for other purposes)
 113  * @return -1 the session was terminated locally, but either a notification
 114  *            could not be sent or received (the underlying socket cannot be
 115  *            reused and must be closed)
 116  */
 117 static inline int vlc_tls_Shutdown(vlc_tls_t *tls, bool duplex)
 118 {
 119     return tls->shutdown(tls, duplex);
 120 }
 121
 122 # define tls_Recv(a,b,c) vlc_tls_Read(a,b,c,false)
 123 # define tls_Send(a,b,c) vlc_tls_Write(a,b,c)
 124
 125 /**
 126  * Closes a TLS session and underlying connection.
 127  *
 128  * This function is non-blocking and is a cancellation point.
 129  */
 130 static inline void vlc_tls_Close(vlc_tls_t *session)
 131 {
 132     int fd = session->fd;
 133
 134     vlc_tls_SessionDelete(session);
 135     shutdown(fd, SHUT_RDWR);
 136     net_Close(fd);
 137 }
 138
 139 /** TLS credentials (certificate, private and trust settings) */
 140 struct vlc_tls_creds
 141 {
 142     VLC_COMMON_MEMBERS
 143
 144     module_t  *module;
 145     void *sys;
 146
 147     int (*open) (vlc_tls_creds_t *, vlc_tls_t *, int fd, const char *host,
 148                  const char *const *alpn);
 149     int  (*handshake)(vlc_tls_creds_t *, vlc_tls_t *, const char *host,
 150                       const char *service, char ** /*restrict*/ alp);
 151 };
 152
 153 /**
 154  * Allocates TLS credentials for a client.
 155  * Credentials can be cached and reused across multiple TLS sessions.
 156  *
 157  * @return TLS credentials object, or NULL on error.
 158  **/
 159 VLC_API vlc_tls_creds_t *vlc_tls_ClientCreate (vlc_object_t *);
 160
 161 /**
 162  * Allocates server TLS credentials.
 163  *
 164  * @param cert required (Unicode) path to an x509 certificate,
 165  *             if NULL, anonymous key exchange will be used.
 166  * @param key (UTF-8) path to the PKCS private key for the certificate,
 167  *            if NULL; cert will be used.
 168  *
 169  * @return TLS credentials object, or NULL on error.
 170  */
 171 VLC_API vlc_tls_creds_t *vlc_tls_ServerCreate (vlc_object_t *,
 172                                                const char *cert,
 173                                                const char *key);
 174
 175 static inline int vlc_tls_SessionHandshake (vlc_tls_creds_t *crd,
 176                                             vlc_tls_t *tls)
 177 {
 178     return crd->handshake(crd, tls, NULL, NULL, NULL);
 179 }
 180
 181 /**
 182  * Releases TLS credentials.
 183  *
 184  * Releases data allocated with vlc_tls_ClientCreate() or
 185  * vlc_tls_ServerCreate().
 186  *
 187  * @param srv object to be destroyed (or NULL)
 188  */
 189 VLC_API void vlc_tls_Delete (vlc_tls_creds_t *);
 190
 191 /**
 192  * Fakes a TLS session.
 193  *
 194  * Creates a dummy TLS session structure from a socket file descriptor. Data
 195  * will be sent and received directly through the socket. This can be used
 196  * either to share common code between non-TLS and TLS cases, or for testing
 197  * purposes.
 198  */
 199 VLC_API vlc_tls_t *vlc_tls_DummyCreate(vlc_object_t *obj, int fd);
 200
 201 /** @} */
 202
 203 #endif