lib/silccrypt/silchash.h

   1 /*
   2
   3   silchash.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2007 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 SILCHASH_H
  21 #define SILCHASH_H
  22
  23 /****h* silccrypt/SILC Hash Interface
  24  *
  25  * DESCRIPTION
  26  *
  27  *    This is the interface for hash functions which are used to create
  28  *    message digests.  The routines are used in various cryptographic
  29  *    operations.  SILC Hash Interface is used for example by the
  30  *    SILC HMAC Interface (SilcHmac).
  31  *
  32  ***/
  33
  34 /****s* silccrypt/SilcHashAPI/SilcHash
  35  *
  36  * NAME
  37  *
  38  *    typedef struct SilcHashStruct *SilcHash;
  39  *
  40  * DESCRIPTION
  41  *
  42  *    This context is the actual hash function context and is allocated
  43  *    by silc_hash_alloc and given as argument usually to all
  44  *    silc_hash_* functions.  It is freed by the silc_hash_free
  45  *    function.
  46  *
  47  ***/
  48 typedef struct SilcHashStruct *SilcHash;
  49
  50 /****s* silccrypt/SilcHashAPI/SilcHashObject
  51  *
  52  * NAME
  53  *
  54  *    typedef struct { ... } SilcHashObject;
  55  *
  56  * DESCRIPTION
  57  *
  58  *    This structure represents one hash function.  The hash function's
  59  *    name, digest length and block length are defined in the structure.
  60  *    This structure is then given as argument to the silc_hash_register.
  61  *    That function is used to register all hash functions into SILC.
  62  *    They can be then allocated by the name found in this structure by
  63  *    calling the silc_hash_alloc.
  64  *
  65  ***/
  66 typedef struct {
  67   char *name;
  68   char *oid;
  69   SilcUInt16 hash_len;
  70   SilcUInt16 block_len;
  71
  72   void (*init)(void *);
  73   void (*update)(void *, const unsigned char *, SilcUInt32);
  74   void (*final)(void *, unsigned char *);
  75   void (*transform)(void *, const unsigned char *);
  76   SilcUInt32 (*context_len)();
  77 } SilcHashObject;
  78
  79 /* Marks for all hash functions. This can be used in silc_hash_unregister
  80    to unregister all hash function at once. */
  81 #define SILC_ALL_HASH_FUNCTIONS ((SilcHashObject *)1)
  82
  83 /* Default hash functions for silc_hash_register_default(). */
  84 extern DLLAPI const SilcHashObject silc_default_hash[];
  85
  86 /* Default HASH function in the SILC protocol */
  87 #define SILC_DEFAULT_HASH "sha1"
  88 #define SILC_HASH_MAXLEN 64
  89
  90 /* Macros */
  91
  92 /* Following macros are used to implement the SILC Hash API. These
  93    macros should be used instead of declaring functions by hand. */
  94
  95 /* Function names in SILC Hash modules. The name of the hash function
  96    is appended into these names and used to the get correct symbol out
  97    of the module. All SILC Hash API compliant modules has to support
  98    these names as function names (use macros below to assure this). */
  99 #define SILC_HASH_SIM_INIT "init"
 100 #define SILC_HASH_SIM_UPDATE "update"
 101 #define SILC_HASH_SIM_FINAL "final"
 102 #define SILC_HASH_SIM_TRANSFORM "transform"
 103 #define SILC_HASH_SIM_CONTEXT_LEN "context_len"
 104
 105 /* Macros that can be used to declare SILC Hash API functions. */
 106 #define SILC_HASH_API_INIT(hash)                                        \
 107 void silc_##hash##_init(void *context)
 108 #define SILC_HASH_API_UPDATE(hash)                                      \
 109 void silc_##hash##_update(void *context, const unsigned char *data,     \
 110                           SilcUInt32 len)
 111 #define SILC_HASH_API_FINAL(hash)                                       \
 112 void silc_##hash##_final(void *context, unsigned char *digest)
 113 #define SILC_HASH_API_TRANSFORM(hash)                                   \
 114 void silc_##hash##_transform(void *state, const unsigned char *buffer)
 115 #define SILC_HASH_API_CONTEXT_LEN(hash)                                 \
 116 SilcUInt32 silc_##hash##_context_len()
 117
 118 /* Prototypes */
 119
 120 /****f* silccrypt/SilcHashAPI/silc_hash_register
 121  *
 122  * SYNOPSIS
 123  *
 124  *    SilcBool silc_hash_register(const SilcHashObject *hash);
 125  *
 126  * DESCRIPTION
 127  *
 128  *    Registers a new hash function into the SILC.  This function is used
 129  *    at the initialization of the SILC.  All registered hash functions
 130  *    should be unregistered with silc_hash_unregister.  The `hash' includes
 131  *    the name of the hash function, digest length and block length.  Usually
 132  *    this function is not called directly.  Instead, application can call
 133  *    the silc_hash_register_default to register all default hash functions
 134  *    that are builtin the sources.  Returns FALSE on error.
 135  *
 136  ***/
 137 SilcBool silc_hash_register(const SilcHashObject *hash);
 138
 139 /****f* silccrypt/SilcHashAPI/silc_hash_unregister
 140  *
 141  * SYNOPSIS
 142  *
 143  *    SilcBool silc_hash_unregister(SilcHashObject *hash);
 144  *
 145  * DESCRIPTION
 146  *
 147  *    Unregister a hash function from SILC by the SilcHashObject `hash'.
 148  *    This should be called for all registered hash functions.  Returns
 149  *    FALSE on error.
 150  *
 151  ***/
 152 SilcBool silc_hash_unregister(SilcHashObject *hash);
 153
 154 /****f* silccrypt/SilcHashAPI/silc_hash_register_default
 155  *
 156  * SYNOPSIS
 157  *
 158  *    SilcBool silc_hash_register_default(void);
 159  *
 160  * DESCRIPTION
 161  *
 162  *    Registers all default hash functions into the SILC.  These are the
 163  *    hash functions that are builtin in the sources.  See the list of
 164  *    default hash functions in the silchash.c source file.  The application
 165  *    may use this to register default hash functions if specific hash
 166  *    function in any specific order is not wanted (application's
 167  *    configuration usually may decide the order of the registration, in
 168  *    which case this function should not be used).
 169  *
 170  ***/
 171 SilcBool silc_hash_register_default(void);
 172
 173 /****f* silccrypt/SilcHashAPI/silc_hash_unregister_all
 174  *
 175  * SYNOPSIS
 176  *
 177  *    SilcBool silc_hash_unregister_all(void);
 178  *
 179  * DESCRIPTION
 180  *
 181  *    Unregisters all registered hash functions.
 182  *
 183  ***/
 184 SilcBool silc_hash_unregister_all(void);
 185
 186 /****f* silccrypt/SilcHashAPI/silc_hash_alloc
 187  *
 188  * SYNOPSIS
 189  *
 190  *    SilcBool silc_hash_alloc(const char *name, SilcHash *new_hash);
 191  *
 192  * DESCRIPTION
 193  *
 194  *    Allocates a new SilcHash object of name of `name'.  The new allocated
 195  *    hash function is returned into `new_hash' pointer.  This function
 196  *    returns FALSE if such hash function does not exist.
 197  *
 198  ***/
 199 SilcBool silc_hash_alloc(const char *name, SilcHash *new_hash);
 200
 201 /****f* silccrypt/SilcHashAPI/silc_hash_alloc_by_oid
 202  *
 203  * SYNOPSIS
 204  *
 205  *    SilcBool silc_hash_alloc_by_oid(const char *oid, SilcHash *new_hash);
 206  *
 207  * DESCRIPTION
 208  *
 209  *    Same as silc_hash_alloc but allocates the hash algorithm by the
 210  *    hash algorithm OID string indicated by `oid'. Returns FALSE if such
 211  *    hash function does not exist.
 212  *
 213  ***/
 214 SilcBool silc_hash_alloc_by_oid(const char *oid, SilcHash *new_hash);
 215
 216 /****f* silccrypt/SilcHashAPI/silc_hash_free
 217  *
 218  * SYNOPSIS
 219  *
 220  *    void silc_hash_free(SilcHash hash);
 221  *
 222  * DESCRIPTION
 223  *
 224  *    Frees the allocated hash function context.
 225  *
 226  ***/
 227 void silc_hash_free(SilcHash hash);
 228
 229 /****f* silccrypt/SilcHashAPI/silc_hash_is_supported
 230  *
 231  * SYNOPSIS
 232  *
 233  *    SilcBool silc_hash_is_supported(const char *name);
 234  *
 235  * DESCRIPTION
 236  *
 237  *    Returns TRUE if the hash function indicated by the `name' exists.
 238  *
 239  ***/
 240 SilcBool silc_hash_is_supported(const char *name);
 241
 242 /****f* silccrypt/SilcHashAPI/silc_hash_get_supported
 243  *
 244  * SYNOPSIS
 245  *
 246  *    char *silc_hash_get_supported(void);
 247  *
 248  * DESCRIPTION
 249  *
 250  *    Returns comma (`,') separated list of registered hash functions  This
 251  *    is used for example when sending supported hash function list during
 252  *    the SILC Key Exchange protocol (SKE).  The caller must free the returned
 253  *    pointer.
 254  *
 255  ***/
 256 char *silc_hash_get_supported(void);
 257
 258 /****f* silccrypt/SilcHashAPI/silc_hash_len
 259  *
 260  * SYNOPSIS
 261  *
 262  *    SilcUInt32 silc_hash_len(SilcHash hash);
 263  *
 264  * DESCRIPTION
 265  *
 266  *    Returns the length of the message digest the hash function produce.
 267  *
 268  ***/
 269 SilcUInt32 silc_hash_len(SilcHash hash);
 270
 271 /****f* silccrypt/SilcHashAPI/silc_hash_block_len
 272  *
 273  * SYNOPSIS
 274  *
 275  *    SilcUInt32 silc_hash_block_len(SilcHash hash);
 276  *
 277  * DESCRIPTION
 278  *
 279  *    Returns the block length of the hash function.
 280  *
 281  ***/
 282 SilcUInt32 silc_hash_block_len(SilcHash hash);
 283
 284 /****f* silccrypt/SilcHashAPI/silc_hash_get_name
 285  *
 286  * SYNOPSIS
 287  *
 288  *    const char *silc_hash_get_name(SilcHash hash);
 289  *
 290  * DESCRIPTION
 291  *
 292  *    Returns the name of the hash function indicated by the `hash' context.
 293  *
 294  ***/
 295 const char *silc_hash_get_name(SilcHash hash);
 296
 297 /****f* silccrypt/SilcHashAPI/silc_hash_get_oid
 298  *
 299  * SYNOPSIS
 300  *
 301  *    const char *silc_hash_get_name(SilcHash hash);
 302  *
 303  * DESCRIPTION
 304  *
 305  *    Returns the hash OID string.  Returns NULL if the hash doesn't have
 306  *    OID string.  Use strlen() to get the OID string length.
 307  *
 308  ***/
 309 const char *silc_hash_get_oid(SilcHash hash);
 310
 311 /****f* silccrypt/SilcHashAPI/silc_hash_make
 312  *
 313  * SYNOPSIS
 314  *
 315  *    void silc_hash_make(SilcHash hash, const unsigned char *data,
 316  *                        SilcUInt32 len, unsigned char *return_hash);
 317  *
 318  * DESCRIPTION
 319  *
 320  *    Computes the message digest (hash) out of the data indicated by
 321  *    `data' of length of `len' bytes.  Returns the message digest to the
 322  *    `return_hash' buffer which must be at least of the size of the
 323  *    message digest the `hash' produces.
 324  *
 325  ***/
 326 void silc_hash_make(SilcHash hash, const unsigned char *data,
 327                     SilcUInt32 len, unsigned char *return_hash);
 328
 329 /****f* silccrypt/SilcHashAPI/silc_hash_init
 330  *
 331  * SYNOPSIS
 332  *
 333  *    void silc_hash_init(SilcHash hash);
 334  *
 335  * DESCRIPTION
 336  *
 337  *    Sometimes calling the silc_hash_make might not be the most optimal
 338  *    case of computing digests.  If you have a lot of different data
 339  *    that you need to put together for computing a digest you may either
 340  *    put them into a buffer and compute the digest from the buffer by
 341  *    calling the silc_hash_make, or you can use the silc_hash_init,
 342  *    silc_hash_update and silc_hash_final to do the digest.  This function
 343  *    prepares the allocated hash function context for this kind of digest
 344  *    computation.  To add the data to be used in the digest computation
 345  *    call the silc_hash_update function.
 346  *
 347  ***/
 348 void silc_hash_init(SilcHash hash);
 349
 350 /****f* silccrypt/SilcHashAPI/silc_hash_update
 351  *
 352  * SYNOPSIS
 353  *
 354  *    void silc_hash_update(SilcHash hash, const unsigned char *data,
 355  *                          SilcUInt32 data_len);
 356  *
 357  * DESCRIPTION
 358  *
 359  *    This function may be called to add data to be used in the digest
 360  *    computation.  This can be called multiple times to add data from
 361  *    many sources before actually computing the digest.  Once you've
 362  *    added all the data you need you can call the silc_hash_final to
 363  *    actually produce the message digest value.
 364  *
 365  * EXAMPLE
 366  *
 367  *    unsigned char digest[20];
 368  *
 369  *    silc_hash_init(hash);
 370  *    silc_hash_update(hash, data, data_len);
 371  *    silc_hash_update(hash, more_data, more_data_len);
 372  *    silc_hash_final(hash, digest);
 373  *
 374  ***/
 375 void silc_hash_update(SilcHash hash, const unsigned char *data,
 376                       SilcUInt32 data_len);
 377
 378 /****f* silccrypt/SilcHashAPI/silc_hash_final
 379  *
 380  * SYNOPSIS
 381  *
 382  *    void silc_hash_final(SilcHash hash, unsigned char *return_hash);
 383  *
 384  * DESCRIPTION
 385  *
 386  *    This function is used to produce the final message digest from
 387  *    the data that has been added to the hash function context by calling
 388  *    the silc_hash_update function.  The digest is copied in to the
 389  *    `return_hash' pointer which must be at least the size that
 390  *    the silc_hash_len returns.
 391  *
 392  ***/
 393 void silc_hash_final(SilcHash hash, unsigned char *return_hash);
 394
 395 /****f* silccrypt/SilcHashAPI/silc_hash_transform
 396  *
 397  * SYNOPSIS
 398  *
 399  *    void silc_hash_transform(SilcHash hash, void *state,
 400  *                             const unsigned char *data);
 401  *
 402  * DESCRIPTION
 403  *
 404  *    This is special function for calling the hash function's internal
 405  *    digest generation function.  The size of the `state' array and the
 406  *    sizeof the `data' buffer is hash function specific and must be
 407  *    known by the caller.  Usually this function is not needed.
 408  *
 409  ***/
 410 void silc_hash_transform(SilcHash hash, void *state,
 411                          const unsigned char *data);
 412
 413 /****f* silccrypt/SilcHashAPI/silc_hash_fingerprint
 414  *
 415  * SYNOPSIS
 416  *
 417  *    char *silc_hash_fingerprint(SilcHash hash, const unsigned char *data,
 418  *                                SilcUInt32 data_len);
 419  *
 420  * DESCRIPTION
 421  *
 422  *    Utility function which can be used to create a textual fingerprint
 423  *    out of the data indicated by `data' of length of `data_len' bytes.
 424  *    If `hash' is NULL then SHA1 hash function is used automatically.
 425  *    The caller must free the returned string.
 426  *
 427  *    Example output could be:
 428  *      41BF 5C2E 4149 039A 3917  831F 65C4 0A69 F98B 0A4D
 429  *
 430  ***/
 431 char *silc_hash_fingerprint(SilcHash hash, const unsigned char *data,
 432                             SilcUInt32 data_len);
 433
 434 /****f* silccrypt/SilcHashAPI/silc_hash_babbleprint
 435  *
 436  * SYNOPSIS
 437  *
 438  *    char *silc_hash_babbleprint(SilcHash hash, const unsigned char *data,
 439  *                                SilcUInt32 data_len);
 440  *
 441  * DESCRIPTION
 442  *
 443  *    Utility function which can be used to create a textual babbleprint
 444  *    out of the data indicated by `data' of length of `data_len' bytes.
 445  *    If `hash' is NULL then SHA1 hash function is used automatically.
 446  *    The caller must free the returned string.
 447  *
 448  *    The babbleprint is same as fingerprint but encoded in a form which
 449  *    makes it easier to pronounce.  When verifying fingerprint for example
 450  *    over a phone call, the babbleprint makes it easier to read the
 451  *    fingerprint.
 452  *
 453  *    Example output could be:
 454  *      xiber-zulad-vubug-noban-puvyc-labac-zonos-gedik-novem-rudog-tyxix
 455  *
 456  ***/
 457 char *silc_hash_babbleprint(SilcHash hash, const unsigned char *data,
 458                             SilcUInt32 data_len);
 459
 460 #endif