lib/silccrypt/silcpkcs.h

   1 /*
   2
   3   silcpkcs.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 /****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/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 /****d* silccrypt/SilcPKCSAlgorithms
  61  *
  62  * NAME
  63  *
  64  *    PKCS Algorithms
  65  *
  66  * DESCRIPTION
  67  *
  68  *    Supported PKCS algorithm names.  These names can be given as argument
  69  *    to silc_pkcs_find_algorithm.  See also SilcPKCSSchemes.
  70  *
  71  * SOURCE
  72  */
  73 #define SILC_PKCS_ALG_RSA    "rsa"         /* RSA algorithm */
  74 #define SILC_PKCS_ALG_DSA    "dsa"         /* DSA algorithm */
  75 /***/
  76
  77 /****d* silccrypt/SilcPKCSSchemes
  78  *
  79  * NAME
  80  *
  81  *    PKCS Algorithm Schemes
  82  *
  83  * DESCRIPTION
  84  *
  85  *    Supported PKCS algorithm scheme names.  Different algorithms can be
  86  *    implemented in different ways to conform differnet standards and
  87  *    protocols.  The scheme defines these ways.  The scheme is given as
  88  *    argument to silc_pkcs_find_algorithm.
  89  *
  90  * SOURCE
  91  */
  92
  93 /* PKCS #1 version 2.x.  This performs RSASSA-PKCS-v1_5 and RSAES-PKCS-v1_5
  94    with hash OID in the signature data (signature with appendix).  This can
  95    be used with SILC_PKCS_ALG_RSA.  Default hash function used with
  96    signatures is SHA-1. */
  97 #define SILC_PKCS_SCHEME_PKCS1          "pkcs1"
  98
  99 /* PKCS #1 version 2.x.  Same as SILC_PKCS_SCHEME_PKCS1 but the hash OID
 100    is not present in the signature data.  This can be used with
 101    SILC_PKCS_ALG_RSA.  Default hash function used with signatures is SHA-1. */
 102 #define SILC_PKCS_SCHEME_PKCS1_NO_OID   "pkcs1-no-oid"
 103
 104 /* The Digital Signature Standard, FIPS 186-3.  The latest DSS standard
 105    version.  The key parameters and hash function used are derived
 106    automatically by the key length and the signature length is variable.
 107    This can be used with SILC_PKCS_ALG_DSA. */
 108 #define SILC_PKCS_SCHEME_DSS            "dss"
 109
 110 /* The Digital Signature Standard, FIPS 186-2.  Same as the
 111    SILC_PKCS_SCHEME_DSS but the signature length is always 160 bits and
 112    hash function used is SHA-1.  This is the most widely used DSS version
 113    (<= year 2008).  This can be used with SILC_PKCS_ALG_DSA.  This is
 114    compatible with SILC_PKCS_ALG_DSS when verifying signatures, but cannot
 115    necessarily create compatible signature. */
 116 #define SILC_PKCS_SCHEME_DSS_FIPS186_2  "dss-fips186-2"
 117
 118 #ifdef SILC_DIST_SSH
 119 /* The SSH2 protocol scheme.  This can be used with SILC_PKCS_ALG_RSA and
 120    SILC_PKCS_ALG_DSA.  When used the algorithms behave as defined in the
 121    SSH2 protocol. */
 122 #define SILC_PKCS_SCHEME_SSH            "ssh"
 123 #endif /* SILC_DIST_SSH */
 124
 125 #ifdef SILC_DIST_PGP
 126 /* The OpenPGP protocol scheme.  This can be used with SILC_PKCS_ALG_RSA and
 127    SILC_PKCS_ALG_DSA.  When used the algorithms behave as defined in the
 128    OpenPGP protocol. */
 129 #define SILC_PKCS_SCHEME_OPENPGP        "openpgp"
 130 #endif /* SILC_DIST_PGP */
 131 /***/
 132
 133 /****s* silccrypt/SilcPublicKey
 134  *
 135  * NAME
 136  *
 137  *    typedef struct { ... } *SilcPublicKey;
 138  *
 139  * DESCRIPTION
 140  *
 141  *    This context represents any kind of PKCS public key.  It can be
 142  *    allocated by silc_pkcs_public_key_alloc or silc_pkcs_load_public_key
 143  *    and is freed by the silc_pkcs_public_key_free.  The PKCS specific
 144  *    public key context can be retrieved by calling
 145  *    silc_pkcs_public_key_get_pkcs.
 146  *
 147  * SOURCE
 148  */
 149 typedef struct SilcPublicKeyStruct {
 150   SilcPKCSObject *pkcs;         /* PKCS */
 151   const SilcPKCSAlgorithm *alg; /* PKCS algorithm */
 152   void *public_key;             /* PKCS specific public key */
 153 } *SilcPublicKey;
 154 /***/
 155
 156 /****s* silccrypt/SilcPrivateKey
 157  *
 158  * NAME
 159  *
 160  *    typedef struct { ... } *SilcPrivateKey;
 161  *
 162  * DESCRIPTION
 163  *
 164  *    This context represents any kind of PKCS private key.  It can be
 165  *    allocated by silc_pkcs_private_key_alloc or more commonly by calling
 166  *    silc_pkcs_load_private_key.  The PKCS specific key context can be
 167  *    retrieved by calling silc_pkcs_private_key_get_pkcs.
 168  *
 169  * SOURCE
 170  */
 171 typedef struct SilcPrivateKeyStruct {
 172   SilcPKCSObject *pkcs;         /* PKCS */
 173   const SilcPKCSAlgorithm *alg; /* PKCS algorithm */
 174   void *private_key;            /* PKCS specific private key */
 175 } *SilcPrivateKey;
 176 /***/
 177
 178 /****d* silccrypt/SilcPKCSFileEncoding
 179  *
 180  * NAME
 181  *
 182  *    typedef enum { ... } SilcPKCSType
 183  *
 184  * DESCRIPTION
 185  *
 186  *    Public and private key file encoding types.
 187  *
 188  * SOURCE
 189  */
 190 typedef enum {
 191   SILC_PKCS_FILE_BIN,           /* Binary encoding */
 192   SILC_PKCS_FILE_BASE64         /* Base64 encoding */
 193 } SilcPKCSFileEncoding;
 194 /***/
 195
 196 /****f* silccrypt/SilcPKCSEncryptCb
 197  *
 198  * SYNOPSIS
 199  *
 200  *    typedef void (*SilcPKCSEncryptCb)(SilcBool success,
 201  *                                      const unsigned char *encrypted,
 202  *                                      SilcUInt32 encrypted_len,
 203  *                                      void *context);
 204  *
 205  * DESCRIPTION
 206  *
 207  *    Encryption callback.  This callback is given as argument to the
 208  *    silc_pkcs_encrypt and the encrypted data is delivered to the caller
 209  *    in this callback.  The `encrypted' is the encrypted data.  If the
 210  *    `success' is FALSE the encryption operation failed.
 211  *
 212  ***/
 213 typedef void (*SilcPKCSEncryptCb)(SilcBool success,
 214                                   const unsigned char *encrypted,
 215                                   SilcUInt32 encrypted_len,
 216                                   void *context);
 217
 218 /****f* silccrypt/SilcPKCSDecryptCb
 219  *
 220  * SYNOPSIS
 221  *
 222  *    typedef void (*SilcPKCSDecryptCb)(SilcBool success,
 223  *                                      const unsigned char *decrypted,
 224  *                                      SilcUInt32 decrypted_len,
 225  *                                      void *context);
 226  *
 227  * DESCRIPTION
 228  *
 229  *    Decryption callback.  This callback is given as argument to the
 230  *    silc_pkcs_decrypt and the decrypted data is delivered to the caller
 231  *    in this callback.  The `decrypted' is the decrypted data.  If the
 232  *    `success' is FALSE the decryption operation failed.
 233  *
 234  ***/
 235 typedef void (*SilcPKCSDecryptCb)(SilcBool success,
 236                                   const unsigned char *decrypted,
 237                                   SilcUInt32 decrypted_len,
 238                                   void *context);
 239
 240 /****f* silccrypt/SilcPKCSSignCb
 241  *
 242  * SYNOPSIS
 243  *
 244  *    typedef void (*SilcPKCSSignCb)(SilcBool success,
 245  *                                   const unsigned char *signature,
 246  *                                   SilcUInt32 signature_len,
 247  *                                   void *context);
 248  *
 249  * DESCRIPTION
 250  *
 251  *    Signature callback.  This callback is given as argument to the
 252  *    silc_pkcs_sign and the digitally signed data is delivered to the caller
 253  *    in this callback.  The `signature' is the signature data.  If the
 254  *    `success' is FALSE the signature operation failed.
 255  *
 256  ***/
 257 typedef void (*SilcPKCSSignCb)(SilcBool success,
 258                                const unsigned char *signature,
 259                                SilcUInt32 signature_len,
 260                                void *context);
 261
 262 /****f* silccrypt/SilcPKCSVerifyCb
 263  *
 264  * SYNOPSIS
 265  *
 266  *    typedef void (*SilcPKCSVerifyCb)(SilcBool success, void *context);
 267  *
 268  * DESCRIPTION
 269  *
 270  *    Verification callback.  This callback is given as argument to the
 271  *    silc_pkcs_verify and the result of the signature verification is
 272  *    deliver to the caller in this callback.  If the `success' is FALSE
 273  *    the signature verification failed.
 274  *
 275  ***/
 276 typedef void (*SilcPKCSVerifyCb)(SilcBool success, void *context);
 277
 278 #include "silcpkcs_i.h"
 279
 280 /* Marks for all PKCS in. This can be used in silc_pkcs_unregister to
 281    unregister all PKCS at once. */
 282 #define SILC_ALL_PKCS ((SilcPKCSObject *)1)
 283 #define SILC_ALL_PKCS_ALG ((SilcPKCSAlgorithm *)1)
 284
 285 /* Static lists of PKCS and PKCS algorithms. */
 286 extern DLLAPI const SilcPKCSObject silc_default_pkcs[];
 287 extern DLLAPI const SilcPKCSAlgorithm silc_default_pkcs_alg[];
 288
 289 /* Prototypes */
 290
 291 /****f* silccrypt/silc_pkcs_register
 292  *
 293  * SYNOPSIS
 294  *
 295  *    SilcBool silc_pkcs_register(const SilcPKCSObject *pkcs);
 296  *
 297  * DESCRIPTION
 298  *
 299  *    Registers a new PKCS into the crypto library.  This function can be
 300  *    used at the initialization of an application.  All registered PKCSs
 301  *    should be unregistered with silc_pkcs_unregister.  Usually this
 302  *    function is not needed.  The default PKCSs  are automatically
 303  *    registered.  This can be used to change the order of the registered
 304  *    PKCSs by re-registering them in desired order, or add new PKCSs.
 305  *    Returns FALSE on error.
 306  *
 307  ***/
 308 SilcBool silc_pkcs_register(const SilcPKCSObject *pkcs);
 309
 310 /****f* silccrypt/silc_pkcs_unregister
 311  *
 312  * SYNOPSIS
 313  *
 314  *    SilcBool silc_pkcs_unregister(SilcPKCSObject *pkcs);
 315  *
 316  * DESCRIPTION
 317  *
 318  *    Unregister a PKCS from the crypto library. Returns FALSE on error.
 319  *
 320  ***/
 321 SilcBool silc_pkcs_unregister(SilcPKCSObject *pkcs);
 322
 323 /****f* silccrypt/silc_pkcs_algorithm_register
 324  *
 325  * SYNOPSIS
 326  *
 327  *    SilcBool silc_pkcs_algorithm_register(const SilcPKCSAlgorithm *pkcs);
 328  *
 329  * DESCRIPTION
 330  *
 331  *    Registers a new PKCS Algorithm into crypto library.  This function
 332  *    can be used at the initialization of an application.  All registered
 333  *    PKCS algorithms should be unregistered with silc_pkcs_unregister.
 334  *
 335  ***/
 336 SilcBool silc_pkcs_algorithm_register(const SilcPKCSAlgorithm *pkcs);
 337
 338 /****f* silccrypt/silc_pkcs_algorithm_unregister
 339  *
 340  * SYNOPSIS
 341  *
 342  *    SilcBool silc_pkcs_algorithm_unregister(SilcPKCSAlgorithm *pkcs);
 343  *
 344  * DESCRIPTION
 345  *
 346  *    Unregister a PKCS from the crypto library. Returns FALSE on error.
 347  *
 348  ***/
 349 SilcBool silc_pkcs_algorithm_unregister(SilcPKCSAlgorithm *pkcs);
 350
 351 /****f* silccrypt/silc_pkcs_register_default
 352  *
 353  * SYNOPSIS
 354  *
 355  *    SilcBool silc_pkcs_register_default(void);
 356  *
 357  * DESCRIPTION
 358  *
 359  *    Registers all the default PKCS (all builtin PKCS) and PKCS algorithms.
 360  *    Application need not call this directly.  By calling silc_crypto_init
 361  *    this function is called.
 362  *
 363  ***/
 364 SilcBool silc_pkcs_register_default(void);
 365
 366 /****f* silccrypt/silc_pkcs_unregister_all
 367  *
 368  * SYNOPSIS
 369  *
 370  *    SilcBool silc_pkcs_unregister_all(void);
 371  *
 372  * DESCRIPTION
 373  *
 374  *    Unregister all PKCS and PKCS algorithms. Returns FALSE on error.
 375  *    Application need not call this directly.  By calling silc_crypto_init
 376  *    this function is called.
 377  *
 378  ***/
 379 SilcBool silc_pkcs_unregister_all(void);
 380
 381 /****f* silccrypt/silc_pkcs_get_supported
 382  *
 383  * SYNOPSIS
 384  *
 385  *    char *silc_pkcs_get_supported(void);
 386  *
 387  * DESCRIPTION
 388  *
 389  *    Returns comma separated list of supported PKCS algorithms.
 390  *
 391  ***/
 392 char *silc_pkcs_get_supported(void);
 393
 394 /****f* silccrypt/silc_pkcs_find_pkcs
 395  *
 396  * SYNOPSIS
 397  *
 398  *    const SilcPKCSObject *silc_pkcs_get_pkcs(SilcPKCSType type);
 399  *
 400  * DESCRIPTION
 401  *
 402  *    Finds PKCS context by the PKCS type.
 403  *
 404  ***/
 405 const SilcPKCSObject *silc_pkcs_find_pkcs(SilcPKCSType type);
 406
 407 /****f* silccrypt/silc_pkcs_find_algorithm
 408  *
 409  * SYNOPSIS
 410  *
 411  *    const SilcPKCSAlgorithm *silc_pkcs_find_algorithm(const char *algorithm,
 412  *                                                      const char *scheme);
 413  *
 414  * DESCRIPTION
 415  *
 416  *    Finds PKCS algorithm context by the algorithm name `algorithm' and
 417  *    the algorithm scheme `scheme'.  The `scheme' may be NULL.  Usually
 418  *    this function is not needed unless you need low level access to the
 419  *    algorithm implementations.  Usually this is used when implementing
 420  *    support to new PKCS type.
 421  *
 422  ***/
 423 const SilcPKCSAlgorithm *silc_pkcs_find_algorithm(const char *algorithm,
 424                                                   const char *scheme);
 425
 426 /****f* silccrypt/silc_pkcs_get_pkcs
 427  *
 428  * SYNOPSIS
 429  *
 430  *    const SilcPKCSObject *silc_pkcs_get_pkcs(void *key);
 431  *
 432  * DESCRIPTION
 433  *
 434  *    Returns the PKCS object from `key', which may be SilcPublicKey or
 435  *    SilcPrivateKey pointer.
 436  *
 437  ***/
 438 const SilcPKCSObject *silc_pkcs_get_pkcs(void *key);
 439
 440 /****f* silccrypt/silc_pkcs_get_algorithm
 441  *
 442  * SYNOPSIS
 443  *
 444  *    const SilcPKCSAlgorithm *silc_pkcs_get_algorithm(void *key);
 445  *
 446  * DESCRIPTION
 447  *
 448  *    Returns the PKCS algorithm object from `key', which may be SilcPublicKey
 449  *    or SilcPrivateKey pointer.
 450  *
 451  ***/
 452 const SilcPKCSAlgorithm *silc_pkcs_get_algorithm(void *key);
 453
 454 /****f* silccrypt/silc_pkcs_get_name
 455  *
 456  * SYNOPSIS
 457  *
 458  *    const char *silc_pkcs_get_name(void *key);
 459  *
 460  * DESCRIPTION
 461  *
 462  *    Returns PKCS algorithm name from the `key', which may be SilcPublicKey
 463  *    or SilcPrivateKey pointer.
 464  *
 465  ***/
 466 const char *silc_pkcs_get_name(void *key);
 467
 468 /****f* silccrypt/silc_pkcs_get_type
 469  *
 470  * SYNOPSIS
 471  *
 472  *    SilcPKCSType silc_pkcs_get_type(void *key);
 473  *
 474  * DESCRIPTION
 475  *
 476  *    Returns PKCS type from the `key', which may be SilcPublicKey or
 477  *    SilcPrivateKey pointer.
 478  *
 479  ***/
 480 SilcPKCSType silc_pkcs_get_type(void *key);
 481
 482 /****f* silccrypt/silc_pkcs_public_key_get_pkcs
 483  *
 484  * SYNOPSIS
 485  *
 486  *    void *silc_pkcs_public_key_get_pkcs(SilcPKCSType type,
 487  *                                        SilcPublicKey public_key);
 488  *
 489  * DESCRIPTION
 490  *
 491  *    Returns the internal PKCS `type' specific public key context from the
 492  *    `public_key'.  The caller needs to explicitly type cast it to correct
 493  *    type.  Returns NULL on error.
 494  *
 495  *    For SILC_PKCS_SILC the returned context is SilcSILCPublicKey.
 496  *    For SILC_PKCS_SSH2 the returned context is SilcSshPublicKey.
 497  *
 498  ***/
 499 void *silc_pkcs_public_key_get_pkcs(SilcPKCSType type,
 500                                     SilcPublicKey public_key);
 501
 502 /****f* silccrypt/silc_pkcs_private_key_get_pkcs
 503  *
 504  * SYNOPSIS
 505  *
 506  *    void *silc_pkcs_private_key_get_pkcs(SilcPKCSType type,
 507  *                                        SilcPublicKey public_key);
 508  *
 509  * DESCRIPTION
 510  *
 511  *    Returns the internal PKCS `type' specific private key context from the
 512  *    `private_key'.  The caller needs to explicitly type cast it to correct
 513  *    type.  Returns NULL on error.
 514  *
 515  *    For SILC_PKCS_SILC the returned context is SilcSILCPrivateKey.
 516  *    For SILC_PKCS_SSH2 the returned context is SilcSshPrivateKey.
 517  *
 518  ***/
 519 void *silc_pkcs_private_key_get_pkcs(SilcPKCSType type,
 520                                      SilcPrivateKey private_key);
 521
 522 /****f* silccrypt/silc_pkcs_public_key_alloc
 523  *
 524  * SYNOPSIS
 525  *
 526  *    SilcBool silc_pkcs_public_key_alloc(SilcPKCSType type,
 527  *                                        unsigned char *key,
 528  *                                        SilcUInt32 key_len
 529  *                                        SilcPublicKey *ret_public_key);
 530  *
 531  * DESCRIPTION
 532  *
 533  *    Allocates SilcPublicKey of the type of `type' from the key data
 534  *    `key' of length of `key_len' bytes.  Returns FALSE if the `key'
 535  *    is malformed or unsupported public key type.  This function can be
 536  *    used to create public key from any kind of PKCS public keys that
 537  *    the implementation supports.
 538  *
 539  ***/
 540 SilcBool silc_pkcs_public_key_alloc(SilcPKCSType type,
 541                                     unsigned char *key,
 542                                     SilcUInt32 key_len,
 543                                     SilcPublicKey *ret_public_key);
 544
 545 /****f* silccrypt/silc_pkcs_public_key_free
 546  *
 547  * SYNOPSIS
 548  *
 549  *    void silc_pkcs_public_key_free(SilcPublicKey public_key);
 550  *
 551  * DESCRIPTION
 552  *
 553  *    Frees the public key.  This will also automatically free the underlaying
 554  *    PKCS specific public key.  All public keys allocated through the
 555  *    PKCS API must be freed by calling this function.
 556  *
 557  ***/
 558 void silc_pkcs_public_key_free(SilcPublicKey public_key);
 559
 560 /****f* silccrypt/silc_pkcs_public_key_export
 561  *
 562  * SYNOPSIS
 563  *
 564  *    unsigned char *silc_pkcs_public_key_encode(SilcStack stack,
 565  *                                               SilcPublicKey public_key,
 566  *                                               SilcUInt32 *ret_len);
 567  *
 568  * DESCRIPTION
 569  *
 570  *    Encodes the `public_key' into a binary format and returns it.  Returns
 571  *    NULL on error.  Caller must free the returned buffer.
 572  *
 573  *    If the `stack' is non-NULL the returned buffer is allocated from the
 574  *    `stack'.  This call will consume `stack' so caller should push the stack
 575  *    before calling and then later pop it.
 576  *
 577  ***/
 578 unsigned char *silc_pkcs_public_key_encode(SilcStack stack,
 579                                            SilcPublicKey public_key,
 580                                            SilcUInt32 *ret_len);
 581
 582 /****f* silccrypt/silc_pkcs_public_key_get_len
 583  *
 584  * SYNOPSIS
 585  *
 586  *    SilcUInt32 silc_pkcs_public_key_get_len(SilcPublicKey public_key);
 587  *
 588  * DESCRIPTION
 589  *
 590  *    Returns the key length in bits from the public key.
 591  *
 592  ***/
 593 SilcUInt32 silc_pkcs_public_key_get_len(SilcPublicKey public_key);
 594
 595 /****f* silccrypt/silc_pkcs_public_key_compare
 596  *
 597  * SYNOPSIS
 598  *
 599  *    SilcBool silc_pkcs_public_key_compare(SilcPublicKey key1,
 600  *                                          SilcPublicKey key2);
 601  *
 602  * DESCRIPTION
 603  *
 604  *    Compares two public keys and returns TRUE if they are same key, and
 605  *    FALSE if they are not same.
 606  *
 607  ***/
 608 SilcBool silc_pkcs_public_key_compare(SilcPublicKey key1, SilcPublicKey key2);
 609
 610 /****f* silccrypt/silc_pkcs_public_key_copy
 611  *
 612  * SYNOPSIS
 613  *
 614  *    SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
 615  *
 616  * DESCRIPTION
 617  *
 618  *    Copies the public key indicated by `public_key' and returns new
 619  *    allocated public key which is indentical to the `public_key'.
 620  *
 621  ***/
 622 SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
 623
 624 /****f* silccrypt/silc_pkcs_private_key_alloc
 625  *
 626  * SYNOPSIS
 627  *
 628  *    SilcBool silc_pkcs_private_key_alloc(SilcPKCSType type,
 629  *                                         unsigned char *key,
 630  *                                         SilcUInt32 key_len,
 631  *                                         SilcPrivateKey *ret_private_key);
 632  *
 633  * DESCRIPTION
 634  *
 635  *    Allocates SilcPrivateKey of the type of `type' from the key data
 636  *    `key' of length of `key_len' bytes.  Returns FALSE if the `key'
 637  *    is malformed or unsupported private key type.
 638  *
 639  *    Usually this function is not needed.  Typical application calls
 640  *    silc_pkcs_load_private_key instead.
 641  *
 642  ***/
 643 SilcBool silc_pkcs_private_key_alloc(SilcPKCSType type,
 644                                      unsigned char *key,
 645                                      SilcUInt32 key_len,
 646                                      SilcPrivateKey *ret_private_key);
 647
 648 /****f* silccrypt/silc_pkcs_private_key_get_len
 649  *
 650  * SYNOPSIS
 651  *
 652  *    SilcUInt32 silc_pkcs_private_key_get_len(SilcPrivateKey private_key);
 653  *
 654  * DESCRIPTION
 655  *
 656  *    Returns the key length in bits from the private key.
 657  *
 658  ***/
 659 SilcUInt32 silc_pkcs_private_key_get_len(SilcPrivateKey private_key);
 660
 661 /****f* silccrypt/silc_pkcs_private_key_free
 662  *
 663  * SYNOPSIS
 664  *
 665  *    void silc_pkcs_private_key_free(SilcPrivateKey private_key;
 666  *
 667  * DESCRIPTION
 668  *
 669  *    Frees the public key.  This will also automatically free the underlaying
 670  *    PKCS specific private key.  All private keys allocated through the
 671  *    PKCS API must be freed by calling this function.
 672  *
 673  ***/
 674 void silc_pkcs_private_key_free(SilcPrivateKey private_key);
 675
 676 /****f* silccrypt/silc_pkcs_encrypt
 677  *
 678  * SYNOPSIS
 679  *
 680  *    SilcBool silc_pkcs_encrypt(SilcPublicKey public_key,
 681  *                               unsigned char *src, SilcUInt32 src_len,
 682  *                               unsigned char *dst, SilcUInt32 dst_size,
 683  *                               SilcUInt32 *dst_len, SilcRng rng);
 684  *
 685  * DESCRIPTION
 686  *
 687  *    Encrypts with the public key.  Returns FALSE on error.  The length
 688  *    the encrypted data is returned to `dst_len' if it is non-NULL.
 689  *
 690  *    This call cannot be used if `public_key' is accelerated.  All
 691  *    accelerators are usually asynchronous and the function will return
 692  *    before the encryption has been done.  In this case the
 693  *    silc_pkcs_encrypt_async should be used.
 694  *
 695  ***/
 696 SilcBool silc_pkcs_encrypt(SilcPublicKey public_key,
 697                            unsigned char *src, SilcUInt32 src_len,
 698                            unsigned char *dst, SilcUInt32 dst_size,
 699                            SilcUInt32 *dst_len, SilcRng rng);
 700
 701 /****f* silccrypt/silc_pkcs_encrypt_async
 702  *
 703  * SYNOPSIS
 704  *
 705  *    SilcAsyncOperation
 706  *    silc_pkcs_encrypt_async(SilcPublicKey public_key,
 707  *                            unsigned char *src,
 708  *                            SilcUInt32 src_len, SilcRng rng,
 709  *                            SilcPKCSEncryptCb encrypt_cb,
 710  *                            void *context);
 711  *
 712  * DESCRIPTION
 713  *
 714  *    Encrypts with the public key.  The `encrypt_cb' will be called to
 715  *    deliver the encrypted data.  The encryption operation may be asynchronous
 716  *    if the `public_key' is accelerated public key.  If this returns NULL
 717  *    the asynchronous operation cannot be controlled.
 718  *
 719  ***/
 720 SilcAsyncOperation silc_pkcs_encrypt_async(SilcPublicKey public_key,
 721                                            unsigned char *src,
 722                                            SilcUInt32 src_len, SilcRng rng,
 723                                            SilcPKCSEncryptCb encrypt_cb,
 724                                            void *context);
 725
 726 /****f* silccrypt/silc_pkcs_decrypt
 727  *
 728  * SYNOPSIS
 729  *
 730  *    SilcBool silc_pkcs_decrypt(SilcPrivateKey private_key,
 731  *                               unsigned char *src, SilcUInt32 src_len,
 732  *                               unsigned char *dst, SilcUInt32 dst_size,
 733  *                               SilcUInt32 *dst_len);
 734  *
 735  * DESCRIPTION
 736  *
 737  *    Decrypts with the private key.  Returns FALSE on error.  The length
 738  *    of the decrypted data is returned to `dst_len' if it is non-NULL.
 739  *
 740  *    This call cannot be used if `public_key' is accelerated.  All
 741  *    accelerators are usually asynchronous and the function will return
 742  *    before the decryption has been done.  In this case the
 743  *    silc_pkcs_decrypt_async should be used.
 744  *
 745  ***/
 746 SilcBool silc_pkcs_decrypt(SilcPrivateKey private_key,
 747                            unsigned char *src, SilcUInt32 src_len,
 748                            unsigned char *dst, SilcUInt32 dst_size,
 749                            SilcUInt32 *dst_len);
 750
 751 /****f* silccrypt/silc_pkcs_decrypt_async
 752  *
 753  * SYNOPSIS
 754  *
 755  *    SilcAsyncOperation
 756  *    silc_pkcs_decrypt_async(SilcPrivateKey private_key,
 757  *                            unsigned char *src,
 758  *                            SilcUInt32 src_len,
 759  *                            SilcPKCSDecryptCb decrypt_cb,
 760  *                            void *context);
 761  *
 762  * DESCRIPTION
 763  *
 764  *    Decrypts with the private key.  The `decrypt_cb' will be called to
 765  *    deliver the decrypted data.  The decryption operation may be asynchronous
 766  *    if the `private_key' is accelerated private key.  If this returns NULL
 767  *    the asynchronous operation cannot be controlled.
 768  *
 769  ***/
 770 SilcAsyncOperation
 771 silc_pkcs_decrypt_async(SilcPrivateKey private_key,
 772                         unsigned char *src, SilcUInt32 src_len,
 773                         SilcPKCSDecryptCb decrypt_cb,
 774                         void *context);
 775
 776 /****f* silccrypt/silc_pkcs_sign
 777  *
 778  * SYNOPSIS
 779  *
 780  *    SilcBool silc_pkcs_sign(SilcPrivateKey private_key,
 781  *                            unsigned char *src, SilcUInt32 src_len,
 782  *                            unsigned char *dst, SilcUInt32 dst_size,
 783  *                            SilcUInt32 *dst_len, SilcBool compute_hash,
 784  *                            SilcHash hash, SilcRng rng);
 785  *
 786  * DESCRIPTION
 787  *
 788  *    Computes signature with the private key.  If `compute_hash' is TRUE
 789  *    the `hash' will be used to compute a message digest over the `src'.
 790  *    The `hash' is NULL the default hash function is used.  The `rng'
 791  *    should always be provided.  The length of the signature is returned
 792  *    to `dst_len' is it is non-NULL.
 793  *
 794  *    This call cannot be used if `public_key' is accelerated.  All
 795  *    accelerators are usually asynchronous and the function will return
 796  *    before the signagture has been done.  In this case the
 797  *    silc_pkcs_sign_async should be used.
 798  *
 799  ***/
 800 SilcBool silc_pkcs_sign(SilcPrivateKey private_key,
 801                         unsigned char *src, SilcUInt32 src_len,
 802                         unsigned char *dst, SilcUInt32 dst_size,
 803                         SilcUInt32 *dst_len, SilcBool compute_hash,
 804                         SilcHash hash, SilcRng rng);
 805
 806 /****f* silccrypt/silc_pkcs_sign_async
 807  *
 808  * SYNOPSIS
 809  *
 810  *    SilcAsyncOperation silc_pkcs_sign_async(SilcPrivateKey private_key,
 811  *                                            unsigned char *src,
 812  *                                            SilcUInt32 src_len,
 813  *                                            SilcBool compute_hash,
 814  *                                            SilcHash hash,
 815  *                                            SilcRng rng,
 816  *                                            SilcPKCSSignCb sign_cb,
 817  *                                            void *context);
 818  *
 819  * DESCRIPTION
 820  *
 821  *    Computes signature with the private key.  The `sign_cb' will be called
 822  *    to deliver the signature data.  If `compute_hash' is TRUE the `hash'
 823  *    will be used to compute a message digest over the `src'.  The `hash'
 824  *    is NULL the default hash function is used.  The `rng' should always
 825  *    be provided.  The signature operation may be asynchronous if the
 826  *    `private_key' is accelerated private key.  If this returns NULL the
 827  *    asynchronous operation cannot be controlled.
 828  *
 829  ***/
 830 SilcAsyncOperation silc_pkcs_sign_async(SilcPrivateKey private_key,
 831                                         unsigned char *src,
 832                                         SilcUInt32 src_len,
 833                                         SilcBool compute_hash,
 834                                         SilcHash hash,
 835                                         SilcRng rng,
 836                                         SilcPKCSSignCb sign_cb,
 837                                         void *context);
 838
 839 /****f* silccrypt/silc_pkcs_verify
 840  *
 841  * SYNOPSIS
 842  *
 843  *    SilcBool silc_pkcs_verify(SilcPublicKey public_key,
 844  *                              unsigned char *signature,
 845  *                              SilcUInt32 signature_len,
 846  *                              unsigned char *data,
 847  *                              SilcUInt32 data_len,
 848  *                              SilcBool compute_hash,
 849  *                              SilcHash hash);
 850  *
 851  * DESCRIPTION
 852  *
 853  *    Verifies signature.  The 'signature' is verified against the 'data'.
 854  *    If `compute_hash' hash is TRUE the `hash' will be used in verification.
 855  *    If `hash' is NULL, the hash algorithm to be used is retrieved from the
 856  *    signature.  If it isn't present in the signature the default hash
 857  *    function is used.  The `rng' is usually not needed and may be NULL.
 858  *
 859  *    This call cannot be used if `public_key' is accelerated.  All
 860  *    accelerators are usually asynchronous and the function will return
 861  *    before the verification has been done.  In this case the
 862  *    silc_pkcs_verify_async should be used.
 863  *
 864  ***/
 865 SilcBool silc_pkcs_verify(SilcPublicKey public_key,
 866                           unsigned char *signature,
 867                           SilcUInt32 signature_len,
 868                           unsigned char *data,
 869                           SilcUInt32 data_len,
 870                           SilcBool compute_hash,
 871                           SilcHash hash);
 872
 873 /****f* silccrypt/silc_pkcs_verify_async
 874  *
 875  * SYNOPSIS
 876  *
 877  *    SilcAsyncOperation silc_pkcs_verify_async(SilcPublicKey public_key,
 878  *                                              unsigned char *signature,
 879  *                                              SilcUInt32 signature_len,
 880  *                                              unsigned char *data,
 881  *                                              SilcUInt32 data_len,
 882  *                                              SilcBool compute_hash,
 883  *                                              SilcHash hash,
 884  *                                              SilcPKCSVerifyCb verify_cb,
 885  *                                              void *context);
 886  *
 887  * DESCRIPTION
 888  *
 889  *    Verifies signature.  The `verify_cb' will be called to deliver the
 890  *    result of the verification process.  The 'signature' is verified against
 891  *    the 'data'.  If `compute_hash' hash is TRUE the `hash' will be used in
 892  *    verification.  If `hash' is NULL, the hash algorithm to be used is
 893  *    retrieved from the signature.  If it isn't present in the signature the
 894  *    default hash function is used.  The `rng' is usually not needed and
 895  *    may be NULL.  If this returns NULL the asynchronous operation cannot
 896  *    be controlled.
 897  *
 898  ***/
 899 SilcAsyncOperation silc_pkcs_verify_async(SilcPublicKey public_key,
 900                                           unsigned char *signature,
 901                                           SilcUInt32 signature_len,
 902                                           unsigned char *data,
 903                                           SilcUInt32 data_len,
 904                                           SilcBool compute_hash,
 905                                           SilcHash hash,
 906                                           SilcPKCSVerifyCb verify_cb,
 907                                           void *context);
 908
 909 /****f* silccrypt/silc_pkcs_load_public_key
 910  *
 911  * SYNOPSIS
 912  *
 913  *    SilcBool silc_pkcs_load_public_key(const char *filename,
 914  *                                       SilcPKCSType type,
 915  *                                       SilcPublicKey *ret_public_key);
 916  *
 917  * DESCRIPTION
 918  *
 919  *    Loads public key from file and allocates new public key.  Returns TRUE
 920  *    if loading was successful.  If `type' is SILC_PKSC_ANY this attempts
 921  *    to automatically detect the public key type.  If `type' is some other
 922  *    PKCS type, the key is expected to be of that type.
 923  *
 924  ***/
 925 SilcBool silc_pkcs_load_public_key(const char *filename,
 926                                    SilcPKCSType type,
 927                                    SilcPublicKey *ret_public_key);
 928
 929 /****f* silccrypt/silc_pkcs_save_public_key
 930  *
 931  * SYNOPSIS
 932  *
 933  *    SilcBool silc_pkcs_save_public_key(const char *filename,
 934  *                                       SilcPublicKey public_key,
 935  *                                       SilcPKCSFileEncoding encoding);
 936  *
 937  * DESCRIPTION
 938  *
 939  *    Saves public key into file with specified encoding.  Returns FALSE
 940  *    on error.
 941  *
 942  ***/
 943 SilcBool silc_pkcs_save_public_key(const char *filename,
 944                                    SilcPublicKey public_key,
 945                                    SilcPKCSFileEncoding encoding);
 946
 947 /****f* silccrypt/silc_pkcs_load_private_key
 948  *
 949  * SYNOPSIS
 950  *
 951  *    SilcBool silc_pkcs_load_private_key(const char *filename,
 952  *                                        const unsigned char *passphrase,
 953  *                                        SilcUInt32 passphrase_len,
 954  *                                        SilcPKCSType type,
 955  *                                        SilcPrivateKey *ret_private_key);
 956  *
 957  * DESCRIPTION
 958  *
 959  *    Loads private key from file and allocates new private key.  Returns TRUE
 960  *    if loading was successful.  The `passphrase' is used as decryption
 961  *    key of the private key file, in case it is encrypted.  If `type' is
 962  *    SILC_PKSC_ANY this attempts to automatically detect the private key type.
 963  *    If `type' is some other PKCS type, the key is expected to be of that
 964  *    type.
 965  *
 966  ***/
 967 SilcBool silc_pkcs_load_private_key(const char *filename,
 968                                     const unsigned char *passphrase,
 969                                     SilcUInt32 passphrase_len,
 970                                     SilcPKCSType type,
 971                                     SilcPrivateKey *ret_private_key);
 972
 973 /****f* silccrypt/silc_pkcs_save_private_key
 974  *
 975  * SYNOPSIS
 976  *
 977  *    SilcBool silc_pkcs_save_private_key(const char *filename,
 978  *                                        SilcPrivateKey private_key,
 979  *                                        const unsigned char *passphrase,
 980  *                                        SilcUInt32 passphrase_len,
 981  *                                        SilcPKCSFileEncoding encoding,
 982  *                                        SilcRng rng);
 983  *
 984  * DESCRIPTION
 985  *
 986  *    Saves private key into file.  The private key is encrypted into
 987  *    the file with the `passphrase' as a key, if PKCS supports encrypted
 988  *    private keys.  Returns FALSE on error.
 989  *
 990  ***/
 991 SilcBool silc_pkcs_save_private_key(const char *filename,
 992                                     SilcPrivateKey private_key,
 993                                     const unsigned char *passphrase,
 994                                     SilcUInt32 passphrase_len,
 995                                     SilcPKCSFileEncoding encoding,
 996                                     SilcRng rng);
 997
 998 /****f* silccrypt/silc_hash_public_key
 999  *
1000  * SYNOPSIS
1001  *
1002  *    SilcUInt32 silc_hash_public_key(void *key, void *user_context);
1003  *
1004  * DESCRIPTION
1005  *
1006  *    An utility function for hashing public key for SilcHashTable.  Give
1007  *    this as argument as the hash function for SilcHashTable.
1008  *
1009  ***/
1010 SilcUInt32 silc_hash_public_key(void *key, void *user_context);
1011
1012 /****f* silccrypt/silc_hash_public_key_compare
1013  *
1014  * SYNOPSIS
1015  *
1016  *    SilcBool silc_hash_public_key_compare(void *key1, void *key2,
1017  *                                          void *user_context);
1018  *
1019  * DESCRIPTION
1020  *
1021  *    An utility function for comparing public keys for SilcHashTable.  Give
1022  *    this as argument as the compare function for SilcHashTable.
1023  *
1024  ***/
1025 SilcBool silc_hash_public_key_compare(void *key1, void *key2,
1026                                       void *user_context);
1027
1028 #endif  /* !SILCPKCS_H */