]>
Commit | Line | Data |
---|---|---|
abca927d JK |
1 | #ifndef CREDENTIAL_H |
2 | #define CREDENTIAL_H | |
3 | ||
4 | #include "string-list.h" | |
6b8dda9a | 5 | #include "strvec.h" |
abca927d | 6 | |
f3b90556 HW |
7 | /** |
8 | * The credentials API provides an abstracted way of gathering username and | |
9 | * password credentials from the user. | |
10 | * | |
11 | * Typical setup | |
12 | * ------------- | |
13 | * | |
14 | * ------------ | |
15 | * +-----------------------+ | |
16 | * | Git code (C) |--- to server requiring ---> | |
17 | * | | authentication | |
18 | * |.......................| | |
19 | * | C credential API |--- prompt ---> User | |
20 | * +-----------------------+ | |
21 | * ^ | | |
22 | * | pipe | | |
23 | * | v | |
24 | * +-----------------------+ | |
25 | * | Git credential helper | | |
26 | * +-----------------------+ | |
27 | * ------------ | |
28 | * | |
29 | * The Git code (typically a remote-helper) will call the C API to obtain | |
30 | * credential data like a login/password pair (credential_fill). The | |
31 | * API will itself call a remote helper (e.g. "git credential-cache" or | |
32 | * "git credential-store") that may retrieve credential data from a | |
33 | * store. If the credential helper cannot find the information, the C API | |
34 | * will prompt the user. Then, the caller of the API takes care of | |
35 | * contacting the server, and does the actual authentication. | |
36 | * | |
37 | * C API | |
38 | * ----- | |
39 | * | |
40 | * The credential C API is meant to be called by Git code which needs to | |
41 | * acquire or store a credential. It is centered around an object | |
42 | * representing a single credential and provides three basic operations: | |
43 | * fill (acquire credentials by calling helpers and/or prompting the user), | |
44 | * approve (mark a credential as successfully used so that it can be stored | |
45 | * for later use), and reject (mark a credential as unsuccessful so that it | |
46 | * can be erased from any persistent storage). | |
47 | * | |
48 | * Example | |
49 | * ~~~~~~~ | |
50 | * | |
51 | * The example below shows how the functions of the credential API could be | |
52 | * used to login to a fictitious "foo" service on a remote host: | |
53 | * | |
54 | * ----------------------------------------------------------------------- | |
55 | * int foo_login(struct foo_connection *f) | |
56 | * { | |
57 | * int status; | |
58 | * // Create a credential with some context; we don't yet know the | |
59 | * // username or password. | |
60 | * | |
61 | * struct credential c = CREDENTIAL_INIT; | |
62 | * c.protocol = xstrdup("foo"); | |
63 | * c.host = xstrdup(f->hostname); | |
64 | * | |
65 | * // Fill in the username and password fields by contacting | |
66 | * // helpers and/or asking the user. The function will die if it | |
67 | * // fails. | |
68 | * credential_fill(&c); | |
69 | * | |
70 | * // Otherwise, we have a username and password. Try to use it. | |
71 | * | |
72 | * status = send_foo_login(f, c.username, c.password); | |
73 | * switch (status) { | |
74 | * case FOO_OK: | |
75 | * // It worked. Store the credential for later use. | |
76 | * credential_accept(&c); | |
77 | * break; | |
78 | * case FOO_BAD_LOGIN: | |
79 | * // Erase the credential from storage so we don't try it again. | |
80 | * credential_reject(&c); | |
81 | * break; | |
82 | * default: | |
83 | * // Some other error occurred. We don't know if the | |
84 | * // credential is good or bad, so report nothing to the | |
85 | * // credential subsystem. | |
86 | * } | |
87 | * | |
88 | * // Free any associated resources. | |
89 | * credential_clear(&c); | |
90 | * | |
91 | * return status; | |
92 | * } | |
93 | * ----------------------------------------------------------------------- | |
f3b90556 HW |
94 | */ |
95 | ||
ca9ccbf6 | 96 | /* |
97 | * These values define the kind of operation we're performing and the | |
98 | * capabilities at each stage. The first is either an external request (via git | |
99 | * credential fill) or an internal request (e.g., via the HTTP) code. The | |
100 | * second is the call to the credential helper, and the third is the response | |
101 | * we're providing. | |
102 | * | |
103 | * At each stage, we will emit the capability only if the previous stage | |
104 | * supported it. | |
105 | */ | |
106 | enum credential_op_type { | |
107 | CREDENTIAL_OP_INITIAL = 1, | |
108 | CREDENTIAL_OP_HELPER = 2, | |
109 | CREDENTIAL_OP_RESPONSE = 3, | |
110 | }; | |
111 | ||
112 | struct credential_capability { | |
113 | unsigned request_initial:1, | |
114 | request_helper:1, | |
115 | response:1; | |
116 | }; | |
f3b90556 HW |
117 | |
118 | /** | |
119 | * This struct represents a single username/password combination | |
120 | * along with any associated context. All string fields should be | |
121 | * heap-allocated (or NULL if they are not known or not applicable). | |
122 | * The meaning of the individual context fields is the same as | |
123 | * their counterparts in the helper protocol. | |
124 | * | |
125 | * This struct should always be initialized with `CREDENTIAL_INIT` or | |
126 | * `credential_init`. | |
127 | */ | |
abca927d | 128 | struct credential { |
f3b90556 HW |
129 | |
130 | /** | |
131 | * A `string_list` of helpers. Each string specifies an external | |
132 | * helper which will be run, in order, to either acquire or store | |
133 | * credentials. This list is filled-in by the API functions | |
134 | * according to the corresponding configuration variables before | |
135 | * consulting helpers, so there usually is no need for a caller to | |
136 | * modify the helpers field at all. | |
137 | */ | |
abca927d | 138 | struct string_list helpers; |
f3b90556 | 139 | |
6b8dda9a MJC |
140 | /** |
141 | * A `strvec` of WWW-Authenticate header values. Each string | |
142 | * is the value of a WWW-Authenticate header in an HTTP response, | |
143 | * in the order they were received in the response. | |
144 | */ | |
145 | struct strvec wwwauth_headers; | |
146 | ||
147 | /** | |
148 | * Internal use only. Keeps track of if we previously matched against a | |
149 | * WWW-Authenticate header line in order to re-fold future continuation | |
150 | * lines into one value. | |
151 | */ | |
152 | unsigned header_is_last_match:1; | |
153 | ||
11825072 | 154 | unsigned approved:1, |
a78fbb4f | 155 | configured:1, |
59b38652 | 156 | quit:1, |
82eb2498 | 157 | use_http_path:1, |
158 | username_from_proto:1; | |
abca927d | 159 | |
ca9ccbf6 | 160 | struct credential_capability capa_authtype; |
161 | ||
abca927d JK |
162 | char *username; |
163 | char *password; | |
6a6d6fb1 | 164 | char *credential; |
abca927d JK |
165 | char *protocol; |
166 | char *host; | |
167 | char *path; | |
a5c76569 | 168 | char *oauth_refresh_token; |
d208bfdf | 169 | timestamp_t password_expiry_utc; |
7046f1d5 | 170 | |
171 | /** | |
172 | * The authorization scheme to use. If this is NULL, libcurl is free to | |
173 | * negotiate any scheme it likes. | |
174 | */ | |
175 | char *authtype; | |
abca927d JK |
176 | }; |
177 | ||
3d97ea47 ÆAB |
178 | #define CREDENTIAL_INIT { \ |
179 | .helpers = STRING_LIST_INIT_DUP, \ | |
d208bfdf | 180 | .password_expiry_utc = TIME_MAX, \ |
6b8dda9a | 181 | .wwwauth_headers = STRVEC_INIT, \ |
3d97ea47 | 182 | } |
abca927d | 183 | |
f3b90556 | 184 | /* Initialize a credential structure, setting all fields to empty. */ |
abca927d | 185 | void credential_init(struct credential *); |
f3b90556 HW |
186 | |
187 | /** | |
188 | * Free any resources associated with the credential structure, returning | |
189 | * it to a pristine initialized state. | |
190 | */ | |
abca927d JK |
191 | void credential_clear(struct credential *); |
192 | ||
f3b90556 HW |
193 | /** |
194 | * Instruct the credential subsystem to fill the username and | |
195 | * password fields of the passed credential struct by first | |
196 | * consulting helpers, then asking the user. After this function | |
197 | * returns, the username and password fields of the credential are | |
198 | * guaranteed to be non-NULL. If an error occurs, the function will | |
199 | * die(). | |
ca9ccbf6 | 200 | * |
201 | * If all_capabilities is set, this is an internal user that is prepared | |
202 | * to deal with all known capabilities, and we should advertise that fact. | |
f3b90556 | 203 | */ |
ca9ccbf6 | 204 | void credential_fill(struct credential *, int all_capabilities); |
f3b90556 HW |
205 | |
206 | /** | |
207 | * Inform the credential subsystem that the provided credentials | |
208 | * were successfully used for authentication. This will cause the | |
209 | * credential subsystem to notify any helpers of the approval, so | |
210 | * that they may store the result to be used again. Any errors | |
211 | * from helpers are ignored. | |
212 | */ | |
abca927d | 213 | void credential_approve(struct credential *); |
f3b90556 HW |
214 | |
215 | /** | |
216 | * Inform the credential subsystem that the provided credentials | |
217 | * have been rejected. This will cause the credential subsystem to | |
218 | * notify any helpers of the rejection (which allows them, for | |
219 | * example, to purge the invalid credentials from storage). It | |
220 | * will also free() the username and password fields of the | |
221 | * credential and set them to NULL (readying the credential for | |
222 | * another call to `credential_fill`). Any errors from helpers are | |
223 | * ignored. | |
224 | */ | |
abca927d JK |
225 | void credential_reject(struct credential *); |
226 | ||
ca9ccbf6 | 227 | /** |
228 | * Enable all of the supported credential flags in this credential. | |
229 | */ | |
230 | void credential_set_all_capabilities(struct credential *c, | |
231 | enum credential_op_type op_type); | |
232 | ||
233 | int credential_read(struct credential *, FILE *, | |
234 | enum credential_op_type); | |
235 | void credential_write(const struct credential *, FILE *, | |
236 | enum credential_op_type); | |
f3b90556 | 237 | |
c716fe4b JK |
238 | /* |
239 | * Parse a url into a credential struct, replacing any existing contents. | |
240 | * | |
67b0a249 | 241 | * If the url can't be parsed (e.g., a missing "proto://" component), the |
7f535838 CMAB |
242 | * resulting credential will be empty and the function will return an |
243 | * error (even in the "gently" form). | |
c716fe4b JK |
244 | * |
245 | * If we encounter a component which cannot be represented as a credential | |
246 | * value (e.g., because it contains a newline), the "gently" form will return | |
247 | * an error but leave the broken state in the credential object for further | |
248 | * examination. The non-gentle form will issue a warning to stderr and return | |
249 | * an empty credential. | |
250 | */ | |
d3e847c1 | 251 | void credential_from_url(struct credential *, const char *url); |
c716fe4b | 252 | int credential_from_url_gently(struct credential *, const char *url, int quiet); |
f3b90556 | 253 | |
bb987657 | 254 | int credential_match(const struct credential *want, |
aeb21ce2 | 255 | const struct credential *have, int match_password); |
abca927d JK |
256 | |
257 | #endif /* CREDENTIAL_H */ |