diff --git a/src/common/crypto.c b/src/common/crypto.c index 80345d430c..a5a01ae382 100644 --- a/src/common/crypto.c +++ b/src/common/crypto.c @@ -432,7 +432,8 @@ crypto_pk_get_rsa_(crypto_pk_t *env) } /** used by tortls.c: get an equivalent EVP_PKEY* for a crypto_pk_t. Iff - * private is set, include the private-key portion of the key. */ + * private is set, include the private-key portion of the key. Return a valid + * pointer on success, and NULL on failure. */ MOCK_IMPL(EVP_PKEY *, crypto_pk_get_evp_pkey_,(crypto_pk_t *env, int private)) { @@ -656,7 +657,8 @@ crypto_pk_read_private_key_from_filename(crypto_pk_t *env, return 0; } -/** Helper function to implement crypto_pk_write_*_key_to_string. */ +/** Helper function to implement crypto_pk_write_*_key_to_string. Return 0 on + * success, -1 on failure. */ static int crypto_pk_write_key_to_string_impl(crypto_pk_t *env, char **dest, size_t *len, int is_public) @@ -897,7 +899,8 @@ crypto_pk_dup_key(crypto_pk_t *env) return env; } -/** Make a real honest-to-goodness copy of env, and return it. */ +/** Make a real honest-to-goodness copy of env, and return it. + * Returns NULL on failure. */ crypto_pk_t * crypto_pk_copy_full(crypto_pk_t *env) { @@ -1189,7 +1192,8 @@ crypto_pk_public_hybrid_encrypt(crypto_pk_t *env, return -1; } -/** Invert crypto_pk_public_hybrid_encrypt. */ +/** Invert crypto_pk_public_hybrid_encrypt. Returns the number of bytes + * written on success, -1 on failure. */ int crypto_pk_private_hybrid_decrypt(crypto_pk_t *env, char *to, @@ -1484,7 +1488,7 @@ crypto_cipher_get_key(crypto_cipher_t *env) /** Encrypt fromlen bytes from from using the cipher * env; on success, store the result to to and return 0. - * On failure, return -1. + * Does not check for failure. */ int crypto_cipher_encrypt(crypto_cipher_t *env, char *to, @@ -1503,7 +1507,7 @@ crypto_cipher_encrypt(crypto_cipher_t *env, char *to, /** Decrypt fromlen bytes from from using the cipher * env; on success, store the result to to and return 0. - * On failure, return -1. + * Does not check for failure. */ int crypto_cipher_decrypt(crypto_cipher_t *env, char *to, @@ -1519,7 +1523,7 @@ crypto_cipher_decrypt(crypto_cipher_t *env, char *to, } /** Encrypt len bytes on from using the cipher in env; - * on success, return 0. On failure, return -1. + * on success, return 0. Does not check for failure. */ int crypto_cipher_crypt_inplace(crypto_cipher_t *env, char *buf, size_t len) @@ -1591,7 +1595,7 @@ crypto_cipher_decrypt_with_iv(const char *key, /** Compute the SHA1 digest of the len bytes on data stored in * m. Write the DIGEST_LEN byte result into digest. - * Return 0 on success, -1 on failure. + * Return 0 on success, 1 on failure. */ int crypto_digest(char *digest, const char *m, size_t len) @@ -1603,7 +1607,7 @@ crypto_digest(char *digest, const char *m, size_t len) /** Compute a 256-bit digest of len bytes in data stored in m, * using the algorithm algorithm. Write the DIGEST_LEN256-byte result - * into digest. Return 0 on success, -1 on failure. */ + * into digest. Return 0 on success, 1 on failure. */ int crypto_digest256(char *digest, const char *m, size_t len, digest_algorithm_t algorithm) @@ -1836,7 +1840,7 @@ crypto_digest_smartlist_prefix(char *digest_out, size_t len_out, /** Compute the HMAC-SHA-256 of the msg_len bytes in msg, using * the key of length key_len. Store the DIGEST256_LEN-byte - * result in hmac_out. + * result in hmac_out. Asserts on failure. */ void crypto_hmac_sha256(char *hmac_out, @@ -1941,7 +1945,8 @@ init_dh_param(void) */ #define DH_PRIVATE_KEY_BITS 320 -/** Allocate and return a new DH object for a key exchange. +/** Allocate and return a new DH object for a key exchange. Returns NULL on + * failure. */ crypto_dh_t * crypto_dh_new(int dh_type) @@ -2196,7 +2201,7 @@ crypto_expand_key_material_TAP(const uint8_t *key_in, size_t key_in_len, * secret key material; the salt_in_len bytes at salt_in and the * info_in_len bytes in info_in_len are the algorithm's "salt" * and "info" parameters respectively. On success, write key_out_len - * bytes to key_out and return 0. On failure, return -1. + * bytes to key_out and return 0. Assert on failure. */ int crypto_expand_key_material_rfc5869_sha256( @@ -2280,7 +2285,7 @@ crypto_seed_weak_rng(tor_weak_rng_t *rng) } /** Try to get out_len bytes of the strongest entropy we can generate, - * storing it into out. + * storing it into out. Return -1 on success, 0 on failure. */ int crypto_strongest_rand(uint8_t *out, size_t out_len) @@ -2373,7 +2378,7 @@ crypto_rand, (char *to, size_t n)) } /** Write n bytes of strong random data to to. Return 0 on - * success, -1 on failure. Most callers will want crypto_rand instead. + * success, assert on failure. Most callers will want crypto_rand instead. */ int crypto_rand_unmocked(char *to, size_t n) @@ -2410,8 +2415,8 @@ crypto_rand_int(unsigned int max) } } -/** Return a pseudorandom integer, chosen uniformly from the values i - * such that min <= i < max. +/** Return a pseudorandom integer, chosen uniformly from the values i such + * that min <= i < max. * * min MUST be in range [0, max). * max MUST be in range (min, INT_MAX]. @@ -2488,7 +2493,7 @@ crypto_rand_double(void) /** Generate and return a new random hostname starting with prefix, * ending with suffix, and containing no fewer than * min_rand_len and no more than max_rand_len random base32 - * characters between. + * characters. Does not check for failure. * * Clip max_rand_len to MAX_DNS_LABEL_SIZE. **/ @@ -2670,7 +2675,7 @@ tor_set_openssl_thread_id(CRYPTO_THREADID *threadid) /** @{ */ /** Helper: Construct mutexes, and set callbacks to help OpenSSL handle being - * multithreaded. */ + * multithreaded. Returns 0. */ static int setup_openssl_threading(void) { @@ -2688,7 +2693,8 @@ setup_openssl_threading(void) return 0; } -/** Uninitialize the crypto library. Return 0 on success, -1 on failure. +/** Uninitialize the crypto library. Return 0 on success. Does not detect + * failure. */ int crypto_global_cleanup(void)