From 96bd269d26af317ba985ad7eec7f75dec5d76bd7 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Fri, 11 Mar 2011 23:55:01 +0100 Subject: [PATCH] crypt: Move documentation to crypt.h. Since we will have two implementations soon, the documentation of the public API should go to the common header. Also fix the documentation of pub_encrypt(): The size of the input buffer is never enough. 512 always suffices. --- crypt.c | 113 ++------------------------------ crypt.h | 174 ++++++++++++++++++++++++++++++++++++++++++++++++- crypt_common.c | 48 -------------- 3 files changed, 175 insertions(+), 160 deletions(-) diff --git a/crypt.c b/crypt.c index 2dc15461..f064fb3a 100644 --- a/crypt.c +++ b/crypt.c @@ -28,17 +28,6 @@ struct asymmetric_key { RSA *rsa; }; -/** - * Fill a buffer with random content. - * - * \param buf The buffer to fill. - * \param num The size of \a buf in bytes. - * - * This function puts \a num cryptographically strong pseudo-random bytes into - * buf. If libssl 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(). - */ void get_random_bytes_or_die(unsigned char *buf, int num) { unsigned long err; @@ -51,13 +40,10 @@ void get_random_bytes_or_die(unsigned char *buf, int num) exit(EXIT_FAILURE); } -/** - * Seed pseudo random number generators. - * - * This function reads 64 bytes from /dev/urandom and adds them to the SSL - * PRNG. It also seeds the PRNG used by random() with a random seed obtained - * from SSL. If /dev/random could not be read, an error message is logged and - * the function calls exit(). +/* + * Read 64 bytes from /dev/urandom and adds them to the SSL PRNG. Seed the PRNG + * used by random() with a random seed obtained from SSL. If /dev/random is not + * readable the function calls exit(). * * \sa RAND_load_file(3), \ref get_random_bytes_or_die(), srandom(3), * random(3), \ref para_random(). @@ -167,17 +153,6 @@ fail: return ret; } -/** - * Read an asymmetric key from a file. - * - * \param key_file The file containing the key. - * \param private if non-zero, read the private key, otherwise the public key. - * \param result The key structure is returned here. - * - * \return The size of the key on success, negative on errors. - * - * \sa openssl(1), rsa(1). - */ int get_asymmetric_key(const char *key_file, int private, struct asymmetric_key **result) { @@ -237,13 +212,6 @@ out: return ret; } -/** - * Deallocate an asymmetric key structure. - * - * \param key Pointer to the key structure to free. - * - * This must be called for any key obtained by get_asymmetric_key(). - */ void free_asymmetric_key(struct asymmetric_key *key) { if (!key) @@ -252,20 +220,6 @@ void free_asymmetric_key(struct asymmetric_key *key) free(key); } -/** - * Decrypt a buffer using a private key. - * - * \param key_file Full path of the key. - * \param outbuf The output buffer. - * \param inbuf The encrypted input buffer. - * \param inlen The length of \a inbuf in bytes. - * - * The \a outbuf must be large enough to hold at least \a rsa_inlen bytes. - * - * \return The size of the recovered plaintext on success, negative on errors. - * - * \sa RSA_private_decrypt(3) - **/ int priv_decrypt(const char *key_file, unsigned char *outbuf, unsigned char *inbuf, int inlen) { @@ -294,18 +248,6 @@ out: return ret; } -/** - * Encrypt a buffer using an RSA key - * - * \param pub: The public key. - * \param inbuf The input buffer. - * \param len The length of \a inbuf. - * \param outbuf The output buffer. - * - * \return The size of the encrypted data on success, negative on errors. - * - * \sa RSA_public_encrypt(3) - */ int pub_encrypt(struct asymmetric_key *pub, unsigned char *inbuf, unsigned len, unsigned char *outbuf) { @@ -322,14 +264,6 @@ struct stream_cipher { RC4_KEY key; }; -/** - * Allocate and initialize a stream cipher structure. - * - * \param data The key. - * \param len The size of the key. - * - * \return A new stream cipher structure. - */ struct stream_cipher *sc_new(const unsigned char *data, int len) { struct stream_cipher *sc = para_malloc(sizeof(*sc)); @@ -337,11 +271,6 @@ struct stream_cipher *sc_new(const unsigned char *data, int len) return sc; } -/** - * Deallocate a stream cipher structure. - * - * \param sc A stream cipher previously obtained by sc_new(). - */ void sc_free(struct stream_cipher *sc) { free(sc); @@ -354,17 +283,6 @@ void sc_free(struct stream_cipher *sc) */ #define RC4_ALIGN 8 -/** - * Encrypt and send a buffer. - * - * \param scc The context. - * \param buf The buffer to send. - * \param len The size of \a buf in bytes. - * - * \return The return value of the underyling call to write_all(). - * - * \sa \ref write_all(), RC4(3). - */ int sc_send_bin_buffer(struct stream_cipher_context *scc, char *buf, size_t len) { @@ -385,18 +303,6 @@ int sc_send_bin_buffer(struct stream_cipher_context *scc, char *buf, return ret; } -/** - * Receive a buffer and decrypt it. - * - * \param scc The context. - * \param buf The buffer to write the decrypted data to. - * \param size The size of \a buf. - * - * \return The number of bytes received on success, negative on errors, zero if - * the peer has performed an orderly shutdown. - * - * \sa recv(2), RC4(3). - */ int sc_recv_bin_buffer(struct stream_cipher_context *scc, char *buf, size_t size) { @@ -411,17 +317,6 @@ int sc_recv_bin_buffer(struct stream_cipher_context *scc, char *buf, return ret; } -/** - * 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 hash Result pointer. - * - * \a hash must point to an area at least \p HASH_SIZE bytes large. - * - * \sa sha(3), openssl(1). - * */ void hash_function(const char *data, unsigned long len, unsigned char *hash) { SHA_CTX c; diff --git a/crypt.h b/crypt.h index fc41acf3..4696ee4a 100644 --- a/crypt.h +++ b/crypt.h @@ -18,24 +18,88 @@ /** Opaque structure for public and private keys. */ struct asymmetric_key; +/** + * Encrypt a buffer using asymmetric keys. + * + * \param pub: The public key. + * \param inbuf The input buffer. + * \param len The length of \a inbuf. + * \param outbuf The output buffer. + * + * \return The size of the encrypted data on success, negative on errors. + */ int pub_encrypt(struct asymmetric_key *pub, unsigned char *inbuf, unsigned len, unsigned char *outbuf); + +/** + * Decrypt a buffer using a private key. + * + * \param key_file Full path of the key. + * \param outbuf The output buffer. + * \param inbuf The encrypted input buffer. + * \param inlen The length of \a inbuf. + * + * The \a outbuf must be large enough to hold at least 512 bytes. + * + * \return The size of the recovered plaintext on success, negative on errors. + */ int priv_decrypt(const char *key_file, unsigned char *outbuf, unsigned char *inbuf, int inlen); + +/** + * Read an asymmetric key from a file. + * + * \param key_file The file containing the key. + * \param private if non-zero, read the private key, otherwise the public key. + * \param result The key structure is returned here. + * + * \return The size of the key on success, negative on errors. + */ int get_asymmetric_key(const char *key_file, int private, struct asymmetric_key **result); + +/** + * Deallocate an asymmetric key structure. + * + * \param key Pointer to the key structure to free. + * + * This must be called for any key obtained by get_asymmetric_key(). + */ void free_asymmetric_key(struct asymmetric_key *key); -/* random numbers */ + +/** + * Fill a buffer with random content. + * + * \param buf The buffer to fill. + * \param num The size of \a buf in bytes. + * + * This function puts \a 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(). + */ void get_random_bytes_or_die(unsigned char *buf, int num); + +/** + * Seed pseudo random number generators. + * + * This function seeds the PRNG used by random() with a random seed obtained + * from the crypto implementation. On errors, an error message is logged and + * the function calls exit(). + * + * \sa \ref get_random_bytes_or_die(), srandom(3), random(3), \ref + * para_random(). + */ void init_random_seed_or_die(void); -/* stream cipher declarations and prototypes */ /** Opaque structure for stream ciphers. */ struct stream_cipher; + /** Number of bytes of the session key for stream ciphers. */ #define SESSION_KEY_LEN 32 + /** * Used for client-server communication encryption. * @@ -52,22 +116,126 @@ struct stream_cipher_context { /** Key used for sending data. */ struct stream_cipher *send; }; + +/** + * Allocate and initialize a stream cipher structure. + * + * \param data The key. + * \param len The size of the key. + * + * \return A new stream cipher structure. + */ struct stream_cipher *sc_new(const unsigned char *data, int len); + +/** + * Deallocate a stream cipher structure. + * + * \param sc A stream cipher previously obtained by sc_new(). + */ void sc_free(struct stream_cipher *sc); + +/** + * Encrypt and send a buffer. + * + * \param scc The context. + * \param buf The buffer to send. + * \param len The size of \a buf in bytes. + * + * \return The return value of the underyling call to write_all(). + * + * \sa \ref write_all(), RC4(3). + */ int sc_send_bin_buffer(struct stream_cipher_context *scc, char *buf, size_t len); + +/** + * Encrypt and send a \p NULL-terminated buffer. + * + * \param scc The context. + * \param buf The buffer to send. + * + * \return The return value of the underyling call to sc_send_bin_buffer(). + */ int sc_send_buffer(struct stream_cipher_context *scc, char *buf); + +/** + * Format, encrypt and send a buffer. + * + * \param scc The context. + * \param fmt A format string. + * + * \return The return value of the underyling call to sc_send_buffer(). + */ __printf_2_3 int sc_send_va_buffer(struct stream_cipher_context *scc, const char *fmt, ...); + +/** + * Receive a buffer and decrypt it. + * + * \param scc The context. + * \param buf The buffer to write the decrypted data to. + * \param size The size of \a buf. + * + * \return The number of bytes received on success, negative on errors, zero if + * the peer has performed an orderly shutdown. + * + * \sa recv(2), RC4(3). + */ int sc_recv_bin_buffer(struct stream_cipher_context *scc, char *buf, size_t size); + +/** + * Receive a buffer, decrypt it and write terminating NULL byte. + * + * \param scc The context. + * \param buf The buffer to write the decrypted data to. + * \param size The size of \a buf. + * + * Read at most \a size - 1 bytes from file descriptor given by \a scc, decrypt + * the received data and write a NULL byte at the end of the decrypted data. + * + * \return The return value of the underlying call to \ref + * sc_recv_bin_buffer(). + */ int sc_recv_buffer(struct stream_cipher_context *scc, char *buf, size_t size); -/* hashing */ /** Size of the hash value in bytes. */ #define HASH_SIZE 20 + +/** + * 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 hash Result pointer. + * + * \a hash must point to an area at least \p HASH_SIZE bytes large. + * + * \sa sha(3), openssl(1). + * */ void hash_function(const char *data, unsigned long len, unsigned char *hash); + +/** + * Convert a hash value to ascii format. + * + * \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. + */ void hash_to_asc(unsigned char *hash, char *asc); + +/** + * Compare two hashes. + * + * \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. + */ int hash_compare(unsigned char *h1, unsigned char *h2); diff --git a/crypt_common.c b/crypt_common.c index a2f68268..05d71de4 100644 --- a/crypt_common.c +++ b/crypt_common.c @@ -247,16 +247,6 @@ int check_key_file(const char *file, bool private_key) return 1; } -/** - * Convert a hash value to ascii format. - * - * \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. - */ void hash_to_asc(unsigned char *hash, char *asc) { int i; @@ -269,15 +259,6 @@ void hash_to_asc(unsigned char *hash, char *asc) asc[2 * HASH_SIZE] = '\0'; } -/** - * Compare two hashes. - * - * \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. - */ int hash_compare(unsigned char *h1, unsigned char *h2) { int i; @@ -291,19 +272,6 @@ int hash_compare(unsigned char *h1, unsigned char *h2) return 0; } -/** - * Receive a buffer, decrypt it and write terminating NULL byte. - * - * \param scc The context. - * \param buf The buffer to write the decrypted data to. - * \param size The size of \a buf. - * - * Read at most \a size - 1 bytes from file descriptor given by \a scc, decrypt - * the received data and write a NULL byte at the end of the decrypted data. - * - * \return The return value of the underlying call to \ref - * sc_recv_bin_buffer(). - */ int sc_recv_buffer(struct stream_cipher_context *scc, char *buf, size_t size) { int n; @@ -317,27 +285,11 @@ int sc_recv_buffer(struct stream_cipher_context *scc, char *buf, size_t size) return n; } -/** - * Encrypt and send a \p NULL-terminated buffer. - * - * \param scc The context. - * \param buf The buffer to send. - * - * \return The return value of the underyling call to sc_send_bin_buffer(). - */ int sc_send_buffer(struct stream_cipher_context *scc, char *buf) { return sc_send_bin_buffer(scc, buf, strlen(buf)); } -/** - * Format, encrypt and send a buffer. - * - * \param scc The context. - * \param fmt A format string. - * - * \return The return value of the underyling call to sc_send_buffer(). - */ __printf_2_3 int sc_send_va_buffer(struct stream_cipher_context *scc, const char *fmt, ...) { -- 2.39.2