xref: /openbsd/usr.bin/ssh/sk-api.h (revision 4fe47877)
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 
41 struct 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 
55 struct 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 
64 struct 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 
74 struct 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 */
84 uint32_t sk_api_version(void);
85 
86 /* Enroll a U2F key (private key generation) */
87 int 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 */
92 int 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 */
98 int 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