crypto/openssh/sk-api.h

   1 /* $OpenBSD: sk-api.h,v 1.9 2020/04/28 04:02:29 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 };
  51
  52 struct sk_sign_response {
  53         uint8_t flags;
  54         uint32_t counter;
  55         uint8_t *sig_r;
  56         size_t sig_r_len;
  57         uint8_t *sig_s;
  58         size_t sig_s_len;
  59 };
  60
  61 struct sk_resident_key {
  62         uint32_t alg;
  63         size_t slot;
  64         char *application;
  65         struct sk_enroll_response key;
  66 };
  67
  68 struct sk_option {
  69         char *name;
  70         char *value;
  71         uint8_t required;
  72 };
  73
  74 #define SSH_SK_VERSION_MAJOR            0x00050000 /* current API version */
  75 #define SSH_SK_VERSION_MAJOR_MASK       0xffff0000
  76
  77 /* Return the version of the middleware API */
  78 uint32_t sk_api_version(void);
  79
  80 /* Enroll a U2F key (private key generation) */
  81 int sk_enroll(uint32_t alg, const uint8_t *challenge, size_t challenge_len,
  82     const char *application, uint8_t flags, const char *pin,
  83     struct sk_option **options, struct sk_enroll_response **enroll_response);
  84
  85 /* Sign a challenge */
  86 int sk_sign(uint32_t alg, const uint8_t *message, size_t message_len,
  87     const char *application, const uint8_t *key_handle, size_t key_handle_len,
  88     uint8_t flags, const char *pin, struct sk_option **options,
  89     struct sk_sign_response **sign_response);
  90
  91 /* Enumerate all resident keys */
  92 int sk_load_resident_keys(const char *pin, struct sk_option **options,
  93     struct sk_resident_key ***rks, size_t *nrks);
  94
  95 #endif /* _SK_API_H */