crypt_ops Directory Reference

lib/crypt_ops: Cryptographic operations.



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 [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.