+++ /dev/null
-/*
-
- silchmac.h
-
- Author: Pekka Riikonen <priikone@silcnet.org>
-
- Copyright (C) 1999 - 2006 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 SILCHMAC_H
-#define SILCHMAC_H
-
-/****h* silccrypt/SILC HMAC Interface
- *
- * DESCRIPTION
- *
- * This is the interface for HMAC, or the keyed hash values, that are
- * used for packet and message authentication. These routines uses
- * already implemented hash functions from the SilcHashAPI. These
- * routines were created according to RFC 2104.
- *
- ***/
-
-/****s* silccrypt/SilcHMACAPI/SilcHmac
- *
- * NAME
- *
- * typedef struct SilcHmacStruct *SilcHmac;
- *
- * DESCRIPTION
- *
- * This context is the actual HMAC context and is allocated
- * by silc_hmac_alloc and given as argument usually to all
- * silc_hmac_* functions. It is freed by the silc_hmac_free
- * function.
- *
- ***/
-typedef struct SilcHmacStruct *SilcHmac;
-
-/****s* silccrypt/SilcHMACAPI/SilcHmacObject
- *
- * NAME
- *
- * typedef struct { ... } SilcHmacObject;
- *
- * DESCRIPTION
- *
- * This structure represents one HMAC. The HMAC's name and the
- * MAC length is defined in the structure. This structure is
- * then given as argument to the silc_hmac_register. That function
- * is used to register all HMACs into SILC. They can be then
- * allocated by the name found in this structure by calling the
- * silc_hmac_alloc.
- *
- ***/
-typedef struct {
- char *name;
- SilcUInt32 len;
-} SilcHmacObject;
-
-/* Marks for all hmacs. This can be used in silc_hmac_unregister
- to unregister all hmacs at once. */
-#define SILC_ALL_HMACS ((SilcHmacObject *)1)
-
-/* Default hmacs for silc_hmac_register_default(). */
-extern DLLAPI const SilcHmacObject silc_default_hmacs[];
-
-/* Default HMAC in the SILC protocol */
-#define SILC_DEFAULT_HMAC "hmac-sha1-96"
-
-/* Prototypes */
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_register
- *
- * SYNOPSIS
- *
- * SilcBool silc_hmac_register(const SilcHmacObject *hmac);
- *
- * DESCRIPTION
- *
- * Registers a new HMAC into the SILC. This function is used at the
- * initialization of the SILC. All registered HMACs should be
- * unregistered with silc_hmac_unregister. The `hmac' includes the
- * name of the HMAC and the length of the MAC. Usually this
- * function is not called directly. Instead, application can call
- * the silc_hmac_register_default to register all default HMACs
- * that are builtin the sources. Returns FALSE on error.
- *
- ***/
-SilcBool silc_hmac_register(const SilcHmacObject *hmac);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_unregister
- *
- * SYNOPSIS
- *
- * SilcBool silc_hmac_unregister(SilcHmacObject *hmac);
- *
- * DESCRIPTION
- *
- * Unregister a HMAC from SILC by the HMAC structure `hmac'. This
- * should be called for all registered HMAC's. Returns FALSE on
- * error.
- *
- ***/
-SilcBool silc_hmac_unregister(SilcHmacObject *hmac);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_register_default
- *
- * SYNOPSIS
- *
- * SilcBool silc_hmac_register_default(void);
- *
- * DESCRIPTION
- *
- * Registers all default HMACs into the SILC. These are the HMACs
- * that are builtin in the sources. See the list of default HMACs
- * in the silchmac.c source file. The application may use this
- * to register default HMACs if specific HMAC in any specific order
- * is not wanted (application's configuration usually may decide
- * the order of the registration, in which case this should not be
- * used).
- *
- ***/
-SilcBool silc_hmac_register_default(void);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_unregister_all
- *
- * SYNOPSIS
- *
- * SilcBool silc_hmac_unregister_all(void);
- *
- * DESCRIPTION
- *
- * Unregisters all registered HMACs.
- *
- ***/
-SilcBool silc_hmac_unregister_all(void);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_alloc
- *
- * SYNOPSIS
- *
- * SilcBool silc_hmac_alloc(const char *name, SilcHash hash,
- * SilcHmac *new_hmac);
- *
- * DESCRIPTION
- *
- * Allocates a new SilcHmac object of name of `name'. The `hash' may
- * be provided as argument. If provided it is used as the hash function
- * of the HMAC. If it is NULL then the hash function is allocated and
- * the name of the hash algorithm is derived from the `name'. Returns
- * FALSE if such HMAC does not exist.
- *
- ***/
-SilcBool silc_hmac_alloc(const char *name, SilcHash hash, SilcHmac *new_hmac);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_free
- *
- * SYNOPSIS
- *
- * void silc_hmac_free(SilcHmac hmac);
- *
- * DESCRIPTION
- *
- * Frees the allocated HMAC context. The key that may have been set
- * with the silc_hmac_set_key is also destroyed.
- *
- ***/
-void silc_hmac_free(SilcHmac hmac);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_is_supported
- *
- * SYNOPSIS
- *
- * SilcBool silc_hmac_is_supported(const char *name);
- *
- * DESCRIPTION
- *
- * Returns TRUE if the HMAC indicated by the `name' exists.
- *
- ***/
-SilcBool silc_hmac_is_supported(const char *name);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_get_supported
- *
- * SYNOPSIS
- *
- * char *silc_hmac_get_supported(void);
- *
- * DESCRIPTION
- *
- * Returns comma (`,') separated list of registered HMACs. This is
- * used for example when sending supported HMAC list during the SILC
- * Key Exchange protocol (SKE). The caller must free the returned
- * pointer.
- *
- ***/
-char *silc_hmac_get_supported(void);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_len
- *
- * SYNOPSIS
- *
- * SilcUInt32 silc_hmac_len(SilcHmac hmac);
- *
- * DESCRIPTION
- *
- * Returns the length of the MAC that the HMAC will produce.
- *
- ***/
-SilcUInt32 silc_hmac_len(SilcHmac hmac);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_get_hash
- *
- * SYNOPSIS
- *
- * SilcHash silc_hmac_get_hash(SilcHmac hmac);
- *
- * DESCRIPTION
- *
- * Returns the SilcHash context that has been associated with the
- * HMAC context. The caller must not free the returned context.
- *
- ***/
-SilcHash silc_hmac_get_hash(SilcHmac hmac);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_get_name
- *
- * SYNOPSIS
- *
- * const char *silc_hmac_get_name(SilcHmac hmac);
- *
- * DESCRIPTION
- *
- * Returns the name of the HMAC context.
- *
- ***/
-const char *silc_hmac_get_name(SilcHmac hmac);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_set_key
- *
- * SYNOPSIS
- *
- * void silc_hmac_set_key(SilcHmac hmac, const unsigned char *key,
- * SilcUInt32 key_len);
- *
- * DESCRIPTION
- *
- * Sets the key to be used in the HMAC operation. This must be set
- * before calling silc_hmac_make or silc_hmac_final functions. If
- * you do not want to set the key you can still produce a MAC by
- * calling the silc_hmac_make_with_key where you give the key as
- * argument. Usually application still wants to set the key.
- *
- ***/
-void silc_hmac_set_key(SilcHmac hmac, const unsigned char *key,
- SilcUInt32 key_len);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_get_key
- *
- * SYNOPSIS
- *
- * const unsigned char *
- * silc_hmac_get_key(SilcHmac hmac, SilcUInt32 *key_len);
- *
- * DESCRIPTION
- *
- * Returns the key data from the `hmac' set with silc_hamc_set_key.
- * The caller must not free the returned pointer.
- *
- ***/
-const unsigned char *silc_hmac_get_key(SilcHmac hmac, SilcUInt32 *key_len);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_make
- *
- * SYNOPSIS
- *
- * void silc_hmac_make(SilcHmac hmac, unsigned char *data,
- * SilcUInt32 data_len, unsigned char *return_hash,
- * SilcUInt32 *return_len);
- *
- * DESCRIPTION
- *
- * Computes a MAC from a data buffer indicated by the `data' of the
- * length of `data_len'. The returned MAC is copied into the
- * `return_hash' pointer which must be at least the size of the
- * value silc_hmac_len returns. The returned length is still
- * returned to `return_len'.
- *
- ***/
-void silc_hmac_make(SilcHmac hmac, unsigned char *data,
- SilcUInt32 data_len, unsigned char *return_hash,
- SilcUInt32 *return_len);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_make_with_key
- *
- * SYNOPSIS
- *
- * void silc_hmac_make_with_key(SilcHmac hmac, unsigned char *data,
- * SilcUInt32 data_len,
- * unsigned char *key, SilcUInt32 key_len,
- * unsigned char *return_hash,
- * SilcUInt32 *return_len);
- *
- * DESCRIPTION
- *
- * Same as the silc_hmac_make but takes the key for the HMAC as
- * argument. If this is used the key that may have been set by calling
- * silc_hmac_set_key is ignored.
- *
- ***/
-void silc_hmac_make_with_key(SilcHmac hmac, unsigned char *data,
- SilcUInt32 data_len,
- unsigned char *key, SilcUInt32 key_len,
- unsigned char *return_hash,
- SilcUInt32 *return_len);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_make_truncated
- *
- * SYNOPSIS
- *
- * void silc_hmac_make_truncated(SilcHmac hmac,
- * unsigned char *data,
- * SilcUInt32 data_len,
- * SilcUInt32 truncated_len,
- * unsigned char *return_hash);
- *
- * DESCRIPTION
- *
- * Same as the silc_hmac_make except that the returned MAC is
- * truncated to the length indicated by the `truncated_len'. Some
- * special applications may need this function. The `return_hash'
- * must be at least the size of `truncated_len'.
- *
- * NOTES
- *
- * For security reasons, one should not truncate to less than half
- * of the length of the true MAC lenght. However, since this routine
- * may be used to non-critical applications this allows these dangerous
- * truncations.
- *
- ***/
-void silc_hmac_make_truncated(SilcHmac hmac,
- unsigned char *data,
- SilcUInt32 data_len,
- SilcUInt32 truncated_len,
- unsigned char *return_hash);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_init
- *
- * SYNOPSIS
- *
- * void silc_hmac_init(SilcHmac hmac);
- *
- * DESCRIPTION
- *
- * Sometimes calling the silc_hmac_make might not be the most
- * optimal case of doing MACs. If you have a lot of different data
- * that you need to put together for computing a MAC you may either
- * put them into a buffer and compute the MAC from the buffer by
- * calling the silc_hmac_make, or you can use the silc_hmac_init,
- * silc_hmac_update and silc_hmac_final to do the MAC. This function
- * prepares the allocated HMAC context for this kind of MAC
- * computation. The caller must have been called the function
- * silc_hmac_set_key before calling this function. To add the
- * data to be used in the MAC computation call the silc_hmac_update
- * function.
- *
- ***/
-void silc_hmac_init(SilcHmac hmac);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_init_with_key
- *
- * SYNOPSIS
- *
- * void silc_hmac_init_with_key(SilcHmac hmac, const unsigned char *key,
- * SilcUInt32 key_len);
- *
- * DESCRIPTION
- *
- * Same as silc_hmac_init but initializes with specific key. The
- * key that may have been set with silc_hmac_set_key is ignored.
- *
- ***/
-void silc_hmac_init_with_key(SilcHmac hmac, const unsigned char *key,
- SilcUInt32 key_len);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_update
- *
- * SYNOPSIS
- *
- * void silc_hmac_update(SilcHmac hmac, const unsigned char *data,
- * SilcUInt32 data_len);
- *
- * DESCRIPTION
- *
- * This function may be called to add data to be used in the MAC
- * computation. This can be called multiple times to add data from
- * many sources before actually performing the HMAC. Once you've
- * added all the data you need you can call the silc_hmac_final to
- * actually produce the MAC.
- *
- * EXAMPLE
- *
- * unsigned char mac[20];
- * SilcUInt32 mac_len;
- *
- * silc_hmac_init(hmac);
- * silc_hmac_update(hmac, data, data_len);
- * silc_hmac_update(hmac, more_data, more_data_len);
- * silc_hmac_final(hmac, mac, &mac_len);
- *
- ***/
-void silc_hmac_update(SilcHmac hmac, const unsigned char *data,
- SilcUInt32 data_len);
-
-/****f* silccrypt/SilcHMACAPI/silc_hmac_final
- *
- * SYNOPSIS
- *
- * void silc_hmac_final(SilcHmac hmac, unsigned char *return_hash,
- * SilcUInt32 *return_len);
- *
- * DESCRIPTION
- *
- * This function is used to produce the final MAC from the data
- * that has been added to the HMAC context by calling the
- * silc_hmac_update function. The MAC is copied in to the
- * `return_hash' pointer which must be at least the size that
- * the silc_hmac_len returns. The length of the MAC is still
- * returned into `return_len'.
- *
- ***/
-void silc_hmac_final(SilcHmac hmac, unsigned char *return_hash,
- SilcUInt32 *return_len);
-
-#endif
projects / crypto.git / blobdiff