crypt

diff --git a/crypt.h b/crypt.h
index 2e094ced9ee760ced8a7647217a5046bc58e0c20..603270984559716c1704849836ef1c80f77b5d5a 100644 (file)
--- a/crypt.h
+++ b/crypt.h
@@ -1,11 +1,28 @@
 /* Copyright (C) 2005 Andre Noll <maan@tuebingen.mpg.de>, 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);