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 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_TLS_SESSION_H__
  22 #define QCRYPTO_TLS_SESSION_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 *erp)
  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 an uninitialized 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 /**
 164  * qcrypto_tls_session_check_credentials:
 165  * @sess: the TLS session object
 166  * @errp: pointer to an uninitialized error object
 167  *
 168  * Validate the peer's credentials after a successful
 169  * TLS handshake. It is an error to call this before
 170  * qcrypto_tls_session_get_handshake_status() returns
 171  * QCRYPTO_TLS_HANDSHAKE_COMPLETE
 172  *
 173  * Returns 0 if the credentials validated, -1 on error
 174  */
 175 int qcrypto_tls_session_check_credentials(QCryptoTLSSession *sess,
 176                                           Error **errp);
 177
 178 typedef ssize_t (*QCryptoTLSSessionWriteFunc)(const char *buf,
 179                                               size_t len,
 180                                               void *opaque);
 181 typedef ssize_t (*QCryptoTLSSessionReadFunc)(char *buf,
 182                                              size_t len,
 183                                              void *opaque);
 184
 185 /**
 186  * qcrypto_tls_session_set_callbacks:
 187  * @sess: the TLS session object
 188  * @writeFunc: callback for sending data
 189  * @readFunc: callback to receiving data
 190  * @opaque: data to pass to callbacks
 191  *
 192  * Sets the callback functions that are to be used for sending
 193  * and receiving data on the underlying data channel. Typically
 194  * the callbacks to write/read to/from a TCP socket, but there
 195  * is no assumption made about the type of channel used.
 196  *
 197  * The @writeFunc callback will be passed the encrypted
 198  * data to send to the remote peer.
 199  *
 200  * The @readFunc callback will be passed a pointer to fill
 201  * with encrypted data received from the remote peer
 202  */
 203 void qcrypto_tls_session_set_callbacks(QCryptoTLSSession *sess,
 204                                        QCryptoTLSSessionWriteFunc writeFunc,
 205                                        QCryptoTLSSessionReadFunc readFunc,
 206                                        void *opaque);
 207
 208 /**
 209  * qcrypto_tls_session_write:
 210  * @sess: the TLS session object
 211  * @buf: the plain text to send
 212  * @len: the length of @buf
 213  *
 214  * Encrypt @len bytes of the data in @buf and send
 215  * it to the remote peer using the callback previously
 216  * registered with qcrypto_tls_session_set_callbacks()
 217  *
 218  * It is an error to call this before
 219  * qcrypto_tls_session_get_handshake_status() returns
 220  * QCRYPTO_TLS_HANDSHAKE_COMPLETE
 221  *
 222  * Returns: the number of bytes sent, or -1 on error
 223  */
 224 ssize_t qcrypto_tls_session_write(QCryptoTLSSession *sess,
 225                                   const char *buf,
 226                                   size_t len);
 227
 228 /**
 229  * qcrypto_tls_session_read:
 230  * @sess: the TLS session object
 231  * @buf: to fill with plain text received
 232  * @len: the length of @buf
 233  *
 234  * Receive up to @len bytes of data from the remote peer
 235  * using the callback previously registered with
 236  * qcrypto_tls_session_set_callbacks(), decrypt it and
 237  * store it in @buf.
 238  *
 239  * It is an error to call this before
 240  * qcrypto_tls_session_get_handshake_status() returns
 241  * QCRYPTO_TLS_HANDSHAKE_COMPLETE
 242  *
 243  * Returns: the number of bytes received, or -1 on error
 244  */
 245 ssize_t qcrypto_tls_session_read(QCryptoTLSSession *sess,
 246                                  char *buf,
 247                                  size_t len);
 248
 249 /**
 250  * qcrypto_tls_session_handshake:
 251  * @sess: the TLS session object
 252  * @errp: pointer to an uninitialized error object
 253  *
 254  * Start, or continue, a TLS handshake sequence. If
 255  * the underlying data channel is non-blocking, then
 256  * this method may return control before the handshake
 257  * is complete. On non-blocking channels the
 258  * qcrypto_tls_session_get_handshake_status() method
 259  * should be used to determine whether the handshake
 260  * has completed, or is waiting to send or receive
 261  * data. In the latter cases, the caller should setup
 262  * an event loop watch and call this method again
 263  * once the underlying data channel is ready to read
 264  * or write again
 265  */
 266 int qcrypto_tls_session_handshake(QCryptoTLSSession *sess,
 267                                   Error **errp);
 268
 269 typedef enum {
 270     QCRYPTO_TLS_HANDSHAKE_COMPLETE,
 271     QCRYPTO_TLS_HANDSHAKE_SENDING,
 272     QCRYPTO_TLS_HANDSHAKE_RECVING,
 273 } QCryptoTLSSessionHandshakeStatus;
 274
 275 /**
 276  * qcrypto_tls_session_get_handshake_status:
 277  * @sess: the TLS session object
 278  *
 279  * Check the status of the TLS handshake. This
 280  * is used with non-blocking data channels to
 281  * determine whether the handshake is waiting
 282  * to send or receive further data to/from the
 283  * remote peer.
 284  *
 285  * Once this returns QCRYPTO_TLS_HANDSHAKE_COMPLETE
 286  * it is permitted to send/receive payload data on
 287  * the channel
 288  */
 289 QCryptoTLSSessionHandshakeStatus
 290 qcrypto_tls_session_get_handshake_status(QCryptoTLSSession *sess);
 291
 292 /**
 293  * qcrypto_tls_session_get_key_size:
 294  * @sess: the TLS session object
 295  * @errp: pointer to an uninitialized error object
 296  *
 297  * Check the size of the data channel encryption key
 298  *
 299  * Returns: the length in bytes of the encryption key
 300  * or -1 on error
 301  */
 302 int qcrypto_tls_session_get_key_size(QCryptoTLSSession *sess,
 303                                      Error **errp);
 304
 305 /**
 306  * qcrypto_tls_session_get_peer_name:
 307  * @sess: the TLS session object
 308  *
 309  * Get the identified name of the remote peer. If the
 310  * TLS session was negotiated using x509 certificate
 311  * credentials, this will return the CommonName from
 312  * the peer's certificate. If no identified name is
 313  * available it will return NULL.
 314  *
 315  * The returned data must be released with g_free()
 316  * when no longer required.
 317  *
 318  * Returns: the peer's name or NULL.
 319  */
 320 char *qcrypto_tls_session_get_peer_name(QCryptoTLSSession *sess);
 321
 322 #endif /* QCRYPTO_TLS_SESSION_H__ */