vlc_tls.h 5.35 KB
Newer Older
1
/*****************************************************************************
2
 * vlc_tls.h: Transport Layer Security API
3
 *****************************************************************************
4
 * Copyright (C) 2004-2011 Rémi Denis-Courmont
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
5
 * Copyright (C) 2005-2006 VLC authors and VideoLAN
6
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
7 8 9
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
10 11 12 13
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
14 15
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
16
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
17 18 19
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
20 21
 *****************************************************************************/

22 23
#ifndef VLC_TLS_H
# define VLC_TLS_H
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
24

25
/**
26 27 28
 * \ingroup sockets
 * \defgroup tls Transport Layer Security
 * @{
29
 * \file
30
 * Transport Layer Security (TLS) functions
31 32
 */

Clément Stenac's avatar
Clément Stenac committed
33
# include <vlc_network.h>
34

35 36 37
typedef struct vlc_tls vlc_tls_t;
typedef struct vlc_tls_creds vlc_tls_creds_t;

38
/** TLS session */
39
struct vlc_tls
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
40
{
41
    vlc_object_t *obj;
42
    void *sys;
43
    int fd;
44

45 46
    ssize_t (*recv)(struct vlc_tls *, void *, size_t);
    ssize_t (*send)(struct vlc_tls *, const void *, size_t);
47
    void (*close)(vlc_tls_t *);
48
};
49

50 51 52 53
/**
 * Initiates a client TLS session.
 *
 * Performs client side of TLS handshake through a connected socket, and
54 55
 * establishes a secure channel. This is a blocking network operation and may
 * be a thread cancellation point.
56 57 58 59 60 61 62 63 64 65 66 67 68
 *
 * @param fd socket through which to establish the secure channel
 * @param hostname expected server name, used both as Server Name Indication
 *                 and as expected Common Name of the peer certificate
 * @param service unique identifier for the service to connect to
 *                (only used locally for certificates database)
 * @param alpn NULL-terminated list of Application Layer Protocols
 *             to negotiate, or NULL to not negotiate protocols
 * @param alp storage space for the negotiated Application Layer
 *            Protocol or NULL if negotiation was not performed[OUT]
 *
 * @return TLS session, or NULL on error.
 **/
69
VLC_API vlc_tls_t *vlc_tls_ClientSessionCreate (vlc_tls_creds_t *, int fd,
70 71
                                         const char *host, const char *service,
                                         const char *const *alpn, char **alp);
72

73 74
vlc_tls_t *vlc_tls_SessionCreate (vlc_tls_creds_t *, int fd, const char *host,
                                  const char *const *alpn);
75 76 77 78 79 80 81 82 83 84

/**
 * Shuts a TLS session down.
 *
 * Shuts a TLS session down (if it was succesfully established) and releases
 * all resources. The underlying connection is preserved. Use vlc_tls_Close()
 * instead to shut it down at the same.
 *
 * This function is non-blocking and is not a cancellation point.
 */
85
VLC_API void vlc_tls_SessionDelete (vlc_tls_t *);
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
86

87 88 89
VLC_API int vlc_tls_Read(vlc_tls_t *, void *buf, size_t len, bool waitall);
VLC_API char *vlc_tls_GetLine(vlc_tls_t *);
VLC_API int vlc_tls_Write(vlc_tls_t *, const void *buf, size_t len);
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
90

91 92
# define tls_Recv(a,b,c) vlc_tls_Read(a,b,c,false)
# define tls_Send(a,b,c) vlc_tls_Write(a,b,c)
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
93

94
/** TLS credentials (certificate, private and trust settings) */
95
struct vlc_tls_creds
96 97
{
    VLC_COMMON_MEMBERS
98

99
    module_t  *module;
100
    void *sys;
101

102 103
    int (*open) (vlc_tls_creds_t *, vlc_tls_t *, int fd, const char *host,
                 const char *const *alpn);
104 105
    int  (*handshake)(vlc_tls_creds_t *, vlc_tls_t *, const char *host,
                      const char *service, char ** /*restrict*/ alp);
106
};
107

108 109 110 111 112 113
/**
 * Allocates TLS credentials for a client.
 * Credentials can be cached and reused across multiple TLS sessions.
 *
 * @return TLS credentials object, or NULL on error.
 **/
114
VLC_API vlc_tls_creds_t *vlc_tls_ClientCreate (vlc_object_t *);
115 116 117 118 119 120 121 122 123 124 125

/**
 * Allocates server TLS credentials.
 *
 * @param cert_path required (Unicode) path to an x509 certificate,
 *                  if NULL, anonymous key exchange will be used.
 * @param key_path (UTF-8) path to the PKCS private key for the certificate,
 *                 if NULL; cert_path will be used.
 *
 * @return TLS credentials object, or NULL on error.
 */
126 127
vlc_tls_creds_t *vlc_tls_ServerCreate (vlc_object_t *,
                                       const char *cert, const char *key);
128

129 130 131
static inline int vlc_tls_SessionHandshake (vlc_tls_creds_t *crd,
                                            vlc_tls_t *tls)
{
132
    return crd->handshake(crd, tls, NULL, NULL, NULL);
133 134
}

135 136 137 138 139 140 141 142
/**
 * Releases TLS credentials.
 *
 * Releases data allocated with vlc_tls_ClientCreate() or
 * vlc_tls_ServerCreate().
 *
 * @param srv object to be destroyed (or NULL)
 */
143
VLC_API void vlc_tls_Delete (vlc_tls_creds_t *);
144

145 146 147 148 149 150 151 152 153 154
/**
 * Fakes a TLS session.
 *
 * Creates a dummy TLS session structure from a socket file descriptor. Data
 * will be sent and received directly through the socket. This can be used
 * either to share common code between non-TLS and TLS cases, or for testing
 * purposes.
 */
VLC_API vlc_tls_t *vlc_tls_DummyCreate(vlc_object_t *obj, int fd);

155 156
/** @} */

Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
157
#endif