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 */