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 SilcPKCSAlgorithmStruct SilcPKCSAlgorithm;
36 typedef struct SilcPKCSObjectStruct SilcPKCSObject;
38 /****d* silccrypt/SilcPKCSAPI/SilcPKCSType
42 * typedef enum { ... } SilcPKCSType;
46 * Supported public key cryptosystem types.
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.
74 typedef struct SilcPublicKeyStruct {
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.
92 typedef struct SilcPrivateKeyStruct {
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 /****f* silccrypt/SilcPKCSAPI/SilcPKCSEncryptCb
120 * typedef void (*SilcPKCSEncryptCb)(SilcBool success,
121 * const unsigned char *encrypted,
122 * SilcUInt32 encrypted_len,
127 * Encryption callback. This callback is given as argument to the
128 * silc_pkcs_encrypt and the encrypted data is delivered to the caller
129 * in this callback. The `encrypted' is the encrypted data. If the
130 * `success' is FALSE the encryption operation failed.
133 typedef void (*SilcPKCSEncryptCb)(SilcBool success,
134 const unsigned char *encrypted,
135 SilcUInt32 encrypted_len,
138 /****f* silccrypt/SilcPKCSAPI/SilcPKCSDecryptCb
142 * typedef void (*SilcPKCSDecryptCb)(SilcBool success,
143 * const unsigned char *decrypted,
144 * SilcUInt32 decrypted_len,
149 * Decryption callback. This callback is given as argument to the
150 * silc_pkcs_decrypt and the decrypted data is delivered to the caller
151 * in this callback. The `decrypted' is the decrypted data. If the
152 * `success' is FALSE the decryption operation failed.
155 typedef void (*SilcPKCSDecryptCb)(SilcBool success,
156 const unsigned char *decrypted,
157 SilcUInt32 decrypted_len,
160 /****f* silccrypt/SilcPKCSAPI/SilcPKCSSignCb
164 * typedef void (*SilcPKCSSignCb)(SilcBool success,
165 * const unsigned char *signature,
166 * SilcUInt32 signature_len,
171 * Signature callback. This callback is given as argument to the
172 * silc_pkcs_sign and the digitally signed data is delivered to the caller
173 * in this callback. The `signature' is the signature data. If the
174 * `success' is FALSE the signature operation failed.
177 typedef void (*SilcPKCSSignCb)(SilcBool success,
178 const unsigned char *signature,
179 SilcUInt32 signature_len,
182 /****f* silccrypt/SilcPKCSAPI/SilcPKCSVerifyCb
186 * typedef void (*SilcPKCSVerifyCb)(SilcBool success, void *context);
190 * Verification callback. This callback is given as argument to the
191 * silc_pkcs_verify and the result of the signature verification is
192 * deliver to the caller in this callback. If the `success' is FALSE
193 * the signature verification failed.
196 typedef void (*SilcPKCSVerifyCb)(SilcBool success, void *context);
198 #include "silcpkcs_i.h"
200 /* Marks for all PKCS in. This can be used in silc_pkcs_unregister to
201 unregister all PKCS at once. */
202 #define SILC_ALL_PKCS ((SilcPKCSObject *)1)
203 #define SILC_ALL_PKCS_ALG ((SilcPKCSAlgorithm *)1)
205 /* Static lists of PKCS and PKCS algorithms. */
206 extern DLLAPI const SilcPKCSObject silc_default_pkcs[];
207 extern DLLAPI const SilcPKCSAlgorithm silc_default_pkcs_alg[];
211 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_register
215 * SilcBool silc_pkcs_register(const SilcPKCSObject *pkcs);
219 * Registers a new PKCS into the crypto library. This function is used
220 * at the initialization of an application. All registered PKCSs
221 * should be unregistered with silc_pkcs_unregister. The `pkcs' includes
222 * the name of the PKCS and member functions for the algorithm. Usually
223 * this function is not called directly. Instead, application can call
224 * the silc_pkcs_register_default to register all PKCSs that are
225 * builtin the sources. Returns FALSE on error.
228 SilcBool silc_pkcs_register(const SilcPKCSObject *pkcs);
230 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_unregister
234 * SilcBool silc_pkcs_unregister(SilcPKCSObject *pkcs);
238 * Unregister a PKCS from the crypto library. Returns FALSE on error.
241 SilcBool silc_pkcs_unregister(SilcPKCSObject *pkcs);
243 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_algorithm_register
247 * SilcBool silc_pkcs_algorithm_register(const SilcPKCSAlgorithm *pkcs);
251 * Registers a new PKCS Algorithm into crypto library. This function
252 * is used at the initialization of an application. All registered PKCS
253 * algorithms should be unregistered with silc_pkcs_unregister.
256 SilcBool silc_pkcs_algorithm_register(const SilcPKCSAlgorithm *pkcs);
258 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_algorithm_unregister
262 * SilcBool silc_pkcs_algorithm_unregister(SilcPKCSAlgorithm *pkcs);
266 * Unregister a PKCS from the crypto library. Returns FALSE on error.
269 SilcBool silc_pkcs_algorithm_unregister(SilcPKCSAlgorithm *pkcs);
271 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_register_default
275 * SilcBool silc_pkcs_register_default(void);
279 * Registers all the default PKCS (all builtin PKCS) and PKCS algorithms.
280 * The application may use this to register the default PKCS if specific
281 * PKCS in any specific order is not wanted. Returns FALSE on error.
284 SilcBool silc_pkcs_register_default(void);
286 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_unregister_all
290 * SilcBool silc_pkcs_unregister_all(void);
294 * Unregister all PKCS and PKCS algorithms. Returns FALSE on error.
297 SilcBool silc_pkcs_unregister_all(void);
299 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_supported
303 * char *silc_pkcs_get_supported(void);
307 * Returns comma separated list of supported PKCS algorithms.
310 char *silc_pkcs_get_supported(void);
312 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_find_pkcs
316 * const SilcPKCSObject *silc_pkcs_get_pkcs(SilcPKCSType type);
320 * Finds PKCS context by the PKCS type.
323 const SilcPKCSObject *silc_pkcs_find_pkcs(SilcPKCSType type);
325 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_find_algorithm
329 * const SilcPKCSAlgorithm *silc_pkcs_find_algorithm(const char *algorithm,
330 * const char *scheme);
334 * Finds PKCS algorithm context by the algorithm name `algorithm' and
335 * the algorithm scheme `scheme'. The `scheme' may be NULL.
338 const SilcPKCSAlgorithm *silc_pkcs_find_algorithm(const char *algorithm,
341 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_pkcs
345 * const SilcPKCSObject *silc_pkcs_get_pkcs(void *key);
349 * Returns the PKCS object from `key', which may be SilcPublicKey or
350 * SilcPrivateKey pointer.
353 const SilcPKCSObject *silc_pkcs_get_pkcs(void *key);
355 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_algorithm
359 * const SilcPKCSAlgorithm *silc_pkcs_get_algorithm(void *key);
363 * Returns the PKCS algorithm object from `key', which may be SilcPublicKey
364 * or SilcPrivateKey pointer.
367 const SilcPKCSAlgorithm *silc_pkcs_get_algorithm(void *key);
369 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_name
373 * const char *silc_pkcs_get_name(void *key);
377 * Returns PKCS algorithm name from the `key', which may be SilcPublicKey
378 * or SilcPrivateKey pointer.
381 const char *silc_pkcs_get_name(void *key);
383 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_type
387 * SilcPKCSType silc_pkcs_get_type(void *key);
391 * Returns PKCS type from the `key', which may be SilcPublicKey or
392 * SilcPrivateKey pointer.
395 SilcPKCSType silc_pkcs_get_type(void *key);
397 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_context
401 * void *silc_pkcs_get_context(SilcPKCSType type, SilcPublicKey public_key);
405 * Returns the internal PKCS `type' specific public key context from the
406 * `public_key'. The caller needs to explicitly type cast it to correct
407 * type. Returns NULL on error.
409 * For SILC_PKCS_SILC the returned context is SilcSILCPublicKey.
412 void *silc_pkcs_get_context(SilcPKCSType type, SilcPublicKey public_key);
414 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_alloc
418 * SilcBool silc_pkcs_public_key_alloc(SilcPKCSType type,
419 * unsigned char *key,
421 * SilcPublicKey *ret_public_key);
425 * Allocates SilcPublicKey of the type of `type' from the key data
426 * `key' of length of `key_len' bytes. Returns FALSE if the `key'
427 * is malformed or unsupported public key type. This function can be
428 * used to create public key from any kind of PKCS public keys that
429 * the implementation supports.
432 SilcBool silc_pkcs_public_key_alloc(SilcPKCSType type,
435 SilcPublicKey *ret_public_key);
437 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_free
441 * void silc_pkcs_public_key_free(SilcPublicKey public_key);
445 * Frees the public key.
448 void silc_pkcs_public_key_free(SilcPublicKey public_key);
450 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_export
454 * unsigned char *silc_pkcs_public_key_encode(SilcStack stack,
455 * SilcPublicKey public_key,
456 * SilcUInt32 *ret_len);
460 * Encodes the `public_key' into a binary format and returns it. Returns
461 * NULL on error. Caller must free the returned buffer.
463 * If the `stack' is non-NULL the returned buffer is allocated from the
464 * `stack'. This call will consume `stack' so caller should push the stack
465 * before calling and then later pop it.
468 unsigned char *silc_pkcs_public_key_encode(SilcStack stack,
469 SilcPublicKey public_key,
470 SilcUInt32 *ret_len);
472 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_get_len
476 * SilcUInt32 silc_pkcs_public_key_get_len(SilcPublicKey public_key);
480 * Returns the key length in bits from the public key.
483 SilcUInt32 silc_pkcs_public_key_get_len(SilcPublicKey public_key);
485 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_compare
489 * SilcBool silc_pkcs_public_key_compare(SilcPublicKey key1,
490 * SilcPublicKey key2);
494 * Compares two public keys and returns TRUE if they are same key, and
495 * FALSE if they are not same.
498 SilcBool silc_pkcs_public_key_compare(SilcPublicKey key1, SilcPublicKey key2);
500 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_copy
504 * SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
508 * Copies the public key indicated by `public_key' and returns new
509 * allocated public key which is indentical to the `public_key'.
512 SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
514 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_alloc
518 * SilcBool silc_pkcs_private_key_alloc(SilcPKCSType type,
519 * unsigned char *key,
520 * SilcUInt32 key_len,
521 * SilcPrivateKey *ret_private_key);
525 * Allocates SilcPrivateKey of the type of `type' from the key data
526 * `key' of length of `key_len' bytes. Returns FALSE if the `key'
527 * is malformed or unsupported private key type.
530 SilcBool silc_pkcs_private_key_alloc(SilcPKCSType type,
533 SilcPrivateKey *ret_private_key);
535 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_get_len
539 * SilcUInt32 silc_pkcs_private_key_get_len(SilcPrivateKey private_key);
543 * Returns the key length in bits from the private key.
546 SilcUInt32 silc_pkcs_private_key_get_len(SilcPrivateKey private_key);
548 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_free
552 * void silc_pkcs_private_key_free(SilcPrivateKey private_key;
556 * Frees the private key.
559 void silc_pkcs_private_key_free(SilcPrivateKey private_key);
561 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_encrypt
565 * SilcAsyncOperation silc_pkcs_encrypt(SilcPublicKey public_key,
566 * unsigned char *src,
567 * SilcUInt32 src_len, SilcRng rng,
568 * SilcPKCSEncryptCb encrypt_cb,
573 * Encrypts with the public key. The `encrypt_cb' will be called to
574 * deliver the encrypted data. The encryption operation may be asynchronous
575 * if the `public_key' is accelerated public key. If this returns NULL
576 * the asynchronous operation cannot be controlled.
579 SilcAsyncOperation silc_pkcs_encrypt(SilcPublicKey public_key,
581 SilcUInt32 src_len, SilcRng rng,
582 SilcPKCSEncryptCb encrypt_cb,
585 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_decrypt
589 * SilcAsyncOperation silc_pkcs_decrypt(SilcPrivateKey private_key,
590 * unsigned char *src,
591 * SilcUInt32 src_len,
592 * SilcPKCSDecryptCb decrypt_cb,
597 * Decrypts with the private key. The `decrypt_cb' will be called to
598 * deliver the decrypted data. The decryption operation may be asynchronous
599 * if the `private_key' is accelerated private key. If this returns NULL
600 * the asynchronous operation cannot be controlled.
603 SilcAsyncOperation silc_pkcs_decrypt(SilcPrivateKey private_key,
604 unsigned char *src, SilcUInt32 src_len,
605 SilcPKCSDecryptCb decrypt_cb,
608 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_sign
612 * SilcAsyncOperation silc_pkcs_sign(SilcPrivateKey private_key,
613 * unsigned char *src,
614 * SilcUInt32 src_len,
615 * SilcBool compute_hash,
617 * SilcPKCSSignCb sign_cb,
622 * Computes signature with the private key. The `sign_cb' will be called
623 * to deliver the signature data. If `compute_hash' is TRUE the `hash'
624 * will be used to compute a message digest over the `src'. The `hash'
625 * must always be valid. The signature operation may be asynchronous if
626 * the `private_key' is accelerated private key. If this returns NULL the
627 * asynchronous operation cannot be controlled.
630 SilcAsyncOperation silc_pkcs_sign(SilcPrivateKey private_key,
633 SilcBool compute_hash,
635 SilcPKCSSignCb sign_cb,
638 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_verify
642 * SilcAsyncOperation silc_pkcs_verify(SilcPublicKey public_key,
643 * unsigned char *signature,
644 * SilcUInt32 signature_len,
645 * unsigned char *data,
646 * SilcUInt32 data_len,
648 * SilcPKCSVerifyCb verify_cb,
653 * Verifies signature. The `verify_cb' will be called to deliver the
654 * result of the verification process. The 'signature' is verified against
655 * the 'data'. If the `hash' is non-NULL then the `data' will hashed
656 * before verification. If the `hash' is NULL, then the hash algorithm
657 * to be used is retrieved from the signature. If it isn't present in the
658 * signature the verification is done as is without hashing. If this
659 * returns NULL the asynchronous operation cannot be controlled.
662 SilcAsyncOperation silc_pkcs_verify(SilcPublicKey public_key,
663 unsigned char *signature,
664 SilcUInt32 signature_len,
668 SilcPKCSVerifyCb verify_cb,
671 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_load_public_key
675 * SilcBool silc_pkcs_load_public_key(const char *filename,
676 * SilcPublicKey *ret_public_key);
680 * Loads public key from file and allocates new public key. Returns TRUE
681 * if loading was successful.
684 SilcBool silc_pkcs_load_public_key(const char *filename,
685 SilcPublicKey *ret_public_key);
687 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_public_key
691 * SilcBool silc_pkcs_save_public_key(const char *filename,
692 * SilcPublicKey public_key,
693 * SilcPKCSFileEncoding encoding);
697 * Saves public key into file with specified encoding. Returns FALSE
701 SilcBool silc_pkcs_save_public_key(const char *filename,
702 SilcPublicKey public_key,
703 SilcPKCSFileEncoding encoding);
705 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_load_private_key
709 * SilcBool silc_pkcs_load_private_key(const char *filename,
710 * const unsigned char *passphrase,
711 * SilcUInt32 passphrase_len,
712 * SilcPrivateKey *ret_private_key);
716 * Loads private key from file and allocates new private key. Returns TRUE
717 * if loading was successful. The `passphrase' is used as decryption
718 * key of the private key file, in case it is encrypted.
721 SilcBool silc_pkcs_load_private_key(const char *filename,
722 const unsigned char *passphrase,
723 SilcUInt32 passphrase_len,
724 SilcPrivateKey *ret_private_key);
726 /****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_private_key
730 * SilcBool silc_pkcs_save_private_key(const char *filename,
731 * SilcPrivateKey private_key,
732 * const unsigned char *passphrase,
733 * SilcUInt32 passphrase_len,
734 * SilcPKCSFileEncoding encoding,
739 * Saves private key into file. The private key is encrypted into
740 * the file with the `passphrase' as a key, if PKCS supports encrypted
741 * private keys. Returns FALSE on error.
744 SilcBool silc_pkcs_save_private_key(const char *filename,
745 SilcPrivateKey private_key,
746 const unsigned char *passphrase,
747 SilcUInt32 passphrase_len,
748 SilcPKCSFileEncoding encoding,
751 /****f* silccrypt/SilcPKCSAPI/silc_hash_public_key
755 * SilcUInt32 silc_hash_public_key(void *key, void *user_context);
759 * An utility function for hashing public key for SilcHashTable. Give
760 * this as argument as the hash function for SilcHashTable.
763 SilcUInt32 silc_hash_public_key(void *key, void *user_context);
765 /****f* silccrypt/SilcPKCSAPI/silc_hash_public_key_compare
769 * SilcBool silc_hash_public_key_compare(void *key1, void *key2,
770 * void *user_context);
774 * An utility function for comparing public keys for SilcHashTable. Give
775 * this as argument as the compare function for SilcHashTable.
778 SilcBool silc_hash_public_key_compare(void *key1, void *key2,
781 #endif /* !SILCPKCS_H */