xref: /openssh-portable/sk-api.h (revision 59d2de95)
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 */
96