README.md
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 constitute
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 numerous functions and 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
53[A report is available](REPORT.md) on the results of the DDD process following
54the completion of the development of the QUIC MVP (minimum viable product).
55
56Background
57----------
58
59These demos were developed after analysis of the following open source
60applications to determine libssl API usage patterns. The commonly occurring usage
61patterns were determined and used to determine categories into which to classify
62the 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
103Demos
104-----
105
106The 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
117On Ubuntu, libuv can be obtained by installing the package "libuv1-dev".
118
119Availability of a default certificate store is assumed. `SSL_CERT_DIR` may be
120set when running the demos if necessary.
121
