From: Andre Noll Date: Thu, 12 Jun 2025 23:03:26 +0000 (+0200) Subject: crypt X-Git-Url: https://git.tuebingen.mpg.de/?a=commitdiff_plain;h=378e8c9c41ec1aae634756eda2665179df1155e2;p=paraslash.git crypt --- diff --git a/crypt.h b/crypt.h index 2e094ced..60327098 100644 --- a/crypt.h +++ b/crypt.h @@ -1,11 +1,28 @@ /* Copyright (C) 2005 Andre Noll , see file COPYING. */ -/** \file crypt.h Public crypto interface. */ - -/* - * Asymmetric pubkey cryptosystem (apc). - * - * This is just RSA, but this fact is a hidden implementation detail. +/** \file crypt.h Crypto API. + * + * The API consists of the following independent parts: the asymmetric public + * key cryptosystem (functions whose name starts with apc_), the stream + * cipher API (prefix _sc), the hash function API, and a function to fill a + * buffer with random data (\ref get_random_bytes_or_die()). APC is just RSA, + * but this implementation detail is hidden by the API. + * + * The source tree contains two interchangeable implementations, \ref openssl.c + * and \ref gcrypt.c, which are based on the corresponding crypto libraries. At + * most one of these two source files is compiled in, however. The configure + * script picks one or the other, depending on the outcome of the header and + * library checks which are performed when the package is configured. Some + * helper functions which are independent of the crypto library are defined + * in \ref crypt_common.c. The file \ref crypt_backend.h declares additional + * helpers which are not supposed to be called by users of the crypto API + * but only by the implementations. + * + * The users of the crypto API are para_server(1), para_audiod(1) and + * para_client(1), which employ the API to authenticate connections and + * to encrypt the network traffic. Additionally, the audio file selector + * of para_server(1) uses hashing to identify audio files and to detect + * content changes. */ /** The size of the challenge sent to the client. */ @@ -19,7 +36,7 @@ struct asymmetric_key; * * \param pub: The public key. * \param inbuf The input buffer. - * \param len The length of \a inbuf. + * \param len The length of inbuf. * \param outbuf The output buffer will be allocated by the callee. * * \return The size of the encrypted data on success, negative on errors. @@ -33,9 +50,9 @@ int apc_pub_encrypt(struct asymmetric_key *pub, unsigned char *inbuf, * \param key_file Full path of the key. * \param outbuf The output buffer is allocated by the callee. * \param inbuf The encrypted input buffer. - * \param inlen The length of \a inbuf. + * \param inlen The length of inbuf. * - * The \a outbuf must be large enough to hold at least 512 bytes. + * The outbuf must be large enough to hold at least 512 bytes. * * \return The size of the recovered plaintext on success, negative on errors. */ @@ -67,9 +84,9 @@ void apc_free_pubkey(struct asymmetric_key *key); * Fill a buffer with random content. * * \param buf The buffer to fill. - * \param num The size of \a buf in bytes. + * \param num The size of buf in bytes. * - * This function puts \a num cryptographically strong pseudo-random bytes into + * This function puts num cryptographically strong pseudo-random bytes into * buf. If it can not guarantee an unpredictable byte sequence (for example * because the PRNG has not been seeded with enough randomness) the function * logs an error message and calls exit(). @@ -134,7 +151,7 @@ struct stream_cipher *sc_new(const unsigned char *data, int len); * * It is up to the implementation to decide whether the crypt operation is * performed in place. The caller can tell by looking if the buffers given by - * \a src and \a dst coincide after the call. If (and only if) the crypt + * src and dst coincide after the call. If (and only if) the crypt * operation was not performed in place, the function allocated a new buffer * for the result, so dst->iov_base is different from src->iov_base. In this * case, the destination buffer must be freed by the caller when it is no @@ -169,10 +186,11 @@ void sc_free(struct stream_cipher *sc); * Compute the hash of the given input data. * * \param data Pointer to the data to compute the hash value from. - * \param len The length of \a data in bytes. + * \param len The length of data in bytes. * \param hash Result pointer. * - * \a hash must point to an area at least \p HASH_SIZE bytes large. + * The function writes exactly HASH_SIZE bytes, hence the memory area for + * the result must be at least that large. * * \sa sha(3), openssl(1). * */ @@ -184,9 +202,9 @@ void hash_function(const char *data, unsigned long len, unsigned char *hash); * \param hash the hash value. * \param asc Result pointer. * - * \a asc must point to an area of at least 2 * \p HASH_SIZE + 1 bytes which - * will be filled by the function with the ascii representation of the hash - * value given by \a hash, and a terminating \p NULL byte. + * The function writes exactly 2 * HASH_SIZE + 1 bytes to fill the result + * buffer with the ascii representation of the hash value and a terminating + * NUL byte. */ void hash_to_asc(const unsigned char *hash, char *asc); @@ -196,8 +214,8 @@ void hash_to_asc(const unsigned char *hash, char *asc); * \param h1 Pointer to the first hash value. * \param h2 Pointer to the second hash value. * - * \return 1, -1, or zero, depending on whether \a h1 is greater than, - * less than or equal to h2, respectively. + * \return 1, -1, or zero, depending on whether h1 is greater than, less + * than or equal to h2, respectively. */ int hash_compare(const unsigned char *h1, const unsigned char *h2); @@ -208,10 +226,11 @@ int hash_compare(const unsigned char *h1, const unsigned char *h2); * Compute the hash2 of the given input data. * * \param data Pointer to the data to compute the hash value from. - * \param len The length of \a data in bytes. + * \param len The length of data in bytes. * \param hash Result pointer. * - * \a hash must point to an area at least \p HASH2_SIZE bytes large. + * The function writes exactly HASH2_SIZE bytes, hence the memory area for + * the result must be at least that large. * * \sa sha(3), openssl(1). * */ @@ -223,9 +242,9 @@ void hash2_function(const char *data, unsigned long len, unsigned char *hash); * \param hash the hash value. * \param asc Result pointer. * - * \a asc must point to an area of at least 2 * \p HASH2_SIZE + 1 bytes which - * will be filled by the function with the ascii representation of the hash - * value given by \a hash, and a terminating \p NULL byte. + * The function writes exactly 2 * HASH2_SIZE + 1 bytes to fill the result + * buffer with the ascii representation of the hash value and a terminating + * NUL byte. */ void hash2_to_asc(const unsigned char *hash, char *asc); @@ -235,7 +254,7 @@ void hash2_to_asc(const unsigned char *hash, char *asc); * \param h1 Pointer to the first hash value. * \param h2 Pointer to the second hash value. * - * \return 1, -1, or zero, depending on whether \a h1 is greater than, + * \return 1, -1, or zero, depending on whether h1 is greater than, * less than or equal to h2, respectively. */ int hash2_compare(const unsigned char *h1, const unsigned char *h2);