]>
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 | ||
96 | ||
97 | /** | |
98 | * This struct represents a single username/password combination | |
99 | * along with any associated context. All string fields should be | |
100 | * heap-allocated (or NULL if they are not known or not applicable). | |
101 | * The meaning of the individual context fields is the same as | |
102 | * their counterparts in the helper protocol. | |
103 | * | |
104 | * This struct should always be initialized with `CREDENTIAL_INIT` or | |
105 | * `credential_init`. | |
106 | */ | |
abca927d | 107 | struct credential { |
f3b90556 HW |
108 | |
109 | /** | |
110 | * A `string_list` of helpers. Each string specifies an external | |
111 | * helper which will be run, in order, to either acquire or store | |
112 | * credentials. This list is filled-in by the API functions | |
113 | * according to the corresponding configuration variables before | |
114 | * consulting helpers, so there usually is no need for a caller to | |
115 | * modify the helpers field at all. | |
116 | */ | |
abca927d | 117 | struct string_list helpers; |
f3b90556 | 118 | |
6b8dda9a MJC |
119 | /** |
120 | * A `strvec` of WWW-Authenticate header values. Each string | |
121 | * is the value of a WWW-Authenticate header in an HTTP response, | |
122 | * in the order they were received in the response. | |
123 | */ | |
124 | struct strvec wwwauth_headers; | |
125 | ||
126 | /** | |
127 | * Internal use only. Keeps track of if we previously matched against a | |
128 | * WWW-Authenticate header line in order to re-fold future continuation | |
129 | * lines into one value. | |
130 | */ | |
131 | unsigned header_is_last_match:1; | |
132 | ||
11825072 | 133 | unsigned approved:1, |
a78fbb4f | 134 | configured:1, |
59b38652 | 135 | quit:1, |
82eb2498 | 136 | use_http_path:1, |
137 | username_from_proto:1; | |
abca927d JK |
138 | |
139 | char *username; | |
140 | char *password; | |
141 | char *protocol; | |
142 | char *host; | |
143 | char *path; | |
a5c76569 | 144 | char *oauth_refresh_token; |
d208bfdf | 145 | timestamp_t password_expiry_utc; |
abca927d JK |
146 | }; |
147 | ||
3d97ea47 ÆAB |
148 | #define CREDENTIAL_INIT { \ |
149 | .helpers = STRING_LIST_INIT_DUP, \ | |
d208bfdf | 150 | .password_expiry_utc = TIME_MAX, \ |
6b8dda9a | 151 | .wwwauth_headers = STRVEC_INIT, \ |
3d97ea47 | 152 | } |
abca927d | 153 | |
f3b90556 | 154 | /* Initialize a credential structure, setting all fields to empty. */ |
abca927d | 155 | void credential_init(struct credential *); |
f3b90556 HW |
156 | |
157 | /** | |
158 | * Free any resources associated with the credential structure, returning | |
159 | * it to a pristine initialized state. | |
160 | */ | |
abca927d JK |
161 | void credential_clear(struct credential *); |
162 | ||
f3b90556 HW |
163 | /** |
164 | * Instruct the credential subsystem to fill the username and | |
165 | * password fields of the passed credential struct by first | |
166 | * consulting helpers, then asking the user. After this function | |
167 | * returns, the username and password fields of the credential are | |
168 | * guaranteed to be non-NULL. If an error occurs, the function will | |
169 | * die(). | |
170 | */ | |
abca927d | 171 | void credential_fill(struct credential *); |
f3b90556 HW |
172 | |
173 | /** | |
174 | * Inform the credential subsystem that the provided credentials | |
175 | * were successfully used for authentication. This will cause the | |
176 | * credential subsystem to notify any helpers of the approval, so | |
177 | * that they may store the result to be used again. Any errors | |
178 | * from helpers are ignored. | |
179 | */ | |
abca927d | 180 | void credential_approve(struct credential *); |
f3b90556 HW |
181 | |
182 | /** | |
183 | * Inform the credential subsystem that the provided credentials | |
184 | * have been rejected. This will cause the credential subsystem to | |
185 | * notify any helpers of the rejection (which allows them, for | |
186 | * example, to purge the invalid credentials from storage). It | |
187 | * will also free() the username and password fields of the | |
188 | * credential and set them to NULL (readying the credential for | |
189 | * another call to `credential_fill`). Any errors from helpers are | |
190 | * ignored. | |
191 | */ | |
abca927d JK |
192 | void credential_reject(struct credential *); |
193 | ||
194 | int credential_read(struct credential *, FILE *); | |
2d6dc182 | 195 | void credential_write(const struct credential *, FILE *); |
f3b90556 | 196 | |
c716fe4b JK |
197 | /* |
198 | * Parse a url into a credential struct, replacing any existing contents. | |
199 | * | |
67b0a249 | 200 | * If the url can't be parsed (e.g., a missing "proto://" component), the |
7f535838 CMAB |
201 | * resulting credential will be empty and the function will return an |
202 | * error (even in the "gently" form). | |
c716fe4b JK |
203 | * |
204 | * If we encounter a component which cannot be represented as a credential | |
205 | * value (e.g., because it contains a newline), the "gently" form will return | |
206 | * an error but leave the broken state in the credential object for further | |
207 | * examination. The non-gentle form will issue a warning to stderr and return | |
208 | * an empty credential. | |
209 | */ | |
d3e847c1 | 210 | void credential_from_url(struct credential *, const char *url); |
c716fe4b | 211 | int credential_from_url_gently(struct credential *, const char *url, int quiet); |
f3b90556 | 212 | |
bb987657 | 213 | int credential_match(const struct credential *want, |
aeb21ce2 | 214 | const struct credential *have, int match_password); |
abca927d JK |
215 | |
216 | #endif /* CREDENTIAL_H */ |