Header documentation changes and other small fixes

[crypto.git] / lib / silcssh / silcssh.h

diff --git a/lib/silcssh/silcssh.h b/lib/silcssh/silcssh.h
index 9f4e8b89a66aa28b3924b87a6d05acf44b504f7a..f07b7cb11b0aaa45543289e342a2fd997db7425e 100644 (file)
--- a/lib/silcssh/silcssh.h
+++ b/lib/silcssh/silcssh.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2007 Pekka Riikonen
+  Copyright (C) 2007 - 2008 Pekka Riikonen
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -31,7 +31,8 @@
  * signatures and verification.  Both RSA and DSS SSH2 keys are supported.
  * The library supports the standard SSH2 public key file format defined
  * in RFC 4716 and the OpenSSH public key file format.  The private key file
- * format support includes OpenSSH private key files.
+ * format support includes OpenSSH private key files.  The signature format
+ * is compliant with the SSH2 protocol.
  *
  * EXAMPLE
  *
@@ -53,22 +54,23 @@
  *
  * // Save new key pair to file
  * silc_pkcs_save_public_key("pubkey.pub", public_key, SILC_PKCS_FILE_BASE64);
- * silc_pkcs_save_private_key("privkey.pub", private_key, passphrase,
+ * silc_pkcs_save_private_key("privkey.prv", private_key, passphrase,
  *                            passphrase_len, SILC_PKCS_FILE_BASE64, rng);
  *
  * // Load SSH2 key pair
  * silc_pkcs_load_public_key("pubkey.pub", SILC_PKCS_SSH2, &public_key);
- * silc_pkcs_load_private_key("privkey.pub", passphrase, passphrase_len,
+ * silc_pkcs_load_private_key("privkey.prv", passphrase, passphrase_len,
  *                            SILC_PKCS_SSH2, &public_key);
  *
- * // Compute signature
- * silc_pkcs_sign(private_key, src, src_len, TRUE, sha1, rng, sign_cb, ctx);
+ * // Free public and private key. Frees automatically the underlaying SSH keys.
+ * silc_pkcs_public_key_free(public_key);
+ * silc_pkcs_private_key_free(private_key);
  *
  ***/
 #ifndef SILCSSH_H
 #define SILCSSH_H
 
-/****d* silcssh/SilcSshAPI/SilcSshKeyType
+/****d* silcssh/SilcSshKeyType
  *
  * NAME
  *
@@ -76,7 +78,7 @@
  *
  * DESCRIPTION
  *
- *    SSH2 public and private key types.  The default when new ke pair
+ *    SSH2 public and private key types.  The default when new key pair
  *    is created is SILC_SSH_KEY_OPENSSH.
  *
  * SOURCE
@@ -86,7 +88,7 @@ typedef enum {
   SILC_SSH_KEY_SSH2      = 2,     /* SSH2 public key, RFC 4716 */
 } SilcSshKeyType;
 
-/****s* silcssh/SilcSshAPI/SilcSshPublicKey
+/****s* silcssh/SilcSshPublicKey
  *
  * NAME
  *
@@ -96,7 +98,7 @@ typedef enum {
  *
  *    This structure defines the SSH2 public key.  This context can be
  *    retrieved from SilcPublicKey by calling silc_pkcs_public_key_get_pkcs
- *    for the PKCS type SILC_PKCS_SSH2 type.
+ *    for the PKCS type SILC_PKCS_SSH2.
  *
  * SOURCE
  */
@@ -108,7 +110,7 @@ typedef struct SilcSshPublicKeyStruct  {
 } *SilcSshPublicKey;
 /***/
 
-/****s* silcssh/SilcSshAPI/SilcSshPrivateKey
+/****s* silcssh/SilcSshPrivateKey
  *
  * NAME
  *
@@ -118,7 +120,7 @@ typedef struct SilcSshPublicKeyStruct  {
  *
  *    This structure defines the SSH2 private key.  This context can be
  *    retrieved from SilcPrivateKey by calling silc_pkcs_private_key_get_pkcs
- *    for the PKCS type SILC_PKCS_SSH2 type.
+ *    for the PKCS type SILC_PKCS_SSH2.
  *
  * SOURCE
  */
@@ -130,7 +132,7 @@ typedef struct SilcSshPrivateKeyStruct  {
 } *SilcSshPrivateKey;
 /***/
 
-/****f* silcssh/SilcSshAPI/silc_ssh_generate_key
+/****f* silcssh/silc_ssh_generate_key
  *
  * SYNOPSIS
  *
@@ -159,7 +161,7 @@ SilcBool silc_ssh_generate_key(const char *algorithm,
                               SilcPublicKey *ret_public_key,
                               SilcPrivateKey *ret_private_key);
 
-/****f* silcssh/SilcSshAPI/silc_ssh_public_key_decode
+/****f* silcssh/silc_ssh_public_key_decode
  *
  * SYNOPSIS
  *
@@ -174,6 +176,8 @@ SilcBool silc_ssh_generate_key(const char *algorithm,
  *    function.  This function expects the public key to be in raw binary
  *    format, without any public key file markers or headers.
  *
+ *    This decodes SSH2 protocol compliant raw public key.
+ *
  *    This function returns the number of bytes decoded from the public
  *    key buffer or 0 on error.
  *
@@ -181,7 +185,7 @@ SilcBool silc_ssh_generate_key(const char *algorithm,
 int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
                               SilcSshPublicKey *ret_public_key);
 
-/****f* silcssh/SilcSshAPI/silc_ssh_public_key_encode
+/****f* silcssh/silc_ssh_public_key_encode
  *
  * SYNOPSIS
  *
@@ -194,6 +198,8 @@ int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
  *    Encodes SSH Public key and returns the encoded buffer.  Caller must
  *    free the returned buffer.
  *
+ *    This encodes SSH2 protocol compliant raw public key.
+ *
  *    If the `stack' is non-NULL the returned buffer is allocated from the
  *    `stack'.  This call will consume `stack' so caller should push the stack
  *    before calling and then later pop it.
@@ -203,7 +209,7 @@ unsigned char *silc_ssh_public_key_encode(SilcStack stack,
                                          SilcSshPublicKey public_key,
                                          SilcUInt32 *ret_key_len);
 
-/****f* silcssh/SilcSshAPI/silc_ssh_public_key_free
+/****f* silcssh/silc_ssh_public_key_free
  *
  * SYNOPSIS
  *
@@ -211,12 +217,14 @@ unsigned char *silc_ssh_public_key_encode(SilcStack stack,
  *
  * DESCRIPTION
  *
- *    Frees the public key.
+ *    Frees the public key.  This need to be called only if you called
+ *    silc_ssh_public_key_decode.  SSH public keys allocated through the
+ *    SILC PKCS API can be freed by calling silc_pkcs_public_key_free.
  *
  ***/
 void silc_ssh_public_key_free(SilcSshPublicKey public_key);
 
-/****f* silcssh/SilcSshAPI/silc_ssh_public_key_get_field
+/****f* silcssh/silc_ssh_public_key_get_field
  *
  * SYNOPSIS
  *
@@ -237,7 +245,7 @@ void silc_ssh_public_key_free(SilcSshPublicKey public_key);
 const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
                                          const char *field);
 
-/****f* silcssh/SilcSshAPI/silc_ssh_public_key_add_field
+/****f* silcssh/silc_ssh_public_key_add_field
  *
  * SYNOPSIS
  *
@@ -255,7 +263,7 @@ SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
                                       const char *field,
                                       const char *value);
 
-/****f* silcssh/SilcSshAPI/silc_ssh_public_key_set_type
+/****f* silcssh/silc_ssh_public_key_set_type
  *
  * SYNOPSIS
  *