]>
Commit | Line | Data |
---|---|---|
ed8ee42c DB |
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 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 | ||
2a6a4076 MA |
21 | #ifndef QIO_CHANNEL_TLS_H |
22 | #define QIO_CHANNEL_TLS_H | |
ed8ee42c DB |
23 | |
24 | #include "io/channel.h" | |
25 | #include "io/task.h" | |
26 | #include "crypto/tlssession.h" | |
db1015e9 | 27 | #include "qom/object.h" |
ed8ee42c DB |
28 | |
29 | #define TYPE_QIO_CHANNEL_TLS "qio-channel-tls" | |
db1015e9 | 30 | typedef struct QIOChannelTLS QIOChannelTLS; |
8110fa1d EH |
31 | DECLARE_INSTANCE_CHECKER(QIOChannelTLS, QIO_CHANNEL_TLS, |
32 | TYPE_QIO_CHANNEL_TLS) | |
ed8ee42c | 33 | |
ed8ee42c DB |
34 | |
35 | /** | |
36 | * QIOChannelTLS | |
37 | * | |
38 | * The QIOChannelTLS class provides a channel wrapper which | |
39 | * can transparently run the TLS encryption protocol. It is | |
40 | * usually used over a TCP socket, but there is actually no | |
41 | * technical restriction on which type of master channel is | |
42 | * used as the transport. | |
43 | * | |
44 | * This channel object is capable of running as either a | |
45 | * TLS server or TLS client. | |
46 | */ | |
47 | ||
48 | struct QIOChannelTLS { | |
49 | QIOChannel parent; | |
50 | QIOChannel *master; | |
51 | QCryptoTLSSession *session; | |
a2458b6f | 52 | QIOChannelShutdown shutdown; |
ed8ee42c DB |
53 | }; |
54 | ||
55 | /** | |
56 | * qio_channel_tls_new_server: | |
57 | * @master: the underlying channel object | |
58 | * @creds: the credentials to use for TLS handshake | |
59 | * @aclname: the access control list for validating clients | |
821791b5 | 60 | * @errp: pointer to a NULL-initialized error object |
ed8ee42c DB |
61 | * |
62 | * Create a new TLS channel that runs the server side of | |
63 | * a TLS session. The TLS session handshake will use the | |
64 | * credentials provided in @creds. If the @aclname parameter | |
65 | * is non-NULL, then the client will have to provide | |
66 | * credentials (ie a x509 client certificate) which will | |
67 | * then be validated against the ACL. | |
68 | * | |
69 | * After creating the channel, it is mandatory to call | |
70 | * the qio_channel_tls_handshake() method before attempting | |
71 | * todo any I/O on the channel. | |
72 | * | |
73 | * Once the handshake has completed, all I/O should be done | |
74 | * via the new TLS channel object and not the original | |
75 | * master channel | |
76 | * | |
77 | * Returns: the new TLS channel object, or NULL | |
78 | */ | |
79 | QIOChannelTLS * | |
80 | qio_channel_tls_new_server(QIOChannel *master, | |
81 | QCryptoTLSCreds *creds, | |
82 | const char *aclname, | |
83 | Error **errp); | |
84 | ||
85 | /** | |
86 | * qio_channel_tls_new_client: | |
87 | * @master: the underlying channel object | |
88 | * @creds: the credentials to use for TLS handshake | |
89 | * @hostname: the user specified server hostname | |
821791b5 | 90 | * @errp: pointer to a NULL-initialized error object |
ed8ee42c DB |
91 | * |
92 | * Create a new TLS channel that runs the client side of | |
93 | * a TLS session. The TLS session handshake will use the | |
94 | * credentials provided in @creds. The @hostname parameter | |
95 | * should provide the user specified hostname of the server | |
96 | * and will be validated against the server's credentials | |
97 | * (ie CommonName of the x509 certificate) | |
98 | * | |
99 | * After creating the channel, it is mandatory to call | |
100 | * the qio_channel_tls_handshake() method before attempting | |
101 | * todo any I/O on the channel. | |
102 | * | |
103 | * Once the handshake has completed, all I/O should be done | |
104 | * via the new TLS channel object and not the original | |
105 | * master channel | |
106 | * | |
107 | * Returns: the new TLS channel object, or NULL | |
108 | */ | |
109 | QIOChannelTLS * | |
110 | qio_channel_tls_new_client(QIOChannel *master, | |
111 | QCryptoTLSCreds *creds, | |
112 | const char *hostname, | |
113 | Error **errp); | |
114 | ||
115 | /** | |
116 | * qio_channel_tls_handshake: | |
117 | * @ioc: the TLS channel object | |
118 | * @func: the callback to invoke when completed | |
119 | * @opaque: opaque data to pass to @func | |
120 | * @destroy: optional callback to free @opaque | |
1939ccda PX |
121 | * @context: the context that TLS handshake will run with. If %NULL, |
122 | * the default context will be used | |
ed8ee42c DB |
123 | * |
124 | * Perform the TLS session handshake. This method | |
125 | * will return immediately and the handshake will | |
126 | * continue in the background, provided the main | |
127 | * loop is running. When the handshake is complete, | |
128 | * or fails, the @func callback will be invoked. | |
129 | */ | |
130 | void qio_channel_tls_handshake(QIOChannelTLS *ioc, | |
131 | QIOTaskFunc func, | |
132 | gpointer opaque, | |
1939ccda PX |
133 | GDestroyNotify destroy, |
134 | GMainContext *context); | |
ed8ee42c DB |
135 | |
136 | /** | |
137 | * qio_channel_tls_get_session: | |
138 | * @ioc: the TLS channel object | |
139 | * | |
140 | * Get the TLS session used by the channel. | |
141 | * | |
142 | * Returns: the TLS session | |
143 | */ | |
144 | QCryptoTLSSession * | |
145 | qio_channel_tls_get_session(QIOChannelTLS *ioc); | |
146 | ||
2a6a4076 | 147 | #endif /* QIO_CHANNEL_TLS_H */ |