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