5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2007 - 2008 Pekka Riikonen
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.
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.
20 /****h* silcssh/SSH Interface
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
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.
39 * SilcPublicKey public_key;
40 * SilcPrivateKey private_key;
41 * SilcSshPublicKey ssh_pubkey;
42 * SilcSshPrivateKey ssh_privkey;
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);
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");
53 * // Rest of the operations use standard SILC PKCS API
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);
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);
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);
73 /****d* silcssh/SilcSshKeyType
77 * typedef enum { ... } SilcSshKeyType;
81 * SSH2 public and private key types. The default when new key pair
82 * is created is SILC_SSH_KEY_OPENSSH.
87 SILC_SSH_KEY_OPENSSH = 1, /* OpenSSH public/private key (default) */
88 SILC_SSH_KEY_SSH2 = 2, /* SSH2 public key, RFC 4716 */
92 /****s* silcssh/SilcSshPublicKey
96 * typedef struct { ... } *SilcSshPublicKey;
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.
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 */
114 /****s* silcssh/SilcSshPrivateKey
118 * typedef struct { ... } *SilcSshPrivateKey;
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.
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;
136 /****f* silcssh/silc_ssh_generate_key
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);
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.
155 * silc_ssh_generate_key("dsa", 1024, rng, "foo@example.com",
156 * &pubkey, &privkey);
159 SilcBool silc_ssh_generate_key(const char *algorithm,
160 int bits_len, SilcRng rng,
162 SilcPublicKey *ret_public_key,
163 SilcPrivateKey *ret_private_key);
165 /****f* silcssh/silc_ssh_public_key_decode
169 * int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
170 * SilcSshPublicKey *ret_public_key);
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.
180 * This decodes SSH2 protocol compliant raw public key.
182 * This function returns the number of bytes decoded from the public
183 * key buffer or 0 on error.
186 int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
187 SilcSshPublicKey *ret_public_key);
189 /****f* silcssh/silc_ssh_public_key_encode
193 * unsigned char *silc_ssh_public_key_encode(SilcStack stack,
194 * SilcSshPublicKey public_key,
195 * SilcUInt32 *ret_key_len);
199 * Encodes SSH Public key and returns the encoded buffer. Caller must
200 * free the returned buffer.
202 * This encodes SSH2 protocol compliant raw public key.
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.
209 unsigned char *silc_ssh_public_key_encode(SilcStack stack,
210 SilcSshPublicKey public_key,
211 SilcUInt32 *ret_key_len);
213 /****f* silcssh/silc_ssh_public_key_free
217 * void silc_ssh_public_key_free(SilcSshPublicKey public_key);
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.
226 void silc_ssh_public_key_free(SilcSshPublicKey public_key);
228 /****f* silcssh/silc_ssh_public_key_get_field
232 * const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
233 * const char *field);
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.
242 * subject = silc_ssh_public_key_get_field(public_key, "Subject");
243 * comment = silc_ssh_public_key_get_field(public_key, "Comment");
246 const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
249 /****f* silcssh/silc_ssh_public_key_add_field
253 * SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
255 * const char *value);
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.
263 SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
267 /****f* silcssh/silc_ssh_public_key_set_type
271 * void silc_ssh_public_key_set_type(SilcSshPublicKey public_key,
272 * SilcSshKeyType type);
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.
281 void silc_ssh_public_key_set_type(SilcSshPublicKey public_key,
282 SilcSshKeyType type);
284 #include "silcssh_i.h"
286 #endif /* SILCSSH_H */