From: Nikos Mavrogiannopoulos Date: Thu, 21 Jan 2010 20:17:44 +0000 (+0100) Subject: Documented the crypto-api functions and made the API tolerant to NULL IV. X-Git-Tag: gnutls_2_9_10~157 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d495b8dd52da94f5c655f52ae50689048a177dc0;p=thirdparty%2Fgnutls.git Documented the crypto-api functions and made the API tolerant to NULL IV. --- diff --git a/lib/crypto-api.c b/lib/crypto-api.c index 8eb4179df9..b1ffd3cc53 100644 --- a/lib/crypto-api.c +++ b/lib/crypto-api.c @@ -29,6 +29,20 @@ #include #include +/** + * gnutls_cipher_init - initializes a crypto context + * @handle: is a #gnutls_cipher_hd_t structure. + * @cipher: the encryption algorithm to use + * @key: The key to be used for encryption + * @iv: The IV to use (if not applicable set NULL) + * + * This function will initialize an context that can + * be used for encryption/decryption of data. This will effectively + * use the current crypto backend in use by gnutls or the + * cryptographic accelerator in use. + * + * Returns: Zero or a negative value on error. + **/ int gnutls_cipher_init (gnutls_cipher_hd_t * handle, gnutls_cipher_algorithm_t cipher, const gnutls_datum_t * key, const gnutls_datum_t * iv) @@ -42,11 +56,33 @@ gnutls_cipher_init (gnutls_cipher_hd_t * handle, gnutls_cipher_algorithm_t ciphe return _gnutls_cipher_init(((cipher_hd_st*)*handle), cipher, key, iv); } +/** + * gnutls_cipher_encrypt - encrypts the given data + * @handle: is a #gnutls_cipher_hd_t structure. + * @text: the data to encrypt + * @textlen: The length of data to encrypt + * + * This function will encrypt the given data using the algorithm + * specified by the context. + * + * Returns: Zero or a negative value on error. + **/ int gnutls_cipher_encrypt (gnutls_cipher_hd_t handle, void *text, int textlen) { return _gnutls_cipher_encrypt((cipher_hd_st*)handle, text, textlen); } +/** + * gnutls_cipher_decrypt - decrypts the given data + * @handle: is a #gnutls_cipher_hd_t structure. + * @text: the data to encrypt + * @textlen: The length of data to encrypt + * + * This function will decrypt the given data using the algorithm + * specified by the context. + * + * Returns: Zero or a negative value on error. + **/ int gnutls_cipher_decrypt (gnutls_cipher_hd_t handle, void *ciphertext, int ciphertextlen) @@ -54,6 +90,15 @@ gnutls_cipher_decrypt (gnutls_cipher_hd_t handle, void *ciphertext, return _gnutls_cipher_decrypt((cipher_hd_st*)handle, ciphertext, ciphertextlen); } +/** + * gnutls_cipher_deinit - deinitializes resources by a context + * @handle: is a #gnutls_cipher_hd_t structure. + * + * This function will deinitialize all resources occupied by + * the given encryption context. + * + * Returns: This function has no return value. + **/ void gnutls_cipher_deinit (gnutls_cipher_hd_t handle) { @@ -62,6 +107,21 @@ gnutls_cipher_deinit (gnutls_cipher_hd_t handle) /* HMAC */ + +/** + * gnutls_hmac_init - initializes an HMAC context + * @handle: is a #gnutls_hmac_hd_t structure. + * @algorithm: the HMAC algorithm to use + * @key: The key to be used for encryption + * @keylen: The length of the key + * + * This function will initialize an context that can + * be used to produce a Message Authentication Code (MAC) of data. + * This will effectively use the current crypto backend in use by gnutls or + * the cryptographic accelerator in use. + * + * Returns: Zero or a negative value on error. + **/ int gnutls_hmac_init (gnutls_hmac_hd_t * dig, gnutls_digest_algorithm_t algorithm, const void *key, int keylen) @@ -75,28 +135,81 @@ gnutls_hmac_init (gnutls_hmac_hd_t * dig, gnutls_digest_algorithm_t algorithm, return _gnutls_hmac_init(((digest_hd_st*)*dig), algorithm, key, keylen); } +/** + * gnutls_hmac - hashes the given data + * @handle: is a #gnutls_cipher_hd_t structure. + * @text: the data to hash + * @textlen: The length of data to hash + * + * This function will hash the given data using the algorithm + * specified by the context. + * + * Returns: Zero or a negative value on error. + **/ int gnutls_hmac (gnutls_hmac_hd_t handle, const void *text, size_t textlen) { return _gnutls_hmac((digest_hd_st*)handle, text, textlen); } +/** + * gnutls_hmac_output - Outputs the current MAC value + * @handle: is a #gnutls_hmac_hd_t structure. + * @digest: is the output value of the MAC + * + * This function will output the current MAC value. + * + * Returns: This function has no return value. + **/ void gnutls_hmac_output (gnutls_hmac_hd_t handle, void *digest) { return _gnutls_hmac_output((digest_hd_st*)handle, digest); } -void -gnutls_hmac_deinit (gnutls_hmac_hd_t handle, void *digest) +/** + * gnutls_hmac_deinit - deinitializes resources by a context + * @handle: is a #gnutls_hmac_hd_t structure. + * @digest: is the output value of the MAC + * + * This function will deinitialize all resources occupied by + * the given hmac context. + * + * Returns: This function has no return value. + **/ +void gnutls_hmac_deinit (gnutls_hmac_hd_t handle, void *digest) { _gnutls_hmac_deinit((digest_hd_st*)handle, digest); } +/** + * gnutls_hmac_get_len - returns the length of the output data + * @algorithm: the hmac algorithm to use + * + * This function will return the length of the output data + * of the given hmac algorithm. + * + * Returns: The length or zero on error. + * + **/ int gnutls_hmac_get_len( gnutls_mac_algorithm_t algorithm) { return _gnutls_hmac_get_algo_len(algorithm); } +/** + * gnutls_hmac_fast - hashes data + * @algorithm: the hash algorithm to use + * @key: the key to use + * @keylen: The length of the key + * @text: the data to hash + * @textlen: The length of data to hash + * @digest: is the output value of the hash + * + * This convenience function will hash the given data and return output + * on a single call. + * + * Returns: Zero or a negative value on error. + **/ int gnutls_hmac_fast( gnutls_mac_algorithm_t algorithm, const void* key, int keylen, const void* text, size_t textlen, void* digest) { @@ -104,8 +217,22 @@ int gnutls_hmac_fast( gnutls_mac_algorithm_t algorithm, const void* key, int key } /* HASH */ -int -gnutls_hash_init (gnutls_hash_hd_t * dig, gnutls_digest_algorithm_t algorithm) + +/** + * gnutls_hash_init - initializes an hash context + * @handle: is a #gnutls_hash_hd_t structure. + * @algorithm: the hash algorithm to use + * @key: The key to be used for encryption + * @keylen: The length of the key + * + * This function will initialize an context that can + * be used to produce a Message Digest of data. + * This will effectively use the current crypto backend in use by gnutls or + * the cryptographic accelerator in use. + * + * Returns: Zero or a negative value on error. + **/ +int gnutls_hash_init (gnutls_hash_hd_t * dig, gnutls_digest_algorithm_t algorithm) { *dig = gnutls_malloc(sizeof(digest_hd_st)); if (*dig == NULL) { @@ -116,28 +243,79 @@ gnutls_hash_init (gnutls_hash_hd_t * dig, gnutls_digest_algorithm_t algorithm) return _gnutls_hash_init(((digest_hd_st*)*dig), algorithm); } +/** + * gnutls_hash - hashes the given data + * @handle: is a #gnutls_cipher_hd_t structure. + * @text: the data to hash + * @textlen: The length of data to hash + * + * This function will hash the given data using the algorithm + * specified by the context. + * + * Returns: Zero or a negative value on error. + **/ int gnutls_hash (gnutls_hash_hd_t handle, const void *text, size_t textlen) { return _gnutls_hash((digest_hd_st*)handle, text, textlen); } -void -gnutls_hash_output (gnutls_hash_hd_t handle, void *digest) +/** + * gnutls_hash_output - Outputs the current hash value + * @handle: is a #gnutls_hash_hd_t structure. + * @digest: is the output value of the hash + * + * This function will output the current hash value. + * + * Returns: This function has no return value. + **/ +void gnutls_hash_output (gnutls_hash_hd_t handle, void *digest) { return _gnutls_hash_output((digest_hd_st*)handle, digest); } +/** + * gnutls_hash_deinit - deinitializes resources by a context + * @handle: is a #gnutls_hash_hd_t structure. + * @digest: is the output value of the hash + * + * This function will deinitialize all resources occupied by + * the given hash context. + * + * Returns: This function has no return value. + **/ void gnutls_hash_deinit (gnutls_hash_hd_t handle, void *digest) { _gnutls_hash_deinit((digest_hd_st*)handle, digest); } +/** + * gnutls_hash_get_len - returns the length of the output data + * @algorithm: the hash algorithm to use + * + * This function will return the length of the output data + * of the given hash algorithm. + * + * Returns: The length or zero on error. + * + **/ int gnutls_hash_get_len( gnutls_digest_algorithm_t algorithm) { return _gnutls_hash_get_algo_len(algorithm); } +/** + * gnutls_hash_fast - initializes an hash context + * @algorithm: the hash algorithm to use + * @text: the data to hash + * @textlen: The length of data to hash + * @digest: is the output value of the hash + * + * This convenience function will hash the given data and return output + * on a single call. + * + * Returns: Zero or a negative value on error. + **/ int gnutls_hash_fast (gnutls_digest_algorithm_t algorithm, const void *text, size_t textlen, void *digest) { diff --git a/lib/gnutls_cipher_int.c b/lib/gnutls_cipher_int.c index b496c688ff..a973973403 100644 --- a/lib/gnutls_cipher_int.c +++ b/lib/gnutls_cipher_int.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2000, 2004, 2005, 2008 Free Software Foundation + * Copyright (C) 2009, 2010 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -51,7 +51,7 @@ _gnutls_cipher_init (cipher_hd_st * handle, gnutls_cipher_algorithm_t cipher, handle->hd.rh.cc = cc; SR (cc->init (cipher, &handle->hd.rh.ctx), cc_cleanup); SR (cc->setkey (handle->hd.rh.ctx, key->data, key->size), cc_cleanup); - if (iv->data && iv->size && cc->setiv) + if (iv && iv->data && iv->size && cc->setiv) SR (cc->setiv (handle->hd.rh.ctx, iv->data, iv->size), cc_cleanup); return 0; } @@ -75,7 +75,7 @@ _gnutls_cipher_init (cipher_hd_st * handle, gnutls_cipher_algorithm_t cipher, return ret; } - if (iv->data != NULL && iv->size > 0) + if (iv && iv->data != NULL && iv->size > 0) _gnutls_cipher_ops.setiv (handle->hd.gc, iv->data, iv->size); return 0;