lib/silccrypt/silcpkcs.h

   1 /*
   2
   3   silcpkcs.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 /****h* silccrypt/SILC PKCS Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * SILC PKCS API provides generic interface for performing various
  25  * public key cryptography related operations with different types of
  26  * public and private keys.  Support for loading and saving of different
  27  * types of public key and private keys are also provided.
  28  *
  29  ***/
  30
  31 #ifndef SILCPKCS_H
  32 #define SILCPKCS_H
  33
  34 /* Forward declarations */
  35 typedef struct SilcPKCSAlgorithmStruct SilcPKCSAlgorithm;
  36 typedef struct SilcPKCSObjectStruct SilcPKCSObject;
  37
  38 /****d* silccrypt/SilcPKCSAPI/SilcPKCSType
  39  *
  40  * NAME
  41  *
  42  *    typedef enum { ... } SilcPKCSType;
  43  *
  44  * DESCRIPTION
  45  *
  46  *    Supported public key cryptosystem types.
  47  *
  48  * SOURCE
  49  */
  50 typedef enum {
  51   SILC_PKCS_SILC    = 1,        /* SILC PKCS */
  52   SILC_PKCS_SSH2    = 2,        /* SSH2 PKCS */
  53   SILC_PKCS_X509V3  = 3,        /* X.509v3 PKCS */
  54   SILC_PKCS_OPENPGP = 4,        /* OpenPGP PKCS */
  55   SILC_PKCS_SPKI    = 5,        /* SPKI PKCS (not supported) */
  56   SILC_PKCS_ANY     = 0,
  57 } SilcPKCSType;
  58 /***/
  59
  60 /****s* silccrypt/SilcPKCSAPI/SilcPublicKey
  61  *
  62  * NAME
  63  *
  64  *    typedef struct { ... } *SilcPublicKey;
  65  *
  66  * DESCRIPTION
  67  *
  68  *    This context represents any kind of PKCS public key.  It can be
  69  *    allocated by silc_pkcs_public_key_alloc or silc_pkcs_load_public_key
  70  *    and is freed by the silc_pkcs_public_key_free.  The PKCS specific
  71  *    public key context can be retrieved by calling
  72  *    silc_pkcs_public_key_get_pkcs.
  73  *
  74  * SOURCE
  75  */
  76 typedef struct SilcPublicKeyStruct {
  77   SilcPKCSObject *pkcs;         /* PKCS */
  78   const SilcPKCSAlgorithm *alg; /* PKCS algorithm */
  79   void *public_key;             /* PKCS specific public key */
  80 } *SilcPublicKey;
  81 /***/
  82
  83 /****s* silccrypt/SilcPKCSAPI/SilcPrivateKey
  84  *
  85  * NAME
  86  *
  87  *    typedef struct { ... } *SilcPrivateKey;
  88  *
  89  * DESCRIPTION
  90  *
  91  *    This context represents any kind of PKCS private key.  It can be
  92  *    allocated by silc_pkcs_private_key_alloc or more commonly by calling
  93  *    silc_pkcs_load_private_key.  The PKCS specific key context can be
  94  *    retrieved by calling silc_pkcs_private_key_get_pkcs.
  95  *
  96  * SOURCE
  97  */
  98 typedef struct SilcPrivateKeyStruct {
  99   SilcPKCSObject *pkcs;         /* PKCS */
 100   const SilcPKCSAlgorithm *alg; /* PKCS algorithm */
 101   void *private_key;            /* PKCS specific private key */
 102 } *SilcPrivateKey;
 103 /***/
 104
 105 /****d* silccrypt/SilcPKCSAPI/SilcPKCSFileEncoding
 106  *
 107  * NAME
 108  *
 109  *    typedef enum { ... } SilcPKCSType
 110  *
 111  * DESCRIPTION
 112  *
 113  *    Public and private key file encoding types.
 114  *
 115  * SOURCE
 116  */
 117 typedef enum {
 118   SILC_PKCS_FILE_BIN,           /* Binary encoding */
 119   SILC_PKCS_FILE_BASE64         /* Base64 encoding */
 120 } SilcPKCSFileEncoding;
 121 /***/
 122
 123 /****f* silccrypt/SilcPKCSAPI/SilcPKCSEncryptCb
 124  *
 125  * SYNOPSIS
 126  *
 127  *    typedef void (*SilcPKCSEncryptCb)(SilcBool success,
 128  *                                      const unsigned char *encrypted,
 129  *                                      SilcUInt32 encrypted_len,
 130  *                                      void *context);
 131  *
 132  * DESCRIPTION
 133  *
 134  *    Encryption callback.  This callback is given as argument to the
 135  *    silc_pkcs_encrypt and the encrypted data is delivered to the caller
 136  *    in this callback.  The `encrypted' is the encrypted data.  If the
 137  *    `success' is FALSE the encryption operation failed.
 138  *
 139  ***/
 140 typedef void (*SilcPKCSEncryptCb)(SilcBool success,
 141                                   const unsigned char *encrypted,
 142                                   SilcUInt32 encrypted_len,
 143                                   void *context);
 144
 145 /****f* silccrypt/SilcPKCSAPI/SilcPKCSDecryptCb
 146  *
 147  * SYNOPSIS
 148  *
 149  *    typedef void (*SilcPKCSDecryptCb)(SilcBool success,
 150  *                                      const unsigned char *decrypted,
 151  *                                      SilcUInt32 decrypted_len,
 152  *                                      void *context);
 153  *
 154  * DESCRIPTION
 155  *
 156  *    Decryption callback.  This callback is given as argument to the
 157  *    silc_pkcs_decrypt and the decrypted data is delivered to the caller
 158  *    in this callback.  The `decrypted' is the decrypted data.  If the
 159  *    `success' is FALSE the decryption operation failed.
 160  *
 161  ***/
 162 typedef void (*SilcPKCSDecryptCb)(SilcBool success,
 163                                   const unsigned char *decrypted,
 164                                   SilcUInt32 decrypted_len,
 165                                   void *context);
 166
 167 /****f* silccrypt/SilcPKCSAPI/SilcPKCSSignCb
 168  *
 169  * SYNOPSIS
 170  *
 171  *    typedef void (*SilcPKCSSignCb)(SilcBool success,
 172  *                                   const unsigned char *signature,
 173  *                                   SilcUInt32 signature_len,
 174  *                                   void *context);
 175  *
 176  * DESCRIPTION
 177  *
 178  *    Signature callback.  This callback is given as argument to the
 179  *    silc_pkcs_sign and the digitally signed data is delivered to the caller
 180  *    in this callback.  The `signature' is the signature data.  If the
 181  *    `success' is FALSE the signature operation failed.
 182  *
 183  ***/
 184 typedef void (*SilcPKCSSignCb)(SilcBool success,
 185                                const unsigned char *signature,
 186                                SilcUInt32 signature_len,
 187                                void *context);
 188
 189 /****f* silccrypt/SilcPKCSAPI/SilcPKCSVerifyCb
 190  *
 191  * SYNOPSIS
 192  *
 193  *    typedef void (*SilcPKCSVerifyCb)(SilcBool success, void *context);
 194  *
 195  * DESCRIPTION
 196  *
 197  *    Verification callback.  This callback is given as argument to the
 198  *    silc_pkcs_verify and the result of the signature verification is
 199  *    deliver to the caller in this callback.  If the `success' is FALSE
 200  *    the signature verification failed.
 201  *
 202  ***/
 203 typedef void (*SilcPKCSVerifyCb)(SilcBool success, void *context);
 204
 205 #include "silcpkcs_i.h"
 206
 207 /* Marks for all PKCS in. This can be used in silc_pkcs_unregister to
 208    unregister all PKCS at once. */
 209 #define SILC_ALL_PKCS ((SilcPKCSObject *)1)
 210 #define SILC_ALL_PKCS_ALG ((SilcPKCSAlgorithm *)1)
 211
 212 /* Static lists of PKCS and PKCS algorithms. */
 213 extern DLLAPI const SilcPKCSObject silc_default_pkcs[];
 214 extern DLLAPI const SilcPKCSAlgorithm silc_default_pkcs_alg[];
 215
 216 /* Prototypes */
 217
 218 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_register
 219  *
 220  * SYNOPSIS
 221  *
 222  *    SilcBool silc_pkcs_register(const SilcPKCSObject *pkcs);
 223  *
 224  * DESCRIPTION
 225  *
 226  *    Registers a new PKCS into the crypto library.  This function is used
 227  *    at the initialization of an application.  All registered PKCSs
 228  *    should be unregistered with silc_pkcs_unregister.  The `pkcs' includes
 229  *    the name of the PKCS and member functions for the algorithm.  Usually
 230  *    this function is not called directly.  Instead, application can call
 231  *    the silc_pkcs_register_default to register all PKCSs that are
 232  *    builtin the sources.  Returns FALSE on error.
 233  *
 234  ***/
 235 SilcBool silc_pkcs_register(const SilcPKCSObject *pkcs);
 236
 237 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_unregister
 238  *
 239  * SYNOPSIS
 240  *
 241  *    SilcBool silc_pkcs_unregister(SilcPKCSObject *pkcs);
 242  *
 243  * DESCRIPTION
 244  *
 245  *    Unregister a PKCS from the crypto library. Returns FALSE on error.
 246  *
 247  ***/
 248 SilcBool silc_pkcs_unregister(SilcPKCSObject *pkcs);
 249
 250 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_algorithm_register
 251  *
 252  * SYNOPSIS
 253  *
 254  *    SilcBool silc_pkcs_algorithm_register(const SilcPKCSAlgorithm *pkcs);
 255  *
 256  * DESCRIPTION
 257  *
 258  *    Registers a new PKCS Algorithm into crypto library.  This function
 259  *    is used at the initialization of an application.  All registered PKCS
 260 *     algorithms should be unregistered with silc_pkcs_unregister.
 261  *
 262  ***/
 263 SilcBool silc_pkcs_algorithm_register(const SilcPKCSAlgorithm *pkcs);
 264
 265 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_algorithm_unregister
 266  *
 267  * SYNOPSIS
 268  *
 269  *    SilcBool silc_pkcs_algorithm_unregister(SilcPKCSAlgorithm *pkcs);
 270  *
 271  * DESCRIPTION
 272  *
 273  *    Unregister a PKCS from the crypto library. Returns FALSE on error.
 274  *
 275  ***/
 276 SilcBool silc_pkcs_algorithm_unregister(SilcPKCSAlgorithm *pkcs);
 277
 278 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_register_default
 279  *
 280  * SYNOPSIS
 281  *
 282  *    SilcBool silc_pkcs_register_default(void);
 283  *
 284  * DESCRIPTION
 285  *
 286  *    Registers all the default PKCS (all builtin PKCS) and PKCS algorithms.
 287  *    The application may use this to register the default PKCS if specific
 288  *    PKCS in any specific order is not wanted.  Returns FALSE on error.
 289  *
 290  ***/
 291 SilcBool silc_pkcs_register_default(void);
 292
 293 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_unregister_all
 294  *
 295  * SYNOPSIS
 296  *
 297  *    SilcBool silc_pkcs_unregister_all(void);
 298  *
 299  * DESCRIPTION
 300  *
 301  *    Unregister all PKCS and PKCS algorithms. Returns FALSE on error.
 302  *
 303  ***/
 304 SilcBool silc_pkcs_unregister_all(void);
 305
 306 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_supported
 307  *
 308  * SYNOPSIS
 309  *
 310  *    char *silc_pkcs_get_supported(void);
 311  *
 312  * DESCRIPTION
 313  *
 314  *    Returns comma separated list of supported PKCS algorithms.
 315  *
 316  ***/
 317 char *silc_pkcs_get_supported(void);
 318
 319 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_find_pkcs
 320  *
 321  * SYNOPSIS
 322  *
 323  *    const SilcPKCSObject *silc_pkcs_get_pkcs(SilcPKCSType type);
 324  *
 325  * DESCRIPTION
 326  *
 327  *    Finds PKCS context by the PKCS type.
 328  *
 329  ***/
 330 const SilcPKCSObject *silc_pkcs_find_pkcs(SilcPKCSType type);
 331
 332 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_find_algorithm
 333  *
 334  * SYNOPSIS
 335  *
 336  *    const SilcPKCSAlgorithm *silc_pkcs_find_algorithm(const char *algorithm,
 337  *                                                      const char *scheme);
 338  *
 339  * DESCRIPTION
 340  *
 341  *    Finds PKCS algorithm context by the algorithm name `algorithm' and
 342  *    the algorithm scheme `scheme'.  The `scheme' may be NULL.
 343  *
 344  ***/
 345 const SilcPKCSAlgorithm *silc_pkcs_find_algorithm(const char *algorithm,
 346                                                   const char *scheme);
 347
 348 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_pkcs
 349  *
 350  * SYNOPSIS
 351  *
 352  *    const SilcPKCSObject *silc_pkcs_get_pkcs(void *key);
 353  *
 354  * DESCRIPTION
 355  *
 356  *    Returns the PKCS object from `key', which may be SilcPublicKey or
 357  *    SilcPrivateKey pointer.
 358  *
 359  ***/
 360 const SilcPKCSObject *silc_pkcs_get_pkcs(void *key);
 361
 362 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_algorithm
 363  *
 364  * SYNOPSIS
 365  *
 366  *    const SilcPKCSAlgorithm *silc_pkcs_get_algorithm(void *key);
 367  *
 368  * DESCRIPTION
 369  *
 370  *    Returns the PKCS algorithm object from `key', which may be SilcPublicKey
 371  *    or SilcPrivateKey pointer.
 372  *
 373  ***/
 374 const SilcPKCSAlgorithm *silc_pkcs_get_algorithm(void *key);
 375
 376 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_name
 377  *
 378  * SYNOPSIS
 379  *
 380  *    const char *silc_pkcs_get_name(void *key);
 381  *
 382  * DESCRIPTION
 383  *
 384  *    Returns PKCS algorithm name from the `key', which may be SilcPublicKey
 385  *    or SilcPrivateKey pointer.
 386  *
 387  ***/
 388 const char *silc_pkcs_get_name(void *key);
 389
 390 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_type
 391  *
 392  * SYNOPSIS
 393  *
 394  *    SilcPKCSType silc_pkcs_get_type(void *key);
 395  *
 396  * DESCRIPTION
 397  *
 398  *    Returns PKCS type from the `key', which may be SilcPublicKey or
 399  *    SilcPrivateKey pointer.
 400  *
 401  ***/
 402 SilcPKCSType silc_pkcs_get_type(void *key);
 403
 404 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_get_pkcs
 405  *
 406  * SYNOPSIS
 407  *
 408  *    void *silc_pkcs_public_key_get_pkcs(SilcPKCSType type,
 409  *                                        SilcPublicKey public_key);
 410  *
 411  * DESCRIPTION
 412  *
 413  *    Returns the internal PKCS `type' specific public key context from the
 414  *    `public_key'.  The caller needs to explicitly type cast it to correct
 415  *    type.  Returns NULL on error.
 416  *
 417  *    For SILC_PKCS_SILC the returned context is SilcSILCPublicKey.
 418  *    For SILC_PKCS_SSH2 the returned context is SilcSshPublicKey.
 419  *
 420  ***/
 421 void *silc_pkcs_public_key_get_pkcs(SilcPKCSType type,
 422                                     SilcPublicKey public_key);
 423
 424 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_get_pkcs
 425  *
 426  * SYNOPSIS
 427  *
 428  *    void *silc_pkcs_private_key_get_pkcs(SilcPKCSType type,
 429  *                                        SilcPublicKey public_key);
 430  *
 431  * DESCRIPTION
 432  *
 433  *    Returns the internal PKCS `type' specific private key context from the
 434  *    `private_key'.  The caller needs to explicitly type cast it to correct
 435  *    type.  Returns NULL on error.
 436  *
 437  *    For SILC_PKCS_SILC the returned context is SilcSILCPrivateKey.
 438  *    For SILC_PKCS_SSH2 the returned context is SilcSshPrivateKey.
 439  *
 440  ***/
 441 void *silc_pkcs_private_key_get_pkcs(SilcPKCSType type,
 442                                      SilcPrivateKey private_key);
 443
 444 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_alloc
 445  *
 446  * SYNOPSIS
 447  *
 448  *    SilcBool silc_pkcs_public_key_alloc(SilcPKCSType type,
 449  *                                        unsigned char *key,
 450  *                                        SilcUInt32 key_len
 451  *                                        SilcPublicKey *ret_public_key);
 452  *
 453  * DESCRIPTION
 454  *
 455  *    Allocates SilcPublicKey of the type of `type' from the key data
 456  *    `key' of length of `key_len' bytes.  Returns FALSE if the `key'
 457  *    is malformed or unsupported public key type.  This function can be
 458  *    used to create public key from any kind of PKCS public keys that
 459  *    the implementation supports.
 460  *
 461  ***/
 462 SilcBool silc_pkcs_public_key_alloc(SilcPKCSType type,
 463                                     unsigned char *key,
 464                                     SilcUInt32 key_len,
 465                                     SilcPublicKey *ret_public_key);
 466
 467 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_free
 468  *
 469  * SYNOPSIS
 470  *
 471  *    void silc_pkcs_public_key_free(SilcPublicKey public_key);
 472  *
 473  * DESCRIPTION
 474  *
 475  *    Frees the public key.  This will also automatically free the underlaying
 476  *    PKCS specific public key.  All public keys allocated through the
 477  *    PKCS API must be freed by calling this function.
 478  *
 479  ***/
 480 void silc_pkcs_public_key_free(SilcPublicKey public_key);
 481
 482 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_export
 483  *
 484  * SYNOPSIS
 485  *
 486  *    unsigned char *silc_pkcs_public_key_encode(SilcStack stack,
 487  *                                               SilcPublicKey public_key,
 488  *                                               SilcUInt32 *ret_len);
 489  *
 490  * DESCRIPTION
 491  *
 492  *    Encodes the `public_key' into a binary format and returns it.  Returns
 493  *    NULL on error.  Caller must free the returned buffer.
 494  *
 495  *    If the `stack' is non-NULL the returned buffer is allocated from the
 496  *    `stack'.  This call will consume `stack' so caller should push the stack
 497  *    before calling and then later pop it.
 498  *
 499  ***/
 500 unsigned char *silc_pkcs_public_key_encode(SilcStack stack,
 501                                            SilcPublicKey public_key,
 502                                            SilcUInt32 *ret_len);
 503
 504 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_get_len
 505  *
 506  * SYNOPSIS
 507  *
 508  *    SilcUInt32 silc_pkcs_public_key_get_len(SilcPublicKey public_key);
 509  *
 510  * DESCRIPTION
 511  *
 512  *    Returns the key length in bits from the public key.
 513  *
 514  ***/
 515 SilcUInt32 silc_pkcs_public_key_get_len(SilcPublicKey public_key);
 516
 517 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_compare
 518  *
 519  * SYNOPSIS
 520  *
 521  *    SilcBool silc_pkcs_public_key_compare(SilcPublicKey key1,
 522  *                                          SilcPublicKey key2);
 523  *
 524  * DESCRIPTION
 525  *
 526  *    Compares two public keys and returns TRUE if they are same key, and
 527  *    FALSE if they are not same.
 528  *
 529  ***/
 530 SilcBool silc_pkcs_public_key_compare(SilcPublicKey key1, SilcPublicKey key2);
 531
 532 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_copy
 533  *
 534  * SYNOPSIS
 535  *
 536  *    SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
 537  *
 538  * DESCRIPTION
 539  *
 540  *    Copies the public key indicated by `public_key' and returns new
 541  *    allocated public key which is indentical to the `public_key'.
 542  *
 543  ***/
 544 SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
 545
 546 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_alloc
 547  *
 548  * SYNOPSIS
 549  *
 550  *    SilcBool silc_pkcs_private_key_alloc(SilcPKCSType type,
 551  *                                         unsigned char *key,
 552  *                                         SilcUInt32 key_len,
 553  *                                         SilcPrivateKey *ret_private_key);
 554  *
 555  * DESCRIPTION
 556  *
 557  *    Allocates SilcPrivateKey of the type of `type' from the key data
 558  *    `key' of length of `key_len' bytes.  Returns FALSE if the `key'
 559  *    is malformed or unsupported private key type.
 560  *
 561  *    Usually this function is not needed.  Typical application calls
 562  *    silc_pkcs_load_private_key instead.
 563  *
 564  ***/
 565 SilcBool silc_pkcs_private_key_alloc(SilcPKCSType type,
 566                                      unsigned char *key,
 567                                      SilcUInt32 key_len,
 568                                      SilcPrivateKey *ret_private_key);
 569
 570 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_get_len
 571  *
 572  * SYNOPSIS
 573  *
 574  *    SilcUInt32 silc_pkcs_private_key_get_len(SilcPrivateKey private_key);
 575  *
 576  * DESCRIPTION
 577  *
 578  *    Returns the key length in bits from the private key.
 579  *
 580  ***/
 581 SilcUInt32 silc_pkcs_private_key_get_len(SilcPrivateKey private_key);
 582
 583 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_free
 584  *
 585  * SYNOPSIS
 586  *
 587  *    void silc_pkcs_private_key_free(SilcPrivateKey private_key;
 588  *
 589  * DESCRIPTION
 590  *
 591  *    Frees the public key.  This will also automatically free the underlaying
 592  *    PKCS specific private key.  All private keys allocated through the
 593  *    PKCS API must be freed by calling this function.
 594  *
 595  ***/
 596 void silc_pkcs_private_key_free(SilcPrivateKey private_key);
 597
 598 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_encrypt
 599  *
 600  * SYNOPSIS
 601  *
 602  *    SilcAsyncOperation silc_pkcs_encrypt(SilcPublicKey public_key,
 603  *                                         unsigned char *src,
 604  *                                         SilcUInt32 src_len, SilcRng rng,
 605  *                                         SilcPKCSEncryptCb encrypt_cb,
 606  *                                         void *context);
 607  *
 608  * DESCRIPTION
 609  *
 610  *    Encrypts with the public key.  The `encrypt_cb' will be called to
 611  *    deliver the encrypted data.  The encryption operation may be asynchronous
 612  *    if the `public_key' is accelerated public key.  If this returns NULL
 613  *    the asynchronous operation cannot be controlled.
 614  *
 615  ***/
 616 SilcAsyncOperation silc_pkcs_encrypt(SilcPublicKey public_key,
 617                                      unsigned char *src,
 618                                      SilcUInt32 src_len, SilcRng rng,
 619                                      SilcPKCSEncryptCb encrypt_cb,
 620                                      void *context);
 621
 622 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_decrypt
 623  *
 624  * SYNOPSIS
 625  *
 626  *    SilcAsyncOperation silc_pkcs_decrypt(SilcPrivateKey private_key,
 627  *                                         unsigned char *src,
 628  *                                         SilcUInt32 src_len,
 629  *                                         SilcPKCSDecryptCb decrypt_cb,
 630  *                                         void *context);
 631  *
 632  * DESCRIPTION
 633  *
 634  *    Decrypts with the private key.  The `decrypt_cb' will be called to
 635  *    deliver the decrypted data.  The decryption operation may be asynchronous
 636  *    if the `private_key' is accelerated private key.  If this returns NULL
 637  *    the asynchronous operation cannot be controlled.
 638  *
 639  ***/
 640 SilcAsyncOperation silc_pkcs_decrypt(SilcPrivateKey private_key,
 641                                      unsigned char *src, SilcUInt32 src_len,
 642                                      SilcPKCSDecryptCb decrypt_cb,
 643                                      void *context);
 644
 645 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_sign
 646  *
 647  * SYNOPSIS
 648  *
 649  *    SilcAsyncOperation silc_pkcs_sign(SilcPrivateKey private_key,
 650  *                                      unsigned char *src,
 651  *                                      SilcUInt32 src_len,
 652  *                                      SilcBool compute_hash,
 653  *                                      SilcHash hash,
 654  *                                      SilcRng rng,
 655  *                                      SilcPKCSSignCb sign_cb,
 656  *                                      void *context);
 657  *
 658  * DESCRIPTION
 659  *
 660  *    Computes signature with the private key.  The `sign_cb' will be called
 661  *    to deliver the signature data.  If `compute_hash' is TRUE the `hash'
 662  *    will be used to compute a message digest over the `src'.  The `hash'
 663  *    must always be valid.  The `rng' should always be provided.  The
 664  *    signature operation may be asynchronous if the `private_key' is
 665  *    accelerated private key.  If this returns NULL the asynchronous
 666  *    operation cannot be controlled.
 667  *
 668  ***/
 669 SilcAsyncOperation silc_pkcs_sign(SilcPrivateKey private_key,
 670                                   unsigned char *src,
 671                                   SilcUInt32 src_len,
 672                                   SilcBool compute_hash,
 673                                   SilcHash hash,
 674                                   SilcRng rng,
 675                                   SilcPKCSSignCb sign_cb,
 676                                   void *context);
 677
 678 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_verify
 679  *
 680  * SYNOPSIS
 681  *
 682  *    SilcAsyncOperation silc_pkcs_verify(SilcPublicKey public_key,
 683  *                                        unsigned char *signature,
 684  *                                        SilcUInt32 signature_len,
 685  *                                        unsigned char *data,
 686  *                                        SilcUInt32 data_len,
 687  *                                        SilcHash hash,
 688  *                                        SilcPKCSVerifyCb verify_cb,
 689  *                                        void *context);
 690  *
 691  * DESCRIPTION
 692  *
 693  *    Verifies signature.  The `verify_cb' will be called to deliver the
 694  *    result of the verification process.  The 'signature' is verified against
 695  *    the 'data'.  If the `hash' is non-NULL then the `data' will hashed
 696  *    before verification.  If the `hash' is NULL, then the hash algorithm
 697  *    to be used is retrieved from the signature.  If it isn't present in the
 698  *    signature the verification is done as is without hashing.  The `rng'
 699  *    is usually not needed and may be NULL.  If this returns NULL the
 700  *    asynchronous operation cannot be controlled.
 701  *
 702  ***/
 703 SilcAsyncOperation silc_pkcs_verify(SilcPublicKey public_key,
 704                                     unsigned char *signature,
 705                                     SilcUInt32 signature_len,
 706                                     unsigned char *data,
 707                                     SilcUInt32 data_len,
 708                                     SilcHash hash,
 709                                     SilcPKCSVerifyCb verify_cb,
 710                                     void *context);
 711
 712 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_load_public_key
 713  *
 714  * SYNOPSIS
 715  *
 716  *    SilcBool silc_pkcs_load_public_key(const char *filename,
 717  *                                       SilcPKCSType type,
 718  *                                       SilcPublicKey *ret_public_key);
 719  *
 720  * DESCRIPTION
 721  *
 722  *    Loads public key from file and allocates new public key.  Returns TRUE
 723  *    if loading was successful.  If `type' is SILC_PKSC_ANY this attempts
 724  *    to automatically detect the public key type.  If `type' is some other
 725  *    PKCS type, the key is expected to be of that type.
 726  *
 727  ***/
 728 SilcBool silc_pkcs_load_public_key(const char *filename,
 729                                    SilcPKCSType type,
 730                                    SilcPublicKey *ret_public_key);
 731
 732 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_public_key
 733  *
 734  * SYNOPSIS
 735  *
 736  *    SilcBool silc_pkcs_save_public_key(const char *filename,
 737  *                                       SilcPublicKey public_key,
 738  *                                       SilcPKCSFileEncoding encoding);
 739  *
 740  * DESCRIPTION
 741  *
 742  *    Saves public key into file with specified encoding.  Returns FALSE
 743  *    on error.
 744  *
 745  ***/
 746 SilcBool silc_pkcs_save_public_key(const char *filename,
 747                                    SilcPublicKey public_key,
 748                                    SilcPKCSFileEncoding encoding);
 749
 750 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_load_private_key
 751  *
 752  * SYNOPSIS
 753  *
 754  *    SilcBool silc_pkcs_load_private_key(const char *filename,
 755  *                                        const unsigned char *passphrase,
 756  *                                        SilcUInt32 passphrase_len,
 757  *                                        SilcPKCSType type,
 758  *                                        SilcPrivateKey *ret_private_key);
 759  *
 760  * DESCRIPTION
 761  *
 762  *    Loads private key from file and allocates new private key.  Returns TRUE
 763  *    if loading was successful.  The `passphrase' is used as decryption
 764  *    key of the private key file, in case it is encrypted.  If `type' is
 765  *    SILC_PKSC_ANY this attempts to automatically detect the private key type.
 766  *    If `type' is some other PKCS type, the key is expected to be of that
 767  *    type.
 768  *
 769  ***/
 770 SilcBool silc_pkcs_load_private_key(const char *filename,
 771                                     const unsigned char *passphrase,
 772                                     SilcUInt32 passphrase_len,
 773                                     SilcPKCSType type,
 774                                     SilcPrivateKey *ret_private_key);
 775
 776 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_private_key
 777  *
 778  * SYNOPSIS
 779  *
 780  *    SilcBool silc_pkcs_save_private_key(const char *filename,
 781  *                                        SilcPrivateKey private_key,
 782  *                                        const unsigned char *passphrase,
 783  *                                        SilcUInt32 passphrase_len,
 784  *                                        SilcPKCSFileEncoding encoding,
 785  *                                        SilcRng rng);
 786  *
 787  * DESCRIPTION
 788  *
 789  *    Saves private key into file.  The private key is encrypted into
 790  *    the file with the `passphrase' as a key, if PKCS supports encrypted
 791  *    private keys.  Returns FALSE on error.
 792  *
 793  ***/
 794 SilcBool silc_pkcs_save_private_key(const char *filename,
 795                                     SilcPrivateKey private_key,
 796                                     const unsigned char *passphrase,
 797                                     SilcUInt32 passphrase_len,
 798                                     SilcPKCSFileEncoding encoding,
 799                                     SilcRng rng);
 800
 801 /****f* silccrypt/SilcPKCSAPI/silc_hash_public_key
 802  *
 803  * SYNOPSIS
 804  *
 805  *    SilcUInt32 silc_hash_public_key(void *key, void *user_context);
 806  *
 807  * DESCRIPTION
 808  *
 809  *    An utility function for hashing public key for SilcHashTable.  Give
 810  *    this as argument as the hash function for SilcHashTable.
 811  *
 812  ***/
 813 SilcUInt32 silc_hash_public_key(void *key, void *user_context);
 814
 815 /****f* silccrypt/SilcPKCSAPI/silc_hash_public_key_compare
 816  *
 817  * SYNOPSIS
 818  *
 819  *    SilcBool silc_hash_public_key_compare(void *key1, void *key2,
 820  *                                          void *user_context);
 821  *
 822  * DESCRIPTION
 823  *
 824  *    An utility function for comparing public keys for SilcHashTable.  Give
 825  *    this as argument as the compare function for SilcHashTable.
 826  *
 827  ***/
 828 SilcBool silc_hash_public_key_compare(void *key1, void *key2,
 829                                       void *user_context);
 830
 831 #endif  /* !SILCPKCS_H */