[tor-commits] [tor/master] Fix comments to describe actual return values (crypto.c)
nickm at torproject.org
nickm at torproject.org
Wed Nov 25 14:08:23 UTC 2015
commit 5b2adfb3d431b8f39cbddbd530840cacbb9b5ce5
Author: teor (Tim Wilson-Brown) <teor2345 at gmail.com>
Date: Mon Nov 23 20:31:57 2015 +1100
Fix comments to describe actual return values (crypto.c)
---
src/common/crypto.c | 44 +++++++++++++++++++++++++-------------------
1 file changed, 25 insertions(+), 19 deletions(-)
diff --git a/src/common/crypto.c b/src/common/crypto.c
index 80345d4..a5a01ae 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 <b>env</b>, and return it. */
+/** Make a real honest-to-goodness copy of <b>env</b>, 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 <b>fromlen</b> bytes from <b>from</b> using the cipher
* <b>env</b>; on success, store the result to <b>to</b> 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 <b>fromlen</b> bytes from <b>from</b> using the cipher
* <b>env</b>; on success, store the result to <b>to</b> 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 <b>len</b> bytes on <b>from</b> using the cipher in <b>env</b>;
- * 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 <b>len</b> bytes on data stored in
* <b>m</b>. Write the DIGEST_LEN byte result into <b>digest</b>.
- * 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 <b>len</b> bytes in data stored in <b>m</b>,
* using the algorithm <b>algorithm</b>. Write the DIGEST_LEN256-byte result
- * into <b>digest</b>. Return 0 on success, -1 on failure. */
+ * into <b>digest</b>. 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 <b>msg_len</b> bytes in <b>msg</b>, using
* the <b>key</b> of length <b>key_len</b>. Store the DIGEST256_LEN-byte
- * result in <b>hmac_out</b>.
+ * result in <b>hmac_out</b>. 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 <b>salt_in_len</b> bytes at <b>salt_in</b> and the
* <b>info_in_len</b> bytes in <b>info_in_len</b> are the algorithm's "salt"
* and "info" parameters respectively. On success, write <b>key_out_len</b>
- * bytes to <b>key_out</b> and return 0. On failure, return -1.
+ * bytes to <b>key_out</b> 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 <b>out_len</b> bytes of the strongest entropy we can generate,
- * storing it into <b>out</b>.
+ * storing it into <b>out</b>. 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 <b>n</b> bytes of strong random data to <b>to</b>. 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>i</i>
- * such that <b>min</b> <= <i>i</i> < <b>max</b>.
+/** Return a pseudorandom integer, chosen uniformly from the values i such
+ * that min <= i < max.
*
* <b>min</b> MUST be in range [0, <b>max</b>).
* <b>max</b> MUST be in range (min, INT_MAX].
@@ -2488,7 +2493,7 @@ crypto_rand_double(void)
/** Generate and return a new random hostname starting with <b>prefix</b>,
* ending with <b>suffix</b>, and containing no fewer than
* <b>min_rand_len</b> and no more than <b>max_rand_len</b> random base32
- * characters between.
+ * characters. Does not check for failure.
*
* Clip <b>max_rand_len</b> 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)
More information about the tor-commits
mailing list