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 *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 /** 164 * qcrypto_tls_session_check_credentials: 165 * @sess: the TLS session object 166 * @errp: pointer to a NULL-initialized 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 a NULL-initialized 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 a NULL-initialized 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__ */ 323