3 BearSSL is for now considered alpha-level software. This means that it
4 probably still has some bugs, possibly very serious ones (e.g. buffer
5 overflows -- one of the perks of using C as programming language). It
6 still lacks some functionalities. The API will probably change and may
7 break both source and binary compatibility.
9 In other words, you would be quite mad to use it for any production
10 purpose. Right now, this is for learning, testing and possibly
13 The usage license is explicited in the `LICENSE.txt` file. This is the
14 "MIT license". It can be summarised in the following way:
16 - You can use and reuse the library as you wish, and modify it, and
17 integrate it in your own code, and distribute it as is or in any
18 modified form, and so on.
20 - The only obligation that the license terms put upon you is that you
21 acknowledge and make it clear that if anything breaks, it is not my
22 fault, and I am not liable for anything, regardless of the type and
23 amount of collateral damage. The license terms say that the copyright
24 notice "shall be included in all copies or substantial portions of
25 the Software": this is how the disclaimer is "made explicit".
26 Basically, I have put it in every source file, so just keep it there.
30 As of version 0.1, BearSSL is a simple static library. Most of the
31 process is rather manual and old-style, and there is no installer (this
32 will be added in a later version, in particular when all the man pages
33 for BearSSL functions are written).
35 1. Have a look at the top of the `Makefile`. There you can configure the
36 command names and flags for invoking the C compiler, linker, and
37 static library archiver.
39 2. There are a few configurable switches in `src/config.h`. These switches
40 relate to compile-time options, e.g. support of a system-provided
41 random source. On usual platforms (e.g. Linux or OS X), auto-detection
42 should work, but you can always override things with `config.h`.
44 3. Type `make`. This should produce the static library (`libbearssl.a`),
45 the test executables (`testcrypto`, `testspeed` and `testx509`), and
46 the command-line debug tool (`brssl`). You might want to run the tests:
48 - `testcrypto all` runs the cryptographic tests (test vectors on all
49 implemented cryptogaphic functions). It can be slow.
51 - `testspeed all` runs a number of performance benchmarks, there again
52 on cryptographic functions. It gives a taste of how things go on the
55 - `testx509` runs X.509 validation tests. The test certificates are
58 4. The `brssl` command-line tool is a stand-alone binary. It can exercise
59 some of the functionalities of BearSSL, in particular running a test
60 SSL client or server. It is not meant for production purposes (e.g.
61 the SSL client has a mode where it disregards the inability to validate
62 the server's certificate, which is inherently unsafe, but convenient
65 5. Using the library means writing some application code that invokes it,
66 and linking with the static library. The header files are all in the
67 `inc` directory; copy them wherever makes sense (e.g. in the
68 `/usr/local/include` directory). The library itself (`libbearssl.a`)
69 is what you link against.
71 Alternatively, you may want to copy the source files directly into
72 your own application code. This will make integrating ulterior versions
73 of BearSSL more difficult. If you still want to go down that road,
74 then simply copy all the `*.h` and `*.c` files from the `src` and `inc`
75 directories into your application source code. In the BearSSL source
76 archive, the source files are segregated into various sub-directories,
77 but this is for my convenience only. There is no technical requirement
78 for that, and all files can be dumped together in a simple directory.
80 Dependencies are simple and systematic:
82 - Each `*.c` file includes `inner.h`
83 - `inner.h` includes `config.h` and `bearssl.h`
84 - `bearssl.h` includes the other `bearssl_*.h`
88 I follow this simple version numbering scheme:
90 - Version numbers are `x.y` or `x.y.z` where `x`, `y` ans `z` are
91 decimal integers (possibly greater than 10). When the `.z` part is
92 missing, it is equivalent to `.0`.
94 - Backward compatibility is maintained, at both source and binary levels,
95 for each major version: this means that if some application code was
96 designed for version `x.y`, then it should compile, link and run
97 properly with any version `x.y'` for any `y'` greater than `y`.
99 The major version `0` is an exception. You shall not expect that any
100 version that starts with `0.` offers any kind of compatibility,
101 either source or binary, with any other `0.` version. (Of course I
102 will try to maintain some decent level of source compatibility, but I
103 make no promise in that respect. Since the API uses caller-allocated
104 context structures, I already know that binary compatibility _will_
107 - Sub-versions (the `y` part) are about added functionality. That is,
108 it can be expected that `1.3` will contain some extra functions when
109 compared to `1.2`. The next version level (the `z` part) is for
110 bugfixes that do not add any functionality.
114 Right now there is little documentation. The following principles are
117 - All public symbols (global functions and data elements, macros) have
118 a name that starts with `br_` or `BR_`.
120 - The header files (the `bearssl_*.h` in the `inc` directory) contain
121 for now the most complete documentation (as comments).
123 - Context structures are allocated by the caller. BearSSL does not
124 contain any single `malloc()` call; this means that there is no
125 "freeing up" call to be done. When you don't need some BearSSL
126 functionality, just cease to call it, and that's it.
128 - BearSSL contains no modifiable static data. It is thus thread-safe
129 and reentrant, _for distinct contexts_. Accessing the same context
130 structure from distinct threads, though, is a recipe for disaster.
132 - The main SSL I/O API is organised as a state machine. A running
133 SSL engine (client or server) has four I/O ports:
135 - It can receive bytes from the transport medium ("record data").
136 - It can send bytes to the transport medium.
137 - It can receive application data, to be sent to the peer through
139 - It can produce application data, built from the records sent by
142 BearSSL never performs I/O by itself; it expects the caller to
143 provide or retrieve the data. Each port consists in a pair of
144 functions: one yields the pointer to the buffer from which data
145 can be read or to which data can be written, and the maximum
146 size for such an operation; the other function is used to
147 inform the engine about how many bytes were actually read or
150 For instance, if the `br_ssl_engine_sendrec_buf()` function returns a
151 non-NULL pointer, then this means that there are bytes to be sent to
152 the transport medium. When the caller has indeed sent some or all of
153 these bytes, it informs the engine with
154 `br_ssl_engine_sendrec_ack()`.
156 This state-machine API means that the engine never blocks. Each
157 invocation may trigger computations, but will always return as
158 promptly as the CPU power allows. All the I/O waiting is supposed to
159 be done on the outside. This structure allows managing several
160 concurrent SSL engines, along with other I/O tasks, with a single
161 mono-threaded loop using `select()` or `poll()`. It also makes it
162 easier to integrate BearSSL with various transport mechanisms (e.g.
163 messages in the EAP-TLS authentication framework).
165 - Nevertheless, there are situations where simple blocking calls _can_
166 be used, and are convenient. For these situations, use the
167 `br_sslio_context` wrapper. Then do blocking reads and writes with
168 `br_sslio_read()` and similar functions. The sample client code
169 in `samples/client_basic.c` shows how such things are done.
projects / BearSSL / blob