/* silchash.h Author: 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 the Free Software Foundation; version 2 of the License. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. */ #ifndef SILCHASH_H #define SILCHASH_H /****h* silccrypt/SILC Hash 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). * ***/ /****s* silccrypt/SilcHash * * NAME * * typedef struct SilcHashStruct *SilcHash; * * DESCRIPTION * * This context is the actual hash function context and is allocated * by silc_hash_alloc and given as argument usually to all * silc_hash_* functions. It is freed by the silc_hash_free * function. * ***/ typedef struct SilcHashStruct *SilcHash; /****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 */ /***/ /* Hash implementation object */ typedef struct { char *name; 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)(void *, const unsigned char *); SilcUInt32 (*context_len)(); } SilcHashObject; /* Marks for all hash functions. This can be used in silc_hash_unregister to unregister all hash function at once. */ #define SILC_ALL_HASH_FUNCTIONS ((SilcHashObject *)1) /* Default hash functions for silc_hash_register_default(). */ extern DLLAPI const SilcHashObject silc_default_hash[]; /* Max hash length */ #define SILC_HASH_MAXLEN 64 /* Macros */ /* Following macros are used to implement the SILC Hash API. These macros should be used instead of declaring functions by hand. */ /* 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_UPDATE(hash) \ void silc_##hash##_update(void *context, const unsigned char *data, \ SilcUInt32 len) #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(void *state, const unsigned char *buffer) #define SILC_HASH_API_CONTEXT_LEN(hash) \ SilcUInt32 silc_##hash##_context_len() /* Prototypes */ /****f* silccrypt/silc_hash_register * * SYNOPSIS * * SilcBool silc_hash_register(const SilcHashObject *hash); * * DESCRIPTION * * 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. * ***/ SilcBool silc_hash_register(const SilcHashObject *hash); /****f* silccrypt/silc_hash_unregister * * SYNOPSIS * * SilcBool silc_hash_unregister(SilcHashObject *hash); * * DESCRIPTION * * Unregister a hash function from SILC by the SilcHashObject `hash'. * 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. * ***/ SilcBool silc_hash_register_default(void); /****f* silccrypt/silc_hash_unregister_all * * SYNOPSIS * * SilcBool silc_hash_unregister_all(void); * * DESCRIPTION * * Unregisters all registered hash functions. Application need not * call this directly. By calling silc_crypto_uninit this function is * called. * ***/ SilcBool silc_hash_unregister_all(void); /****f* silccrypt/silc_hash_alloc * * SYNOPSIS * * SilcBool silc_hash_alloc(const char *name, SilcHash *new_hash); * * DESCRIPTION * * Allocates a new SilcHash object of name of `name'. The new allocated * hash function is returned into `new_hash' pointer. This function * returns FALSE if such hash function does not exist. * ***/ SilcBool silc_hash_alloc(const char *name, SilcHash *new_hash); /****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. * ***/ SilcBool silc_hash_alloc_by_oid(const char *oid, SilcHash *new_hash); /****f* silccrypt/silc_hash_free * * SYNOPSIS * * void silc_hash_free(SilcHash hash); * * DESCRIPTION * * Frees the allocated hash function context. * ***/ void silc_hash_free(SilcHash hash); /****f* silccrypt/silc_hash_is_supported * * SYNOPSIS * * SilcBool silc_hash_is_supported(const char *name); * * DESCRIPTION * * Returns TRUE if the hash function indicated by the `name' exists. * ***/ SilcBool silc_hash_is_supported(const char *name); /****f* silccrypt/silc_hash_get_supported * * SYNOPSIS * * char *silc_hash_get_supported(void); * * DESCRIPTION * * Returns comma (`,') separated list of registered hash functions This * is used for example when sending supported hash function list during * the SILC Key Exchange protocol (SKE). The caller must free the returned * pointer. * ***/ char *silc_hash_get_supported(void); /****f* silccrypt/silc_hash_len * * SYNOPSIS * * SilcUInt32 silc_hash_len(SilcHash hash); * * DESCRIPTION * * Returns the length of the message digest the hash function produce. * ***/ SilcUInt32 silc_hash_len(SilcHash hash); /****f* silccrypt/silc_hash_block_len * * SYNOPSIS * * SilcUInt32 silc_hash_block_len(SilcHash hash); * * DESCRIPTION * * Returns the block length of the hash function. * ***/ SilcUInt32 silc_hash_block_len(SilcHash hash); /****f* silccrypt/silc_hash_get_name * * SYNOPSIS * * const char *silc_hash_get_name(SilcHash hash); * * DESCRIPTION * * Returns the name of the hash function indicated by the `hash' context. * ***/ const char *silc_hash_get_name(SilcHash hash); /****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); * * DESCRIPTION * * Computes the message digest (hash) out of the data indicated by * `data' of length of `len' bytes. Returns the message digest to the * `return_hash' buffer which must be at least of the size of the * message digest the `hash' produces. * ***/ void silc_hash_make(SilcHash hash, const unsigned char *data, SilcUInt32 len, unsigned char *return_hash); /****f* silccrypt/silc_hash_init * * SYNOPSIS * * void silc_hash_init(SilcHash hash); * * DESCRIPTION * * Sometimes calling the silc_hash_make might not be the most optimal * case of computing digests. If you have a lot of different data * that you need to put together for computing a digest you may either * 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 * 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/silc_hash_update * * SYNOPSIS * * void silc_hash_update(SilcHash hash, const unsigned char *data, * SilcUInt32 data_len); * * DESCRIPTION * * This function may be called to add data to be used in the digest * computation. This can be called multiple times to add data from * many sources before actually computing the digest. Once you've * added all the data you need you can call the silc_hash_final to * actually produce the message digest value. * * EXAMPLE * * unsigned char digest[20]; * * silc_hash_init(hash); * silc_hash_update(hash, data, data_len); * silc_hash_update(hash, more_data, more_data_len); * silc_hash_final(hash, digest); * ***/ void silc_hash_update(SilcHash hash, const unsigned char *data, SilcUInt32 data_len); /****f* silccrypt/silc_hash_final * * SYNOPSIS * * void silc_hash_final(SilcHash hash, unsigned char *return_hash); * * DESCRIPTION * * This function is used to produce the final message digest from * the data that has been added to the hash function context by calling * the silc_hash_update function. The digest is copied in to the * `return_hash' pointer which must be at least the size that * the silc_hash_len returns. * ***/ void silc_hash_final(SilcHash hash, unsigned char *return_hash); /****f* silccrypt/silc_hash_transform * * SYNOPSIS * * void silc_hash_transform(SilcHash hash, void *state, * const unsigned char *data); * * DESCRIPTION * * This is special function for calling the hash function's internal * digest generation function. The size of the `state' array and the * sizeof the `data' buffer is hash function specific and must be * known by the caller. Usually this function is not needed. * ***/ void silc_hash_transform(SilcHash hash, void *state, const unsigned char *data); /****f* silccrypt/silc_hash_fingerprint * * SYNOPSIS * * char *silc_hash_fingerprint(SilcHash hash, const unsigned char *data, * SilcUInt32 data_len); * * DESCRIPTION * * Utility function which can be used to create a textual fingerprint * out of the data indicated by `data' of length of `data_len' bytes. * If `hash' is NULL then SHA1 hash function is used automatically. * The caller must free the returned string. * * Example output could be: * 41BF 5C2E 4149 039A 3917 831F 65C4 0A69 F98B 0A4D * ***/ char *silc_hash_fingerprint(SilcHash hash, const unsigned char *data, SilcUInt32 data_len); /****f* silccrypt/silc_hash_babbleprint * * SYNOPSIS * * char *silc_hash_babbleprint(SilcHash hash, const unsigned char *data, * SilcUInt32 data_len); * * DESCRIPTION * * Utility function which can be used to create a textual babbleprint * out of the data indicated by `data' of length of `data_len' bytes. * If `hash' is NULL then SHA1 hash function is used automatically. * The caller must free the returned string. * * The babbleprint is same as fingerprint but encoded in a form which * makes it easier to pronounce. When verifying fingerprint for example * over a phone call, the babbleprint makes it easier to read the * fingerprint. * * Example output could be: * xiber-zulad-vubug-noban-puvyc-labac-zonos-gedik-novem-rudog-tyxix * ***/ char *silc_hash_babbleprint(SilcHash hash, const unsigned char *data, SilcUInt32 data_len); #endif