jcs.org
jcs's openbsd hax
openbsd
1/* $OpenBSD: sshkey.h,v 1.72 2026/02/06 22:59:18 dtucker 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/ec.h>
34#include <openssl/ecdsa.h>
35#include <openssl/evp.h>
36#define SSH_OPENSSL_VERSION OpenSSL_version(OPENSSL_VERSION)
37#else /* OPENSSL */
38#define BIGNUM void
39#define RSA void
40#define EC_KEY void
41#define EC_GROUP void
42#define EC_POINT void
43#define EVP_PKEY void
44#define SSH_OPENSSL_VERSION "without OpenSSL"
45#endif /* WITH_OPENSSL */
46
47#define SSH_RSA_MINIMUM_MODULUS_SIZE 1024
48#define SSH_KEY_MAX_SIGN_DATA_SIZE (1 << 20)
49
50struct sshbuf;
51
52/* Key types */
53enum sshkey_types {
54 KEY_RSA,
55 KEY_ECDSA,
56 KEY_ED25519,
57 KEY_RSA_CERT,
58 KEY_ECDSA_CERT,
59 KEY_ED25519_CERT,
60 KEY_ECDSA_SK,
61 KEY_ECDSA_SK_CERT,
62 KEY_ED25519_SK,
63 KEY_ED25519_SK_CERT,
64 KEY_UNSPEC
65};
66
67/* Default fingerprint hash */
68#define SSH_FP_HASH_DEFAULT SSH_DIGEST_SHA256
69
70/* Fingerprint representation formats */
71enum sshkey_fp_rep {
72 SSH_FP_DEFAULT = 0,
73 SSH_FP_HEX,
74 SSH_FP_BASE64,
75 SSH_FP_BUBBLEBABBLE,
76 SSH_FP_RANDOMART
77};
78
79/* Private key serialisation formats, used on the wire */
80enum sshkey_serialize_rep {
81 SSHKEY_SERIALIZE_DEFAULT = 0,
82};
83
84/* Private key disk formats */
85enum sshkey_private_format {
86 SSHKEY_PRIVATE_OPENSSH = 0,
87 SSHKEY_PRIVATE_PEM = 1,
88 SSHKEY_PRIVATE_PKCS8 = 2,
89};
90
91/* key is stored in external hardware */
92#define SSHKEY_FLAG_EXT 0x0001
93
94#define SSHKEY_CERT_MAX_PRINCIPALS 256
95/* XXX opacify? */
96struct sshkey_cert {
97 struct sshbuf *certblob; /* Kept around for use on wire */
98 u_int type; /* SSH2_CERT_TYPE_USER or SSH2_CERT_TYPE_HOST */
99 u_int64_t serial;
100 char *key_id;
101 u_int nprincipals;
102 char **principals;
103 u_int64_t valid_after, valid_before;
104 struct sshbuf *critical;
105 struct sshbuf *extensions;
106 struct sshkey *signature_key;
107 char *signature_type;
108};
109
110/* XXX opacify? */
111struct sshkey {
112 int type;
113 int flags;
114 /* KEY_ECDSA and KEY_ECDSA_SK */
115 int ecdsa_nid; /* NID of curve */
116 /* libcrypto-backed keys */
117 EVP_PKEY *pkey;
118 /* KEY_ED25519 and KEY_ED25519_SK */
119 u_char *ed25519_sk;
120 u_char *ed25519_pk;
121 /* KEY_ECDSA_SK and KEY_ED25519_SK */
122 char *sk_application;
123 uint8_t sk_flags;
124 struct sshbuf *sk_key_handle;
125 struct sshbuf *sk_reserved;
126 /* Certificates */
127 struct sshkey_cert *cert;
128 /* Private key shielding */
129 u_char *shielded_private;
130 size_t shielded_len;
131 u_char *shield_prekey;
132 size_t shield_prekey_len;
133};
134
135#define ED25519_SK_SZ crypto_sign_ed25519_SECRETKEYBYTES
136#define ED25519_PK_SZ crypto_sign_ed25519_PUBLICKEYBYTES
137
138/* Additional fields contained in signature */
139struct sshkey_sig_details {
140 uint32_t sk_counter; /* U2F signature counter */
141 uint8_t sk_flags; /* U2F signature flags; see ssh-sk.h */
142};
143
144struct sshkey_impl_funcs {
145 u_int (*size)(const struct sshkey *); /* optional */
146 int (*alloc)(struct sshkey *); /* optional */
147 void (*cleanup)(struct sshkey *); /* optional */
148 int (*equal)(const struct sshkey *, const struct sshkey *);
149 int (*serialize_public)(const struct sshkey *, struct sshbuf *,
150 enum sshkey_serialize_rep);
151 int (*deserialize_public)(const char *, struct sshbuf *,
152 struct sshkey *);
153 int (*serialize_private)(const struct sshkey *, struct sshbuf *,
154 enum sshkey_serialize_rep);
155 int (*deserialize_private)(const char *, struct sshbuf *,
156 struct sshkey *);
157 int (*generate)(struct sshkey *, int); /* optional */
158 int (*copy_public)(const struct sshkey *, struct sshkey *);
159 int (*sign)(struct sshkey *, u_char **, size_t *,
160 const u_char *, size_t, const char *,
161 const char *, const char *, u_int); /* optional */
162 int (*verify)(const struct sshkey *, const u_char *, size_t,
163 const u_char *, size_t, const char *, u_int,
164 struct sshkey_sig_details **);
165};
166
167struct sshkey_impl {
168 const char *name;
169 const char *shortname;
170 const char *sigalg;
171 int type;
172 int nid;
173 int cert;
174 int sigonly;
175 int keybits;
176 const struct sshkey_impl_funcs *funcs;
177};
178
179struct sshkey *sshkey_new(int);
180void sshkey_free(struct sshkey *);
181int sshkey_equal_public(const struct sshkey *,
182 const struct sshkey *);
183int sshkey_equal(const struct sshkey *, const struct sshkey *);
184char *sshkey_fingerprint(const struct sshkey *,
185 int, enum sshkey_fp_rep);
186int sshkey_fingerprint_raw(const struct sshkey *k,
187 int, u_char **retp, size_t *lenp);
188const char *sshkey_type(const struct sshkey *);
189const char *sshkey_cert_type(const struct sshkey *);
190int sshkey_format_text(const struct sshkey *, struct sshbuf *);
191int sshkey_write(const struct sshkey *, FILE *);
192int sshkey_read(struct sshkey *, char **);
193u_int sshkey_size(const struct sshkey *);
194
195int sshkey_generate(int type, u_int bits, struct sshkey **keyp);
196int sshkey_from_private(const struct sshkey *, struct sshkey **);
197
198int sshkey_is_shielded(struct sshkey *);
199int sshkey_shield_private(struct sshkey *);
200int sshkey_unshield_private(struct sshkey *);
201
202int sshkey_type_from_name(const char *);
203int sshkey_type_from_shortname(const char *);
204int sshkey_is_cert(const struct sshkey *);
205int sshkey_is_sk(const struct sshkey *);
206int sshkey_type_is_cert(int);
207int sshkey_type_plain(int);
208
209/* Returns non-zero if key name match sigalgs pattern list. (handles RSA) */
210int sshkey_match_keyname_to_sigalgs(const char *, const char *);
211
212int sshkey_to_certified(struct sshkey *);
213int sshkey_drop_cert(struct sshkey *);
214int sshkey_cert_copy(const struct sshkey *, struct sshkey *);
215int sshkey_cert_check_authority(const struct sshkey *, int, int,
216 uint64_t, const char *, const char **);
217int sshkey_cert_check_authority_now(const struct sshkey *, int, int,
218 const char *, const char **);
219int sshkey_cert_check_host(const struct sshkey *, const char *,
220 const char *, const char **);
221size_t sshkey_format_cert_validity(const struct sshkey_cert *,
222 char *, size_t) __attribute__((__bounded__(__string__, 2, 3)));
223int sshkey_check_cert_sigtype(const struct sshkey *, const char *);
224
225int sshkey_certify(struct sshkey *, struct sshkey *,
226 const char *, const char *, const char *);
227/* Variant allowing use of a custom signature function (e.g. for ssh-agent) */
228typedef int sshkey_certify_signer(struct sshkey *, u_char **, size_t *,
229 const u_char *, size_t, const char *, const char *, const char *,
230 u_int, void *);
231int sshkey_certify_custom(struct sshkey *, struct sshkey *, const char *,
232 const char *, const char *, sshkey_certify_signer *, void *);
233
234int sshkey_ecdsa_nid_from_name(const char *);
235int sshkey_curve_name_to_nid(const char *);
236const char * sshkey_curve_nid_to_name(int);
237u_int sshkey_curve_nid_to_bits(int);
238int sshkey_ecdsa_bits_to_nid(int);
239int sshkey_ecdsa_key_to_nid(const EC_KEY *);
240int sshkey_ecdsa_pkey_to_nid(EVP_PKEY *);
241int sshkey_ec_nid_to_hash_alg(int nid);
242int sshkey_ec_validate_public(const EC_GROUP *, const EC_POINT *);
243int sshkey_ec_validate_private(const EC_KEY *);
244const char *sshkey_ssh_name(const struct sshkey *);
245const char *sshkey_ssh_name_plain(const struct sshkey *);
246int sshkey_names_valid2(const char *, int, int);
247char *sshkey_alg_list(int, int, int, char);
248
249int sshkey_from_blob(const u_char *, size_t, struct sshkey **);
250int sshkey_fromb(struct sshbuf *, struct sshkey **);
251int sshkey_froms(struct sshbuf *, struct sshkey **);
252int sshkey_to_blob(const struct sshkey *, u_char **, size_t *);
253int sshkey_to_base64(const struct sshkey *, char **);
254int sshkey_putb(const struct sshkey *, struct sshbuf *);
255int sshkey_puts(const struct sshkey *, struct sshbuf *);
256int sshkey_plain_to_blob(const struct sshkey *, u_char **, size_t *);
257int sshkey_putb_plain(const struct sshkey *, struct sshbuf *);
258int sshkey_puts_plain(const struct sshkey *, struct sshbuf *);
259
260int sshkey_sign(struct sshkey *, u_char **, size_t *,
261 const u_char *, size_t, const char *, const char *, const char *, u_int);
262int sshkey_verify(const struct sshkey *, const u_char *, size_t,
263 const u_char *, size_t, const char *, u_int, struct sshkey_sig_details **);
264int sshkey_check_sigtype(const u_char *, size_t, const char *);
265const char *sshkey_sigalg_by_name(const char *);
266int sshkey_get_sigtype(const u_char *, size_t, char **);
267
268/* Signing and verification backend for libcrypto-backed keys */
269int sshkey_pkey_digest_sign(EVP_PKEY*, int, u_char **,
270 size_t *, const u_char *, size_t);
271int sshkey_pkey_digest_verify(EVP_PKEY *, int, const u_char *,
272 size_t, u_char *, size_t);
273
274/* for debug */
275void sshkey_dump_ec_point(const EC_GROUP *, const EC_POINT *);
276void sshkey_dump_ec_key(const EC_KEY *);
277
278/* private key parsing and serialisation */
279int sshkey_private_serialize(struct sshkey *key, struct sshbuf *buf);
280int sshkey_private_deserialize(struct sshbuf *buf, struct sshkey **keyp);
281
282/* private key file format parsing and serialisation */
283int sshkey_private_to_fileblob(struct sshkey *key, struct sshbuf *blob,
284 const char *passphrase, const char *comment,
285 int format, const char *openssh_format_cipher, int openssh_format_rounds);
286int sshkey_parse_private_fileblob(struct sshbuf *buffer,
287 const char *passphrase, struct sshkey **keyp, char **commentp);
288int sshkey_parse_private_fileblob_type(struct sshbuf *blob, int type,
289 const char *passphrase, struct sshkey **keyp, char **commentp);
290int sshkey_parse_pubkey_from_private_fileblob_type(struct sshbuf *blob,
291 int type, struct sshkey **pubkeyp);
292
293int sshkey_check_rsa_length(const struct sshkey *, int);
294/* XXX should be internal, but used by ssh-keygen */
295int ssh_rsa_complete_crt_parameters(const BIGNUM *, const BIGNUM *,
296 const BIGNUM *, const BIGNUM *, BIGNUM **, BIGNUM **);
297
298void sshkey_sig_details_free(struct sshkey_sig_details *);
299
300#ifdef WITH_OPENSSL
301int sshkey_ecdsa_fixup_group(EVP_PKEY *k); /* ssh-ecdsa.c */
302#endif
303
304#ifdef SSHKEY_INTERNAL
305int sshkey_sk_fields_equal(const struct sshkey *a, const struct sshkey *b);
306void sshkey_sk_cleanup(struct sshkey *k);
307int sshkey_serialize_sk(const struct sshkey *key, struct sshbuf *b);
308int sshkey_copy_public_sk(const struct sshkey *from, struct sshkey *to);
309int sshkey_deserialize_sk(struct sshbuf *b, struct sshkey *key);
310int sshkey_serialize_private_sk(const struct sshkey *key,
311 struct sshbuf *buf);
312int sshkey_private_deserialize_sk(struct sshbuf *buf, struct sshkey *k);
313#ifdef WITH_OPENSSL
314int check_rsa_length(const RSA *rsa); /* XXX remove */
315int ssh_rsa_hash_id_from_keyname(const char *);
316const char *ssh_rsa_hash_alg_ident(int);
317int ssh_rsa_encode_store_sig(int, const u_char *, size_t,
318 u_char **, size_t *);
319int ssh_ecdsa_encode_store_sig(const struct sshkey *,
320 const BIGNUM *, const BIGNUM *, u_char **, size_t *);
321#endif
322int ssh_ed25519_encode_store_sig(const u_char *, size_t,
323 u_char **, size_t *);
324#endif
325
326#ifndef WITH_OPENSSL
327#undef RSA
328#undef EC_KEY
329#undef EC_GROUP
330#undef EC_POINT
331#undef EVP_PKEY
332#endif /* WITH_OPENSSL */
333
334#endif /* SSHKEY_H */