@romangol 2017-08-26T11:01:32.000000Z 字数 40653 阅读 11311

Sodium密码学软件库（libsodium）手册中文版

未分类

介绍

Sodium是一个现代易于使用的软件库，它可以用来做加密、解密、签名、口令Hash以及更多的事情。

它是一个可移植的、可交叉编译的、可安装的基于NaCl开发的加密库，具有兼容的API以及扩展的API，来进一步提高可用性。

它的目标是提供构建更高级加密工具所需的所有核心操作。

Sodium支持各种编译器和操作系统，包括Windows（MinGW或Visual Studio，x86和x86_64）、iOS和Android。

这个设计选择强调安全性，“魔术常量”(magic constants)有明确的理论基础。

尽管强调了高安全性，但是与NIST标准的大多数实现相比，原语的速度要快得多。

1.0.11版本于2016年7月31日发布。

下载libsodium库

邮件列表

邮件列表可用于讨论libsodium。

为了加入，只需发送一个随机邮件到sodium-subscribe {at} pureftpd {dot} org。

离线文档

您可以下载ePUB（适用于iPad、iPhone及Mac）格式，MOBI（适用于Kindle）格式和PDF格式的文档：https://www.gitbook.com/book/jedisct1/libsodium/details

证书

ISC许可证。

有关详细信息，请参阅LICENSE文件。

安装

在类Unix系统上编译

Sodium是一个共享库，具有机器独立的头文件集合，因此它方便被第三方项目使用。

这个库是使用自动工具构建的，这让它易于打包。

安装很简单，能利用多核进行编译和测试。

下载libsodium压缩包，接着按照以下步骤：

$ ./configure
	$ make && make check
# make install

在Windows上编译

通常不需要在Windows上编译，因为MinGW和Visual Studio的预构建库可用（见下文）。

但是，如果您想要自己亲手编译，首先从Git中克隆稳定分支库。

Visual Studio解决方案可以在builds/msvc目录中找到。

为了用MingW编译，在Win32或x64平台上运行./dist-build/msys2-win32.sh或./dist-build/msys2-win64.sh。

预构建库

Visual Studio 2010，2012，2013和2015的预构建x86和x86_64库可用， MinGW32和MinGW64的预构建库也可用。

它们包括头文件，以及用于所有受支持的编译器版本的静态（.LIB）和共享（.DLL）库。

Visual Studio注意事项

想要静态链接Sodium的项目必须定义一个名为SODIUM_STATIC的宏，这将阻止符号定义引用__dllexport。

交叉编译

完全支持交叉编译。这是使用ARM嵌入式处理器的GNU工具对ARM进行交叉编译的一个例子：

$ export PATH=/path/to/gcc-arm-none-eabi/bin:$PATH
$ export LDFLAGS='--specs=nosys.specs'
	$ export CFLAGS='-Os'
$ ./configure --host=arm-none-eabi --prefix=/install/path
	$ make install

make check还可以构建测试应用程序，但这些应用程序必须在本地平台上运行。

注意：--specs = nosys.specs仅用于ARM编译工具链。

用CompCert编译

可以使用CompCert编译器来编译发行版本。但在使用CompCert时，即使在小端系统上，Autoconf脚本可能会错误地将字节排序检测为大端序列。

您可能需要手动预定义ac_cv_c_bigendian=no，以解决此问题。

使用CompCert在一个小端系统上编译Sodium的典型命令行是：

env CC=ccomp ac_cv_c_bigendian=no \
    CFLAGS="-O2 -fstruct-passing" ./configure \
    --disable-shared --enable-static && \
make check && make install

稳定分支

我们建议在克隆libsodium git仓库时使用分布式压缩包，特别是当压缩包不需要libtool或autotools这样的依赖。

然而，当克隆Git存储库更方便的时候，稳定分支总是包含以下内容：

libsodium最新的稳定版本
下一个版本的部分小补丁
关键的安全修复程序（当新软件包正在准备的时候）。

稳定分支中的代码还包括生成的文件，因此不需要使用自动化工具（libtool，autoconf，automake）来生成文件。

完整性检查

可以使用Minisign和以下的Ed25519密钥来验证配置文件：

RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3

或者使用GnuPG和以下的RSA密钥：

使用libsodium的应用程序

有一些应用程序使用Libsodium。发送一个pull请求将你的请求添加到列表中。

CRUD Messenger:A libsodium-php and MongoDB based single server messaging platform.
CurveLock:Message encryption for Windows.
Cyph:End-to-end encrypted, authenticated, and ephemeral chat with voice + video + file transfers.
Discord:All-in-one voice and text chat for gamers that’s free, secure, and works on both your desktop and phone.
Evernym Plenum:A byzantine fault tolerant protocol.
Fasted:A fast and secure tunnelling daemon.
FeCl:A secure message-passing server based on libsodium.
Flocksy:An anonymous file synchronisation tool.
Glorytun:A small, simple and very fast VPN.
Habitat:Habitat, by Chef, is automation that travels with the app.
Hat-Backup:A backend-agnostic snapshotting backup system.
KadNode:A small P2P DNS resolution daemon based on a Distributed Hash Table.
Kickpass:A stupid simple password manager.
Lawncipher:An embedded, encrypted, multi-purpose document store.
Lageant:Libsodium Authentication Agent.
Libsodium password hashing schemes for Dovecot:Dovecot plugin to support Scrypt and Argon2 for password hashing.
Libsodium for Universal Windows Platform:a C++ Windows Runtime Component for UWP applications.
Lumimaja: PasswordSafe with Argon2 KDF, data encrypted with ChaCha20Poly1305,and Yubikey support.
Magic Wormhole:Get things from one computer to another, safely.
MaidSfe:A new Secure way to access a world of existing apps where the security of your data is put above all else.
Minisign:A dead simple tool to sign files and verify signatures.
MLVPN:A multi-link VPN (ADSL/SDSL/xDSL/Network aggregator).
Molch:An implementation of the Axolotl ratchet.
NanoChat:A P2P, E2E encrypted and discoverable chat application on top of nanomsg library.
NTPsec:A security-hardened implementation of Network Time Protocol Version 4.
Open Reputation:An open source decentralized platform that maps identity and reputation onto the Internet-of-things.
OpenBazaar:A free market for all. No fees, no restrictions.
PAVE:The Password Manager. Easy password sharing for teams. No cloud.
PCP:Pretty Curved Privacy (pcp1) is a commandline utility which can be used to encrypt files.
Pbox:A CLI password manager.
Petmail:A secure communication and file-sharing system.
PipeSocks:A pipe-like SOCKS5 tunnel system.
PowerDNS:PowerDNS has been designed to serve both the needs of small installations by being easy to setup, as well as for serving very large query volumes on large numbers of domains. Additionally, PowerDNS offers very high domain resolution performance.
QtCrypt:Lightweight, portable application that encrypts files and directories using a symmetric-key algorithm.
Reop:Reasonable expectation of privacy.
Rubinius:Rubinius is a platform for building programming language technology.
SODA:The SODA project aims to investigate the relationship between server components and server performance.
SaltStack:SaltStack software orchestrates the build and ongoing management of any modern infrastructure.
Sandstorm:An open source operating system for personal and private clouds.
ShadowSocks:A secure socks5 proxy, designed to protect your Internet traffic.
Simple DnsCrypt:A simple management tool for dnscrypt-proxy.
Splonebox:An open source network assessment tool with focus on modularity.
Stellar:An open platform for building financial products that connect people everywhere.
Tbak:Encrypted, compressed, distributed backups.
Telehash:An embeddable private network stack for mobile, web, and devices.
Tinfoil Chat NaCI:TFC-NaCl is a high assurance encryption plugin for the Pidgin IM client.
Tox:A new kind of instant messenging.
Ultrapowa Clash Server:UCS is a server emulator for the famous game Clash of Clans.
VOLTTRON:VOLTTRON is an innovative distributed control and sensing software platform. Its source code has been released, making it possible for researchers and others to use this tool to build applications for more efficiently managing energy use among appliances and devices, including heating, ventilation and air conditioning (HVAC) systems, lighting, electric vehicles and others.
VPNCloud:A Peer-to-Peer VPN.
Wire:Modern, private communications. Crystal clear voice, video and group chats. No advertising. Your data, always encrypted.
Zcash:Zcash is a decentralized and open source cryptocurrency that aims to set a new standard for privacy through the use of groundbreaking cryptography.

