]>
Commit | Line | Data |
---|---|---|
abca927d JK |
1 | credentials API |
2 | =============== | |
3 | ||
4 | The credentials API provides an abstracted way of gathering username and | |
5 | password credentials from the user (even though credentials in the wider | |
6 | world can take many forms, in this document the word "credential" always | |
7 | refers to a username and password pair). | |
8 | ||
22398880 | 9 | This document describes two interfaces: the C API that the credential |
2de9b711 | 10 | subsystem provides to the rest of Git, and the protocol that Git uses to |
22398880 | 11 | communicate with system-specific "credential helpers". If you are |
2de9b711 | 12 | writing Git code that wants to look up or prompt for credentials, see |
22398880 MM |
13 | the section "C API" below. If you want to write your own helper, see |
14 | the section on "Credential Helpers" below. | |
15 | ||
16 | Typical setup | |
17 | ------------- | |
18 | ||
19 | ------------ | |
20 | +-----------------------+ | |
2de9b711 | 21 | | Git code (C) |--- to server requiring ---> |
22398880 MM |
22 | | | authentication |
23 | |.......................| | |
24 | | C credential API |--- prompt ---> User | |
25 | +-----------------------+ | |
26 | ^ | | |
27 | | pipe | | |
28 | | v | |
29 | +-----------------------+ | |
2de9b711 | 30 | | Git credential helper | |
22398880 MM |
31 | +-----------------------+ |
32 | ------------ | |
33 | ||
2de9b711 | 34 | The Git code (typically a remote-helper) will call the C API to obtain |
22398880 MM |
35 | credential data like a login/password pair (credential_fill). The |
36 | API will itself call a remote helper (e.g. "git credential-cache" or | |
37 | "git credential-store") that may retrieve credential data from a | |
38 | store. If the credential helper cannot find the information, the C API | |
39 | will prompt the user. Then, the caller of the API takes care of | |
40 | contacting the server, and does the actual authentication. | |
41 | ||
42 | C API | |
43 | ----- | |
44 | ||
2de9b711 | 45 | The credential C API is meant to be called by Git code which needs to |
22398880 MM |
46 | acquire or store a credential. It is centered around an object |
47 | representing a single credential and provides three basic operations: | |
48 | fill (acquire credentials by calling helpers and/or prompting the user), | |
49 | approve (mark a credential as successfully used so that it can be stored | |
50 | for later use), and reject (mark a credential as unsuccessful so that it | |
51 | can be erased from any persistent storage). | |
52 | ||
abca927d | 53 | Data Structures |
22398880 | 54 | ~~~~~~~~~~~~~~~ |
abca927d JK |
55 | |
56 | `struct credential`:: | |
57 | ||
58 | This struct represents a single username/password combination | |
59 | along with any associated context. All string fields should be | |
60 | heap-allocated (or NULL if they are not known or not applicable). | |
61 | The meaning of the individual context fields is the same as | |
62 | their counterparts in the helper protocol; see the section below | |
63 | for a description of each field. | |
64 | + | |
65 | The `helpers` member of the struct is a `string_list` of helpers. Each | |
66 | string specifies an external helper which will be run, in order, to | |
67 | either acquire or store credentials. See the section on credential | |
317d74be MM |
68 | helpers below. This list is filled-in by the API functions |
69 | according to the corresponding configuration variables before | |
70 | consulting helpers, so there usually is no need for a caller to | |
71 | modify the helpers field at all. | |
abca927d JK |
72 | + |
73 | This struct should always be initialized with `CREDENTIAL_INIT` or | |
74 | `credential_init`. | |
75 | ||
76 | ||
77 | Functions | |
22398880 | 78 | ~~~~~~~~~ |
abca927d JK |
79 | |
80 | `credential_init`:: | |
81 | ||
82 | Initialize a credential structure, setting all fields to empty. | |
83 | ||
84 | `credential_clear`:: | |
85 | ||
86 | Free any resources associated with the credential structure, | |
87 | returning it to a pristine initialized state. | |
88 | ||
89 | `credential_fill`:: | |
90 | ||
91 | Instruct the credential subsystem to fill the username and | |
92 | password fields of the passed credential struct by first | |
93 | consulting helpers, then asking the user. After this function | |
94 | returns, the username and password fields of the credential are | |
95 | guaranteed to be non-NULL. If an error occurs, the function will | |
96 | die(). | |
97 | ||
98 | `credential_reject`:: | |
99 | ||
100 | Inform the credential subsystem that the provided credentials | |
101 | have been rejected. This will cause the credential subsystem to | |
102 | notify any helpers of the rejection (which allows them, for | |
103 | example, to purge the invalid credentials from storage). It | |
104 | will also free() the username and password fields of the | |
105 | credential and set them to NULL (readying the credential for | |
106 | another call to `credential_fill`). Any errors from helpers are | |
107 | ignored. | |
108 | ||
109 | `credential_approve`:: | |
110 | ||
111 | Inform the credential subsystem that the provided credentials | |
112 | were successfully used for authentication. This will cause the | |
113 | credential subsystem to notify any helpers of the approval, so | |
114 | that they may store the result to be used again. Any errors | |
115 | from helpers are ignored. | |
116 | ||
d3e847c1 JK |
117 | `credential_from_url`:: |
118 | ||
119 | Parse a URL into broken-down credential fields. | |
120 | ||
abca927d | 121 | Example |
22398880 | 122 | ~~~~~~~ |
abca927d JK |
123 | |
124 | The example below shows how the functions of the credential API could be | |
125 | used to login to a fictitious "foo" service on a remote host: | |
126 | ||
127 | ----------------------------------------------------------------------- | |
128 | int foo_login(struct foo_connection *f) | |
129 | { | |
130 | int status; | |
131 | /* | |
132 | * Create a credential with some context; we don't yet know the | |
133 | * username or password. | |
134 | */ | |
135 | ||
136 | struct credential c = CREDENTIAL_INIT; | |
137 | c.protocol = xstrdup("foo"); | |
138 | c.host = xstrdup(f->hostname); | |
139 | ||
140 | /* | |
141 | * Fill in the username and password fields by contacting | |
142 | * helpers and/or asking the user. The function will die if it | |
143 | * fails. | |
144 | */ | |
145 | credential_fill(&c); | |
146 | ||
147 | /* | |
148 | * Otherwise, we have a username and password. Try to use it. | |
149 | */ | |
150 | status = send_foo_login(f, c.username, c.password); | |
151 | switch (status) { | |
152 | case FOO_OK: | |
153 | /* It worked. Store the credential for later use. */ | |
154 | credential_accept(&c); | |
155 | break; | |
156 | case FOO_BAD_LOGIN: | |
157 | /* Erase the credential from storage so we don't try it | |
158 | * again. */ | |
159 | credential_reject(&c); | |
160 | break; | |
161 | default: | |
162 | /* | |
e1c3bf49 | 163 | * Some other error occurred. We don't know if the |
abca927d JK |
164 | * credential is good or bad, so report nothing to the |
165 | * credential subsystem. | |
166 | */ | |
167 | } | |
168 | ||
169 | /* Free any associated resources. */ | |
170 | credential_clear(&c); | |
171 | ||
172 | return status; | |
173 | } | |
174 | ----------------------------------------------------------------------- | |
175 | ||
176 | ||
177 | Credential Helpers | |
178 | ------------------ | |
179 | ||
2de9b711 | 180 | Credential helpers are programs executed by Git to fetch or save |
abca927d | 181 | credentials from and to long-term storage (where "long-term" is simply |
2de9b711 | 182 | longer than a single Git process; e.g., credentials may be stored |
abca927d JK |
183 | in-memory for a few minutes, or indefinitely on disk). |
184 | ||
365fc8d5 | 185 | Each helper is specified by a single string in the configuration |
fe77b416 | 186 | variable `credential.helper` (and others, see linkgit:git-config[1]). |
2de9b711 | 187 | The string is transformed by Git into a command to be executed using |
365fc8d5 | 188 | these rules: |
abca927d JK |
189 | |
190 | 1. If the helper string begins with "!", it is considered a shell | |
191 | snippet, and everything after the "!" becomes the command. | |
192 | ||
193 | 2. Otherwise, if the helper string begins with an absolute path, the | |
194 | verbatim helper string becomes the command. | |
195 | ||
196 | 3. Otherwise, the string "git credential-" is prepended to the helper | |
197 | string, and the result becomes the command. | |
198 | ||
199 | The resulting command then has an "operation" argument appended to it | |
200 | (see below for details), and the result is executed by the shell. | |
201 | ||
202 | Here are some example specifications: | |
203 | ||
204 | ---------------------------------------------------- | |
205 | # run "git credential-foo" | |
206 | foo | |
207 | ||
208 | # same as above, but pass an argument to the helper | |
209 | foo --bar=baz | |
210 | ||
211 | # the arguments are parsed by the shell, so use shell | |
212 | # quoting if necessary | |
213 | foo --bar="whitespace arg" | |
214 | ||
215 | # you can also use an absolute path, which will not use the git wrapper | |
216 | /path/to/my/helper --with-arguments | |
217 | ||
218 | # or you can specify your own shell snippet | |
219 | !f() { echo "password=`cat $HOME/.secret`"; }; f | |
220 | ---------------------------------------------------- | |
221 | ||
222 | Generally speaking, rule (3) above is the simplest for users to specify. | |
223 | Authors of credential helpers should make an effort to assist their | |
224 | users by naming their program "git-credential-$NAME", and putting it in | |
225 | the $PATH or $GIT_EXEC_PATH during installation, which will allow a user | |
226 | to enable it with `git config credential.helper $NAME`. | |
227 | ||
228 | When a helper is executed, it will have one "operation" argument | |
229 | appended to its command line, which is one of: | |
230 | ||
231 | `get`:: | |
232 | ||
233 | Return a matching credential, if any exists. | |
234 | ||
235 | `store`:: | |
236 | ||
237 | Store the credential, if applicable to the helper. | |
238 | ||
239 | `erase`:: | |
240 | ||
241 | Remove a matching credential, if any, from the helper's storage. | |
242 | ||
243 | The details of the credential will be provided on the helper's stdin | |
e30b2feb JRI |
244 | stream. The exact format is the same as the input/output format of the |
245 | `git credential` plumbing command (see the section `INPUT/OUTPUT | |
1cca17df | 246 | FORMAT` in linkgit:git-credential[1] for a detailed specification). |
abca927d JK |
247 | |
248 | For a `get` operation, the helper should produce a list of attributes | |
249 | on stdout in the same format. A helper is free to produce a subset, or | |
250 | even no values at all if it has nothing useful to provide. Any provided | |
59b38652 JK |
251 | attributes will overwrite those already known about by Git. If a helper |
252 | outputs a `quit` attribute with a value of `true` or `1`, no further | |
253 | helpers will be consulted, nor will the user be prompted (if no | |
254 | credential has been provided, the operation will then fail). | |
abca927d JK |
255 | |
256 | For a `store` or `erase` operation, the helper's output is ignored. | |
257 | If it fails to perform the requested operation, it may complain to | |
258 | stderr to inform the user. If it does not support the requested | |
259 | operation (e.g., a read-only store), it should silently ignore the | |
260 | request. | |
261 | ||
262 | If a helper receives any other operation, it should silently ignore the | |
263 | request. This leaves room for future operations to be added (older | |
264 | helpers will just ignore the new requests). | |
04ab6ae7 MM |
265 | |
266 | See also | |
267 | -------- | |
268 | ||
fe77b416 | 269 | linkgit:gitcredentials[7] |
04ab6ae7 | 270 | |
1cca17df | 271 | linkgit:git-config[1] (See configuration variables `credential.*`) |