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
+
9
+Data Structures
10
+---------------
11
+
12
+`struct credential`::
13
+
14
+ This struct represents a single username/password combination
15
+ along with any associated context. All string fields should be
16
+ heap-allocated (or NULL if they are not known or not applicable).
17
+ The meaning of the individual context fields is the same as
18
+ their counterparts in the helper protocol; see the section below
19
+ for a description of each field.
20
++
21
+The `helpers` member of the struct is a `string_list` of helpers. Each
22
+string specifies an external helper which will be run, in order, to
23
+either acquire or store credentials. See the section on credential
24
+helpers below.
25
++
26
+This struct should always be initialized with `CREDENTIAL_INIT` or
27
+`credential_init`.
28
+
29
+
30
+Functions
31
+---------
32
+
33
+`credential_init`::
34
+
35
+ Initialize a credential structure, setting all fields to empty.
36
+
37
+`credential_clear`::
38
+
39
+ Free any resources associated with the credential structure,
40
+ returning it to a pristine initialized state.
41
+
42
+`credential_fill`::
43
+
44
+ Instruct the credential subsystem to fill the username and
45
+ password fields of the passed credential struct by first
46
+ consulting helpers, then asking the user. After this function
47
+ returns, the username and password fields of the credential are
48
+ guaranteed to be non-NULL. If an error occurs, the function will
49
+ die().
50
+
51
+`credential_reject`::
52
+
53
+ Inform the credential subsystem that the provided credentials
54
+ have been rejected. This will cause the credential subsystem to
55
+ notify any helpers of the rejection (which allows them, for
56
+ example, to purge the invalid credentials from storage). It
57
+ will also free() the username and password fields of the
58
+ credential and set them to NULL (readying the credential for
59
+ another call to `credential_fill`). Any errors from helpers are
60
+ ignored.
61
+
62
+`credential_approve`::
63
+
64
+ Inform the credential subsystem that the provided credentials
65
+ were successfully used for authentication. This will cause the
66
+ credential subsystem to notify any helpers of the approval, so
67
+ that they may store the result to be used again. Any errors
68
+ from helpers are ignored.
69
+
70
+Example
71
+-------
72
+
73
+The example below shows how the functions of the credential API could be
74
+used to login to a fictitious "foo" service on a remote host:
75
+
76
+-----------------------------------------------------------------------
77
+int foo_login(struct foo_connection *f)
78
+{
79
+ int status;
80
+ /*
81
+ * Create a credential with some context; we don't yet know the
82
+ * username or password.
83
+ */
84
+
85
+ struct credential c = CREDENTIAL_INIT;
86
+ c.protocol = xstrdup("foo");
87
+ c.host = xstrdup(f->hostname);
88
+
89
+ /*
90
+ * Fill in the username and password fields by contacting
91
+ * helpers and/or asking the user. The function will die if it
92
+ * fails.
93
+ */
94
+ credential_fill(&c);
95
+
96
+ /*
97
+ * Otherwise, we have a username and password. Try to use it.
98
+ */
99
+ status = send_foo_login(f, c.username, c.password);
100
+ switch (status) {
101
+ case FOO_OK:
102
+ /* It worked. Store the credential for later use. */
103
+ credential_accept(&c);
104
+ break;
105
+ case FOO_BAD_LOGIN:
106
+ /* Erase the credential from storage so we don't try it
107
+ * again. */
108
+ credential_reject(&c);
109
+ break;
110
+ default:
111
+ /*
112
+ * Some other error occured. We don't know if the
113
+ * credential is good or bad, so report nothing to the
114
+ * credential subsystem.
115
+ */
116
+ }
117
+
118
+ /* Free any associated resources. */
119
+ credential_clear(&c);
120
+
121
+ return status;
122
+}
123
+-----------------------------------------------------------------------
124
+
125
+
126
+Credential Helpers
127
+------------------
128
+
129
+Credential helpers are programs executed by git to fetch or save
130
+credentials from and to long-term storage (where "long-term" is simply
131
+longer than a single git process; e.g., credentials may be stored
132
+in-memory for a few minutes, or indefinitely on disk).
133
+
134
+Each helper is specified by a single string. The string is transformed
135
+by git into a command to be executed using these rules:
136
+
137
+ 1. If the helper string begins with "!", it is considered a shell
138
+ snippet, and everything after the "!" becomes the command.
139
+
140
+ 2. Otherwise, if the helper string begins with an absolute path, the
141
+ verbatim helper string becomes the command.
142
+
143
+ 3. Otherwise, the string "git credential-" is prepended to the helper
144
+ string, and the result becomes the command.
145
+
146
+The resulting command then has an "operation" argument appended to it
147
+(see below for details), and the result is executed by the shell.
148
+
149
+Here are some example specifications:
150
+
151
+----------------------------------------------------
152
+# run "git credential-foo"
153
+foo
154
+
155
+# same as above, but pass an argument to the helper
156
+foo --bar=baz
157
+
158
+# the arguments are parsed by the shell, so use shell
159
+# quoting if necessary
160
+foo --bar="whitespace arg"
161
+
162
+# you can also use an absolute path, which will not use the git wrapper
163
+/path/to/my/helper --with-arguments
164
+
165
+# or you can specify your own shell snippet
166
+!f() { echo "password=`cat $HOME/.secret`"; }; f
167
+----------------------------------------------------
168
+
169
+Generally speaking, rule (3) above is the simplest for users to specify.
170
+Authors of credential helpers should make an effort to assist their
171
+users by naming their program "git-credential-$NAME", and putting it in
172
+the $PATH or $GIT_EXEC_PATH during installation, which will allow a user
173
+to enable it with `git config credential.helper $NAME`.
174
+
175
+When a helper is executed, it will have one "operation" argument
176
+appended to its command line, which is one of:
177
+
178
+`get`::
179
+
180
+ Return a matching credential, if any exists.
181
+
182
+`store`::
183
+
184
+ Store the credential, if applicable to the helper.
185
+
186
+`erase`::
187
+
188
+ Remove a matching credential, if any, from the helper's storage.
189
+
190
+The details of the credential will be provided on the helper's stdin
191
+stream. The credential is split into a set of named attributes.
192
+Attributes are provided to the helper, one per line. Each attribute is
193
+specified by a key-value pair, separated by an `=` (equals) sign,
194
+followed by a newline. The key may contain any bytes except `=`,
195
+newline, or NUL. The value may contain any bytes except newline or NUL.
196
+In both cases, all bytes are treated as-is (i.e., there is no quoting,
197
+and one cannot transmit a value with newline or NUL in it). The list of
198
+attributes is terminated by a blank line or end-of-file.
199
+
200
+Git will send the following attributes (but may not send all of
201
+them for a given credential; for example, a `host` attribute makes no
202
+sense when dealing with a non-network protocol):
203
+
204
+`protocol`::
205
+
206
+ The protocol over which the credential will be used (e.g.,
207
+ `https`).
208
+
209
+`host`::
210
+
211
+ The remote hostname for a network credential.
212
+
213
+`path`::
214
+
215
+ The path with which the credential will be used. E.g., for
216
+ accessing a remote https repository, this will be the
217
+ repository's path on the server.
218
+
219
+`username`::
220
+
221
+ The credential's username, if we already have one (e.g., from a
222
+ URL, from the user, or from a previously run helper).
223
+
224
+`password`::
225
+
226
+ The credential's password, if we are asking it to be stored.
227
+
228
+For a `get` operation, the helper should produce a list of attributes
229
+on stdout in the same format. A helper is free to produce a subset, or
230
+even no values at all if it has nothing useful to provide. Any provided
231
+attributes will overwrite those already known about by git.
232
+
233
+For a `store` or `erase` operation, the helper's output is ignored.
234
+If it fails to perform the requested operation, it may complain to
235
+stderr to inform the user. If it does not support the requested
236
+operation (e.g., a read-only store), it should silently ignore the
237
+request.
238
+
239
+If a helper receives any other operation, it should silently ignore the
240
+request. This leaves room for future operations to be added (older
241
+helpers will just ignore the new requests).