Added comments, added subject param to silc_ssh_generate_key.

diff --git a/lib/silcssh/silcssh.c b/lib/silcssh/silcssh.c
index 0e4f606b05e04a17457701e840a6d2f2a5911c45..818a0fa2893e96302114f3b50ae8bb1d2d9bd10d 100644 (file)
--- a/lib/silcssh/silcssh.c
+++ b/lib/silcssh/silcssh.c
@@ -174,6 +174,7 @@ SilcHashTable silc_ssh_parse_headers(SilcBuffer key)
 
 SilcBool silc_ssh_generate_key(const char *algorithm,
                               int bits_len, SilcRng rng,
+                              const char *subject,
                               SilcPublicKey *ret_public_key,
                               SilcPrivateKey *ret_private_key)
 {
@@ -249,6 +250,9 @@ SilcBool silc_ssh_generate_key(const char *algorithm,
     return FALSE;
   }
 
+  if (subject)
+    silc_ssh_public_key_add_field(pubkey, "Subject", strdup(subject));
+
   return TRUE;
 }
 

diff --git a/lib/silcssh/silcssh.h b/lib/silcssh/silcssh.h
index 68848943f12ac9732ac858def84033d3b98586b0..9f4e8b89a66aa28b3924b87a6d05acf44b504f7a 100644 (file)
--- a/lib/silcssh/silcssh.h
+++ b/lib/silcssh/silcssh.h
@@ -41,12 +41,12 @@
  * 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
@@ -62,30 +62,73 @@
  *                            SILC_PKCS_SSH2, &public_key);
  *
  * // Compute signature
- * silc_pkcs_sign(private_key, src, src_len, TRUE, sha1, sign_cb, ctx);
+ * silc_pkcs_sign(private_key, src, src_len, TRUE, sha1, rng, sign_cb, ctx);
  *
  ***/
 #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 ke 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 type.
+ *
+ * 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 type.
+ *
+ * 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 +136,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);
 

diff --git a/lib/silcssh/tests/test_silcssh.c b/lib/silcssh/tests/test_silcssh.c
index 7962dc175f9a10c922c6d79129f32e75de4623f2..7362c3df843a815830553b4d9a876fc65c981d66 100644 (file)
--- a/lib/silcssh/tests/test_silcssh.c
+++ b/lib/silcssh/tests/test_silcssh.c
@@ -22,22 +22,22 @@ int main(int argc, char **argv)
   silc_rng_init(rng);
 
   SILC_LOG_DEBUG(("Generate key pair"));
-  silc_ssh_generate_key("dsa", 1024, rng, &public_key, &private_key);
+  silc_ssh_generate_key("dsa", 1024, rng, "foo@example.com",
+                       &public_key, &private_key);
 
   SILC_LOG_DEBUG(("Set SSH2 public key headers"));
   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");
 
   SILC_LOG_DEBUG(("Save public and private key"));
-  if (!silc_pkcs_save_public_key("pubkey.pub", public_key, 
+  if (!silc_pkcs_save_public_key("pubkey.pub", public_key,
                                 SILC_PKCS_FILE_BASE64))
     goto err;
   if (!silc_pkcs_save_private_key("privkey.prv", private_key, "testi", 5,
                                          SILC_PKCS_FILE_BASE64, rng))
     goto err;
- 
+
   SILC_LOG_DEBUG(("Load public key"));
   if (!silc_pkcs_load_public_key("pubkey.pub", SILC_PKCS_ANY,  &public_key))
     goto err;
@@ -55,12 +55,12 @@ int main(int argc, char **argv)
   SILC_LOG_DEBUG(("Save as OpenSSH public key"));
   ssh_pubkey = silc_pkcs_public_key_get_pkcs(SILC_PKCS_SSH2, public_key);
   silc_ssh_public_key_set_type(ssh_pubkey, SILC_SSH_KEY_OPENSSH);
-  if (!silc_pkcs_save_public_key("pubkey_openssh.pub", public_key, 
+  if (!silc_pkcs_save_public_key("pubkey_openssh.pub", public_key,
                                 SILC_PKCS_FILE_BASE64))
     goto err;
 
   SILC_LOG_DEBUG(("Load public key"));
-  if (!silc_pkcs_load_public_key("pubkey_openssh.pub", SILC_PKCS_SSH2, 
+  if (!silc_pkcs_load_public_key("pubkey_openssh.pub", SILC_PKCS_SSH2,
                                 &public_key))
     goto err;