c4aec8b664
* split `decls.nim` into smaller modules - allows using parts of the ABI without compiling all of `bearssl` * deprecate functions with `Br` prefix - there are duplicate exports both with and without `Br` for the same function and we use both in consumers like `chronos` and `libp2p` * fix several cases of incorrectly mapped types * use `var` for certain arguments that can't be `nil` * add script to regenerate ABI with `c2nim` * consistently use `uint` for length (`int` was sometimes used) The Split likely needs more cleanup work - this is a first cut to get the idea in place. In the new layout, `bearssl/abi/` contains "raw" nim mappings while hand-written helpers are in `bearssl/`.
bearssl
Simple BearSSL wrapper for Nim, fully integrated with the Nim build system.
Applications using nim-bearssl are fully stand-alone, needing no additional DLL or shared library.
Usage
The library is organised into two parts:
bearssl/(except forabi) exposes thin wrappers around the raw ABI making the functions more convenient to use in Nimbearssl/abiexposes the raw C functions of bearssl
For each bearssl header file, a corresponding Nim file exists - bearssl_rand.h ~ bearssl/rand.nim.
# You can import the whole library
import bearssl
# ... or simply parts thereof, which can save compilation time
import bearssl/rand
In general, the mappings follow the conventions of the original BearSSL library closely. The following conventions exist:
- the
br_prefix has been dropped throughout - functions taking a
XxxContext*usevarand notptr bytereplacesunsigned char*- this type is predominantly used for byte buffersuintused instead ofcsize_t- these are the same type in Nim, but spelled more conveniently- Canonical nim code will have to be careful when converting existing
intlengths, looking out for out-of-range values
- Canonical nim code will have to be careful when converting existing
Installation
You can install the developement version of the library through nimble with the following command:
nimble install bearssl
BearSSL itself is compiled as part of your project - there is no need to install any third-party libraries.
Developer notes
When updating the library, c2nim is used via regenerate.sh to update the RAW ABI files. Manual editing is then needed to make a few adjustments to the mapping, after which the files can be generated.
When adding new convenience functions, these should be added to bearssl/ instead of the generated files.
License
Licensed and distributed under either of
- MIT license: LICENSE-MIT or http://opensource.org/licenses/MIT
or
- Apache License, Version 2.0, (LICENSE-APACHEv2 or http://www.apache.org/licenses/LICENSE-2.0)
at your option. This file may not be copied, modified, or distributed except according to those terms.