crypt_ops Directory Reference

lib/crypt_ops: Cryptographic operations.

More...

Files
file	aes.h [code]
	Headers for aes.c.
file	aes_nss.c [code]
	Use NSS to implement AES_CTR.
file	aes_openssl.c [code]
	Use OpenSSL to implement AES_CTR.
file	crypto_cipher.c [code]
	Symmetric cryptography (low-level) with AES.
file	crypto_cipher.h [code]
	Headers for crypto_cipher.c.
file	crypto_curve25519.c [code]
	Wrapper code for a curve25519 implementation.
file	crypto_curve25519.h [code]
	Header for crypto_curve25519.c.
file	crypto_dh.c [code]
	Block of functions related with DH utilities and operations. over Z_p. We aren't using this for any new crypto – EC is more efficient.
file	crypto_dh.h [code]
	Headers for crypto_dh.c.
file	crypto_dh_nss.c [code]
	NSS implementation of Diffie-Hellman over Z_p.
file	crypto_dh_openssl.c [code]
	Implement Tor's Z_p diffie-hellman stuff for OpenSSL.
file	crypto_digest.c [code]
	Block of functions related with digest and xof utilities and operations.
file	crypto_digest.h [code]
	Headers for crypto_digest.c.
file	crypto_digest_nss.c [code]
	Block of functions related with digest and xof utilities and operations (NSS specific implementations).
file	crypto_digest_openssl.c [code]
	Block of functions related with digest and xof utilities and operations (OpenSSL specific implementations).
file	crypto_ed25519.c [code]
	Wrapper code for an ed25519 implementation.
file	crypto_ed25519.h [code]
	Header for crypto_ed25519.c.
file	crypto_format.c [code]
	Formatting and parsing code for crypto-related data structures.
file	crypto_format.h [code]
	Header for crypto_format.c.
file	crypto_hkdf.c [code]
	Block of functions related with HKDF utilities and operations.
file	crypto_hkdf.h [code]
	Headers for crypto_hkdf.h.
file	crypto_init.c [code]
	Initialize and shut down Tor's crypto library and subsystem.
file	crypto_init.h [code]
	Headers for crypto_init.c.
file	crypto_nss_mgt.c [code]
	Manage the NSS library (if used)
file	crypto_nss_mgt.h [code]
	Headers for crypto_nss_mgt.c.
file	crypto_ope.c [code]
	A rudimentary order-preserving encryption scheme.
file	crypto_ope.h [code]
	header for crypto_ope.c
file	crypto_openssl_mgt.c [code]
	Block of functions related to operations from OpenSSL.
file	crypto_openssl_mgt.h [code]
	Headers for crypto_openssl_mgt.c.
file	crypto_options.inc [code]
	Declare configuration options for the crypto_ops module.
file	crypto_options_st.h [code]
	Header for lib/crypt_ops/crypto_options_st.c.
file	crypto_pwbox.c [code]
	Code for encrypting secrets in a password-protected form and saving them to disk.
file	crypto_pwbox.h [code]
	Header for crypto_pwbox.c.
file	crypto_rand.c [code]
	Functions for initialising and seeding (pseudo-)random number generators, and working with randomness.
file	crypto_rand.h [code]
	Common functions for using (pseudo-)random number generators.
file	crypto_rand_fast.c [code]
	A fast strong PRNG for use when our underlying cryptographic library's PRNG isn't fast enough.
file	crypto_rand_numeric.c [code]
	Functions for retrieving uniformly distributed numbers from our PRNGs.
file	crypto_rsa.c [code]
	Block of functions related with RSA utilities and operations.
file	crypto_rsa.h [code]
	Headers for crypto_rsa.c.
file	crypto_s2k.c [code]
	Functions for deriving keys from human-readable passphrases.
file	crypto_s2k.h [code]
	Header for crypto_s2k.c.
file	crypto_sys.h [code]
	Declare subsystem object for the crypto module.
file	crypto_util.c [code]
	Common cryptographic utilities.
file	crypto_util.h [code]
	Common functions for cryptographic routines.
file	digestset.c [code]
	Implementation for a set of digests.
file	digestset.h [code]
	Types to handle sets of digests, based on bloom filters.

Detailed Description

lib/crypt_ops: Cryptographic operations.

This module contains wrappers around the cryptographic libraries that we support, and implementations for some higher-level cryptographic constructions that we use.

It wraps our two major cryptographic backends (OpenSSL or NSS, as configured by the user), and also wraps other cryptographic code in src/ext.

Generally speaking, Tor code shouldn't be calling OpenSSL or NSS (or any other crypto library) directly. Instead, we should indirect through one of the functions in this directory, or through lib/tls.

Cryptography functionality that's available is described below.

RNG facilities

