vlc_tls.h 4.53 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
{
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
41 42
    VLC_COMMON_MEMBERS

43
    void *sys;
44
    int fd;
45

46
    struct virtual_socket_t sock;
47
};
48

49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
/**
 * Initiates a client TLS session.
 *
 * Performs client side of TLS handshake through a connected socket, and
 * establishes a secure channel. This is a blocking network operation.
 *
 * @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.
 **/
67
VLC_API vlc_tls_t *vlc_tls_ClientSessionCreate (vlc_tls_creds_t *, int fd,
68 69
                                         const char *host, const char *service,
                                         const char *const *alpn, char **alp);
70

71 72 73
vlc_tls_t *vlc_tls_SessionCreate (vlc_tls_creds_t *, int fd, const char *host,
                                  const char *const *alpn);
int vlc_tls_SessionHandshake (vlc_tls_t *, const char *host, const char *serv,
74
                              char ** /*restrict*/ alp);
75
VLC_API void vlc_tls_SessionDelete (vlc_tls_t *);
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
76

77 78 79
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
80

81 82
# 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
83

84
/** TLS credentials (certificate, private and trust settings) */
85
struct vlc_tls_creds
86 87
{
    VLC_COMMON_MEMBERS
88

89
    module_t  *module;
90
    void *sys;
91

92 93 94
    int (*open) (vlc_tls_creds_t *, vlc_tls_t *, int fd, const char *host,
                 const char *const *alpn);
    int  (*handshake) (vlc_tls_t *, const char *host, const char *service,
95
                       char ** /*restrict*/ alp);
96
    void (*close) (vlc_tls_t *);
97
};
98

99 100 101 102 103 104
/**
 * Allocates TLS credentials for a client.
 * Credentials can be cached and reused across multiple TLS sessions.
 *
 * @return TLS credentials object, or NULL on error.
 **/
105
VLC_API vlc_tls_creds_t *vlc_tls_ClientCreate (vlc_object_t *);
106 107 108 109 110 111 112 113 114 115 116

/**
 * 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.
 */
117 118
vlc_tls_creds_t *vlc_tls_ServerCreate (vlc_object_t *,
                                       const char *cert, const char *key);
119 120 121 122 123 124 125 126 127

/**
 * Releases TLS credentials.
 *
 * Releases data allocated with vlc_tls_ClientCreate() or
 * vlc_tls_ServerCreate().
 *
 * @param srv object to be destroyed (or NULL)
 */
128
VLC_API void vlc_tls_Delete (vlc_tls_creds_t *);
129

130 131
/** @} */

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