Grid Community Toolkit  6.2.1705709074 (tag: v6.2.20240202)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
sshkey.h
1 /* $OpenBSD: sshkey.h,v 1.61 2022/10/28 00:44:44 djm Exp $ */
2 
3 /*
4  * Copyright (c) 2000, 2001 Markus Friedl. All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25  */
26 #ifndef SSHKEY_H
27 #define SSHKEY_H
28 
29 #include <sys/types.h>
30 
31 #ifdef WITH_OPENSSL
32 #include <openssl/rsa.h>
33 #include <openssl/dsa.h>
34 #include <openssl/evp.h>
35 # if OPENSSL_VERSION_NUMBER >= 0x30000000L
36 #include <openssl/param_build.h>
37 #include <openssl/core_names.h>
38 # endif
39 # ifdef OPENSSL_HAS_ECC
40 # include <openssl/ec.h>
41 # include <openssl/ecdsa.h>
42 # else /* OPENSSL_HAS_ECC */
43 # define EC_KEY void
44 # define EC_GROUP void
45 # define EC_POINT void
46 # endif /* OPENSSL_HAS_ECC */
47 #define SSH_OPENSSL_VERSION OpenSSL_version(OPENSSL_VERSION)
48 #else /* WITH_OPENSSL */
49 # define BIGNUM void
50 # define RSA void
51 # define DSA void
52 # define EC_KEY void
53 # define EC_GROUP void
54 # define EC_POINT void
55 #define SSH_OPENSSL_VERSION "without OpenSSL"
56 #endif /* WITH_OPENSSL */
57 
58 #define SSH_RSA_MINIMUM_MODULUS_SIZE 1024
59 #define SSH_KEY_MAX_SIGN_DATA_SIZE (1 << 20)
60 
61 struct sshbuf;
62 
63 /* Key types */
64 enum sshkey_types {
65  KEY_RSA,
66  KEY_DSA,
67  KEY_ECDSA,
68  KEY_ED25519,
69  KEY_RSA_CERT,
70  KEY_DSA_CERT,
71  KEY_ECDSA_CERT,
72  KEY_ED25519_CERT,
73  KEY_XMSS,
74  KEY_XMSS_CERT,
75  KEY_ECDSA_SK,
76  KEY_ECDSA_SK_CERT,
77  KEY_ED25519_SK,
78  KEY_ED25519_SK_CERT,
79  KEY_NULL,
80  KEY_UNSPEC
81 };
82 
83 /* Default fingerprint hash */
84 #define SSH_FP_HASH_DEFAULT SSH_DIGEST_SHA256
85 
86 /* Fingerprint representation formats */
87 enum sshkey_fp_rep {
88  SSH_FP_DEFAULT = 0,
89  SSH_FP_HEX,
90  SSH_FP_BASE64,
91  SSH_FP_BUBBLEBABBLE,
92  SSH_FP_RANDOMART
93 };
94 
95 /* Private key serialisation formats, used on the wire */
96 enum sshkey_serialize_rep {
97  SSHKEY_SERIALIZE_DEFAULT = 0,
98  SSHKEY_SERIALIZE_STATE = 1, /* only state is serialized */
99  SSHKEY_SERIALIZE_FULL = 2, /* include keys for saving to disk */
100  SSHKEY_SERIALIZE_SHIELD = 3, /* everything, for encrypting in ram */
101  SSHKEY_SERIALIZE_INFO = 254, /* minimal information */
102 };
103 
104 /* Private key disk formats */
105 enum sshkey_private_format {
106  SSHKEY_PRIVATE_OPENSSH = 0,
107  SSHKEY_PRIVATE_PEM = 1,
108  SSHKEY_PRIVATE_PKCS8 = 2,
109 };
110 
111 /* key is stored in external hardware */
112 #define SSHKEY_FLAG_EXT 0x0001
113 
114 #define SSHKEY_CERT_MAX_PRINCIPALS 256
115 /* XXX opaquify? */
116 struct sshkey_cert {
117  struct sshbuf *certblob; /* Kept around for use on wire */
118  u_int type; /* SSH2_CERT_TYPE_USER or SSH2_CERT_TYPE_HOST */
119  u_int64_t serial;
120  char *key_id;
121  u_int nprincipals;
122  char **principals;
123  u_int64_t valid_after, valid_before;
124  struct sshbuf *critical;
125  struct sshbuf *extensions;
126  struct sshkey *signature_key;
127  char *signature_type;
128 };
129 
130 /* XXX opaquify? */
131 struct sshkey {
132  int type;
133  int flags;
134  /* KEY_RSA */
135  RSA *rsa;
136  /* KEY_DSA */
137  DSA *dsa;
138  /* KEY_ECDSA and KEY_ECDSA_SK */
139  int ecdsa_nid; /* NID of curve */
140  EC_KEY *ecdsa;
141  /* KEY_ED25519 and KEY_ED25519_SK */
142  u_char *ed25519_sk;
143  u_char *ed25519_pk;
144  /* KEY_XMSS */
145  char *xmss_name;
146  char *xmss_filename; /* for state file updates */
147  void *xmss_state; /* depends on xmss_name, opaque */
148  u_char *xmss_sk;
149  u_char *xmss_pk;
150  /* KEY_ECDSA_SK and KEY_ED25519_SK */
151  char *sk_application;
152  uint8_t sk_flags;
153  struct sshbuf *sk_key_handle;
154  struct sshbuf *sk_reserved;
155  /* Certificates */
156  struct sshkey_cert *cert;
157  /* Private key shielding */
158  u_char *shielded_private;
159  size_t shielded_len;
160  u_char *shield_prekey;
161  size_t shield_prekey_len;
162 };
163 
164 #define ED25519_SK_SZ crypto_sign_ed25519_SECRETKEYBYTES
165 #define ED25519_PK_SZ crypto_sign_ed25519_PUBLICKEYBYTES
166 
167 /* Additional fields contained in signature */
168 struct sshkey_sig_details {
169  uint32_t sk_counter; /* U2F signature counter */
170  uint8_t sk_flags; /* U2F signature flags; see ssh-sk.h */
171 };
172 
173 struct sshkey_impl_funcs {
174  u_int (*size)(const struct sshkey *); /* optional */
175  int (*alloc)(struct sshkey *); /* optional */
176  void (*cleanup)(struct sshkey *); /* optional */
177  int (*equal)(const struct sshkey *, const struct sshkey *);
178  int (*serialize_public)(const struct sshkey *, struct sshbuf *,
179  enum sshkey_serialize_rep);
180  int (*deserialize_public)(const char *, struct sshbuf *,
181  struct sshkey *);
182  int (*serialize_private)(const struct sshkey *, struct sshbuf *,
183  enum sshkey_serialize_rep);
184  int (*deserialize_private)(const char *, struct sshbuf *,
185  struct sshkey *);
186  int (*generate)(struct sshkey *, int); /* optional */
187  int (*copy_public)(const struct sshkey *, struct sshkey *);
188  int (*sign)(struct sshkey *, u_char **, size_t *,
189  const u_char *, size_t, const char *,
190  const char *, const char *, u_int); /* optional */
191  int (*verify)(const struct sshkey *, const u_char *, size_t,
192  const u_char *, size_t, const char *, u_int,
193  struct sshkey_sig_details **);
194 };
195 
196 struct sshkey_impl {
197  const char *name;
198  const char *shortname;
199  const char *sigalg;
200  int type;
201  int nid;
202  int cert;
203  int sigonly;
204  int keybits;
205  const struct sshkey_impl_funcs *funcs;
206 };
207 
208 struct sshkey *sshkey_new(int);
209 void sshkey_free(struct sshkey *);
210 int sshkey_equal_public(const struct sshkey *,
211  const struct sshkey *);
212 int sshkey_equal(const struct sshkey *, const struct sshkey *);
213 char *sshkey_fingerprint(const struct sshkey *,
214  int, enum sshkey_fp_rep);
215 int sshkey_fingerprint_raw(const struct sshkey *k,
216  int, u_char **retp, size_t *lenp);
217 const char *sshkey_type(const struct sshkey *);
218 const char *sshkey_cert_type(const struct sshkey *);
219 int sshkey_format_text(const struct sshkey *, struct sshbuf *);
220 int sshkey_write(const struct sshkey *, FILE *);
221 int sshkey_read(struct sshkey *, char **);
222 u_int sshkey_size(const struct sshkey *);
223 
224 int sshkey_generate(int type, u_int bits, struct sshkey **keyp);
225 int sshkey_from_private(const struct sshkey *, struct sshkey **);
226 
227 int sshkey_is_shielded(struct sshkey *);
228 int sshkey_shield_private(struct sshkey *);
229 int sshkey_unshield_private(struct sshkey *);
230 
231 int sshkey_type_from_name(const char *);
232 int sshkey_is_private(const struct sshkey *);
233 int sshkey_is_cert(const struct sshkey *);
234 int sshkey_is_sk(const struct sshkey *);
235 int sshkey_type_is_cert(int);
236 int sshkey_type_plain(int);
237 
238 /* Returns non-zero if key name match sigalgs pattern list. (handles RSA) */
239 int sshkey_match_keyname_to_sigalgs(const char *, const char *);
240 
241 int sshkey_to_certified(struct sshkey *);
242 int sshkey_drop_cert(struct sshkey *);
243 int sshkey_cert_copy(const struct sshkey *, struct sshkey *);
244 int sshkey_cert_check_authority(const struct sshkey *, int, int, int,
245  uint64_t, const char *, const char **);
246 int sshkey_cert_check_authority_now(const struct sshkey *, int, int, int,
247  const char *, const char **);
248 int sshkey_cert_check_host(const struct sshkey *, const char *,
249  int , const char *, const char **);
250 size_t sshkey_format_cert_validity(const struct sshkey_cert *,
251  char *, size_t) __attribute__((__bounded__(__string__, 2, 3)));
252 int sshkey_check_cert_sigtype(const struct sshkey *, const char *);
253 
254 int sshkey_certify(struct sshkey *, struct sshkey *,
255  const char *, const char *, const char *);
256 /* Variant allowing use of a custom signature function (e.g. for ssh-agent) */
257 typedef int sshkey_certify_signer(struct sshkey *, u_char **, size_t *,
258  const u_char *, size_t, const char *, const char *, const char *,
259  u_int, void *);
260 int sshkey_certify_custom(struct sshkey *, struct sshkey *, const char *,
261  const char *, const char *, sshkey_certify_signer *, void *);
262 
263 int sshkey_ecdsa_nid_from_name(const char *);
264 int sshkey_curve_name_to_nid(const char *);
265 const char * sshkey_curve_nid_to_name(int);
266 u_int sshkey_curve_nid_to_bits(int);
267 int sshkey_ecdsa_bits_to_nid(int);
268 int sshkey_ecdsa_key_to_nid(EC_KEY *);
269 int sshkey_ec_nid_to_hash_alg(int nid);
270 int sshkey_ec_validate_public(const EC_GROUP *, const EC_POINT *);
271 int sshkey_ec_validate_private(const EC_KEY *);
272 const char *sshkey_ssh_name(const struct sshkey *);
273 const char *sshkey_ssh_name_plain(const struct sshkey *);
274 int sshkey_names_valid2(const char *, int);
275 char *sshkey_alg_list(int, int, int, char);
276 int sshkey_calculate_signature(EVP_PKEY*, int, u_char **,
277  int *, const u_char *, size_t);
278 int sshkey_verify_signature(EVP_PKEY *, int, const u_char *,
279  size_t, u_char *, int);
280 
281 int sshkey_from_blob(const u_char *, size_t, struct sshkey **);
282 int sshkey_fromb(struct sshbuf *, struct sshkey **);
283 int sshkey_froms(struct sshbuf *, struct sshkey **);
284 int sshkey_to_blob(const struct sshkey *, u_char **, size_t *);
285 int sshkey_to_base64(const struct sshkey *, char **);
286 int sshkey_putb(const struct sshkey *, struct sshbuf *);
287 int sshkey_puts(const struct sshkey *, struct sshbuf *);
288 int sshkey_puts_opts(const struct sshkey *, struct sshbuf *,
289  enum sshkey_serialize_rep);
290 int sshkey_plain_to_blob(const struct sshkey *, u_char **, size_t *);
291 int sshkey_putb_plain(const struct sshkey *, struct sshbuf *);
292 
293 int sshkey_sign(struct sshkey *, u_char **, size_t *,
294  const u_char *, size_t, const char *, const char *, const char *, u_int);
295 int sshkey_verify(const struct sshkey *, const u_char *, size_t,
296  const u_char *, size_t, const char *, u_int, struct sshkey_sig_details **);
297 int sshkey_check_sigtype(const u_char *, size_t, const char *);
298 const char *sshkey_sigalg_by_name(const char *);
299 int sshkey_get_sigtype(const u_char *, size_t, char **);
300 
301 /* for debug */
302 void sshkey_dump_ec_point(const EC_GROUP *, const EC_POINT *);
303 void sshkey_dump_ec_key(const EC_KEY *);
304 
305 /* private key parsing and serialisation */
306 int sshkey_private_serialize(struct sshkey *key, struct sshbuf *buf);
307 int sshkey_private_serialize_opt(struct sshkey *key, struct sshbuf *buf,
308  enum sshkey_serialize_rep);
309 int sshkey_private_deserialize(struct sshbuf *buf, struct sshkey **keyp);
310 
311 /* private key file format parsing and serialisation */
312 int sshkey_private_to_fileblob(struct sshkey *key, struct sshbuf *blob,
313  const char *passphrase, const char *comment,
314  int format, const char *openssh_format_cipher, int openssh_format_rounds);
315 int sshkey_parse_private_fileblob(struct sshbuf *buffer,
316  const char *passphrase, struct sshkey **keyp, char **commentp);
317 int sshkey_parse_private_fileblob_type(struct sshbuf *blob, int type,
318  const char *passphrase, struct sshkey **keyp, char **commentp);
319 int sshkey_parse_pubkey_from_private_fileblob_type(struct sshbuf *blob,
320  int type, struct sshkey **pubkeyp);
321 
322 int sshkey_check_rsa_length(const struct sshkey *, int);
323 /* XXX should be internal, but used by ssh-keygen */
324 int ssh_rsa_complete_crt_parameters(struct sshkey *, const BIGNUM *);
325 
326 /* stateful keys (e.g. XMSS) */
327 int sshkey_set_filename(struct sshkey *, const char *);
328 int sshkey_enable_maxsign(struct sshkey *, u_int32_t);
329 u_int32_t sshkey_signatures_left(const struct sshkey *);
330 int sshkey_forward_state(const struct sshkey *, u_int32_t, int);
331 int sshkey_private_serialize_maxsign(struct sshkey *key,
332  struct sshbuf *buf, u_int32_t maxsign, int);
333 
334 void sshkey_sig_details_free(struct sshkey_sig_details *);
335 
336 #ifdef WITH_OPENSSL
337 # if OPENSSL_VERSION_NUMBER >= 0x30000000L
338 EVP_PKEY *sshkey_create_evp(OSSL_PARAM_BLD *, EVP_PKEY_CTX *);
339 int ssh_create_evp_dss(const struct sshkey *, EVP_PKEY **);
340 int ssh_create_evp_rsa(const struct sshkey *, EVP_PKEY **);
341 int ssh_create_evp_ec(EC_KEY *, int, EVP_PKEY **);
342 # endif
343 #endif /* WITH_OPENSSL */
344 
345 #ifdef SSHKEY_INTERNAL
346 int sshkey_sk_fields_equal(const struct sshkey *a, const struct sshkey *b);
347 void sshkey_sk_cleanup(struct sshkey *k);
348 int sshkey_serialize_sk(const struct sshkey *key, struct sshbuf *b);
349 int sshkey_copy_public_sk(const struct sshkey *from, struct sshkey *to);
350 int sshkey_deserialize_sk(struct sshbuf *b, struct sshkey *key);
351 int sshkey_serialize_private_sk(const struct sshkey *key,
352  struct sshbuf *buf);
353 int sshkey_private_deserialize_sk(struct sshbuf *buf, struct sshkey *k);
354 #ifdef WITH_OPENSSL
355 int check_rsa_length(const RSA *rsa); /* XXX remove */
356 #endif
357 #endif
358 
359 #ifdef ENABLE_PKCS11
360 int pkcs11_get_ecdsa_idx(void);
361 #endif
362 
363 #if !defined(WITH_OPENSSL)
364 # undef RSA
365 # undef DSA
366 # undef EC_KEY
367 # undef EC_GROUP
368 # undef EC_POINT
369 #elif !defined(OPENSSL_HAS_ECC)
370 # undef EC_KEY
371 # undef EC_GROUP
372 # undef EC_POINT
373 #endif
374 
375 #endif /* SSHKEY_H */
Generated by   doxygen 1.8.5