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, &public_key, &private_key);
  45  *
  46  * // Add (optional) headers to the key before saving to a file
  47  * ssh_pubkey = silc_pkcs_public_key_get_pkcs(SILC_PKCS_SSH2, public_key);
  48  * silc_ssh_public_key_set_type(ssh_pubkey, SILC_SSH_KEY_SSH2);
  49  * silc_ssh_public_key_add_field(ssh_pubkey, "Subject", "foo@example.com");
  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, sign_cb, ctx);
  66  *
  67  ***/
  68 #ifndef SILCSSH_H
  69 #define SILCSSH_H
  70
  71 typedef enum {
  72   SILC_SSH_KEY_OPENSSH   = 1,      /* OpenSSH public/private key (default) */
  73   SILC_SSH_KEY_SSH2      = 2,      /* SSH2 public key, RFC 4716 */
  74 } SilcSshKeyType;
  75
  76 typedef struct SilcSshPublicKeyStruct  {
  77   SilcHashTable fields;            /* Public key headers */
  78   const SilcPKCSAlgorithm *pkcs;   /* PKCS Algorithm */
  79   void *public_key;                /* PKCS Algorithm specific public key */
  80   SilcSshKeyType type;             /* Public key type */
  81 } *SilcSshPublicKey;
  82
  83 typedef struct SilcSshPrivateKeyStruct  {
  84   SilcHashTable fields;            /* Private key headers */
  85   const SilcPKCSAlgorithm *pkcs;   /* PKCS Algorithm */
  86   void *private_key;               /* PKCS Algorithm specific private key */
  87   SilcSshKeyType type;             /* Private key type */
  88 } *SilcSshPrivateKey;
  89
  90 /****f* silcssh/SilcSshAPI/silc_ssh_generate_key
  91  *
  92  * SYNOPSIS
  93  *
  94  *    SilcBool silc_ssh_generate_key(const char *algorithm,
  95  *                                   int bits_len, SilcRng rng,
  96  *                                   SilcPublicKey *ret_public_key,
  97  *                                   SilcPrivateKey *ret_private_key);
  98  *
  99  * DESCRIPTION
 100  *
 101  *    Generates new SSH2 key pair.  The `algorithm' is either rsa or dsa.
 102  *    The `bits_len' specify the key length in bits.  Returns FALSE on error.
 103  *
 104  ***/
 105 SilcBool silc_ssh_generate_key(const char *algorithm,
 106                                int bits_len, SilcRng rng,
 107                                SilcPublicKey *ret_public_key,
 108                                SilcPrivateKey *ret_private_key);
 109
 110 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_decode
 111  *
 112  * SYNOPSIS
 113  *
 114  *    int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
 115  *                                   SilcSshPublicKey *ret_public_key);
 116  *
 117  * DESCRIPTION
 118  *
 119  *    Decodes SSH Public Key indicated by `key' of length of `key_len'
 120  *    bytes.  The decoded public key is returned into the `ret_public_key'
 121  *    which the caller must free by calling the silc_ssh_public_key_free
 122  *    function.  This function expects the public key to be in raw binary
 123  *    format, without any public key file markers or headers.
 124  *
 125  *    This function returns the number of bytes decoded from the public
 126  *    key buffer or 0 on error.
 127  *
 128  ***/
 129 int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
 130                                SilcSshPublicKey *ret_public_key);
 131
 132 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_encode
 133  *
 134  * SYNOPSIS
 135  *
 136  *    unsigned char *silc_ssh_public_key_encode(SilcStack stack,
 137  *                                              SilcSshPublicKey public_key,
 138  *                                              SilcUInt32 *ret_key_len);
 139  *
 140  * DESCRIPTION
 141  *
 142  *    Encodes SSH Public key and returns the encoded buffer.  Caller must
 143  *    free the returned buffer.
 144  *
 145  *    If the `stack' is non-NULL the returned buffer is allocated from the
 146  *    `stack'.  This call will consume `stack' so caller should push the stack
 147  *    before calling and then later pop it.
 148  *
 149  ***/
 150 unsigned char *silc_ssh_public_key_encode(SilcStack stack,
 151                                           SilcSshPublicKey public_key,
 152                                           SilcUInt32 *ret_key_len);
 153
 154 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_free
 155  *
 156  * SYNOPSIS
 157  *
 158  *    void silc_ssh_public_key_free(SilcSshPublicKey public_key);
 159  *
 160  * DESCRIPTION
 161  *
 162  *    Frees the public key.
 163  *
 164  ***/
 165 void silc_ssh_public_key_free(SilcSshPublicKey public_key);
 166
 167 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_get_field
 168  *
 169  * SYNOPSIS
 170  *
 171  *    const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
 172  *                                              const char *field);
 173  *
 174  * DESCRIPTION
 175  *
 176  *    Returns public key header field `field' value from the public key or
 177  *    NULL if such header field was not present in the public key.
 178  *
 179  * EXAMPLE
 180  *
 181  *    subject = silc_ssh_public_key_get_field(public_key, "Subject");
 182  *    comment = silc_ssh_public_key_get_field(public_key, "Comment");
 183  *
 184  ***/
 185 const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
 186                                           const char *field);
 187
 188 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_add_field
 189  *
 190  * SYNOPSIS
 191  *
 192  *    SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
 193  *                                           const char *field,
 194  *                                           const char *value);
 195  *
 196  * DESCRIPTION
 197  *
 198  *    Add new public key header field and value to public key.  Returns
 199  *    FALSE if field could not be added or has been added already.
 200  *
 201  ***/
 202 SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
 203                                        const char *field,
 204                                        const char *value);
 205
 206 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_set_type
 207  *
 208  * SYNOPSIS
 209  *
 210  *    void silc_ssh_public_key_set_type(SilcSshPublicKey public_key,
 211  *                                      SilcSshKeyType type);
 212  *
 213  * DESCRIPTION
 214  *
 215  *    Set the type of the SSH public key.  This affects the format of the
 216  *    public key file when `public_key' is saved to a file.  If this is
 217  *    not called the default type is always SILC_SSH_KEY_OPENSSH.
 218  *
 219  ***/
 220 void silc_ssh_public_key_set_type(SilcSshPublicKey public_key,
 221                                   SilcSshKeyType type);
 222
 223 #include "silcssh_i.h"
 224
 225 #endif /* SILCSSH_H */