sodiumoxide

|Crate|文档|Gitter| |:---:|:-----------:|:--------:|:-----:|:------:|:----:| ||||

NaCl（发音为“salt”）是一个易于使用的高性能网络通信、加密、解密、签名等软件库。NaCl 的目标是提供构建更高级加密工具所需的所有核心操作。当然，已经存在其他库用于这些核心操作。NaCl 通过提高安全性、可用性和速度来推动技术进步。

Sodium 是 NaCl 的一个可移植、可交叉编译、可安装、可打包的分支（基于最新发布的上游版本 nacl-20110221），具有兼容的 API。

此包旨在提供一个类型安全且高效的 Rust 绑定，易于使用。由于 mem::MaybeUninit，需要 Rust >= 1.36.0。

基本用法

克隆

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

构建

cargo build

测试

cargo test

文档

cargo doc

文档将在 target/doc/... 中生成

大多数文档来自 NaCl，在 API 之间有所不同时进行了少量修改。

AES AEAD 变体的支持

AES AEAD 变体 crypto_aead_aes256gcm 需要 x86 的 AES 和 CLMUL 指令集扩展的硬件支持；您可以在 这里 了解为什么是这样。这些指令集扩展首次在 Intel Westmere（2010 年初）中提供，撰写本文时，x86 硬件对它们的支持几乎普遍。

Libsodium 提供了一个 API 用于运行时功能检测，并且不会阻止你在没有 AES 和 CMUL 表达式的机器上调用 crypto_aead_aes256gcm。这样做会导致运行时 SIGILL（非法指令）。相比之下，sodiumoxide 提供了一个 API，在执行运行时检查之前，阻止使用 crypto_aead_aes256gcm_ 函数族。需要注意的是，当使用 AES 时，使用 sodiumoxide::init() 是强制性的；除非你调用 init，否则即使你的运行时硬件支持 AES，调用 aead::aes256gcm::Aes256Gcm::new() 也总会返回 Err(_)。

依赖项

必须安装 C 编译器（cc，clang 等）才能从源代码构建 libsodium。

扩展使用

此项目包含了一个 libsodium 的快照，并默认构建它，优先选择静态构建的固定版本的本地库。

虽然强烈建议使用默认方式与固定版本一起使用，但你可以以几种方式使用此 crate

• 将其链接到系统上安装的库
• 将其链接到你自己构建的预编译库

你可以通过设置环境变量来完成此操作。

在 *nix 上的示例

使用 pkg-config

（Ubuntu: apt install pkg-config，OSX: brew install pkg-config 等）

export SODIUM_USE_PKG_CONFIG=1
cargo build

使用预编译库

请参阅 https://download.libsodium.org/doc/installation。

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

可选功能

有几个 可选功能 可用

• std（默认：启用）。当此功能被禁用时，sodiumoxide 使用 #![no_std] 构建。可能会丢失一些功能。

• serde（默认：启用）。允许使用 serde 库 对密钥、身份验证标签等进行序列化和反序列化。

• benchmarks（默认：禁用）。编译基准测试。需要 Rust 的夜间构建。

交叉编译

为 armv7-unknown-linux-gnueabihf 交叉编译

1. 安装依赖和工具链

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

2. 将以下内容添加到.cargo/config文件中

[target.armv7-unknown-linux-gnueabihf]
linker = "arm-linux-gnueabihf-gcc"

3. 通过运行以下命令进行构建

cargo build --release --target armv7-unknown-linux-gnueabihf

通过Docker跨平台编译armv7-unknown-linux-musleabihf

1. cargo.config

[target.armv7-unknown-linux-musleabihf]
linker = "arm-buildroot-linux-musleabihf-gcc"

2. 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}

为32位Linux进行交叉编译

1. 安装依赖和工具链

sudo apt update
sudo apt install build-essential gcc-multilib -y
rustup target add i686-unknown-linux-gnu

2. 通过运行以下命令进行构建

cargo build --release --target i686-unknown-linux-gnu

示例

待定

平台兼容性

Sodiumoxide已在以下系统上测试过

• Linux: 是
• Windows: 是（MSVC）
• Mac OS: 是
• IOS: 待定
• Android: 是

加入我们

在问题跟踪器中提交问题

主git仓库

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

许可协议

根据您的要求，许可协议为以下之一

• Apache许可证版本2.0，(LICENSE-APACHE或https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT许可证(LICENSE-MIT或http://opensource.org/licenses/MIT)

任选其一。

贡献

通过阅读CONTRIBUTING.md文档，了解更多关于如何为此项目做出贡献的信息。

除非您明确表示，否则根据Apache-2.0许可证定义的，任何有意提交以包含在您的工作中的贡献，都将根据上述方式双许可，不附加任何额外的条款或条件。

行为准则

我们相信创建一个为开发者提供支持的平台，并制定了一般性的行为准则。请阅读并采纳它，以帮助我们实现并维持期望的社区标准。