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