1/* $OpenBSD: sk-api.h,v 1.15 2022/07/20 03:29:14 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#include <stdint.h> 23 24/* Flags */ 25#define SSH_SK_USER_PRESENCE_REQD 0x01 26#define SSH_SK_USER_VERIFICATION_REQD 0x04 27#define SSH_SK_FORCE_OPERATION 0x10 28#define SSH_SK_RESIDENT_KEY 0x20 29 30/* Algs */ 31#define SSH_SK_ECDSA 0x00 32#define SSH_SK_ED25519 0x01 33 34/* Error codes */ 35#define SSH_SK_ERR_GENERAL -1 36#define SSH_SK_ERR_UNSUPPORTED -2 37#define SSH_SK_ERR_PIN_REQUIRED -3 38#define SSH_SK_ERR_DEVICE_NOT_FOUND -4 39#define SSH_SK_ERR_CREDENTIAL_EXISTS -5 40 41struct sk_enroll_response { 42 uint8_t flags; 43 uint8_t *public_key; 44 size_t public_key_len; 45 uint8_t *key_handle; 46 size_t key_handle_len; 47 uint8_t *signature; 48 size_t signature_len; 49 uint8_t *attestation_cert; 50 size_t attestation_cert_len; 51 uint8_t *authdata; 52 size_t authdata_len; 53}; 54 55struct sk_sign_response { 56 uint8_t flags; 57 uint32_t counter; 58 uint8_t *sig_r; 59 size_t sig_r_len; 60 uint8_t *sig_s; 61 size_t sig_s_len; 62}; 63 64struct sk_resident_key { 65 uint32_t alg; 66 size_t slot; 67 char *application; 68 struct sk_enroll_response key; 69 uint8_t flags; 70 uint8_t *user_id; 71 size_t user_id_len; 72}; 73 74struct sk_option { 75 char *name; 76 char *value; 77 uint8_t required; 78}; 79 80#define SSH_SK_VERSION_MAJOR 0x000a0000 /* current API version */ 81#define SSH_SK_VERSION_MAJOR_MASK 0xffff0000 82 83/* Return the version of the middleware API */ 84uint32_t sk_api_version(void); 85 86/* Enroll a U2F key (private key generation) */ 87int sk_enroll(uint32_t alg, const uint8_t *challenge, size_t challenge_len, 88 const char *application, uint8_t flags, const char *pin, 89 struct sk_option **options, struct sk_enroll_response **enroll_response); 90 91/* Sign a challenge */ 92int sk_sign(uint32_t alg, const uint8_t *data, size_t data_len, 93 const char *application, const uint8_t *key_handle, size_t key_handle_len, 94 uint8_t flags, const char *pin, struct sk_option **options, 95 struct sk_sign_response **sign_response); 96 97/* Enumerate all resident keys */ 98int sk_load_resident_keys(const char *pin, struct sk_option **options, 99 struct sk_resident_key ***rks, size_t *nrks); 100 101#endif /* _SK_API_H */ 102