5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2007 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/SILC 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.
38 * SilcPublicKey public_key;
39 * SilcPrivateKey private_key;
40 * SilcSshPublicKey ssh_pubkey;
41 * SilcSshPrivateKey ssh_privkey;
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);
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");
52 * // Rest of the operations use standard SILC PKCS API
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);
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);
64 * // Compute signature
65 * silc_pkcs_sign(private_key, src, src_len, TRUE, sha1, rng, sign_cb, ctx);
71 /****d* silcssh/SilcSshAPI/SilcSshKeyType
75 * typedef enum { ... } SilcSshKeyType;
79 * SSH2 public and private key types. The default when new ke pair
80 * is created is SILC_SSH_KEY_OPENSSH.
85 SILC_SSH_KEY_OPENSSH = 1, /* OpenSSH public/private key (default) */
86 SILC_SSH_KEY_SSH2 = 2, /* SSH2 public key, RFC 4716 */
89 /****s* silcssh/SilcSshAPI/SilcSshPublicKey
93 * typedef struct { ... } *SilcSshPublicKey;
97 * This structure defines the SSH2 public key. This context can be
98 * retrieved from SilcPublicKey by calling silc_pkcs_public_key_get_pkcs
99 * for the PKCS type SILC_PKCS_SSH2 type.
103 typedef struct SilcSshPublicKeyStruct {
104 SilcHashTable fields; /* Public key headers */
105 const SilcPKCSAlgorithm *pkcs; /* PKCS Algorithm */
106 void *public_key; /* PKCS Algorithm specific public key */
107 SilcSshKeyType type; /* Public key type */
111 /****s* silcssh/SilcSshAPI/SilcSshPrivateKey
115 * typedef struct { ... } *SilcSshPrivateKey;
119 * This structure defines the SSH2 private key. This context can be
120 * retrieved from SilcPrivateKey by calling silc_pkcs_private_key_get_pkcs
121 * for the PKCS type SILC_PKCS_SSH2 type.
125 typedef struct SilcSshPrivateKeyStruct {
126 SilcHashTable fields; /* Private key headers */
127 const SilcPKCSAlgorithm *pkcs; /* PKCS Algorithm */
128 void *private_key; /* PKCS Algorithm specific private key */
129 SilcSshKeyType type; /* Private key type */
130 } *SilcSshPrivateKey;
133 /****f* silcssh/SilcSshAPI/silc_ssh_generate_key
137 * SilcBool silc_ssh_generate_key(const char *algorithm,
138 * int bits_len, SilcRng rng,
139 * const char *subject,
140 * SilcPublicKey *ret_public_key,
141 * SilcPrivateKey *ret_private_key);
145 * Generates new SSH2 key pair. The `algorithm' is either rsa or dsa.
146 * The `bits_len' specify the key length in bits. The `subject' is
147 * usually the email address of the user creating the key or some other
148 * similar subject name. Returns FALSE on error.
152 * silc_ssh_generate_key("dsa", 1024, rng, "foo@example.com",
153 * &pubkey, &privkey);
156 SilcBool silc_ssh_generate_key(const char *algorithm,
157 int bits_len, SilcRng rng,
159 SilcPublicKey *ret_public_key,
160 SilcPrivateKey *ret_private_key);
162 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_decode
166 * int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
167 * SilcSshPublicKey *ret_public_key);
171 * Decodes SSH Public Key indicated by `key' of length of `key_len'
172 * bytes. The decoded public key is returned into the `ret_public_key'
173 * which the caller must free by calling the silc_ssh_public_key_free
174 * function. This function expects the public key to be in raw binary
175 * format, without any public key file markers or headers.
177 * This function returns the number of bytes decoded from the public
178 * key buffer or 0 on error.
181 int silc_ssh_public_key_decode(unsigned char *key, SilcUInt32 key_len,
182 SilcSshPublicKey *ret_public_key);
184 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_encode
188 * unsigned char *silc_ssh_public_key_encode(SilcStack stack,
189 * SilcSshPublicKey public_key,
190 * SilcUInt32 *ret_key_len);
194 * Encodes SSH Public key and returns the encoded buffer. Caller must
195 * free the returned buffer.
197 * If the `stack' is non-NULL the returned buffer is allocated from the
198 * `stack'. This call will consume `stack' so caller should push the stack
199 * before calling and then later pop it.
202 unsigned char *silc_ssh_public_key_encode(SilcStack stack,
203 SilcSshPublicKey public_key,
204 SilcUInt32 *ret_key_len);
206 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_free
210 * void silc_ssh_public_key_free(SilcSshPublicKey public_key);
214 * Frees the public key.
217 void silc_ssh_public_key_free(SilcSshPublicKey public_key);
219 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_get_field
223 * const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
224 * const char *field);
228 * Returns public key header field `field' value from the public key or
229 * NULL if such header field was not present in the public key.
233 * subject = silc_ssh_public_key_get_field(public_key, "Subject");
234 * comment = silc_ssh_public_key_get_field(public_key, "Comment");
237 const char *silc_ssh_public_key_get_field(SilcSshPublicKey public_key,
240 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_add_field
244 * SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
246 * const char *value);
250 * Add new public key header field and value to public key. Returns
251 * FALSE if field could not be added or has been added already.
254 SilcBool silc_ssh_public_key_add_field(SilcSshPublicKey public_key,
258 /****f* silcssh/SilcSshAPI/silc_ssh_public_key_set_type
262 * void silc_ssh_public_key_set_type(SilcSshPublicKey public_key,
263 * SilcSshKeyType type);
267 * Set the type of the SSH public key. This affects the format of the
268 * public key file when `public_key' is saved to a file. If this is
269 * not called the default type is always SILC_SSH_KEY_OPENSSH.
272 void silc_ssh_public_key_set_type(SilcSshPublicKey public_key,
273 SilcSshKeyType type);
275 #include "silcssh_i.h"
277 #endif /* SILCSSH_H */