docs: indicate new credential protocol fields
Now that we have new fields (authtype and credential), let's document them for users and credential helper implementers. Indicate specifically what common values of authtype are and what values are allowed. Note that, while common, digest and NTLM authentication are insecure because they require unsalted, uniterated password hashes to be stored. Tell users that they can continue to use a username and password even if the new capability is supported. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
brian m. carlson committed
Apr 17, 2024 at 00:02 UTC
5af5cc68aa8658c42bb2c4c46f2f01dabbd5acff
1 file changed
+48
-1
Documentation/git-credential.txt
+48
-1
@@ -178,6 +178,39 @@ empty string.
178
Components which are missing from the URL (e.g., there is no
179
username in the example above) will be left unset.
180
181
+`authtype`::
182
+ This indicates that the authentication scheme in question should be used.
183
+ Common values for HTTP and HTTPS include `basic`, `bearer`, and `digest`,
184
+ although the latter is insecure and should not be used. If `credential`
185
+ is used, this may be set to an arbitrary string suitable for the protocol in
186
+ question (usually HTTP).
187
++
188
+This value should not be sent unless the appropriate capability (see below) is
189
+provided on input.
190
+
191
+`credential`::
192
+ The pre-encoded credential, suitable for the protocol in question (usually
193
+ HTTP). If this key is sent, `authtype` is mandatory, and `username` and
194
+ `password` are not used. For HTTP, Git concatenates the `authtype` value and
195
+ this value with a single space to determine the `Authorization` header.
196
++
197
+This value should not be sent unless the appropriate capability (see below) is
198
+provided on input.
199
+
200
+`ephemeral`::
201
+ This boolean value indicates, if true, that the value in the `credential`
202
+ field should not be saved by the credential helper because its usefulness is
203
+ limited in time. For example, an HTTP Digest `credential` value is computed
204
+ using a nonce and reusing it will not result in successful authentication.
205
+ This may also be used for situations with short duration (e.g., 24-hour)
206
+ credentials. The default value is false.
207
++
208
+The credential helper will still be invoked with `store` or `erase` so that it
209
+can determine whether the operation was successful.
210
++
211
+This value should not be sent unless the appropriate capability (see below) is
212
+provided on input.
213
+
214
`wwwauth[]`::
215
216
When an HTTP response is received by Git that includes one or more
@@ -189,7 +222,21 @@ attribute 'wwwauth[]', where the order of the attributes is the same as
222
they appear in the HTTP response. This attribute is 'one-way' from Git
223
to pass additional information to credential helpers.
224
192
-Unrecognised attributes are silently discarded.
225
+`capability[]`::
226
+ This signals that the caller supports the capability in question.
227
+ This can be used to provide better, more specific data as part of the
228
+ protocol.
229
++
230
+The only capability currently supported is `authtype`, which indicates that the
231
+`authtype`, `credential`, and `ephemeral` values are understood. It is not
232
+obligatory to use these values in such a case, but they should not be provided
233
+without this capability.
234
++
235
+Callers of `git credential` and credential helpers should emit the
236
+capabilities they support unconditionally, and Git will gracefully
237
+handle passing them on.
238
+
239
+Unrecognised attributes and capabilities are silently discarded.
240
241
GIT
242
---