BearSSL wrapper in Nim
Go to file
Eugene Kabanov 554b464b34
Fix gcc-14 issues part 2. (#61)
* Fix recently discovered nim-2.0 gcc-14 issues.

* One more place to fix.
2024-06-27 01:42:04 +03:00
.github/workflows update ci.yml and be more explicit in .nimble (#60) 2024-06-27 01:22:34 +03:00
bearssl Fix gcc-14 issues part 2. (#61) 2024-06-27 01:42:04 +03:00
tests Release 023 (#59) 2024-06-02 16:55:11 +03:00
.gitignore update nimble build (#38) 2022-11-21 11:07:33 +01:00
.gitmodules Fix a submodule URL (otherwise, cloning was failing on a fresh Windows installation) 2022-03-04 13:29:44 +02:00
LICENSE-APACHEv2 Initial commit (copied from nim-libp2p) 2019-09-30 21:23:06 +03:00
LICENSE-MIT Initial commit (copied from nim-libp2p) 2019-09-30 21:23:06 +03:00
README.md remove appveyor/travis scripts and fix ci (#47) 2023-05-22 12:03:57 +02:00
bearssl.nim remove non-split api, bump version (#39) 2022-11-21 18:01:21 +01:00
bearssl.nimble update ci.yml and be more explicit in .nimble (#60) 2024-06-27 01:22:34 +03:00
config.nims Add setup files 2022-07-25 22:05:58 +03:00
nim.cfg move `-d:nimRawSetjmp` to config.nims (#30) 2022-06-24 20:09:29 +02:00
regenerate.sh update nimble build (#38) 2022-11-21 11:07:33 +01:00

README.md

bearssl

Stability: experimental License: MIT License: Apache Github action

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

In addition to the raw C-like api, convenience functions are added where applicable - these follow a similar set of conventions:

  • named after the function they simplify, but take advantage of types and overload support in Nim
  • help turn pointers and bytes into Nim types

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

or

at your option. This file may not be copied, modified, or distributed except according to those terms.