setup: unset ref storage when reinitializing repository version
[git.git] / credential.h
blobaf8c287ff24788e9b10079457371987b4e6ff365
1 #ifndef CREDENTIAL_H
2 #define CREDENTIAL_H
4 #include "string-list.h"
5 #include "strvec.h"
7 /**
8 * The credentials API provides an abstracted way of gathering username and
9 * password credentials from the user.
11 * Typical setup
12 * -------------
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 * ------------
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.
37 * C API
38 * -----
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).
48 * Example
49 * ~~~~~~~
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:
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.
61 * struct credential c = CREDENTIAL_INIT;
62 * c.protocol = xstrdup("foo");
63 * c.host = xstrdup(f->hostname);
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);
70 * // Otherwise, we have a username and password. Try to use it.
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 * }
88 * // Free any associated resources.
89 * credential_clear(&c);
91 * return status;
92 * }
93 * -----------------------------------------------------------------------
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.
103 * At each stage, we will emit the capability only if the previous stage
104 * supported it.
106 enum credential_op_type {
107 CREDENTIAL_OP_INITIAL = 1,
108 CREDENTIAL_OP_HELPER = 2,
109 CREDENTIAL_OP_RESPONSE = 3,
112 struct credential_capability {
113 unsigned request_initial:1,
114 request_helper:1,
115 response:1;
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.
125 * This struct should always be initialized with `CREDENTIAL_INIT` or
126 * `credential_init`.
128 struct credential {
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.
138 struct string_list helpers;
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.
145 struct strvec wwwauth_headers;
148 * A `strvec` of state headers received from credential helpers.
150 struct strvec state_headers;
153 * A `strvec` of state headers to send to credential helpers.
155 struct strvec state_headers_to_send;
158 * Internal use only. Keeps track of if we previously matched against a
159 * WWW-Authenticate header line in order to re-fold future continuation
160 * lines into one value.
162 unsigned header_is_last_match:1;
164 unsigned approved:1,
165 ephemeral:1,
166 configured:1,
167 multistage: 1,
168 quit:1,
169 use_http_path:1,
170 username_from_proto:1;
172 struct credential_capability capa_authtype;
173 struct credential_capability capa_state;
175 char *username;
176 char *password;
177 char *credential;
178 char *protocol;
179 char *host;
180 char *path;
181 char *oauth_refresh_token;
182 timestamp_t password_expiry_utc;
185 * The authorization scheme to use. If this is NULL, libcurl is free to
186 * negotiate any scheme it likes.
188 char *authtype;
191 #define CREDENTIAL_INIT { \
192 .helpers = STRING_LIST_INIT_DUP, \
193 .password_expiry_utc = TIME_MAX, \
194 .wwwauth_headers = STRVEC_INIT, \
195 .state_headers = STRVEC_INIT, \
196 .state_headers_to_send = STRVEC_INIT, \
199 /* Initialize a credential structure, setting all fields to empty. */
200 void credential_init(struct credential *);
203 * Free any resources associated with the credential structure, returning
204 * it to a pristine initialized state.
206 void credential_clear(struct credential *);
209 * Instruct the credential subsystem to fill the username and
210 * password fields of the passed credential struct by first
211 * consulting helpers, then asking the user. After this function
212 * returns, the username and password fields of the credential are
213 * guaranteed to be non-NULL. If an error occurs, the function will
214 * die().
216 * If all_capabilities is set, this is an internal user that is prepared
217 * to deal with all known capabilities, and we should advertise that fact.
219 void credential_fill(struct credential *, int all_capabilities);
222 * Inform the credential subsystem that the provided credentials
223 * were successfully used for authentication. This will cause the
224 * credential subsystem to notify any helpers of the approval, so
225 * that they may store the result to be used again. Any errors
226 * from helpers are ignored.
228 void credential_approve(struct credential *);
231 * Inform the credential subsystem that the provided credentials
232 * have been rejected. This will cause the credential subsystem to
233 * notify any helpers of the rejection (which allows them, for
234 * example, to purge the invalid credentials from storage). It
235 * will also free() the username and password fields of the
236 * credential and set them to NULL (readying the credential for
237 * another call to `credential_fill`). Any errors from helpers are
238 * ignored.
240 void credential_reject(struct credential *);
243 * Enable all of the supported credential flags in this credential.
245 void credential_set_all_capabilities(struct credential *c,
246 enum credential_op_type op_type);
249 * Clear the secrets in this credential, but leave other data intact.
251 * This is useful for resetting credentials in preparation for a subsequent
252 * stage of filling.
254 void credential_clear_secrets(struct credential *c);
257 * Print a list of supported capabilities and version numbers to standard
258 * output.
260 void credential_announce_capabilities(struct credential *c, FILE *fp);
263 * Prepares the credential for the next iteration of the helper protocol by
264 * updating the state headers to send with the ones read by the last iteration
265 * of the protocol.
267 * Except for internal callers, this should be called exactly once between
268 * reading credentials with `credential_fill` and writing them.
270 void credential_next_state(struct credential *c);
273 * Return true if the capability is enabled for an operation of op_type.
275 int credential_has_capability(const struct credential_capability *capa,
276 enum credential_op_type op_type);
278 int credential_read(struct credential *, FILE *,
279 enum credential_op_type);
280 void credential_write(const struct credential *, FILE *,
281 enum credential_op_type);
284 * Parse a url into a credential struct, replacing any existing contents.
286 * If the url can't be parsed (e.g., a missing "proto://" component), the
287 * resulting credential will be empty and the function will return an
288 * error (even in the "gently" form).
290 * If we encounter a component which cannot be represented as a credential
291 * value (e.g., because it contains a newline), the "gently" form will return
292 * an error but leave the broken state in the credential object for further
293 * examination. The non-gentle form will issue a warning to stderr and return
294 * an empty credential.
296 void credential_from_url(struct credential *, const char *url);
297 int credential_from_url_gently(struct credential *, const char *url, int quiet);
299 int credential_match(const struct credential *want,
300 const struct credential *have, int match_password);
302 #endif /* CREDENTIAL_H */