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