merged the modularization branch (credentials) back to trunk

src/libstrongswan/crypto/hashers/hasher.h

@@ -1,10 +1,3 @@
-/**
- * @file hasher.h
- * 
- * @brief Interface hasher_t.
- * 
- */
-
 /*
  * Copyright (C) 2005 Jan Hutter
  * Copyright (C) 2005-2006 Martin Willi
@@ -21,7 +14,12 @@
  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * for more details.
  *
- * RCSID $Id$
+ * $Id$
+ */
+ 
+/**
+ * @defgroup traffic_selector traffic_selector
+ * @{ @ingroup config
  */
 
 #ifndef HASHER_H_
@@ -33,30 +31,21 @@ typedef struct hasher_t hasher_t;
 #include <library.h>
 
 /**
- * @brief Algorithms to use for hashing.
- *
- * Currently only the following algorithms are implemented:
- * - HASH_MD5
- * - HASH_SHA1
- * - HASH_SHA256
- * - HASH_SHA384
- * - HASH_SHA512
- *
- * @ingroup hashers
+ * Algorithms to use for hashing.
  */
 enum hash_algorithm_t {
-	HASH_UNKNOWN = 0,
-	HASH_MD2 =     1,
-	/** Implemented in class md5_hasher_t */
-	HASH_MD5 =     2,
-	/** Implemented in class sha1_hasher_t */
-	HASH_SHA1 =    3,
-	/** Implemented in class sha2_hasher_t */
-	HASH_SHA256 =  4,
-	/** Implemented in class sha2_hasher_t */
-	HASH_SHA384 =  5,
-	/** Implemented in class sha2_hasher_t */
-	HASH_SHA512 =  6,
+	/** not specified hash function */
+	HASH_UNKNOWN 		= 0,
+	/** preferred hash function, general purpose */
+	HASH_PREFERRED	 	= 1,
+	HASH_MD2 			= 2,
+	HASH_MD5 			= 3,
+	HASH_SHA1 			= 4,
+	/** special SHA1 which does not run SHA1Final, but copies the state */
+	HASH_SHA1_NOFINAL	= 5,
+	HASH_SHA256 		= 6,
+	HASH_SHA384 		= 7,
+	HASH_SHA512 		= 8,
 };
 
 #define HASH_SIZE_MD2		16
@@ -65,7 +54,6 @@ enum hash_algorithm_t {
 #define HASH_SIZE_SHA256	32
 #define HASH_SIZE_SHA384	48
 #define HASH_SIZE_SHA512	64
-#define HASH_SIZE_MAX		64
 
 /**
  * enum names for hash_algorithm_t.
@@ -73,16 +61,11 @@ enum hash_algorithm_t {
 extern enum_name_t *hash_algorithm_names;
 
 /**
- * @brief Generic interface for all hash functions.
- * 
- * @b Constructors:
- *  - hasher_create()
- * 
- * @ingroup hashers
+ * Generic interface for all hash functions.
  */
 struct hasher_t {
 	/**
-	 * @brief Hash data and write it in the buffer.
+	 * Hash data and write it in the buffer.
 	 * 
 	 * If the parameter hash is NULL, no result is written back
 	 * and more data can be appended to already hashed data.
@@ -91,108 +74,63 @@ struct hasher_t {
 	 * The hash output parameter must hold at least
 	 * hash_t.get_block_size() bytes.
 	 * 
-	 * @param this			calling object
-	 * @param data			data to hash
-	 * @param[out] hash		pointer where the hash will be written
+	 * @param data		data to hash
+	 * @param hash		pointer where the hash will be written
 	 */
 	void (*get_hash) (hasher_t *this, chunk_t data, u_int8_t *hash);
 	
 	/**
-	 * @brief Hash data and allocate space for the hash.
+	 * Hash data and allocate space for the hash.
 	 * 
 	 * If the parameter hash is NULL, no result is written back
 	 * and more data can be appended to already hashed data.
 	 * If not, the result is written back and the hasher is reset.
 	 * 
-	 * @param this			calling object
-	 * @param data			chunk with data to hash
-	 * @param[out] hash		chunk which will hold allocated hash
+	 * @param data		chunk with data to hash
+	 * @param hash		chunk which will hold allocated hash
 	 */
 	void (*allocate_hash) (hasher_t *this, chunk_t data, chunk_t *hash);
 	
 	/**
-	 * @brief Get the size of the resulting hash.
+	 * Get the size of the resulting hash.
 	 * 
-	 * @param this			calling object
-	 * @return				hash size in bytes
+	 * @return			hash size in bytes
 	 */
 	size_t (*get_hash_size) (hasher_t *this);
 	
 	/**
-	 * @brief Resets the hashers state.
-	 * 
-	 * @param this			calling object
+	 * Resets the hashers state.
 	 */
 	void (*reset) (hasher_t *this);
 	
 	/**
-	 * @brief Get the state of the hasher.
-	 *
-	 * A hasher stores internal state information. This state may be
-	 * manipulated to include a "seed" into the hashing operation. It used by
-	 * some exotic protocols (such as AKA).
-	 * The data pointed by chunk may be manipulated, but not replaced nor freed.
-	 * This is more a hack than a feature. The hasher's state may be byte
-	 * order dependant; use with care.
-	 *
-	 * @param this			calling object
-	 */
-	chunk_t (*get_state) (hasher_t *this);
-	
-	/**
-	 * @brief Destroys a hasher object.
-	 *
-	 * @param this 			calling object
+	 * Destroys a hasher object.
 	 */
 	void (*destroy) (hasher_t *this);
 };
 
 /**
- * @brief Generic interface to create a hasher_t.
+ * Conversion of ASN.1 OID to hash algorithm.
  * 
- * @param hash_algorithm	Algorithm to use for hashing
- * @return
- * 							- hasher_t object
- * 							- NULL if algorithm not supported
- * 
- * @ingroup hashers
- */
-hasher_t *hasher_create(hash_algorithm_t hash_algorithm);
-
-/**
- * @brief Conversion of ASN.1 OID to hash algorithm.
- * 
- * @param oid				ASN.1 OID
- * @return
- * 							- hash algorithm
- * 							- HASH_UNKNOWN if OID unsuported
- * 
- * @ingroup hashers
+ * @param oid			ASN.1 OID
+ * @return				hash algorithm, HASH_UNKNOWN if OID unsuported
  */
 hash_algorithm_t hasher_algorithm_from_oid(int oid);
 
 /**
- * @brief Conversion of hash algorithm into ASN.1 OID.
+ * Conversion of hash algorithm into ASN.1 OID.
  * 
- * @param alg				hash algorithm
- * @return
- * 							- ASN.1 hash OID if known hash algorithm
- * 							- OID_UNKNOW
- * 
- * @ingroup hashers
+ * @param alg			hash algorithm
+ * @return				ASN.1 OID, or OID_UNKNOW
  */
 int hasher_algorithm_to_oid(hash_algorithm_t alg);
 
 /**
- * @brief Conversion of hash signature algorithm into ASN.1 OID.
+ * Conversion of hash signature algorithm into ASN.1 OID.
  * 
- * @param alg				hash algorithm
- * @return
- * 							- ASN.1 signature OID if known hash algorithm
- * 							- OID_UNKNOW
- * 
- * @ingroup hashers
+ * @param alg			hash algorithm
+ * @return				ASN.1 OID if, or OID_UNKNOW
  */
 int hasher_signature_algorithm_to_oid(hash_algorithm_t alg);
 
-#endif /* HASHER_H_ */
+#endif /* HASHER_H_ @} */