1Demo-Driven Design 2================== 3 4The OpenSSL project from time to time must evolve its public API surface in 5order to support new functionality and deprecate old functionality. When this 6occurs, the changes to OpenSSL's public API must be planned, discussed and 7agreed. One significant dimension which must be considered when considering any 8proposed API change is how a broad spectrum of real-world OpenSSL applications 9uses the APIs which exist today, as this determines the ways in which those 10applications will be affected by any proposed changes, the extent to which they 11will be affected, and the extent of any changes which will need to be made by 12codebases using OpenSSL to remain current with best practices for OpenSSL API 13usage. 14 15As such, it is useful for the OpenSSL project to have a good understanding of 16the usage patterns common in codebases which use OpenSSL, so that it can 17anticipate the impact of any evolution of its API on those codebases. This 18directory seeks to maintain a set of **API usage demos** which demonstrate a 19full spectrum of ways in which real-world applications use the OpenSSL APIs. 20This allows the project to discuss any proposed API changes in terms of the 21changes that would need to be made to each demo. Since the demos are 22representative of a broad spectrum of real-world OpenSSL-based applications, 23this ensures that API evolution is made both with reference to real-world API 24usage patterns and with reference to the impact on existing applications. 25 26As such, these demos are maintained in the OpenSSL repository because they are 27useful both to current and any future proposed API changes. The set of demos may 28be expanded over time, and the demos in this directory at any one time consitute 29a present body of understanding of API usage patterns, which can be used to plan 30API changes. 31 32For further background information on the premise of this approach, see [API 33long-term evolution](https://github.com/openssl/openssl/issues/17939). 34 35Scope 36----- 37 38The current emphasis is on client demos. Server support for QUIC is deferred to 39subsequent OpenSSL releases, and therefore is (currently) out of scope for this 40design exercise. 41 42The demos also deliberately focus on aspects of libssl usage which are likely to 43be relevant to QUIC and require changes; for example, how varied applications 44have libssl perform network I/O, and how varied applications create sockets and 45connections for use with libssl. The libssl API as a whole has a much larger 46scope and includes innumerate functions and myriad features; the intention is 47not to demonstrate all of these, because most of them will not be touched by 48QUIC. For example, while many users of OpenSSL may make use of APIs for client 49certificates or other TLS functionality, the use of QUIC is unlikely to have 50implications for these APIs and demos demonstrating such functionality are 51therefore out of scope. 52 53Background 54---------- 55 56These demos were developed after analysis of the following open source 57applications to determine libssl API usage patterns. The modally occuring usage 58patterns were determined and used to determine categories into which to classify 59the applications: 60 61| | Blk? | FD | 62|------------------|------|----| 63| mutt | S | AOSF | 64| vsftpd | S | AOSF | 65| exim | S | AOSFx | 66| wget | S | AOSF | 67| Fossil | S | BIOc | 68| librabbitmq | A | BIOx | 69| ngircd | A | AOSF | 70| stunnel | A | AOSFx | 71| Postfix | A | AOSF | 72| socat | A | AOSF | 73| HAProxy | A | BIOx | 74| Dovecot | A | BIOm | 75| Apache httpd | A | BIOx | 76| UnrealIRCd | A | AOSF | 77| wpa_supplicant | A | BIOm | 78| icecast | A | AOSF | 79| nginx | A | AOSF | 80| curl | A | AOSF | 81| Asterisk | A | AOSF | 82| Asterisk (DTLS) | A | BIOm/x | 83| pgbouncer | A | AOSF, BIOc | 84 85* Blk: Whether the application uses blocking or non-blocking I/O. 86 * S: Blocking 87 * A: Nonblocking 88* FD: Whether the application creates and owns its own FD. 89 * AOSF: Application owns, calls SSL_set_fd. 90 * AOSFx: Application owns, calls SSL_set_[rw]fd, different FDs for read/write. 91 * BIOs: Application creates a socket/FD BIO and calls SSL_set_bio. 92 Application created the connection. 93 * BIOx: Application creates a BIO with a custom BIO method and calls SSL_set_bio. 94 * BIOm: Application creates a memory BIO and does its own 95 pumping to/from actual socket, treating libssl as a pure state machine which 96 does no I/O itself. 97 * BIOc: Application uses BIO_s_connect-based methods such as BIO_new_ssl_connect 98 and leaves connection establishment to OpenSSL. 99 100Demos 101----- 102 103The demos found in this directory are: 104 105| | Type | Description | 106|-----------------|-------|-------------| 107| [ddd-01-conn-blocking](ddd-01-conn-blocking.c) | S-BIOc | A `BIO_s_connect`-based blocking example demonstrating exemplary OpenSSL API usage | 108| [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 | 109| [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) | 110| [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) | 111| [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) | 112| [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 | 113 114Availability of a default certificate store is assumed. `SSL_CERT_DIR` may be 115set when running the demos if necessary. 116
