Need help with sodiumoxide?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

sodiumoxide
602 Stars 139 Forks Other 939 Commits 19 Opened issues

Description

Sodium Oxide: Fast cryptographic library for Rust (bindings to libsodium)

Services available

!
?

Need anything else?

Contributors list

sodiumoxide

|Crate|Documentation|Gitter| |:---:|:-----------:|:--------:|:-----:|:------:|:----:| |Crates.io|Docs|Gitter|

NaCl (pronounced "salt") is a new easy-to-use high-speed software library for network communication, encryption, decryption, signatures, etc. NaCl's goal is to provide all of the core operations needed to build higher-level cryptographic tools. Of course, other libraries already exist for these core operations. NaCl advances the state of the art by improving security, by improving usability, and by improving speed.

Sodium is a portable, cross-compilable, installable, packageable fork of NaCl (based on the latest released upstream version nacl-20110221), with a compatible API.

This package aims to provide a type-safe and efficient Rust binding that's just as easy to use. Rust >= 1.36.0 is required because of mem::MaybeUninit.

Basic usage

Cloning

git clone https://github.com/sodiumoxide/sodiumoxide.git
cd sodiumoxide
git submodule update --init --recursive

Building

cargo build

Testing

cargo test

Documentation

cargo doc

Documentation will be generated in target/doc/...

Most documentation is taken from NaCl, with minor modification where the API differs between the C and Rust versions.

Support for the AES AEAD Variant

The AES AEAD variant

crypto_aead_aes256gcm
requires hardware support for the
AES
and
CLMUL
instruction set extensions to x86; you can read why that's the case here. These instruction set extensions were first made available in Intel Westmere (early 2010) and at the time of writing x86 hardware support for them is near universal.

Libsodium exposes an API for runtime feature detection and doesn't prevent you from calling

crypto_aead_aes256gcm
on a machine lacking
AES
and
CMUL
expressions; doing so will result in a runtime
SIGILL
(illegal instruction). By contrast sodiumoxide exposes an API that precludes the use of the
crypto_aead_aes256gcm_*
family of functions without performing the runtime check. It's important to note that the use of
sodiumoxide::init()
is mandatory when using AES; unless you call
init
calls
aead::aes256gcm::Aes256Gcm::new()
will always return
Err(_)
even if your runtime hardware supports AES.

Dependencies

C compiler (

cc
,
clang
, ...) must be installed in order to build libsodium from source.

Extended usage

This project contains a snapshot of libsodium and builds it by default, favouring a statically-built, fixed version of the native library.

Although it is highly recommended to use the default way with the pinned version, there are several ways you may want to use this crate: * link it against the library installed on your system * link it against a precompiled library that you built on your own

You can do this by setting environment variables.

|Name|Description|Example value|Notes| | :- | :-------- | :---------- | :-- | |

SODIUM_LIB_DIR
|Where to find a precompiled library|
/usr/lib/x86_64-linux-gnu/
|The value should be set to the directory containing
.so
,
.a
,
.la
,
.dll
or
.lib
| |
SODIUM_SHARED
|Tell
rustc
to link the library dynamically|
1
|Works only with
SODIUM_LIB_DIR
. We check only the presence| |
SODIUM_USE_PKG_CONFIG
|Tell build.rs to find system library using pkg-config|
1
|We check only the presence| |
SODIUM_DISABLE_PIE
|Build with
--disable-pie
|
1
|Certain situations may require building libsodium configured with
--disable-pie
. Useful for !Windows only and when building libsodium from source. We check only the presence|

Examples on *nix

Using pkg-config

(Ubuntu:

apt install pkg-config
, OSX:
brew install pkg-config
, ...)
export SODIUM_USE_PKG_CONFIG=1
cargo build

Using precompiled library

See https://download.libsodium.org/doc/installation.

export SODIUM_LIB_DIR=/home/user/libsodium-1.0.18/release/lib/
export SODIUM_SHARED=1
cargo build

Optional features

Several optional features are available:

  • std
    (default: enabled). When this feature is disabled, sodiumoxide builds using
    #![no_std]
    . Some functionality may be lost.
  • serde
    (default: enabled). Allows serialization and deserialization of keys, authentication tags, etc. using the serde library.
  • benchmarks
    (default: disabled). Compile benchmark tests. Requires a nightly build of Rust.

Cross-Compiling

Cross-Compiling for armv7-unknown-linux-gnueabihf

  1. Install dependencies and toolchain:
sudo apt update
sudo apt install build-essential gcc-arm-linux-gnueabihf libc6-armhf-cross libc6-dev-armhf-cross -y
rustup target add armv7-unknown-linux-gnueabihf
  1. Add the following to a .cargo/config file:
[target.armv7-unknown-linux-gnueabihf]
linker = "arm-linux-gnueabihf-gcc"
  1. Build by running:
cargo build --release --target armv7-unknown-linux-gnueabihf

Cross-Compiling for armv7-unknown-linux-musleabihf via docker

  1. cargo.config:
[target.armv7-unknown-linux-musleabihf]
linker = "arm-buildroot-linux-musleabihf-gcc"
  1. Dockerfile:
FROM rust:1.36.0

ENV TARGET="armv7-unknown-linux-musleabihf"

ARG TOOLCHAIN_ARM7="armv7-eabihf--musl--stable-2018.02-2" ARG TC_ARM7_URL="https://toolchains.bootlin.com/downloads/releases/toolchains/armv7-eabihf/tarballs/${TOOLCHAIN_ARM7}.tar.bz2"

RUN rustup target add ${TARGET} COPY cargo.config "${CARGO_HOME}/config"

WORKDIR /opt RUN curl -o- ${TC_ARM7_URL} | tar -xjf -

ENV PATH="${PATH}:/opt/${TOOLCHAIN_ARM7}/bin" ENV CC_armv7_unknown_linux_musleabihf=arm-buildroot-linux-musleabihf-gcc ENV CXX_armv7_unknown_linux_musleabihf=arm-buildroot-linux-musleabihf-g++ ENV LD_armv7_unknown_linux_musleabihf=arm-buildroot-linux-musleabihf-ld

WORKDIR /work RUN git clone https://github.com/sodiumoxide/sodiumoxide

WORKDIR /work/sodiumoxide RUN cargo build --target=${TARGET}

Cross-Compiling for 32-bit Linux

  1. Install dependencies and toolchain:
sudo apt update
sudo apt install build-essential gcc-multilib -y
rustup target add i686-unknown-linux-gnu
  1. Build by running:
cargo build --release --target i686-unknown-linux-gnu

Examples

TBD

Platform Compatibiility

Sodiumoxide has been tested on:

  • Linux: Yes
  • Windows: Yes (MSVC)
  • Mac OS: Yes
  • IOS: TODO
  • Android: Yes

Join in

File bugs in the issue tracker

Master git repository

git clone https://github.com/sodiumoxide/sodiumoxide.git

License

Licensed under either of

  • Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
  • MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Go through the CONTRIBUTING.md document to know more about how to contribute to this project.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Code of Conduct

We believe in creating an enabling community for developers and have laid out a general code of conduct. Please read and adopt it to help us achieve and maintain the desired community standards.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.