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.prv", 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.prv", passphrase, passphrase_len,
  62  *                            SILC_PKCS_SSH2, &public_key);
  63  *
  64  * // Free public and private key. Frees automatically the underlaying SSH keys.
  65  * silc_pkcs_public_key_free(public_key);
  66  * silc_pkcs_private_key_free(private_key);
  67  *
  68  ***/
  69 #ifndef SILCSSH_H
  70 #define SILCSSH_H
  71
  72 /****d* silcssh/SilcSshAPI/SilcSshKeyType
  73  *
  74  * NAME
  75  *
  76  *    typedef enum { ... } SilcSshKeyType;
  77  *
  78  * DESCRIPTION
  79  *
  80  *    SSH2 public and private key types.  The default when new key pair
  81  *    is created is SILC_SSH_KEY_OPENSSH.
  82  *
  83  * SOURCE
  84  */
  85 typedef enum {
  86   SILC_SSH_KEY_OPENSSH   = 1,      /* OpenSSH public/private key (default) */
  87   SILC_SSH_KEY_SSH2      = 2,      /* SSH2 public key, RFC 4716 */
  88 } SilcSshKeyType;
  89
  90 /****s* silcssh/SilcSshAPI/SilcSshPublicKey
  91  *
  92  * NAME
  93  *
  94  *    typedef struct { ... } *SilcSshPublicKey;
  95  *
  96  * DESCRIPTION
  97  *
  98  *    This structure defines the SSH2 public key.  This context can be
  99  *    retrieved from SilcPublicKey by calling silc_pkcs_public_key_get_pkcs
 100  *    for the PKCS type SILC_PKCS_SSH2.
 101  *
 102  * SOURCE
 103  */
 104 typedef struct SilcSshPublicKeyStruct  {
 105   SilcHashTable fields;            /* Public key headers */
 106   const SilcPKCSAlgorithm *pkcs;   /* PKCS Algorithm */
 107   void *public_key;                /* PKCS Algorithm specific public key */
 108   SilcSshKeyType type;             /* Public key type */
 109 } *SilcSshPublicKey;
 110 /***/
 111
 112 /****s* silcssh/SilcSshAPI/SilcSshPrivateKey
 113  *
 114  * NAME
 115  *
 116  *    typedef struct { ... } *SilcSshPrivateKey;
 117  *
 118  * DESCRIPTION
 119  *
 120  *    This structure defines the SSH2 private key.  This context can be
 121  *    retrieved from SilcPrivateKey by calling silc_pkcs_private_key_get_pkcs
 122  *    for the PKCS type SILC_PKCS_SSH2.
 123  *
 124  * SOURCE
 125  */
 126 typedef struct SilcSshPrivateKeyStruct  {
 127   SilcHashTable fields;            /* Private key headers */
 128   const SilcPKCSAlgorithm *pkcs;   /* PKCS Algorithm */
 129   void *private_key;               /* PKCS Algorithm specific private key */
 130   SilcSshKeyType type;             /* Private key type */
 131 } *SilcSshPrivateKey;
 132 /***/
 133
 134 /****f* silcssh/SilcSshAPI/silc_ssh_generate_key
 135  *
 136  * SYNOPSIS
 137  *
 138  *    SilcBool silc_ssh_generate_key(const char *algorithm,
 139  *                                   int bits_len, SilcRng rng,
 140  *                                   const char *subject,
 141  *                                   SilcPublicKey *ret_public_key,
 142  *                                   SilcPrivateKey *ret_private_key);
 143  *
 144  * DESCRIPTION
 145  *
 146  *    Generates new SSH2 key pair.  The `algorithm' is either rsa or dsa.
 147  *    The `bits_len' specify the key length in bits.  The `subject' is
 148  *    usually the email address of the user creating the key or some other
 149  *    similar subject name.  Returns FALSE on error.
 150  *
 151  * EXAMPLE
 152  *
 153  *    silc_ssh_generate_key("dsa", 1024, rng, "foo@example.com",
 154  *                          &pubkey, &privkey);
 155  *
 156  ***/
 157 SilcBool silc_ssh_generate_key(const char *algorithm,
 158                                int bits_len, SilcRng rng,
 159                                const char *subject,
 160                                SilcPublicKey *ret_public_key,
 161                                SilcPrivateKey *ret_private_key);
 162
 163 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_decode
 164  *
 165  * SYNOPSIS
 166  *
 167  *    int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
 168  *                                   SilcSshPublicKey *ret_public_key);
 169  *
 170  * DESCRIPTION
 171  *
 172  *    Decodes SSH Public Key indicated by `key' of length of `key_len'
 173  *    bytes.  The decoded public key is returned into the `ret_public_key'
 174  *    which the caller must free by calling the silc_ssh_public_key_free
 175  *    function.  This function expects the public key to be in raw binary
 176  *    format, without any public key file markers or headers.
 177  *
 178  *    This decodes SSH2 protocol compliant raw public key.
 179  *
 180  *    This function returns the number of bytes decoded from the public
 181  *    key buffer or 0 on error.
 182  *
 183  ***/
 184 int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
 185                                SilcSshPublicKey *ret_public_key);
 186
 187 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_encode
 188  *
 189  * SYNOPSIS
 190  *
 191  *    unsigned char *silc_ssh_public_key_encode(SilcStack stack,
 192  *                                              SilcSshPublicKey public_key,
 193  *                                              SilcUInt32 *ret_key_len);
 194  *
 195  * DESCRIPTION
 196  *
 197  *    Encodes SSH Public key and returns the encoded buffer.  Caller must
 198  *    free the returned buffer.
 199  *
 200  *    This encodes SSH2 protocol compliant raw public key.
 201  *
 202  *    If the `stack' is non-NULL the returned buffer is allocated from the
 203  *    `stack'.  This call will consume `stack' so caller should push the stack
 204  *    before calling and then later pop it.
 205  *
 206  ***/
 207 unsigned char *silc_ssh_public_key_encode(SilcStack stack,
 208                                           SilcSshPublicKey public_key,
 209                                           SilcUInt32 *ret_key_len);
 210
 211 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_free
 212  *
 213  * SYNOPSIS
 214  *
 215  *    void silc_ssh_public_key_free(SilcSshPublicKey public_key);
 216  *
 217  * DESCRIPTION
 218  *
 219  *    Frees the public key.  This need to be called only if you called
 220  *    silc_ssh_public_key_decode.  SSH public keys allocated through the
 221  *    SILC PKCS API can be freed by calling silc_pkcs_public_key_free.
 222  *
 223  ***/
 224 void silc_ssh_public_key_free(SilcSshPublicKey public_key);
 225
 226 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_get_field
 227  *
 228  * SYNOPSIS
 229  *
 230  *    const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
 231  *                                              const char *field);
 232  *
 233  * DESCRIPTION
 234  *
 235  *    Returns public key header field `field' value from the public key or
 236  *    NULL if such header field was not present in the public key.
 237  *
 238  * EXAMPLE
 239  *
 240  *    subject = silc_ssh_public_key_get_field(public_key, "Subject");
 241  *    comment = silc_ssh_public_key_get_field(public_key, "Comment");
 242  *
 243  ***/
 244 const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
 245                                           const char *field);
 246
 247 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_add_field
 248  *
 249  * SYNOPSIS
 250  *
 251  *    SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
 252  *                                           const char *field,
 253  *                                           const char *value);
 254  *
 255  * DESCRIPTION
 256  *
 257  *    Add new public key header field and value to public key.  Returns
 258  *    FALSE if field could not be added or has been added already.
 259  *
 260  ***/
 261 SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
 262                                        const char *field,
 263                                        const char *value);
 264
 265 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_set_type
 266  *
 267  * SYNOPSIS
 268  *
 269  *    void silc_ssh_public_key_set_type(SilcSshPublicKey public_key,
 270  *                                      SilcSshKeyType type);
 271  *
 272  * DESCRIPTION
 273  *
 274  *    Set the type of the SSH public key.  This affects the format of the
 275  *    public key file when `public_key' is saved to a file.  If this is
 276  *    not called the default type is always SILC_SSH_KEY_OPENSSH.
 277  *
 278  ***/
 279 void silc_ssh_public_key_set_type(SilcSshPublicKey public_key,
 280                                   SilcSshKeyType type);
 281
 282 #include "silcssh_i.h"
 283
 284 #endif /* SILCSSH_H */