The most basic RNG capability in Tor is the crypto_rand() family of functions. These currently use OpenSSL's RAND_() backend, but may use something faster in the future.

In addition to crypto_rand(), which fills in a buffer with random bytes, we also have functions to produce random integers in certain ranges; to produce random hostnames; to produce random doubles, etc.

When you're creating a long-term cryptographic secret, you might want to use crypto_strongest_rand() instead of crypto_rand(). It takes the operating system's entropy source and combines it with output from crypto_rand(). This is a pure paranoia measure, but it might help us someday.

You can use smartlist_choose() to pick a random element from a smartlist and smartlist_shuffle() to randomize the order of a smartlist. Both are potentially a bit slow.

Cryptographic digests and related functions

We treat digests as separate types based on the length of their outputs. We support one 160-bit digest (SHA1), two 256-bit digests (SHA256 and SHA3-256), and two 512-bit digests (SHA512 and SHA3-512).

You should not use SHA1 for anything new.

The crypto_digest*() family of functions manipulates digests. You can either compute a digest of a chunk of memory all at once using crypto_digest(), crypto_digest256(), or crypto_digest512(). Or you can create a crypto_digest_t object with crypto_digest{,256,512}_new(), feed information to it in chunks using crypto_digest_add_bytes(), and then extract the final digest using crypto_digest_get_digest(). You can copy the state of one of these objects using crypto_digest_dup() or crypto_digest_assign().

We support the HMAC hash-based message authentication code instantiated using SHA256. See crypto_hmac_sha256. (You should not add any HMAC users with SHA1, and HMAC is not necessary with SHA3.)

We also support the SHA3 cousins, SHAKE128 and SHAKE256. Unlike digests, these are extendable output functions (or XOFs) where you can get any amount of output. Use the crypto_xof_*() functions to access these.

We have several ways to derive keys from cryptographically strong secret inputs (like diffie-hellman outputs). The old crypto_expand_key_material_TAP() performs an ad-hoc KDF based on SHA1 – you shouldn't use it for implementing anything but old versions of the Tor protocol. You can use HKDF-SHA256 (as defined in RFC5869) for more modern protocols. Also consider SHAKE256.

If your input is potentially weak, like a password or passphrase, use a salt along with the secret_to_key() functions as defined in crypto_s2k.c. Prefer scrypt over other hashing methods when possible. If you're using a password to encrypt something, see the "boxed file storage" section below.

Finally, in order to store objects in hash tables, Tor includes the randomized SipHash 2-4 function. Call it via the siphash24g() function in src/ext/siphash.h whenever you're creating a hashtable whose keys may be manipulated by an attacker in order to DoS you with collisions.

Stream ciphers

You can create instances of a stream cipher using crypto_cipher_new(). These are stateful objects of type crypto_cipher_t. Note that these objects only support AES-128 right now; a future version should add support for AES-128 and/or ChaCha20.

You can encrypt/decrypt with crypto_cipher_encrypt or crypto_cipher_decrypt. The crypto_cipher_crypt_inplace function performs an encryption without a copy.

Note that sensible people should not use raw stream ciphers; they should probably be using some kind of AEAD. Sorry.

Public key functionality

We support four public key algorithms: DH1024, RSA, Curve25519, and Ed25519.

We support DH1024 over two prime groups. You access these via the crypto_dh_*() family of functions.

We support RSA in many bit sizes for signing and encryption. You access it via the crypto_pk_*() family of functions. Note that a crypto_pk_t may or may not include a private key. See the crypto_pk_* functions in crypto.c for a full list of functions here.

For Curve25519 functionality, see the functions and types in crypto_curve25519.c. Curve25519 is generally suitable for when you need a secure fast elliptic-curve diffie hellman implementation. When designing new protocols, prefer it over DH in Z_p.

For Ed25519 functionality, see the functions and types in crypto_ed25519.c. Ed25519 is a generally suitable as a secure fast elliptic curve signature method. For new protocols, prefer it over RSA signatures.

Metaformats for storage

When OpenSSL manages the storage of some object, we use whatever format OpenSSL provides – typically, some kind of PEM-wrapped base 64 encoding that starts with "----- BEGIN CRYPTOGRAPHIC OBJECT ----".

When we manage the storage of some cryptographic object, we prefix the object with 32-byte NUL-padded prefix in order to avoid accidental object confusion; see the crypto_read_tagged_contents_from_file() and crypto_write_tagged_contents_to_file() functions for manipulating these. The prefix is "== type: tag ==", where type describes the object and its encoding, and tag indicates which one it is.

Boxed-file storage

When managing keys, you frequently want to have some way to write a secret object to disk, encrypted with a passphrase. The crypto_pwbox and crypto_unpwbox functions do so in a way that's likely to be readable by future versions of Tor.