lib/silcssh/silcssh.h

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