lib/silccrypt/silcpkcs.h

   1 /*
   2
   3   silcpkcs.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2003 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 #ifndef SILCPKCS_H
  21 #define SILCPKCS_H
  22
  23 /****h* silccrypt/SILC PKCS Interface
  24  *
  25  * DESCRIPTION
  26  *
  27  *    This is the interface for public key cryptosystems, and various
  28  *    utility functions related to public keys and private keys.  This
  29  *    interface also defines the actual PKCS objects, public keys and
  30  *    private keys.  The interface is generic PKCS interface, which has
  31  *    capability of supporting any kind of public key algorithm.  This
  32  *    interface also implements the SILC Public Key and routines for
  33  *    encoding and decoding SILC Public Key (as defined by the SILC
  34  *    protocol specification).  Interface or encrypting, decrypting,
  35  *    producing digital signatures and verifying digital signatures are
  36  *    also defined in this header.
  37  *
  38  ***/
  39
  40 /****s* silccrypt/SilcPKCSAPI/SilcPKCS
  41  *
  42  * NAME
  43  *
  44  *    typedef struct SilcPKCSStruct *SilcPKCS;
  45  *
  46  * DESCRIPTION
  47  *
  48  *    This context is the actual PKCS context and is allocated
  49  *    by silc_pkcs_alloc and given as argument usually to all
  50  *    silc_pkcs_* functions.  It is freed by the silc_pkcs_free
  51  *    function.
  52  *
  53  ***/
  54 typedef struct SilcPKCSStruct *SilcPKCS;
  55
  56 /* The default SILC PKCS (Public Key Cryptosystem) object to represent
  57    any PKCS in SILC. */
  58 typedef struct SilcPKCSObjectStruct {
  59   char *name;
  60   int (*init)(void *, SilcUInt32, SilcRng);
  61   void (*clear_keys)(void *);
  62   unsigned char *(*get_public_key)(void *, SilcUInt32 *);
  63   unsigned char *(*get_private_key)(void *, SilcUInt32 *);
  64   SilcUInt32 (*set_public_key)(void *, unsigned char *, SilcUInt32);
  65   SilcUInt32 (*set_private_key)(void *, unsigned char *, SilcUInt32);
  66   SilcUInt32 (*context_len)();
  67   int (*encrypt)(void *, unsigned char *, SilcUInt32,
  68                  unsigned char *, SilcUInt32 *);
  69   int (*decrypt)(void *, unsigned char *, SilcUInt32,
  70                  unsigned char *, SilcUInt32 *);
  71   int (*sign)(void *, unsigned char *, SilcUInt32,
  72               unsigned char *, SilcUInt32 *);
  73   int (*verify)(void *, unsigned char *, SilcUInt32,
  74                 unsigned char *, SilcUInt32);
  75 } SilcPKCSObject;
  76
  77 /****s* silccrypt/SilcPKCSAPI/SilcPublicKey
  78  *
  79  * NAME
  80  *
  81  *    typedef struct { ... } *SilcPublicKey, SilcPublicKeyStruct;
  82  *
  83  * DESCRIPTION
  84  *
  85  *    SILC style public key object.  Public key is read from file to this
  86  *    object.  Public keys received from network must be in this format as
  87  *    well.  The format is defined by the SILC protocol specification.
  88  *    This object is allocated by silc_pkcs_public_key_alloc and freed
  89  *    by silc_pkcs_public_key_free.  The object is given as argument to
  90  *    all silc_pkcs_public_key_* functions.
  91  *
  92  * SOURCE
  93  */
  94 typedef struct {
  95   SilcUInt16 pk_type;           /* Public key type (SilcSKEPKType) */
  96   SilcUInt32 len;
  97   char *name;
  98   char *identifier;
  99   unsigned char *pk;
 100   SilcUInt32 pk_len;
 101 } *SilcPublicKey, SilcPublicKeyStruct;
 102 /***/
 103
 104 /****s* silccrypt/SilcPKCSAPI/SilcPublicKeyIdentifier
 105  *
 106  * NAME
 107  *
 108  *    typedef struct { ... } *SilcPublicKeyIdentifier,
 109  *                            SilcPublicKeyIdentifierStruct;
 110  *
 111  * DESCRIPTION
 112  *
 113  *    Decoded SILC Public Key identifier.  Note that some of the fields
 114  *    may be NULL.  This context is allocated by the function
 115  *    silc_pkcs_decode_identifier and freed by silc_pkcs_free_identifier.
 116  *    The identifier in SilcPublicKey is the `identifier' field, which
 117  *    can be given as argument to silc_pkcs_decode_identifier.
 118  *
 119  * SOURCE
 120  */
 121 typedef struct {
 122   char *username;
 123   char *host;
 124   char *realname;
 125   char *email;
 126   char *org;
 127   char *country;
 128 } *SilcPublicKeyIdentifier, SilcPublicKeyIdentifierStruct;
 129 /***/
 130
 131 /****s* silccrypt/SilcPKCSAPI/SilcPrivateKey
 132  *
 133  * NAME
 134  *
 135  *    typedef struct { ... } *SilcPrivateKey, SilcPrivateKeyStruct;
 136  *
 137  * DESCRIPTION
 138  *
 139  *    SILC style private key object.  Public key is read from file to this
 140  *    object.  This object is allocated by silc_pkcs_private_key_alloc and
 141  *    freed by silc_pkcs_private_key_free.  The object is given as argument
 142  *    to all silc_pkcs_private_key_* functions.
 143  *
 144  ***/
 145 typedef struct {
 146   char *name;
 147   unsigned char *prv;
 148   SilcUInt32 prv_len;
 149 } *SilcPrivateKey, SilcPrivateKeyStruct;
 150
 151 /* Public and private key file headers */
 152 #define SILC_PKCS_PUBLIC_KEYFILE_BEGIN "-----BEGIN SILC PUBLIC KEY-----\n"
 153 #define SILC_PKCS_PUBLIC_KEYFILE_END "\n-----END SILC PUBLIC KEY-----\n"
 154 #define SILC_PKCS_PRIVATE_KEYFILE_BEGIN "-----BEGIN SILC PRIVATE KEY-----\n"
 155 #define SILC_PKCS_PRIVATE_KEYFILE_END "\n-----END SILC PRIVATE KEY-----\n"
 156
 157 /* Public and private key file encoding types */
 158 #define SILC_PKCS_FILE_BIN 0
 159 #define SILC_PKCS_FILE_PEM 1
 160
 161 /* Marks for all PKCS in silc. This can be used in silc_pkcs_unregister
 162    to unregister all PKCS at once. */
 163 #define SILC_ALL_PKCS ((SilcPKCSObject *)1)
 164
 165 /* Static list of PKCS for silc_pkcs_register_default(). */
 166 extern DLLAPI const SilcPKCSObject silc_default_pkcs[];
 167
 168 /* Default PKXS in the SILC protocol */
 169 #define SILC_DEFAULT_PKCS "rsa"
 170
 171 /* Macros */
 172
 173 /* Macros used to implement the SILC PKCS API */
 174
 175 /* XXX: This needs slight redesigning. These needs to be made even
 176    more generic. I don't like that the actual prime generation is done
 177    in PKCS_API_INIT. The primes used in key generation should be sent
 178    as argument to the init function. By doing this we would achieve
 179    that PKCS could be used as SIM's. The only requirement would be
 180    that they are compiled against GMP (well, actually even that would
 181    not be a requirement, but the most generic case anyway). The new init
 182    would look something like this:
 183
 184    #define SILC_PKCS_API_INIT(pkcs) \
 185    inline int silc_##pkcs##_init(void *context, SilcUInt32 keylen, \
 186                                  void *p1, void *p2)
 187
 188    Now we wouldn't have to send the SilcRng object since the primes are
 189    provided as arguments. To send them as void * they could actually be
 190    used as in anyway for real (MP_INT (SilcMPInt) or even something else
 191    (the pointer could be kludged to be something else in the module))
 192    (Plus, the SilcRng object management in prime generation would be
 193    simpler and better what it is now (in silcprimegen.c, that is)).
 194 */
 195
 196 #define SILC_PKCS_API_INIT(pkcs) \
 197 int silc_##pkcs##_init(void *context, SilcUInt32 keylen, \
 198                        SilcRng rng)
 199 #define SILC_PKCS_API_CLEAR_KEYS(pkcs) \
 200 void silc_##pkcs##_clear_keys(void *context)
 201 #define SILC_PKCS_API_GET_PUBLIC_KEY(pkcs) \
 202 unsigned char *silc_##pkcs##_get_public_key(void *context, \
 203                                             SilcUInt32 *ret_len)
 204 #define SILC_PKCS_API_GET_PRIVATE_KEY(pkcs) \
 205 unsigned char *silc_##pkcs##_get_private_key(void *context, \
 206                                              SilcUInt32 *ret_len)
 207 #define SILC_PKCS_API_SET_PUBLIC_KEY(pkcs) \
 208 SilcUInt32 silc_##pkcs##_set_public_key(void *context, unsigned char *key_data, \
 209                                         SilcUInt32 key_len)
 210 #define SILC_PKCS_API_SET_PRIVATE_KEY(pkcs) \
 211 SilcUInt32 silc_##pkcs##_set_private_key(void *context, unsigned char *key_data, \
 212                                          SilcUInt32 key_len)
 213 #define SILC_PKCS_API_CONTEXT_LEN(pkcs) \
 214 SilcUInt32 silc_##pkcs##_context_len()
 215 #define SILC_PKCS_API_ENCRYPT(pkcs) \
 216 int silc_##pkcs##_encrypt(void *context, \
 217                           unsigned char *src, \
 218                           SilcUInt32 src_len, \
 219                           unsigned char *dst, \
 220                           SilcUInt32 *dst_len)
 221 #define SILC_PKCS_API_DECRYPT(pkcs) \
 222 int silc_##pkcs##_decrypt(void *context, \
 223                           unsigned char *src, \
 224                           SilcUInt32 src_len, \
 225                           unsigned char *dst, \
 226                           SilcUInt32 *dst_len)
 227 #define SILC_PKCS_API_SIGN(pkcs) \
 228 int silc_##pkcs##_sign(void *context, \
 229                        unsigned char *src, \
 230                        SilcUInt32 src_len, \
 231                        unsigned char *dst, \
 232                        SilcUInt32 *dst_len)
 233 #define SILC_PKCS_API_VERIFY(pkcs) \
 234 int silc_##pkcs##_verify(void *context, \
 235                          unsigned char *signature, \
 236                          SilcUInt32 signature_len, \
 237                          unsigned char *data, \
 238                          SilcUInt32 data_len)
 239
 240 /* Prototypes */
 241
 242 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_register
 243  *
 244  * SYNOPSIS
 245  *
 246  *    bool silc_pkcs_register(const SilcPKCSObject *pkcs);
 247  *
 248  * DESCRIPTION
 249  *
 250  *    Registers a new PKCS into the SILC.  This function is used
 251  *    at the initialization of the SILC.  All registered PKCSs
 252  *    should be unregistered with silc_pkcs_unregister.  The `pkcs' includes
 253  *    the name of the PKCS and member functions for the algorithm.  Usually
 254  *    this function is not called directly.  Instead, application can call
 255  *    the silc_pkcs_register_default to register all PKCSs that are
 256  *    builtin the sources.  Returns FALSE on error.
 257  *
 258  ***/
 259 bool silc_pkcs_register(const SilcPKCSObject *pkcs);
 260
 261 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_unregister
 262  *
 263  * SYNOPSIS
 264  *
 265  *    bool silc_pkcs_unregister(SilcPKCSObject *pkcs);
 266  *
 267  * DESCRIPTION
 268  *
 269  *    Unregister a PKCS from the SILC. Returns FALSE on error.
 270  *
 271  ***/
 272 bool silc_pkcs_unregister(SilcPKCSObject *pkcs);
 273
 274 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_register_default
 275  *
 276  * SYNOPSIS
 277  *
 278  *    bool silc_pkcs_register_default(void);
 279  *
 280  * DESCRIPTION
 281  *
 282  *    Registers all the default PKCS (all builtin PKCS).  The application may
 283  *    use this to register the default PKCS if specific PKCS in any specific
 284  *    order is not wanted. Returns FALSE on error.
 285  *
 286  ***/
 287 bool silc_pkcs_register_default(void);
 288
 289 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_unregister_all
 290  *
 291  * SYNOPSIS
 292  *
 293  *    bool silc_pkcs_unregister_all(void);
 294  *
 295  * DESCRIPTION
 296  *
 297  *    Returns FALSE on error.
 298  *
 299  ***/
 300 bool silc_pkcs_unregister_all(void);
 301
 302 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_alloc
 303  *
 304  * SYNOPSIS
 305  *
 306  *    bool silc_pkcs_alloc(const unsigned char *name, SilcPKCS *new_pkcs);
 307  *
 308  * DESCRIPTION
 309  *
 310  *    Allocates a new SilcPKCS object.  The new allocated object is returned
 311  *    to the 'new_pkcs' argument.  Returns FALSE on error.
 312  *
 313  ***/
 314 bool silc_pkcs_alloc(const unsigned char *name, SilcPKCS *new_pkcs);
 315
 316 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_free
 317  *
 318  * SYNOPSIS
 319  *
 320  *    void silc_pkcs_free(SilcPKCS pkcs);
 321  *
 322  * DESCRIPTION
 323  *
 324  *    Frees the PKCS object.
 325  *
 326  ***/
 327 void silc_pkcs_free(SilcPKCS pkcs);
 328
 329 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_is_supported
 330  *
 331  * SYNOPSIS
 332  *
 333  *    bool silc_pkcs_is_supported(const unsigned char *name);
 334  *
 335  * DESCRIPTION
 336  *
 337  *    Returns TRUE if PKCS algorithm `name' is supported.
 338  *
 339  ***/
 340 bool silc_pkcs_is_supported(const unsigned char *name);
 341
 342 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_supported
 343  *
 344  * SYNOPSIS
 345  *
 346  *    char *silc_pkcs_get_supported(void);
 347  *
 348  * DESCRIPTION
 349  *
 350  *    Returns comma separated list of supported PKCS algorithms.
 351  *
 352  ***/
 353 char *silc_pkcs_get_supported(void);
 354
 355 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_generate_key
 356  *
 357  * SYNOPSIS
 358  *
 359  *    bool silc_pkcs_generate_key(SilcPKCS pkcs, SilcUInt32 bits_key_len,
 360  *                                SilcRng rng);
 361  *
 362  * DESCRIPTION
 363  *
 364  *    Generate new key pair into the `pkcs' context. Returns FALSE on error.
 365  *    If the `rng' is NULL global SILC RNG will be used.
 366  *
 367  ***/
 368 bool silc_pkcs_generate_key(SilcPKCS pkcs, SilcUInt32 bits_key_len,
 369                             SilcRng rng);
 370
 371 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_key_len
 372  *
 373  * SYNOPSIS
 374  *
 375  *    SilcUInt32 silc_pkcs_get_key_len(SilcPKCS self);
 376  *
 377  * DESCRIPTION
 378  *
 379  *    Returns the length of the key in bits.
 380  *
 381  ***/
 382 SilcUInt32 silc_pkcs_get_key_len(SilcPKCS self);
 383
 384 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_name
 385  *
 386  * SYNOPSIS
 387  *
 388  *    const char *silc_pkcs_get_name(SilcPKCS pkcs);
 389  *
 390  * DESCRIPTION
 391  *
 392  *    Returns PKCS name.
 393  *
 394  ***/
 395 const char *silc_pkcs_get_name(SilcPKCS pkcs);
 396
 397 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_public_key
 398  *
 399  * SYNOPSIS
 400  *
 401  *    unsigned char *silc_pkcs_get_public_key(SilcPKCS pkcs, SilcUInt32 *len);
 402  *
 403  * DESCRIPTION
 404  *
 405  *    Returns SILC style public key for the PKCS.  Note that this is not
 406  *    the SILC Public Key, but the raw public key data from the PKCS.
 407  *    The caller must free the returned data.
 408  *
 409  ***/
 410 unsigned char *silc_pkcs_get_public_key(SilcPKCS pkcs, SilcUInt32 *len);
 411
 412 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_private_key
 413  *
 414  * SYNOPSIS
 415  *
 416  *    unsigned char *silc_pkcs_get_private_key(SilcPKCS pkcs,
 417  *                                             SilcUInt32 *len);
 418  *
 419  * DESCRIPTION
 420  *
 421  *    Returns SILC style private key.  Note that this is not SilcPrivateKey
 422  *    but the raw private key bits from the PKCS.  The caller must free the
 423  *    returned data and SHOULD zero the memory area before freeing.
 424  *
 425  ***/
 426 unsigned char *silc_pkcs_get_private_key(SilcPKCS pkcs, SilcUInt32 *len);
 427
 428 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_set
 429  *
 430  * SYNOPSIS
 431  *
 432  *    SilcUInt32 silc_pkcs_public_key_set(SilcPKCS pkcs,
 433  *                                        SilcPublicKey public_key);
 434  *
 435  * DESCRIPTION
 436  *
 437  *    Sets public key from SilcPublicKey. Returns the length of the key in
 438  *    bits.
 439  *
 440  ***/
 441 SilcUInt32 silc_pkcs_public_key_set(SilcPKCS pkcs, SilcPublicKey public_key);
 442
 443 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_data_set
 444  *
 445  * SYNOPSIS
 446  *
 447  *    SilcUInt32 silc_pkcs_public_key_data_set(SilcPKCS pkcs,
 448  *                                             unsigned char *pk,
 449  *                                             SilcUInt32 pk_len);
 450  *
 451  * DESCRIPTION
 452  *
 453  *    Sets public key from data. Returns the length of the key.
 454  *
 455  ***/
 456 SilcUInt32 silc_pkcs_public_key_data_set(SilcPKCS pkcs, unsigned char *pk,
 457                                          SilcUInt32 pk_len);
 458
 459 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_set
 460  *
 461  * SYNOPSIS
 462  *
 463  *    SilcUInt32 silc_pkcs_private_key_set(SilcPKCS pkcs,
 464  *                                         SilcPrivateKey private_key);
 465  *
 466  * DESCRIPTION
 467  *
 468  *    Sets private key from SilcPrivateKey. Returns the length of the key
 469  *    in bits.
 470  *
 471  ***/
 472 SilcUInt32 silc_pkcs_private_key_set(SilcPKCS pkcs,
 473                                      SilcPrivateKey private_key);
 474
 475 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_data_set
 476  *
 477  * SYNOPSIS
 478  *
 479  *    SilcUInt32 silc_pkcs_private_key_data_set(SilcPKCS pkcs,
 480  *                                              unsigned char *prv,
 481  *                                              SilcUInt32 prv_len);
 482  *
 483  * DESCRIPTION
 484  *
 485  *    Sets private key from data. Returns the length of the key.
 486  *
 487  ***/
 488 SilcUInt32 silc_pkcs_private_key_data_set(SilcPKCS pkcs, unsigned char *prv,
 489                                           SilcUInt32 prv_len);
 490
 491 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_encrypt
 492  *
 493  * SYNOPSIS
 494  *
 495  *    bool silc_pkcs_encrypt(SilcPKCS pkcs, unsigned char *src,
 496  *                           SilcUInt32 src_len, unsigned char *dst,
 497  *                           SilcUInt32 *dst_len);
 498  *
 499  * DESCRIPTION
 500  *
 501  *    Encrypts. Returns FALSE on error.
 502  *
 503  ***/
 504 bool silc_pkcs_encrypt(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
 505                        unsigned char *dst, SilcUInt32 *dst_len);
 506
 507 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_decrypt
 508  *
 509  * SYNOPSIS
 510  *
 511  *    bool silc_pkcs_decrypt(SilcPKCS pkcs, unsigned char *src,
 512  *                           SilcUInt32 src_len, unsigned char *dst,
 513  *                           SilcUInt32 *dst_len);
 514  *
 515  * DESCRIPTION
 516  *
 517  *    Decrypts.  Returns FALSE on error.
 518  *
 519  ***/
 520 bool silc_pkcs_decrypt(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
 521                        unsigned char *dst, SilcUInt32 *dst_len);
 522
 523 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_sign
 524  *
 525  * SYNOPSIS
 526  *
 527  *    bool silc_pkcs_sign(SilcPKCS pkcs, unsigned char *src,
 528  *                        SilcUInt32 src_len, unsigned char *dst,
 529  *                        SilcUInt32 *dst_len);
 530  *
 531  * DESCRIPTION
 532  *
 533  *    Generates signature.  Returns FALSE on error.
 534  *
 535  ***/
 536 bool silc_pkcs_sign(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
 537                     unsigned char *dst, SilcUInt32 *dst_len);
 538
 539 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_verify
 540  *
 541  * SYNOPSIS
 542  *
 543  *    bool silc_pkcs_verify(SilcPKCS pkcs, unsigned char *signature,
 544  *                          SilcUInt32 signature_len, unsigned char *data,
 545  *                          SilcUInt32 data_len);
 546  *
 547  * DESCRIPTION
 548  *
 549  *    Verifies signature.  Returns FALSE on error.  The 'signature' is
 550  *    verified against the 'data'.
 551  *
 552  ***/
 553 bool silc_pkcs_verify(SilcPKCS pkcs, unsigned char *signature,
 554                       SilcUInt32 signature_len, unsigned char *data,
 555                       SilcUInt32 data_len);
 556
 557 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_sign_with_hash
 558  *
 559  * SYNOPSIS
 560  *
 561  *    bool silc_pkcs_sign_with_hash(SilcPKCS pkcs, SilcHash hash,
 562  *                                  unsigned char *src, SilcUInt32 src_len,
 563  *                                  unsigned char *dst, SilcUInt32 *dst_len);
 564  *
 565  * DESCRIPTION
 566  *
 567  *    Generates signature with hash.  The hash is signed.  Returns FALSE on
 568  *    error.
 569  *
 570  ***/
 571 bool silc_pkcs_sign_with_hash(SilcPKCS pkcs, SilcHash hash,
 572                               unsigned char *src, SilcUInt32 src_len,
 573                               unsigned char *dst, SilcUInt32 *dst_len);
 574
 575 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_verify_with_hash
 576  *
 577  * SYNOPSIS
 578  *
 579  *    bool silc_pkcs_verify_with_hash(SilcPKCS pkcs, SilcHash hash,
 580  *                                    unsigned char *signature,
 581  *                                    SilcUInt32 signature_len,
 582  *                                    unsigned char *data,
 583  *                                    SilcUInt32 data_len);
 584  *
 585  * DESCRIPTION
 586  *
 587  *    Verifies signature with hash.  The `data' is hashed and verified against
 588  *    the `signature'.  Returns FALSE on error.
 589  *
 590  ***/
 591 bool silc_pkcs_verify_with_hash(SilcPKCS pkcs, SilcHash hash,
 592                                 unsigned char *signature,
 593                                 SilcUInt32 signature_len,
 594                                 unsigned char *data,
 595                                 SilcUInt32 data_len);
 596
 597 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_encode_identifier
 598  *
 599  * SYNOPSIS
 600  *
 601  *    char *silc_pkcs_encode_identifier(char *username, char *host,
 602  *                                      char *realname, char *email,
 603  *                                      char *org, char *country);
 604  *
 605  * DESCRIPTION
 606  *
 607  *    Encodes and returns SILC public key identifier. If some of the
 608  *    arguments is NULL those are not encoded into the identifier string.
 609  *    Protocol says that at least username and host must be provided.
 610  *
 611  ***/
 612 char *silc_pkcs_encode_identifier(char *username, char *host, char *realname,
 613                                   char *email, char *org, char *country);
 614
 615 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_decode_identifier
 616  *
 617  * SYNOPSIS
 618  *
 619  *    SilcPublicKeyIdentifier silc_pkcs_decode_identifier(char *identifier);
 620  *
 621  * DESCRIPTION
 622  *
 623  *    Decodes the provided `identifier' and returns allocated context for
 624  *    the identifier.
 625  *
 626  ***/
 627 SilcPublicKeyIdentifier silc_pkcs_decode_identifier(char *identifier);
 628
 629 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_free_identifier
 630  *
 631  * SYNOPSIS
 632  *
 633  *    void silc_pkcs_free_identifier(SilcPublicKeyIdentifier identifier);
 634  *
 635  * DESCRIPTION
 636  *
 637  *    Frees decoded public key identifier context.  Call this to free the
 638  *    context returned by the silc_pkcs_decode_identifier.
 639  *
 640  ***/
 641 void silc_pkcs_free_identifier(SilcPublicKeyIdentifier identifier);
 642
 643 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_alloc
 644  *
 645  * SYNOPSIS
 646  *
 647  *    SilcPublicKey silc_pkcs_public_key_alloc(const char *name,
 648  *                                             const char *identifier,
 649  *                                             const unsigned char *pk,
 650  *                                             SilcUInt32 pk_len);
 651  *
 652  * DESCRIPTION
 653  *
 654  *    Allocates SILC style public key formed from sent arguments.  The
 655  *    'name' is the algorithm (PKCS) name, the 'identifier' is the public
 656  *    key identifier generated with silc_pkcs_encode_identifier, and the
 657  *    'pk' and 'pk_len' are the raw public key data returned for example
 658  *    by silc_pkcs_get_public_key.
 659  *
 660  ***/
 661 SilcPublicKey silc_pkcs_public_key_alloc(const char *name,
 662                                          const char *identifier,
 663                                          const unsigned char *pk,
 664                                          SilcUInt32 pk_len);
 665
 666 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_free
 667  *
 668  * SYNOPSIS
 669  *
 670  *    void silc_pkcs_public_key_free(SilcPublicKey public_key);
 671  *
 672  * DESCRIPTION
 673  *
 674  *    Frees public key and all data in it.
 675  *
 676  ***/
 677 void silc_pkcs_public_key_free(SilcPublicKey public_key);
 678
 679 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_alloc
 680  *
 681  * SYNOPSIS
 682  *
 683  *    SilcPrivateKey silc_pkcs_private_key_alloc(const char *name,
 684  *                                               const unsigned char *prv,
 685  *                                               SilcUInt32 prv_len);
 686  *
 687  * DESCRIPTION
 688  *
 689  *    Allocates SILC private key formed from sent arguments.  The 'name'
 690  *    is the algorithm name, and the 'prv' and 'prv_len' are the raw
 691  *    private key bits returned by silc_pkcs_get_private_key.
 692  *
 693  ***/
 694 SilcPrivateKey silc_pkcs_private_key_alloc(const char *name,
 695                                            const unsigned char *prv,
 696                                            SilcUInt32 prv_len);
 697
 698 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_free
 699  *
 700  * SYNOPSIS
 701  *
 702  *    void silc_pkcs_private_key_free(SilcPrivateKey private_key);
 703  *
 704  * DESCRIPTION
 705  *
 706  *    Frees private key and all data in it.  The private key is zeroed
 707  *    before it is freed.
 708  *
 709  ***/
 710 void silc_pkcs_private_key_free(SilcPrivateKey private_key);
 711
 712 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_encode
 713  *
 714  * SYNOPSIS
 715  *
 716  *    unsigned char *
 717  *    silc_pkcs_public_key_encode(SilcPublicKey public_key, SilcUInt32 *len);
 718  *
 719  * DESCRIPTION
 720  *
 721  *    Encodes SILC style public key from SilcPublicKey.  Returns the encoded
 722  *    data.
 723  *
 724  ***/
 725 unsigned char *
 726 silc_pkcs_public_key_encode(SilcPublicKey public_key, SilcUInt32 *len);
 727
 728 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_data_encode
 729  *
 730  * SYNOPSIS
 731  *
 732  *    unsigned char *
 733  *    silc_pkcs_public_key_data_encode(unsigned char *pk, SilcUInt32 pk_len,
 734  *                                     char *pkcs, char *identifier,
 735  *                                     SilcUInt32 *len);
 736  *
 737  * DESCRIPTION
 738  *
 739  *    Encodes SILC style public key.  Returns the encoded data.
 740  *
 741  ***/
 742 unsigned char *
 743 silc_pkcs_public_key_data_encode(unsigned char *pk, SilcUInt32 pk_len,
 744                                  char *pkcs, char *identifier,
 745                                  SilcUInt32 *len);
 746
 747 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_decode
 748  *
 749  * SYNOPSIS
 750  *
 751  *    bool silc_pkcs_public_key_decode(unsigned char *data,
 752  *                                     SilcUInt32 data_len,
 753  *                                     SilcPublicKey *public_key);
 754  *
 755  * DESCRIPTION
 756  *
 757  *    Decodes SILC style public key. Returns TRUE if the decoding was
 758  *    successful. Allocates new public key as well.
 759  *
 760  ***/
 761 bool silc_pkcs_public_key_decode(unsigned char *data, SilcUInt32 data_len,
 762                                  SilcPublicKey *public_key);
 763
 764 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_payload_encode
 765  *
 766  * SYNOPSIS
 767  *
 768  *    bool silc_pkcs_public_key_payload_encode(SilcPublicKey public_key);
 769  *
 770  * DESCRIPTION
 771  *
 772  *    Encodes the Public Key Payload from the public key indicated by
 773  *    `public_key' of type of `pk_type'.  The type is SilcSKEPKType.
 774  *    Returns the encoded payload buffer.
 775  *
 776  ***/
 777 SilcBuffer silc_pkcs_public_key_payload_encode(SilcPublicKey public_key);
 778
 779 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_payload_decode
 780  *
 781  * SYNOPSIS
 782  *
 783  *    bool silc_pkcs_public_key_payload_decode(unsigned char *data,
 784  *                                             SilcUInt32 data_len,
 785  *                                             SilcPublicKey *public_key);
 786  *
 787  * DESCRIPTION
 788  *
 789  *    Decodes Public Key Payload from `data' of `data_len' bytes in length
 790  *    data buffer into `public_key' pointer.  Returns FALSE if the payload
 791  *    cannot be decoded.
 792  *
 793  ***/
 794 bool silc_pkcs_public_key_payload_decode(unsigned char *data,
 795                                          SilcUInt32 data_len,
 796                                          SilcPublicKey *public_key);
 797
 798 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_compare
 799  *
 800  * SYNOPSIS
 801  *
 802  *    bool silc_pkcs_public_key_compare(SilcPublicKey key1,
 803  *                                      SilcPublicKey key2);
 804  *
 805  * DESCRIPTION
 806  *
 807  *    Compares two public keys and returns TRUE if they are same key, and
 808  *    FALSE if they are not same.
 809  *
 810  ***/
 811 bool silc_pkcs_public_key_compare(SilcPublicKey key1, SilcPublicKey key2);
 812
 813 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_copy
 814  *
 815  * SYNOPSIS
 816  *
 817  *    SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
 818  *
 819  * DESCRIPTION
 820  *
 821  *    Copies the public key indicated by `public_key' and returns new allocated
 822  *    public key which is indentical to the `public_key'.
 823  *
 824  ***/
 825 SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
 826
 827 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_encode
 828  *
 829  * SYNOPSIS
 830  *
 831  *    unsigned char *
 832  *    silc_pkcs_private_key_encode(SilcPrivateKey private_key,
 833  *                                 SilcUInt32 *len);
 834  *
 835  * DESCRIPTION
 836  *
 837  *    Encodes SILC private key from SilcPrivateKey.  Returns the encoded data.
 838  *
 839  ***/
 840 unsigned char *
 841 silc_pkcs_private_key_encode(SilcPrivateKey private_key, SilcUInt32 *len);
 842
 843 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_data_encode
 844  *
 845  * SYNOPSIS
 846  *
 847  *    unsigned char *
 848  *    silc_pkcs_private_key_data_encode(unsigned char *prv, SilcUInt32 prv_len,
 849  *                                      char *pkcs, SilcUInt32 *len);
 850  *
 851  * DESCRIPTION
 852  *
 853  *    Encodes SILC private key.  Returns the encoded data.
 854  *
 855  ***/
 856 unsigned char *
 857 silc_pkcs_private_key_data_encode(unsigned char *prv, SilcUInt32 prv_len,
 858                                   char *pkcs, SilcUInt32 *len);
 859
 860 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_decode
 861  *
 862  * SYNOPSIS
 863  *
 864  *    bool silc_pkcs_private_key_decode(unsigned char *data,
 865  *                                      SilcUInt32 data_len,
 866  *                                      SilcPrivateKey *private_key);
 867  *
 868  * DESCRIPTION
 869  *
 870  *    Decodes SILC style private key.  Returns TRUE if the decoding was
 871  *    successful.  Allocates new private key as well.
 872  *
 873  ***/
 874 bool silc_pkcs_private_key_decode(unsigned char *data, SilcUInt32 data_len,
 875                                   SilcPrivateKey *private_key);
 876
 877 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_public_key
 878  *
 879  * SYNOPSIS
 880  *
 881  *    bool silc_pkcs_save_public_key(const char *filename,
 882  *                                   SilcPublicKey public_key,
 883  *                                   SilcUInt32 encoding);
 884  *
 885  * DESCRIPTION
 886  *
 887  *    Saves public key into file.  Returns FALSE on error.
 888  *
 889  ***/
 890 bool silc_pkcs_save_public_key(const char *filename, SilcPublicKey public_key,
 891                                SilcUInt32 encoding);
 892
 893 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_public_key_data
 894  *
 895  * SYNOPSIS
 896  *
 897  *    bool silc_pkcs_save_public_key_data(const char *filename,
 898  *                                        unsigned char *data,
 899  *                                        SilcUInt32 data_len,
 900  *                                        SilcUInt32 encoding);
 901  *
 902  * DESCRIPTION
 903  *
 904  *    Saves public key into file.  The public key is already encoded as
 905  *    data when calling this function.  Returns FALSE on error.
 906  *
 907  ***/
 908 bool silc_pkcs_save_public_key_data(const char *filename, unsigned char *data,
 909                                     SilcUInt32 data_len, SilcUInt32 encoding);
 910
 911 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_private_key
 912  *
 913  * SYNOPSIS
 914  *
 915  *    bool silc_pkcs_save_private_key(const char *filename,
 916  *                                    SilcPrivateKey private_key,
 917  *                                    unsigned char *passphrase,
 918  *                                    SilcUInt32 passphrase_len,
 919  *                                    SilcUInt32 encoding);
 920  *
 921  * DESCRIPTION
 922  *
 923  *    Saves private key into file.  The private key is encrypted into
 924  *    the file with the `passphrase' as a key.  The encryption algorithm
 925  *    is AES with 256 bit key in CBC mode.  Returns FALSE on error.
 926  *
 927  ***/
 928 bool silc_pkcs_save_private_key(const char *filename,
 929                                 SilcPrivateKey private_key,
 930                                 unsigned char *passphrase,
 931                                 SilcUInt32 passphrase_len,
 932                                 SilcUInt32 encoding);
 933
 934 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_load_public_key
 935  *
 936  * SYNOPSIS
 937  *
 938  *    bool silc_pkcs_load_public_key(const char *filename,
 939  *                                   SilcPublicKey *public_key,
 940  *                                   SilcUInt32 encoding);
 941  *
 942  * DESCRIPTION
 943  *
 944  *    Loads public key from file and allocates new public key.  Returns TRUE
 945  *    if loading was successful.
 946  *
 947  ***/
 948 bool silc_pkcs_load_public_key(const char *filename, SilcPublicKey *public_key,
 949                                SilcUInt32 encoding);
 950
 951 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_load_private_key
 952  *
 953  * SYNOPSIS
 954  *
 955  *    bool silc_pkcs_load_private_key(const char *filename,
 956  *                                    SilcPrivateKey *private_key,
 957  *                                    unsigned char *passphrase,
 958  *                                    SilcUInt32 passphrase_len,
 959  *                                    SilcUInt32 encoding);
 960  *
 961  * DESCRIPTION
 962  *
 963  *    Loads private key from file and allocates new private key.  Returns TRUE
 964  *    if loading was successful.  The `passphrase' is used as decryption
 965  *    key of the private key file.
 966  *
 967  ***/
 968 bool silc_pkcs_load_private_key(const char *filename,
 969                                 SilcPrivateKey *private_key,
 970                                 unsigned char *passphrase,
 971                                 SilcUInt32 passphrase_len,
 972                                 SilcUInt32 encoding);
 973
 974 #endif  /* !SILCPKCS_H */