Added SILC Thread Queue API

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

diff --git a/lib/silcssh/silcssh.h b/lib/silcssh/silcssh.h
index 68848943f12ac9732ac858def84033d3b98586b0..6c52bc7a8ea28e95748220fa389548256810657a 100644 (file)
--- a/lib/silcssh/silcssh.h
+++ b/lib/silcssh/silcssh.h
@@ -41,51 +41,95 @@
  * SilcSshPrivateKey ssh_privkey;
  *
  * // Generate new SSH2 key pair, RSA algorithm, 2048 bits
- * silc_ssh_generate_key("rsa", 2048, rng, &public_key, &private_key);
+ * silc_ssh_generate_key("rsa", 2048, rng, "foo@example.com",
+ *                       &public_key, &private_key);
  *
  * // Add (optional) headers to the key before saving to a file
  * ssh_pubkey = silc_pkcs_public_key_get_pkcs(SILC_PKCS_SSH2, public_key);
  * silc_ssh_public_key_set_type(ssh_pubkey, SILC_SSH_KEY_SSH2);
- * silc_ssh_public_key_add_field(ssh_pubkey, "Subject", "foo@example.com");
  * silc_ssh_public_key_add_field(ssh_pubkey, "Comment", "My own key");
  *
  * // Rest of the operations use standard SILC PKCS API
  *
  * // 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, 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
+ *
+ * NAME
+ *
+ *    typedef enum { ... } SilcSshKeyType;
+ *
+ * DESCRIPTION
+ *
+ *    SSH2 public and private key types.  The default when new key pair
+ *    is created is SILC_SSH_KEY_OPENSSH.
+ *
+ * SOURCE
+ */
 typedef enum {
   SILC_SSH_KEY_OPENSSH   = 1,     /* OpenSSH public/private key (default) */
   SILC_SSH_KEY_SSH2      = 2,     /* SSH2 public key, RFC 4716 */
 } SilcSshKeyType;
 
+/****s* silcssh/SilcSshAPI/SilcSshPublicKey
+ *
+ * NAME
+ *
+ *    typedef struct { ... } *SilcSshPublicKey;
+ *
+ * DESCRIPTION
+ *
+ *    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.
+ *
+ * SOURCE
+ */
 typedef struct SilcSshPublicKeyStruct  {
   SilcHashTable fields;                   /* Public key headers */
   const SilcPKCSAlgorithm *pkcs;   /* PKCS Algorithm */
   void *public_key;               /* PKCS Algorithm specific public key */
   SilcSshKeyType type;            /* Public key type */
 } *SilcSshPublicKey;
+/***/
 
+/****s* silcssh/SilcSshAPI/SilcSshPrivateKey
+ *
+ * NAME
+ *
+ *    typedef struct { ... } *SilcSshPrivateKey;
+ *
+ * DESCRIPTION
+ *
+ *    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.
+ *
+ * SOURCE
+ */
 typedef struct SilcSshPrivateKeyStruct  {
   SilcHashTable fields;                   /* Private key headers */
   const SilcPKCSAlgorithm *pkcs;   /* PKCS Algorithm */
   void *private_key;              /* PKCS Algorithm specific private key */
   SilcSshKeyType type;            /* Private key type */
 } *SilcSshPrivateKey;
+/***/
 
 /****f* silcssh/SilcSshAPI/silc_ssh_generate_key
  *
@@ -93,17 +137,26 @@ typedef struct SilcSshPrivateKeyStruct  {
  *
  *    SilcBool silc_ssh_generate_key(const char *algorithm,
  *                                   int bits_len, SilcRng rng,
+ *                                   const char *subject,
  *                                   SilcPublicKey *ret_public_key,
  *                                   SilcPrivateKey *ret_private_key);
  *
  * DESCRIPTION
  *
  *    Generates new SSH2 key pair.  The `algorithm' is either rsa or dsa.
- *    The `bits_len' specify the key length in bits.  Returns FALSE on error.
+ *    The `bits_len' specify the key length in bits.  The `subject' is
+ *    usually the email address of the user creating the key or some other
+ *    similar subject name.  Returns FALSE on error.
+ *
+ * EXAMPLE
+ *
+ *    silc_ssh_generate_key("dsa", 1024, rng, "foo@example.com",
+ *                          &pubkey, &privkey);
  *
  ***/
 SilcBool silc_ssh_generate_key(const char *algorithm,
                               int bits_len, SilcRng rng,
+                              const char *subject,
                               SilcPublicKey *ret_public_key,
                               SilcPrivateKey *ret_private_key);
 
@@ -122,6 +175,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.
  *
@@ -142,6 +197,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.
@@ -159,7 +216,9 @@ 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);