crypto/openssh/sk-api.h

   1 /* $OpenBSD: sk-api.h,v 1.12 2021/02/18 02:15:07 djm Exp $ */
   2 /*
   3  * Copyright (c) 2019 Google LLC
   4  *
   5  * Permission to use, copy, modify, and distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 #ifndef _SK_API_H
  19 #define _SK_API_H 1
  20
  21 #include <stddef.h>
  22 #ifdef HAVE_STDINT_H
  23 #include <stdint.h>
  24 #endif
  25
  26 /* Flags */
  27 #define SSH_SK_USER_PRESENCE_REQD       0x01
  28 #define SSH_SK_USER_VERIFICATION_REQD   0x04
  29 #define SSH_SK_RESIDENT_KEY             0x20
  30
  31 /* Algs */
  32 #define SSH_SK_ECDSA                    0x00
  33 #define SSH_SK_ED25519                  0x01
  34
  35 /* Error codes */
  36 #define SSH_SK_ERR_GENERAL              -1
  37 #define SSH_SK_ERR_UNSUPPORTED          -2
  38 #define SSH_SK_ERR_PIN_REQUIRED         -3
  39 #define SSH_SK_ERR_DEVICE_NOT_FOUND     -4
  40
  41 struct sk_enroll_response {
  42         uint8_t *public_key;
  43         size_t public_key_len;
  44         uint8_t *key_handle;
  45         size_t key_handle_len;
  46         uint8_t *signature;
  47         size_t signature_len;
  48         uint8_t *attestation_cert;
  49         size_t attestation_cert_len;
  50         uint8_t *authdata;
  51         size_t authdata_len;
  52 };
  53
  54 struct sk_sign_response {
  55         uint8_t flags;
  56         uint32_t counter;
  57         uint8_t *sig_r;
  58         size_t sig_r_len;
  59         uint8_t *sig_s;
  60         size_t sig_s_len;
  61 };
  62
  63 struct sk_resident_key {
  64         uint32_t alg;
  65         size_t slot;
  66         char *application;
  67         struct sk_enroll_response key;
  68         uint8_t flags;
  69 };
  70
  71 struct sk_option {
  72         char *name;
  73         char *value;
  74         uint8_t required;
  75 };
  76
  77 #define SSH_SK_VERSION_MAJOR            0x00070000 /* current API version */
  78 #define SSH_SK_VERSION_MAJOR_MASK       0xffff0000
  79
  80 /* Return the version of the middleware API */
  81 uint32_t sk_api_version(void);
  82
  83 /* Enroll a U2F key (private key generation) */
  84 int sk_enroll(uint32_t alg, const uint8_t *challenge, size_t challenge_len,
  85     const char *application, uint8_t flags, const char *pin,
  86     struct sk_option **options, struct sk_enroll_response **enroll_response);
  87
  88 /* Sign a challenge */
  89 int sk_sign(uint32_t alg, const uint8_t *data, size_t data_len,
  90     const char *application, const uint8_t *key_handle, size_t key_handle_len,
  91     uint8_t flags, const char *pin, struct sk_option **options,
  92     struct sk_sign_response **sign_response);
  93
  94 /* Enumerate all resident keys */
  95 int sk_load_resident_keys(const char *pin, struct sk_option **options,
  96     struct sk_resident_key ***rks, size_t *nrks);
  97
  98 #endif /* _SK_API_H */