1 /* 2 * Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the Apache License 2.0 (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 #ifndef OSSL_NGHTTP3_H 10 # define OSSL_NGHTTP3_H 11 12 # include <openssl/bio.h> 13 # include <openssl/ssl.h> 14 # include <nghttp3/nghttp3.h> 15 16 /* 17 * ossl-nghttp3: Demo binding of nghttp3 to OpenSSL QUIC 18 * ===================================================== 19 * 20 * This is a simple library which provides an example binding of the nghttp3 21 * HTTP/3 library to OpenSSL's QUIC API. 22 */ 23 24 /* Represents an HTTP/3 connection to a server. */ 25 typedef struct ossl_demo_h3_conn_st OSSL_DEMO_H3_CONN; 26 27 /* Represents an HTTP/3 request, control or QPACK stream. */ 28 typedef struct ossl_demo_h3_stream_st OSSL_DEMO_H3_STREAM; 29 30 /* 31 * Creates a HTTP/3 connection using the given QUIC client connection BIO. The 32 * BIO must be able to provide an SSL object pointer using BIO_get_ssl. Takes 33 * ownership of the reference. If the QUIC connection SSL object has not already 34 * been connected, HTTP/3 ALPN is set automatically. If it has already been 35 * connected, HTTP/3 ALPN ("h3") must have been configured and no streams must 36 * have been created yet. 37 * 38 * If settings is NULL, use default settings only. Settings unsupported by 39 * this QUIC binding are ignored. 40 * 41 * user_data is an application-provided opaque value which can be retrieved 42 * using OSSL_DEMO_H3_CONN_get_user_data. Note that the user data value passed 43 * to the callback functions specified in callbacks is a pointer to the 44 * OSSL_DEMO_H3_CONN, not user_data. 45 * 46 * Returns NULL on failure. 47 */ 48 OSSL_DEMO_H3_CONN *OSSL_DEMO_H3_CONN_new_for_conn(BIO *qconn_bio, 49 const nghttp3_callbacks *callbacks, 50 const nghttp3_settings *settings, 51 void *user_data); 52 53 /* 54 * Works identically to OSSL_DEMO_H3_CONN_new_for_conn except that it manages 55 * the creation of a QUIC connection SSL object automatically using an address 56 * string. addr should be a string such as "www.example.com:443". The created 57 * underlying QUIC connection SSL object is owned by the OSSL_DEMO_H3_CONN and 58 * can be subsequently retrieved using OSSL_DEMO_H3_CONN_get0_connection. 59 * 60 * Returns NULL on failure. ctx must be an SSL_CTX using a QUIC client 61 * SSL_METHOD. 62 */ 63 OSSL_DEMO_H3_CONN *OSSL_DEMO_H3_CONN_new_for_addr(SSL_CTX *ctx, 64 const char *addr, 65 const nghttp3_callbacks *callbacks, 66 const nghttp3_settings *settings, 67 void *user_data); 68 69 /* Equivalent to SSL_connect(OSSL_DEMO_H3_CONN_get0_connection(conn)). */ 70 int OSSL_DEMO_H3_CONN_connect(OSSL_DEMO_H3_CONN *conn); 71 72 /* 73 * Free the OSSL_DEMO_H3_CONN and any underlying QUIC connection SSL object and 74 * associated streams. 75 */ 76 void OSSL_DEMO_H3_CONN_free(OSSL_DEMO_H3_CONN *conn); 77 78 /* 79 * Returns the user data value which was specified in 80 * OSSL_DEMO_H3_CONN_new_for_conn. 81 */ 82 void *OSSL_DEMO_H3_CONN_get_user_data(const OSSL_DEMO_H3_CONN *conn); 83 84 /* Returns the underlying QUIC connection SSL object. */ 85 SSL *OSSL_DEMO_H3_CONN_get0_connection(const OSSL_DEMO_H3_CONN *conn); 86 87 /* 88 * Handle any pending events on a given HTTP/3 connection. Returns 0 on error. 89 */ 90 int OSSL_DEMO_H3_CONN_handle_events(OSSL_DEMO_H3_CONN *conn); 91 92 /* 93 * Submits a new HTTP/3 request on the given connection. Returns 0 on error. 94 * 95 * This works analogously to nghttp3_conn_submit_request(). The stream user data 96 * pointer passed to the callbacks is a OSSL_DEMO_H3_STREAM object pointer; to 97 * retrieve the stream user data pointer passed to this function, use 98 * OSSL_DEMO_H3_STREAM_get_user_data. 99 */ 100 int OSSL_DEMO_H3_CONN_submit_request(OSSL_DEMO_H3_CONN *conn, 101 const nghttp3_nv *hdr, size_t hdrlen, 102 const nghttp3_data_reader *dr, 103 void *stream_user_data); 104 105 /* 106 * Returns the user data value which was specified in 107 * OSSL_DEMO_H3_CONN_submit_request. 108 */ 109 void *OSSL_DEMO_H3_STREAM_get_user_data(const OSSL_DEMO_H3_STREAM *stream); 110 111 #endif 112
