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