Daniel P. Berrange | ed8ee42 | 2015-03-02 18:13:13 +0000 | [diff] [blame] | 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 | |
Markus Armbruster | 2a6a407 | 2016-06-29 13:47:03 +0200 | [diff] [blame] | 21 | #ifndef QIO_CHANNEL_TLS_H |
| 22 | #define QIO_CHANNEL_TLS_H |
Daniel P. Berrange | ed8ee42 | 2015-03-02 18:13:13 +0000 | [diff] [blame] | 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; |
Daniel P. Berrangé | a2458b6 | 2018-11-19 13:42:28 +0000 | [diff] [blame] | 51 | QIOChannelShutdown shutdown; |
Daniel P. Berrange | ed8ee42 | 2015-03-02 18:13:13 +0000 | [diff] [blame] | 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 |
Daniel P. Berrange | 821791b | 2016-01-13 12:22:33 +0000 | [diff] [blame] | 59 | * @errp: pointer to a NULL-initialized error object |
Daniel P. Berrange | ed8ee42 | 2015-03-02 18:13:13 +0000 | [diff] [blame] | 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 |
Daniel P. Berrange | 821791b | 2016-01-13 12:22:33 +0000 | [diff] [blame] | 89 | * @errp: pointer to a NULL-initialized error object |
Daniel P. Berrange | ed8ee42 | 2015-03-02 18:13:13 +0000 | [diff] [blame] | 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 |
Peter Xu | 1939ccd | 2018-03-05 14:43:24 +0800 | [diff] [blame] | 120 | * @context: the context that TLS handshake will run with. If %NULL, |
| 121 | * the default context will be used |
Daniel P. Berrange | ed8ee42 | 2015-03-02 18:13:13 +0000 | [diff] [blame] | 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, |
Peter Xu | 1939ccd | 2018-03-05 14:43:24 +0800 | [diff] [blame] | 132 | GDestroyNotify destroy, |
| 133 | GMainContext *context); |
Daniel P. Berrange | ed8ee42 | 2015-03-02 18:13:13 +0000 | [diff] [blame] | 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 | |
Markus Armbruster | 2a6a407 | 2016-06-29 13:47:03 +0200 | [diff] [blame] | 146 | #endif /* QIO_CHANNEL_TLS_H */ |