xref: /openbmc/qemu/include/crypto/tlssession.h (revision 9726687f2fdfe7ae4a3014d78c2b2f639f75e303)
1d321e1e5SDaniel P. Berrange /*
2d321e1e5SDaniel P. Berrange  * QEMU crypto TLS session support
3d321e1e5SDaniel P. Berrange  *
4d321e1e5SDaniel P. Berrange  * Copyright (c) 2015 Red Hat, Inc.
5d321e1e5SDaniel P. Berrange  *
6d321e1e5SDaniel P. Berrange  * This library is free software; you can redistribute it and/or
7d321e1e5SDaniel P. Berrange  * modify it under the terms of the GNU Lesser General Public
8d321e1e5SDaniel P. Berrange  * License as published by the Free Software Foundation; either
9b7cbb874SThomas Huth  * version 2.1 of the License, or (at your option) any later version.
10d321e1e5SDaniel P. Berrange  *
11d321e1e5SDaniel P. Berrange  * This library is distributed in the hope that it will be useful,
12d321e1e5SDaniel P. Berrange  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13d321e1e5SDaniel P. Berrange  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14d321e1e5SDaniel P. Berrange  * Lesser General Public License for more details.
15d321e1e5SDaniel P. Berrange  *
16d321e1e5SDaniel P. Berrange  * You should have received a copy of the GNU Lesser General Public
17d321e1e5SDaniel P. Berrange  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18d321e1e5SDaniel P. Berrange  *
19d321e1e5SDaniel P. Berrange  */
20d321e1e5SDaniel P. Berrange 
21121d0712SMarkus Armbruster #ifndef QCRYPTO_TLSSESSION_H
22121d0712SMarkus Armbruster #define QCRYPTO_TLSSESSION_H
23d321e1e5SDaniel P. Berrange 
24d321e1e5SDaniel P. Berrange #include "crypto/tlscreds.h"
25d321e1e5SDaniel P. Berrange 
26d321e1e5SDaniel P. Berrange /**
27d321e1e5SDaniel P. Berrange  * QCryptoTLSSession:
28d321e1e5SDaniel P. Berrange  *
29d321e1e5SDaniel P. Berrange  * The QCryptoTLSSession object encapsulates the
30d321e1e5SDaniel P. Berrange  * logic to integrate with a TLS providing library such
31d321e1e5SDaniel P. Berrange  * as GNUTLS, to setup and run TLS sessions.
32d321e1e5SDaniel P. Berrange  *
33d321e1e5SDaniel P. Berrange  * The API is designed such that it has no assumption about
34d321e1e5SDaniel P. Berrange  * the type of transport it is running over. It may be a
35d321e1e5SDaniel P. Berrange  * traditional TCP socket, or something else entirely. The
36d321e1e5SDaniel P. Berrange  * only requirement is a full-duplex stream of some kind.
37d321e1e5SDaniel P. Berrange  *
38d321e1e5SDaniel P. Berrange  * <example>
39d321e1e5SDaniel P. Berrange  *   <title>Using TLS session objects</title>
40d321e1e5SDaniel P. Berrange  *   <programlisting>
41d321e1e5SDaniel P. Berrange  * static ssize_t mysock_send(const char *buf, size_t len,
42d321e1e5SDaniel P. Berrange  *                            void *opaque)
43d321e1e5SDaniel P. Berrange  * {
44d321e1e5SDaniel P. Berrange  *    int fd = GPOINTER_TO_INT(opaque);
45d321e1e5SDaniel P. Berrange  *
46d321e1e5SDaniel P. Berrange  *    return write(*fd, buf, len);
47d321e1e5SDaniel P. Berrange  * }
48d321e1e5SDaniel P. Berrange  *
49d321e1e5SDaniel P. Berrange  * static ssize_t mysock_recv(const char *buf, size_t len,
50d321e1e5SDaniel P. Berrange  *                            void *opaque)
51d321e1e5SDaniel P. Berrange  * {
52d321e1e5SDaniel P. Berrange  *    int fd = GPOINTER_TO_INT(opaque);
53d321e1e5SDaniel P. Berrange  *
54d321e1e5SDaniel P. Berrange  *    return read(*fd, buf, len);
55d321e1e5SDaniel P. Berrange  * }
56d321e1e5SDaniel P. Berrange  *
57d321e1e5SDaniel P. Berrange  * static int mysock_run_tls(int sockfd,
58d321e1e5SDaniel P. Berrange  *                           QCryptoTLSCreds *creds,
59118bf79aSMarkus Armbruster  *                           Error **errp)
60d321e1e5SDaniel P. Berrange  * {
61d321e1e5SDaniel P. Berrange  *    QCryptoTLSSession *sess;
62d321e1e5SDaniel P. Berrange  *
63d321e1e5SDaniel P. Berrange  *    sess = qcrypto_tls_session_new(creds,
64d321e1e5SDaniel P. Berrange  *                                   "vnc.example.com",
65d321e1e5SDaniel P. Berrange  *                                   NULL,
66d321e1e5SDaniel P. Berrange  *                                   QCRYPTO_TLS_CREDS_ENDPOINT_CLIENT,
67d321e1e5SDaniel P. Berrange  *                                   errp);
68d321e1e5SDaniel P. Berrange  *    if (sess == NULL) {
69d321e1e5SDaniel P. Berrange  *       return -1;
70d321e1e5SDaniel P. Berrange  *    }
71d321e1e5SDaniel P. Berrange  *
72d321e1e5SDaniel P. Berrange  *    qcrypto_tls_session_set_callbacks(sess,
73d321e1e5SDaniel P. Berrange  *                                      mysock_send,
74d321e1e5SDaniel P. Berrange  *                                      mysock_recv
75d321e1e5SDaniel P. Berrange  *                                      GINT_TO_POINTER(fd));
76d321e1e5SDaniel P. Berrange  *
77d321e1e5SDaniel P. Berrange  *    while (1) {
78d321e1e5SDaniel P. Berrange  *       if (qcrypto_tls_session_handshake(sess, errp) < 0) {
79d321e1e5SDaniel P. Berrange  *           qcrypto_tls_session_free(sess);
80d321e1e5SDaniel P. Berrange  *           return -1;
81d321e1e5SDaniel P. Berrange  *       }
82d321e1e5SDaniel P. Berrange  *
83d321e1e5SDaniel P. Berrange  *       switch(qcrypto_tls_session_get_handshake_status(sess)) {
84d321e1e5SDaniel P. Berrange  *       case QCRYPTO_TLS_HANDSHAKE_COMPLETE:
85d321e1e5SDaniel P. Berrange  *           if (qcrypto_tls_session_check_credentials(sess, errp) < )) {
86d321e1e5SDaniel P. Berrange  *               qcrypto_tls_session_free(sess);
87d321e1e5SDaniel P. Berrange  *               return -1;
88d321e1e5SDaniel P. Berrange  *           }
89d321e1e5SDaniel P. Berrange  *           goto done;
90d321e1e5SDaniel P. Berrange  *       case QCRYPTO_TLS_HANDSHAKE_RECVING:
91d321e1e5SDaniel P. Berrange  *           ...wait for GIO_IN event on fd...
92d321e1e5SDaniel P. Berrange  *           break;
93d321e1e5SDaniel P. Berrange  *       case QCRYPTO_TLS_HANDSHAKE_SENDING:
94d321e1e5SDaniel P. Berrange  *           ...wait for GIO_OUT event on fd...
95d321e1e5SDaniel P. Berrange  *           break;
96d321e1e5SDaniel P. Berrange  *       }
97d321e1e5SDaniel P. Berrange  *    }
98d321e1e5SDaniel P. Berrange  *   done:
99d321e1e5SDaniel P. Berrange  *
100d321e1e5SDaniel P. Berrange  *    ....send/recv payload data on sess...
101d321e1e5SDaniel P. Berrange  *
102d321e1e5SDaniel P. Berrange  *    qcrypto_tls_session_free(sess):
103d321e1e5SDaniel P. Berrange  * }
104d321e1e5SDaniel P. Berrange  *   </programlisting>
105d321e1e5SDaniel P. Berrange  * </example>
106d321e1e5SDaniel P. Berrange  */
107d321e1e5SDaniel P. Berrange 
108d321e1e5SDaniel P. Berrange typedef struct QCryptoTLSSession QCryptoTLSSession;
109d321e1e5SDaniel P. Berrange 
11057941c9cSDaniel P. Berrangé #define QCRYPTO_TLS_SESSION_ERR_BLOCK -2
111d321e1e5SDaniel P. Berrange 
112d321e1e5SDaniel P. Berrange /**
113d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_new:
114d321e1e5SDaniel P. Berrange  * @creds: pointer to a TLS credentials object
115d321e1e5SDaniel P. Berrange  * @hostname: optional hostname to validate
116d321e1e5SDaniel P. Berrange  * @aclname: optional ACL to validate peer credentials against
117d321e1e5SDaniel P. Berrange  * @endpoint: role of the TLS session, client or server
11807982d2eSDaniel P. Berrange  * @errp: pointer to a NULL-initialized error object
119d321e1e5SDaniel P. Berrange  *
120d321e1e5SDaniel P. Berrange  * Create a new TLS session object that will be used to
121d321e1e5SDaniel P. Berrange  * negotiate a TLS session over an arbitrary data channel.
122d321e1e5SDaniel P. Berrange  * The session object can operate as either the server or
123d321e1e5SDaniel P. Berrange  * client, according to the value of the @endpoint argument.
124d321e1e5SDaniel P. Berrange  *
125d321e1e5SDaniel P. Berrange  * For clients, the @hostname parameter should hold the full
126d321e1e5SDaniel P. Berrange  * unmodified hostname as requested by the user. This will
127d321e1e5SDaniel P. Berrange  * be used to verify the against the hostname reported in
128d321e1e5SDaniel P. Berrange  * the server's credentials (aka x509 certificate).
129d321e1e5SDaniel P. Berrange  *
130d321e1e5SDaniel P. Berrange  * The @aclname parameter (optionally) specifies the name
131d321e1e5SDaniel P. Berrange  * of an access control list that will be used to validate
132d321e1e5SDaniel P. Berrange  * the peer's credentials. For x509 credentials, the ACL
133d321e1e5SDaniel P. Berrange  * will be matched against the CommonName shown in the peer's
134d321e1e5SDaniel P. Berrange  * certificate. If the session is acting as a server, setting
135d321e1e5SDaniel P. Berrange  * an ACL will require that the client provide a validate
136d321e1e5SDaniel P. Berrange  * x509 client certificate.
137d321e1e5SDaniel P. Berrange  *
138d321e1e5SDaniel P. Berrange  * After creating the session object, the I/O callbacks
139d321e1e5SDaniel P. Berrange  * must be set using the qcrypto_tls_session_set_callbacks()
140d321e1e5SDaniel P. Berrange  * method. A TLS handshake sequence must then be completed
141d321e1e5SDaniel P. Berrange  * using qcrypto_tls_session_handshake(), before payload
142d321e1e5SDaniel P. Berrange  * data is permitted to be sent/received.
143d321e1e5SDaniel P. Berrange  *
144d321e1e5SDaniel P. Berrange  * The session object must be released by calling
145d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_free() when no longer required
146d321e1e5SDaniel P. Berrange  *
147d321e1e5SDaniel P. Berrange  * Returns: a TLS session object, or NULL on error.
148d321e1e5SDaniel P. Berrange  */
149d321e1e5SDaniel P. Berrange QCryptoTLSSession *qcrypto_tls_session_new(QCryptoTLSCreds *creds,
150d321e1e5SDaniel P. Berrange                                            const char *hostname,
151d321e1e5SDaniel P. Berrange                                            const char *aclname,
152d321e1e5SDaniel P. Berrange                                            QCryptoTLSCredsEndpoint endpoint,
153d321e1e5SDaniel P. Berrange                                            Error **errp);
154d321e1e5SDaniel P. Berrange 
155d321e1e5SDaniel P. Berrange /**
156d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_free:
157d321e1e5SDaniel P. Berrange  * @sess: the TLS session object
158d321e1e5SDaniel P. Berrange  *
159d321e1e5SDaniel P. Berrange  * Release all memory associated with the TLS session
160d321e1e5SDaniel P. Berrange  * object previously allocated by qcrypto_tls_session_new()
161d321e1e5SDaniel P. Berrange  */
162d321e1e5SDaniel P. Berrange void qcrypto_tls_session_free(QCryptoTLSSession *sess);
163d321e1e5SDaniel P. Berrange 
164133cf1e5SDaniel P. Berrangé G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoTLSSession, qcrypto_tls_session_free)
165133cf1e5SDaniel P. Berrangé 
166d321e1e5SDaniel P. Berrange /**
167d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_check_credentials:
168d321e1e5SDaniel P. Berrange  * @sess: the TLS session object
16907982d2eSDaniel P. Berrange  * @errp: pointer to a NULL-initialized error object
170d321e1e5SDaniel P. Berrange  *
171d321e1e5SDaniel P. Berrange  * Validate the peer's credentials after a successful
172d321e1e5SDaniel P. Berrange  * TLS handshake. It is an error to call this before
173d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_get_handshake_status() returns
174d321e1e5SDaniel P. Berrange  * QCRYPTO_TLS_HANDSHAKE_COMPLETE
175d321e1e5SDaniel P. Berrange  *
176d321e1e5SDaniel P. Berrange  * Returns 0 if the credentials validated, -1 on error
177d321e1e5SDaniel P. Berrange  */
178d321e1e5SDaniel P. Berrange int qcrypto_tls_session_check_credentials(QCryptoTLSSession *sess,
179d321e1e5SDaniel P. Berrange                                           Error **errp);
180d321e1e5SDaniel P. Berrange 
181*97f7bf11SDaniel P. Berrangé /*
182*97f7bf11SDaniel P. Berrangé  * These must return QCRYPTO_TLS_SESSION_ERR_BLOCK if the I/O
183*97f7bf11SDaniel P. Berrangé  * would block, but on other errors, must fill 'errp'
184*97f7bf11SDaniel P. Berrangé  */
185d321e1e5SDaniel P. Berrange typedef ssize_t (*QCryptoTLSSessionWriteFunc)(const char *buf,
186d321e1e5SDaniel P. Berrange                                               size_t len,
187*97f7bf11SDaniel P. Berrangé                                               void *opaque,
188*97f7bf11SDaniel P. Berrangé                                               Error **errp);
189d321e1e5SDaniel P. Berrange typedef ssize_t (*QCryptoTLSSessionReadFunc)(char *buf,
190d321e1e5SDaniel P. Berrange                                              size_t len,
191*97f7bf11SDaniel P. Berrangé                                              void *opaque,
192*97f7bf11SDaniel P. Berrangé                                              Error **errp);
193d321e1e5SDaniel P. Berrange 
194d321e1e5SDaniel P. Berrange /**
195d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_set_callbacks:
196d321e1e5SDaniel P. Berrange  * @sess: the TLS session object
197d321e1e5SDaniel P. Berrange  * @writeFunc: callback for sending data
198d321e1e5SDaniel P. Berrange  * @readFunc: callback to receiving data
199d321e1e5SDaniel P. Berrange  * @opaque: data to pass to callbacks
200d321e1e5SDaniel P. Berrange  *
201d321e1e5SDaniel P. Berrange  * Sets the callback functions that are to be used for sending
202d321e1e5SDaniel P. Berrange  * and receiving data on the underlying data channel. Typically
203d321e1e5SDaniel P. Berrange  * the callbacks to write/read to/from a TCP socket, but there
204d321e1e5SDaniel P. Berrange  * is no assumption made about the type of channel used.
205d321e1e5SDaniel P. Berrange  *
206d321e1e5SDaniel P. Berrange  * The @writeFunc callback will be passed the encrypted
207d321e1e5SDaniel P. Berrange  * data to send to the remote peer.
208d321e1e5SDaniel P. Berrange  *
209d321e1e5SDaniel P. Berrange  * The @readFunc callback will be passed a pointer to fill
210d321e1e5SDaniel P. Berrange  * with encrypted data received from the remote peer
211d321e1e5SDaniel P. Berrange  */
212d321e1e5SDaniel P. Berrange void qcrypto_tls_session_set_callbacks(QCryptoTLSSession *sess,
213d321e1e5SDaniel P. Berrange                                        QCryptoTLSSessionWriteFunc writeFunc,
214d321e1e5SDaniel P. Berrange                                        QCryptoTLSSessionReadFunc readFunc,
215d321e1e5SDaniel P. Berrange                                        void *opaque);
216d321e1e5SDaniel P. Berrange 
217d321e1e5SDaniel P. Berrange /**
218d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_write:
219d321e1e5SDaniel P. Berrange  * @sess: the TLS session object
220d321e1e5SDaniel P. Berrange  * @buf: the plain text to send
221d321e1e5SDaniel P. Berrange  * @len: the length of @buf
22257941c9cSDaniel P. Berrangé  * @errp: pointer to hold returned error object
223d321e1e5SDaniel P. Berrange  *
224d321e1e5SDaniel P. Berrange  * Encrypt @len bytes of the data in @buf and send
225d321e1e5SDaniel P. Berrange  * it to the remote peer using the callback previously
226d321e1e5SDaniel P. Berrange  * registered with qcrypto_tls_session_set_callbacks()
227d321e1e5SDaniel P. Berrange  *
228d321e1e5SDaniel P. Berrange  * It is an error to call this before
229d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_get_handshake_status() returns
230d321e1e5SDaniel P. Berrange  * QCRYPTO_TLS_HANDSHAKE_COMPLETE
231d321e1e5SDaniel P. Berrange  *
23257941c9cSDaniel P. Berrangé  * Returns: the number of bytes sent,
23357941c9cSDaniel P. Berrangé  * or QCRYPTO_TLS_SESSION_ERR_BLOCK if the write would block,
23457941c9cSDaniel P. Berrangé  * or -1 on error.
235d321e1e5SDaniel P. Berrange  */
236d321e1e5SDaniel P. Berrange ssize_t qcrypto_tls_session_write(QCryptoTLSSession *sess,
237d321e1e5SDaniel P. Berrange                                   const char *buf,
23857941c9cSDaniel P. Berrangé                                   size_t len,
23957941c9cSDaniel P. Berrangé                                   Error **errp);
240d321e1e5SDaniel P. Berrange 
241d321e1e5SDaniel P. Berrange /**
242d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_read:
243d321e1e5SDaniel P. Berrange  * @sess: the TLS session object
244d321e1e5SDaniel P. Berrange  * @buf: to fill with plain text received
245d321e1e5SDaniel P. Berrange  * @len: the length of @buf
24657941c9cSDaniel P. Berrangé  * @gracefulTermination: treat premature termination as graceful EOF
24757941c9cSDaniel P. Berrangé  * @errp: pointer to hold returned error object
248d321e1e5SDaniel P. Berrange  *
249d321e1e5SDaniel P. Berrange  * Receive up to @len bytes of data from the remote peer
250d321e1e5SDaniel P. Berrange  * using the callback previously registered with
251d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_set_callbacks(), decrypt it and
252d321e1e5SDaniel P. Berrange  * store it in @buf.
253d321e1e5SDaniel P. Berrange  *
25457941c9cSDaniel P. Berrangé  * If @gracefulTermination is true, then a premature termination
25557941c9cSDaniel P. Berrangé  * of the TLS session will be treated as indicating EOF, as
25657941c9cSDaniel P. Berrangé  * opposed to an error.
25757941c9cSDaniel P. Berrangé  *
258d321e1e5SDaniel P. Berrange  * It is an error to call this before
259d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_get_handshake_status() returns
260d321e1e5SDaniel P. Berrange  * QCRYPTO_TLS_HANDSHAKE_COMPLETE
261d321e1e5SDaniel P. Berrange  *
26257941c9cSDaniel P. Berrangé  * Returns: the number of bytes received,
26357941c9cSDaniel P. Berrangé  * or QCRYPTO_TLS_SESSION_ERR_BLOCK if the receive would block,
26457941c9cSDaniel P. Berrangé  * or -1 on error.
265d321e1e5SDaniel P. Berrange  */
266d321e1e5SDaniel P. Berrange ssize_t qcrypto_tls_session_read(QCryptoTLSSession *sess,
267d321e1e5SDaniel P. Berrange                                  char *buf,
26857941c9cSDaniel P. Berrangé                                  size_t len,
26957941c9cSDaniel P. Berrangé                                  bool gracefulTermination,
27057941c9cSDaniel P. Berrangé                                  Error **errp);
271d321e1e5SDaniel P. Berrange 
272d321e1e5SDaniel P. Berrange /**
27333ee0d8eSAntoine Damhet  * qcrypto_tls_session_check_pending:
27433ee0d8eSAntoine Damhet  * @sess: the TLS session object
27533ee0d8eSAntoine Damhet  *
27633ee0d8eSAntoine Damhet  * Check if there are unread data in the TLS buffers that have
27733ee0d8eSAntoine Damhet  * already been read from the underlying data source.
27833ee0d8eSAntoine Damhet  *
27933ee0d8eSAntoine Damhet  * Returns: the number of bytes available or zero
28033ee0d8eSAntoine Damhet  */
28133ee0d8eSAntoine Damhet size_t qcrypto_tls_session_check_pending(QCryptoTLSSession *sess);
28233ee0d8eSAntoine Damhet 
28333ee0d8eSAntoine Damhet /**
284d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_handshake:
285d321e1e5SDaniel P. Berrange  * @sess: the TLS session object
28607982d2eSDaniel P. Berrange  * @errp: pointer to a NULL-initialized error object
287d321e1e5SDaniel P. Berrange  *
288d321e1e5SDaniel P. Berrange  * Start, or continue, a TLS handshake sequence. If
289d321e1e5SDaniel P. Berrange  * the underlying data channel is non-blocking, then
290d321e1e5SDaniel P. Berrange  * this method may return control before the handshake
291d321e1e5SDaniel P. Berrange  * is complete. On non-blocking channels the
292d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_get_handshake_status() method
293d321e1e5SDaniel P. Berrange  * should be used to determine whether the handshake
294d321e1e5SDaniel P. Berrange  * has completed, or is waiting to send or receive
295d321e1e5SDaniel P. Berrange  * data. In the latter cases, the caller should setup
296d321e1e5SDaniel P. Berrange  * an event loop watch and call this method again
297d321e1e5SDaniel P. Berrange  * once the underlying data channel is ready to read
298d321e1e5SDaniel P. Berrange  * or write again
299d321e1e5SDaniel P. Berrange  */
300d321e1e5SDaniel P. Berrange int qcrypto_tls_session_handshake(QCryptoTLSSession *sess,
301d321e1e5SDaniel P. Berrange                                   Error **errp);
302d321e1e5SDaniel P. Berrange 
303d321e1e5SDaniel P. Berrange typedef enum {
304d321e1e5SDaniel P. Berrange     QCRYPTO_TLS_HANDSHAKE_COMPLETE,
305d321e1e5SDaniel P. Berrange     QCRYPTO_TLS_HANDSHAKE_SENDING,
306d321e1e5SDaniel P. Berrange     QCRYPTO_TLS_HANDSHAKE_RECVING,
307d321e1e5SDaniel P. Berrange } QCryptoTLSSessionHandshakeStatus;
308d321e1e5SDaniel P. Berrange 
309d321e1e5SDaniel P. Berrange /**
310d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_get_handshake_status:
311d321e1e5SDaniel P. Berrange  * @sess: the TLS session object
312d321e1e5SDaniel P. Berrange  *
313d321e1e5SDaniel P. Berrange  * Check the status of the TLS handshake. This
314d321e1e5SDaniel P. Berrange  * is used with non-blocking data channels to
315d321e1e5SDaniel P. Berrange  * determine whether the handshake is waiting
316d321e1e5SDaniel P. Berrange  * to send or receive further data to/from the
317d321e1e5SDaniel P. Berrange  * remote peer.
318d321e1e5SDaniel P. Berrange  *
319d321e1e5SDaniel P. Berrange  * Once this returns QCRYPTO_TLS_HANDSHAKE_COMPLETE
320d321e1e5SDaniel P. Berrange  * it is permitted to send/receive payload data on
321d321e1e5SDaniel P. Berrange  * the channel
322d321e1e5SDaniel P. Berrange  */
323d321e1e5SDaniel P. Berrange QCryptoTLSSessionHandshakeStatus
324d321e1e5SDaniel P. Berrange qcrypto_tls_session_get_handshake_status(QCryptoTLSSession *sess);
325d321e1e5SDaniel P. Berrange 
326d321e1e5SDaniel P. Berrange /**
327d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_get_key_size:
328d321e1e5SDaniel P. Berrange  * @sess: the TLS session object
32907982d2eSDaniel P. Berrange  * @errp: pointer to a NULL-initialized error object
330d321e1e5SDaniel P. Berrange  *
331d321e1e5SDaniel P. Berrange  * Check the size of the data channel encryption key
332d321e1e5SDaniel P. Berrange  *
333d321e1e5SDaniel P. Berrange  * Returns: the length in bytes of the encryption key
334d321e1e5SDaniel P. Berrange  * or -1 on error
335d321e1e5SDaniel P. Berrange  */
336d321e1e5SDaniel P. Berrange int qcrypto_tls_session_get_key_size(QCryptoTLSSession *sess,
337d321e1e5SDaniel P. Berrange                                      Error **errp);
338d321e1e5SDaniel P. Berrange 
339d321e1e5SDaniel P. Berrange /**
340d321e1e5SDaniel P. Berrange  * qcrypto_tls_session_get_peer_name:
341d321e1e5SDaniel P. Berrange  * @sess: the TLS session object
342d321e1e5SDaniel P. Berrange  *
343d321e1e5SDaniel P. Berrange  * Get the identified name of the remote peer. If the
344d321e1e5SDaniel P. Berrange  * TLS session was negotiated using x509 certificate
345d321e1e5SDaniel P. Berrange  * credentials, this will return the CommonName from
346d321e1e5SDaniel P. Berrange  * the peer's certificate. If no identified name is
347d321e1e5SDaniel P. Berrange  * available it will return NULL.
348d321e1e5SDaniel P. Berrange  *
349d321e1e5SDaniel P. Berrange  * The returned data must be released with g_free()
350d321e1e5SDaniel P. Berrange  * when no longer required.
351d321e1e5SDaniel P. Berrange  *
352d321e1e5SDaniel P. Berrange  * Returns: the peer's name or NULL.
353d321e1e5SDaniel P. Berrange  */
354d321e1e5SDaniel P. Berrange char *qcrypto_tls_session_get_peer_name(QCryptoTLSSession *sess);
355d321e1e5SDaniel P. Berrange 
356121d0712SMarkus Armbruster #endif /* QCRYPTO_TLSSESSION_H */
357