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