Changeset View
Changeset View
Standalone View
Standalone View
head/contrib/bearssl/README.txt
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
# Documentation | |||||
The most up-to-date documentation is supposed to be available on the | |||||
[BearSSL Web site](https://www.bearssl.org/). | |||||
# Disclaimer | |||||
BearSSL is considered beta-level software. Most planned functionalities | |||||
are implemented; new evolution may still break both source and binary | |||||
compatibility. | |||||
Using BearSSL for production purposes would be a relatively bold but not | |||||
utterly crazy move. BearSSL is free, open-source software, provided | |||||
without any guarantee of fitness or reliability. That being said, it | |||||
appears to behave properly, and only minor issues have been found (and | |||||
fixed) so far. You are encourage to inspect its API and code for | |||||
learning, testing and possibly contributing. | |||||
The usage license is explicited in the `LICENSE.txt` file. This is the | |||||
"MIT license". It can be summarised in the following way: | |||||
- You can use and reuse the library as you wish, and modify it, and | |||||
integrate it in your own code, and distribute it as is or in any | |||||
modified form, and so on. | |||||
- The only obligation that the license terms put upon you is that you | |||||
acknowledge and make it clear that if anything breaks, it is not my | |||||
fault, and I am not liable for anything, regardless of the type and | |||||
amount of collateral damage. The license terms say that the copyright | |||||
notice "shall be included in all copies or substantial portions of | |||||
the Software": this is how the disclaimer is "made explicit". | |||||
Basically, I have put it in every source file, so just keep it there. | |||||
# Installation | |||||
Right now, BearSSL is a simple library, along with a few test and debug | |||||
command-line tools. There is no installer yet. The library _can_ be | |||||
compiled as a shared library on some systems, but since the binary API | |||||
is not fully stabilised, this is not a very good idea to do that right | |||||
now. | |||||
To compile the code, just type `make`. This will try to use sane | |||||
"default" values. On a Windows system with Visual Studio, run a console | |||||
with the environment initialised for a specific version of the C compiler, | |||||
and type `nmake`. | |||||
To override the default settings, create a custom configuration file in | |||||
the `conf` directory, and invoke `make` (or `nmake`) with an explicit | |||||
`CONF=` parameter. For instance, to use the provided `samd20.mk` | |||||
configuration file (that targets cross-compilation for an Atmel board | |||||
that features a Cortex-M0+ CPU), type: | |||||
make CONF=samd20 | |||||
The `conf/samd20.mk` file includes the `Unix.mk` file and then overrides | |||||
some of the parameters, including the destination directory. Any custom | |||||
configuration can be made the same way. | |||||
Some compile-time options can be set through macros, either on the | |||||
compiler command-line, or in the `src/config.h` file. See the comments | |||||
in that file. Some settings are autodetected but they can still be | |||||
explicitly overridden. | |||||
When compilation is done, the library (static and DLL, when appropriate) | |||||
and the command-line tools can be found in the designated build | |||||
directory (by default named `build`). The public headers (to be used | |||||
by applications linked against BearSSL) are in the `inc/` directory. | |||||
To run the tests: | |||||
- `testcrypto all` runs the cryptographic tests (test vectors on all | |||||
implemented cryptogaphic functions). It can be slow. You can also | |||||
run a selection of the tests by providing their names (run | |||||
`testcrypto` without any parameter to see the available names). | |||||
- `testspeed all` runs a number of performance benchmarks, there again | |||||
on cryptographic functions. It gives a taste of how things go on the | |||||
current platform. As for `testcrypto`, specific named benchmarks can | |||||
be executed. | |||||
- `testx509` runs X.509 validation tests. The test certificates are | |||||
all in `test/x509/`. | |||||
The `brssl` command-line tool produced in the build directory is a | |||||
stand-alone binary. It can exercise some of the functionalities of | |||||
BearSSL, in particular running a test SSL client or server. It is not | |||||
meant for production purposes (e.g. the SSL client has a mode where it | |||||
disregards the inability to validate the server's certificate, which is | |||||
inherently unsafe, but convenient for debug). | |||||
**Using the library** means writing some application code that invokes | |||||
it, and linking with the static library. The header files are all in the | |||||
`inc` directory; copy them wherever makes sense (e.g. in the | |||||
`/usr/local/include` directory). The library itself (`libbearssl.a`) is | |||||
what you link against. | |||||
Alternatively, you may want to copy the source files directly into your | |||||
own application code. This will make integrating ulterior versions of | |||||
BearSSL more difficult. If you still want to go down that road, then | |||||
simply copy all the `*.h` and `*.c` files from the `src` and `inc` | |||||
directories into your application source code. In the BearSSL source | |||||
archive, the source files are segregated into various sub-directories, | |||||
but this is for my convenience only. There is no technical requirement | |||||
for that, and all files can be dumped together in a simple directory. | |||||
Dependencies are simple and systematic: | |||||
- Each `*.c` file includes `inner.h` | |||||
- `inner.h` includes `config.h` and `bearssl.h` | |||||
- `bearssl.h` includes the other `bearssl_*.h` | |||||
# Versioning | |||||
I follow this simple version numbering scheme: | |||||
- Version numbers are `x.y` or `x.y.z` where `x`, `y` and `z` are | |||||
decimal integers (possibly greater than 10). When the `.z` part is | |||||
missing, it is equivalent to `.0`. | |||||
- Backward compatibility is maintained, at both source and binary levels, | |||||
for each major version: this means that if some application code was | |||||
designed for version `x.y`, then it should compile, link and run | |||||
properly with any version `x.y'` for any `y'` greater than `y`. | |||||
The major version `0` is an exception. You shall not expect that any | |||||
version that starts with `0.` offers any kind of compatibility, | |||||
either source or binary, with any other `0.` version. (Of course I | |||||
will try to maintain some decent level of source compatibility, but I | |||||
make no promise in that respect. Since the API uses caller-allocated | |||||
context structures, I already know that binary compatibility _will_ | |||||
be broken.) | |||||
- Sub-versions (the `y` part) are about added functionality. That is, | |||||
it can be expected that `1.3` will contain some extra functions when | |||||
compared to `1.2`. The next version level (the `z` part) is for | |||||
bugfixes that do not add any functionality. |