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 8eb4179df97e97da2d03cb562e520fd29c24e70c..b1ffd3cc53d2611f8e13a3778824ae82b1cf9610 100644 (file)
--- a/lib/crypto-api.c
+++ b/lib/crypto-api.c
@@ -29,6 +29,20 @@
 #include <gnutls/crypto.h>
 #include <crypto.h>
 
+/**
+  * 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 b496c688ffdf1b2bda7e3512bb18d4567e7dc8e9..a97397340336cd5d810606e9183d6e6d882651a1 100644 (file)
--- 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;