使用libsodium的库

有一些库和框架使用Libsodium。发送一个pull请求将你的请求添加到列表中。

Aiso Sodium Socket:A header-only C++14 library implementing custom transport encryption using libsodium and Asio's stackless coroutines.
Blobcrypt:Authenticated encryption for streams and arbitrary large files.
Cordova MInisodium:A minimal sodium plugin for Cordova - for iOS and Android.
EdCert:A Rust crate to sign and verify content using Ed25519.
Halite:High-level cryptography interface for PHP.
Libsaxolotl:An Axolotol implementation in C using libsodium.
Neuropil:An IoT secure messaging library with end-to-end encryption written in C and using libsodium.
Libsodium-Laravel:Laravel integration.
Libsodium-UE4:An easy to use cryptography plugin for Unreal Engine 4 based on libsodium.
LibSQRL:SQRL authentication library.
Libyojimbo:A library for creating secure client/server network protocols over UDP.
MEGA SDK:SDK by mega.nz, a secure cloud storage provider that protects your data,thanks to end-to-end encryption.
Macaroons:Macaroons are flexible authorization credentials that support decentralized delegation, attenuation, and verification.
Minisign-net:.NET library to handle and create minisign signatures.
NaclKeys:Library to generate libsodium-net compatible KeyPair`s.
OAuthSDK:OAuth 1 and OAuth 2 framework in Swift for iOS.
Posh-Sodium:A powershell module.
Pull-box-stream:One way streaming encryption for Javascript.
Smart Encryption:Stream encryption & decryption with libsodium and protobuf for .NET.
Stream Cryptor:Secure by default encryption for .NET.
The Update Framework:A plug-and-play library for securing a software updater.
ZeroMQ:Connect your code in any language, on any platform.

使用libsodium的企业

有一些企业可能在非开源的产品中使用Libsodium。发送一个pull请求将你的请求添加到列表中。

其他语言的绑定

.NET:libsodium-net
.NET:nsec
Ada:libsodium-ada
C++:sodiumpp
C++:tears
Clojure:caesium
Clojure:naclj
Common LISP:cl-sodium
D:Chloride
D:Shaker
D:Sodium
Delphi/FreePascal:Delphi/FreePascal
Dylan:libsodium-dylan
Elixir:Savory
Erlang:ENaCl
Erlang:Erlang-NaCl
Erlang:Erlang-Libsodium
Erlang:Salt
Fortran:Fortium
Go:GoSodium
Go:libsodium-go
Go:Natrium
Go:Sodium
Guile:Guile-NaCl
Haskell:haskell-libsodium
Haskell:Saltine
HaXe:haxe_libsodium
Idris:Idris-Sodium
Idris: Sodium-Idris
Java (Android):Libstodium
Java (Android):Robosodium
Java (Android):Libsodium-JNI
Java:jsodium
Java:Kalium
Java:sodium-jni
JavaScript (compiled to pure JavaScript):libsodium.js
JavaScript(compiled to pure JavaScript):js-nacl
JavaScript (libsodium.js wrapper):Natrium
JavaScript (libsodium.js wrapper for browsers):Natrium Browser
JavaScript (NodeJS):node-sodium
JavaScript (NodeJS):sodium-native
Julia:Sodium.jl
Lisp (CFFI):foreign-sodium
Lua:lua-sodium
MRuby:mruby-libsodium
Nim:Libsodium.nim
Nim:Sodium.nim
OCaml:ocaml-sodium
Objective-C:NAChloride
Objective-C:SodiumObjc
PHP:PHP-Sodium
PHP:libsodium-php
Perl:Crypt-Sodium
Perl:Crypt::Nacl ::Sodium
Pharo/Squeak:Crypto-NaCl
Pony:Pony-Sodium
Python:Csodium
Python:LibNaCl
Python:PyNaCl
Python:PySodium
Q/KDB:Qsalt
R:Sodium
Racket:Natrium
Racket:part of CRESTaceans
Ruby:RbNaCl
Ruby:Sodium
Rust:rust_sodium
Rust:Sodium Oxide
Rust:libsodium-sys
Swift:NaOH
Swift:Swift-Sodium

用法

#include <sodium.h>
int main(void)
{
    if (sodium_init() == -1) {
        return 1;
    }
    ...
}

sodium.h是唯一需要被包含的头文件。

在Linux系统中，使用-lsodium来链接sodium库，在可用系统上使用pgk-config可以获得正确的编译器/链接器标识。

CFLAGS=$(pkg-config --cflags libsodium)
LDFLAGS=$(pkg-config --libs libsodium)

对于静态链接，Visual Studio的用户应该定义SODIUM_STATIC=1和SODIUM_EXPORT=。而在其他的平台上这不是必须的。

sodium_init()初始化库并且应该在任何由Sodium提供的函数前被调用。这个函数可以被调用不止一次，并且可以被从版本1.0.11开始的多线程同时调用。

在这个函数返回后，有Sodium提供的其他所有的函数都将是线程安全的。

sodium_init()不进行任何的内存分配。但是，在Unix系统中，它将打开/dev/urandom并且保持描述符打开，这样设备在一个chroot()调用后仍保持可访问。对sodium_init()的多次调用不会导致额外的描述符被打开。

sodium_init()成功则返回0，失败返回-1，当库已经被初始化则返回1。

帮助

常量时间内的差异性测试

int sodium_memcmp(const void * const b1_, const void * const b2_, size_t len);

当一个比较涉及私密数据（例如：密钥，认证标签）的时候，使用一个常量时间比较函数来减轻侧信道攻击是至关重要的。

sodium_memcmp()函数可以用于此目的。

当b1_指向的len字节与b2_指向的len字节相匹配的时候，该函数返回0，否则返回-1。

注意：sodium_memcmp()不是一个字典比较器，它并不是memcmp()的一个通用替代品。

十六进制编码/解码

char *sodium_bin2hex(char * const hex, const size_t hex_maxlen,
                   const unsigned char * const bin, const size_t bin_len);

sodium_bin2hex()函数将bin中存储的bin_len字节转换成十六进制字符串。

字符串存储在hex并且包含了一个空字节(\0)终止符。

hex_maxlen是从十六制开始允许写入该函数的最大字节数。它应该至少有bin_len * 2 + 1。

该函数成功返回hex，溢出返回NULL。它在给定大小的常量时间内进行评估。

int sodium_hex2bin(unsigned char * const bin, const size_t bin_maxlen,
                   const char * const hex, const size_t hex_len,
                   const char * const ignore, size_t * const bin_len,
                   const char ** const hex_end);

sodium_hex2bin()函数解析十六进制字符串hex并将其转换为字节序列。

hex不必空终止，因为要解析的字符数是通过hex_len参数提供的。

ignore是一串要跳过的字符。例如，字符串": "允许列和空格出现在十六进制字符串的任何位置。这些字符将被忽略。因此，"69:FC"，"69 FC"，"69 : FC" 和 "69FC"将被有效输入并产生相同的输出。

ignore可以被设置为NULL来禁止任何非十六进制字符。

bin_maxlen 是要放入bin的最大的字节数。

当一个非十六进制，不可忽略的字符被找到或者当bin_maxlen字节已被写入时，解析器就停止。

如果需要多于bin_maxlen字节来存储解析字符串，该函数将返回-1。它成功时返回0，并将hex_end(如果不为NULL)设置为指向最后一个解析字符后的字符指针。

在常量时间内，对给定的长度和格式进行评估。

递增大数

void sodium_increment(unsigned char *n, const size_t nlen);

sodium_increment()函数将指针指向任意长度的无符号数字，并将其递增。

它以常量时间运行给定的长度，并将数字视为小端格式进行编码。

sodium_increment()可以用于在常量时间内递增瞬时值。

这个函数在libsodium 1.0.4中引入。

添加大数

void sodium_add(unsigned char *a, const unsigned char *b, const size_t len);

sodium_ad()函数接收两个指向无符号数字的指针，将这些指针以小端的格式进行编码，a和b的大小都是len字节。

它在给定的长度上以常量时间计算(a + b) mod 2^(8*len)，并用结果覆盖它。

这个函数在libsodium 1.0.7被引入。

比较大数

int sodium_compare(const void * const b1_, const void * const b2_, size_t len);

给定b1_和b2_，以小端格式编码两个len字节数字，该函数返回：
- -1 如果b1_ 比b2_小
- 0 如果b1_ 等于b2_
- 1 如果b1_ 比b2_大

比较在给定长度的常量时间内完成。

该函数可以与瞬时值一起使用，以防止重放攻击。

这个函数在libsodium 1.0.6被引入。

全零测试

int sodium_is_zero(const unsigned char *n, const size_t nlen);

如果n指向nlen个字节的向量只包含零，此函数返回1。如果找到非零的比特，就返回0.

其执行时间对于给定长度是恒定的。

这个函数在libsodium 1.0.7中被引入。

安全内存分配

清空内存

void sodium_memzero(void * const pnt, const size_t len);

使用结束后，敏感数据应该被覆盖，但是memset()和手写的代码会被优化编译器或链接器悄悄地删除。

即使代码会被优化，sodium_memzero()这个函数尝试从pnt开始有效地清空len个字节。

锁定内存

int sodium_mlock(void * const addr, const size_t len);

sodium_mlock()这个函数锁定从addr开始的至少len个字节的内存。这将有助于避免将敏感数据交换到硬盘上。

另外，建议在处理敏感数据的机器上完全禁用交换分区，或者作为第二选择，使用加密的交换分区。

出于类似的原因，在Unix系统上，当您在开发环境之外运行密码相关的代码时，您应该禁用核心转储。这可以通过使用内置的shell（例如ulimit）或者使用setrlimit(RLIMIT_CORE, &(struct rlimit) {0, 0})。在能够实现此功能的操作系统上，还应禁用内核崩溃转储。

sodium_mlock()包装了mlock()和VirtualLock()。注意：许多系统对进程可能锁定的内存量进行限制。注意在必要时应提高这些限制（例如Unix ulimits）。当任何限制达到的时候，sodium_lock()将返回-1。

int sodium_munlock(void * const addr, const size_t len);

在锁定的内存不再被使用之后，应该调用sodium_munlock()函数。在将页面重新标记为可交换之前，它会从addr开始清空len个字节。因此不需要在使用sodium_munlock()函数之前调用sodium_memzero()函数。

在支持它的系统上，sodium_mlock()也包装了madvise()，并建议内核不要将锁定的内存包含在核心转储中。 sodium_unlock()也会撤消这个额外的保护。

保护堆分配

Sodium提供用于存储敏感数据的堆分配函数，这些函数不是一般的堆分配函数。特别地，它们比malloc()慢，并且需要3或4个额外的虚拟内存页。

在使用任何保护堆分配函数之前，必须先调用sodium_init()函数。

void *sodium_malloc(size_t size);

sodium_malloc()函数返回一个指针，这个指针可以访问大小连续的内存字节。

分配的区域放置在页边界的末尾，紧随其后的是保护页。因此，访问该区域结尾处的内存将立即终止应用程序。

一个canary也放置在返回的指针之前。尝试使用sodium_free()释放分配的区域时，如果检测到这个canary的修改，会导致应用程序立即终止。

在这个canary之前放置一个附加的保护页面，以便当读取到超过无关区域的末尾时，敏感数据不太可能被访问。

分配的区域填充0xd0个字节，以帮助捕获由于初始化数据引起的错误。

此外，在该区域调用了sodium_mlock()以帮助避免将其交换到磁盘。在支持MAP_NOCORE或MADV_DONTDUMP的操作系统上，以这种方式分配的内存也不会成为核心转储的一部分。

如果分配的大小不是所需对齐字节的倍数，返回的地址将不会对齐。

因此，为了确保正确地对齐，sodium_malloc()函数不应该和包装或可变长度的结构一起使用，除非给与sodium_malloc()的大小被舍入。

libsodium使用的所有结构都可以安全地使用sodium_malloc()进行分配，唯一需要额外注意的是crypto_generichash_state，其大小需要舍入到64字节的倍数。

分配0个字节是一个有效的操作，并返回一个可以成功传递给sodium_free()的指针。

void *sodium_allocarray(size_t count, size_t size);

sodium_allocarray()函数返回一个指针，这个指针可以访问size字节大小的count对象。

它提供与sodium_malloc()相同的保证，当count * size超过SIZE_MAX时可以防止算术溢出。

void sodium_free(void *ptr);

sodium_free()函数解锁并释放使用sodium_malloc()或sodium_allocarray()分配的内存。

在此之前，检查canary以检测可能的缓冲区下溢，并在需要时终止该过程。

在释放之前，sodium_free()也会用零填充内存区域。
即使您以前使用sodium_mprotect_readonly()保护过该区域，也可以调用此函数; 保护将根据需要自动更改。

ptr可以为NULL，在这种情况下不执行任何操作。

int sodium_mprotect_noaccess(void *ptr);

sodium_mprotect_noaccess()函数使得使用sodium_malloc()或sodium_allocarray()分配的区域无法访问。它不能被读取或写入，但数据被保留。

此功能可用于使机密数据无法访问，除了特定操作实际需要之外。

int sodium_mprotect_readonly(void *ptr);

sodium_mprotect_readonly()函数将使用sodium_malloc()或sodium_allocarray()分配的区域标记为只读。

尝试修改数据将导致进程终止。

int sodium_mprotect_readwrite(void *ptr);

在使用sodium_mprotect_readonly()或sodium_mprotect_noaccess()将区域置于保护的状态之后，sodium_mprotect_readwrite()函数将使用sodium_malloc()或sodium_allocarray()分配的区域标记为可读写。

生成随机数据

这个函数库提供了一组函数来生成不可预知的数据，这适用于创建密钥。
- 在Windows系统上，使用RtlGenRandom()函数
- 在OpenBSD和Bitrig上，使用arc4random()函数
- 在较新的Linux内核中，使用getrandom系统调用（从Sodium 1.0.3版本开始）
- 在其它类Linux系统上，使用/dev/urandom设备
- 如果上述选项都不能被安全地使用，我们也提供自定义实现。

用法

uint32_t randombytes_random(void);

这个randombytes_random()函数返回0到0xffffffff之间（闭区间）的一个不可预测的值。

uint32_t randombytes_uniform(const uint32_t upper_bound);

randombytes_uniform()函数返回0和upper_bound之间（开区间）的一个不可预测的值。与randombytes_random() % upper_bound不同，即使upper_bound不是2的幂次方，它也尽可能保证可能的输出值是均匀分布的。

void randombytes_buf(void * const buf, const size_t size);

randombytes_buf()函数用不可预测的字节序列填充从buf开始的size个字节。

int randombytes_close(void);

这个函数释放了伪随机数生成器使用的全局资源。更具体地说，当/dev/urandom设备在被使用时，它会关闭描述符。显然调用这个函数是几乎不需要的。

void randombytes_stir(void);

如果它支持这种操作的话，randombytes_stir()函数会重新设置伪随机生成器的种子。即使在调用了fork()后，调用这个函数也不需要使用默认的生成器，除非您使用了randombytes_close()函数来关闭/dev/urandom的描述符。

如果您使用了非默认实现（请参阅randombytes_set_implementation() 函数），
在调用了fork()后，必须再调用randombytes_stir()函数。

注意

如果这在VM中的一个应用程序中使用，并且VM恢复了快照，那么上述的功能可能会产生相同的输出。

密钥加密

（这部分的文档正在编写中。欢迎贡献一个很好的关于密钥加密的介绍！）

密钥认证加密

示例

#define MESSAGE ((const unsigned char *) "test")
#define MESSAGE_LEN 4
#define CIPHERTEXT_LEN (crypto_secretbox_MACBYTES + MESSAGE_LEN)
unsigned char nonce[crypto_secretbox_NONCEBYTES];
unsigned char key[crypto_secretbox_KEYBYTES];
unsigned char ciphertext[CIPHERTEXT_LEN];
randombytes_buf(nonce, sizeof nonce);
randombytes_buf(key, sizeof key);
crypto_secretbox_easy(ciphertext, MESSAGE, MESSAGE_LEN, nonce, key);
unsigned char decrypted[MESSAGE_LEN];
if (crypto_secretbox_open_easy(decrypted, ciphertext, CIPHERTEXT_LEN, nonce, key) != 0
) {
    /* message forged! */
}

目标

我们希望这个操作满足以下两个条件：
- 使用密钥和瞬时值机密消息，以保持消息的机密性。
- 计算一个身份验证标记。这个标记用于确保消息在解密之前不会被篡改。

一个密钥既用于加密/签名，也用于验证/解密消息。因此，保密这个密钥至关重要。

这个瞬时值并不一定要保密，但它永远不能用相同的密钥重复使用。生成瞬时值最简单的方法是使用randombytes_buf()函数。

组合模式

在组合模式中，认证标签和加密消息被一同存储。这通常就是你想要的。

int crypto_secretbox_easy(unsigned char *c, const unsigned char *m,
                          unsigned long long mlen, const unsigned char *n,
                          const unsigned char *k);

crypto_secretbox_easy()函数使用一个密钥k和一个瞬时值n来加密一个长度为mlen字节的消息m。

k应该是crypto_secretbox_KEYBYTES字节，而n应该是crypto_secretbox_NONCEBYTES字节。

c应该是至少crypto_secretbox_MACBYTES + mlen字节长。

此函数在c中写入长度为crypto_secretbox_MACBYTES字节的认证标签，紧接着的是长度与明文长度mlen相同的加密消息。

c和m 可以重叠，从而使得就地加密成为可能。但是，不要忘记crypto_secretbox_MACBYTES 额外的字节需要添加标签。

int crypto_secretbox_open_easy(unsigned char *m, const unsigned char *c,
                               unsigned long long clen, const unsigned char *n,
                               const unsigned char *k);

crypto_secretbox_open_easy() 函数验证和解密一个由crypto_secretbox_easy()生成的密文。

c是一个由crypto_secretbox_easy()生成的指向认证标签 + 加密消息组合的指针。clen是这个认证标签 + 加密消息组合的长度。换句话说，clen是由crypto_secretbox_easy()写入的字节数，这是crypto_secretbox_MACBYTES + 消息的长度。

瞬时值n和密钥k必须匹配用于加密和认证消息。

如果验证失败，该函数返回-1，成功则返回0.成功后，解密消息被存储在m中。

m和c可以重叠，是就地解密成为可能。

分离模式

一些应用可能需要在不同的位置存储认证标签和加密消息。

对于这种具体的例子，可以使用上述函数的“分离”变体。

int crypto_secretbox_detached(unsigned char *c, unsigned char *mac,
                              const unsigned char *m,
                              unsigned long long mlen,
                              const unsigned char *n,
                              const unsigned char *k);

这个函数使用密钥k和瞬时值n来加密mlen长的消息m，并且将其加密的消息放入c中。正确的mlen字节将被放入c，这个函数不会添加认证标签。标签大小为crypto_secretbox_MACBYTES 字节将被放入mac。

int crypto_secretbox_open_detached(unsigned char *m,
                                   const unsigned char *c,
                                   const unsigned char *mac,
                                  unsigned long long clen,
                                   const unsigned char *n,
                                   const unsigned char *k);

crypto_secretbox_open_detached()函数验证解密一个长度为clen的加密消息c。clen不包括标签，所以这个长度与明文的长度相同。

通过给定的瞬时值n和密钥k，验证mac是该密文的有效认证标签之后，明文被放入m中。

如果验证失败，这个函数返回-1，成功则返回0。

常量

crypto_secretbox_KEYBYTES
crypto_secretbox_MACBYTES
crypto_secretbox_NONCEBYTES

算法细节

加密：XSalsa20 流密码
认证：Poly1305 MAC

说明

原始的NaCl crypto_secretbox API也是支持的，虽然不推荐使用。

crypto_secretbox()在消息之前接收32个字节的指针，并将密文存储在目标指针后的16个字节，前16个字节被零覆盖。crypto_secretbox_open()在密文接收16字节的指针，将消息存储在目标指针后的32个字节。前32个字节被零覆盖。

_easy 和 _detached APIs 更快，并且不需要填充、复制或者复杂的指针运算，可以提高可用性。

密钥认证

示例

#define MESSAGE (const unsigned char *) "test"
#define MESSAGE_LEN 4
unsigned char key[crypto_auth_KEYBYTES];
unsigned char mac[crypto_auth_BYTES];
randombytes_buf(key, sizeof key);
crypto_auth(mac, MESSAGE, MESSAGE_LEN, key);
if (crypto_auth_verify(mac, MESSAGE, MESSAGE_LEN, key) != 0) {
/* message forged! */
}

目的

该操作为消息和密钥计算了认证标签，并提供一种验证给定标签对于给定消息和密钥是否有效的一种方式。

该函数计算了标签的有效性：相同的（消息，密钥）元组将始终产生相同的输出。

然而，即使消息是公开的，为了能够计算出一个有效的标签，需要知道密钥。因此，密钥应该保密，但标签可以公开。

一个典型的用例是：
- A准备了一条消息，添加一个认证的标签，将它发送给B
- A不存储这条消息
- 稍后，B将消息和认证标签发送给A
- A使用认证标签来确认它是否创建了这条消息

这个操作不加密消息。它只计算和验证认证标签。

用法

int crypto_auth(unsigned char *out, const unsigned char *in,
                unsigned long long inlen, const unsigned char *k);

crypto_auth()函数为消息in计算了一个标签，标签的长度为inlen个字节，密钥为k。k的长度应该是crypto_auth_KEYBYTES个字节。这个函数将标签放入out中。这个标签的长度为crypto_auth_BYTES个字节。

int crypto_auth_verify(const unsigned char *h, const unsigned char *in,
                    unsigned long long inlen, const unsigned char *k);

对于长度为inlen个字节的消息in和密钥k来说，crypto_auth_verify()函数验证存储在h中的标签是一个合法的标签。
如果验证失败，函数返回-1，否则返回0。

常量

crypto_auth_BYTES
crypto_auth_KEYBYTES

算法细节

HMAC-SHA512256

带有附加数据的认证加密

我们希望这个操作满足以下两个条件：
- 使用一个密钥和一个瞬时值来加密消息以保证消息的机密性。
- 计算一个认证标签。这个标签用来确保消息和可选的非机密（未加密）数据尚未被篡改。

附加数据的一个典型用例是存储关于消息的协议特定的元数据，比如消息的长度和编码。

支持的结构

Libsodium支持两种流行的结构：AES256-GCM和ChaCha20-Poly1305。

AES256-GCM

目前这种结构的实现是硬件加速的，它需要英特尔SSSE3扩展，以及aesni和pclmul指令。

英特尔Westmere处理器（2010年推出）以及更新的处理器满足这个要求。

没有计划支持AES-GCM的非硬件加速实现。

如果不考虑可移植性，AES256-GCM是最快的选择。

ChaCha20-Poly1305

虽然AES在专用硬件上的速度非常快，但在缺乏此类硬件的平台上的性能要低得多。另一个问题是，许多AES的软件实现都容易受到缓存-碰撞时间攻击的影响。

ChaCha20在软件上的实现上比AES快得多，在缺乏专用AES硬件的平台上，ChaCha20的速度是AES速度的三倍。ChaCha20对定时攻击也不敏感。

Poly1305是一个速度很快的消息认证码。

ChaCha20流密码与Poly1305认证器的组合于2014年1月提出，它是一种更快速的替代方法，用来替代研究良好的Salsa20-Poly1305结构。

不久后，ChaCha20-Poly1305在主流操作系统、Web浏览器以及加密库中得以实现。它最终于2015年5月成为IETF的官方标准。

在所有支持的体系结构中，Libsodium的ChaCha20-Poly1305实现是可移植的，并且是大多数应用程序的推荐选择。

ChaCha20-Poly1305

使用ChaCha20-Poly1305进行带有附加数据的认证加密

目的

我们希望这个操作满足以下两个条件：
- 使用密钥和瞬时值加密消息来保证其机密性
- 计算一个认证标签。该标签用于确保消息和可选且非机密（非加密）数据不能被篡改。

附加数据的一个典型的用例就是存储有关消息的协议特定元数据，例如其长度和编码。

选择的构造使用encrypt-then-MAC，并且在验证之前，不会被解密甚至部分解密。

变体

Libsodium 实行两个版本的ChaCha20-Poly1305构造：
- 原始结构可以用相同的密钥安全地加密最多2^64条消息，对消息的大小没有任何实际限制（最多2^70字节）。
- IETF变体会有些慢。它可以安全地加密一个实际上无限数量的消息（2^96），但是单个消息不能超过 64*(1^32)-64 字节（大约256GB）。

两者都能与其他的密码库协作，共享相同的安全属性，可以通过类似的API访问。
crypto_aead_chacha20poly1305_*()函数集实现原始构造，而crypto_aead_chacha20poly1305_ietf_*()函数实现IETF版本。这些常数除了瞬时值的大小，都是相同的。

原始的ChaCha20-Poly1305结构

原始的ChaCha20-Poly1305结构可以使用相同的密钥安全地加密最多2^64条消息，对消息的大小没有任何实际的限制（最多2^70个字节）。

例子（组合模式）

#define MESSAGE (const unsigned char *) "test"
#define MESSAGE_LEN 4
#define ADDITIONAL_DATA (const unsigned char *) "123456"
#define ADDITIONAL_DATA_LEN 6
unsigned char nonce[crypto_aead_chacha20poly1305_NPUBBYTES];
unsigned char key[crypto_aead_chacha20poly1305_KEYBYTES];
unsigned char ciphertext[MESSAGE_LEN + crypto_aead_chacha20poly1305_ABYTES];
unsigned long long ciphertext_len;
randombytes_buf(key, sizeof key);
randombytes_buf(nonce, sizeof nonce);
crypto_aead_chacha20poly1305_encrypt(ciphertext, &ciphertext_len,
                                     MESSAGE, MESSAGE_LEN,
                                     ADDITIONAL_DATA, ADDITIONAL_DATA_LEN,
                                     NULL, nonce, key);
unsigned char decrypted[MESSAGE_LEN];
unsigned long long decrypted_len;
if (crypto_aead_chacha20poly1305_decrypt(decrypted, &decrypted_len,
                                         NULL,
                                         ciphertext, ciphertext_len,
                                         ADDITIONAL_DATA,
                                         ADDITIONAL_DATA_LEN,
                                        nonce, key) != 0) {
/* message forged! */
}

组合模式

在组合模式下，认证标签和加密的消息一同存储。这通常就是你想要的。

int crypto_aead_chacha20poly1305_encrypt(unsigned char *c,
                                         unsigned long long *clen,
                                         const unsigned char *m,
                                         unsigned long long mlen,
                                         const unsigned char *ad,
                                        unsigned long long adlen,
                                        const unsigned char *nsec,
                                         const unsigned char *npub,
                                         const unsigned char *k);

crypto_aead_chacha20poly1305_encrypt() 函数使用一个密钥k（crypto_aead_chacha20poly1305_KEYBYTES字节）和公共瞬时值npub（crypto_aead_chacha20poly1305_NPUBBYTES字节）加密一个长度为mlen字节的消息m。

将加密消息和认证机密消息m与adlen字节长的非机密消息ad的标签一起放入c。

如果不需要附加数据，ad可以是一个NULL指针，alen等于0。

至多mlen + crypto_aead_chacha20poly1305_ABYTES字节放入c，并且实际的字节数存储在clen，除非clen是一个NULL指针。

在这个特定的结构中不使用nsec，而应该始终为NULL。

公共瞬时值npub永远不应该与相同的密钥一起使用。我们推荐使用randombytes_buf()函数来为第一条消息生成瞬时值，并使用相同的密钥为后续的消息增加瞬时值。

int crypto_aead_chacha20poly1305_decrypt(unsigned char *m,
                                         unsigned long long *mlen,
                                         unsigned char *nsec,
                                         const unsigned char *c,
                                         unsigned long long clen,
                                         const unsigned char *ad,
                                         unsigned long long adlen,
                                         const unsigned char *npub,
                                         const unsigned char *k);

crypto_aead_chacha20poly1305_decrypt()函数验证密文c（由crypto_aead_chacha20poly1305_encrypt() 生成）包含使用密钥k、公共瞬时值npub和附加数据ad（adlen 字节）生成的有效标签。

如果不需要附加数据，ad可以是一个NULL指针，alen等于0。

这个特定的结构不使用nsec，并且其应该始终为NULL。

当验证失败的时候这个函数返回-1。

如果验证成功，函数返回0。如果mlen不是一个NULL指针，将解密后的消息放入m，并且存储其实际的字节数到mlen中。

至多有clen - crypto_aead_chacha20poly1305_ABYTES字节将被放入m中。

分离模式

一些应用可能需要在不同的位置存储认证标签和加密消息。
对于这种具体的用例，可以使用上述函数的“分离”变体。

int crypto_aead_chacha20poly1305_encrypt_detached(unsigned char *c,
                                                  unsigned char *mac,
                                                  unsigned long long *maclen_p,
                                                  const unsigned char *m,
                                                  unsigned long long mlen,
                                                  const unsigned char *ad,
                                                  unsigned long long adlen,
                                                  const unsigned char *nsec,
                                                  const unsigned char *npub,
                                                  const unsigned char *k);

crypto_aead_chacha20poly1305_encrypt_detached()函数使用一个密钥k和一个瞬时值npub加密一个消息m。它将生成长度等于消息的密文放入c中。

它还计算一个标签，用于认证密文和长adlen的可选的附加数据ad。该标签将被放入mac，并且它的长度是crypto_aead_chacha20poly1305_ABYTES字节。

这个特定结构不使用nsec并且始终应该为NULL。

int crypto_aead_chacha20poly1305_decrypt_detached(unsigned char *m,
                                                  unsigned char *nsec,
                                                  const unsigned char *c,
                                                  unsigned long long clen,
                                                  const unsigned char *mac,
                                                  const unsigned char *ad,
                                                  unsigned long long adlen,
                                                  const unsigned char *npub,
                                                  const unsigned char *k);

crypto_aead_chacha20poly1305_decrypt_detached()函数验证认证标签mac对长度为clen字节的密文c、瞬时值npub和长度为adlen字节的可选附加数据ad是有效的。

如果标签无效，函数返回-1并且不进行下一步操作。

如果标签有效，密文被解密并且明文将放入m。长度等于密文的长度。

这个特定结构不使用nsec并且始终应该为NULL。

常量

crypto_aead_chacha20poly1305_KEYBYTES
crypto_aead_chacha20poly1305_NPUBBYTES
crypto_aead_chacha20poly1305_ABYTES

算法细节

加密: ChaCha20 流密码
认证: Poly1305 MAC

说明

为了防止瞬时值重用，如果一个密钥被重用了，建议增加之前的瞬时值，而不是为每条消息都生成一个随机的瞬时值。

为了防止瞬时值在C/S模型中被重用，要么在每个方向的通信中使用不同的密钥，要么确保在一个比特位在一个方向中被屏蔽，然后再另一个方向上设置。

API符合CAESAR竞赛提出的API。

直到CAESAR竞赛结束，一个高级别的crypto_aead_*() API才被定义。

参阅

基于TLS密码套件的ChaCha20 和 Poly1305 - 原始结构规范

The IETF ChaCha20-Poly1305 结构

ChaCha20-Poly1305 结构的IETF变体可以安全加密一个几乎无限数量的消息(2^96)，但单个消息不能超过 64*(1^32)-64 字节（大约256GB）。

举例（组合模式）

#define MESSAGE (const unsigned char *) "test"
#define MESSAGE_LEN 4
#define ADDITIONAL_DATA (const unsigned char *) "123456"
#define ADDITIONAL_DATA_LEN 6
unsigned char nonce[crypto_aead_chacha20poly1305_IETF_NPUBBYTES];
unsigned char key[crypto_aead_chacha20poly1305_IETF_KEYBYTES];
unsigned char ciphertext[MESSAGE_LEN + crypto_aead_chacha20poly1305_IETF_ABYTES];
unsigned long long ciphertext_len;
randombytes_buf(key, sizeof key);
randombytes_buf(nonce, sizeof nonce);
crypto_aead_chacha20poly1305_ietf_encrypt(ciphertext, &ciphertext_len,
                                          MESSAGE, MESSAGE_LEN,
                                          ADDITIONAL_DATA, ADDITIONAL_DATA_LEN,
                                          NULL, nonce, key);
unsigned char decrypted[MESSAGE_LEN];
unsigned long long decrypted_len;
if (crypto_aead_chacha20poly1305_ietf_decrypt(decrypted, &decrypted_len,
                                              NULL,
                                              ciphertext, ciphertext_len,
                                              ADDITIONAL_DATA,
                                              ADDITIONAL_DATA_LEN,
                                              nonce, key) != 0) {
/* message forged! */
}

组合模式

在组合模式的情况下，认证标签和加密的消息一起存储。这通常是你想要的。

int crypto_aead_chacha20poly1305_ietf_encrypt(unsigned char *c,
                                            unsigned long long *clen,
                                            const unsigned char *m,
                                            unsigned long long mlen,
                                            const unsigned char *ad,
                                            unsigned long long adlen,
                                            const unsigned char *nsec,
                                            const unsigned char *npub,
                                            const unsigned char *k);

crypto_aead_chacha20poly1305_ietf_encrypt()函数使用密钥k（crypto_aead_chacha20poly1305_IETF_KEYBYTES个字节长）和一个公共的瞬时值npub（crypto_aead_chacha20poly1305_IETF_NPUBBYTES个字节长）来加密mlen个字节长的消息m。

加密后的消息以及一个标签都放入c中，这个标签认证了机密消息m和adlen个字节长的非机密数据ad。

如果不需要附加的数据，ad可以是一个adlen为0的NULL指针。

最多mlen + crypto_aead_chacha20poly1305_IETF_ABYTES个字节被放入到c中，如果clen不是一个空指针，那么c确切的字节数存放在clen中。

在这个特定的结构中，nsec没有被使用，它的值应该始终为NULL。

公共的瞬时值npub永远不能和相同的密钥一起重复使用。建议使用randombytes_buf()函数来为第一条消息生成瞬时值，并使用相同的密钥为每个后续消息增加这个瞬时值。

int crypto_aead_chacha20poly1305_ietf_decrypt(unsigned char *m,
                                            unsigned long long *mlen,
                                            unsigned char *nsec,
                                            const unsigned char *c,
                                            unsigned long long clen,
                                            const unsigned char *ad,
                                            unsigned long long adlen,
                                            const unsigned char *npub,
                                            const unsigned char *k);

crypto_aead_chacha20poly1305_ietf_decrypt()函数使用一个密钥k、一个公共的瞬时值npub以及一个附加数据ad（adlen个字节长）来验证密文c（由crypto_aead_chacha20poly1305_ietf_encrypt()函数生成）包含一个有效的标签。

如果不需要附加的数据，ad可以是一个adlen为0的NULL指针。

在这个特定的结构中，nsec没有被使用，它的值应该始终为NULL。

当验证失败的时候函数返回-1。

当验证成功的时候，函数返回0，将解密后的数据放入m，如果clen不是一个空指针，那么m确切的字节数存放在clen中。

最多clen - crypto_aead_chacha20poly1305_IETF_ABYTES个字节被放入m。

分离模式

一些应用可能需要将认证标签和加密后的消息存储在不同的位置。

对于这种具体用例，可以使用上述函数的“分离”变体。

int crypto_aead_chacha20poly1305_ietf_encrypt_detached(unsigned char *c,
                                                    unsigned char *mac,
                                                    unsigned long long *maclen_p,
                                                    const unsigned char *m,
                                                    unsigned long long mlen,
                                                    const unsigned char *ad,
                                                    unsigned long long adlen,
                                                    const unsigned char *nsec,
                                                    const unsigned char *npub,
                                                    const unsigned char *k);

crypto_aead_chacha20poly1305_ietf_encrypt_detached()函数使用密钥k和瞬时值npub来加密消息。它将得到的密文放入c中，其中密文的长度和消息的长度相等。

它还计算标签，这个标签用来认证密文以及可选的adlen长度的附加数据ad。这个标签放在mac中，标签的长度为crypto_aead_chacha20poly1305_IETF_ABYTES个字节。

在这个特定的结构中，nsec没有被使用，它的值应该始终为NULL。

int crypto_aead_chacha20poly1305_ietf_decrypt_detached(unsigned char *m,
                                                     unsigned char *nsec,
                                                     const unsigned char *c,
                                                     unsigned long long clen,
                                                     const unsigned char *mac,
                                                     const unsigned char *ad,
                                                     unsigned long long adlen,
                                                     const unsigned char *npub,
                                                     const unsigned char *k);

crypto_aead_chacha20poly1305_ietf_decrypt_detached()函数验证了认证标签mac对于clen个字节长的密文c、密钥k、瞬时值npub以及可选的adlen个字节长的附加数据ad来说是有效的。

如果标签无效，函数返回-1并且不再进行任何进一步的处理。

如果标签有效，密文被解密并且明文被放入m中。明文的长度与密文的长度相等。

在这个特定的结构中，nsec没有被使用，它的值应该始终为NULL。

常量

crypto_aead_chacha20poly1305_IETF_ABYTES

从Sodium 1.0.9开始：
- crypto_aead_chacha20poly1305_IETF_KEYBYTES
- crypto_aead_chacha20poly1305_IETF_NPUBBYTES

在早期的版本中，使用crypto_aead_chacha20poly1305_KEYBYTES和crypto_aead_chacha20poly1305_NPUBBYTES。在原始变体和IETF变体之间，瞬时值的大小是唯一一个不同的常量。

算法细节

加密：ChaCha20流加密
认证：Poly1305 MAC

说明

为了防止瞬时值重用，如果一个密钥被重用了，建议增加之前的瞬时值，而不是为每条消息都生成一个随机的瞬时值。

该API符合CAESAR竞赛中提出的API。

直到CAESAR竞赛结束时，一个高水平的API crypto_aead_*()才有意被定义。

参阅

用于IETF协议的ChaCha20和Poly1305 - IETF变体的规范

AES256-GCM

使用AES-GCM进行带有附加数据的认证加密

示例（组合模式）

#include <sodium.h>
#define MESSAGE (const unsigned char *) "test"
#define MESSAGE_LEN 4
#define ADDITIONAL_DATA (const unsigned char *) "123456"
#define ADDITIONAL_DATA_LEN 6
unsigned char nonce[crypto_aead_aes256gcm_NPUBBYTES];
unsigned char key[crypto_aead_aes256gcm_KEYBYTES];
unsigned char ciphertext[MESSAGE_LEN + crypto_aead_aes256gcm_ABYTES];
unsigned long long ciphertext_len;
sodium_init();
if (crypto_aead_aes256gcm_is_available() == 0) {
    abort(); /* Not available on this CPU */
}
randombytes_buf(key, sizeof key);
randombytes_buf(nonce, sizeof nonce);
crypto_aead_aes256gcm_encrypt(ciphertext, &ciphertext_len,
                              MESSAGE, MESSAGE_LEN,
                              ADDITIONAL_DATA, ADDITIONAL_DATA_LEN,
                              NULL, nonce, key);
unsigned char decrypted[MESSAGE_LEN];
unsigned long long decrypted_len;
if (ciphertext_len < crypto_aead_aes256gcm_ABYTES ||
    crypto_aead_aes256gcm_decrypt(decrypted, &decrypted_len,
                                  NULL,
                                  ciphertext, ciphertext_len,
                                  ADDITIONAL_DATA,
                                  ADDITIONAL_DATA_LEN,
                                  nonce, key) != 0) {
                                  /* message forged! */
}

目的

附加数据的一个典型用例是存储关于消息的协议特定的元数据，比如消息的长度和编码。

它也能被用作带有空消息的MAC。

在消息被验证之前，即使是部分解密也永远不会被执行。

当CPU支持时，AES-GCM是该库中最快的AEAD算法。

局限性

目前这种结构的实现是硬件加速的，它需要英特尔SSSE3扩展，以及aesni和pclmul指令。

英特尔Westmere处理器（2010年推出）以及更新的处理器满足这个要求。

没有计划支持AES-GCM的非硬件加速实现。如果考虑移植性，请改用ChaCha20-Poly1305算法。

在使用以下的函数之前，先可以通过以下方式检查AES的硬件支持：

int crypto_aead_aes256gcm_is_available(void);

如果当前的CPU支持AES256-GCM实现，函数返回1，否则函数返回0。

在调用这个函数前，必须使用sodium_init()初始化库。

组合模式

在组合模式的情况下，认证标签和加密的消息一起存储。这通常是你想要的。

int crypto_aead_aes256gcm_encrypt(unsigned char *c,
                                unsigned long long *clen,
                                const unsigned char *m,
                                unsigned long long mlen,
                                const unsigned char *ad,
                                unsigned long long adlen,
                                const unsigned char *nsec,
                                const unsigned char *npub,
                                const unsigned char *k);

crypto_aead_aes256gcm_encrypt()函数使用密钥k（crypto_aead_aes256gcm_KEYBYTES个字节长）和一个公共的瞬时值npub（crypto_aead_aes256gcm_NPUBBYTES个字节长）来加密mlen个字节长的消息m。

加密后的消息以及一个标签都放入c中，这个标签认证了机密消息m和adlen个字节长的非机密数据ad。

如果不需要附加数据，ad可以是一个adlen为0的NULL指针。

最多mlen + crypto_aead_aes256gcm_ABYTES个字节被放入到c中，如果clen不是一个空指针，那么c确切的字节数存放在clen中。

在这个特定的结构中，nsec没有被使用，它的值应该始终为NULL。

这个函数总是返回0。

int crypto_aead_aes256gcm_decrypt(unsigned char *m,
                                  unsigned long long *mlen_p,
                                  unsigned char *nsec,
                                  const unsigned char *c,
                                  unsigned long long clen,
                                  const unsigned char *ad,
                                  unsigned long long adlen,
                                  const unsigned char *npub,
                                  const unsigned char *k);

crypto_aead_aes256gcm_decrypt()函数使用一个密钥k、一个公共的瞬时值npub以及一个附加数据ad（adlen个字节长）来验证密文c（由crypto_aead_aes256gcm_encrypt()函数生成）包含一个有效的标签。clen是认证者的密文字节长度，因此它必须至少为 aead_aes256gcm_ABYTES。

如果不需要附加数据，ad可以是一个NULL指针。

这个特定结构不使用nsec，并且应该始终为NULL。

如果验证失败函数返回-1。

如果验证成功，函数返回0。将解密消息放入m，如果mlen表示一个NULL指针，则将实际字节数存储到mlen。

最多有clen - crypto_aead_aes256gcm_ABYTES字节被放入m。

分离模式

一些应用可能需要在不同的位置存储认证标签以及加密消息。

对于这种具体用例，可以使用上述函数的“分离”变体。

int crypto_aead_aes256gcm_encrypt_detached(unsigned char *c,
                                           unsigned char *mac,
                                           unsigned long long *maclen_p,
                                           const unsigned char *m,
                                           unsigned long long mlen,
                                           const unsigned char *ad,
                                           unsigned long long adlen,
                                           const unsigned char *nsec,
                                           const unsigned char *npub,
                                           const unsigned char *k);

crypto_aead_aes256gcm_encrypt_detached()函数使用一个密钥k（crypto_aead_aes256gcm_KEYBYTES 字节）和一个公共瞬时值npub（crypto_aead_aes256gcm_NPUBBYTES字节）加密一个长度为mlen字节的消息m。

加密消息放入c。认证机密消息m和adlen字节的非机密数据ad的标签被放入mac。

如果不需要附加数据，ad也可以是NULL指针。

将crypto_aead_aes256gcm_ABYTES字节放入mac，验证所需的实际字节数存储到maclen_p，除非maclen_p是NULL指针。

这个特定结构不使用nsec，并且应该始终为NULL。

函数总是返回0。

int crypto_aead_aes256gcm_decrypt_detached(unsigned char *m,
                                           unsigned char *nsec,
                                           const unsigned char *c,
                                           unsigned long long clen,
                                           const unsigned char *mac,
                                           const unsigned char *ad,
                                           unsigned long long adlen,
                                           const unsigned char *npub,
                                           const unsigned char *k);

函数crypto_aead_aes256gcm_decrypt_detached()使用密钥k、公共瞬时值npub和附加数据ad（adlen字节）来验证标签mac对于密文c是否有效。

clen是以字节为单位的密文长度。

如果不需要附加数据，ad可以是NULL指针。

这个特定结构不使用nsec，并且应该始终为NULL。

如果验证失败函数返回-1。

如果验证成功，函数返回0。将解密消息放入m，其长度与密文的长度一致。

常量

crypto_aead_aes256gcm_KEYBYTES
crypto_aead_aes256gcm_NPUBBYTES
crypto_aead_aes256gcm_ABYTES

说明

为了防止瞬时值重用，如果一个密钥被重用了，建议增加之前的瞬时值，而不是为每条消息都生成一个随机的瞬时值。为了防止瞬时值在C/S模型中被重用，要么在每个方向的通信中使用不同的密钥，要么确保在一个比特位在一个方向中被屏蔽，然后再另一个方向上设置。

建议将大于2Gb的消息拆分成更小的块。

在Libsodium 1.0.4引入了对AES256-GCM的支持。

Libsodium 1.0.9中引入了分离API。

经过预计算的AES256-GCM

使用相同密钥加密多条消息的应用程序可以通过预计算接口仅仅扩展一次AES密钥，从而获得一点加速。

int crypto_aead_aes256gcm_beforenm(crypto_aead_aes256gcm_state *ctx_,
                                   const unsigned char *k);

crypto_aead_aes256gcm_beforenm()函数通过扩展密钥k来初始化上下文ctx，并始终返回0。

ctx的地址需要16字节对齐。可以使用sizeof(crypto_aead_aes256gcm_state)或者crypto_aead_aes256gcm_statebytes()来获取这个值的大小。

带有预计算的组合模式

int crypto_aead_aes256gcm_encrypt_afternm(unsigned char *c,
                                         unsigned long long *clen_p,
                                         const unsigned char *m,
                                         unsigned long long mlen,
                                         const unsigned char *ad,
                                         unsigned long long adlen,
                                         const unsigned char *nsec,
                                         const unsigned char *npub,
                                         const crypto_aead_aes256gcm_state *ctx_);

int crypto_aead_aes256gcm_decrypt_afternm(unsigned char *m,
                                         unsigned long long *mlen_p,
                                         unsigned char *nsec,
                                         const unsigned char *c,
                                         unsigned long long clen,
                                         const unsigned char *ad,
                                         unsigned long long adlen,
                                         const unsigned char *npub,
                                         const crypto_aead_aes256gcm_state *ctx_);

crypto_aead_aes256gcm_encrypt_afternm()函数、crypto_aead_aes256gcm_decrypt_afternm()函数与crypto_aead_aes256gcm_encrypt()函数、crypto_aead_aes256gcm_decrypt()函数相同，但是接收的是之前初始化的上下文ctx而不是密钥。

带有预计算的分离模式

int crypto_aead_aes256gcm_encrypt_detached_afternm(unsigned char *c,
                                                   unsigned char *mac,
                                                   unsigned long long *maclen_p,
                                                   const unsigned char *m,
                                                   unsigned long long mlen,
                                                   const unsigned char *ad,
                                                   unsigned long long adlen,
                                                   const unsigned char *nsec,
                                                   const unsigned char *npub,
                                                   const crypto_aead_aes256gcm_state *ctx_);

int crypto_aead_aes256gcm_decrypt_detached_afternm(unsigned char *m,
                                                   unsigned char *nsec,
                                                   const unsigned char *c,
                                                   unsigned long long clen,
                                                   const unsigned char *mac,
                                                   const unsigned char *ad,
                                                   unsigned long long adlen,
                                                   const unsigned char *npub,
                                                   const crypto_aead_aes256gcm_state *ctx_)

crypto_aead_aes256gcm_encrypt_detached_afternm()函数、crypto_aead_aes256gcm_decrypt_detached_afternm()函数和crypto_aead_aes256gcm_encrypt_detached()函数、crypto_aead_aes256gcm_decrypt_detached()函数相同，但是接收的是之前初始化的上下文ctx而不是密钥。

常量

crypto_aead_aes256gcm_KEYBYTES
crypto_aead_aes256gcm_NPUBBYTES
crypto_aead_aes256gcm_ABYTES

数据类型

crypto_aead_aes256gcm_state

说明

瞬时值为96比特长。为了防止瞬时值重用，如果一个密钥被重用了，建议增加之前的瞬时值，而不是为每条消息都生成一个随机的瞬时值。为了防止瞬时值在C/S模型中被重用，要么在每个方向的通信中使用不同的密钥，要么确保在一个比特位在一个方向中被屏蔽，然后再另一个方向上设置。

建议将大于2Gb的消息拆分成更小的块，在某个密钥加密的数据量达到64比特前换一个新的密钥。

在Libsodium 1.0.4中引入了对AES256-GCM的支持。

在Libsodium 1.0.9中引入了分离API。