X-Git-Url: http://git.silcnet.org/gitweb/?p=crypto.git;a=blobdiff_plain;f=lib%2Fsilccrypt%2Fsilcmac.h;fp=lib%2Fsilccrypt%2Fsilcmac.h;h=d04d8c100a84629ab6699d32acc82a504720c2b3;hp=0000000000000000000000000000000000000000;hb=8cbd4e2524c7e45c506bd00779d05f6608a81f66;hpb=57af98efbd82c4c89c81850f42b02585fed1a16a

diff --git a/lib/silccrypt/silcmac.h b/lib/silccrypt/silcmac.h
new file mode 100644
index 00000000..d04d8c10
--- /dev/null
+++ b/lib/silccrypt/silcmac.h
@@ -0,0 +1,484 @@
+/*
+
+  silcmac.h
+
+  Author: Pekka Riikonen <priikone@silcnet.org>
+
+  Copyright (C) 1999 - 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 SILCMAC_H
+#define SILCMAC_H
+
+/****h* silccrypt/SILC MAC Interface
+ *
+ * DESCRIPTION
+ *
+ * The Message Authentication Code interface for computing MAC values for
+ * authentication purposes.  The MAC is usually used in combination with
+ * encryption to provide authentication.
+ *
+ ***/
+
+/****s* silccrypt/SilcMac
+ *
+ * NAME
+ *
+ *    typedef struct SilcMacStruct *SilcMac;
+ *
+ * DESCRIPTION
+ *
+ *    This context is the actual MAC context and is allocated
+ *    by silc_mac_alloc and given as argument usually to all
+ *    silc_mac_* functions.  It is freed by the silc_mac_free
+ *    function.
+ *
+ ***/
+typedef struct SilcMacStruct *SilcMac;
+
+/****d* silccrypt/MACs
+ *
+ * NAME
+ *
+ *    MAC Algorithms
+ *
+ * DESCRIPTION
+ *
+ *    Supported MAC algorithm names.  These names can be given as argument
+ *    to silc_mac_alloc.
+ *
+ * SOURCE
+ */
+
+/* HMAC with SHA-256, MAC truncated to 96 bits */
+#define SILC_MAC_HMAC_SHA256_96   "hmac-sha256-96"
+
+/* HMAC with SHA-512, MAC truncated to 96 bits */
+#define SILC_MAC_HMAC_SHA512_96   "hmac-sha512-96"
+
+/* HMAC with SHA-1, MAC truncated to 96 bits */
+#define SILC_MAC_HMAC_SHA1_96     "hmac-sha1-96"
+
+/* HMAC with MD5, MAC truncated to 96 bits */
+#define SILC_MAC_HMAC_MD5_96      "hmac-md5-96"
+
+/* HMAC with SHA-256 */
+#define SILC_MAC_HMAC_SHA256      "hmac-sha256"
+
+/* HMAC with SHA-512 */
+#define SILC_MAC_HMAC_SHA512      "hmac-sha512"
+
+/* HMAC with SHA-1 */
+#define SILC_MAC_HMAC_SHA1        "hmac-sha1"
+
+/* HMAC with MD5 */
+#define SILC_MAC_HMAC_MD5         "hmac-md5"
+/***/
+
+/* MAC implementation object */
+typedef struct {
+  char *name;
+  SilcUInt32 len;
+} SilcMacObject;
+
+/* Marks for all MACs. This can be used in silc_mac_unregister
+   to unregister all MACs at once. */
+#define SILC_ALL_MACS ((SilcMacObject *)1)
+
+/* Default MACs for silc_mac_register_default(). */
+extern DLLAPI const SilcMacObject silc_default_macs[];
+
+/* Prototypes */
+
+/****f* silccrypt/silc_mac_register
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_mac_register(const SilcMacObject *mac);
+ *
+ * DESCRIPTION
+ *
+ *    Registers a new MAC into Crypto Toolkit. This function can be used
+ *    at the initialization.  All registered MACs should be unregistered
+ *    with silc_mac_unregister.  Returns FALSE on error.  Usually this
+ *    function is not needed.  The default MAC algorithms are automatically
+ *    registered.  This can be used to change the order of the registered
+ *    MAC algorithms by re-registering them in desired order, or add new
+ *    algorithms.
+ *
+ ***/
+SilcBool silc_mac_register(const SilcMacObject *mac);
+
+/****f* silccrypt/silc_mac_unregister
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_mac_unregister(SilcMacObject *mac);
+ *
+ * DESCRIPTION
+ *
+ *    Unregister a MAC from SILC by the MAC structure `mac'.  This
+ *    should be called for all MACs registered with silc_mac_register.
+ *    Returns FALSE on error.
+ *
+ ***/
+SilcBool silc_mac_unregister(SilcMacObject *mac);
+
+/****f* silccrypt/silc_mac_register_default
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_mac_register_default(void);
+ *
+ * DESCRIPTION
+ *
+ *    Registers all default MACs into the SILC.  These are the MACs
+ *    that are builtin in the sources.  Application need not call this
+ *    directly.  By calling silc_crypto_init this function is called.
+ *
+ ***/
+SilcBool silc_mac_register_default(void);
+
+/****f* silccrypt/silc_mac_unregister_all
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_mac_unregister_all(void);
+ *
+ * DESCRIPTION
+ *
+ *    Unregisters all registered MACs.  Application need not call this
+ *    directly.  By calling silc_crypto_uninit this function is called.
+ *
+ ***/
+SilcBool silc_mac_unregister_all(void);
+
+/****f* silccrypt/silc_mac_alloc
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_mac_alloc(const char *name, SilcMac *new_mac);
+ *
+ * DESCRIPTION
+ *
+ *    Allocates a new SilcMac object of name of `name'.  Returns FALSE if
+ *    such MAC does not exist.  After the MAC is allocated a key must be
+ *    set for it by calling silc_mac_set_key.
+ *
+ ***/
+SilcBool silc_mac_alloc(const char *name, SilcMac *new_mac);
+
+/****f* silccrypt/silc_mac_free
+ *
+ * SYNOPSIS
+ *
+ *    void silc_mac_free(SilcMac mac);
+ *
+ * DESCRIPTION
+ *
+ *    Frees the allocated MAC context.  The key that may have been set
+ *    with the silc_mac_set_key is also destroyed.
+ *
+ ***/
+void silc_mac_free(SilcMac mac);
+
+/****f* silccrypt/silc_mac_is_supported
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_mac_is_supported(const char *name);
+ *
+ * DESCRIPTION
+ *
+ *    Returns TRUE if the MAC indicated by the `name' exists.
+ *
+ ***/
+SilcBool silc_mac_is_supported(const char *name);
+
+/****f* silccrypt/silc_mac_get_supported
+ *
+ * SYNOPSIS
+ *
+ *    char *silc_mac_get_supported(void);
+ *
+ * DESCRIPTION
+ *
+ *    Returns comma (`,') separated list of registered MACs.  The caller
+ *    must free the returned pointer.
+ *
+ ***/
+char *silc_mac_get_supported(void);
+
+/****f* silccrypt/silc_mac_len
+ *
+ * SYNOPSIS
+ *
+ *    SilcUInt32 silc_mac_len(SilcMac mac);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the length of the MAC that the MAC will produce.
+ *
+ ***/
+SilcUInt32 silc_mac_len(SilcMac mac);
+
+/****f* silccrypt/silc_mac_get_name
+ *
+ * SYNOPSIS
+ *
+ *    const char *silc_mac_get_name(SilcMac mac);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the name of the MAC context.
+ *
+ ***/
+const char *silc_mac_get_name(SilcMac mac);
+
+/****f* silccrypt/silc_mac_get_hash
+ *
+ * SYNOPSIS
+ *
+ *    SilcHash silc_mac_get_hash(SilcMac mac);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the SilcHash context that has been associated with the
+ *    MAC context or NULL if the `mac' doesn't use hash function.  In effect
+ *    with HMACs this returns the underlaying hash function.  The caller
+ *    must not free the returned context.
+ *
+ ***/
+SilcHash silc_mac_get_hash(SilcMac hmac);
+
+/****f* silccrypt/silc_mac_set_key
+ *
+ * SYNOPSIS
+ *
+ *    void silc_mac_set_key(SilcMac mac, const unsigned char *key,
+ *                          SilcUInt32 key_len);
+ *
+ * DESCRIPTION
+ *
+ *    Sets the key to be used in the MAC operation.  This must be set
+ *    before calling silc_mac_make or silc_mac_final functions.  If
+ *    you do not want to set the key you can still produce a MAC by
+ *    calling the silc_mac_make_with_key where you give the key as
+ *    argument.  Usually application still wants to set the key.
+ *
+ ***/
+void silc_mac_set_key(SilcMac mac, const unsigned char *key,
+		      SilcUInt32 key_len);
+
+/****f* silccrypt/silc_mac_get_key
+ *
+ * SYNOPSIS
+ *
+ *    const unsigned char *
+ *    silc_mac_get_key(SilcMac mac, SilcUInt32 *key_len);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the key data from the `mac' set with silc_hamc_set_key.
+ *    The caller must not free the returned pointer.
+ *
+ ***/
+const unsigned char *silc_mac_get_key(SilcMac mac, SilcUInt32 *key_len);
+
+/****f* silccrypt/silc_mac_make
+ *
+ * SYNOPSIS
+ *
+ *    void silc_mac_make(SilcMac mac, 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_mac_len returns.  The returned length is still
+ *    returned to `return_len'.
+ *
+ ***/
+void silc_mac_make(SilcMac mac, unsigned char *data,
+		   SilcUInt32 data_len, unsigned char *return_hash,
+		   SilcUInt32 *return_len);
+
+/****f* silccrypt/silc_mac_make_with_key
+ *
+ * SYNOPSIS
+ *
+ *    void silc_mac_make_with_key(SilcMac mac, unsigned char *data,
+ *                                SilcUInt32 data_len,
+ *                                unsigned char *key, SilcUInt32 key_len,
+ *                                unsigned char *return_hash,
+ *                                SilcUInt32 *return_len);
+ *
+ * DESCRIPTION
+ *
+ *    Same as the silc_mac_make but takes the key for the MAC as argument.
+ *    If this is used the key that may have been set by calling
+ *    silc_mac_set_key is ignored.
+ *
+ ***/
+void silc_mac_make_with_key(SilcMac mac, unsigned char *data,
+			    SilcUInt32 data_len,
+			    unsigned char *key, SilcUInt32 key_len,
+			    unsigned char *return_hash,
+			    SilcUInt32 *return_len);
+
+/****f* silccrypt/silc_mac_make_truncated
+ *
+ * SYNOPSIS
+ *
+ *    void silc_mac_make_truncated(SilcMac mac,
+ *                                 unsigned char *data,
+ *                                 SilcUInt32 data_len,
+ *                                 SilcUInt32 truncated_len,
+ *                                 unsigned char *return_hash);
+ *
+ * DESCRIPTION
+ *
+ *    Same as the silc_mac_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_mac_make_truncated(SilcMac mac,
+			     unsigned char *data,
+			     SilcUInt32 data_len,
+			     SilcUInt32 truncated_len,
+			     unsigned char *return_hash);
+
+/****f* silccrypt/silc_mac_init
+ *
+ * SYNOPSIS
+ *
+ *    void silc_mac_init(SilcMac mac);
+ *
+ * DESCRIPTION
+ *
+ *    Sometimes calling the silc_mac_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_mac_make, or you can use the silc_mac_init,
+ *    silc_mac_update and silc_mac_final to do the MAC.  This function
+ *    prepares the allocated MAC context for this kind of MAC
+ *    computation.  The caller must have been called the function
+ *    silc_mac_set_key before calling this function.  To add the
+ *    data to be used in the MAC computation call the silc_mac_update
+ *    function.
+ *
+ ***/
+void silc_mac_init(SilcMac mac);
+
+/****f* silccrypt/silc_mac_init_with_key
+ *
+ * SYNOPSIS
+ *
+ *    void silc_mac_init_with_key(SilcMac mac, const unsigned char *key,
+ *                                SilcUInt32 key_len);
+ *
+ * DESCRIPTION
+ *
+ *    Same as silc_mac_init but initializes with specific key.  The
+ *    key that may have been set with silc_mac_set_key is ignored.
+ *
+ ***/
+void silc_mac_init_with_key(SilcMac mac, const unsigned char *key,
+			    SilcUInt32 key_len);
+
+/****f* silccrypt/silc_mac_update
+ *
+ * SYNOPSIS
+ *
+ *    void silc_mac_update(SilcMac mac, 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 MAC.  Once you've
+ *    added all the data you need you can call the silc_mac_final to
+ *    actually produce the MAC.
+ *
+ * EXAMPLE
+ *
+ *    unsigned char mac[20];
+ *    SilcUInt32 mac_len;
+ *
+ *    silc_mac_init(mac);
+ *    silc_mac_update(mac, data, data_len);
+ *    silc_mac_update(mac, more_data, more_data_len);
+ *    silc_mac_final(hac, mac, &mac_len);
+ *
+ ***/
+void silc_mac_update(SilcMac mac, const unsigned char *data,
+		     SilcUInt32 data_len);
+
+/****f* silccrypt/silc_mac_final
+ *
+ * SYNOPSIS
+ *
+ *    void silc_mac_final(SilcMac mac, 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 MAC context by calling the
+ *    silc_mac_update function.  The MAC is copied in to the
+ *    `return_hash' pointer which must be at least the size that
+ *    the silc_mac_len returns.  The length of the MAC is still
+ *    returned into `return_len'.
+ *
+ ***/
+void silc_mac_final(SilcMac mac, unsigned char *return_hash,
+		    SilcUInt32 *return_len);
+
+/* Backwards support for old HMAC API */
+#define SilcHmac SilcMac
+#define SilcHmacObject SilcMacObject
+#define SILC_ALL_HMACS SILC_ALL_MACS
+#define silc_default_hmacs silc_default_macs
+#define silc_hmac_register silc_mac_register
+#define silc_hmac_unregister silc_mac_unregister
+#define silc_hmac_register_default silc_mac_register_default
+#define silc_hmac_unregister_all silc_mac_unregister_all
+#define silc_hmac_alloc(name, hash, new_hmac) silc_mac_alloc(name, new_hmac)
+#define silc_hmac_free silc_mac_free
+#define silc_hmac_is_supported silc_mac_is_supported
+#define silc_hmac_get_supported silc_mac_get_supported
+#define silc_hmac_len silc_mac_len
+#define silc_hmac_get_hash silc_mac_get_hash
+#define silc_hmac_get_name silc_mac_get_name
+#define silc_hmac_set_key silc_mac_set_key
+#define silc_hmac_get_key silc_mac_get_key
+#define silc_hmac_make silc_mac_make
+#define silc_hmac_init_with_key silc_mac_init_with_key
+#define silc_hmac_update silc_mac_update
+#define silc_hmac_final silc_mac_final
+
+#endif /* SILCMAC_H */