lib/silcssh/silcssh.h

   1 /*
   2
   3   silcssh.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2007 Pekka Riikonen
   8
   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.
  12
  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.
  17
  18 */
  19
  20 /****h* silcssh/SILC SSH Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * SILC SSH Library provides SSH2 public key and private key support for
  25  * applications.  The SILC SSH Library has been integrated to the SILC Crypto
  26  * Toolkit allowing easy use of the SSH keys through the SILC PKCS API.  The
  27  * interface provides also a low level API to directly manipulate the SSH
  28  * keys.
  29  *
  30  * The library supports creation of new SSH2 key pairs, encryption, decryption,
  31  * signatures and verification.  Both RSA and DSS SSH2 keys are supported.
  32  * The library supports the standard SSH2 public key file format defined
  33  * in RFC 4716 and the OpenSSH public key file format.  The private key file
  34  * format support includes OpenSSH private key files.
  35  *
  36  * EXAMPLE
  37  *
  38  * SilcPublicKey public_key;
  39  * SilcPrivateKey private_key;
  40  * SilcSshPublicKey ssh_pubkey;
  41  * SilcSshPrivateKey ssh_privkey;
  42  *
  43  * // Generate new SSH2 key pair, RSA algorithm, 2048 bits
  44  * silc_ssh_generate_key("rsa", 2048, rng, "foo@example.com",
  45  *                       &public_key, &private_key);
  46  *
  47  * // Add (optional) headers to the key before saving to a file
  48  * ssh_pubkey = silc_pkcs_public_key_get_pkcs(SILC_PKCS_SSH2, public_key);
  49  * silc_ssh_public_key_set_type(ssh_pubkey, SILC_SSH_KEY_SSH2);
  50  * silc_ssh_public_key_add_field(ssh_pubkey, "Comment", "My own key");
  51  *
  52  * // Rest of the operations use standard SILC PKCS API
  53  *
  54  * // Save new key pair to file
  55  * silc_pkcs_save_public_key("pubkey.pub", public_key, SILC_PKCS_FILE_BASE64);
  56  * silc_pkcs_save_private_key("privkey.pub", private_key, passphrase,
  57  *                            passphrase_len, SILC_PKCS_FILE_BASE64, rng);
  58  *
  59  * // Load SSH2 key pair
  60  * silc_pkcs_load_public_key("pubkey.pub", SILC_PKCS_SSH2, &public_key);
  61  * silc_pkcs_load_private_key("privkey.pub", passphrase, passphrase_len,
  62  *                            SILC_PKCS_SSH2, &public_key);
  63  *
  64  * // Compute signature
  65  * silc_pkcs_sign(private_key, src, src_len, TRUE, sha1, rng, sign_cb, ctx);
  66  *
  67  ***/
  68 #ifndef SILCSSH_H
  69 #define SILCSSH_H
  70
  71 /****d* silcssh/SilcSshAPI/SilcSshKeyType
  72  *
  73  * NAME
  74  *
  75  *    typedef enum { ... } SilcSshKeyType;
  76  *
  77  * DESCRIPTION
  78  *
  79  *    SSH2 public and private key types.  The default when new ke pair
  80  *    is created is SILC_SSH_KEY_OPENSSH.
  81  *
  82  * SOURCE
  83  */
  84 typedef enum {
  85   SILC_SSH_KEY_OPENSSH   = 1,      /* OpenSSH public/private key (default) */
  86   SILC_SSH_KEY_SSH2      = 2,      /* SSH2 public key, RFC 4716 */
  87 } SilcSshKeyType;
  88
  89 /****s* silcssh/SilcSshAPI/SilcSshPublicKey
  90  *
  91  * NAME
  92  *
  93  *    typedef struct { ... } *SilcSshPublicKey;
  94  *
  95  * DESCRIPTION
  96  *
  97  *    This structure defines the SSH2 public key.  This context can be
  98  *    retrieved from SilcPublicKey by calling silc_pkcs_public_key_get_pkcs
  99  *    for the PKCS type SILC_PKCS_SSH2 type.
 100  *
 101  * SOURCE
 102  */
 103 typedef struct SilcSshPublicKeyStruct  {
 104   SilcHashTable fields;            /* Public key headers */
 105   const SilcPKCSAlgorithm *pkcs;   /* PKCS Algorithm */
 106   void *public_key;                /* PKCS Algorithm specific public key */
 107   SilcSshKeyType type;             /* Public key type */
 108 } *SilcSshPublicKey;
 109 /***/
 110
 111 /****s* silcssh/SilcSshAPI/SilcSshPrivateKey
 112  *
 113  * NAME
 114  *
 115  *    typedef struct { ... } *SilcSshPrivateKey;
 116  *
 117  * DESCRIPTION
 118  *
 119  *    This structure defines the SSH2 private key.  This context can be
 120  *    retrieved from SilcPrivateKey by calling silc_pkcs_private_key_get_pkcs
 121  *    for the PKCS type SILC_PKCS_SSH2 type.
 122  *
 123  * SOURCE
 124  */
 125 typedef struct SilcSshPrivateKeyStruct  {
 126   SilcHashTable fields;            /* Private key headers */
 127   const SilcPKCSAlgorithm *pkcs;   /* PKCS Algorithm */
 128   void *private_key;               /* PKCS Algorithm specific private key */
 129   SilcSshKeyType type;             /* Private key type */
 130 } *SilcSshPrivateKey;
 131 /***/
 132
 133 /****f* silcssh/SilcSshAPI/silc_ssh_generate_key
 134  *
 135  * SYNOPSIS
 136  *
 137  *    SilcBool silc_ssh_generate_key(const char *algorithm,
 138  *                                   int bits_len, SilcRng rng,
 139  *                                   const char *subject,
 140  *                                   SilcPublicKey *ret_public_key,
 141  *                                   SilcPrivateKey *ret_private_key);
 142  *
 143  * DESCRIPTION
 144  *
 145  *    Generates new SSH2 key pair.  The `algorithm' is either rsa or dsa.
 146  *    The `bits_len' specify the key length in bits.  The `subject' is
 147  *    usually the email address of the user creating the key or some other
 148  *    similar subject name.  Returns FALSE on error.
 149  *
 150  * EXAMPLE
 151  *
 152  *    silc_ssh_generate_key("dsa", 1024, rng, "foo@example.com",
 153  *                          &pubkey, &privkey);
 154  *
 155  ***/
 156 SilcBool silc_ssh_generate_key(const char *algorithm,
 157                                int bits_len, SilcRng rng,
 158                                const char *subject,
 159                                SilcPublicKey *ret_public_key,
 160                                SilcPrivateKey *ret_private_key);
 161
 162 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_decode
 163  *
 164  * SYNOPSIS
 165  *
 166  *    int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
 167  *                                   SilcSshPublicKey *ret_public_key);
 168  *
 169  * DESCRIPTION
 170  *
 171  *    Decodes SSH Public Key indicated by `key' of length of `key_len'
 172  *    bytes.  The decoded public key is returned into the `ret_public_key'
 173  *    which the caller must free by calling the silc_ssh_public_key_free
 174  *    function.  This function expects the public key to be in raw binary
 175  *    format, without any public key file markers or headers.
 176  *
 177  *    This function returns the number of bytes decoded from the public
 178  *    key buffer or 0 on error.
 179  *
 180  ***/
 181 int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
 182                                SilcSshPublicKey *ret_public_key);
 183
 184 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_encode
 185  *
 186  * SYNOPSIS
 187  *
 188  *    unsigned char *silc_ssh_public_key_encode(SilcStack stack,
 189  *                                              SilcSshPublicKey public_key,
 190  *                                              SilcUInt32 *ret_key_len);
 191  *
 192  * DESCRIPTION
 193  *
 194  *    Encodes SSH Public key and returns the encoded buffer.  Caller must
 195  *    free the returned buffer.
 196  *
 197  *    If the `stack' is non-NULL the returned buffer is allocated from the
 198  *    `stack'.  This call will consume `stack' so caller should push the stack
 199  *    before calling and then later pop it.
 200  *
 201  ***/
 202 unsigned char *silc_ssh_public_key_encode(SilcStack stack,
 203                                           SilcSshPublicKey public_key,
 204                                           SilcUInt32 *ret_key_len);
 205
 206 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_free
 207  *
 208  * SYNOPSIS
 209  *
 210  *    void silc_ssh_public_key_free(SilcSshPublicKey public_key);
 211  *
 212  * DESCRIPTION
 213  *
 214  *    Frees the public key.
 215  *
 216  ***/
 217 void silc_ssh_public_key_free(SilcSshPublicKey public_key);
 218
 219 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_get_field
 220  *
 221  * SYNOPSIS
 222  *
 223  *    const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
 224  *                                              const char *field);
 225  *
 226  * DESCRIPTION
 227  *
 228  *    Returns public key header field `field' value from the public key or
 229  *    NULL if such header field was not present in the public key.
 230  *
 231  * EXAMPLE
 232  *
 233  *    subject = silc_ssh_public_key_get_field(public_key, "Subject");
 234  *    comment = silc_ssh_public_key_get_field(public_key, "Comment");
 235  *
 236  ***/
 237 const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
 238                                           const char *field);
 239
 240 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_add_field
 241  *
 242  * SYNOPSIS
 243  *
 244  *    SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
 245  *                                           const char *field,
 246  *                                           const char *value);
 247  *
 248  * DESCRIPTION
 249  *
 250  *    Add new public key header field and value to public key.  Returns
 251  *    FALSE if field could not be added or has been added already.
 252  *
 253  ***/
 254 SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
 255                                        const char *field,
 256                                        const char *value);
 257
 258 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_set_type
 259  *
 260  * SYNOPSIS
 261  *
 262  *    void silc_ssh_public_key_set_type(SilcSshPublicKey public_key,
 263  *                                      SilcSshKeyType type);
 264  *
 265  * DESCRIPTION
 266  *
 267  *    Set the type of the SSH public key.  This affects the format of the
 268  *    public key file when `public_key' is saved to a file.  If this is
 269  *    not called the default type is always SILC_SSH_KEY_OPENSSH.
 270  *
 271  ***/
 272 void silc_ssh_public_key_set_type(SilcSshPublicKey public_key,
 273                                   SilcSshKeyType type);
 274
 275 #include "silcssh_i.h"
 276
 277 #endif /* SILCSSH_H */