SILC Crypto Toolkit 1.2 Beta1

[crypto.git] / lib / silccrypt / silcmac.h

diff --git a/lib/silccrypt/silcmac.h b/lib/silccrypt/silcmac.h
index d04d8c100a84629ab6699d32acc82a504720c2b3..ad6548c628f001151fb59146b515862f2a9a4e10 100644 (file)
--- a/lib/silccrypt/silcmac.h
+++ b/lib/silccrypt/silcmac.h
@@ -20,7 +20,7 @@
 #ifndef SILCMAC_H
 #define SILCMAC_H
 
-/****h* silccrypt/SILC MAC Interface
+/****h* silccrypt/MAC Interface
  *
  * DESCRIPTION
  *
@@ -28,6 +28,25 @@
  * authentication purposes.  The MAC is usually used in combination with
  * encryption to provide authentication.
  *
+ * EXAMPLE
+ *
+ * SilcMac hmac;
+ *
+ * // Allocate HMAC
+ * silc_mac_alloc(SILC_MAC_HMAC_SHA256, &hmac);
+ *
+ * // Set secret key to the MAC
+ * silc_mac_set_key(hmac, key, key_len);
+ *
+ * // Compute MAC
+ * unsigned char mac[SILC_MAC_MAXLEN];
+ * SilcUInt32 mac_len;
+ *
+ * silc_mac_make(hmac, data, data_len, digest, &mac_len);
+ *
+ * // Free MAC
+ * silc_mac_free(hmac);
+ *
  ***/
 
 /****s* silccrypt/SilcMac
@@ -85,6 +104,21 @@ typedef struct SilcMacStruct *SilcMac;
 #define SILC_MAC_HMAC_MD5         "hmac-md5"
 /***/
 
+/****d* silccrypt/SILC_MAC_MAXLEN
+ *
+ * NAME
+ *
+ *    #define SILC_MAC_MAXLEN 64
+ *
+ * DESCRIPTION
+ *
+ *    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.
+ *
+ ***/
+#define SILC_MAC_MAXLEN 64
+
 /* MAC implementation object */
 typedef struct {
   char *name;
@@ -175,6 +209,8 @@ SilcBool silc_mac_unregister_all(void);
  *    such MAC does not exist.  After the MAC is allocated a key must be
  *    set for it by calling silc_mac_set_key.
  *
+ *    See MACs for supported MAC algorithms.
+ *
  ***/
 SilcBool silc_mac_alloc(const char *name, SilcMac *new_mac);