127 lines
3.4 KiB
Markdown
127 lines
3.4 KiB
Markdown
|
# nettle-sys
|
||
|
|
|
||
|
|
Low-level Rust bindings for the [Nettle cryptographic library](https://git.lysator.liu.se/nettle/nettle).
|
||
|
|
|
||
|
|
The documentation can be found [here](https://sequoia-pgp.gitlab.io/nettle-sys).
|
||
|
|
|
||
|
|
## Building
|
||
|
|
|
||
|
|
To build the Nettle bindings, you need a few libraries and support
|
||
|
|
packages. Notably, you need the Nettle cryptographic library version
|
||
|
|
3.4.1 or up. Some cryptographic algorithms are only available if
|
||
|
|
build against newer versions of Nettle, see [optional
|
||
|
|
features](#optional-features).
|
||
|
|
|
||
|
|
Please see below for OS-specific commands to install the needed
|
||
|
|
libraries.
|
||
|
|
|
||
|
|
### Debian
|
||
|
|
|
||
|
|
```shell
|
||
|
|
$ sudo apt install clang llvm pkg-config nettle-dev
|
||
|
|
```
|
||
|
|
|
||
|
|
### Arch Linux
|
||
|
|
|
||
|
|
```shell
|
||
|
|
$ sudo pacman -S clang pkg-config nettle --needed
|
||
|
|
```
|
||
|
|
|
||
|
|
### Fedora
|
||
|
|
|
||
|
|
```shell
|
||
|
|
$ sudo dnf install clang pkg-config nettle-devel
|
||
|
|
```
|
||
|
|
|
||
|
|
### macOS (Mojave), using MacPorts
|
||
|
|
|
||
|
|
```shell
|
||
|
|
$ sudo port install nettle pkgconfig
|
||
|
|
```
|
||
|
|
|
||
|
|
### Windows
|
||
|
|
|
||
|
|
#### MSYS2
|
||
|
|
|
||
|
|
You can install the needed libraries with the following command:
|
||
|
|
|
||
|
|
```shell
|
||
|
|
$ pacman -S mingw-w64-x86_64-{clang,pkg-config,nettle} libnettle-devel
|
||
|
|
```
|
||
|
|
|
||
|
|
## Optional features
|
||
|
|
|
||
|
|
Some cryptographic algorithms are only available if build against
|
||
|
|
newer versions of Nettle. Support for each feature is detected at
|
||
|
|
build time.
|
||
|
|
|
||
|
|
In case the automatic detection does not work for some reason, the
|
||
|
|
optional algorithms can be enabled or disabled by setting the given
|
||
|
|
environment variable.
|
||
|
|
|
||
|
|
Setting such a variable to `1`, `y`, `yes`, `enable`, or `true`
|
||
|
|
enables a feature. Any other value disables it.
|
||
|
|
|
||
|
|
| Algorithm | Required Nettle version | Environment variable |
|
||
|
|
|--------------|-------------------------|----------------------|
|
||
|
|
| cv448, ed448 | >= 3.6 | NETTLE_HAVE_CV448 |
|
||
|
|
| OCB | >= 3.9 | NETTLE_HAVE_OCB |
|
||
|
|
|
||
|
|
## Cross compilation
|
||
|
|
|
||
|
|
`nettle-sys` can be cross compiled using [`cross`](https://github.com/rust-embedded/cross) and a custom Docker container. First, build the container and install `cross`:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo install cross
|
||
|
|
docker -t nettle-sys/<toolchain>:1 docker/<toolchain>
|
||
|
|
```
|
||
|
|
|
||
|
|
Then, you can cross compile the project:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cross --target <toolchain> -v
|
||
|
|
```
|
||
|
|
|
||
|
|
The build artifacts will be placed in `target/debug/<toolchain>`.
|
||
|
|
|
||
|
|
## Static linking
|
||
|
|
|
||
|
|
By default, `nettle-sys` is dynamically linked to its dependencies.
|
||
|
|
|
||
|
|
By defining the `NETTLE_STATIC` environment variable during the build, it can
|
||
|
|
also be statically link to its dependencies:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
env NETTLE_STATIC=yes cargo build
|
||
|
|
```
|
||
|
|
|
||
|
|
This is particularly useful to produce standalone binaries that can be easily
|
||
|
|
distributed.
|
||
|
|
|
||
|
|
## Pregenerate `bindings.rs`
|
||
|
|
|
||
|
|
By default, `nettle-sys` invokes `bindgen` to generate bindings for
|
||
|
|
Nettle. In some build environments, this might not work due to
|
||
|
|
`bindgen` depending on `libllvm`. In this case, the `bindings.rs` may
|
||
|
|
be pregenerated, and used by setting:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
env NETTLE_PREGENERATED_BINDINGS=/path/to/bindings.rs cargo build
|
||
|
|
```
|
||
|
|
|
||
|
|
Note: `bindings.rs` is specific to target architecture, operating
|
||
|
|
system, and Nettle version.
|
||
|
|
|
||
|
|
# License
|
||
|
|
|
||
|
|
This project is licensed under either of
|
||
|
|
|
||
|
|
* GNU General Public License, Version 2.0, ([LICENSE-GPL2](LICENSE-GPL2) or
|
||
|
|
https://www.gnu.org/licenses/old-licenses/gpl-2.0.html)
|
||
|
|
* GNU General Public License, Version 3.0, ([LICENSE-GPL3](LICENSE-GPL3) or
|
||
|
|
https://www.gnu.org/licenses/gpl.html)
|
||
|
|
* GNU Lesser General Public License, Version 3.0, ([LICENSE-LGPL3](LICENSE-LGPL3) or
|
||
|
|
https://www.gnu.org/licenses/lgpl.html)
|
||
|
|
|
||
|
|
at your option.
|