Home | History | Annotate | Line # | Download | only in http3 
      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