1  # Documentation
  2  
  3  The most up-to-date documentation is supposed to be available on the
  4  [BearSSL Web site](https://www.bearssl.org/).
  5  
  6  # Disclaimer
  7  
  8  BearSSL is considered beta-level software. Most planned functionalities
  9  are implemented; new evolution may still break both source and binary
 10  compatibility.
 11  
 12  Using BearSSL for production purposes would be a relatively bold but not
 13  utterly crazy move. BearSSL is free, open-source software, provided
 14  without any guarantee of fitness or reliability. That being said, it
 15  appears to behave properly, and only minor issues have been found (and
 16  fixed) so far. You are encourage to inspect its API and code for
 17  learning, testing and possibly contributing.
 18  
 19  The 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  
 36  Right now, BearSSL is a simple library, along with a few test and debug
 37  command-line tools. There is no installer yet. The library _can_ be
 38  compiled as a shared library on some systems, but since the binary API
 39  is not fully stabilised, this is not a very good idea to do that right
 40  now.
 41  
 42  To 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
 44  with the environment initialised for a specific version of the C compiler,
 45  and type `nmake`.
 46  
 47  To override the default settings, create a custom configuration file in
 48  the `conf` directory, and invoke `make` (or `nmake`) with an explicit
 49  `CONF=` parameter. For instance, to use the provided `samd20.mk`
 50  configuration file (that targets cross-compilation for an Atmel board
 51  that features a Cortex-M0+ CPU), type:
 52  
 53      make CONF=samd20
 54  
 55  The `conf/samd20.mk` file includes the `Unix.mk` file and then overrides
 56  some of the parameters, including the destination directory. Any custom
 57  configuration can be made the same way.
 58  
 59  Some compile-time options can be set through macros, either on the
 60  compiler command-line, or in the `src/config.h` file. See the comments
 61  in that file. Some settings are autodetected but they can still be
 62  explicitly overridden.
 63  
 64  When compilation is done, the library (static and DLL, when appropriate)
 65  and the command-line tools can be found in the designated build
 66  directory (by default named `build`). The public headers (to be used
 67  by applications linked against BearSSL) are in the `inc/` directory.
 68  
 69  To 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  
 84  The `brssl` command-line tool produced in the build directory is a
 85  stand-alone binary. It can exercise some of the functionalities of
 86  BearSSL, in particular running a test SSL client or server. It is not
 87  meant for production purposes (e.g. the SSL client has a mode where it
 88  disregards the inability to validate the server's certificate, which is
 89  inherently unsafe, but convenient for debug).
 90  
 91  **Using the library** means writing some application code that invokes
 92  it, 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
 95  what you link against.
 96  
 97  Alternatively, you may want to copy the source files directly into your
 98  own application code. This will make integrating ulterior versions of
 99  BearSSL more difficult. If you still want to go down that road, then
100  simply copy all the `*.h` and `*.c` files from the `src` and `inc`
101  directories into your application source code. In the BearSSL source
102  archive, the source files are segregated into various sub-directories,
103  but this is for my convenience only. There is no technical requirement
104  for that, and all files can be dumped together in a simple directory.
105  
106  Dependencies 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  
114  I 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.