nacl

nacl
Login

nacl

NaCl - Networking and Cryptography library (pronounced "salt")

Synopsis

nacl::info
nacl::manifest
nacl::build-info ?version|patchlevel|commit|compiler?
nacl::randombytes names
nacl::randombytes source ?random|urandom|secrandomcopybytes|cryptgenrandom|default?
nacl::randombytes lengthValue
nacl::randombytes box ?-nonce?
nacl::randombytes scalarmult ?-scalar|-group?
nacl::randombytes secretbox ?-nonce|-key?
nacl::randombytes stream ?-nonce|-key?
nacl::randombytes auth ?-key?
nacl::randombytes onetimeauth ?-key?

Public-key cryptography

nacl::box info
nacl::box keypair publicKeyVariable secretKeyVariable
nacl::box cipherVariable messageValue nonceValue publicKeyValue secretKeyValue
nacl::box open messageVariable cipherValue nonceValue publicKeyValue secretKeyValue
nacl::scalarmult info
nacl::scalarmult resultVariable scalarValue groupValue
nacl::scalarmult base resultVariable scalarValue
nacl::sign info
nacl::sign keypair publicKeyVariable secretKeyVariable
nacl::sign signedVariable messageValue secretKeyValue
nacl::sign verify messageVariable signedValue publicKeyValue

Secret-key cryptography

nacl::secretbox info
nacl::secretbox cipherVariable messageValue nonceValue keyValue
nacl::secretbox open messageVariable cipherValue nonceValue keyValue
nacl::stream info
nacl::stream generate cipherVariable nonceValue keyValue
nacl::stream cipherVariable messageValue nonceValue keyValue
nacl::auth info
nacl::auth ?-hmac224|-hmac256|-hmac384|-hmac512256|-hmac512?
    authVariable messageValue keyValue
nacl::auth verify -hmac224|-hmac256|-hmac384|-hmac512256|-hmac512
    authValue messageValue keyValue
nacl::onetimeauth info
nacl::onetimeauth authVariable messageValue keyValue
nacl::onetimeauth verify authValue messageValue keyValue

Low-level functions

nacl::hash info
nacl::hash ?-sha256|-sha512? hashVariable messageValue

Description

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.

Key features

No data flow from secrets to load addresses. No data flow from secrets to branch conditions. No padding oracles. Centralizing randomness. Avoiding unnecessary randomness. Extremely high speed.

HMAC variants

nacl::auth offers the four untruncated HMACs that RFC 4231 defines test vectors for, plus the truncated one NaCl itself ships. All seven vectors of the RFC are covered by the test suite for each of the four.

option hash tag JWT
-hmac224 SHA-224 28 bytes --
-hmac256 SHA-256 32 bytes HS256
-hmac384 SHA-384 48 bytes HS384
-hmac512256 SHA-512 32 bytes NaCl crypto_auth, the default
-hmac512 SHA-512 64 bytes HS512

-hmac512256 is crypto_auth of NaCl: HMAC-SHA-512 cut to 32 bytes, so its tag is the prefix of an -hmac512 tag. -hmac224 and -hmac384 are no such prefixes of their bigger siblings, because SHA-224 and SHA-384 start from a different initial state. verify insists on a tag of the length its variant produces.

HMAC key length

nacl::auth accepts a key of any length. The key is prepared as required by RFC 2104 section 2: a key longer than the block size of the hash is replaced by its hash, a shorter one is padded with zero bytes on the right. The block size is 64 bytes for -hmac224 and -hmac256, 128 bytes for the other three.

The key is shortened with the hash of its own variant, SHA-224 for -hmac224 and SHA-384 for -hmac384, not with the hash of equal block size -- the differing initial state makes that distinction visible in the tag.

This is what makes nacl::auth usable for JWT and for webhook signatures, where the secret is chosen by the peer and rotating it changes its length. A key of exactly 32 bytes yields the same result as it always did, so nothing that worked before changes.

RFC 2104 sets no lower bound on the key length, and neither does nacl::auth. Enforcing a minimum is left to the caller, who knows the context. nacl::randombytes auth -key generates 32 bytes.

Functions supported

Simple NaCl applications need only six high-level NaCl functions: crypto_box for public-key authenticated encryption; crypto_box_open for verification and decryption; crypto_box_keypair to create a public key in the first place; and similarly for signatures crypto_sign, crypto_sign_open, and crypto_sign_keypair.

A minimalist implementation of the NaCl API would provide just these six functions. TweetNaCl is more ambitious, supporting all 25 of the NaCl functions listed below, which as mentioned earlier are all of the C NaCl functions used by applications. This list includes all of NaCl's "default" primitives except for crypto_auth_hmacsha512256, which was included in NaCl only for compatibility with standards and is superseded by crypto_onetimeauth.

The Ed25519 signature system has not yet been integrated into NaCl, since the Ed25519 software has not yet been fully audited; NaCl currently provides an older signature system. However, NaCl has announced that it will transition to Ed25519, so TweetNaCl provides Ed25519.

Public-key cryptography

Secret-key cryptography

Low-level functions

Wiki Pages

See Also

Copyright (C) 2016-2026 Alexander Schoepe, Bochum, DE

NaCl and TweetNaCl crypto library are public domain and the Tcl package BSD-3 license

Contributors (alphabetical order)