ROBODoc documented. A patch by Ville Räsänen.

diff --git a/TODO b/TODO
index eb380fad03f905c5998678592a8a1dbaf249025a..fa25425bac8f94fd534e4e8c6a81fc589fc95627 100644 (file)
--- a/TODO
+++ b/TODO
@@ -38,6 +38,9 @@ TODO/bugs In SILC Libraries
    than on Unix.  Do it with threads on WIN32.  The function works but
    is not actually async currently (Fix this to 0.9.x).
 
+ o Private key encryption to silc_pkcs_[save/load]_private_key[_data]
+   function.
+
 
 TODO in Toolkit Documentation
 =============================
@@ -47,8 +50,6 @@ Manual (Do these to 0.9.x).
 
  o ROBOdoc documenting missing from lib/silccrypt/silccipher.h.
 
- o ROBOdoc documenting missing from lib/silccrypt/silcpkcs.h.
-
  o Write "Programming with Toolkit" document, describing how to build
    Toolkit, how the build system works, where is everything, how
    new (external) projects can be glued into Toolkit (use irssi as an

diff --git a/lib/silccrypt/silcpkcs.c b/lib/silccrypt/silcpkcs.c
index cbc8c762416cf51937fc2f590e35d0f38ec79799..f3282f92f23715484881ed7fecdf93b27296c322 100644 (file)
--- a/lib/silccrypt/silcpkcs.c
+++ b/lib/silccrypt/silcpkcs.c
@@ -223,7 +223,7 @@ void silc_pkcs_free(SilcPKCS pkcs)
 
 /* Return TRUE if PKCS algorithm `name' is supported. */
 
-int silc_pkcs_is_supported(const unsigned char *name)
+bool silc_pkcs_is_supported(const unsigned char *name)
 {
 #ifndef SILC_EPOC
   SilcPKCSObject *entry;
@@ -290,8 +290,8 @@ char *silc_pkcs_get_supported(void)
 
 /* Generate new key pair into the `pkcs' context. */
 
-int silc_pkcs_generate_key(SilcPKCS pkcs, SilcUInt32 bits_key_len,
-                          SilcRng rng)
+bool silc_pkcs_generate_key(SilcPKCS pkcs, SilcUInt32 bits_key_len,
+                           SilcRng rng)
 {
   return pkcs->pkcs->init(pkcs->context, bits_key_len, rng);
 }
@@ -366,33 +366,33 @@ SilcUInt32 silc_pkcs_private_key_data_set(SilcPKCS pkcs, unsigned char *prv,
 
 /* Encrypts */
 
-int silc_pkcs_encrypt(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
-                     unsigned char *dst, SilcUInt32 *dst_len)
+bool silc_pkcs_encrypt(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
+                      unsigned char *dst, SilcUInt32 *dst_len)
 {
   return pkcs->pkcs->encrypt(pkcs->context, src, src_len, dst, dst_len);
 }
 
 /* Decrypts */
 
-int silc_pkcs_decrypt(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
-                     unsigned char *dst, SilcUInt32 *dst_len)
+bool silc_pkcs_decrypt(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
+                      unsigned char *dst, SilcUInt32 *dst_len)
 {
   return pkcs->pkcs->decrypt(pkcs->context, src, src_len, dst, dst_len);
 }
 
 /* Generates signature */
 
-int silc_pkcs_sign(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
-                  unsigned char *dst, SilcUInt32 *dst_len)
+bool silc_pkcs_sign(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
+                   unsigned char *dst, SilcUInt32 *dst_len)
 {
   return pkcs->pkcs->sign(pkcs->context, src, src_len, dst, dst_len);
 }
 
 /* Verifies signature */
 
-int silc_pkcs_verify(SilcPKCS pkcs, unsigned char *signature, 
-                    SilcUInt32 signature_len, unsigned char *data, 
-                    SilcUInt32 data_len)
+bool silc_pkcs_verify(SilcPKCS pkcs, unsigned char *signature, 
+                     SilcUInt32 signature_len, unsigned char *data, 
+                     SilcUInt32 data_len)
 {
   return pkcs->pkcs->verify(pkcs->context, signature, signature_len, 
                            data, data_len);
@@ -400,9 +400,9 @@ int silc_pkcs_verify(SilcPKCS pkcs, unsigned char *signature,
 
 /* Generates signature with hash. The hash is signed. */
 
-int silc_pkcs_sign_with_hash(SilcPKCS pkcs, SilcHash hash,
-                            unsigned char *src, SilcUInt32 src_len,
-                            unsigned char *dst, SilcUInt32 *dst_len)
+bool silc_pkcs_sign_with_hash(SilcPKCS pkcs, SilcHash hash,
+                             unsigned char *src, SilcUInt32 src_len,
+                             unsigned char *dst, SilcUInt32 *dst_len)
 {
   unsigned char hashr[32];
   SilcUInt32 hash_len;
@@ -422,11 +422,11 @@ int silc_pkcs_sign_with_hash(SilcPKCS pkcs, SilcHash hash,
 /* Verifies signature with hash. The `data' is hashed and verified against
    the `signature'. */
 
-int silc_pkcs_verify_with_hash(SilcPKCS pkcs, SilcHash hash, 
-                              unsigned char *signature, 
-                              SilcUInt32 signature_len, 
-                              unsigned char *data, 
-                              SilcUInt32 data_len)
+bool silc_pkcs_verify_with_hash(SilcPKCS pkcs, SilcHash hash, 
+                               unsigned char *signature, 
+                               SilcUInt32 signature_len, 
+                               unsigned char *data, 
+                               SilcUInt32 data_len)
 {
   unsigned char hashr[32];
   SilcUInt32 hash_len;
@@ -744,8 +744,8 @@ silc_pkcs_public_key_data_encode(unsigned char *pk, SilcUInt32 pk_len,
 /* Decodes SILC style public key. Returns TRUE if the decoding was
    successful. Allocates new public key as well. */
 
-int silc_pkcs_public_key_decode(unsigned char *data, SilcUInt32 data_len,
-                               SilcPublicKey *public_key)
+bool silc_pkcs_public_key_decode(unsigned char *data, SilcUInt32 data_len,
+                                SilcPublicKey *public_key)
 {
   SilcBuffer buf;
   SilcPKCS alg;
@@ -938,11 +938,11 @@ silc_pkcs_private_key_data_encode(unsigned char *prv, SilcUInt32 prv_len,
   return ret;
 }
 
-/* Decodes SILC style public key. Returns TRUE if the decoding was
+/* Decodes SILC style private key. Returns TRUE if the decoding was
    successful. Allocates new private key as well. */
 
-int silc_pkcs_private_key_decode(unsigned char *data, SilcUInt32 data_len,
-                                SilcPrivateKey *private_key)
+bool silc_pkcs_private_key_decode(unsigned char *data, SilcUInt32 data_len,
+                                 SilcPrivateKey *private_key)
 {
   SilcBuffer buf;
   SilcPKCS alg;
@@ -1012,10 +1012,10 @@ int silc_pkcs_private_key_decode(unsigned char *data, SilcUInt32 data_len,
 
 /* Internal routine to save public key */
 
-static int silc_pkcs_save_public_key_internal(char *filename,
-                                             unsigned char *data,
-                                             SilcUInt32 data_len,
-                                             SilcUInt32 encoding)
+static bool silc_pkcs_save_public_key_internal(char *filename,
+                                              unsigned char *data,
+                                              SilcUInt32 data_len,
+                                              SilcUInt32 encoding)
 {
   SilcBuffer buf;
   SilcUInt32 len;
@@ -1052,8 +1052,8 @@ static int silc_pkcs_save_public_key_internal(char *filename,
 
 /* Saves public key into file */
 
-int silc_pkcs_save_public_key(char *filename, SilcPublicKey public_key,
-                             SilcUInt32 encoding)
+bool silc_pkcs_save_public_key(char *filename, SilcPublicKey public_key,
+                              SilcUInt32 encoding)
 {
   unsigned char *data;
   SilcUInt32 data_len;
@@ -1065,9 +1065,9 @@ int silc_pkcs_save_public_key(char *filename, SilcPublicKey public_key,
 
 /* Saves public key into file */
 
-int silc_pkcs_save_public_key_data(char *filename, unsigned char *data,
-                                  SilcUInt32 data_len,
-                                  SilcUInt32 encoding)
+bool silc_pkcs_save_public_key_data(char *filename, unsigned char *data,
+                                   SilcUInt32 data_len,
+                                   SilcUInt32 encoding)
 {
   return silc_pkcs_save_public_key_internal(filename, data, data_len,
                                            encoding);
@@ -1075,10 +1075,10 @@ int silc_pkcs_save_public_key_data(char *filename, unsigned char *data,
 
 /* Internal routine to save private key. */
 
-static int silc_pkcs_save_private_key_internal(char *filename,
-                                              unsigned char *data,
-                                              SilcUInt32 data_len,
-                                              SilcUInt32 encoding)
+static bool silc_pkcs_save_private_key_internal(char *filename,
+                                               unsigned char *data,
+                                               SilcUInt32 data_len,
+                                               SilcUInt32 encoding)
 {
   SilcBuffer buf;
   SilcUInt32 len;
@@ -1116,9 +1116,9 @@ static int silc_pkcs_save_private_key_internal(char *filename,
 /* Saves private key into file. */
 /* XXX The buffer should be encrypted if passphrase is provided. */
 
-int silc_pkcs_save_private_key(char *filename, SilcPrivateKey private_key, 
-                              unsigned char *passphrase,
-                              SilcUInt32 encoding)
+bool silc_pkcs_save_private_key(char *filename, SilcPrivateKey private_key, 
+                               unsigned char *passphrase,
+                               SilcUInt32 encoding)
 {
   unsigned char *data;
   SilcUInt32 data_len;
@@ -1131,20 +1131,20 @@ int silc_pkcs_save_private_key(char *filename, SilcPrivateKey private_key,
 /* Saves private key into file. */
 /* XXX The buffer should be encrypted if passphrase is provided. */
 
-int silc_pkcs_save_private_key_data(char *filename, unsigned char *data, 
-                                   SilcUInt32 data_len,
-                                   unsigned char *passphrase,
-                                   SilcUInt32 encoding)
+bool silc_pkcs_save_private_key_data(char *filename, unsigned char *data, 
+                                    SilcUInt32 data_len,
+                                    unsigned char *passphrase,
+                                    SilcUInt32 encoding)
 {
   return silc_pkcs_save_private_key_internal(filename, data, data_len,
                                             encoding);
 }
 
 /* Loads public key from file and allocates new public key. Returns TRUE
-   is loading was successful. */
+   if loading was successful. */
 
-int silc_pkcs_load_public_key(char *filename, SilcPublicKey *public_key,
-                             SilcUInt32 encoding)
+bool silc_pkcs_load_public_key(char *filename, SilcPublicKey *public_key,
+                              SilcUInt32 encoding)
 {
   unsigned char *cp, *old, *data, byte;
   SilcUInt32 i, data_len, len;
@@ -1200,8 +1200,8 @@ int silc_pkcs_load_public_key(char *filename, SilcPublicKey *public_key,
    if loading was successful. */
 /* XXX Should support encrypted private key files */
 
-int silc_pkcs_load_private_key(char *filename, SilcPrivateKey *private_key,
-                              SilcUInt32 encoding)
+bool silc_pkcs_load_private_key(char *filename, SilcPrivateKey *private_key,
+                               SilcUInt32 encoding)
 {
   unsigned char *cp, *old, *data, byte;
   SilcUInt32 i, data_len, len;

diff --git a/lib/silccrypt/silcpkcs.h b/lib/silccrypt/silcpkcs.h
index 13f0bde74e127cc9abc9a7d8c1df9865b7854075..43d602aafc6ec8b6913728106ba9d60df90dfe26 100644 (file)
--- a/lib/silccrypt/silcpkcs.h
+++ b/lib/silccrypt/silcpkcs.h
@@ -256,87 +256,673 @@ int silc_##pkcs##_verify(void *context, \
  ***/
 bool silc_pkcs_register(const SilcPKCSObject *pkcs);
 
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_unregister
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_unregister(SilcPKCSObject *pkcs);
+ *
+ * DESCRIPTION
+ *
+ *    Unregister a PKCS from the SILC. Returns FALSE on error.
+ *
+ ***/
 bool silc_pkcs_unregister(SilcPKCSObject *pkcs);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_register_default
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_register_default(void);
+ *
+ * DESCRIPTION
+ *
+ *    Registers all the default PKCS (all builtin PKCS).  The application may
+ *    use this to register the default PKCS if specific PKCS in any specific
+ *    order is not wanted. Returns FALSE on error.
+ *
+ ***/
 bool silc_pkcs_register_default(void);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_unregister_all
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_unregister_all(void);
+ *
+ * DESCRIPTION
+ *
+ *    Returns FALSE on error.
+ *
+ ***/
 bool silc_pkcs_unregister_all(void);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_alloc
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_alloc(const unsigned char *name, SilcPKCS *new_pkcs);
+ *
+ * DESCRIPTION
+ *
+ *    Allocates a new SilcPKCS object. The new allocated object is returned
+ *    to the 'new_pkcs' argument. Returns FALSE on error.
+ *
+ ***/
 bool silc_pkcs_alloc(const unsigned char *name, SilcPKCS *new_pkcs);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_free
+ *
+ * SYNOPSIS
+ *
+ *    void silc_pkcs_free(SilcPKCS pkcs);
+ *
+ * DESCRIPTION
+ *
+ *    Frees the PKCS object.
+ *
+ ***/
 void silc_pkcs_free(SilcPKCS pkcs);
-int silc_pkcs_is_supported(const unsigned char *name);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_is_supported
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_is_supported(const unsigned char *name);
+ *
+ * DESCRIPTION
+ *
+ *    Returns TRUE if PKCS algorithm `name' is supported.
+ *
+ ***/
+bool silc_pkcs_is_supported(const unsigned char *name);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_supported
+ *
+ * SYNOPSIS
+ *
+ *    char *silc_pkcs_get_supported(void);
+ *
+ * DESCRIPTION
+ *
+ *    Returns comma separated list of supported PKCS algorithms.
+ *
+ ***/
 char *silc_pkcs_get_supported(void);
-int silc_pkcs_generate_key(SilcPKCS pkcs, SilcUInt32 bits_key_len,
-                          SilcRng rng);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_generate_key
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_generate_key(SilcPKCS pkcs, SilcUInt32 bits_key_len,
+ *                               SilcRng rng);
+ *
+ * DESCRIPTION
+ *
+ *    Generate new key pair into the `pkcs' context. Returns FALSE on error.
+ *
+ ***/
+bool silc_pkcs_generate_key(SilcPKCS pkcs, SilcUInt32 bits_key_len,
+                           SilcRng rng);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_key_len
+ *
+ * SYNOPSIS
+ *
+ *    SilcUInt32 silc_pkcs_get_key_len(SilcPKCS self);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the length of the key.
+ *
+ ***/
 SilcUInt32 silc_pkcs_get_key_len(SilcPKCS self);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_name
+ *
+ * SYNOPSIS
+ *
+ *    const char *silc_pkcs_get_name(SilcPKCS pkcs);
+ *
+ * DESCRIPTION
+ *
+ *    Returns PKCS name.
+ *
+ ***/
 const char *silc_pkcs_get_name(SilcPKCS pkcs);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_public_key
+ *
+ * SYNOPSIS
+ *
+ *    unsigned char *silc_pkcs_get_public_key(SilcPKCS pkcs, SilcUInt32 *len);
+ *
+ * DESCRIPTION
+ *
+ *    Returns SILC style public key.
+ *
+ ***/
 unsigned char *silc_pkcs_get_public_key(SilcPKCS pkcs, SilcUInt32 *len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_get_private_key
+ *
+ * SYNOPSIS
+ *
+ *    unsigned char *silc_pkcs_get_private_key(SilcPKCS pkcs,
+ *                                            SilcUInt32 *len);
+ *
+ * DESCRIPTION
+ *
+ *    Returns SILC style private key.
+ *
+ ***/
 unsigned char *silc_pkcs_get_private_key(SilcPKCS pkcs, SilcUInt32 *len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_set
+ *
+ * SYNOPSIS
+ *
+ *    SilcUInt32 silc_pkcs_public_key_set(SilcPKCS pkcs,
+ *                                       SilcPublicKey public_key);
+ *
+ * DESCRIPTION
+ *
+ *    Sets public key from SilcPublicKey. Returns the length of the key.
+ *
+ ***/
 SilcUInt32 silc_pkcs_public_key_set(SilcPKCS pkcs, SilcPublicKey public_key);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_data_set
+ *
+ * SYNOPSIS
+ *
+ *    SilcUInt32 silc_pkcs_public_key_data_set(SilcPKCS pkcs,
+ *                                             unsigned char *pk,
+ *                                            SilcUInt32 pk_len);
+ *
+ * DESCRIPTION
+ *
+ *    Sets public key from data. Returns the length of the key.
+ *
+ ***/
 SilcUInt32 silc_pkcs_public_key_data_set(SilcPKCS pkcs, unsigned char *pk,
                                         SilcUInt32 pk_len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_set
+ *
+ * SYNOPSIS
+ *
+ *    SilcUInt32 silc_pkcs_private_key_set(SilcPKCS pkcs,
+ *                                        SilcPrivateKey private_key);
+ *
+ * DESCRIPTION
+ *
+ *    Sets private key from SilcPrivateKey. Returns the length of the key.
+ *
+ ***/
 SilcUInt32 silc_pkcs_private_key_set(SilcPKCS pkcs, SilcPrivateKey private_key);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_data_set
+ *
+ * SYNOPSIS
+ *
+ *    SilcUInt32 silc_pkcs_private_key_data_set(SilcPKCS pkcs,
+ *                                             unsigned char *prv,
+ *                                             SilcUInt32 prv_len);
+ *
+ * DESCRIPTION
+ *
+ *    Sets private key from data. Returns the length of the key.
+ *
+ ***/
 SilcUInt32 silc_pkcs_private_key_data_set(SilcPKCS pkcs, unsigned char *prv,
                                          SilcUInt32 prv_len);
-int silc_pkcs_encrypt(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
-                     unsigned char *dst, SilcUInt32 *dst_len);
-int silc_pkcs_decrypt(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
-                     unsigned char *dst, SilcUInt32 *dst_len);
-int silc_pkcs_sign(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
-                  unsigned char *dst, SilcUInt32 *dst_len);
-int silc_pkcs_verify(SilcPKCS pkcs, unsigned char *signature, 
-                    SilcUInt32 signature_len, unsigned char *data, 
-                    SilcUInt32 data_len);
-int silc_pkcs_sign_with_hash(SilcPKCS pkcs, SilcHash hash,
-                            unsigned char *src, SilcUInt32 src_len,
-                            unsigned char *dst, SilcUInt32 *dst_len);
-int silc_pkcs_verify_with_hash(SilcPKCS pkcs, SilcHash hash, 
-                              unsigned char *signature, 
-                              SilcUInt32 signature_len, 
-                              unsigned char *data, 
-                              SilcUInt32 data_len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_encrypt
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_encrypt(SilcPKCS pkcs, unsigned char *src,
+ *                          SilcUInt32 src_len, unsigned char *dst,
+ *                          SilcUInt32 *dst_len);
+ *
+ * DESCRIPTION
+ *
+ *    Encrypts. Returns FALSE on error.
+ *
+ ***/
+bool silc_pkcs_encrypt(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
+                      unsigned char *dst, SilcUInt32 *dst_len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_decrypt
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_decrypt(SilcPKCS pkcs, unsigned char *src,
+ *                          SilcUInt32 src_len, unsigned char *dst,
+ *                          SilcUInt32 *dst_len);
+ *
+ * DESCRIPTION
+ *
+ *    Decrypts. Returns FALSE on error.
+ *
+ ***/
+bool silc_pkcs_decrypt(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
+                      unsigned char *dst, SilcUInt32 *dst_len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_sign
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_sign(SilcPKCS pkcs, unsigned char *src,
+ *                       SilcUInt32 src_len, unsigned char *dst,
+ *                       SilcUInt32 *dst_len);
+ *
+ * DESCRIPTION
+ *
+ *    Generates signature. Returns FALSE on error.
+ *
+ ***/
+bool silc_pkcs_sign(SilcPKCS pkcs, unsigned char *src, SilcUInt32 src_len,
+                   unsigned char *dst, SilcUInt32 *dst_len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_verify
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_verify(SilcPKCS pkcs, unsigned char *signature,
+ *                         SilcUInt32 signature_len, unsigned char *data,
+ *                         SilcUInt32 data_len);
+ *
+ * DESCRIPTION
+ *
+ *    Verifies signature. Returns FALSE on error.
+ *
+ ***/
+bool silc_pkcs_verify(SilcPKCS pkcs, unsigned char *signature,
+                     SilcUInt32 signature_len, unsigned char *data,
+                     SilcUInt32 data_len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_sign_with_hash
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_sign_with_hash(SilcPKCS pkcs, SilcHash hash,
+ *                                 unsigned char *src, SilcUInt32 src_len,
+ *                                 unsigned char *dst, SilcUInt32 *dst_len);
+ *
+ * DESCRIPTION
+ *
+ *    Generates signature with hash. The hash is signed. Returns FALSE on
+ *    error.
+ *
+ ***/
+bool silc_pkcs_sign_with_hash(SilcPKCS pkcs, SilcHash hash,
+                             unsigned char *src, SilcUInt32 src_len,
+                             unsigned char *dst, SilcUInt32 *dst_len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_verify_with_hash
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_verify_with_hash(SilcPKCS pkcs, SilcHash hash,
+ *                                   unsigned char *signature,
+ *                                   SilcUInt32 signature_len,
+ *                                   unsigned char *data,
+ *                                   SilcUInt32 data_len);
+ *
+ * DESCRIPTION
+ *
+ *    Verifies signature with hash. The `data' is hashed and verified against
+ *    the `signature'. Returns FALSE on error.
+ *
+ ***/
+bool silc_pkcs_verify_with_hash(SilcPKCS pkcs, SilcHash hash,
+                               unsigned char *signature,
+                               SilcUInt32 signature_len,
+                               unsigned char *data,
+                               SilcUInt32 data_len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_encode_identifier
+ *
+ * SYNOPSIS
+ *
+ *    char *silc_pkcs_encode_identifier(char *username, char *host,
+ *                                     char *realname, char *email,
+ *                                     char *org, char *country);
+ *
+ * DESCRIPTION
+ *
+ *    Encodes and returns SILC public key identifier. If some of the
+ *    arguments is NULL those are not encoded into the identifier string.
+ *    Protocol says that at least username and host must be provided.
+ *
+ ***/
 char *silc_pkcs_encode_identifier(char *username, char *host, char *realname,
                                  char *email, char *org, char *country);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_decode_identifier
+ *
+ * SYNOPSIS
+ *
+ *    SilcPublicKeyIdentifier silc_pkcs_decode_identifier(char *identifier);
+ *
+ * DESCRIPTION
+ *
+ *    Decodes the provided `identifier' and returns allocated context for
+ *    the identifier.
+ *
+ ***/
 SilcPublicKeyIdentifier silc_pkcs_decode_identifier(char *identifier);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_free_identifier
+ *
+ * SYNOPSIS
+ *
+ *    void silc_pkcs_free_identifier(SilcPublicKeyIdentifier identifier);
+ *
+ * DESCRIPTION
+ *
+ *    Frees decoded public key identifier context. Call this to free the
+ *    context returned by the silc_pkcs_decode_identifier.
+ *
+ ***/
 void silc_pkcs_free_identifier(SilcPublicKeyIdentifier identifier);
-SilcPublicKey silc_pkcs_public_key_alloc(const char *name, 
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_alloc
+ *
+ * SYNOPSIS
+ *
+ *    SilcPublicKey silc_pkcs_public_key_alloc(const char *name,
+ *                                            const char *identifier,
+ *                                            const unsigned char *pk,
+ *                                            SilcUInt32 pk_len);
+ *
+ * DESCRIPTION
+ *
+ *    Allocates SILC style public key formed from sent arguments. All data
+ *    is duplicated.
+ *
+ ***/
+SilcPublicKey silc_pkcs_public_key_alloc(const char *name,
                                         const char *identifier,
-                                        const unsigned char *pk, 
+                                        const unsigned char *pk,
                                         SilcUInt32 pk_len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_free
+ *
+ * SYNOPSIS
+ *
+ *    void silc_pkcs_public_key_free(SilcPublicKey public_key);
+ *
+ * DESCRIPTION
+ *
+ *    Frees public key.
+ *
+ ***/
 void silc_pkcs_public_key_free(SilcPublicKey public_key);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_alloc
+ *
+ * SYNOPSIS
+ *
+ *    SilcPrivateKey silc_pkcs_private_key_alloc(const char *name,
+ *                                              const unsigned char *prv,
+ *                                              SilcUInt32 prv_len);
+ *
+ * DESCRIPTION
+ *
+ *    Allocates SILC private key formed from sent arguments. All data is
+ *    duplicated.
+ *
+ ***/
 SilcPrivateKey silc_pkcs_private_key_alloc(const char *name,
                                           const unsigned char *prv,
                                           SilcUInt32 prv_len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_free
+ *
+ * SYNOPSIS
+ *
+ *    void silc_pkcs_private_key_free(SilcPrivateKey private_key);
+ *
+ * DESCRIPTION
+ *
+ *    Frees private key.
+ *
+ ***/
 void silc_pkcs_private_key_free(SilcPrivateKey private_key);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_encode
+ *
+ * SYNOPSIS
+ *
+ *    unsigned char *
+ *    silc_pkcs_public_key_encode(SilcPublicKey public_key, SilcUInt32 *len);
+ *
+ * DESCRIPTION
+ *
+ *    Encodes SILC style public key from SilcPublicKey. Returns the encoded
+ *    data.
+ *
+ ***/
 unsigned char *
 silc_pkcs_public_key_encode(SilcPublicKey public_key, SilcUInt32 *len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_data_encode
+ *
+ * SYNOPSIS
+ *
+ *    unsigned char *
+ *    silc_pkcs_public_key_data_encode(unsigned char *pk, SilcUInt32 pk_len,
+ *                                    char *pkcs, char *identifier,
+ *                                    SilcUInt32 *len);
+ *
+ * DESCRIPTION
+ *
+ *    Encodes SILC style public key. Returns the encoded data.
+ *
+ ***/
 unsigned char *
 silc_pkcs_public_key_data_encode(unsigned char *pk, SilcUInt32 pk_len,
-                                char *pkcs, char *identifier, 
+                                char *pkcs, char *identifier,
                                 SilcUInt32 *len);
-int silc_pkcs_public_key_decode(unsigned char *data, SilcUInt32 data_len,
-                               SilcPublicKey *public_key);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_decode
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_public_key_decode(unsigned char *data, SilcUInt32 data_len,
+ *                                    SilcPublicKey *public_key);
+ *
+ * DESCRIPTION
+ *
+ *    Decodes SILC style public key. Returns TRUE if the decoding was
+ *    successful. Allocates new public key as well.
+ *
+ ***/
+bool silc_pkcs_public_key_decode(unsigned char *data, SilcUInt32 data_len,
+                                SilcPublicKey *public_key);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_compare
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_public_key_compare(SilcPublicKey key1,
+ *                                     SilcPublicKey key2);
+ *
+ * DESCRIPTION
+ *
+ *    Compares two public keys and returns TRUE if they are same key, and
+ *    FALSE if they are not same.
+ *
+ ***/
 bool silc_pkcs_public_key_compare(SilcPublicKey key1, SilcPublicKey key2);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_public_key_copy
+ *
+ * SYNOPSIS
+ *
+ *    SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
+ *
+ * DESCRIPTION
+ *
+ *    Copies the public key indicated by `public_key' and returns new allocated
+ *    public key which is indentical to the `public_key'.
+ *
+ ***/
 SilcPublicKey silc_pkcs_public_key_copy(SilcPublicKey public_key);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_encode
+ *
+ * SYNOPSIS
+ *
+ *    unsigned char *
+ *    silc_pkcs_private_key_encode(SilcPrivateKey private_key,
+ *                                SilcUInt32 *len);
+ *
+ * DESCRIPTION
+ *
+ *    Encodes SILC private key from SilcPrivateKey. Returns the encoded data.
+ *
+ ***/
 unsigned char *
 silc_pkcs_private_key_encode(SilcPrivateKey private_key, SilcUInt32 *len);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_data_encode
+ *
+ * SYNOPSIS
+ *
+ *    unsigned char *
+ *    silc_pkcs_private_key_data_encode(unsigned char *prv, SilcUInt32 prv_len,
+ *                                     char *pkcs, SilcUInt32 *len);
+ *
+ * DESCRIPTION
+ *
+ *    Encodes SILC private key. Returns the encoded data.
+ *
+ ***/
 unsigned char *
 silc_pkcs_private_key_data_encode(unsigned char *prv, SilcUInt32 prv_len,
                                  char *pkcs, SilcUInt32 *len);
-int silc_pkcs_private_key_decode(unsigned char *data, SilcUInt32 data_len,
-                                SilcPrivateKey *private_key);
-int silc_pkcs_save_public_key(char *filename, SilcPublicKey public_key,
-                             SilcUInt32 encoding);
-int silc_pkcs_save_public_key_data(char *filename, unsigned char *data,
-                                  SilcUInt32 data_len,
-                                  SilcUInt32 encoding);
-int silc_pkcs_save_private_key(char *filename, SilcPrivateKey private_key, 
-                              unsigned char *passphrase,
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_private_key_decode
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_private_key_decode(unsigned char *data,
+ *                                     SilcUInt32 data_len,
+ *                                     SilcPrivateKey *private_key);
+ *
+ * DESCRIPTION
+ *
+ *    Decodes SILC style private key. Returns TRUE if the decoding was
+ *    successful. Allocates new private key as well.
+ *
+ ***/
+bool silc_pkcs_private_key_decode(unsigned char *data, SilcUInt32 data_len,
+                                 SilcPrivateKey *private_key);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_public_key
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_save_public_key(char *filename, SilcPublicKey public_key,
+ *                                  SilcUInt32 encoding);
+ *
+ * DESCRIPTION
+ *
+ *    Saves public key into file. Returns FALSE on error.
+ *
+ ***/
+bool silc_pkcs_save_public_key(char *filename, SilcPublicKey public_key,
                               SilcUInt32 encoding);
-int silc_pkcs_save_private_key_data(char *filename, unsigned char *data, 
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_public_key_data
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_save_public_key_data(char *filename, unsigned char *data,
+ *                                       SilcUInt32 data_len,
+ *                                       SilcUInt32 encoding);
+ *
+ * DESCRIPTION
+ *
+ *    Saves public key into file. Returns FALSE on error.
+ *
+ ***/
+bool silc_pkcs_save_public_key_data(char *filename, unsigned char *data,
                                    SilcUInt32 data_len,
-                                   unsigned char *passphrase,
                                    SilcUInt32 encoding);
-int silc_pkcs_load_public_key(char *filename, SilcPublicKey *public_key,
-                             SilcUInt32 encoding);
-int silc_pkcs_load_private_key(char *filename, SilcPrivateKey *private_key,
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_private_key
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_save_private_key(char *filename,
+ *                                   SilcPrivateKey private_key,
+ *                                   unsigned char *passphrase,
+ *                                   SilcUInt32 encoding);
+ *
+ * DESCRIPTION
+ *
+ *    Saves private key into file. Returns FALSE on error.
+ *
+ ***/
+bool silc_pkcs_save_private_key(char *filename, SilcPrivateKey private_key, 
+                               unsigned char *passphrase,
+                               SilcUInt32 encoding);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_save_private_key_data
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_save_private_key_data(char *filename, unsigned char *data,
+ *                                        SilcUInt32 data_len,
+ *                                        unsigned char *passphrase,
+ *                                        SilcUInt32 encoding);
+ *
+ * DESCRIPTION
+ *
+ *    Saves private key into file. Returns FALSE on error.
+ *
+ ***/
+bool silc_pkcs_save_private_key_data(char *filename, unsigned char *data, 
+                                    SilcUInt32 data_len,
+                                    unsigned char *passphrase,
+                                    SilcUInt32 encoding);
+
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_load_public_key
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_load_public_key(char *filename, SilcPublicKey *public_key,
+ *                                  SilcUInt32 encoding);
+ *
+ * DESCRIPTION
+ *
+ *    Loads public key from file and allocates new public key. Returns TRUE
+ *    if loading was successful.
+ *
+ ***/
+bool silc_pkcs_load_public_key(char *filename, SilcPublicKey *public_key,
                               SilcUInt32 encoding);
 
+/****f* silccrypt/SilcPKCSAPI/silc_pkcs_load_private_key
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_pkcs_load_private_key(char *filename,
+ *                                   SilcPrivateKey *private_key,
+ *                                   SilcUInt32 encoding);
+ *
+ * DESCRIPTION
+ *
+ *    Load private key from file and allocates new private key. Returns TRUE
+ *    if loading was successful.
+ *
+ ***/
+bool silc_pkcs_load_private_key(char *filename, SilcPrivateKey *private_key,
+                               SilcUInt32 encoding);
+
 #endif /* SILCPKCS_H */