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