/*
- silchash.h
+ silchash.h
Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2002 Pekka Riikonen
+ Copyright (C) 1997 - 2008 Pekka Riikonen
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
#ifndef SILCHASH_H
#define SILCHASH_H
-/****h* silccrypt/SILC Hash Interface
+/****h* silccrypt/Hash Function Interface
*
* DESCRIPTION
*
- * This is the interface for hash functions which are used to create
- * message digests. The routines are used in various cryptographic
- * operations. SILC Hash Interface is used for example by the
- * SILC HMAC Interface (SilcHmac).
+ * This is the interface for hash functions which are used to create message
+ * digests. The routines are used in various cryptographic operations.
+ *
+ * EXAMPLE
+ *
+ * SilcHash sha1hash;
+ *
+ * // Allocate SHA-1 hash function
+ * silc_hash_alloc(SILC_HASH_SHA1, &sha1hash);
+ *
+ * // Hash some data
+ * unsigned char digest[SILC_HASH_MAXLEN];
+ *
+ * silc_hash_init(sha1hash);
+ * silc_hash_update(sha1hash, "foobar", 6);
+ * silc_hash_final(sha1hash, digest);
+ *
+ * // Same can be done in one call also
+ * silc_hash_make(sha1hash, "foobar", 6, digest);
+ *
+ * // Free hash
+ * silc_hash_free(sha1hash);
*
***/
-/****s* silccrypt/SilcHashAPI/SilcHash
+/****s* silccrypt/SilcHash
*
* NAME
- *
+ *
* typedef struct SilcHashStruct *SilcHash;
*
* DESCRIPTION
***/
typedef struct SilcHashStruct *SilcHash;
-/****s* silccrypt/SilcHashAPI/SilcHashObject
+/****d* silccrypt/Hashes
+ *
+ * NAME
+ *
+ * Hash functions
+ *
+ * DESCRIPTION
+ *
+ * Supported hash function names. These names can be given as argument
+ * to silc_hash_alloc.
+ *
+ * SOURCE
+ */
+#define SILC_HASH_SHA256 "sha256" /* SHA-256 */
+#define SILC_HASH_SHA512 "sha512" /* SHA-512 */
+#define SILC_HASH_SHA1 "sha1" /* SHA-1 */
+#define SILC_HASH_MD5 "md5" /* MD5 */
+/***/
+
+/****d* silccrypt/Hash-OIDs
+ *
+ * NAME
+ *
+ * Hash functions
+ *
+ * DESCRIPTION
+ *
+ * Supported hash function OIDs. These names can be given as argument
+ * to silc_hash_alloc_by_oid.
+ *
+ * SOURCE
+ */
+#define SILC_HASH_OID_SHA256 "2.16.840.1.101.3.4.2.1"
+#define SILC_HASH_OID_SHA512 "2.16.840.1.101.3.4.2.3"
+#define SILC_HASH_OID_SHA1 "1.3.14.3.2.26"
+#define SILC_HASH_OID_MD5 "1.2.840.113549.2.5"
+/***/
+
+/****d* silccrypt/SILC_HASH_MAXLEN
*
* NAME
- *
- * typedef struct { ... } SilcHashObject;
+ *
+ * #define SILC_HASH_MAXLEN 64
*
* DESCRIPTION
*
- * This structure represents one hash function. The hash function's
- * name, digest length and block length are defined in the structure.
- * This structure is then given as argument to the silc_hash_register.
- * That function is used to register all hash functions into SILC.
- * They can be then allocated by the name found in this structure by
- * calling the silc_hash_alloc.
+ * Maximum size of digest any algorithm supported by SILC Crypto Toolkit
+ * would produce. You can use this to define static digest buffers and
+ * safely use it with any hash function.
+ *
+ * EXAMPLE
+ *
+ * unsigned char digest[SILC_HASH_MAXLEN];
+ *
+ * silc_hash_make(hash, data, data_len, digest);
*
***/
+#define SILC_HASH_MAXLEN 64
+
+/* Hash implementation object */
typedef struct {
char *name;
- SilcUInt32 hash_len;
- SilcUInt32 block_len;
+ char *oid;
+ SilcUInt16 hash_len;
+ SilcUInt16 block_len;
void (*init)(void *);
void (*update)(void *, const unsigned char *, SilcUInt32);
void (*final)(void *, unsigned char *);
- void (*transform)(SilcUInt32 *, const unsigned char *);
+ void (*transform)(void *, const unsigned char *);
SilcUInt32 (*context_len)();
} SilcHashObject;
/* Default hash functions for silc_hash_register_default(). */
extern DLLAPI const SilcHashObject silc_default_hash[];
-/* Default HASH function in the SILC protocol */
-#define SILC_DEFAULT_HASH "sha1"
-
/* Macros */
/* Following macros are used to implement the SILC Hash API. These
macros should be used instead of declaring functions by hand. */
-/* Function names in SILC Hash modules. The name of the hash function
- is appended into these names and used to the get correct symbol out
- of the module. All SILC Hash API compliant modules has to support
- these names as function names (use macros below to assure this). */
-#define SILC_HASH_SIM_INIT "init"
-#define SILC_HASH_SIM_UPDATE "update"
-#define SILC_HASH_SIM_FINAL "final"
-#define SILC_HASH_SIM_TRANSFORM "transform"
-#define SILC_HASH_SIM_CONTEXT_LEN "context_len"
-
/* Macros that can be used to declare SILC Hash API functions. */
#define SILC_HASH_API_INIT(hash) \
void silc_##hash##_init(void *context)
#define SILC_HASH_API_FINAL(hash) \
void silc_##hash##_final(void *context, unsigned char *digest)
#define SILC_HASH_API_TRANSFORM(hash) \
-void silc_##hash##_transform(SilcUInt32 *state, const unsigned char *buffer)
+void silc_##hash##_transform(void *state, const unsigned char *buffer)
#define SILC_HASH_API_CONTEXT_LEN(hash) \
SilcUInt32 silc_##hash##_context_len()
/* Prototypes */
-/****f* silccrypt/SilcHashAPI/silc_hash_register
+/****f* silccrypt/silc_hash_register
*
* SYNOPSIS
*
- * bool silc_hash_register(const SilcHashObject *hash);
+ * SilcBool silc_hash_register(const SilcHashObject *hash);
*
* DESCRIPTION
*
- * Registers a new hash function into the SILC. This function is used
- * at the initialization of the SILC. All registered hash functions
- * should be unregistered with silc_hash_unregister. The `hash' includes
- * the name of the hash function, digest length and block length. Usually
- * this function is not called directly. Instead, application can call
- * the silc_hash_register_default to register all default hash functions
- * that are builtin the sources. Returns FALSE on error.
+ * Registers a new hash function into the SILC. This function can be
+ * used at the initialization. All registered hash functions should be
+ * unregistered with silc_hash_unregister. Returns FALSE on error.
+ * Usually this function is not needed. The default hash functions are
+ * automatically registered. This can be used to change the order of
+ * the registered hash functions by re-registering them in desired order,
+ * or add new hash functions.
*
***/
-bool silc_hash_register(const SilcHashObject *hash);
+SilcBool silc_hash_register(const SilcHashObject *hash);
-/****f* silccrypt/SilcHashAPI/silc_hash_unregister
+/****f* silccrypt/silc_hash_unregister
*
* SYNOPSIS
*
- * bool silc_hash_unregister(SilcHashObject *hash);
+ * SilcBool silc_hash_unregister(SilcHashObject *hash);
*
* DESCRIPTION
*
* Unregister a hash function from SILC by the SilcHashObject `hash'.
- * This should be called for all registered hash functions. Returns
- * FALSE on error.
+ * This should be called for all hash functions registered with
+ * silc_hash_register. Returns FALSE on error.
+ *
+ ***/
+SilcBool silc_hash_unregister(SilcHashObject *hash);
+
+/****f* silccrypt/silc_hash_register_default
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_hash_register_default(void);
+ *
+ * DESCRIPTION
+ *
+ * Registers all default hash functions into the SILC. Application
+ * need not call this directly. By calling silc_crypto_init this function
+ * is called.
*
***/
-bool silc_hash_unregister(SilcHashObject *hash);
+SilcBool silc_hash_register_default(void);
-/****f* silccrypt/SilcHashAPI/silc_hash_register_default
+/****f* silccrypt/silc_hash_unregister_all
*
* SYNOPSIS
*
- * bool silc_hash_register_default(void);
+ * SilcBool silc_hash_unregister_all(void);
*
* DESCRIPTION
*
- * Registers all default hash functions into the SILC. These are the
- * hash functions that are builtin in the sources. See the list of
- * default hash functions in the silchash.c source file. The application
- * may use this to register default hash functions if specific hash
- * function in any specific order is not wanted (application's
- * configuration usually may decide the order of the registration, in
- * which case this function should not be used).
+ * Unregisters all registered hash functions. Application need not
+ * call this directly. By calling silc_crypto_uninit this function is
+ * called.
*
***/
-bool silc_hash_register_default(void);
+SilcBool silc_hash_unregister_all(void);
-/****f* silccrypt/SilcHashAPI/silc_hash_alloc
+/****f* silccrypt/silc_hash_alloc
*
* SYNOPSIS
*
- * bool silc_hash_alloc(const unsigned char *name, SilcHash *new_hash);
+ * SilcBool silc_hash_alloc(const char *name, SilcHash *new_hash);
*
* DESCRIPTION
*
* hash function is returned into `new_hash' pointer. This function
* returns FALSE if such hash function does not exist.
*
+ * See Hashes for supported hash functions.
+ *
***/
-bool silc_hash_alloc(const unsigned char *name, SilcHash *new_hash);
+SilcBool silc_hash_alloc(const char *name, SilcHash *new_hash);
-/****f* silccrypt/SilcHashAPI/silc_hash_free
+/****f* silccrypt/silc_hash_alloc_by_oid
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_hash_alloc_by_oid(const char *oid, SilcHash *new_hash);
+ *
+ * DESCRIPTION
+ *
+ * Same as silc_hash_alloc but allocates the hash algorithm by the
+ * hash algorithm OID string indicated by `oid'. Returns FALSE if such
+ * hash function does not exist.
+ *
+ * See Hash-OIDs for supported hash function OIDs.
+ *
+ ***/
+SilcBool silc_hash_alloc_by_oid(const char *oid, SilcHash *new_hash);
+
+/****f* silccrypt/silc_hash_free
*
* SYNOPSIS
*
***/
void silc_hash_free(SilcHash hash);
-/****f* silccrypt/SilcHashAPI/silc_hash_is_supported
+/****f* silccrypt/silc_hash_is_supported
*
* SYNOPSIS
*
- * bool silc_hash_is_supported(const unsigned char *name);
+ * SilcBool silc_hash_is_supported(const char *name);
*
* DESCRIPTION
*
* Returns TRUE if the hash function indicated by the `name' exists.
*
***/
-bool silc_hash_is_supported(const unsigned char *name);
+SilcBool silc_hash_is_supported(const char *name);
-/****f* silccrypt/SilcHashAPI/silc_hash_get_supported
+/****f* silccrypt/silc_hash_get_supported
*
* SYNOPSIS
*
***/
char *silc_hash_get_supported(void);
-/****f* silccrypt/SilcHashAPI/silc_hash_len
+/****f* silccrypt/silc_hash_len
*
* SYNOPSIS
*
***/
SilcUInt32 silc_hash_len(SilcHash hash);
-/****f* silccrypt/SilcHashAPI/silc_hash_block_len
+/****f* silccrypt/silc_hash_block_len
*
* SYNOPSIS
*
***/
SilcUInt32 silc_hash_block_len(SilcHash hash);
-/****f* silccrypt/SilcHashAPI/silc_hash_get_name
+/****f* silccrypt/silc_hash_get_name
*
* SYNOPSIS
*
***/
const char *silc_hash_get_name(SilcHash hash);
-/****f* silccrypt/SilcHashAPI/silc_hash_make
+/****f* silccrypt/silc_hash_get_oid
+ *
+ * SYNOPSIS
+ *
+ * const char *silc_hash_get_name(SilcHash hash);
+ *
+ * DESCRIPTION
+ *
+ * Returns the hash OID string. Returns NULL if the hash doesn't have
+ * OID string. Use strlen() to get the OID string length.
+ *
+ ***/
+const char *silc_hash_get_oid(SilcHash hash);
+
+/****f* silccrypt/silc_hash_make
*
* SYNOPSIS
*
void silc_hash_make(SilcHash hash, const unsigned char *data,
SilcUInt32 len, unsigned char *return_hash);
-/****f* silccrypt/SilcHashAPI/silc_hash_init
+/****f* silccrypt/silc_hash_init
*
* SYNOPSIS
*
* put them into a buffer and compute the digest from the buffer by
* calling the silc_hash_make, or you can use the silc_hash_init,
* silc_hash_update and silc_hash_final to do the digest. This function
- * prepares the allocated hash function context for this kind of digest
+ * prepares the allocated hash function context for this kind of digest
* computation. To add the data to be used in the digest computation
* call the silc_hash_update function.
*
***/
void silc_hash_init(SilcHash hash);
-/****f* silccrypt/SilcHashAPI/silc_hash_update
+/****f* silccrypt/silc_hash_update
*
* SYNOPSIS
*
void silc_hash_update(SilcHash hash, const unsigned char *data,
SilcUInt32 data_len);
-/****f* silccrypt/SilcHashAPI/silc_hash_final
+/****f* silccrypt/silc_hash_final
*
* SYNOPSIS
*
***/
void silc_hash_final(SilcHash hash, unsigned char *return_hash);
-/****f* silccrypt/SilcHashAPI/silc_hash_transform
+/****f* silccrypt/silc_hash_transform
*
* SYNOPSIS
*
- * void silc_hash_transform(SilcHash hash, SilcUInt32 *state,
+ * void silc_hash_transform(SilcHash hash, void *state,
* const unsigned char *data);
*
* DESCRIPTION
* known by the caller. Usually this function is not needed.
*
***/
-void silc_hash_transform(SilcHash hash, SilcUInt32 *state,
+void silc_hash_transform(SilcHash hash, void *state,
const unsigned char *data);
-/****f* silccrypt/SilcHashAPI/silc_hash_fingerprint
+/****f* silccrypt/silc_hash_fingerprint
*
* SYNOPSIS
*
char *silc_hash_fingerprint(SilcHash hash, const unsigned char *data,
SilcUInt32 data_len);
-/****f* silccrypt/SilcHashAPI/silc_hash_babbleprint
+/****f* silccrypt/silc_hash_babbleprint
*
* SYNOPSIS
*
projects / crypto.git / blobdiff