_ Git - BearSSL/blob - README.txt

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