lib/silccrypt/silchmac.h

   1 /*
   2
   3   silchmac.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1999 - 2006 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 SILCHMAC_H
  21 #define SILCHMAC_H
  22
  23 /****h* silccrypt/SILC HMAC Interface
  24  *
  25  * DESCRIPTION
  26  *
  27  *    This is the interface for HMAC, or the keyed hash values, that are
  28  *    used for packet and message authentication.  These routines uses
  29  *    already implemented hash functions from the SilcHashAPI. These
  30  *    routines were created according to RFC 2104.
  31  *
  32  ***/
  33
  34 /****s* silccrypt/SilcHMACAPI/SilcHmac
  35  *
  36  * NAME
  37  *
  38  *    typedef struct SilcHmacStruct *SilcHmac;
  39  *
  40  * DESCRIPTION
  41  *
  42  *    This context is the actual HMAC context and is allocated
  43  *    by silc_hmac_alloc and given as argument usually to all
  44  *    silc_hmac_* functions.  It is freed by the silc_hmac_free
  45  *    function.
  46  *
  47  ***/
  48 typedef struct SilcHmacStruct *SilcHmac;
  49
  50 /****s* silccrypt/SilcHMACAPI/SilcHmacObject
  51  *
  52  * NAME
  53  *
  54  *    typedef struct { ... } SilcHmacObject;
  55  *
  56  * DESCRIPTION
  57  *
  58  *    This structure represents one HMAC.  The HMAC's name and the
  59  *    MAC length is defined in the structure.  This structure is
  60  *    then given as argument to the silc_hmac_register.  That function
  61  *    is used to register all HMACs into SILC.  They can be then
  62  *    allocated by the name found in this structure by calling the
  63  *    silc_hmac_alloc.
  64  *
  65  ***/
  66 typedef struct {
  67   char *name;
  68   SilcUInt32 len;
  69 } SilcHmacObject;
  70
  71 /* Marks for all hmacs. This can be used in silc_hmac_unregister
  72    to unregister all hmacs at once. */
  73 #define SILC_ALL_HMACS ((SilcHmacObject *)1)
  74
  75 /* Default hmacs for silc_hmac_register_default(). */
  76 extern DLLAPI const SilcHmacObject silc_default_hmacs[];
  77
  78 /* Default HMAC in the SILC protocol */
  79 #define SILC_DEFAULT_HMAC "hmac-sha1-96"
  80
  81 /* Prototypes */
  82
  83 /****f* silccrypt/SilcHMACAPI/silc_hmac_register
  84  *
  85  * SYNOPSIS
  86  *
  87  *    SilcBool silc_hmac_register(const SilcHmacObject *hmac);
  88  *
  89  * DESCRIPTION
  90  *
  91  *    Registers a new HMAC into the SILC. This function is used at the
  92  *    initialization of the SILC.  All registered HMACs should be
  93  *    unregistered with silc_hmac_unregister.  The `hmac' includes the
  94  *    name of the HMAC and the length of the MAC.  Usually this
  95  *    function is not called directly.  Instead, application can call
  96  *    the silc_hmac_register_default to register all default HMACs
  97  *    that are builtin the sources.  Returns FALSE on error.
  98  *
  99  ***/
 100 SilcBool silc_hmac_register(const SilcHmacObject *hmac);
 101
 102 /****f* silccrypt/SilcHMACAPI/silc_hmac_unregister
 103  *
 104  * SYNOPSIS
 105  *
 106  *    SilcBool silc_hmac_unregister(SilcHmacObject *hmac);
 107  *
 108  * DESCRIPTION
 109  *
 110  *    Unregister a HMAC from SILC by the HMAC structure `hmac'.  This
 111  *    should be called for all registered HMAC's.  Returns FALSE on
 112  *    error.
 113  *
 114  ***/
 115 SilcBool silc_hmac_unregister(SilcHmacObject *hmac);
 116
 117 /****f* silccrypt/SilcHMACAPI/silc_hmac_register_default
 118  *
 119  * SYNOPSIS
 120  *
 121  *    SilcBool silc_hmac_register_default(void);
 122  *
 123  * DESCRIPTION
 124  *
 125  *    Registers all default HMACs into the SILC.  These are the HMACs
 126  *    that are builtin in the sources.  See the list of default HMACs
 127  *    in the silchmac.c source file.  The application may use this
 128  *    to register default HMACs if specific HMAC in any specific order
 129  *    is not wanted (application's configuration usually may decide
 130  *    the order of the registration, in which case this should not be
 131  *    used).
 132  *
 133  ***/
 134 SilcBool silc_hmac_register_default(void);
 135
 136 /****f* silccrypt/SilcHMACAPI/silc_hmac_unregister_all
 137  *
 138  * SYNOPSIS
 139  *
 140  *    SilcBool silc_hmac_unregister_all(void);
 141  *
 142  * DESCRIPTION
 143  *
 144  *    Unregisters all registered HMACs.
 145  *
 146  ***/
 147 SilcBool silc_hmac_unregister_all(void);
 148
 149 /****f* silccrypt/SilcHMACAPI/silc_hmac_alloc
 150  *
 151  * SYNOPSIS
 152  *
 153  *    SilcBool silc_hmac_alloc(const char *name, SilcHash hash,
 154  *                         SilcHmac *new_hmac);
 155  *
 156  * DESCRIPTION
 157  *
 158  *    Allocates a new SilcHmac object of name of `name'.  The `hash' may
 159  *    be provided as argument.  If provided it is used as the hash function
 160  *    of the HMAC.  If it is NULL then the hash function is allocated and
 161  *    the name of the hash algorithm is derived from the `name'.  Returns
 162  *    FALSE if such HMAC does not exist.
 163  *
 164  ***/
 165 SilcBool silc_hmac_alloc(const char *name, SilcHash hash, SilcHmac *new_hmac);
 166
 167 /****f* silccrypt/SilcHMACAPI/silc_hmac_free
 168  *
 169  * SYNOPSIS
 170  *
 171  *    void silc_hmac_free(SilcHmac hmac);
 172  *
 173  * DESCRIPTION
 174  *
 175  *    Frees the allocated HMAC context.  The key that may have been set
 176  *    with the silc_hmac_set_key is also destroyed.
 177  *
 178  ***/
 179 void silc_hmac_free(SilcHmac hmac);
 180
 181 /****f* silccrypt/SilcHMACAPI/silc_hmac_is_supported
 182  *
 183  * SYNOPSIS
 184  *
 185  *    SilcBool silc_hmac_is_supported(const char *name);
 186  *
 187  * DESCRIPTION
 188  *
 189  *    Returns TRUE if the HMAC indicated by the `name' exists.
 190  *
 191  ***/
 192 SilcBool silc_hmac_is_supported(const char *name);
 193
 194 /****f* silccrypt/SilcHMACAPI/silc_hmac_get_supported
 195  *
 196  * SYNOPSIS
 197  *
 198  *    char *silc_hmac_get_supported(void);
 199  *
 200  * DESCRIPTION
 201  *
 202  *    Returns comma (`,') separated list of registered HMACs.  This is
 203  *    used for example when sending supported HMAC list during the SILC
 204  *    Key Exchange protocol (SKE).  The caller must free the returned
 205  *    pointer.
 206  *
 207  ***/
 208 char *silc_hmac_get_supported(void);
 209
 210 /****f* silccrypt/SilcHMACAPI/silc_hmac_len
 211  *
 212  * SYNOPSIS
 213  *
 214  *    SilcUInt32 silc_hmac_len(SilcHmac hmac);
 215  *
 216  * DESCRIPTION
 217  *
 218  *    Returns the length of the MAC that the HMAC will produce.
 219  *
 220  ***/
 221 SilcUInt32 silc_hmac_len(SilcHmac hmac);
 222
 223 /****f* silccrypt/SilcHMACAPI/silc_hmac_get_hash
 224  *
 225  * SYNOPSIS
 226  *
 227  *    SilcHash silc_hmac_get_hash(SilcHmac hmac);
 228  *
 229  * DESCRIPTION
 230  *
 231  *    Returns the SilcHash context that has been associated with the
 232  *    HMAC context.  The caller must not free the returned context.
 233  *
 234  ***/
 235 SilcHash silc_hmac_get_hash(SilcHmac hmac);
 236
 237 /****f* silccrypt/SilcHMACAPI/silc_hmac_get_name
 238  *
 239  * SYNOPSIS
 240  *
 241  *    const char *silc_hmac_get_name(SilcHmac hmac);
 242  *
 243  * DESCRIPTION
 244  *
 245  *    Returns the name of the HMAC context.
 246  *
 247  ***/
 248 const char *silc_hmac_get_name(SilcHmac hmac);
 249
 250 /****f* silccrypt/SilcHMACAPI/silc_hmac_set_key
 251  *
 252  * SYNOPSIS
 253  *
 254  *    void silc_hmac_set_key(SilcHmac hmac, const unsigned char *key,
 255  *                           SilcUInt32 key_len);
 256  *
 257  * DESCRIPTION
 258  *
 259  *    Sets the key to be used in the HMAC operation.  This must be set
 260  *    before calling silc_hmac_make or silc_hmac_final functions.  If
 261  *    you do not want to set the key you can still produce a MAC by
 262  *    calling the silc_hmac_make_with_key where you give the key as
 263  *    argument.  Usually application still wants to set the key.
 264  *
 265  ***/
 266 void silc_hmac_set_key(SilcHmac hmac, const unsigned char *key,
 267                        SilcUInt32 key_len);
 268
 269 /****f* silccrypt/SilcHMACAPI/silc_hmac_get_key
 270  *
 271  * SYNOPSIS
 272  *
 273  *    const unsigned char *
 274  *    silc_hmac_get_key(SilcHmac hmac, SilcUInt32 *key_len);
 275  *
 276  * DESCRIPTION
 277  *
 278  *    Returns the key data from the `hmac' set with silc_hamc_set_key.
 279  *    The caller must not free the returned pointer.
 280  *
 281  ***/
 282 const unsigned char *silc_hmac_get_key(SilcHmac hmac, SilcUInt32 *key_len);
 283
 284 /****f* silccrypt/SilcHMACAPI/silc_hmac_make
 285  *
 286  * SYNOPSIS
 287  *
 288  *    void silc_hmac_make(SilcHmac hmac, unsigned char *data,
 289  *                        SilcUInt32 data_len, unsigned char *return_hash,
 290  *                        SilcUInt32 *return_len);
 291  *
 292  * DESCRIPTION
 293  *
 294  *    Computes a MAC from a data buffer indicated by the `data' of the
 295  *    length of `data_len'.  The returned MAC is copied into the
 296  *    `return_hash' pointer which must be at least the size of the
 297  *    value silc_hmac_len returns.  The returned length is still
 298  *    returned to `return_len'.
 299  *
 300  ***/
 301 void silc_hmac_make(SilcHmac hmac, unsigned char *data,
 302                     SilcUInt32 data_len, unsigned char *return_hash,
 303                     SilcUInt32 *return_len);
 304
 305 /****f* silccrypt/SilcHMACAPI/silc_hmac_make_with_key
 306  *
 307  * SYNOPSIS
 308  *
 309  *    void silc_hmac_make_with_key(SilcHmac hmac, unsigned char *data,
 310  *                                 SilcUInt32 data_len,
 311  *                                 unsigned char *key, SilcUInt32 key_len,
 312  *                                 unsigned char *return_hash,
 313  *                                 SilcUInt32 *return_len);
 314  *
 315  * DESCRIPTION
 316  *
 317  *    Same as the silc_hmac_make but takes the key for the HMAC as
 318  *    argument.  If this is used the key that may have been set by calling
 319  *    silc_hmac_set_key is ignored.
 320  *
 321  ***/
 322 void silc_hmac_make_with_key(SilcHmac hmac, unsigned char *data,
 323                              SilcUInt32 data_len,
 324                              unsigned char *key, SilcUInt32 key_len,
 325                              unsigned char *return_hash,
 326                              SilcUInt32 *return_len);
 327
 328 /****f* silccrypt/SilcHMACAPI/silc_hmac_make_truncated
 329  *
 330  * SYNOPSIS
 331  *
 332  *    void silc_hmac_make_truncated(SilcHmac hmac,
 333  *                                  unsigned char *data,
 334  *                                  SilcUInt32 data_len,
 335  *                                  SilcUInt32 truncated_len,
 336  *                                  unsigned char *return_hash);
 337  *
 338  * DESCRIPTION
 339  *
 340  *    Same as the silc_hmac_make except that the returned MAC is
 341  *    truncated to the length indicated by the `truncated_len'.  Some
 342  *    special applications may need this function.  The `return_hash'
 343  *    must be at least the size of `truncated_len'.
 344  *
 345  * NOTES
 346  *
 347  *    For security reasons, one should not truncate to less than half
 348  *    of the length of the true MAC lenght.  However, since this routine
 349  *    may be used to non-critical applications this allows these dangerous
 350  *    truncations.
 351  *
 352  ***/
 353 void silc_hmac_make_truncated(SilcHmac hmac,
 354                               unsigned char *data,
 355                               SilcUInt32 data_len,
 356                               SilcUInt32 truncated_len,
 357                               unsigned char *return_hash);
 358
 359 /****f* silccrypt/SilcHMACAPI/silc_hmac_init
 360  *
 361  * SYNOPSIS
 362  *
 363  *    void silc_hmac_init(SilcHmac hmac);
 364  *
 365  * DESCRIPTION
 366  *
 367  *    Sometimes calling the silc_hmac_make might not be the most
 368  *    optimal case of doing MACs.  If you have a lot of different data
 369  *    that you need to put together for computing a MAC you may either
 370  *    put them into a buffer and compute the MAC from the buffer by
 371  *    calling the silc_hmac_make, or you can use the silc_hmac_init,
 372  *    silc_hmac_update and silc_hmac_final to do the MAC.  This function
 373  *    prepares the allocated HMAC context for this kind of MAC
 374  *    computation.  The caller must have been called the function
 375  *    silc_hmac_set_key before calling this function.  To add the
 376  *    data to be used in the MAC computation call the silc_hmac_update
 377  *    function.
 378  *
 379  ***/
 380 void silc_hmac_init(SilcHmac hmac);
 381
 382 /****f* silccrypt/SilcHMACAPI/silc_hmac_init_with_key
 383  *
 384  * SYNOPSIS
 385  *
 386  *    void silc_hmac_init_with_key(SilcHmac hmac, const unsigned char *key,
 387  *                                 SilcUInt32 key_len);
 388  *
 389  * DESCRIPTION
 390  *
 391  *    Same as silc_hmac_init but initializes with specific key.  The
 392  *    key that may have been set with silc_hmac_set_key is ignored.
 393  *
 394  ***/
 395 void silc_hmac_init_with_key(SilcHmac hmac, const unsigned char *key,
 396                              SilcUInt32 key_len);
 397
 398 /****f* silccrypt/SilcHMACAPI/silc_hmac_update
 399  *
 400  * SYNOPSIS
 401  *
 402  *    void silc_hmac_update(SilcHmac hmac, const unsigned char *data,
 403  *                          SilcUInt32 data_len);
 404  *
 405  * DESCRIPTION
 406  *
 407  *    This function may be called to add data to be used in the MAC
 408  *    computation.  This can be called multiple times to add data from
 409  *    many sources before actually performing the HMAC.  Once you've
 410  *    added all the data you need you can call the silc_hmac_final to
 411  *    actually produce the MAC.
 412  *
 413  * EXAMPLE
 414  *
 415  *    unsigned char mac[20];
 416  *    SilcUInt32 mac_len;
 417  *
 418  *    silc_hmac_init(hmac);
 419  *    silc_hmac_update(hmac, data, data_len);
 420  *    silc_hmac_update(hmac, more_data, more_data_len);
 421  *    silc_hmac_final(hmac, mac, &mac_len);
 422  *
 423  ***/
 424 void silc_hmac_update(SilcHmac hmac, const unsigned char *data,
 425                       SilcUInt32 data_len);
 426
 427 /****f* silccrypt/SilcHMACAPI/silc_hmac_final
 428  *
 429  * SYNOPSIS
 430  *
 431  *    void silc_hmac_final(SilcHmac hmac, unsigned char *return_hash,
 432  *                         SilcUInt32 *return_len);
 433  *
 434  * DESCRIPTION
 435  *
 436  *    This function is used to produce the final MAC from the data
 437  *    that has been added to the HMAC context by calling the
 438  *    silc_hmac_update function.  The MAC is copied in to the
 439  *    `return_hash' pointer which must be at least the size that
 440  *    the silc_hmac_len returns.  The length of the MAC is still
 441  *    returned into `return_len'.
 442  *
 443  ***/
 444 void silc_hmac_final(SilcHmac hmac, unsigned char *return_hash,
 445                      SilcUInt32 *return_len);
 446
 447 #endif