1 #pragma once
2 
3 /*
4  * Copyright (C) 2019 The Android Open Source Project
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  *      http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 #include <stdbool.h>
20 #include <stdint.h>
21 #include <sys/cdefs.h>
22 #include <sys/types.h>
23 
24 #if !defined(__INTRODUCED_IN)
25 #define __INTRODUCED_IN(__api_level) /* nothing */
26 #endif
27 
28 __BEGIN_DECLS
29 
30 // The transport type of the device connection.
31 enum AdbTransportType : int32_t {
32     kAdbTransportTypeUsb = 0,
33     kAdbTransportTypeWifi,
34 };
35 static_assert(sizeof(AdbTransportType) == sizeof(int32_t), "Unexpected AdbTransportType size");
36 
37 struct AdbdAuthCallbacks {
38     uint32_t version;
39 };
40 
41 struct AdbdAuthCallbacksV1 : AdbdAuthCallbacks {
42     // Callback for a successful user authorization.
43     void (*key_authorized)(void* opaque, uint64_t id);
44     // The framework removed the key from the keystore. This callback notifies
45     // adbd so it can take the appropriate actions (e.g. disconnect all devices
46     // using that key).
47     void (*key_removed)(const char* public_key, size_t length);
48 };
49 
50 struct AdbdAuthContext;
51 typedef struct AdbdAuthContext AdbdAuthContext;
52 
53 /**
54  * Creates a new AdbdAuthContext.
55  *
56  * @param callbacks a set of user-provided callbacks used internally (see
57  * #AdbdAuthCallbacksV1
58  * @return a new AdbdAuthContext instance. Caller is responsible for destroying
59  * the context with #adbd_auth_delete.
60  */
61 AdbdAuthContext* adbd_auth_new(AdbdAuthCallbacks* callbacks) __INTRODUCED_IN(30);
62 
63 /**
64  * Destroys the AdbdAuthContext.
65  *
66  * @param ctx the AdbdAuthContext to destroy.
67  */
68 void adbd_auth_delete(AdbdAuthContext* ctx) __INTRODUCED_IN(30);
69 
70 /**
71  * Starts the AdbdAuthContext.
72  *
73  * The caller may want to run this on a different thread, as this
74  * runs indefinitely.
75  *
76  * @param ctx the AdbdAuthContext
77  */
78 void adbd_auth_run(AdbdAuthContext* ctx) __INTRODUCED_IN(30);
79 
80 /**
81  * Iterate through the list of authorized public keys.
82  *
83  * @param ctx the AdbdAuthContext
84  * @param callback a callback which will get called for every known adb public
85  * key in its keystore. To stop iteration of the keys, return false in the
86  * callback. Otherwise, return true to continue the iteration.
87  * @param opaque an opaque userdata argument
88  */
89 void adbd_auth_get_public_keys(AdbdAuthContext* ctx,
90                                bool (*callback)(void* opaque, const char* public_key, size_t len),
91                                void* opaque) __INTRODUCED_IN(30);
92 
93 /**
94  * Let system_server know that a key has been successfully used for authentication.
95  *
96  * @param ctx the AdbdAuthContext
97  * @param public_key the RSA key that was authorized using the AUTH protocol
98  * @param len the length of the public_key argument
99  * @return an id corresponding to the new connection
100  */
101 uint64_t adbd_auth_notify_auth(AdbdAuthContext* ctx,
102                                const char* public_key,
103                                size_t len) __INTRODUCED_IN(30);
104 
105 /**
106  * Let system_server know that an AUTH connection has been closed.
107  *
108  * @param ctx the AdbdAuthContext
109  * @param id the id of the disconnected device
110  */
111 void adbd_auth_notify_disconnect(AdbdAuthContext* ctx,
112                                  uint64_t id) __INTRODUCED_IN(30);
113 
114 /**
115  * Prompt the user to authorize a public key.
116  *
117  * When this happens, a callback will be run on the auth thread with the result.
118  *
119  * @param ctx the AdbdAuthContext
120  * @param public_key the RSA public key to prompt user with
121  * @param len the length of the public_key argument
122  * @param arg an opaque userdata argument
123  */
124 void adbd_auth_prompt_user(AdbdAuthContext* ctx, const char* public_key, size_t len, void* opaque)
125         __INTRODUCED_IN(30);
126 
127 /**
128  * Prompt the user to authorize a public key.
129  *
130  * When this happens, a callback will be run on the auth thread with the result.
131  *
132  * @param ctx the AdbdAuthContext
133  * @param public_key the RSA public key to prompt user with
134  * @param len the length of the public_key argument
135  * @param arg an opaque userdata argument
136  * @return a unique id which will be returned via callback
137  */
138 __attribute__((weak)) uint64_t adbd_auth_prompt_user_with_id(AdbdAuthContext* ctx,
139                                                              const char* public_key, size_t len,
140                                                              void* opaque) __INTRODUCED_IN(30);
141 
142 /**
143  * Let system_server know that a TLS device has connected.
144  *
145  * @param ctx the AdbdAuthContext
146  * @param type the transport type of the connection (see #AdbTransportType)
147  * @param public_key the RSA public key used to establish the connection
148  * @param len the length of the public_key argument
149  * @return an id corresponding to the new connection
150  */
151 uint64_t adbd_auth_tls_device_connected(AdbdAuthContext* ctx,
152                                         AdbTransportType type,
153                                         const char* public_key,
154                                         size_t len) __INTRODUCED_IN(30);
155 
156 /**
157  * Let system_server know that a TLS device has disconnected.
158  *
159  * @param ctx the AdbdAuthContext
160  * @param type the transport type of the connection (see #AdbTransportType)
161  * @param the id of the disconnected device (see #adbd_tls_device_connected)
162  */
163 void adbd_auth_tls_device_disconnected(AdbdAuthContext* ctx,
164                                        AdbTransportType type,
165                                        uint64_t id) __INTRODUCED_IN(30);
166 
167 /**
168  * Returns the max #AdbdAuthCallbacks version.
169  *
170  * The version starts at 1, with version 1 corresponding to the
171  * #AdbdAuthCallbacksV1 struct.
172  *
173  * @return the max #AdbdAuthCallbacks version.
174  */
175 uint32_t adbd_auth_get_max_version(void) __INTRODUCED_IN(30);
176 
177 enum AdbdAuthFeature : int32_t {
178 };
179 
180 /**
181  * Checks if a feature is supported by the framework. See #AdbdAuthFeature.
182  *
183  * @param feature the feature to check for support
184  * @return true if the feature is supported
185  */
186 bool adbd_auth_supports_feature(AdbdAuthFeature feature);
187 
188 __END_DECLS
189