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