lib/silccrypt/silcmac.h

   1 /*
   2
   3   silcmac.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1999 - 2008 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 #ifndef SILCMAC_H
  21 #define SILCMAC_H
  22
  23 /****h* silccrypt/MAC Interface
  24  *
  25  * DESCRIPTION
  26  *
  27  * The Message Authentication Code interface for computing MAC values for
  28  * authentication purposes.  The MAC is usually used in combination with
  29  * encryption to provide authentication.
  30  *
  31  * EXAMPLE
  32  *
  33  * SilcMac hmac;
  34  *
  35  * // Allocate HMAC
  36  * silc_mac_alloc(SILC_MAC_HMAC_SHA256, &hmac);
  37  *
  38  * // Set secret key to the MAC
  39  * silc_mac_set_key(hmac, key, key_len);
  40  *
  41  * // Compute MAC
  42  * unsigned char mac[SILC_MAC_MAXLEN];
  43  * SilcUInt32 mac_len;
  44  *
  45  * silc_mac_make(hmac, data, data_len, digest, &mac_len);
  46  *
  47  * // Free MAC
  48  * silc_mac_free(hmac);
  49  *
  50  ***/
  51
  52 /****s* silccrypt/SilcMac
  53  *
  54  * NAME
  55  *
  56  *    typedef struct SilcMacStruct *SilcMac;
  57  *
  58  * DESCRIPTION
  59  *
  60  *    This context is the actual MAC context and is allocated
  61  *    by silc_mac_alloc and given as argument usually to all
  62  *    silc_mac_* functions.  It is freed by the silc_mac_free
  63  *    function.
  64  *
  65  ***/
  66 typedef struct SilcMacStruct *SilcMac;
  67
  68 /****d* silccrypt/MACs
  69  *
  70  * NAME
  71  *
  72  *    MAC Algorithms
  73  *
  74  * DESCRIPTION
  75  *
  76  *    Supported MAC algorithm names.  These names can be given as argument
  77  *    to silc_mac_alloc.
  78  *
  79  * SOURCE
  80  */
  81
  82 /* HMAC with SHA-256, MAC truncated to 96 bits */
  83 #define SILC_MAC_HMAC_SHA256_96   "hmac-sha256-96"
  84
  85 /* HMAC with SHA-512, MAC truncated to 96 bits */
  86 #define SILC_MAC_HMAC_SHA512_96   "hmac-sha512-96"
  87
  88 /* HMAC with SHA-1, MAC truncated to 96 bits */
  89 #define SILC_MAC_HMAC_SHA1_96     "hmac-sha1-96"
  90
  91 /* HMAC with MD5, MAC truncated to 96 bits */
  92 #define SILC_MAC_HMAC_MD5_96      "hmac-md5-96"
  93
  94 /* HMAC with SHA-256 */
  95 #define SILC_MAC_HMAC_SHA256      "hmac-sha256"
  96
  97 /* HMAC with SHA-512 */
  98 #define SILC_MAC_HMAC_SHA512      "hmac-sha512"
  99
 100 /* HMAC with SHA-1 */
 101 #define SILC_MAC_HMAC_SHA1        "hmac-sha1"
 102
 103 /* HMAC with MD5 */
 104 #define SILC_MAC_HMAC_MD5         "hmac-md5"
 105 /***/
 106
 107 /****d* silccrypt/SILC_MAC_MAXLEN
 108  *
 109  * NAME
 110  *
 111  *    #define SILC_MAC_MAXLEN 64
 112  *
 113  * DESCRIPTION
 114  *
 115  *    Maximum size of digest any algorithm supported by SILC Crypto Toolkit
 116  *    would produce.  You can use this to define static digest buffers and
 117  *    safely use it with any hash function.
 118  *
 119  ***/
 120 #define SILC_MAC_MAXLEN 64
 121
 122 /* MAC implementation object */
 123 typedef struct {
 124   char *name;
 125   SilcUInt32 len;
 126 } SilcMacObject;
 127
 128 /* Marks for all MACs. This can be used in silc_mac_unregister
 129    to unregister all MACs at once. */
 130 #define SILC_ALL_MACS ((SilcMacObject *)1)
 131
 132 /* Default MACs for silc_mac_register_default(). */
 133 extern DLLAPI const SilcMacObject silc_default_macs[];
 134
 135 /* Prototypes */
 136
 137 /****f* silccrypt/silc_mac_register
 138  *
 139  * SYNOPSIS
 140  *
 141  *    SilcBool silc_mac_register(const SilcMacObject *mac);
 142  *
 143  * DESCRIPTION
 144  *
 145  *    Registers a new MAC into Crypto Toolkit. This function can be used
 146  *    at the initialization.  All registered MACs should be unregistered
 147  *    with silc_mac_unregister.  Returns FALSE on error.  Usually this
 148  *    function is not needed.  The default MAC algorithms are automatically
 149  *    registered.  This can be used to change the order of the registered
 150  *    MAC algorithms by re-registering them in desired order, or add new
 151  *    algorithms.
 152  *
 153  ***/
 154 SilcBool silc_mac_register(const SilcMacObject *mac);
 155
 156 /****f* silccrypt/silc_mac_unregister
 157  *
 158  * SYNOPSIS
 159  *
 160  *    SilcBool silc_mac_unregister(SilcMacObject *mac);
 161  *
 162  * DESCRIPTION
 163  *
 164  *    Unregister a MAC from SILC by the MAC structure `mac'.  This
 165  *    should be called for all MACs registered with silc_mac_register.
 166  *    Returns FALSE on error.
 167  *
 168  ***/
 169 SilcBool silc_mac_unregister(SilcMacObject *mac);
 170
 171 /****f* silccrypt/silc_mac_register_default
 172  *
 173  * SYNOPSIS
 174  *
 175  *    SilcBool silc_mac_register_default(void);
 176  *
 177  * DESCRIPTION
 178  *
 179  *    Registers all default MACs into the SILC.  These are the MACs
 180  *    that are builtin in the sources.  Application need not call this
 181  *    directly.  By calling silc_crypto_init this function is called.
 182  *
 183  ***/
 184 SilcBool silc_mac_register_default(void);
 185
 186 /****f* silccrypt/silc_mac_unregister_all
 187  *
 188  * SYNOPSIS
 189  *
 190  *    SilcBool silc_mac_unregister_all(void);
 191  *
 192  * DESCRIPTION
 193  *
 194  *    Unregisters all registered MACs.  Application need not call this
 195  *    directly.  By calling silc_crypto_uninit this function is called.
 196  *
 197  ***/
 198 SilcBool silc_mac_unregister_all(void);
 199
 200 /****f* silccrypt/silc_mac_alloc
 201  *
 202  * SYNOPSIS
 203  *
 204  *    SilcBool silc_mac_alloc(const char *name, SilcMac *new_mac);
 205  *
 206  * DESCRIPTION
 207  *
 208  *    Allocates a new SilcMac object of name of `name'.  Returns FALSE if
 209  *    such MAC does not exist.  After the MAC is allocated a key must be
 210  *    set for it by calling silc_mac_set_key.
 211  *
 212  *    See MACs for supported MAC algorithms.
 213  *
 214  ***/
 215 SilcBool silc_mac_alloc(const char *name, SilcMac *new_mac);
 216
 217 /****f* silccrypt/silc_mac_free
 218  *
 219  * SYNOPSIS
 220  *
 221  *    void silc_mac_free(SilcMac mac);
 222  *
 223  * DESCRIPTION
 224  *
 225  *    Frees the allocated MAC context.  The key that may have been set
 226  *    with the silc_mac_set_key is also destroyed.
 227  *
 228  ***/
 229 void silc_mac_free(SilcMac mac);
 230
 231 /****f* silccrypt/silc_mac_is_supported
 232  *
 233  * SYNOPSIS
 234  *
 235  *    SilcBool silc_mac_is_supported(const char *name);
 236  *
 237  * DESCRIPTION
 238  *
 239  *    Returns TRUE if the MAC indicated by the `name' exists.
 240  *
 241  ***/
 242 SilcBool silc_mac_is_supported(const char *name);
 243
 244 /****f* silccrypt/silc_mac_get_supported
 245  *
 246  * SYNOPSIS
 247  *
 248  *    char *silc_mac_get_supported(void);
 249  *
 250  * DESCRIPTION
 251  *
 252  *    Returns comma (`,') separated list of registered MACs.  The caller
 253  *    must free the returned pointer.
 254  *
 255  ***/
 256 char *silc_mac_get_supported(void);
 257
 258 /****f* silccrypt/silc_mac_len
 259  *
 260  * SYNOPSIS
 261  *
 262  *    SilcUInt32 silc_mac_len(SilcMac mac);
 263  *
 264  * DESCRIPTION
 265  *
 266  *    Returns the length of the MAC that the MAC will produce.
 267  *
 268  ***/
 269 SilcUInt32 silc_mac_len(SilcMac mac);
 270
 271 /****f* silccrypt/silc_mac_get_name
 272  *
 273  * SYNOPSIS
 274  *
 275  *    const char *silc_mac_get_name(SilcMac mac);
 276  *
 277  * DESCRIPTION
 278  *
 279  *    Returns the name of the MAC context.
 280  *
 281  ***/
 282 const char *silc_mac_get_name(SilcMac mac);
 283
 284 /****f* silccrypt/silc_mac_get_hash
 285  *
 286  * SYNOPSIS
 287  *
 288  *    SilcHash silc_mac_get_hash(SilcMac mac);
 289  *
 290  * DESCRIPTION
 291  *
 292  *    Returns the SilcHash context that has been associated with the
 293  *    MAC context or NULL if the `mac' doesn't use hash function.  In effect
 294  *    with HMACs this returns the underlaying hash function.  The caller
 295  *    must not free the returned context.
 296  *
 297  ***/
 298 SilcHash silc_mac_get_hash(SilcMac hmac);
 299
 300 /****f* silccrypt/silc_mac_set_key
 301  *
 302  * SYNOPSIS
 303  *
 304  *    void silc_mac_set_key(SilcMac mac, const unsigned char *key,
 305  *                          SilcUInt32 key_len);
 306  *
 307  * DESCRIPTION
 308  *
 309  *    Sets the key to be used in the MAC operation.  This must be set
 310  *    before calling silc_mac_make or silc_mac_final functions.  If
 311  *    you do not want to set the key you can still produce a MAC by
 312  *    calling the silc_mac_make_with_key where you give the key as
 313  *    argument.  Usually application still wants to set the key.
 314  *
 315  ***/
 316 void silc_mac_set_key(SilcMac mac, const unsigned char *key,
 317                       SilcUInt32 key_len);
 318
 319 /****f* silccrypt/silc_mac_get_key
 320  *
 321  * SYNOPSIS
 322  *
 323  *    const unsigned char *
 324  *    silc_mac_get_key(SilcMac mac, SilcUInt32 *key_len);
 325  *
 326  * DESCRIPTION
 327  *
 328  *    Returns the key data from the `mac' set with silc_hamc_set_key.
 329  *    The caller must not free the returned pointer.
 330  *
 331  ***/
 332 const unsigned char *silc_mac_get_key(SilcMac mac, SilcUInt32 *key_len);
 333
 334 /****f* silccrypt/silc_mac_make
 335  *
 336  * SYNOPSIS
 337  *
 338  *    void silc_mac_make(SilcMac mac, unsigned char *data,
 339  *                       SilcUInt32 data_len, unsigned char *return_hash,
 340  *                       SilcUInt32 *return_len);
 341  *
 342  * DESCRIPTION
 343  *
 344  *    Computes a MAC from a data buffer indicated by the `data' of the
 345  *    length of `data_len'.  The returned MAC is copied into the
 346  *    `return_hash' pointer which must be at least the size of the
 347  *    value silc_mac_len returns.  The returned length is still
 348  *    returned to `return_len'.
 349  *
 350  ***/
 351 void silc_mac_make(SilcMac mac, unsigned char *data,
 352                    SilcUInt32 data_len, unsigned char *return_hash,
 353                    SilcUInt32 *return_len);
 354
 355 /****f* silccrypt/silc_mac_make_with_key
 356  *
 357  * SYNOPSIS
 358  *
 359  *    void silc_mac_make_with_key(SilcMac mac, unsigned char *data,
 360  *                                SilcUInt32 data_len,
 361  *                                unsigned char *key, SilcUInt32 key_len,
 362  *                                unsigned char *return_hash,
 363  *                                SilcUInt32 *return_len);
 364  *
 365  * DESCRIPTION
 366  *
 367  *    Same as the silc_mac_make but takes the key for the MAC as argument.
 368  *    If this is used the key that may have been set by calling
 369  *    silc_mac_set_key is ignored.
 370  *
 371  ***/
 372 void silc_mac_make_with_key(SilcMac mac, unsigned char *data,
 373                             SilcUInt32 data_len,
 374                             unsigned char *key, SilcUInt32 key_len,
 375                             unsigned char *return_hash,
 376                             SilcUInt32 *return_len);
 377
 378 /****f* silccrypt/silc_mac_make_truncated
 379  *
 380  * SYNOPSIS
 381  *
 382  *    void silc_mac_make_truncated(SilcMac mac,
 383  *                                 unsigned char *data,
 384  *                                 SilcUInt32 data_len,
 385  *                                 SilcUInt32 truncated_len,
 386  *                                 unsigned char *return_hash);
 387  *
 388  * DESCRIPTION
 389  *
 390  *    Same as the silc_mac_make except that the returned MAC is
 391  *    truncated to the length indicated by the `truncated_len'.  Some
 392  *    special applications may need this function.  The `return_hash'
 393  *    must be at least the size of `truncated_len'.
 394  *
 395  * NOTES
 396  *
 397  *    For security reasons, one should not truncate to less than half
 398  *    of the length of the true MAC lenght.  However, since this routine
 399  *    may be used to non-critical applications this allows these dangerous
 400  *    truncations.
 401  *
 402  ***/
 403 void silc_mac_make_truncated(SilcMac mac,
 404                              unsigned char *data,
 405                              SilcUInt32 data_len,
 406                              SilcUInt32 truncated_len,
 407                              unsigned char *return_hash);
 408
 409 /****f* silccrypt/silc_mac_init
 410  *
 411  * SYNOPSIS
 412  *
 413  *    void silc_mac_init(SilcMac mac);
 414  *
 415  * DESCRIPTION
 416  *
 417  *    Sometimes calling the silc_mac_make might not be the most
 418  *    optimal case of doing MACs.  If you have a lot of different data
 419  *    that you need to put together for computing a MAC you may either
 420  *    put them into a buffer and compute the MAC from the buffer by
 421  *    calling the silc_mac_make, or you can use the silc_mac_init,
 422  *    silc_mac_update and silc_mac_final to do the MAC.  This function
 423  *    prepares the allocated MAC context for this kind of MAC
 424  *    computation.  The caller must have been called the function
 425  *    silc_mac_set_key before calling this function.  To add the
 426  *    data to be used in the MAC computation call the silc_mac_update
 427  *    function.
 428  *
 429  ***/
 430 void silc_mac_init(SilcMac mac);
 431
 432 /****f* silccrypt/silc_mac_init_with_key
 433  *
 434  * SYNOPSIS
 435  *
 436  *    void silc_mac_init_with_key(SilcMac mac, const unsigned char *key,
 437  *                                SilcUInt32 key_len);
 438  *
 439  * DESCRIPTION
 440  *
 441  *    Same as silc_mac_init but initializes with specific key.  The
 442  *    key that may have been set with silc_mac_set_key is ignored.
 443  *
 444  ***/
 445 void silc_mac_init_with_key(SilcMac mac, const unsigned char *key,
 446                             SilcUInt32 key_len);
 447
 448 /****f* silccrypt/silc_mac_update
 449  *
 450  * SYNOPSIS
 451  *
 452  *    void silc_mac_update(SilcMac mac, const unsigned char *data,
 453  *                         SilcUInt32 data_len);
 454  *
 455  * DESCRIPTION
 456  *
 457  *    This function may be called to add data to be used in the MAC
 458  *    computation.  This can be called multiple times to add data from
 459  *    many sources before actually performing the MAC.  Once you've
 460  *    added all the data you need you can call the silc_mac_final to
 461  *    actually produce the MAC.
 462  *
 463  * EXAMPLE
 464  *
 465  *    unsigned char mac[20];
 466  *    SilcUInt32 mac_len;
 467  *
 468  *    silc_mac_init(mac);
 469  *    silc_mac_update(mac, data, data_len);
 470  *    silc_mac_update(mac, more_data, more_data_len);
 471  *    silc_mac_final(hac, mac, &mac_len);
 472  *
 473  ***/
 474 void silc_mac_update(SilcMac mac, const unsigned char *data,
 475                      SilcUInt32 data_len);
 476
 477 /****f* silccrypt/silc_mac_final
 478  *
 479  * SYNOPSIS
 480  *
 481  *    void silc_mac_final(SilcMac mac, unsigned char *return_hash,
 482  *                        SilcUInt32 *return_len);
 483  *
 484  * DESCRIPTION
 485  *
 486  *    This function is used to produce the final MAC from the data
 487  *    that has been added to the MAC context by calling the
 488  *    silc_mac_update function.  The MAC is copied in to the
 489  *    `return_hash' pointer which must be at least the size that
 490  *    the silc_mac_len returns.  The length of the MAC is still
 491  *    returned into `return_len'.
 492  *
 493  ***/
 494 void silc_mac_final(SilcMac mac, unsigned char *return_hash,
 495                     SilcUInt32 *return_len);
 496
 497 /* Backwards support for old HMAC API */
 498 #define SilcHmac SilcMac
 499 #define SilcHmacObject SilcMacObject
 500 #define SILC_ALL_HMACS SILC_ALL_MACS
 501 #define silc_default_hmacs silc_default_macs
 502 #define silc_hmac_register silc_mac_register
 503 #define silc_hmac_unregister silc_mac_unregister
 504 #define silc_hmac_register_default silc_mac_register_default
 505 #define silc_hmac_unregister_all silc_mac_unregister_all
 506 #define silc_hmac_alloc(name, hash, new_hmac) silc_mac_alloc(name, new_hmac)
 507 #define silc_hmac_free silc_mac_free
 508 #define silc_hmac_is_supported silc_mac_is_supported
 509 #define silc_hmac_get_supported silc_mac_get_supported
 510 #define silc_hmac_len silc_mac_len
 511 #define silc_hmac_get_hash silc_mac_get_hash
 512 #define silc_hmac_get_name silc_mac_get_name
 513 #define silc_hmac_set_key silc_mac_set_key
 514 #define silc_hmac_get_key silc_mac_get_key
 515 #define silc_hmac_make silc_mac_make
 516 #define silc_hmac_init_with_key silc_mac_init_with_key
 517 #define silc_hmac_update silc_mac_update
 518 #define silc_hmac_final silc_mac_final
 519
 520 #endif /* SILCMAC_H */