crypto/openssh/sshkey.h

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