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