1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
/*
* QEMU I/O channels TLS driver
*
* Copyright (c) 2015 Red Hat, Inc.
*
* This library 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 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, see <http://www.gnu.org/licenses/>.
*
*/
#ifndef QIO_CHANNEL_TLS_H
#define QIO_CHANNEL_TLS_H
#include "io/channel.h"
#include "io/task.h"
#include "crypto/tlssession.h"
#define TYPE_QIO_CHANNEL_TLS "qio-channel-tls"
#define QIO_CHANNEL_TLS(obj) \
OBJECT_CHECK(QIOChannelTLS, (obj), TYPE_QIO_CHANNEL_TLS)
typedef struct QIOChannelTLS QIOChannelTLS;
/**
* QIOChannelTLS
*
* The QIOChannelTLS class provides a channel wrapper which
* can transparently run the TLS encryption protocol. It is
* usually used over a TCP socket, but there is actually no
* technical restriction on which type of master channel is
* used as the transport.
*
* This channel object is capable of running as either a
* TLS server or TLS client.
*/
struct QIOChannelTLS {
QIOChannel parent;
QIOChannel *master;
QCryptoTLSSession *session;
};
/**
* qio_channel_tls_new_server:
* @master: the underlying channel object
* @creds: the credentials to use for TLS handshake
* @aclname: the access control list for validating clients
* @errp: pointer to a NULL-initialized error object
*
* Create a new TLS channel that runs the server side of
* a TLS session. The TLS session handshake will use the
* credentials provided in @creds. If the @aclname parameter
* is non-NULL, then the client will have to provide
* credentials (ie a x509 client certificate) which will
* then be validated against the ACL.
*
* After creating the channel, it is mandatory to call
* the qio_channel_tls_handshake() method before attempting
* todo any I/O on the channel.
*
* Once the handshake has completed, all I/O should be done
* via the new TLS channel object and not the original
* master channel
*
* Returns: the new TLS channel object, or NULL
*/
QIOChannelTLS *
qio_channel_tls_new_server(QIOChannel *master,
QCryptoTLSCreds *creds,
const char *aclname,
Error **errp);
/**
* qio_channel_tls_new_client:
* @master: the underlying channel object
* @creds: the credentials to use for TLS handshake
* @hostname: the user specified server hostname
* @errp: pointer to a NULL-initialized error object
*
* Create a new TLS channel that runs the client side of
* a TLS session. The TLS session handshake will use the
* credentials provided in @creds. The @hostname parameter
* should provide the user specified hostname of the server
* and will be validated against the server's credentials
* (ie CommonName of the x509 certificate)
*
* After creating the channel, it is mandatory to call
* the qio_channel_tls_handshake() method before attempting
* todo any I/O on the channel.
*
* Once the handshake has completed, all I/O should be done
* via the new TLS channel object and not the original
* master channel
*
* Returns: the new TLS channel object, or NULL
*/
QIOChannelTLS *
qio_channel_tls_new_client(QIOChannel *master,
QCryptoTLSCreds *creds,
const char *hostname,
Error **errp);
/**
* qio_channel_tls_handshake:
* @ioc: the TLS channel object
* @func: the callback to invoke when completed
* @opaque: opaque data to pass to @func
* @destroy: optional callback to free @opaque
* @context: the context that TLS handshake will run with. If %NULL,
* the default context will be used
*
* Perform the TLS session handshake. This method
* will return immediately and the handshake will
* continue in the background, provided the main
* loop is running. When the handshake is complete,
* or fails, the @func callback will be invoked.
*/
void qio_channel_tls_handshake(QIOChannelTLS *ioc,
QIOTaskFunc func,
gpointer opaque,
GDestroyNotify destroy,
GMainContext *context);
/**
* qio_channel_tls_get_session:
* @ioc: the TLS channel object
*
* Get the TLS session used by the channel.
*
* Returns: the TLS session
*/
QCryptoTLSSession *
qio_channel_tls_get_session(QIOChannelTLS *ioc);
#endif /* QIO_CHANNEL_TLS_H */
|
