5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2007 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* silccrypt/SILC PKCS Interface
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.
34 /* Forward declarations */
35 typedef struct SilcPKCSObjectStruct SilcPKCSObject;
37 /****d* silccrypt/SilcPKCSAPI/SilcPKCSType
41 * typedef enum { ... } SilcPKCSType;
45 * Public key cryptosystem types. These are defined by the SILC
46 * Key Exchange protocol.
51 SILC_PKCS_SILC = 1, /* SILC PKCS */
52 SILC_PKCS_SSH2 = 2, /* SSH2 PKCS (not supported) */
53 SILC_PKCS_X509V3 = 3, /* X.509v3 PKCS (not supported) */
54 SILC_PKCS_OPENPGP = 4, /* OpenPGP PKCS (not supported) */
55 SILC_PKCS_SPKI = 5, /* SPKI PKCS (not supported) */
59 /****s* silccrypt/SilcPKCSAPI/SilcPublicKey
63 * typedef struct { ... } *SilcPublicKey;
67 * This context represents any kind of PKCS public key. It can be
68 * allocated by silc_pkcs_public_key_alloc and is freed by the
69 * silc_pkcs_public_key_free. The PKCS specific public key context
70 * can be retrieved by calling silc_pkcs_get_context.
75 const SilcPKCSObject *pkcs; /* PKCS */
76 void *public_key; /* PKCS specific public key */
80 /****s* silccrypt/SilcPKCSAPI/SilcPrivateKey
84 * typedef struct { ... } *SilcPrivateKey;
88 * This context represents any kind of PKCS private key.
93 const SilcPKCSObject *pkcs; /* PKCS */
94 void *private_key; /* PKCS specific private key */
98 /****d* silccrypt/SilcPKCSAPI/SilcPKCSFileEncoding
102 * typedef enum { ... } SilcPKCSType
106 * Public and private key file encoding types.
111 SILC_PKCS_FILE_BIN, /* Binary encoding */
112 SILC_PKCS_FILE_BASE64 /* Base64 encoding */
113 } SilcPKCSFileEncoding;
116 /* The PKCS Algorithm object to represent any PKCS algorithm. */
118 /* Algorithm name and scheme */
122 /* Supported hash functions, comma separated list */
125 /* Generate new key pair. Returns PKCS algorithm specific public key
126 and private key contexts. */
127 SilcBool (*generate_key)(SilcUInt32 keylen,
129 void **ret_public_key,
130 void **ret_private_key);
132 /* Public key routines */
133 SilcBool (*import_public_key)(unsigned char *key,
135 void **ret_public_key);
136 unsigned char *(*export_public_key)(void *public_key,
137 SilcUInt32 *ret_len);
138 SilcUInt32 (*public_key_bitlen)(void *public_key);
139 void *(*public_key_copy)(void *public_key);
140 SilcBool (*public_key_compare)(void *key1, void *key2);
141 void (*public_key_free)(void *public_key);
143 /* Private key routines */
144 SilcBool (*import_private_key)(unsigned char *key,
146 void **ret_private_key);
147 unsigned char *(*export_private_key)(void *private_key,
148 SilcUInt32 *ret_len);
149 SilcUInt32 (*private_key_bitlen)(void *public_key);
150 void (*private_key_free)(void *private_key);
152 /* Encrypt and decrypt operations */
153 SilcBool (*encrypt)(void *public_key,
158 SilcUInt32 *ret_dst_len,
160 SilcBool (*decrypt)(void *private_key,
165 SilcUInt32 *ret_dst_len);
167 /* Signature and verification operations */
168 SilcBool (*sign)(void *private_key,
171 unsigned char *signature,
172 SilcUInt32 signature_size,
173 SilcUInt32 *ret_signature_len,
175 SilcBool (*verify)(void *public_key,
176 unsigned char *signature,
177 SilcUInt32 signature_len,
183 /* The PKCS (Public Key Cryptosystem) object to represent any PKCS. */
184 struct SilcPKCSObjectStruct {
188 /* Public key routines */
190 /* Returns PKCS algorithm context from public key */
191 const SilcPKCSAlgorithm *(*get_algorithm)(void *public_key);
193 /* Imports from public key file */
194 SilcBool (*import_public_key_file)(unsigned char *filedata,
195 SilcUInt32 filedata_len,
196 SilcPKCSFileEncoding encoding,
197 void **ret_public_key);
199 /* Imports from public key binary data */
200 SilcBool (*import_public_key)(unsigned char *key,
202 void **ret_public_key);
204 /* Exports public key to file */
205 unsigned char *(*export_public_key_file)(void *public_key,
206 SilcPKCSFileEncoding encoding,
207 SilcUInt32 *ret_len);
209 /* Export public key as binary data */
210 unsigned char *(*export_public_key)(void *public_key,
211 SilcUInt32 *ret_len);
213 /* Returns key length in bits */
214 SilcUInt32 (*public_key_bitlen)(void *public_key);
216 /* Copy public key */
217 void *(*public_key_copy)(void *public_key);
219 /* Compares public keys */
220 SilcBool (*public_key_compare)(void *key1, void *key2);
222 /* Free public key */
223 void (*public_key_free)(void *public_key);
225 /* Private key routines */
227 /* Imports from private key file */
228 SilcBool (*import_private_key_file)(unsigned char *filedata,
229 SilcUInt32 filedata_len,
230 const char *passphrase,
231 SilcUInt32 passphrase_len,
232 SilcPKCSFileEncoding encoding,
233 void **ret_private_key);
235 /* Imports from private key binary data */
236 SilcBool (*import_private_key)(unsigned char *key,
238 void **ret_private_key);
240 /* Exports private key to file */
241 unsigned char *(*export_private_key_file)(void *private_key,
242 const char *passphrase,
243 SilcUInt32 passphrase_len,
244 SilcPKCSFileEncoding encoding,
246 SilcUInt32 *ret_len);
248 /* Export private key as binary data */
249 unsigned char *(*export_private_key)(void *private_key,
250 SilcUInt32 *ret_len);
252 /* Returns key length in bits */
253 SilcUInt32 (*private_key_bitlen)(void *private_key);
255 /* Free private key */
256 void (*private_key_free)(void *private_key);
258 /* Encrypt and decrypt operations */
259 SilcBool (*encrypt)(void *public_key,
264 SilcUInt32 *ret_dst_len,
266 SilcBool (*decrypt)(void *private_key,
271 SilcUInt32 *ret_dst_len);
273 /* Signature and verification operations */
274 SilcBool (*sign)(void *private_key,
277 unsigned char *signature,
278 SilcUInt32 signature_size,
279 SilcUInt32 *ret_signature_len,
281 SilcBool (*verify)(void *public_key,
282 unsigned char *signature,
283 SilcUInt32 signature_len,
289 /* Marks for all PKCS in silc. This can be used in silc_pkcs_unregister
290 to unregister all PKCS at once. */
291 #define SILC_ALL_PKCS ((SilcPKCSObject *)1)
292 #define SILC_ALL_PKCS_ALG ((SilcPKCSAlgorithm *)1)
294 /* Static lists of PKCS and PKCS algorithms. */
295 extern DLLAPI const SilcPKCSObject silc_default_pkcs[];
296 extern DLLAPI const SilcPKCSAlgorithm silc_default_pkcs_alg[];
300 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_register
304 * SilcBool silc_pkcs_register(const SilcPKCSObject *pkcs);
308 * Registers a new PKCS into the SILC. This function is used
309 * at the initialization of the SILC. All registered PKCSs
310 * should be unregistered with silc_pkcs_unregister. The `pkcs' includes
311 * the name of the PKCS and member functions for the algorithm. Usually
312 * this function is not called directly. Instead, application can call
313 * the silc_pkcs_register_default to register all PKCSs that are
314 * builtin the sources. Returns FALSE on error.
317 SilcBool silc_pkcs_register(const SilcPKCSObject *pkcs);
319 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_unregister
323 * SilcBool silc_pkcs_unregister(SilcPKCSObject *pkcs);
327 * Unregister a PKCS from the SILC. Returns FALSE on error.
330 SilcBool silc_pkcs_unregister(SilcPKCSObject *pkcs);
332 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_algorithm_register
336 * SilcBool silc_pkcs_algorithm_register(const SilcPKCSAlgorithm *pkcs);
340 * Registers a new PKCS Algorithm into the SILC. This function is used
341 * at the initialization of the SILC. All registered PKCS algorithms
342 * should be unregistered with silc_pkcs_unregister.
345 SilcBool silc_pkcs_algorithm_register(const SilcPKCSAlgorithm *pkcs);
347 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_algorithm_unregister
351 * SilcBool silc_pkcs_algorithm_unregister(SilcPKCSAlgorithm *pkcs);
355 * Unregister a PKCS from the SILC. Returns FALSE on error.
358 SilcBool silc_pkcs_algorithm_unregister(SilcPKCSAlgorithm *pkcs);
360 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_register_default
364 * SilcBool silc_pkcs_register_default(void);
368 * Registers all the default PKCS (all builtin PKCS) and PKCS algorithms.
369 * The application may use this to register the default PKCS if specific
370 * PKCS in any specific order is not wanted. Returns FALSE on error.
373 SilcBool silc_pkcs_register_default(void);
375 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_unregister_all
379 * SilcBool silc_pkcs_unregister_all(void);
383 * Unregister all PKCS and PKCS algorithms. Returns FALSE on error.
386 SilcBool silc_pkcs_unregister_all(void);
388 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_supported
392 * char *silc_pkcs_get_supported(void);
396 * Returns comma separated list of supported PKCS algorithms.
399 char *silc_pkcs_get_supported(void);
401 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_find_pkcs
405 * const SilcPKCSObject *silc_pkcs_get_pkcs(SilcPKCSType type);
409 * Finds PKCS context by the PKCS type.
412 const SilcPKCSObject *silc_pkcs_find_pkcs(SilcPKCSType type);
414 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_find_algorithm
418 * const SilcPKCSAlgorithm *silc_pkcs_find_algorithm(const char *algorithm,
419 * const char *scheme);
423 * Finds PKCS algorithm context by the algorithm name `algorithm' and
424 * the algorithm scheme `scheme'. The `scheme' may be NULL.
427 const SilcPKCSAlgorithm *silc_pkcs_find_algorithm(const char *algorithm,
430 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_pkcs
434 * const SilcPKCSObject *silc_pkcs_get_pkcs(void *key);
438 * Returns the PKCS object from `key', which may be SilcPublicKey or
439 * SilcPrivateKey pointer.
442 const SilcPKCSObject *silc_pkcs_get_pkcs(void *key);
444 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_algorithm
448 * const SilcPKCSAlgorithm *silc_pkcs_get_algorithm(void *key);
452 * Returns the PKCS algorithm object from `key', which may be SilcPublicKey
453 * or SilcPrivateKey pointer.
456 const SilcPKCSAlgorithm *silc_pkcs_get_algorithm(void *key);
458 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_name
462 * const char *silc_pkcs_get_name(void *key);
466 * Returns PKCS algorithm name from the `key', which may be SilcPublicKey
467 * or SilcPrivateKey pointer.
470 const char *silc_pkcs_get_name(void *key);
472 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_type
476 * SilcPKCSType silc_pkcs_get_type(void *key);
480 * Returns PKCS type from the `key', which may be SilcPublicKey or
481 * SilcPrivateKey pointer.
484 SilcPKCSType silc_pkcs_get_type(void *key);
486 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_context
490 * void *silc_pkcs_get_context(SilcPKCSType type, SilcPublicKey public_key);
494 * Returns the internal PKCS `type' specific public key context from the
495 * `public_key'. The caller needs to explicitly type cast it to correct
496 * type. Returns NULL on error.
498 * For SILC_PKCS_SILC the returned context is SilcSILCPublicKey.
501 void *silc_pkcs_get_context(SilcPKCSType type, SilcPublicKey public_key);
503 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_alloc
507 * SilcBool silc_pkcs_public_key_alloc(SilcPKCSType type,
508 * unsigned char *key,
510 * SilcPublicKey *ret_public_key);
514 * Allocates SilcPublicKey of the type of `type' from the key data
515 * `key' of length of `key_len' bytes. Returns FALSE if the `key'
516 * is malformed or unsupported public key type. This function can be
517 * used to create public key from any kind of PKCS public keys that
518 * the implementation supports.
521 SilcBool silc_pkcs_public_key_alloc(SilcPKCSType type,
524 SilcPublicKey *ret_public_key);
526 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_free
530 * void silc_pkcs_public_key_free(SilcPublicKey public_key);
534 * Frees the public key.
537 void silc_pkcs_public_key_free(SilcPublicKey public_key);
539 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_export
543 * unsigned char *silc_pkcs_public_key_encode(SilcPublicKey public_key,
544 * SilcUInt32 *ret_len);
548 * Encodes the `public_key' into a binary format and returns it. Returns
549 * NULL on error. Caller must free the returned buffer.
552 unsigned char *silc_pkcs_public_key_encode(SilcPublicKey public_key,
553 SilcUInt32 *ret_len);
555 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_get_len
559 * SilcUInt32 silc_pkcs_public_key_get_len(SilcPublicKey public_key);
563 * Returns the key length in bits from the public key.
566 SilcUInt32 silc_pkcs_public_key_get_len(SilcPublicKey public_key);
568 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_compare
572 * SilcBool silc_pkcs_public_key_compare(SilcPublicKey key1,
573 * SilcPublicKey key2);
577 * Compares two public keys and returns TRUE if they are same key, and
578 * FALSE if they are not same.
581 SilcBool silc_pkcs_public_key_compare(SilcPublicKey key1, SilcPublicKey key2);
583 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_copy
587 * SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
591 * Copies the public key indicated by `public_key' and returns new
592 * allocated public key which is indentical to the `public_key'.
595 SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
597 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_alloc
601 * SilcBool silc_pkcs_private_key_alloc(SilcPKCSType type,
602 * unsigned char *key,
603 * SilcUInt32 key_len,
604 * SilcPrivateKey *ret_private_key);
608 * Allocates SilcPrivateKey of the type of `type' from the key data
609 * `key' of length of `key_len' bytes. Returns FALSE if the `key'
610 * is malformed or unsupported private key type.
613 SilcBool silc_pkcs_private_key_alloc(SilcPKCSType type,
616 SilcPrivateKey *ret_private_key);
618 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_get_len
622 * SilcUInt32 silc_pkcs_private_key_get_len(SilcPrivateKey private_key);
626 * Returns the key length in bits from the private key.
629 SilcUInt32 silc_pkcs_private_key_get_len(SilcPrivateKey private_key);
631 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_free
635 * void silc_pkcs_private_key_free(SilcPrivateKey private_key;
639 * Frees the private key.
642 void silc_pkcs_private_key_free(SilcPrivateKey private_key);
644 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_encrypt
648 * SilcBool silc_pkcs_encrypt(SilcPublicKey public_key,
649 * unsigned char *src, SilcUInt32 src_len,
650 * unsigned char *dst, SilcUInt32 dst_size,
651 * SilcUInt32 *dst_len);
655 * Encrypts with the public key. Returns FALSE on error.
658 SilcBool silc_pkcs_encrypt(SilcPublicKey public_key,
659 unsigned char *src, SilcUInt32 src_len,
660 unsigned char *dst, SilcUInt32 dst_size,
661 SilcUInt32 *dst_len, SilcRng rng);
663 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_decrypt
667 * SilcBool silc_pkcs_decrypt(SilcPrivateKey private_key,
668 * unsigned char *src, SilcUInt32 src_len,
669 * unsigned char *dst, SilcUInt32 dst_size,
670 * SilcUInt32 *dst_len);
674 * Decrypts with the private key. Returns FALSE on error.
677 SilcBool silc_pkcs_decrypt(SilcPrivateKey private_key,
678 unsigned char *src, SilcUInt32 src_len,
679 unsigned char *dst, SilcUInt32 dst_size,
680 SilcUInt32 *dst_len);
682 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_sign
686 * SilcBool silc_pkcs_sign(SilcPrivateKey private_key,
687 * unsigned char *src, SilcUInt32 src_len,
688 * unsigned char *dst, SilcUInt32 dst_size,
689 * SilcUInt32 *dst_len, SilcHash hash);
693 * Generates signature with the private key. Returns FALSE on error.
694 * If `hash' is non-NULL the `src' will be hashed before signing.
697 SilcBool silc_pkcs_sign(SilcPrivateKey private_key,
698 unsigned char *src, SilcUInt32 src_len,
699 unsigned char *dst, SilcUInt32 dst_size,
700 SilcUInt32 *dst_len, SilcHash hash);
702 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_verify
706 * SilcBool silc_pkcs_verify(SilcPublicKey public_key,
707 * unsigned char *signature,
708 * SilcUInt32 signature_len,
709 * unsigned char *data,
710 * SilcUInt32 data_len, SilcHash hash);
714 * Verifies signature. Returns FALSE on error. The 'signature' is
715 * verified against the 'data'. If the `hash' is non-NULL then the `data'
716 * will hashed before verification. If the `hash' is NULL, then the
717 * hash algorithm to be used is retrieved from the signature. If it
718 * isn't present in the signature the verification is done as is without
722 SilcBool silc_pkcs_verify(SilcPublicKey public_key,
723 unsigned char *signature,
724 SilcUInt32 signature_len,
726 SilcUInt32 data_len, SilcHash hash);
728 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_load_public_key
732 * SilcBool silc_pkcs_load_public_key(const char *filename,
733 * SilcPublicKey *ret_public_key);
737 * Loads public key from file and allocates new public key. Returns TRUE
738 * if loading was successful.
741 SilcBool silc_pkcs_load_public_key(const char *filename,
742 SilcPublicKey *ret_public_key);
744 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_public_key
748 * SilcBool silc_pkcs_save_public_key(const char *filename,
749 * SilcPublicKey public_key,
750 * SilcPKCSFileEncoding encoding);
754 * Saves public key into file with specified encoding. Returns FALSE
758 SilcBool silc_pkcs_save_public_key(const char *filename,
759 SilcPublicKey public_key,
760 SilcPKCSFileEncoding encoding);
762 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_load_private_key
766 * SilcBool silc_pkcs_load_private_key(const char *filename,
767 * const unsigned char *passphrase,
768 * SilcUInt32 passphrase_len,
769 * SilcPrivateKey *ret_private_key);
773 * Loads private key from file and allocates new private key. Returns TRUE
774 * if loading was successful. The `passphrase' is used as decryption
775 * key of the private key file, in case it is encrypted.
778 SilcBool silc_pkcs_load_private_key(const char *filename,
779 const unsigned char *passphrase,
780 SilcUInt32 passphrase_len,
781 SilcPrivateKey *ret_private_key);
783 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_private_key
787 * SilcBool silc_pkcs_save_private_key(const char *filename,
788 * SilcPrivateKey private_key,
789 * const unsigned char *passphrase,
790 * SilcUInt32 passphrase_len,
791 * SilcPKCSFileEncoding encoding,
796 * Saves private key into file. The private key is encrypted into
797 * the file with the `passphrase' as a key, if PKCS supports encrypted
798 * private keys. Returns FALSE on error.
801 SilcBool silc_pkcs_save_private_key(const char *filename,
802 SilcPrivateKey private_key,
803 const unsigned char *passphrase,
804 SilcUInt32 passphrase_len,
805 SilcPKCSFileEncoding encoding,
808 #endif /* !SILCPKCS_H */