hw/intc/armv7m_nvic: Provide default "reset the system" behaviour for SYSRESETREQ
[qemu.git] / include / crypto / tlssession.h
1 /*
2 * QEMU crypto TLS session support
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 QCRYPTO_TLSSESSION_H
22 #define QCRYPTO_TLSSESSION_H
23
24 #include "crypto/tlscreds.h"
25
26 /**
27 * QCryptoTLSSession:
28 *
29 * The QCryptoTLSSession object encapsulates the
30 * logic to integrate with a TLS providing library such
31 * as GNUTLS, to setup and run TLS sessions.
32 *
33 * The API is designed such that it has no assumption about
34 * the type of transport it is running over. It may be a
35 * traditional TCP socket, or something else entirely. The
36 * only requirement is a full-duplex stream of some kind.
37 *
38 * <example>
39 * <title>Using TLS session objects</title>
40 * <programlisting>
41 * static ssize_t mysock_send(const char *buf, size_t len,
42 * void *opaque)
43 * {
44 * int fd = GPOINTER_TO_INT(opaque);
45 *
46 * return write(*fd, buf, len);
47 * }
48 *
49 * static ssize_t mysock_recv(const char *buf, size_t len,
50 * void *opaque)
51 * {
52 * int fd = GPOINTER_TO_INT(opaque);
53 *
54 * return read(*fd, buf, len);
55 * }
56 *
57 * static int mysock_run_tls(int sockfd,
58 * QCryptoTLSCreds *creds,
59 * Error **errp)
60 * {
61 * QCryptoTLSSession *sess;
62 *
63 * sess = qcrypto_tls_session_new(creds,
64 * "vnc.example.com",
65 * NULL,
66 * QCRYPTO_TLS_CREDS_ENDPOINT_CLIENT,
67 * errp);
68 * if (sess == NULL) {
69 * return -1;
70 * }
71 *
72 * qcrypto_tls_session_set_callbacks(sess,
73 * mysock_send,
74 * mysock_recv
75 * GINT_TO_POINTER(fd));
76 *
77 * while (1) {
78 * if (qcrypto_tls_session_handshake(sess, errp) < 0) {
79 * qcrypto_tls_session_free(sess);
80 * return -1;
81 * }
82 *
83 * switch(qcrypto_tls_session_get_handshake_status(sess)) {
84 * case QCRYPTO_TLS_HANDSHAKE_COMPLETE:
85 * if (qcrypto_tls_session_check_credentials(sess, errp) < )) {
86 * qcrypto_tls_session_free(sess);
87 * return -1;
88 * }
89 * goto done;
90 * case QCRYPTO_TLS_HANDSHAKE_RECVING:
91 * ...wait for GIO_IN event on fd...
92 * break;
93 * case QCRYPTO_TLS_HANDSHAKE_SENDING:
94 * ...wait for GIO_OUT event on fd...
95 * break;
96 * }
97 * }
98 * done:
99 *
100 * ....send/recv payload data on sess...
101 *
102 * qcrypto_tls_session_free(sess):
103 * }
104 * </programlisting>
105 * </example>
106 */
107
108 typedef struct QCryptoTLSSession QCryptoTLSSession;
109
110
111 /**
112 * qcrypto_tls_session_new:
113 * @creds: pointer to a TLS credentials object
114 * @hostname: optional hostname to validate
115 * @aclname: optional ACL to validate peer credentials against
116 * @endpoint: role of the TLS session, client or server
117 * @errp: pointer to a NULL-initialized error object
118 *
119 * Create a new TLS session object that will be used to
120 * negotiate a TLS session over an arbitrary data channel.
121 * The session object can operate as either the server or
122 * client, according to the value of the @endpoint argument.
123 *
124 * For clients, the @hostname parameter should hold the full
125 * unmodified hostname as requested by the user. This will
126 * be used to verify the against the hostname reported in
127 * the server's credentials (aka x509 certificate).
128 *
129 * The @aclname parameter (optionally) specifies the name
130 * of an access control list that will be used to validate
131 * the peer's credentials. For x509 credentials, the ACL
132 * will be matched against the CommonName shown in the peer's
133 * certificate. If the session is acting as a server, setting
134 * an ACL will require that the client provide a validate
135 * x509 client certificate.
136 *
137 * After creating the session object, the I/O callbacks
138 * must be set using the qcrypto_tls_session_set_callbacks()
139 * method. A TLS handshake sequence must then be completed
140 * using qcrypto_tls_session_handshake(), before payload
141 * data is permitted to be sent/received.
142 *
143 * The session object must be released by calling
144 * qcrypto_tls_session_free() when no longer required
145 *
146 * Returns: a TLS session object, or NULL on error.
147 */
148 QCryptoTLSSession *qcrypto_tls_session_new(QCryptoTLSCreds *creds,
149 const char *hostname,
150 const char *aclname,
151 QCryptoTLSCredsEndpoint endpoint,
152 Error **errp);
153
154 /**
155 * qcrypto_tls_session_free:
156 * @sess: the TLS session object
157 *
158 * Release all memory associated with the TLS session
159 * object previously allocated by qcrypto_tls_session_new()
160 */
161 void qcrypto_tls_session_free(QCryptoTLSSession *sess);
162
163 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoTLSSession, qcrypto_tls_session_free)
164
165 /**
166 * qcrypto_tls_session_check_credentials:
167 * @sess: the TLS session object
168 * @errp: pointer to a NULL-initialized error object
169 *
170 * Validate the peer's credentials after a successful
171 * TLS handshake. It is an error to call this before
172 * qcrypto_tls_session_get_handshake_status() returns
173 * QCRYPTO_TLS_HANDSHAKE_COMPLETE
174 *
175 * Returns 0 if the credentials validated, -1 on error
176 */
177 int qcrypto_tls_session_check_credentials(QCryptoTLSSession *sess,
178 Error **errp);
179
180 typedef ssize_t (*QCryptoTLSSessionWriteFunc)(const char *buf,
181 size_t len,
182 void *opaque);
183 typedef ssize_t (*QCryptoTLSSessionReadFunc)(char *buf,
184 size_t len,
185 void *opaque);
186
187 /**
188 * qcrypto_tls_session_set_callbacks:
189 * @sess: the TLS session object
190 * @writeFunc: callback for sending data
191 * @readFunc: callback to receiving data
192 * @opaque: data to pass to callbacks
193 *
194 * Sets the callback functions that are to be used for sending
195 * and receiving data on the underlying data channel. Typically
196 * the callbacks to write/read to/from a TCP socket, but there
197 * is no assumption made about the type of channel used.
198 *
199 * The @writeFunc callback will be passed the encrypted
200 * data to send to the remote peer.
201 *
202 * The @readFunc callback will be passed a pointer to fill
203 * with encrypted data received from the remote peer
204 */
205 void qcrypto_tls_session_set_callbacks(QCryptoTLSSession *sess,
206 QCryptoTLSSessionWriteFunc writeFunc,
207 QCryptoTLSSessionReadFunc readFunc,
208 void *opaque);
209
210 /**
211 * qcrypto_tls_session_write:
212 * @sess: the TLS session object
213 * @buf: the plain text to send
214 * @len: the length of @buf
215 *
216 * Encrypt @len bytes of the data in @buf and send
217 * it to the remote peer using the callback previously
218 * registered with qcrypto_tls_session_set_callbacks()
219 *
220 * It is an error to call this before
221 * qcrypto_tls_session_get_handshake_status() returns
222 * QCRYPTO_TLS_HANDSHAKE_COMPLETE
223 *
224 * Returns: the number of bytes sent, or -1 on error
225 */
226 ssize_t qcrypto_tls_session_write(QCryptoTLSSession *sess,
227 const char *buf,
228 size_t len);
229
230 /**
231 * qcrypto_tls_session_read:
232 * @sess: the TLS session object
233 * @buf: to fill with plain text received
234 * @len: the length of @buf
235 *
236 * Receive up to @len bytes of data from the remote peer
237 * using the callback previously registered with
238 * qcrypto_tls_session_set_callbacks(), decrypt it and
239 * store it in @buf.
240 *
241 * It is an error to call this before
242 * qcrypto_tls_session_get_handshake_status() returns
243 * QCRYPTO_TLS_HANDSHAKE_COMPLETE
244 *
245 * Returns: the number of bytes received, or -1 on error
246 */
247 ssize_t qcrypto_tls_session_read(QCryptoTLSSession *sess,
248 char *buf,
249 size_t len);
250
251 /**
252 * qcrypto_tls_session_handshake:
253 * @sess: the TLS session object
254 * @errp: pointer to a NULL-initialized error object
255 *
256 * Start, or continue, a TLS handshake sequence. If
257 * the underlying data channel is non-blocking, then
258 * this method may return control before the handshake
259 * is complete. On non-blocking channels the
260 * qcrypto_tls_session_get_handshake_status() method
261 * should be used to determine whether the handshake
262 * has completed, or is waiting to send or receive
263 * data. In the latter cases, the caller should setup
264 * an event loop watch and call this method again
265 * once the underlying data channel is ready to read
266 * or write again
267 */
268 int qcrypto_tls_session_handshake(QCryptoTLSSession *sess,
269 Error **errp);
270
271 typedef enum {
272 QCRYPTO_TLS_HANDSHAKE_COMPLETE,
273 QCRYPTO_TLS_HANDSHAKE_SENDING,
274 QCRYPTO_TLS_HANDSHAKE_RECVING,
275 } QCryptoTLSSessionHandshakeStatus;
276
277 /**
278 * qcrypto_tls_session_get_handshake_status:
279 * @sess: the TLS session object
280 *
281 * Check the status of the TLS handshake. This
282 * is used with non-blocking data channels to
283 * determine whether the handshake is waiting
284 * to send or receive further data to/from the
285 * remote peer.
286 *
287 * Once this returns QCRYPTO_TLS_HANDSHAKE_COMPLETE
288 * it is permitted to send/receive payload data on
289 * the channel
290 */
291 QCryptoTLSSessionHandshakeStatus
292 qcrypto_tls_session_get_handshake_status(QCryptoTLSSession *sess);
293
294 /**
295 * qcrypto_tls_session_get_key_size:
296 * @sess: the TLS session object
297 * @errp: pointer to a NULL-initialized error object
298 *
299 * Check the size of the data channel encryption key
300 *
301 * Returns: the length in bytes of the encryption key
302 * or -1 on error
303 */
304 int qcrypto_tls_session_get_key_size(QCryptoTLSSession *sess,
305 Error **errp);
306
307 /**
308 * qcrypto_tls_session_get_peer_name:
309 * @sess: the TLS session object
310 *
311 * Get the identified name of the remote peer. If the
312 * TLS session was negotiated using x509 certificate
313 * credentials, this will return the CommonName from
314 * the peer's certificate. If no identified name is
315 * available it will return NULL.
316 *
317 * The returned data must be released with g_free()
318 * when no longer required.
319 *
320 * Returns: the peer's name or NULL.
321 */
322 char *qcrypto_tls_session_get_peer_name(QCryptoTLSSession *sess);
323
324 #endif /* QCRYPTO_TLSSESSION_H */