]>
Commit | Line | Data |
---|---|---|
abca927d JK |
1 | #ifndef CREDENTIAL_H |
2 | #define CREDENTIAL_H | |
3 | ||
4 | #include "string-list.h" | |
5 | ||
f3b90556 HW |
6 | /** |
7 | * The credentials API provides an abstracted way of gathering username and | |
8 | * password credentials from the user. | |
9 | * | |
10 | * Typical setup | |
11 | * ------------- | |
12 | * | |
13 | * ------------ | |
14 | * +-----------------------+ | |
15 | * | Git code (C) |--- to server requiring ---> | |
16 | * | | authentication | |
17 | * |.......................| | |
18 | * | C credential API |--- prompt ---> User | |
19 | * +-----------------------+ | |
20 | * ^ | | |
21 | * | pipe | | |
22 | * | v | |
23 | * +-----------------------+ | |
24 | * | Git credential helper | | |
25 | * +-----------------------+ | |
26 | * ------------ | |
27 | * | |
28 | * The Git code (typically a remote-helper) will call the C API to obtain | |
29 | * credential data like a login/password pair (credential_fill). The | |
30 | * API will itself call a remote helper (e.g. "git credential-cache" or | |
31 | * "git credential-store") that may retrieve credential data from a | |
32 | * store. If the credential helper cannot find the information, the C API | |
33 | * will prompt the user. Then, the caller of the API takes care of | |
34 | * contacting the server, and does the actual authentication. | |
35 | * | |
36 | * C API | |
37 | * ----- | |
38 | * | |
39 | * The credential C API is meant to be called by Git code which needs to | |
40 | * acquire or store a credential. It is centered around an object | |
41 | * representing a single credential and provides three basic operations: | |
42 | * fill (acquire credentials by calling helpers and/or prompting the user), | |
43 | * approve (mark a credential as successfully used so that it can be stored | |
44 | * for later use), and reject (mark a credential as unsuccessful so that it | |
45 | * can be erased from any persistent storage). | |
46 | * | |
47 | * Example | |
48 | * ~~~~~~~ | |
49 | * | |
50 | * The example below shows how the functions of the credential API could be | |
51 | * used to login to a fictitious "foo" service on a remote host: | |
52 | * | |
53 | * ----------------------------------------------------------------------- | |
54 | * int foo_login(struct foo_connection *f) | |
55 | * { | |
56 | * int status; | |
57 | * // Create a credential with some context; we don't yet know the | |
58 | * // username or password. | |
59 | * | |
60 | * struct credential c = CREDENTIAL_INIT; | |
61 | * c.protocol = xstrdup("foo"); | |
62 | * c.host = xstrdup(f->hostname); | |
63 | * | |
64 | * // Fill in the username and password fields by contacting | |
65 | * // helpers and/or asking the user. The function will die if it | |
66 | * // fails. | |
67 | * credential_fill(&c); | |
68 | * | |
69 | * // Otherwise, we have a username and password. Try to use it. | |
70 | * | |
71 | * status = send_foo_login(f, c.username, c.password); | |
72 | * switch (status) { | |
73 | * case FOO_OK: | |
74 | * // It worked. Store the credential for later use. | |
75 | * credential_accept(&c); | |
76 | * break; | |
77 | * case FOO_BAD_LOGIN: | |
78 | * // Erase the credential from storage so we don't try it again. | |
79 | * credential_reject(&c); | |
80 | * break; | |
81 | * default: | |
82 | * // Some other error occurred. We don't know if the | |
83 | * // credential is good or bad, so report nothing to the | |
84 | * // credential subsystem. | |
85 | * } | |
86 | * | |
87 | * // Free any associated resources. | |
88 | * credential_clear(&c); | |
89 | * | |
90 | * return status; | |
91 | * } | |
92 | * ----------------------------------------------------------------------- | |
f3b90556 HW |
93 | */ |
94 | ||
95 | ||
96 | /** | |
97 | * This struct represents a single username/password combination | |
98 | * along with any associated context. All string fields should be | |
99 | * heap-allocated (or NULL if they are not known or not applicable). | |
100 | * The meaning of the individual context fields is the same as | |
101 | * their counterparts in the helper protocol. | |
102 | * | |
103 | * This struct should always be initialized with `CREDENTIAL_INIT` or | |
104 | * `credential_init`. | |
105 | */ | |
abca927d | 106 | struct credential { |
f3b90556 HW |
107 | |
108 | /** | |
109 | * A `string_list` of helpers. Each string specifies an external | |
110 | * helper which will be run, in order, to either acquire or store | |
111 | * credentials. This list is filled-in by the API functions | |
112 | * according to the corresponding configuration variables before | |
113 | * consulting helpers, so there usually is no need for a caller to | |
114 | * modify the helpers field at all. | |
115 | */ | |
abca927d | 116 | struct string_list helpers; |
f3b90556 | 117 | |
11825072 | 118 | unsigned approved:1, |
a78fbb4f | 119 | configured:1, |
59b38652 | 120 | quit:1, |
82eb2498 | 121 | use_http_path:1, |
122 | username_from_proto:1; | |
abca927d JK |
123 | |
124 | char *username; | |
125 | char *password; | |
126 | char *protocol; | |
127 | char *host; | |
128 | char *path; | |
129 | }; | |
130 | ||
3d97ea47 ÆAB |
131 | #define CREDENTIAL_INIT { \ |
132 | .helpers = STRING_LIST_INIT_DUP, \ | |
133 | } | |
abca927d | 134 | |
f3b90556 | 135 | /* Initialize a credential structure, setting all fields to empty. */ |
abca927d | 136 | void credential_init(struct credential *); |
f3b90556 HW |
137 | |
138 | /** | |
139 | * Free any resources associated with the credential structure, returning | |
140 | * it to a pristine initialized state. | |
141 | */ | |
abca927d JK |
142 | void credential_clear(struct credential *); |
143 | ||
f3b90556 HW |
144 | /** |
145 | * Instruct the credential subsystem to fill the username and | |
146 | * password fields of the passed credential struct by first | |
147 | * consulting helpers, then asking the user. After this function | |
148 | * returns, the username and password fields of the credential are | |
149 | * guaranteed to be non-NULL. If an error occurs, the function will | |
150 | * die(). | |
151 | */ | |
abca927d | 152 | void credential_fill(struct credential *); |
f3b90556 HW |
153 | |
154 | /** | |
155 | * Inform the credential subsystem that the provided credentials | |
156 | * were successfully used for authentication. This will cause the | |
157 | * credential subsystem to notify any helpers of the approval, so | |
158 | * that they may store the result to be used again. Any errors | |
159 | * from helpers are ignored. | |
160 | */ | |
abca927d | 161 | void credential_approve(struct credential *); |
f3b90556 HW |
162 | |
163 | /** | |
164 | * Inform the credential subsystem that the provided credentials | |
165 | * have been rejected. This will cause the credential subsystem to | |
166 | * notify any helpers of the rejection (which allows them, for | |
167 | * example, to purge the invalid credentials from storage). It | |
168 | * will also free() the username and password fields of the | |
169 | * credential and set them to NULL (readying the credential for | |
170 | * another call to `credential_fill`). Any errors from helpers are | |
171 | * ignored. | |
172 | */ | |
abca927d JK |
173 | void credential_reject(struct credential *); |
174 | ||
175 | int credential_read(struct credential *, FILE *); | |
2d6dc182 | 176 | void credential_write(const struct credential *, FILE *); |
f3b90556 | 177 | |
c716fe4b JK |
178 | /* |
179 | * Parse a url into a credential struct, replacing any existing contents. | |
180 | * | |
67b0a249 | 181 | * If the url can't be parsed (e.g., a missing "proto://" component), the |
7f535838 CMAB |
182 | * resulting credential will be empty and the function will return an |
183 | * error (even in the "gently" form). | |
c716fe4b JK |
184 | * |
185 | * If we encounter a component which cannot be represented as a credential | |
186 | * value (e.g., because it contains a newline), the "gently" form will return | |
187 | * an error but leave the broken state in the credential object for further | |
188 | * examination. The non-gentle form will issue a warning to stderr and return | |
189 | * an empty credential. | |
190 | */ | |
d3e847c1 | 191 | void credential_from_url(struct credential *, const char *url); |
c716fe4b | 192 | int credential_from_url_gently(struct credential *, const char *url, int quiet); |
f3b90556 | 193 | |
bb987657 CMAB |
194 | int credential_match(const struct credential *want, |
195 | const struct credential *have); | |
abca927d JK |
196 | |
197 | #endif /* CREDENTIAL_H */ |