lib/silccrypt/silchash.h

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