1# Documentation 2 3The most up-to-date documentation is supposed to be available on the 4[BearSSL Web site](https://www.bearssl.org/). 5 6# Disclaimer 7 8BearSSL is considered beta-level software. Most planned functionalities 9are implemented; new evolution may still break both source and binary 10compatibility. 11 12Using BearSSL for production purposes would be a relatively bold but not 13utterly crazy move. BearSSL is free, open-source software, provided 14without any guarantee of fitness or reliability. That being said, it 15appears to behave properly, and only minor issues have been found (and 16fixed) so far. You are encourage to inspect its API and code for 17learning, testing and possibly contributing. 18 19The usage license is explicited in the `LICENSE.txt` file. This is the 20"MIT license". It can be summarised in the following way: 21 22 - You can use and reuse the library as you wish, and modify it, and 23 integrate it in your own code, and distribute it as is or in any 24 modified form, and so on. 25 26 - The only obligation that the license terms put upon you is that you 27 acknowledge and make it clear that if anything breaks, it is not my 28 fault, and I am not liable for anything, regardless of the type and 29 amount of collateral damage. The license terms say that the copyright 30 notice "shall be included in all copies or substantial portions of 31 the Software": this is how the disclaimer is "made explicit". 32 Basically, I have put it in every source file, so just keep it there. 33 34# Installation 35 36Right now, BearSSL is a simple library, along with a few test and debug 37command-line tools. There is no installer yet. The library _can_ be 38compiled as a shared library on some systems, but since the binary API 39is not fully stabilised, this is not a very good idea to do that right 40now. 41 42To compile the code, just type `make`. This will try to use sane 43"default" values. On a Windows system with Visual Studio, run a console 44with the environment initialised for a specific version of the C compiler, 45and type `nmake`. 46 47To override the default settings, create a custom configuration file in 48the `conf` directory, and invoke `make` (or `nmake`) with an explicit 49`CONF=` parameter. For instance, to use the provided `samd20.mk` 50configuration file (that targets cross-compilation for an Atmel board 51that features a Cortex-M0+ CPU), type: 52 53 make CONF=samd20 54 55The `conf/samd20.mk` file includes the `Unix.mk` file and then overrides 56some of the parameters, including the destination directory. Any custom 57configuration can be made the same way. 58 59Some compile-time options can be set through macros, either on the 60compiler command-line, or in the `src/config.h` file. See the comments 61in that file. Some settings are autodetected but they can still be 62explicitly overridden. 63 64When compilation is done, the library (static and DLL, when appropriate) 65and the command-line tools can be found in the designated build 66directory (by default named `build`). The public headers (to be used 67by applications linked against BearSSL) are in the `inc/` directory. 68 69To run the tests: 70 71 - `testcrypto all` runs the cryptographic tests (test vectors on all 72 implemented cryptogaphic functions). It can be slow. You can also 73 run a selection of the tests by providing their names (run 74 `testcrypto` without any parameter to see the available names). 75 76 - `testspeed all` runs a number of performance benchmarks, there again 77 on cryptographic functions. It gives a taste of how things go on the 78 current platform. As for `testcrypto`, specific named benchmarks can 79 be executed. 80 81 - `testx509` runs X.509 validation tests. The test certificates are 82 all in `test/x509/`. 83 84The `brssl` command-line tool produced in the build directory is a 85stand-alone binary. It can exercise some of the functionalities of 86BearSSL, in particular running a test SSL client or server. It is not 87meant for production purposes (e.g. the SSL client has a mode where it 88disregards the inability to validate the server's certificate, which is 89inherently unsafe, but convenient for debug). 90 91**Using the library** means writing some application code that invokes 92it, and linking with the static library. The header files are all in the 93`inc` directory; copy them wherever makes sense (e.g. in the 94`/usr/local/include` directory). The library itself (`libbearssl.a`) is 95what you link against. 96 97Alternatively, you may want to copy the source files directly into your 98own application code. This will make integrating ulterior versions of 99BearSSL more difficult. If you still want to go down that road, then 100simply copy all the `*.h` and `*.c` files from the `src` and `inc` 101directories into your application source code. In the BearSSL source 102archive, the source files are segregated into various sub-directories, 103but this is for my convenience only. There is no technical requirement 104for that, and all files can be dumped together in a simple directory. 105 106Dependencies are simple and systematic: 107 108 - Each `*.c` file includes `inner.h` 109 - `inner.h` includes `config.h` and `bearssl.h` 110 - `bearssl.h` includes the other `bearssl_*.h` 111 112# Versioning 113 114I follow this simple version numbering scheme: 115 116 - Version numbers are `x.y` or `x.y.z` where `x`, `y` and `z` are 117 decimal integers (possibly greater than 10). When the `.z` part is 118 missing, it is equivalent to `.0`. 119 120 - Backward compatibility is maintained, at both source and binary levels, 121 for each major version: this means that if some application code was 122 designed for version `x.y`, then it should compile, link and run 123 properly with any version `x.y'` for any `y'` greater than `y`. 124 125 The major version `0` is an exception. You shall not expect that any 126 version that starts with `0.` offers any kind of compatibility, 127 either source or binary, with any other `0.` version. (Of course I 128 will try to maintain some decent level of source compatibility, but I 129 make no promise in that respect. Since the API uses caller-allocated 130 context structures, I already know that binary compatibility _will_ 131 be broken.) 132 133 - Sub-versions (the `y` part) are about added functionality. That is, 134 it can be expected that `1.3` will contain some extra functions when 135 compared to `1.2`. The next version level (the `z` part) is for 136 bugfixes that do not add any functionality. 137