blob: acc41adf5481a21148a6b4797f9a8267feb5d8b6 [file] [log] [blame]
Jeff Kingabca9272011-12-10 05:31:11 -05001#ifndef CREDENTIAL_H
2#define CREDENTIAL_H
3
4#include "string-list.h"
Matthew John Cheetham6b8dda92023-02-27 17:20:19 +00005#include "strvec.h"
Jeff Kingabca9272011-12-10 05:31:11 -05006
Heba Walyf3b90552019-11-17 21:04:53 +00007/**
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 * -----------------------------------------------------------------------
Heba Walyf3b90552019-11-17 21:04:53 +000094 */
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 */
Jeff Kingabca9272011-12-10 05:31:11 -0500107struct credential {
Heba Walyf3b90552019-11-17 21:04:53 +0000108
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 */
Jeff Kingabca9272011-12-10 05:31:11 -0500117 struct string_list helpers;
Heba Walyf3b90552019-11-17 21:04:53 +0000118
Matthew John Cheetham6b8dda92023-02-27 17:20:19 +0000119 /**
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
Jeff King11825072011-12-10 05:31:24 -0500133 unsigned approved:1,
Jeff Kinga78fbb42011-12-10 05:31:34 -0500134 configured:1,
Jeff King59b38652014-12-03 22:46:48 -0500135 quit:1,
brian m. carlson82eb2492020-02-20 02:24:12 +0000136 use_http_path:1,
137 username_from_proto:1;
Jeff Kingabca9272011-12-10 05:31:11 -0500138
139 char *username;
140 char *password;
141 char *protocol;
142 char *host;
143 char *path;
M Hickforda5c76562023-04-21 09:47:59 +0000144 char *oauth_refresh_token;
M Hickfordd208bfd2023-02-18 06:32:57 +0000145 timestamp_t password_expiry_utc;
Jeff Kingabca9272011-12-10 05:31:11 -0500146};
147
Ævar Arnfjörð Bjarmason3d97ea42021-07-01 12:51:25 +0200148#define CREDENTIAL_INIT { \
149 .helpers = STRING_LIST_INIT_DUP, \
M Hickfordd208bfd2023-02-18 06:32:57 +0000150 .password_expiry_utc = TIME_MAX, \
Matthew John Cheetham6b8dda92023-02-27 17:20:19 +0000151 .wwwauth_headers = STRVEC_INIT, \
Ævar Arnfjörð Bjarmason3d97ea42021-07-01 12:51:25 +0200152}
Jeff Kingabca9272011-12-10 05:31:11 -0500153
Heba Walyf3b90552019-11-17 21:04:53 +0000154/* Initialize a credential structure, setting all fields to empty. */
Jeff Kingabca9272011-12-10 05:31:11 -0500155void credential_init(struct credential *);
Heba Walyf3b90552019-11-17 21:04:53 +0000156
157/**
158 * Free any resources associated with the credential structure, returning
159 * it to a pristine initialized state.
160 */
Jeff Kingabca9272011-12-10 05:31:11 -0500161void credential_clear(struct credential *);
162
Heba Walyf3b90552019-11-17 21:04:53 +0000163/**
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 */
Jeff Kingabca9272011-12-10 05:31:11 -0500171void credential_fill(struct credential *);
Heba Walyf3b90552019-11-17 21:04:53 +0000172
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 */
Jeff Kingabca9272011-12-10 05:31:11 -0500180void credential_approve(struct credential *);
Heba Walyf3b90552019-11-17 21:04:53 +0000181
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 */
Jeff Kingabca9272011-12-10 05:31:11 -0500192void credential_reject(struct credential *);
193
194int credential_read(struct credential *, FILE *);
Matthieu Moy2d6dc182012-06-24 13:40:00 +0200195void credential_write(const struct credential *, FILE *);
Heba Walyf3b90552019-11-17 21:04:53 +0000196
Jeff Kingc716fe42020-03-12 01:31:11 -0400197/*
198 * Parse a url into a credential struct, replacing any existing contents.
199 *
Junio C Hamano67b0a242020-03-17 18:12:01 -0700200 * If the url can't be parsed (e.g., a missing "proto://" component), the
Carlo Marcelo Arenas Belón7f535832020-05-04 18:39:05 -0700201 * resulting credential will be empty and the function will return an
202 * error (even in the "gently" form).
Jeff Kingc716fe42020-03-12 01:31:11 -0400203 *
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 */
Jeff Kingd3e847c2011-12-10 05:31:17 -0500210void credential_from_url(struct credential *, const char *url);
Jeff Kingc716fe42020-03-12 01:31:11 -0400211int credential_from_url_gently(struct credential *, const char *url, int quiet);
Heba Walyf3b90552019-11-17 21:04:53 +0000212
Carlo Marcelo Arenas Belónbb987652020-05-04 18:39:06 -0700213int credential_match(const struct credential *want,
M Hickfordaeb21ce2023-06-15 19:19:32 +0000214 const struct credential *have, int match_password);
Jeff Kingabca9272011-12-10 05:31:11 -0500215
216#endif /* CREDENTIAL_H */