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