mirror of https://github.com/logos-storage/nim-bearssl.git synced 2026-01-06 07:23:09 +00:00

split decls into separate modules in bearssl/abi (#27 )

* 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/`.

2022-06-14 19:33:00 +02:00

2.9 KiB

Raw Blame History

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 for abi) exposes thin wrappers around the raw ABI making the functions more convenient to use in Nim
bearssl/abi exposes 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* use var and not ptr
byte replaces unsigned char* - this type is predominantly used for byte buffers
uint used instead of csize_t - these are the same type in Nim, but spelled more conveniently
- Canonical nim code will have to be careful when converting existing int lengths, looking out for out-of-range values

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

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.