lib/silcpgp/silcpgp.h

   1 /*
   2
   3   silcpgp.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2007 - 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* silcpgp/OpenPGP Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * This implementation supports OpenPGP public key versions 2, 3 and 4.
  25  * OpenPGP private key support exist only for version 4.  This means that
  26  * this API can be used verify signatures with all versions of OpenPGP public
  27  * keys, but signatures can only be computed with version 4 private keys.
  28  * This implementation also only generates version 4 private keys.
  29  *
  30  * The interface implements the RFC 2440 and rfc2440bis-22 Internet Draft
  31  * specifications.
  32  *
  33  ***/
  34
  35 #ifndef SILCPGP_H
  36 #define SILCPGP_H
  37
  38 /****s* silcpgp/SilcPGPPublicKey
  39  *
  40  * NAME
  41  *
  42  *    typedef struct { ... } *SilcPGPPublicKey;
  43  *
  44  * DESCRIPTION
  45  *
  46  *    This structure defines the OpenPGP public key (certificate).  This
  47  *    context can be retrieved from SilcPublicKey by calling
  48  *    silc_pkcs_public_key_get_pkcs for the PKCS type SILC_PKCS_OPENPGP.
  49  *
  50  * SOURCE
  51  */
  52 typedef struct SilcPGPPublicKeyStruct {
  53   SilcList packets;                /* Packets making this public key, contains
  54                                       main key, subkeys, signatures etc. */
  55   SilcDList subkeys;               /* Subkeys, each is SilcPGPPublicKey */
  56
  57   const SilcPKCSAlgorithm *pkcs;   /* PKCS Algorithm */
  58   void *public_key;                /* PKCS Algorithm specific public key */
  59
  60   unsigned char key_id[8];         /* Public key ID */
  61   unsigned char fingerprint[20];   /* Fingerprint of the public key */
  62
  63   SilcUInt32 created;              /* Time when public key was created */
  64   SilcUInt16 valid;                /* Validity period (V3 keys) */
  65   SilcUInt8 version;               /* Version, 2, 3 or 4 */
  66   SilcUInt8 algorithm;             /* Algorithm, SilcPGPPKCSAlgorithm */
  67 } *SilcPGPPublicKey;
  68 /***/
  69
  70 /****s* silcpgp/SilcPGPPrivateKey
  71  *
  72  * NAME
  73  *
  74  *    typedef struct { ... } *SilcPGPPrivateKey;
  75  *
  76  * DESCRIPTION
  77  *
  78  *    This structure defines the OpenPGP private key.  This context can be
  79  *    retrieved from SilcPublicKey by calling silc_pkcs_private_key_get_pkcs
  80  *    for the PKCS type SILC_PKCS_OPENPGP.
  81  *
  82  * SOURCE
  83  */
  84 typedef struct SilcPGPPrivateKeyStruct {
  85   SilcList packets;                /* Packets making this private key, contains
  86                                       main key, subkeys, signatures etc. */
  87   SilcDList subkeys;               /* Subkeys, each is SilcPGPPrivateKey */
  88
  89   SilcPGPPublicKey public_key;     /* Public key */
  90   void *private_key;               /* Algorithm specific private key */
  91
  92   SilcUInt32 s2k_count;            /* S2K iterate octet count */
  93   SilcUInt8 cipher;                /* Cipher, SilcPGPCipher */
  94   SilcUInt8 s2k_type;              /* S2K type, SilcPGPS2KType */
  95   SilcUInt8 s2k_hash;              /* Hash, SilcPGPHash */
  96 } *SilcPGPPrivateKey;
  97 /***/
  98
  99 /****s* silcpgp/SilcPGPPacket
 100  *
 101  * NAME
 102  *
 103  *    typedef struct SilcPGPPacketStruct *SilcPGPPacket;
 104  *
 105  * DESCRIPTION
 106  *
 107  *    OpenPGP packet context.  This context is allocated by calling
 108  *    silc_pgp_packet_decode.
 109  *
 110  ***/
 111 typedef struct SilcPGPPacketStruct *SilcPGPPacket;
 112
 113 /****d* silcpgp/SilcPGPPacketTag
 114  *
 115  * NAME
 116  *
 117  *    typedef enum { ... } SilcPGPPacketTag;
 118  *
 119  * DESCRIPTION
 120  *
 121  *    OpenPGP packet types.
 122  *
 123  * SOURCE
 124  */
 125 typedef enum {
 126   SILC_PGP_PACKET_PKENC_SK        = 1,   /* Public key enc session key */
 127   SILC_PGP_PACKET_SIGNATURE       = 2,   /* Signature packet */
 128   SILC_PGP_PACKET_SENC_SK         = 3,   /* Symmetric-key enc session key */
 129   SILC_PGP_PACKET_OP_SIGNATURE    = 4,   /* One pass signature packet */
 130   SILC_PGP_PACKET_SECKEY          = 5,   /* Secret key packet */
 131   SILC_PGP_PACKET_PUBKEY          = 6,   /* Public key packet */
 132   SILC_PGP_PACKET_SECKEY_SUB      = 7,   /* Secret subkey packet */
 133   SILC_PGP_PACKET_COMP_DATA       = 8,   /* Compressed data packet */
 134   SILC_PGP_PACKET_SENC_DATA       = 9,   /* Symmetrically enc data packet */
 135   SILC_PGP_PACKET_MARKER          = 10,  /* Marker packet */
 136   SILC_PGP_PACKET_LITERAL_DATA    = 11,  /* Literal data packet */
 137   SILC_PGP_PACKET_TRUST           = 12,  /* Trust packet */
 138   SILC_PGP_PACKET_USER_ID         = 13,  /* User ID packet */
 139   SILC_PGP_PACKET_PUBKEY_SUB      = 14,  /* Public subkey packet */
 140   SILC_PGP_PACKET_USER_ATTR       = 17,  /* User attribute packet */
 141   SILC_PGP_PACKET_SENC_I_DATA     = 18,  /* Symmetric key enc/integ data */
 142   SILC_PGP_PACKET_MDC             = 19,  /* Modification detection code */
 143 } SilcPGPPacketTag;
 144 /***/
 145
 146 /****d* silcpgp/SilcPGPPKCSAlgorithm
 147  *
 148  * NAME
 149  *
 150  *    typedef enum { ... } SilcPGPPKCSAlgorithm;
 151  *
 152  * DESCRIPTION
 153  *
 154  *    OpenPGP public key cryptosystem algorithms.
 155  *
 156  * SOURCE
 157  */
 158 typedef enum {
 159   SILC_PGP_PKCS_RSA               = 1,   /* RSA */
 160   SILC_PGP_PKCS_RSA_ENC_ONLY      = 2,   /* RSA encryption allowed only */
 161   SILC_PGP_PKCS_RSA_SIG_ONLY      = 3,   /* RSA signatures allowed only */
 162   SILC_PGP_PKCS_ELGAMAL_ENC_ONLY  = 16,  /* Elgamal encryption only */
 163   SILC_PGP_PKCS_DSA               = 17,  /* DSA */
 164   SILC_PGP_PKCS_ECDSA             = 19,  /* ECDSA */
 165   SILC_PGP_PKCS_ELGAMAL           = 20,  /* Elgamal encryption/signatures */
 166   SILC_PGP_PKCS_DH                = 21,  /* Diffie-Hellman */
 167 } SilcPGPPKCSAlgorithm;
 168 /***/
 169
 170 /****d* silcpgp/SilcPGPCipher
 171  *
 172  * NAME
 173  *
 174  *    typedef enum { ... } SilcPGPCipher;
 175  *
 176  * DESCRIPTION
 177  *
 178  *    OpenPGP ciphers.
 179  *
 180  * SOURCE
 181  */
 182 typedef enum {
 183   SILC_PGP_CIPHER_NONE            = 0,   /* No cipher, plaintext */
 184   SILC_PGP_CIPHER_IDEA            = 1,   /* IDEA */
 185   SILC_PGP_CIPHER_3DES            = 2,   /* Triple-DES */
 186   SILC_PGP_CIPHER_CAST5           = 3,   /* CAST5 (CAST-128) */
 187   SILC_PGP_CIPHER_BLOWFISH        = 4,   /* Blowfish */
 188   SILC_PGP_CIPHER_AES128          = 7,   /* AES 128-bit key */
 189   SILC_PGP_CIPHER_AES192          = 8,   /* AES 192-bit key */
 190   SILC_PGP_CIPHER_AES256          = 9,   /* AES 256-bit key */
 191   SILC_PGP_CIPHER_TWOFISH         = 10,  /* Twofish 256-bit key */
 192 } SilcPGPCipher;
 193 /***/
 194
 195 /****d* silcpgp/SilcPGPHash
 196  *
 197  * NAME
 198  *
 199  *    typedef enum { ... } SilcPGPHash;
 200  *
 201  * DESCRIPTION
 202  *
 203  *    OpenPGP hash functions.
 204  *
 205  * SOURCE
 206  */
 207 typedef enum {
 208   SILC_PGP_HASH_MD5               = 1,   /* MD5 */
 209   SILC_PGP_HASH_SHA1              = 2,   /* SHA-1 */
 210   SILC_PGP_HASH_RIPEMD160         = 3,   /* RIPE-MD160 */
 211   SILC_PGP_HASH_SHA256            = 8,   /* SHA-256 */
 212   SILC_PGP_HASH_SHA384            = 9,   /* SHA-394 */
 213   SILC_PGP_HASH_SHA512            = 10,  /* SHA-512 */
 214   SILC_PGP_HASH_SHA224            = 11,  /* SHA-224 */
 215 } SilcPGPHash;
 216 /***/
 217
 218 /****d* silcpgp/SilcPGPS2KType
 219  *
 220  * NAME
 221  *
 222  *    typedef enum { ... } SilcPGPS2KType;
 223  *
 224  * DESCRIPTION
 225  *
 226  *    String-to-key (S2K) specifier types.  These define how the passphrase
 227  *    is converted into encryption and decryption key.
 228  *
 229  * SOURCE
 230  */
 231 typedef enum {
 232   SILC_PGP_S2K_SIMPLE             = 0,   /* Simple S2K */
 233   SILC_PGP_S2K_SALTED             = 1,   /* Salted S2K */
 234   SILC_PGP_S2K_ITERATED_SALTED    = 3,   /* Iterated and salted S2K */
 235 } SilcPGPS2KType;
 236 /***/
 237
 238 /****d* silcpgp/SilcPGPKeyType
 239  *
 240  * NAME
 241  *
 242  *    typedef enum { ... } SilcPGPKeyType;
 243  *
 244  * DESCRIPTION
 245  *
 246  *    PGP key generation types.  These types define what kind of PGP key
 247  *    is created with silc_pgp_generate_key.
 248  *
 249  *    SILC_PGP_RSA
 250  *
 251  *      Generates RSA key that can be used for both signatures and encryption.
 252  *      This is default.  If key type is not specified, this is used as
 253  *      default key type.
 254  *
 255  *    SILC_PGP_DSA_SIG
 256  *
 257  *      Generates signature only DSA key.  The key cannot be used for
 258  *      encryption.
 259  *
 260  *    SILC_PGP_ECDSA_SIG
 261  *
 262  *      Generates signature only ECDSA key.  The key cannot be used for
 263  *      encryption.
 264  *
 265  *    SILC_PGP_DSA_SIG_ELGAMAL_ENC
 266  *
 267  *      Generates key with DSA for signatures and Elgamal for encryption.
 268  *
 269  *    SILC_PGP_DSA_SIG_RSA_ENC
 270  *
 271  *      Generates key with DSA for signatures and RSA for encryption.
 272  *
 273  * SOURCE
 274  */
 275 typedef enum {
 276   SILC_PGP_RSA                     = 0,  /* Generate RSA key */
 277   SILC_PGP_DSA_SIG                 = 1,  /* Generate signature only DSA key */
 278   SILC_PGP_ECDSA_SIG               = 2,  /* Generate signature only ECDSA key */
 279   SILC_PGP_DSA_SIG_ELGAMAL_ENC     = 3,  /* Generate DSA and Elgamal key */
 280   SILC_PGP_DSA_SIG_RSA_ENC         = 4,  /* Generate DSA and RSA key */
 281 } SilcPGPKeyType;
 282 /***/
 283
 284 typedef struct SilcPgpKeygenParamsStruct {
 285   SilcPGPKeyType type;
 286   int key_len_bits;
 287
 288   int expire_days;
 289   int expire_weeks;
 290   int expire_months;
 291   int expire_years;
 292 } SilcPgpKeygenParams;
 293
 294 /* XXX TODO */
 295 SilcBool silc_pgp_generate_key(SilcPgpKeygenParams *params,
 296                                const char *user_id,
 297                                SilcRng rng,
 298                                SilcPublicKey *ret_public_key,
 299                                SilcPrivateKey *ret_private_key);
 300
 301 /****f* silcpgp/silc_pgp_packet_decode
 302  *
 303  * SYNOPSIS
 304  *
 305  *    SilcBool silc_pgp_packet_decode(const unsigned char *data,
 306  *                                    SilcUInt32 data_len,
 307  *                                    SilcBool *success,
 308  *                                    SilcList *ret_list);
 309  *
 310  * DESCRIPTION
 311  *
 312  *    Decodes PGP packets from the data buffer indicated by `data' of length
 313  *    of `data_len' bytes.  The data buffer may include one or more packets
 314  *    that are decoded and returned to the `ret_list'.  The caller must free
 315  *    the returned packets with silc_pgp_packet_free_list.  Each entry in
 316  *    the `ret_list' is SilcPGPPacket.
 317  *
 318  *    Returns the number of packets decoded or 0 on error.  If the `success'
 319  *    is FALSE but this returns > 0 then not all packets were decoded
 320  *    successfully and the `ret_list' includes the packets that were decoded.
 321  *    When the `success' is TRUE all packets were decoded successfully.
 322  *
 323  * EXAMPLE
 324  *
 325  *    SilcList list;
 326  *    SilcBool success;
 327  *    unsigned char *data;
 328  *    SilcUInt32 data_len;
 329  *    SilcPGPPublicKey public_key;
 330  *
 331  *    // Open public key file (binary format) and parse all PGP packets
 332  *    data = silc_file_readfile("pubkey.bin", &data_len, NULL);
 333  *    silc_pgp_packet_decode(data, data_len, &success, &list);
 334  *
 335  *    // Parse public key
 336  *    silc_pgp_public_key_decode(&list, &public_key);
 337  *
 338  ***/
 339 int silc_pgp_packet_decode(const unsigned char *data,
 340                            SilcUInt32 data_len,
 341                            SilcBool *success,
 342                            SilcList *ret_list);
 343
 344 /****f* silcpgp/silc_pgp_packet_get_tag
 345  *
 346  * SYNOPSIS
 347  *
 348  *    SilcPGPPacketTag silc_pgp_packet_get_tag(SilcPGPPacket packet);
 349  *
 350  * DESCRIPTION
 351  *
 352  *    Returns the OpenPGP packet tag (packet type) from `packet'.
 353  *
 354  ***/
 355 SilcPGPPacketTag silc_pgp_packet_get_tag(SilcPGPPacket packet);
 356
 357 /****f* silcpgp/silc_pgp_packet_get_data
 358  *
 359  * SYNOPSIS
 360  *
 361  *    unsigned char *silc_pgp_packet_get_data(SilcPGPPacket packet,
 362  *                                            SilcUInt32 *data_len);
 363  *
 364  * DESCRIPTION
 365  *
 366  *    Returns the packet data from the `packet'.  The returned pointer
 367  *    must not be freed by the caller.  The length of the data is returned
 368  *    into `data_len' pointer.
 369  *
 370  ***/
 371 unsigned char *silc_pgp_packet_get_data(SilcPGPPacket packet,
 372                                         SilcUInt32 *data_len);
 373
 374 /****f* silcpgp/silc_pgp_packet_free
 375  *
 376  * SYNOPSIS
 377  *
 378  *    void silc_pgp_packet_free(SilcPGPPacket packet);
 379  *
 380  * DESCRIPTION
 381  *
 382  *    Free PGP packet.
 383  *
 384  ***/
 385 void silc_pgp_packet_free(SilcPGPPacket packet);
 386
 387 /****f* silcpgp/silc_pgp_packet_free_list
 388  *
 389  * SYNOPSIS
 390  *
 391  *    void silc_pgp_packet_free_list(SilcList *list);
 392  *
 393  * DESCRIPTION
 394  *
 395  *    Free all PGP packets from the `list'.  All packets in the list will
 396  *    become invalid after this call.
 397  *
 398  ***/
 399 void silc_pgp_packet_free_list(SilcList *list);
 400
 401 /****f* silcpgp/silc_pgp_public_key_decode
 402  *
 403  * SYNOPSIS
 404  *
 405  *    SilcBool silc_pgp_public_key_decode(SilcList *list,
 406  *                                        SilcPGPPublicKey *ret_public_key);
 407  *
 408  * DESCRIPTION
 409  *
 410  *    Decodes OpenPGP public key (certificate) from decoded PGP packets list
 411  *    indicated by `list'.  The decoded public key is returned into the
 412  *    `ret_public_key' which the caller must free by calling the
 413  *    silc_pgp_public_key_free function.  Returns FALSE on error.
 414  *
 415  *    The `list' can be allocated by calling silc_pgp_packet_decode.
 416  *    If the `list' contains more that one public keys this only decodes
 417  *    the first one.  The public key `list' is advanced while decoding the
 418  *    public key.  If another public key follows the first public key, this
 419  *    function may be called again to decode that public key as well.
 420  *
 421  ***/
 422 SilcBool silc_pgp_public_key_decode(SilcList *pubkey,
 423                                     SilcPGPPublicKey *ret_public_key);
 424
 425 /****f* silcpgp/silc_pgp_public_key_free
 426  *
 427  * SYNOPSIS
 428  *
 429  *    void silc_pgp_public_key_free(SilcPGPPublicKey public_key);
 430  *
 431  * DESCRIPTION
 432  *
 433  *    Frees the public key.
 434  *
 435  ***/
 436 void silc_pgp_public_key_free(SilcPGPPublicKey public_key);
 437
 438 /****f* silcpgp/silc_pgp_private_key_decode
 439  *
 440  * SYNOPSIS
 441  *
 442  *    SilcBool silc_pgp_private_key_decode(SilcList *list,
 443  *                                         const char *passphrase,
 444  *                                         SilcUInt32 passphrase_len,
 445  *                                         SilcPGPPrivateKey *ret_private_key);
 446  *
 447  * DESCRIPTION
 448  *
 449  *    Decodes OpenPGP secret key (private key) from decoded PGP packets list
 450  *    indicated by `list'.  The decoded private key is returned into the
 451  *    `ret_private_key' which the caller must free by calling the
 452  *    silc_pgp_private_key_free function.  Returns FALSE on error.
 453  *
 454  *    The `passphrase' can be provided in case the private key is
 455  *    encrypted.  Usually all OpenPGP private keys are encrypted so the
 456  *    passphrase should be always provided.
 457  *
 458  *    The `list' can be allocated by calling silc_pgp_packet_decode.
 459  *    If the `list' contains more that one private keys this only decodes
 460  *    the first one.  The private key `list' is advanced while decoding the
 461  *    public key.  If another private key follows the first public key, this
 462  *    function may be called again to decode that private key as well.
 463  *
 464  ***/
 465 SilcBool silc_pgp_private_key_decode(SilcList *list,
 466                                      const char *passphrase,
 467                                      SilcUInt32 passphrase_len,
 468                                      SilcPGPPrivateKey *ret_private_key);
 469
 470 /****f* silcpgp/silc_pgp_private_key_free
 471  *
 472  * SYNOPSIS
 473  *
 474  *    void silc_pgp_private_key_free(SilcPGPPrivateKey private_key);
 475  *
 476  * DESCRIPTION
 477  *
 478  *    Frees the private key.
 479  *
 480  ***/
 481 void silc_pgp_private_key_free(SilcPGPPrivateKey private_key);
 482
 483 /****f* silcpgp/silc_pgp_s2k
 484  *
 485  * SYNOPSIS
 486  *
 487  *    unsigned char *silc_pgp_s2k(SilcPGPS2KType type,
 488  *                                SilcPGPHash hash,
 489  *                                const char *passphrase,
 490  *                                SilcUInt32 passphrase_len,
 491  *                                SilcUInt32 key_len,
 492  *                                unsigned char *salt,
 493  *                                SilcUInt32 iter_octet_count,
 494  *                                SilcRng rng);
 495  *
 496  * DESCRIPTION
 497  *
 498  *   Computes the OpenPGP string-to-key (S2K).  Converts passphrases to
 499  *   encryption and decryption keys.  The `passphrase' must be non-NULL.
 500  *
 501  *   The `type' specifies the S2K specifier type.  The `hash' is the
 502  *   hash algorithm used if the `type' is SILC_PGP_S2K_SALTED or
 503  *   SILC_PGP_S2K_ITERATED_SALTED.  If the `type' is
 504  *   SILC_PGP_S2K_ITERATED_SALTED the `iter_octet_count' is the number of
 505  *   bytes to iteratively hash (max value is 65536).
 506  *
 507  *   The `key_len' is the length of the key to produce in bytes.  If `salt'
 508  *   is NULL this will generate an encryption key.  If it is non-NULL this
 509  *   will use the salt to compute the decryption key.
 510  *
 511  ***/
 512 unsigned char *silc_pgp_s2k(SilcPGPS2KType type,
 513                             SilcPGPHash hash,
 514                             const char *passphrase,
 515                             SilcUInt32 passphrase_len,
 516                             SilcUInt32 key_len,
 517                             unsigned char *salt,
 518                             SilcUInt32 iter_count,
 519                             SilcRng rng);
 520
 521 unsigned char *silc_pgp_dearmor(unsigned char *data,
 522                                 SilcUInt32 data_len,
 523                                 SilcUInt32 *ret_len);
 524
 525 #include "silcpgp_i.h"
 526
 527 #endif /* SILCPGP_H */