5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2007 - 2008 Pekka Riikonen
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.
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.
20 /****h* silcpgp/OpenPGP Interface
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.
30 * The interface implements the RFC 2440 and rfc2440bis-22 Internet Draft
38 /****s* silcpgp/SilcPGPPublicKey
42 * typedef struct { ... } *SilcPGPPublicKey;
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.
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 */
57 const SilcPKCSAlgorithm *pkcs; /* PKCS Algorithm */
58 void *public_key; /* PKCS Algorithm specific public key */
60 unsigned char key_id[8]; /* Public key ID */
61 unsigned char fingerprint[20]; /* Fingerprint of the public key */
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 */
70 /****s* silcpgp/SilcPGPPrivateKey
74 * typedef struct { ... } *SilcPGPPrivateKey;
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.
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 */
89 SilcPGPPublicKey public_key; /* Public key */
90 void *private_key; /* Algorithm specific private key */
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 */
99 /****s* silcpgp/SilcPGPPacket
103 * typedef struct SilcPGPPacketStruct *SilcPGPPacket;
107 * OpenPGP packet context. This context is allocated by calling
108 * silc_pgp_packet_decode.
111 typedef struct SilcPGPPacketStruct *SilcPGPPacket;
113 /****d* silcpgp/SilcPGPPacketTag
117 * typedef enum { ... } SilcPGPPacketTag;
121 * OpenPGP packet types.
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 */
146 /****d* silcpgp/SilcPGPPKCSAlgorithm
150 * typedef enum { ... } SilcPGPPKCSAlgorithm;
154 * OpenPGP public key cryptosystem algorithms.
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;
170 /****d* silcpgp/SilcPGPCipher
174 * typedef enum { ... } SilcPGPCipher;
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 */
195 /****d* silcpgp/SilcPGPHash
199 * typedef enum { ... } SilcPGPHash;
203 * OpenPGP hash functions.
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 */
218 /****d* silcpgp/SilcPGPS2KType
222 * typedef enum { ... } SilcPGPS2KType;
226 * String-to-key (S2K) specifier types. These define how the passphrase
227 * is converted into encryption and decryption key.
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 */
238 /****d* silcpgp/SilcPGPKeyType
242 * typedef enum { ... } SilcPGPKeyType;
246 * PGP key generation types. These types define what kind of PGP key
247 * is created with silc_pgp_generate_key.
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
257 * Generates signature only DSA key. The key cannot be used for
262 * Generates signature only ECDSA key. The key cannot be used for
265 * SILC_PGP_DSA_SIG_ELGAMAL_ENC
267 * Generates key with DSA for signatures and Elgamal for encryption.
269 * SILC_PGP_DSA_SIG_RSA_ENC
271 * Generates key with DSA for signatures and RSA for encryption.
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 */
284 typedef struct SilcPgpKeygenParamsStruct {
292 } SilcPgpKeygenParams;
295 SilcBool silc_pgp_generate_key(SilcPgpKeygenParams *params,
298 SilcPublicKey *ret_public_key,
299 SilcPrivateKey *ret_private_key);
301 /****f* silcpgp/silc_pgp_packet_decode
305 * SilcBool silc_pgp_packet_decode(const unsigned char *data,
306 * SilcUInt32 data_len,
308 * SilcList *ret_list);
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.
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.
327 * unsigned char *data;
328 * SilcUInt32 data_len;
329 * SilcPGPPublicKey public_key;
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);
335 * // Parse public key
336 * silc_pgp_public_key_decode(&list, &public_key);
339 int silc_pgp_packet_decode(const unsigned char *data,
344 /****f* silcpgp/silc_pgp_packet_get_tag
348 * SilcPGPPacketTag silc_pgp_packet_get_tag(SilcPGPPacket packet);
352 * Returns the OpenPGP packet tag (packet type) from `packet'.
355 SilcPGPPacketTag silc_pgp_packet_get_tag(SilcPGPPacket packet);
357 /****f* silcpgp/silc_pgp_packet_get_data
361 * unsigned char *silc_pgp_packet_get_data(SilcPGPPacket packet,
362 * SilcUInt32 *data_len);
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.
371 unsigned char *silc_pgp_packet_get_data(SilcPGPPacket packet,
372 SilcUInt32 *data_len);
374 /****f* silcpgp/silc_pgp_packet_free
378 * void silc_pgp_packet_free(SilcPGPPacket packet);
385 void silc_pgp_packet_free(SilcPGPPacket packet);
387 /****f* silcpgp/silc_pgp_packet_free_list
391 * void silc_pgp_packet_free_list(SilcList *list);
395 * Free all PGP packets from the `list'. All packets in the list will
396 * become invalid after this call.
399 void silc_pgp_packet_free_list(SilcList *list);
401 /****f* silcpgp/silc_pgp_public_key_decode
405 * SilcBool silc_pgp_public_key_decode(SilcList *list,
406 * SilcPGPPublicKey *ret_public_key);
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.
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.
422 SilcBool silc_pgp_public_key_decode(SilcList *pubkey,
423 SilcPGPPublicKey *ret_public_key);
425 /****f* silcpgp/silc_pgp_public_key_free
429 * void silc_pgp_public_key_free(SilcPGPPublicKey public_key);
433 * Frees the public key.
436 void silc_pgp_public_key_free(SilcPGPPublicKey public_key);
438 /****f* silcpgp/silc_pgp_private_key_decode
442 * SilcBool silc_pgp_private_key_decode(SilcList *list,
443 * const char *passphrase,
444 * SilcUInt32 passphrase_len,
445 * SilcPGPPrivateKey *ret_private_key);
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.
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.
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.
465 SilcBool silc_pgp_private_key_decode(SilcList *list,
466 const char *passphrase,
467 SilcUInt32 passphrase_len,
468 SilcPGPPrivateKey *ret_private_key);
470 /****f* silcpgp/silc_pgp_private_key_free
474 * void silc_pgp_private_key_free(SilcPGPPrivateKey private_key);
478 * Frees the private key.
481 void silc_pgp_private_key_free(SilcPGPPrivateKey private_key);
483 /****f* silcpgp/silc_pgp_s2k
487 * unsigned char *silc_pgp_s2k(SilcPGPS2KType type,
489 * const char *passphrase,
490 * SilcUInt32 passphrase_len,
491 * SilcUInt32 key_len,
492 * unsigned char *salt,
493 * SilcUInt32 iter_octet_count,
498 * Computes the OpenPGP string-to-key (S2K). Converts passphrases to
499 * encryption and decryption keys. The `passphrase' must be non-NULL.
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).
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.
512 unsigned char *silc_pgp_s2k(SilcPGPS2KType type,
514 const char *passphrase,
515 SilcUInt32 passphrase_len,
518 SilcUInt32 iter_count,
521 unsigned char *silc_pgp_dearmor(unsigned char *data,
523 SilcUInt32 *ret_len);
525 #include "silcpgp_i.h"
527 #endif /* SILCPGP_H */