From ec36534cbbf57999b90cbb36404d9daa599a9ae4 Mon Sep 17 00:00:00 2001 From: Hugo Landau Date: Tue, 29 Mar 2022 13:53:58 +0100 Subject: [PATCH] Add initial demo-driven design demos Reviewed-by: Paul Dale Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/17991) --- doc/designs/ddd/Makefile | 24 + doc/designs/ddd/README.md | 115 +++++ doc/designs/ddd/WINDOWS.md | 80 +++ doc/designs/ddd/ddd-01-conn-blocking.c | 161 ++++++ doc/designs/ddd/ddd-02-conn-nonblocking.c | 289 +++++++++++ doc/designs/ddd/ddd-03-fd-blocking.c | 188 +++++++ doc/designs/ddd/ddd-04-fd-nonblocking.c | 323 ++++++++++++ doc/designs/ddd/ddd-05-mem-nonblocking.c | 408 +++++++++++++++ doc/designs/ddd/ddd-06-mem-uv.c | 599 ++++++++++++++++++++++ util/markdownlint.rb | 2 + 10 files changed, 2189 insertions(+) create mode 100644 doc/designs/ddd/Makefile create mode 100644 doc/designs/ddd/README.md create mode 100644 doc/designs/ddd/WINDOWS.md create mode 100644 doc/designs/ddd/ddd-01-conn-blocking.c create mode 100644 doc/designs/ddd/ddd-02-conn-nonblocking.c create mode 100644 doc/designs/ddd/ddd-03-fd-blocking.c create mode 100644 doc/designs/ddd/ddd-04-fd-nonblocking.c create mode 100644 doc/designs/ddd/ddd-05-mem-nonblocking.c create mode 100644 doc/designs/ddd/ddd-06-mem-uv.c diff --git a/doc/designs/ddd/Makefile b/doc/designs/ddd/Makefile new file mode 100644 index 00000000000..0671f4ed731 --- /dev/null +++ b/doc/designs/ddd/Makefile @@ -0,0 +1,24 @@ +# +# To run the demos when linked with a shared library (default): +# +# LD_LIBRARY_PATH=../.. make test + +TESTS=ddd-01-conn-blocking ddd-02-conn-nonblocking ddd-03-fd-blocking ddd-04-fd-nonblocking ddd-05-mem-nonblocking ddd-06-mem-uv + +CFLAGS = -I../include -O3 -g -Wall +LDFLAGS = -L.. +LDLIBS = -lcrypto -lssl + +all: $(TESTS) + +clean: + rm -f $(TESTS) *.o + +test: all + for x in $(TESTS); do echo "$$x"; LD_LIBRARY_PATH="$$(pwd)/.." ./$$x | grep -q '' || { echo >&2 'Error'; exit 1; }; done + +ddd-06-mem-uv: ddd-06-mem-uv.c + $(CC) $(CFLAGS) $(LDFLAGS) -o "$@" "$<" $(LDLIBS) -luv + +ddd-%: ddd-%.c + $(CC) $(CFLAGS) $(LDFLAGS) -o "$@" "$<" $(LDLIBS) diff --git a/doc/designs/ddd/README.md b/doc/designs/ddd/README.md new file mode 100644 index 00000000000..61b74e8ceba --- /dev/null +++ b/doc/designs/ddd/README.md @@ -0,0 +1,115 @@ +Demo-Driven Design +================== + +The OpenSSL project from time to time must evolve its public API surface in +order to support new functionality and deprecate old functionality. When this +occurs, the changes to OpenSSL's public API must be planned, discussed and +agreed. One significant dimension which must be considered when considering any +proposed API change is how a broad spectrum of real-world OpenSSL applications +uses the APIs which exist today, as this determines the ways in which those +applications will be affected by any proposed changes, the extent to which they +will be affected, and the extent of any changes which will need to be made by +codebases using OpenSSL to remain current with best practices for OpenSSL API +usage. + +As such, it is useful for the OpenSSL project to have a good understanding of +the usage patterns common in codebases which use OpenSSL, so that it can +anticipate the impact of any evolution of its API on those codebases. This +directory seeks to maintain a set of **API usage demos** which demonstrate a +full spectrum of ways in which real-world applications use the OpenSSL APIs. +This allows the project to discuss any proposed API changes in terms of the +changes that would need to be made to each demo. Since the demos are +representative of a broad spectrum of real-world OpenSSL-based applications, +this ensures that API evolution is made both with reference to real-world API +usage patterns and with reference to the impact on existing applications. + +As such, these demos are maintained in the OpenSSL repository because they are +useful both to current and any future proposed API changes. The set of demos may +be expanded over time, and the demos in this directory at any one time consitute +a present body of understanding of API usage patterns, which can be used to plan +API changes. + +For further background information on the premise of this approach, see [API +long-term evolution](https://github.com/openssl/openssl/issues/17939). + +Scope +----- + +The current emphasis is on client demos. Server support for QUIC is deferred to +subsequent OpenSSL releases, and therefore is (currently) out of scope for this +design exercise. + +The demos also deliberately focus on aspects of libssl usage which are likely to +be relevant to QUIC and require changes; for example, how varied applications +have libssl perform network I/O, and how varied applications create sockets and +connections for use with libssl. The libssl API as a whole has a much larger +scope and includes innumerate functions and myriad features; the intention is +not to demonstrate all of these, because most of them will not be touched by +QUIC. For example, while many users of OpenSSL may make use of APIs for client +certificates or other TLS functionality, the use of QUIC is unlikely to have +implications for these APIs and demos demonstrating such functionality are +therefore out of scope. + +Background +---------- + +These demos were developed after analysis of the following open source +applications to determine libssl API usage patterns. The modally occuring usage +patterns were determined and used to determine categories into which to classify +the applications: + +| | Blk? | FD | +|------------------|------|----| +| mutt | S | AOSF | +| vsftpd | S | AOSF | +| exim | S | AOSFx | +| wget | S | AOSF | +| Fossil | S | BIOc | +| librabbitmq | A | BIOx | +| ngircd | A | AOSF | +| stunnel | A | AOSFx | +| Postfix | A | AOSF | +| socat | A | AOSF | +| HAProxy | A | BIOx | +| Dovecot | A | BIOm | +| Apache httpd | A | BIOx | +| UnrealIRCd | A | AOSF | +| wpa_supplicant | A | BIOm | +| icecast | A | AOSF | +| nginx | A | AOSF | +| curl | A | AOSF | +| Asterisk | A | AOSF | +| Asterisk (DTLS) | A | BIOm/x | +| pgbouncer | A | AOSF, BIOc | + +* Blk: Whether the application uses blocking or non-blocking I/O. + * S: Blocking + * A: Nonblocking +* FD: Whether the application creates and owns its own FD. + * AOSF: Application owns, calls SSL_set_fd. + * AOSFx: Application owns, calls SSL_set_[rw]fd, different FDs for read/write. + * BIOs: Application creates a socket/FD BIO and calls SSL_set_bio. + Application created the connection. + * BIOx: Application creates a BIO with a custom BIO method and calls SSL_set_bio. + * BIOm: Application creates a memory BIO and does its own + pumping to/from actual socket, treating libssl as a pure state machine which + does no I/O itself. + * BIOc: Application uses BIO_s_connect-based methods such as BIO_new_ssl_connect + and leaves connection establishment to OpenSSL. + +Demos +----- + +The demos found in this directory are: + +| | Type | Description | +|-----------------|-------|-------------| +| [ddd-01-conn-blocking](ddd-01-conn-blocking.c) | S-BIOc | A `BIO_s_connect`-based blocking example demonstrating exemplary OpenSSL API usage | +| [ddd-02-conn-nonblocking](ddd-02-conn-nonblocking.c) | A-BIOc | A `BIO_s_connect`-based nonblocking example demonstrating exemplary OpenSSL API usage, with use of a buffering BIO | +| [ddd-03-fd-blocking](ddd-03-fd-blocking.c) | S-AOSF | A `SSL_set_fd`-based blocking example demonstrating real-world OpenSSL API usage (corresponding to S-AOSF applications above) | +| [ddd-04-fd-nonblocking](ddd-04-fd-nonblocking.c) | A-AOSF | A `SSL_set_fd`-based non-blocking example demonstrating real-world OpenSSL API usage (corresponding to A-AOSF applications above) | +| [ddd-05-mem-nonblocking](ddd-05-mem-nonblocking.c) | A-BIOm | A non-blocking example based on use of a memory buffer to feed OpenSSL encrypted data (corresponding to A-BIOm applications above) | +| [ddd-06-mem-uv](ddd-06-mem-uv.c) | A-BIOm | A non-blocking example based on use of a memory buffer to feed OpenSSL encrypted data; uses libuv, a real-world async I/O library | + +Availability of a default certificate store is assumed. `SSL_CERT_DIR` may be +set when running the demos if necessary. diff --git a/doc/designs/ddd/WINDOWS.md b/doc/designs/ddd/WINDOWS.md new file mode 100644 index 00000000000..2c96a9542ed --- /dev/null +++ b/doc/designs/ddd/WINDOWS.md @@ -0,0 +1,80 @@ +Windows-related issues +====================== + +Supporting Windows introduces some complications due to some "fun" peculiarities +of Windows's socket API. + +In general, Windows does not provide a poll(2) call. WSAPoll(2) was introduced +in Vista and supposed to bring this functionality, but it had a bug in it which +Microsoft refused to fix, making it rather pointless. However Microsoft has now +finally fixed this bug in a build of Windows 10. So WSAPoll(2) is a viable +method, but only on fairly new versions of Windows. + +Traditionally, polling has been done on windows using select(). However, this +call works a little differently than on POSIX platforms. Whereas on POSIX +platforms select() accepts a bitmask of FDs, on Windows select() accepts a +structure which embeds a fixed-length array of socket handles. This is necessary +because sockets are NT kernel handles on Windows and thus are not allocated +contiguously like FDs. As such, Windows select() is actually very similar to +POSIX poll(), making select() a viable option for polling on Windows. + +Neither select() nor poll() are, of course, high performance polling options. +Windows does not provide anything like epoll or kqueue. For high performance +network I/O, you are expected to use a Windows API called I/O Completion Ports +(IOCP). + +Supporting these is a pain for applications designed around polling. The reason +is that IOCPs are a higher-level interface; it is easy to build an IOCP-like +interface on top of polling, but it is not really possible to build a +polling-like interface on top of IOCPs. + +For this reason it's actually common for asynchronous I/O libraries to basically +contain two separate implementations of their APIs internally, or at least a +substantial chunk of their code (e.g. libuv, nanomsg). It turns out to be easier +just to write a poll-based implementation of an I/O reactor and an IOCP-based +implementation than try to overcome the impedence discontinuities. + +The difference between polling and IOCPs is that polling reports *readiness* +whereas IOCPs report *completion of an operation*. For example, in the IOCP +model, you make a read or write on a socket and an event is posted to the IOCP +when the read or write is complete. This is a fundamentally different model and +actually more similar to a high-level asynchronous I/O library such as libuv or +so on. + +Evaluation of the existing demos and their applicability to Windows IOCP: + +- ddd-01-conn-blocking: Blocking example, use of IOCP is not applicable. + +- ddd-02-conn-nonblocking: Socket is managed by OpenSSL, and IOCP is not + supported. + +- ddd-03-fd-blocking: Blocking example, use of IOCP is not applicable. + +- ddd-04-fd-nonblocking: libssl is passed an FD with BIO_set_fd. + + BIO_s_sock doesn't appear to support overlapped (that is, IOCP-based) I/O + as this requires use of special WSASend() and WSARecv() functions, rather + than standard send()/recv(). + + Since libssl already doesn't support IOCP for use of BIO_s_sock, + we might say here that any existing application using BIO_s_sock + obviously isn't trying to use IOCP, and therefore we don't need to + worry about the adapability of this example to IOCP. + +- ddd-05-mem-nonblocking: Since the application is in full control of passing + data from the memory BIO to the network, or vice versa, the application + can use IOCP if it wishes. + + This is demonstrated in the following demo: + +- ddd-06-mem-uv: This demo uses a memory BIO and libuv. Since libuv supports + IOCP, it proves that a memory BIO can be used to support IOCP-based usage. + +Further, a cursory examination of code on GitHub seems to suggest that when +people do use IOCP with libssl, they do it using memory BIOs passed to libssl. +So ddd-05 and ddd-06 essentially demonstate this use case, especially ddd-06 as +it uses IOCP internally on Windows. + +My conclusion here is that since libssl does not support IOCP in the first +place, we don't need to be particularly worried about this. But in the worst +case there are always workable solutions, as in demos 5 and 6. diff --git a/doc/designs/ddd/ddd-01-conn-blocking.c b/doc/designs/ddd/ddd-01-conn-blocking.c new file mode 100644 index 00000000000..8ed79e51474 --- /dev/null +++ b/doc/designs/ddd/ddd-01-conn-blocking.c @@ -0,0 +1,161 @@ +#include + +/* + * Demo 1: Client — Managed Connection — Blocking + * ============================================== + * + * This is an example of (part of) an application which uses libssl in a simple, + * synchronous, blocking fashion. The functions show all interactions with + * libssl the application makes, and would hypothetically be linked into a + * larger application. + */ + +/* + * The application is initializing and wants an SSL_CTX which it will use for + * some number of outgoing connections, which it creates in subsequent calls to + * new_conn. The application may also call this function multiple times to + * create multiple SSL_CTX. + */ +SSL_CTX *create_ssl_ctx(void) +{ + SSL_CTX *ctx; + + ctx = SSL_CTX_new(TLS_client_method()); + if (ctx == NULL) + return NULL; + + /* Enable trust chain verification. */ + SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL); + + /* Load default root CA store. */ + if (SSL_CTX_set_default_verify_paths(ctx) == 0) { + SSL_CTX_free(ctx); + return NULL; + } + + return ctx; +} + +/* + * The application wants to create a new outgoing connection using a given + * SSL_CTX. + * + * hostname is a string like "openssl.org:443" or "[::1]:443". + */ +BIO *new_conn(SSL_CTX *ctx, const char *hostname) +{ + BIO *out; + SSL *ssl = NULL; + const char *bare_hostname; + + out = BIO_new_ssl_connect(ctx); + if (out == NULL) + return NULL; + + if (BIO_get_ssl(out, &ssl) == 0) { + BIO_free_all(out); + return NULL; + } + + if (BIO_set_conn_hostname(out, hostname) == 0) { + BIO_free_all(out); + return NULL; + } + + /* Returns the parsed hostname extracted from the hostname:port string. */ + bare_hostname = BIO_get_conn_hostname(out); + if (bare_hostname == NULL) { + BIO_free_all(out); + return NULL; + } + + /* Tell the SSL object the hostname to check certificates against. */ + if (SSL_set1_host(ssl, bare_hostname) <= 0) { + BIO_free_all(out); + return NULL; + } + + return out; +} + +/* + * The application wants to send some block of data to the peer. + * This is a blocking call. + */ +int tx(BIO *bio, const void *buf, int buf_len) +{ + return BIO_write(bio, buf, buf_len); +} + +/* + * The application wants to receive some block of data from + * the peer. This is a blocking call. + */ +int rx(BIO *bio, void *buf, int buf_len) +{ + return BIO_read(bio, buf, buf_len); +} + +/* + * The application wants to close the connection and free bookkeeping + * structures. + */ +void teardown(BIO *bio) +{ + BIO_free_all(bio); +} + +/* + * The application is shutting down and wants to free a previously + * created SSL_CTX. + */ +void teardown_ctx(SSL_CTX *ctx) +{ + SSL_CTX_free(ctx); +} + +/* + * ============================================================================ + * Example driver for the above code. This is just to demonstrate that the code + * works and is not intended to be representative of a real application. + */ +int main(int argc, char **argv) +{ + const char msg[] = "GET / HTTP/1.0\r\nHost: www.openssl.org\r\n\r\n"; + SSL_CTX *ctx = NULL; + BIO *b = NULL; + char buf[2048]; + int l, res = 1; + + ctx = create_ssl_ctx(); + if (ctx == NULL) { + fprintf(stderr, "could not create context\n"); + goto fail; + } + + b = new_conn(ctx, "www.openssl.org:443"); + if (b == NULL) { + fprintf(stderr, "could not create conn\n"); + goto fail; + } + + if (tx(b, msg, sizeof(msg)) < sizeof(msg)) { + fprintf(stderr, "tx error\n"); + goto fail; + } + + for (;;) { + l = rx(b, buf, sizeof(buf)); + if (l <= 0) + break; + fwrite(buf, 1, l, stdout); + } + + res = 0; +fail: + if (b != NULL) + teardown(b); + if (ctx != NULL) + teardown_ctx(ctx); + return res; +} diff --git a/doc/designs/ddd/ddd-02-conn-nonblocking.c b/doc/designs/ddd/ddd-02-conn-nonblocking.c new file mode 100644 index 00000000000..fa508afc7cd --- /dev/null +++ b/doc/designs/ddd/ddd-02-conn-nonblocking.c @@ -0,0 +1,289 @@ +#include +#include + +/* + * Demo 2: Client — Managed Connection — Asynchronous Nonblocking + * ============================================================== + * + * This is an example of (part of) an application which uses libssl in an + * asynchronous, nonblocking fashion. The functions show all interactions with + * libssl the application makes, and would hypothetically be linked into a + * larger application. + * + * In this example, libssl still makes syscalls directly using an fd, which is + * configured in nonblocking mode. As such, the application can still be + * abstracted from the details of what that fd is (is it a TCP socket? is it a + * UDP socket?); this code passes the application an fd and the application + * simply calls back into this code when poll()/etc. indicates it is ready. + */ +typedef struct app_conn_st { + SSL *ssl; + BIO *ssl_bio; + int rx_need_tx, tx_need_rx; +} APP_CONN; + +/* + * The application is initializing and wants an SSL_CTX which it will use for + * some number of outgoing connections, which it creates in subsequent calls to + * new_conn. The application may also call this function multiple times to + * create multiple SSL_CTX. + */ +SSL_CTX *create_ssl_ctx(void) +{ + SSL_CTX *ctx; + + ctx = SSL_CTX_new(TLS_client_method()); + if (ctx == NULL) + return NULL; + + /* Enable trust chain verification. */ + SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL); + + /* Load default root CA store. */ + if (SSL_CTX_set_default_verify_paths(ctx) == 0) { + SSL_CTX_free(ctx); + return NULL; + } + + return ctx; +} + +/* + * The application wants to create a new outgoing connection using a given + * SSL_CTX. + * + * hostname is a string like "openssl.org:443" or "[::1]:443". + */ +APP_CONN *new_conn(SSL_CTX *ctx, const char *hostname) +{ + APP_CONN *conn; + BIO *out, *buf; + SSL *ssl = NULL; + const char *bare_hostname; + + conn = calloc(1, sizeof(APP_CONN)); + if (conn == NULL) + return NULL; + + out = BIO_new_ssl_connect(ctx); + if (out == NULL) { + free(conn); + return NULL; + } + + if (BIO_get_ssl(out, &ssl) == 0) { + BIO_free_all(out); + free(conn); + return NULL; + } + + buf = BIO_new(BIO_f_buffer()); + if (buf == NULL) { + BIO_free_all(out); + free(conn); + return NULL; + } + + BIO_push(out, buf); + + if (BIO_set_conn_hostname(out, hostname) == 0) { + BIO_free_all(out); + free(conn); + return NULL; + } + + /* Returns the parsed hostname extracted from the hostname:port string. */ + bare_hostname = BIO_get_conn_hostname(out); + if (bare_hostname == NULL) { + BIO_free_all(out); + free(conn); + return NULL; + } + + /* Tell the SSL object the hostname to check certificates against. */ + if (SSL_set1_host(ssl, bare_hostname) <= 0) { + BIO_free_all(out); + free(conn); + return NULL; + } + + /* Make the BIO nonblocking. */ + BIO_set_nbio(out, 1); + + conn->ssl_bio = out; + return conn; +} + +/* + * Non-blocking transmission. + * + * Returns -1 on error. Returns -2 if the function would block (corresponds to + * EWOULDBLOCK). + */ +int tx(APP_CONN *conn, const void *buf, int buf_len) +{ + int l; + + conn->tx_need_rx = 0; + + l = BIO_write(conn->ssl_bio, buf, buf_len); + if (l <= 0) { + if (BIO_should_retry(conn->ssl_bio)) { + conn->tx_need_rx = BIO_should_read(conn->ssl_bio); + return -2; + } else { + return -1; + } + } + + return l; +} + +/* + * Non-blocking reception. + * + * Returns -1 on error. Returns -2 if the function would block (corresponds to + * EWOULDBLOCK). + */ +int rx(APP_CONN *conn, void *buf, int buf_len) +{ + int l; + + conn->rx_need_tx = 0; + + l = BIO_read(conn->ssl_bio, buf, buf_len); + if (l <= 0) { + if (BIO_should_retry(conn->ssl_bio)) { + conn->rx_need_tx = BIO_should_write(conn->ssl_bio); + return -2; + } else { + return -1; + } + } + + return l; +} + +/* + * The application wants to know a fd it can poll on to determine when the + * SSL state machine needs to be pumped. + */ +int get_conn_fd(APP_CONN *conn) +{ + return BIO_get_fd(conn->ssl_bio, NULL); +} + +/* + * These functions returns zero or more of: + * + * POLLIN: The SSL state machine is interested in socket readability events. + * + * POLLOUT: The SSL state machine is interested in socket writeability events. + * + * POLLERR: The SSL state machine is interested in socket error events. + * + * get_conn_pending_tx returns events which may cause SSL_write to make + * progress and get_conn_pending_rx returns events which may cause SSL_read + * to make progress. + */ +int get_conn_pending_tx(APP_CONN *conn) +{ + return (conn->tx_need_rx ? POLLIN : 0) | POLLOUT | POLLERR; +} + +int get_conn_pending_rx(APP_CONN *conn) +{ + return (conn->rx_need_tx ? POLLOUT : 0) | POLLIN | POLLERR; +} + +/* + * The application wants to close the connection and free bookkeeping + * structures. + */ +void teardown(APP_CONN *conn) +{ + BIO_free_all(conn->ssl_bio); + free(conn); +} + +/* + * The application is shutting down and wants to free a previously + * created SSL_CTX. + */ +void teardown_ctx(SSL_CTX *ctx) +{ + SSL_CTX_free(ctx); +} + +/* + * ============================================================================ + * Example driver for the above code. This is just to demonstrate that the code + * works and is not intended to be representative of a real application. + */ +int main(int argc, char **argv) +{ + const char tx_msg[] = "GET / HTTP/1.0\r\nHost: www.openssl.org\r\n\r\n"; + const char *tx_p = tx_msg; + char rx_buf[2048]; + int res = 1, l, tx_len = sizeof(tx_msg)-1; + int timeout = 2000 /* ms */; + APP_CONN *conn = NULL; + SSL_CTX *ctx; + + ctx = create_ssl_ctx(); + if (ctx == NULL) { + fprintf(stderr, "cannot create SSL context\n"); + goto fail; + } + + conn = new_conn(ctx, "www.openssl.org:443"); + if (conn == NULL) { + fprintf(stderr, "cannot establish connection\n"); + goto fail; + } + + /* TX */ + while (tx_len != 0) { + l = tx(conn, tx_p, tx_len); + if (l > 0) { + tx_p += l; + tx_len -= l; + } else if (l == -1) { + fprintf(stderr, "tx error\n"); + } else if (l == -2) { + struct pollfd pfd = {0}; + pfd.fd = get_conn_fd(conn); + pfd.events = get_conn_pending_tx(conn); + if (poll(&pfd, 1, timeout) == 0) { + fprintf(stderr, "tx timeout\n"); + goto fail; + } + } + } + + /* RX */ + for (;;) { + l = rx(conn, rx_buf, sizeof(rx_buf)); + if (l > 0) { + fwrite(rx_buf, 1, l, stdout); + } else if (l == -1) { + break; + } else if (l == -2) { + struct pollfd pfd = {0}; + pfd.fd = get_conn_fd(conn); + pfd.events = get_conn_pending_rx(conn); + if (poll(&pfd, 1, timeout) == 0) { + fprintf(stderr, "rx timeout\n"); + goto fail; + } + } + } + + res = 0; +fail: + if (conn != NULL) + teardown(conn); + if (ctx != NULL) + teardown_ctx(ctx); + return res; +} diff --git a/doc/designs/ddd/ddd-03-fd-blocking.c b/doc/designs/ddd/ddd-03-fd-blocking.c new file mode 100644 index 00000000000..f4aaf35a1e9 --- /dev/null +++ b/doc/designs/ddd/ddd-03-fd-blocking.c @@ -0,0 +1,188 @@ +#include + +/* + * Demo 3: Client — Client Creates FD — Blocking + * ============================================= + * + * This is an example of (part of) an application which uses libssl in a simple, + * synchronous, blocking fashion. The client is responsible for creating the + * socket and passing it to libssl. The functions show all interactions with + * libssl the application makes, and would hypothetically be linked into a + * larger application. + */ + +/* + * The application is initializing and wants an SSL_CTX which it will use for + * some number of outgoing connections, which it creates in subsequent calls to + * new_conn. The application may also call this function multiple times to + * create multiple SSL_CTX. + */ +SSL_CTX *create_ssl_ctx(void) +{ + SSL_CTX *ctx; + + ctx = SSL_CTX_new(TLS_client_method()); + if (ctx == NULL) + return NULL; + + /* Enable trust chain verification. */ + SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL); + + /* Load default root CA store. */ + if (SSL_CTX_set_default_verify_paths(ctx) == 0) { + SSL_CTX_free(ctx); + return NULL; + } + + return ctx; +} + +/* + * The application wants to create a new outgoing connection using a given + * SSL_CTX. + * + * hostname is a string like "openssl.org" used for certificate validation. + */ +SSL *new_conn(SSL_CTX *ctx, int fd, const char *bare_hostname) +{ + SSL *ssl; + + ssl = SSL_new(ctx); + if (ssl == NULL) + return NULL; + + SSL_set_connect_state(ssl); /* cannot fail */ + + if (SSL_set_fd(ssl, fd) <= 0) { + SSL_free(ssl); + return NULL; + } + + if (SSL_set1_host(ssl, bare_hostname) <= 0) { + SSL_free(ssl); + return NULL; + } + + if (SSL_set_tlsext_host_name(ssl, bare_hostname) <= 0) { + SSL_free(ssl); + return NULL; + } + + return ssl; +} + +/* + * The application wants to send some block of data to the peer. + * This is a blocking call. + */ +int tx(SSL *ssl, const void *buf, int buf_len) +{ + return SSL_write(ssl, buf, buf_len); +} + +/* + * The application wants to receive some block of data from + * the peer. This is a blocking call. + */ +int rx(SSL *ssl, void *buf, int buf_len) +{ + return SSL_read(ssl, buf, buf_len); +} + +/* + * The application wants to close the connection and free bookkeeping + * structures. + */ +void teardown(SSL *ssl) +{ + SSL_free(ssl); +} + +/* + * The application is shutting down and wants to free a previously + * created SSL_CTX. + */ +void teardown_ctx(SSL_CTX *ctx) +{ + SSL_CTX_free(ctx); +} + +/* + * ============================================================================ + * Example driver for the above code. This is just to demonstrate that the code + * works and is not intended to be representative of a real application. + */ +#include +#include +#include +#include +#include + +int main(int argc, char **argv) +{ + int rc, fd = -1, l, res = 1; + const char msg[] = "GET / HTTP/1.0\r\nHost: www.openssl.org\r\n\r\n"; + struct addrinfo hints = {0}, *result = NULL; + SSL *ssl = NULL; + SSL_CTX *ctx; + char buf[2048]; + + ctx = create_ssl_ctx(); + if (ctx == NULL) { + fprintf(stderr, "cannot create context\n"); + goto fail; + } + + hints.ai_family = AF_INET; + hints.ai_socktype = SOCK_STREAM; + hints.ai_flags = AI_PASSIVE; + rc = getaddrinfo("www.openssl.org", "443", &hints, &result); + if (rc < 0) { + fprintf(stderr, "cannot resolve\n"); + goto fail; + } + + signal(SIGPIPE, SIG_IGN); + + fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP); + if (fd < 0) { + fprintf(stderr, "cannot create socket\n"); + goto fail; + } + + rc = connect(fd, result->ai_addr, result->ai_addrlen); + if (rc < 0) { + fprintf(stderr, "cannot connect\n"); + goto fail; + } + + ssl = new_conn(ctx, fd, "www.openssl.org"); + if (ssl == NULL) { + fprintf(stderr, "cannot create connection\n"); + goto fail; + } + + if (tx(ssl, msg, sizeof(msg)-1) < sizeof(msg)-1) { + fprintf(stderr, "tx error\n"); + goto fail; + } + + for (;;) { + l = rx(ssl, buf, sizeof(buf)); + if (l <= 0) + break; + fwrite(buf, 1, l, stdout); + } + + res = 0; +fail: + if (ssl != NULL) + teardown(ssl); + if (ctx != NULL) + teardown_ctx(ctx); + if (fd >= 0) + close(fd); + if (result != NULL) + freeaddrinfo(result); + return res; +} diff --git a/doc/designs/ddd/ddd-04-fd-nonblocking.c b/doc/designs/ddd/ddd-04-fd-nonblocking.c new file mode 100644 index 00000000000..2e9606b921b --- /dev/null +++ b/doc/designs/ddd/ddd-04-fd-nonblocking.c @@ -0,0 +1,323 @@ +#include +#include + +/* + * Demo 4: Client — Client Creates FD — Nonblocking + * ================================================ + * + * This is an example of (part of) an application which uses libssl in an + * asynchronous, nonblocking fashion. The client is responsible for creating the + * socket and passing it to libssl. The functions show all interactions with + * libssl the application makes, and wouldn hypothetically be linked into a + * larger application. + */ +typedef struct app_conn_st { + SSL *ssl; + int fd; + int rx_need_tx, tx_need_rx; +} APP_CONN; + +/* + * The application is initializing and wants an SSL_CTX which it will use for + * some number of outgoing connections, which it creates in subsequent calls to + * new_conn. The application may also call this function multiple times to + * create multiple SSL_CTX. + */ +SSL_CTX *create_ssl_ctx(void) +{ + SSL_CTX *ctx; + + ctx = SSL_CTX_new(TLS_client_method()); + if (ctx == NULL) + return NULL; + + /* Enable trust chain verification. */ + SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL); + + /* Load default root CA store. */ + if (SSL_CTX_set_default_verify_paths(ctx) == 0) { + SSL_CTX_free(ctx); + return NULL; + } + + return ctx; +} + +/* + * The application wants to create a new outgoing connection using a given + * SSL_CTX. + * + * hostname is a string like "openssl.org" used for certificate validation. + */ +APP_CONN *new_conn(SSL_CTX *ctx, int fd, const char *bare_hostname) +{ + APP_CONN *conn; + SSL *ssl; + + conn = calloc(1, sizeof(APP_CONN)); + if (conn == NULL) + return NULL; + + ssl = conn->ssl = SSL_new(ctx); + if (ssl == NULL) { + free(conn); + return NULL; + } + + SSL_set_connect_state(ssl); /* cannot fail */ + + if (SSL_set_fd(ssl, fd) <= 0) { + SSL_free(ssl); + free(conn); + return NULL; + } + + if (SSL_set1_host(ssl, bare_hostname) <= 0) { + SSL_free(ssl); + free(conn); + return NULL; + } + + if (SSL_set_tlsext_host_name(ssl, bare_hostname) <= 0) { + SSL_free(ssl); + free(conn); + return NULL; + } + + conn->fd = fd; + return conn; +} + +/* + * Non-blocking transmission. + * + * Returns -1 on error. Returns -2 if the function would block (corresponds to + * EWOULDBLOCK). + */ +int tx(APP_CONN *conn, const void *buf, int buf_len) +{ + int rc, l; + + conn->tx_need_rx = 0; + + l = SSL_write(conn->ssl, buf, buf_len); + if (l <= 0) { + rc = SSL_get_error(conn->ssl, l); + switch (rc) { + case SSL_ERROR_WANT_READ: + conn->tx_need_rx = 1; + case SSL_ERROR_WANT_CONNECT: + case SSL_ERROR_WANT_WRITE: + return -2; + default: + return -1; + } + } + + return l; +} + +/* + * Non-blocking reception. + * + * Returns -1 on error. Returns -2 if the function would block (corresponds to + * EWOULDBLOCK). + */ +int rx(APP_CONN *conn, void *buf, int buf_len) +{ + int rc, l; + + conn->rx_need_tx = 0; + + l = SSL_read(conn->ssl, buf, buf_len); + if (l <= 0) { + rc = SSL_get_error(conn->ssl, l); + switch (rc) { + case SSL_ERROR_WANT_WRITE: + conn->rx_need_tx = 1; + case SSL_ERROR_WANT_READ: + return -2; + default: + return -1; + } + } + + return l; +} + +/* + * The application wants to know a fd it can poll on to determine when the + * SSL state machine needs to be pumped. + * + * If the fd returned has: + * + * POLLIN: SSL_read *may* return data; + * if application does not want to read yet, it should call pump(). + * + * POLLOUT: SSL_write *may* accept data + * + * POLLERR: An application should call pump() if it is not likely to call + * SSL_read or SSL_write soon. + * + */ +int get_conn_fd(APP_CONN *conn) +{ + return conn->fd; +} + +/* + * These functions returns zero or more of: + * + * POLLIN: The SSL state machine is interested in socket readability events. + * + * POLLOUT: The SSL state machine is interested in socket writeability events. + * + * POLLERR: The SSL state machine is interested in socket error events. + * + * get_conn_pending_tx returns events which may cause SSL_write to make + * progress and get_conn_pending_rx returns events which may cause SSL_read + * to make progress. + */ +int get_conn_pending_tx(APP_CONN *conn) +{ + return (conn->tx_need_rx ? POLLIN : 0) | POLLOUT | POLLERR; +} + +int get_conn_pending_rx(APP_CONN *conn) +{ + return (conn->rx_need_tx ? POLLOUT : 0) | POLLIN | POLLERR; +} + +/* + * The application wants to close the connection and free bookkeeping + * structures. + */ +void teardown(APP_CONN *conn) +{ + SSL_shutdown(conn->ssl); + SSL_free(conn->ssl); + free(conn); +} + +/* + * The application is shutting down and wants to free a previously + * created SSL_CTX. + */ +void teardown_ctx(SSL_CTX *ctx) +{ + SSL_CTX_free(ctx); +} + +/* + * ============================================================================ + * Example driver for the above code. This is just to demonstrate that the code + * works and is not intended to be representative of a real application. + */ +#include +#include +#include +#include +#include +#include + +int main(int argc, char **argv) +{ + int rc, fd = -1, res = 1; + const char tx_msg[] = "GET / HTTP/1.0\r\nHost: www.openssl.org\r\n\r\n"; + const char *tx_p = tx_msg; + char rx_buf[2048]; + int l, tx_len = sizeof(tx_msg)-1; + int timeout = 2000 /* ms */; + APP_CONN *conn = NULL; + struct addrinfo hints = {0}, *result = NULL; + SSL_CTX *ctx; + + ctx = create_ssl_ctx(); + if (ctx == NULL) { + fprintf(stderr, "cannot create SSL context\n"); + goto fail; + } + + hints.ai_family = AF_INET; + hints.ai_socktype = SOCK_STREAM; + hints.ai_flags = AI_PASSIVE; + rc = getaddrinfo("www.openssl.org", "443", &hints, &result); + if (rc < 0) { + fprintf(stderr, "cannot resolve\n"); + goto fail; + } + + signal(SIGPIPE, SIG_IGN); + + fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP); + if (fd < 0) { + fprintf(stderr, "cannot create socket\n"); + goto fail; + } + + rc = connect(fd, result->ai_addr, result->ai_addrlen); + if (rc < 0) { + fprintf(stderr, "cannot connect\n"); + goto fail; + } + + rc = fcntl(fd, F_SETFL, O_NONBLOCK); + if (rc < 0) { + fprintf(stderr, "cannot make socket nonblocking\n"); + goto fail; + } + + conn = new_conn(ctx, fd, "www.openssl.org"); + if (conn == NULL) { + fprintf(stderr, "cannot establish connection\n"); + goto fail; + } + + /* TX */ + while (tx_len != 0) { + l = tx(conn, tx_p, tx_len); + if (l > 0) { + tx_p += l; + tx_len -= l; + } else if (l == -1) { + fprintf(stderr, "tx error\n"); + goto fail; + } else if (l == -2) { + struct pollfd pfd = {0}; + pfd.fd = get_conn_fd(conn); + pfd.events = get_conn_pending_tx(conn); + if (poll(&pfd, 1, timeout) == 0) { + fprintf(stderr, "tx timeout\n"); + goto fail; + } + } + } + + /* RX */ + for (;;) { + l = rx(conn, rx_buf, sizeof(rx_buf)); + if (l > 0) { + fwrite(rx_buf, 1, l, stdout); + } else if (l == -1) { + break; + } else if (l == -2) { + struct pollfd pfd = {0}; + pfd.fd = get_conn_fd(conn); + pfd.events = get_conn_pending_rx(conn); + if (poll(&pfd, 1, timeout) == 0) { + fprintf(stderr, "rx timeout\n"); + goto fail; + } + } + } + + res = 0; +fail: + if (conn != NULL) + teardown(conn); + if (ctx != NULL) + teardown_ctx(ctx); + if (result != NULL) + freeaddrinfo(result); + return res; +} diff --git a/doc/designs/ddd/ddd-05-mem-nonblocking.c b/doc/designs/ddd/ddd-05-mem-nonblocking.c new file mode 100644 index 00000000000..206ca7a6f79 --- /dev/null +++ b/doc/designs/ddd/ddd-05-mem-nonblocking.c @@ -0,0 +1,408 @@ +#include +#include + +/* + * Demo 5: Client — Client Uses Memory BIO — Nonblocking + * ===================================================== + * + * This is an example of (part of) an application which uses libssl in an + * asynchronous, nonblocking fashion. The application passes memory BIOs to + * OpenSSL, meaning that it controls both when data is read/written from an SSL + * object on the decrypted side but also when encrypted data from the network is + * shunted to/from OpenSSL. In this way OpenSSL is used as a pure state machine + * which does not make its own network I/O calls. OpenSSL never sees or creates + * any file descriptor for a network socket. The functions below show all + * interactions with libssl the application makes, and would hypothetically be + * linked into a larger application. + */ +typedef struct app_conn_st { + SSL *ssl; + BIO *ssl_bio, *net_bio; + int rx_need_tx, tx_need_rx; +} APP_CONN; + +/* + * The application is initializing and wants an SSL_CTX which it will use for + * some number of outgoing connections, which it creates in subsequent calls to + * new_conn. The application may also call this function multiple times to + * create multiple SSL_CTX. + */ +SSL_CTX *create_ssl_ctx(void) +{ + SSL_CTX *ctx; + + ctx = SSL_CTX_new(TLS_client_method()); + if (ctx == NULL) + return NULL; + + /* Enable trust chain verification. */ + SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL); + + /* Load default root CA store. */ + if (SSL_CTX_set_default_verify_paths(ctx) == 0) { + SSL_CTX_free(ctx); + return NULL; + } + + return ctx; +} + +/* + * The application wants to create a new outgoing connection using a given + * SSL_CTX. + * + * hostname is a string like "openssl.org" used for certificate validation. + */ +APP_CONN *new_conn(SSL_CTX *ctx, const char *bare_hostname) +{ + BIO *ssl_bio, *internal_bio, *net_bio; + APP_CONN *conn; + SSL *ssl; + + conn = calloc(1, sizeof(APP_CONN)); + if (conn == NULL) + return NULL; + + ssl = conn->ssl = SSL_new(ctx); + if (ssl == NULL) { + free(conn); + return NULL; + } + + SSL_set_connect_state(ssl); /* cannot fail */ + + if (BIO_new_bio_pair(&internal_bio, 0, &net_bio, 0) <= 0) { + SSL_free(ssl); + free(conn); + return NULL; + } + + SSL_set_bio(ssl, internal_bio, internal_bio); + + if (SSL_set1_host(ssl, bare_hostname) <= 0) { + SSL_free(ssl); + free(conn); + return NULL; + } + + if (SSL_set_tlsext_host_name(ssl, bare_hostname) <= 0) { + SSL_free(ssl); + free(conn); + return NULL; + } + + ssl_bio = BIO_new(BIO_f_ssl()); + if (ssl_bio == NULL) { + SSL_free(ssl); + free(conn); + return NULL; + } + + if (BIO_set_ssl(ssl_bio, ssl, BIO_CLOSE) <= 0) { + SSL_free(ssl); + BIO_free(ssl_bio); + return NULL; + } + + conn->ssl_bio = ssl_bio; + conn->net_bio = net_bio; + return conn; +} + +/* + * Non-blocking transmission. + * + * Returns -1 on error. Returns -2 if the function would block (corresponds to + * EWOULDBLOCK). + */ +int tx(APP_CONN *conn, const void *buf, int buf_len) +{ + int rc, l; + + l = BIO_write(conn->ssl_bio, buf, buf_len); + if (l <= 0) { + rc = SSL_get_error(conn->ssl, l); + switch (rc) { + case SSL_ERROR_WANT_READ: + conn->tx_need_rx = 1; + case SSL_ERROR_WANT_CONNECT: + case SSL_ERROR_WANT_WRITE: + return -2; + default: + return -1; + } + } else { + conn->tx_need_rx = 0; + } + + return l; +} + +/* + * Non-blocking reception. + * + * Returns -1 on error. Returns -2 if the function would block (corresponds to + * EWOULDBLOCK). + */ +int rx(APP_CONN *conn, void *buf, int buf_len) +{ + int rc, l; + + l = BIO_read(conn->ssl_bio, buf, buf_len); + if (l <= 0) { + rc = SSL_get_error(conn->ssl, l); + switch (rc) { + case SSL_ERROR_WANT_WRITE: + conn->rx_need_tx = 1; + case SSL_ERROR_WANT_READ: + return -2; + default: + return -1; + } + } else { + conn->rx_need_tx = 0; + } + + return l; +} + +/* + * Called to get data which has been enqueued for transmission to the network + * by OpenSSL. + */ +int read_net_tx(APP_CONN *conn, void *buf, int buf_len) +{ + return BIO_read(conn->net_bio, buf, buf_len); +} + +/* + * Called to feed data which has been received from the network to OpenSSL. + */ +int write_net_rx(APP_CONN *conn, const void *buf, int buf_len) +{ + return BIO_write(conn->net_bio, buf, buf_len); +} + +/* + * Determine how much data can be written to the network RX BIO. + */ +size_t net_rx_space(APP_CONN *conn) +{ + return BIO_ctrl_get_write_guarantee(conn->net_bio); +} + +/* + * Determine how much data is currently queued for transmission in the network + * TX BIO. + */ +size_t net_tx_avail(APP_CONN *conn) +{ + return BIO_ctrl_pending(conn->net_bio); +} + +/* + * These functions returns zero or more of: + * + * POLLIN: The SSL state machine is interested in socket readability events. + * + * POLLOUT: The SSL state machine is interested in socket writeability events. + * + * POLLERR: The SSL state machine is interested in socket error events. + * + * get_conn_pending_tx returns events which may cause SSL_write to make + * progress and get_conn_pending_rx returns events which may cause SSL_read + * to make progress. + */ +int get_conn_pending_tx(APP_CONN *conn) +{ + return (conn->tx_need_rx ? POLLIN : 0) | POLLOUT | POLLERR; +} + +int get_conn_pending_rx(APP_CONN *conn) +{ + return (conn->rx_need_tx ? POLLOUT : 0) | POLLIN | POLLERR; +} + +/* + * The application wants to close the connection and free bookkeeping + * structures. + */ +void teardown(APP_CONN *conn) +{ + BIO_free_all(conn->ssl_bio); + BIO_free_all(conn->net_bio); + free(conn); +} + +/* + * The application is shutting down and wants to free a previously + * created SSL_CTX. + */ +void teardown_ctx(SSL_CTX *ctx) +{ + SSL_CTX_free(ctx); +} + +/* + * ============================================================================ + * Example driver for the above code. This is just to demonstrate that the code + * works and is not intended to be representative of a real application. + */ +#include +#include +#include +#include +#include +#include +#include + +static int pump(APP_CONN *conn, int fd, int events, int timeout) +{ + int l, l2; + char buf[2048]; + size_t wspace; + struct pollfd pfd = {0}; + + pfd.fd = fd; + pfd.events = (events & (POLLIN | POLLERR)); + if (net_rx_space(conn) == 0) + pfd.events &= ~POLLIN; + if (net_tx_avail(conn) > 0) + pfd.events |= POLLOUT; + + if ((pfd.events & (POLLIN|POLLOUT)) == 0) + return 1; + + if (poll(&pfd, 1, timeout) == 0) + return -1; + + if (pfd.revents & POLLIN) { + while ((wspace = net_rx_space(conn)) > 0) { + l = read(fd, buf, wspace > sizeof(buf) ? sizeof(buf) : wspace); + if (l <= 0) { + switch (errno) { + case EAGAIN: + goto stop; + default: + if (l == 0) /* EOF */ + goto stop; + + fprintf(stderr, "error on read: %d\n", errno); + return -1; + } + break; + } + l2 = write_net_rx(conn, buf, l); + if (l2 < l) + fprintf(stderr, "short write %d %d\n", l2, l); + } stop:; + } + + if (pfd.revents & POLLOUT) { + for (;;) { + l = read_net_tx(conn, buf, sizeof(buf)); + if (l <= 0) + break; + l2 = write(fd, buf, l); + if (l2 < l) + fprintf(stderr, "short read %d %d\n", l2, l); + } + } + + return 1; +} + +int main(int argc, char **argv) +{ + int rc, fd = -1, res = 1; + const char tx_msg[] = "GET / HTTP/1.0\r\nHost: www.openssl.org\r\n\r\n"; + const char *tx_p = tx_msg; + char rx_buf[2048]; + int l, tx_len = sizeof(tx_msg)-1; + int timeout = 2000 /* ms */; + APP_CONN *conn = NULL; + struct addrinfo hints = {0}, *result = NULL; + SSL_CTX *ctx; + + ctx = create_ssl_ctx(); + if (ctx == NULL) { + fprintf(stderr, "cannot create SSL context\n"); + goto fail; + } + + hints.ai_family = AF_INET; + hints.ai_socktype = SOCK_STREAM; + hints.ai_flags = AI_PASSIVE; + rc = getaddrinfo("www.openssl.org", "443", &hints, &result); + if (rc < 0) { + fprintf(stderr, "cannot resolve\n"); + goto fail; + } + + signal(SIGPIPE, SIG_IGN); + + fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP); + if (fd < 0) { + fprintf(stderr, "cannot create socket\n"); + goto fail; + } + + rc = connect(fd, result->ai_addr, result->ai_addrlen); + if (rc < 0) { + fprintf(stderr, "cannot connect\n"); + goto fail; + } + + rc = fcntl(fd, F_SETFL, O_NONBLOCK); + if (rc < 0) { + fprintf(stderr, "cannot make socket nonblocking\n"); + goto fail; + } + + conn = new_conn(ctx, "www.openssl.org"); + if (conn == NULL) { + fprintf(stderr, "cannot establish connection\n"); + goto fail; + } + + /* TX */ + while (tx_len != 0) { + l = tx(conn, tx_p, tx_len); + if (l > 0) { + tx_p += l; + tx_len -= l; + } else if (l == -1) { + fprintf(stderr, "tx error\n"); + } else if (l == -2) { + if (pump(conn, fd, get_conn_pending_tx(conn), timeout) != 1) { + fprintf(stderr, "pump error\n"); + goto fail; + } + } + } + + /* RX */ + for (;;) { + l = rx(conn, rx_buf, sizeof(rx_buf)); + if (l > 0) { + fwrite(rx_buf, 1, l, stdout); + } else if (l == -1) { + break; + } else if (l == -2) { + if (pump(conn, fd, get_conn_pending_rx(conn), timeout) != 1) { + fprintf(stderr, "pump error\n"); + goto fail; + } + } + } + + res = 0; +fail: + if (conn != NULL) + teardown(conn); + if (ctx != NULL) + teardown_ctx(ctx); + if (result != NULL) + freeaddrinfo(result); + return res; +} diff --git a/doc/designs/ddd/ddd-06-mem-uv.c b/doc/designs/ddd/ddd-06-mem-uv.c new file mode 100644 index 00000000000..f912f68bdf7 --- /dev/null +++ b/doc/designs/ddd/ddd-06-mem-uv.c @@ -0,0 +1,599 @@ +#include +#include +#include +#include + +typedef struct app_conn_st APP_CONN; +typedef struct upper_write_op_st UPPER_WRITE_OP; +typedef struct lower_write_op_st LOWER_WRITE_OP; + +typedef void (app_connect_cb)(APP_CONN *conn, int status, void *arg); +typedef void (app_write_cb)(APP_CONN *conn, int status, void *arg); +typedef void (app_read_cb)(APP_CONN *conn, void *buf, size_t buf_len, void *arg); + +static void tcp_connect_done(uv_connect_t *tcp_connect, int status); +static void net_connect_fail_close_done(uv_handle_t *handle); +static int handshake_ssl(APP_CONN *conn); +static void flush_write_buf(APP_CONN *conn); +static void set_rx(APP_CONN *conn); +static int try_write(APP_CONN *conn, UPPER_WRITE_OP *op); +static void handle_pending_writes(APP_CONN *conn); +static int write_deferred(APP_CONN *conn, const void *buf, size_t buf_len, app_write_cb *cb, void *arg); +static void teardown_continued(uv_handle_t *handle); +static int setup_ssl(APP_CONN *conn, const char *hostname); + +/* + * Structure to track an application-level write request. Only created + * if SSL_write does not accept the data immediately, typically because + * it is in WANT_READ. + */ +struct upper_write_op_st { + struct upper_write_op_st *prev, *next; + const uint8_t *buf; + size_t buf_len, written; + APP_CONN *conn; + app_write_cb *cb; + void *cb_arg; +}; + +/* + * Structure to track a network-level write request. + */ +struct lower_write_op_st { + uv_write_t w; + uv_buf_t b; + uint8_t *buf; + APP_CONN *conn; +}; + +/* + * Application connection object. + */ +struct app_conn_st { + SSL_CTX *ctx; + SSL *ssl; + BIO *net_bio; + uv_stream_t *stream; + uv_tcp_t tcp; + uv_connect_t tcp_connect; + app_connect_cb *app_connect_cb; /* called once handshake is done */ + void *app_connect_arg; + app_read_cb *app_read_cb; /* application's on-RX callback */ + void *app_read_arg; + const char *hostname; + char init_handshake, done_handshake, closed; + char *teardown_done; + + UPPER_WRITE_OP *pending_upper_write_head, *pending_upper_write_tail; +}; + +/* + * The application is initializing and wants an SSL_CTX which it will use for + * some number of outgoing connections, which it creates in subsequent calls to + * new_conn. The application may also call this function multiple times to + * create multiple SSL_CTX. + */ +SSL_CTX *create_ssl_ctx(void) +{ + SSL_CTX *ctx; + + ctx = SSL_CTX_new(TLS_client_method()); + if (ctx == NULL) + return NULL; + + /* Enable trust chain verification. */ + SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL); + + /* Load default root CA store. */ + if (SSL_CTX_set_default_verify_paths(ctx) == 0) { + SSL_CTX_free(ctx); + return NULL; + } + + return ctx; +} + +/* + * The application wants to create a new outgoing connection using a given + * SSL_CTX. An outgoing TCP connection is started and the callback is called + * asynchronously when the TLS handshake is complete. + * + * hostname is a string like "openssl.org" used for certificate validation. + */ + +APP_CONN *new_conn(SSL_CTX *ctx, const char *hostname, + struct sockaddr *sa, socklen_t sa_len, + app_connect_cb *cb, void *arg) +{ + int rc; + APP_CONN *conn = NULL; + + conn = calloc(1, sizeof(APP_CONN)); + if (!conn) + return NULL; + + uv_tcp_init(uv_default_loop(), &conn->tcp); + conn->tcp.data = conn; + + conn->stream = (uv_stream_t *)&conn->tcp; + conn->app_connect_cb = cb; + conn->app_connect_arg = arg; + conn->tcp_connect.data = conn; + rc = uv_tcp_connect(&conn->tcp_connect, &conn->tcp, sa, tcp_connect_done); + if (rc < 0) { + uv_close((uv_handle_t *)&conn->tcp, net_connect_fail_close_done); + return NULL; + } + + conn->ctx = ctx; + conn->hostname = hostname; + return conn; +} + +/* + * The application wants to start reading from the SSL stream. + * The callback is called whenever data is available. + */ +int app_read_start(APP_CONN *conn, app_read_cb *cb, void *arg) +{ + conn->app_read_cb = cb; + conn->app_read_arg = arg; + set_rx(conn); + return 0; +} + +/* + * The application wants to write. The callback is called once the + * write is complete. The callback should free the buffer. + */ +int app_write(APP_CONN *conn, const void *buf, size_t buf_len, app_write_cb *cb, void *arg) +{ + write_deferred(conn, buf, buf_len, cb, arg); + handle_pending_writes(conn); + return buf_len; +} + +/* + * The application wants to close the connection and free bookkeeping + * structures. + */ +void teardown(APP_CONN *conn) +{ + char teardown_done = 0; + + if (conn == NULL) + return; + + BIO_free_all(conn->net_bio); + SSL_free(conn->ssl); + + uv_cancel((uv_req_t *)&conn->tcp_connect); + + conn->teardown_done = &teardown_done; + uv_close((uv_handle_t *)conn->stream, teardown_continued); + + /* Just wait synchronously until teardown completes. */ + while (!teardown_done) + uv_run(uv_default_loop(), UV_RUN_DEFAULT); +} + +/* + * The application is shutting down and wants to free a previously + * created SSL_CTX. + */ +void teardown_ctx(SSL_CTX *ctx) +{ + SSL_CTX_free(ctx); +} + +/* + * ============================================================================ + * Internal implementation functions. + */ +static void enqueue_upper_write_op(APP_CONN *conn, UPPER_WRITE_OP *op) +{ + op->prev = conn->pending_upper_write_tail; + if (op->prev) + op->prev->next = op; + + conn->pending_upper_write_tail = op; + if (conn->pending_upper_write_head == NULL) + conn->pending_upper_write_head = op; +} + +static void dequeue_upper_write_op(APP_CONN *conn) +{ + if (conn->pending_upper_write_head == NULL) + return; + + if (conn->pending_upper_write_head->next == NULL) { + conn->pending_upper_write_head = NULL; + conn->pending_upper_write_tail = NULL; + } else { + conn->pending_upper_write_head = conn->pending_upper_write_head->next; + conn->pending_upper_write_head->prev = NULL; + } +} + +static void net_read_alloc(uv_handle_t *handle, + size_t suggested_size, uv_buf_t *buf) +{ + buf->base = malloc(suggested_size); + buf->len = suggested_size; +} + +static void on_rx_push(APP_CONN *conn) +{ + int srd, rc; + size_t buf_len = 4096; + + do { + if (!conn->app_read_cb) + return; + + void *buf = malloc(buf_len); + if (!buf) + return; + + srd = SSL_read(conn->ssl, buf, buf_len); + flush_write_buf(conn); + if (srd < 0) { + free(buf); + rc = SSL_get_error(conn->ssl, srd); + if (rc == SSL_ERROR_WANT_READ) + return; + } + + conn->app_read_cb(conn, buf, srd, conn->app_read_arg); + } while (srd == buf_len); +} + +static void net_error(APP_CONN *conn) +{ + conn->closed = 1; + set_rx(conn); + + if (conn->app_read_cb) + conn->app_read_cb(conn, NULL, 0, conn->app_read_arg); +} + +static void handle_pending_writes(APP_CONN *conn) +{ + int rc; + + if (conn->pending_upper_write_head == NULL) + return; + + do { + UPPER_WRITE_OP *op = conn->pending_upper_write_head; + rc = try_write(conn, op); + if (rc <= 0) + break; + + dequeue_upper_write_op(conn); + free(op); + } while (conn->pending_upper_write_head != NULL); + + set_rx(conn); +} + +static void net_read_done(uv_stream_t *stream, ssize_t nr, const uv_buf_t *buf) +{ + int rc; + APP_CONN *conn = (APP_CONN *)stream->data; + + if (nr < 0) { + free(buf->base); + net_error(conn); + return; + } + + if (nr > 0) { + int wr = BIO_write(conn->net_bio, buf->base, nr); + assert(wr == nr); + } + + free(buf->base); + + if (!conn->done_handshake) { + rc = handshake_ssl(conn); + if (rc < 0) { + fprintf(stderr, "handshake error: %d\n", rc); + return; + } + + if (!conn->done_handshake) + return; + } + + handle_pending_writes(conn); + on_rx_push(conn); +} + +static void set_rx(APP_CONN *conn) +{ + if (!conn->closed && (conn->app_read_cb || (!conn->done_handshake && conn->init_handshake) || conn->pending_upper_write_head != NULL)) + uv_read_start(conn->stream, net_read_alloc, net_read_done); + else + uv_read_stop(conn->stream); +} + +static void net_write_done(uv_write_t *req, int status) +{ + LOWER_WRITE_OP *op = (LOWER_WRITE_OP *)req->data; + APP_CONN *conn = op->conn; + + if (status < 0) { + fprintf(stderr, "UV write failed %d\n", status); + return; + } + + free(op->buf); + free(op); + + flush_write_buf(conn); +} + +static void flush_write_buf(APP_CONN *conn) +{ + int rc, rd; + LOWER_WRITE_OP *op; + uint8_t *buf; + + buf = malloc(4096); + if (!buf) + return; + + rd = BIO_read(conn->net_bio, buf, 4096); + if (rd <= 0) { + free(buf); + return; + } + + op = calloc(1, sizeof(LOWER_WRITE_OP)); + if (!op) + return; + + op->buf = buf; + op->conn = conn; + op->w.data = op; + op->b.base = (char *)buf; + op->b.len = rd; + + rc = uv_write(&op->w, conn->stream, &op->b, 1, net_write_done); + if (rc < 0) { + free(buf); + free(op); + fprintf(stderr, "UV write failed\n"); + return; + } +} + +static void handshake_done_ssl(APP_CONN *conn) +{ + conn->app_connect_cb(conn, 0, conn->app_connect_arg); +} + +static int handshake_ssl(APP_CONN *conn) +{ + int rc, rcx; + + conn->init_handshake = 1; + + rc = SSL_do_handshake(conn->ssl); + if (rc > 0) { + conn->done_handshake = 1; + handshake_done_ssl(conn); + set_rx(conn); + return 0; + } + + flush_write_buf(conn); + rcx = SSL_get_error(conn->ssl, rc); + if (rcx == SSL_ERROR_WANT_READ) { + set_rx(conn); + return 0; + } + + fprintf(stderr, "Handshake error: %d\n", rcx); + return -rcx; +} + +static int setup_ssl(APP_CONN *conn, const char *hostname) +{ + BIO *internal_bio = NULL, *net_bio = NULL; + SSL *ssl = NULL; + + ssl = SSL_new(conn->ctx); + if (!ssl) + return -1; + + SSL_set_connect_state(ssl); + + if (BIO_new_bio_pair(&internal_bio, 0, &net_bio, 0) <= 0) { + SSL_free(ssl); + return -1; + } + + SSL_set_bio(ssl, internal_bio, internal_bio); + + if (SSL_set1_host(ssl, hostname) <= 0) { + SSL_free(ssl); + return -1; + } + + if (SSL_set_tlsext_host_name(ssl, hostname) <= 0) { + SSL_free(ssl); + return -1; + } + + conn->net_bio = net_bio; + conn->ssl = ssl; + return handshake_ssl(conn); +} + +static void tcp_connect_done(uv_connect_t *tcp_connect, int status) +{ + int rc; + APP_CONN *conn = (APP_CONN *)tcp_connect->data; + + if (status < 0) { + uv_stop(uv_default_loop()); + return; + } + + rc = setup_ssl(conn, conn->hostname); + if (rc < 0) { + fprintf(stderr, "cannot init SSL\n"); + uv_stop(uv_default_loop()); + return; + } +} + +static void net_connect_fail_close_done(uv_handle_t *handle) +{ + APP_CONN *conn = (APP_CONN *)handle->data; + + free(conn); +} + +static int try_write(APP_CONN *conn, UPPER_WRITE_OP *op) +{ + int rc, rcx; + size_t written = op->written; + + while (written < op->buf_len) { + rc = SSL_write(conn->ssl, op->buf + written, op->buf_len - written); + if (rc <= 0) { + rcx = SSL_get_error(conn->ssl, rc); + if (rcx == SSL_ERROR_WANT_READ) { + op->written = written; + return 0; + } else { + if (op->cb != NULL) + op->cb(conn, -rcx, op->cb_arg); + return 1; /* op should be freed */ + } + } + + written += rc; + } + + if (op->cb != NULL) + op->cb(conn, 0, op->cb_arg); + + flush_write_buf(conn); + return 1; /* op should be freed */ +} + +static int write_deferred(APP_CONN *conn, const void *buf, size_t buf_len, app_write_cb *cb, void *arg) +{ + UPPER_WRITE_OP *op = calloc(1, sizeof(UPPER_WRITE_OP)); + if (!op) + return -1; + + op->buf = buf; + op->buf_len = buf_len; + op->conn = conn; + op->cb = cb; + op->cb_arg = arg; + + enqueue_upper_write_op(conn, op); + set_rx(conn); + flush_write_buf(conn); + return buf_len; +} + +static void teardown_continued(uv_handle_t *handle) +{ + APP_CONN *conn = (APP_CONN *)handle->data; + UPPER_WRITE_OP *op, *next_op; + char *teardown_done = conn->teardown_done; + + for (op=conn->pending_upper_write_head; op; op=next_op) { + next_op = op->next; + free(op); + } + + free(conn); + *teardown_done = 1; +} + +/* + * ============================================================================ + * Example driver for the above code. This is just to demonstrate that the code + * works and is not intended to be representative of a real application. + */ +static void post_read(APP_CONN *conn, void *buf, size_t buf_len, void *arg) +{ + if (!buf_len) { + free(buf); + uv_stop(uv_default_loop()); + return; + } + + fwrite(buf, 1, buf_len, stdout); + free(buf); +} + +static void post_write_get(APP_CONN *conn, int status, void *arg) +{ + if (status < 0) { + fprintf(stderr, "write failed: %d\n", status); + return; + } + + app_read_start(conn, post_read, NULL); +} + +static void post_connect(APP_CONN *conn, int status, void *arg) +{ + int wr; + const char tx_msg[] = "GET / HTTP/1.0\r\nHost: www.openssl.org\r\n\r\n"; + + if (status < 0) { + fprintf(stderr, "failed to connect: %d\n", status); + uv_stop(uv_default_loop()); + return; + } + + wr = app_write(conn, tx_msg, sizeof(tx_msg)-1, post_write_get, NULL); + if (wr < sizeof(tx_msg)-1) { + fprintf(stderr, "error writing request"); + return; + } +} + +int main(int argc, char **argv) +{ + int rc = 1; + SSL_CTX *ctx; + APP_CONN *conn = NULL; + struct addrinfo hints = {0}, *result = NULL; + + ctx = create_ssl_ctx(); + if (!ctx) + goto fail; + + hints.ai_family = AF_INET; + hints.ai_socktype = SOCK_STREAM; + hints.ai_flags = AI_PASSIVE; + rc = getaddrinfo("www.openssl.org", "443", &hints, &result); + if (rc < 0) { + fprintf(stderr, "cannot resolve\n"); + goto fail; + } + + conn = new_conn(ctx, "www.openssl.org", result->ai_addr, result->ai_addrlen, post_connect, NULL); + if (!conn) + goto fail; + + uv_run(uv_default_loop(), UV_RUN_DEFAULT); + + rc = 0; +fail: + teardown(conn); + freeaddrinfo(result); + uv_loop_close(uv_default_loop()); + teardown_ctx(ctx); +} diff --git a/util/markdownlint.rb b/util/markdownlint.rb index 51814c29f94..bc39bde18a7 100644 --- a/util/markdownlint.rb +++ b/util/markdownlint.rb @@ -8,6 +8,8 @@ rule 'MD003', :style => :setext_with_atx # Code blocks may be fenced or indented, both are OK... # but they must be consistent throughout each file. rule 'MD046', :style => :consistent +# Not possible to line-break tables. +rule 'MD013', :tables => false # Bug in mdl, https://github.com/markdownlint/markdownlint/issues/313 exclude_rule 'MD007' -- 2.47.2