| 1 | git-credential(1) |
| 2 | ================= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-credential - Retrieve and store user credentials |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | ------------------ |
| 11 | 'git credential' (fill|approve|reject|capability) |
| 12 | ------------------ |
| 13 | |
| 14 | DESCRIPTION |
| 15 | ----------- |
| 16 | |
| 17 | Git has an internal interface for storing and retrieving credentials |
| 18 | from system-specific helpers, as well as prompting the user for |
| 19 | usernames and passwords. The git-credential command exposes this |
| 20 | interface to scripts which may want to retrieve, store, or prompt for |
| 21 | credentials in the same manner as Git. The design of this scriptable |
| 22 | interface models the internal C API; see credential.h for more |
| 23 | background on the concepts. |
| 24 | |
| 25 | git-credential takes an "action" option on the command-line (one of |
| 26 | `fill`, `approve`, or `reject`) and reads a credential description |
| 27 | on stdin (see <<IOFMT,INPUT/OUTPUT FORMAT>>). |
| 28 | |
| 29 | If the action is `fill`, git-credential will attempt to add "username" |
| 30 | and "password" attributes to the description by reading config files, |
| 31 | by contacting any configured credential helpers, or by prompting the |
| 32 | user. The username and password attributes of the credential |
| 33 | description are then printed to stdout together with the attributes |
| 34 | already provided. |
| 35 | |
| 36 | If the action is `approve`, git-credential will send the description |
| 37 | to any configured credential helpers, which may store the credential |
| 38 | for later use. |
| 39 | |
| 40 | If the action is `reject`, git-credential will send the description to |
| 41 | any configured credential helpers, which may erase any stored |
| 42 | credentials matching the description. |
| 43 | |
| 44 | If the action is `capability`, git-credential will announce any capabilities |
| 45 | it supports to standard output. |
| 46 | |
| 47 | If the action is `approve` or `reject`, no output should be emitted. |
| 48 | |
| 49 | TYPICAL USE OF GIT CREDENTIAL |
| 50 | ----------------------------- |
| 51 | |
| 52 | An application using git-credential will typically use `git |
| 53 | credential` following these steps: |
| 54 | |
| 55 | 1. Generate a credential description based on the context. |
| 56 | + |
| 57 | For example, if we want a password for |
| 58 | `https://example.com/foo.git`, we might generate the following |
| 59 | credential description (don't forget the blank line at the end; it |
| 60 | tells `git credential` that the application finished feeding all the |
| 61 | information it has): |
| 62 | |
| 63 | protocol=https |
| 64 | host=example.com |
| 65 | path=foo.git |
| 66 | |
| 67 | 2. Ask git-credential to give us a username and password for this |
| 68 | description. This is done by running `git credential fill`, |
| 69 | feeding the description from step (1) to its standard input. The complete |
| 70 | credential description (including the credential per se, i.e. the |
| 71 | login and password) will be produced on standard output, like: |
| 72 | |
| 73 | protocol=https |
| 74 | host=example.com |
| 75 | username=bob |
| 76 | password=secr3t |
| 77 | + |
| 78 | In most cases, this means the attributes given in the input will be |
| 79 | repeated in the output, but Git may also modify the credential |
| 80 | description, for example by removing the `path` attribute when the |
| 81 | protocol is HTTP(s) and `credential.useHttpPath` is false. |
| 82 | + |
| 83 | If the `git credential` knew about the password, this step may |
| 84 | not have involved the user actually typing this password (the |
| 85 | user may have typed a password to unlock the keychain instead, |
| 86 | or no user interaction was done if the keychain was already |
| 87 | unlocked) before it returned `password=secr3t`. |
| 88 | |
| 89 | 3. Use the credential (e.g., access the URL with the username and |
| 90 | password from step (2)), and see if it's accepted. |
| 91 | |
| 92 | 4. Report on the success or failure of the password. If the |
| 93 | credential allowed the operation to complete successfully, then |
| 94 | it can be marked with an "approve" action to tell `git |
| 95 | credential` to reuse it in its next invocation. If the credential |
| 96 | was rejected during the operation, use the "reject" action so |
| 97 | that `git credential` will ask for a new password in its next |
| 98 | invocation. In either case, `git credential` should be fed with |
| 99 | the credential description obtained from step (2) (which also |
| 100 | contains the fields provided in step (1)). |
| 101 | |
| 102 | [[IOFMT]] |
| 103 | INPUT/OUTPUT FORMAT |
| 104 | ------------------- |
| 105 | |
| 106 | `git credential` reads and/or writes (depending on the action used) |
| 107 | credential information in its standard input/output. This information |
| 108 | can correspond either to keys for which `git credential` will obtain |
| 109 | the login information (e.g. host, protocol, path), or to the actual |
| 110 | credential data to be obtained (username/password). |
| 111 | |
| 112 | The credential is split into a set of named attributes, with one |
| 113 | attribute per line. Each attribute is specified by a key-value pair, |
| 114 | separated by an `=` (equals) sign, followed by a newline. |
| 115 | |
| 116 | The key may contain any bytes except `=`, newline, or NUL. The value may |
| 117 | contain any bytes except newline or NUL. A line, including the trailing |
| 118 | newline, may not exceed 65535 bytes in order to allow implementations to |
| 119 | parse efficiently. |
| 120 | |
| 121 | Attributes with keys that end with C-style array brackets `[]` can have |
| 122 | multiple values. Each instance of a multi-valued attribute forms an |
| 123 | ordered list of values - the order of the repeated attributes defines |
| 124 | the order of the values. An empty multi-valued attribute (`key[]=\n`) |
| 125 | acts to clear any previous entries and reset the list. |
| 126 | |
| 127 | In all cases, all bytes are treated as-is (i.e., there is no quoting, |
| 128 | and one cannot transmit a value with newline or NUL in it). The list of |
| 129 | attributes is terminated by a blank line or end-of-file. |
| 130 | |
| 131 | Git understands the following attributes: |
| 132 | |
| 133 | `protocol`:: |
| 134 | |
| 135 | The protocol over which the credential will be used (e.g., |
| 136 | `https`). |
| 137 | |
| 138 | `host`:: |
| 139 | |
| 140 | The remote hostname for a network credential. This includes |
| 141 | the port number if one was specified (e.g., "example.com:8088"). |
| 142 | |
| 143 | `path`:: |
| 144 | |
| 145 | The path with which the credential will be used. E.g., for |
| 146 | accessing a remote https repository, this will be the |
| 147 | repository's path on the server. |
| 148 | |
| 149 | `username`:: |
| 150 | |
| 151 | The credential's username, if we already have one (e.g., from a |
| 152 | URL, the configuration, the user, or from a previously run helper). |
| 153 | |
| 154 | `password`:: |
| 155 | |
| 156 | The credential's password, if we are asking it to be stored. |
| 157 | |
| 158 | `password_expiry_utc`:: |
| 159 | |
| 160 | Generated passwords such as an OAuth access token may have an expiry date. |
| 161 | When reading credentials from helpers, `git credential fill` ignores expired |
| 162 | passwords. Represented as Unix time UTC, seconds since 1970. |
| 163 | |
| 164 | `oauth_refresh_token`:: |
| 165 | |
| 166 | An OAuth refresh token may accompany a password that is an OAuth access |
| 167 | token. Helpers must treat this attribute as confidential like the password |
| 168 | attribute. Git itself has no special behaviour for this attribute. |
| 169 | |
| 170 | `url`:: |
| 171 | |
| 172 | When this special attribute is read by `git credential`, the |
| 173 | value is parsed as a URL and treated as if its constituent parts |
| 174 | were read (e.g., `url=https://example.com` would behave as if |
| 175 | `protocol=https` and `host=example.com` had been provided). This |
| 176 | can help callers avoid parsing URLs themselves. |
| 177 | + |
| 178 | Note that specifying a protocol is mandatory and if the URL |
| 179 | doesn't specify a hostname (e.g., "cert:///path/to/file") the |
| 180 | credential will contain a hostname attribute whose value is an |
| 181 | empty string. |
| 182 | + |
| 183 | Components which are missing from the URL (e.g., there is no |
| 184 | username in the example above) will be left unset. |
| 185 | |
| 186 | `authtype`:: |
| 187 | This indicates that the authentication scheme in question should be used. |
| 188 | Common values for HTTP and HTTPS include `basic`, `bearer`, and `digest`, |
| 189 | although the latter is insecure and should not be used. If `credential` |
| 190 | is used, this may be set to an arbitrary string suitable for the protocol in |
| 191 | question (usually HTTP). |
| 192 | + |
| 193 | This value should not be sent unless the appropriate capability (see below) is |
| 194 | provided on input. |
| 195 | |
| 196 | `credential`:: |
| 197 | The pre-encoded credential, suitable for the protocol in question (usually |
| 198 | HTTP). If this key is sent, `authtype` is mandatory, and `username` and |
| 199 | `password` are not used. For HTTP, Git concatenates the `authtype` value and |
| 200 | this value with a single space to determine the `Authorization` header. |
| 201 | + |
| 202 | This value should not be sent unless the appropriate capability (see below) is |
| 203 | provided on input. |
| 204 | |
| 205 | `ephemeral`:: |
| 206 | This boolean value indicates, if true, that the value in the `credential` |
| 207 | field should not be saved by the credential helper because its usefulness is |
| 208 | limited in time. For example, an HTTP Digest `credential` value is computed |
| 209 | using a nonce and reusing it will not result in successful authentication. |
| 210 | This may also be used for situations with short duration (e.g., 24-hour) |
| 211 | credentials. The default value is false. |
| 212 | + |
| 213 | The credential helper will still be invoked with `store` or `erase` so that it |
| 214 | can determine whether the operation was successful. |
| 215 | + |
| 216 | This value should not be sent unless the appropriate capability (see below) is |
| 217 | provided on input. |
| 218 | |
| 219 | `state[]`:: |
| 220 | This value provides an opaque state that will be passed back to this helper |
| 221 | if it is called again. Each different credential helper may specify this |
| 222 | once. The value should include a prefix unique to the credential helper and |
| 223 | should ignore values that don't match its prefix. |
| 224 | + |
| 225 | This value should not be sent unless the appropriate capability (see below) is |
| 226 | provided on input. |
| 227 | |
| 228 | `continue`:: |
| 229 | This is a boolean value, which, if enabled, indicates that this |
| 230 | authentication is a non-final part of a multistage authentication step. This |
| 231 | is common in protocols such as NTLM and Kerberos, where two rounds of client |
| 232 | authentication are required, and setting this flag allows the credential |
| 233 | helper to implement the multistage authentication step. This flag should |
| 234 | only be sent if a further stage is required; that is, if another round of |
| 235 | authentication is expected. |
| 236 | + |
| 237 | This value should not be sent unless the appropriate capability (see below) is |
| 238 | provided on input. This attribute is 'one-way' from a credential helper to |
| 239 | pass information to Git (or other programs invoking `git credential`). |
| 240 | |
| 241 | `wwwauth[]`:: |
| 242 | |
| 243 | When an HTTP response is received by Git that includes one or more |
| 244 | 'WWW-Authenticate' authentication headers, these will be passed by Git |
| 245 | to credential helpers. |
| 246 | + |
| 247 | Each 'WWW-Authenticate' header value is passed as a multi-valued |
| 248 | attribute 'wwwauth[]', where the order of the attributes is the same as |
| 249 | they appear in the HTTP response. This attribute is 'one-way' from Git |
| 250 | to pass additional information to credential helpers. |
| 251 | |
| 252 | `capability[]`:: |
| 253 | This signals that Git, or the helper, as appropriate, supports the capability |
| 254 | in question. This can be used to provide better, more specific data as part |
| 255 | of the protocol. A `capability[]` directive must precede any value depending |
| 256 | on it and these directives _should_ be the first item announced in the |
| 257 | protocol. |
| 258 | + |
| 259 | There are two currently supported capabilities. The first is `authtype`, which |
| 260 | indicates that the `authtype`, `credential`, and `ephemeral` values are |
| 261 | understood. The second is `state`, which indicates that the `state[]` and |
| 262 | `continue` values are understood. |
| 263 | + |
| 264 | It is not obligatory to use the additional features just because the capability |
| 265 | is supported, but they should not be provided without the capability. |
| 266 | |
| 267 | Unrecognised attributes and capabilities are silently discarded. |
| 268 | |
| 269 | [[CAPA-IOFMT]] |
| 270 | CAPABILITY INPUT/OUTPUT FORMAT |
| 271 | ------------------------------ |
| 272 | |
| 273 | For `git credential capability`, the format is slightly different. First, a |
| 274 | `version 0` announcement is made to indicate the current version of the |
| 275 | protocol, and then each capability is announced with a line like `capability |
| 276 | authtype`. Credential helpers may also implement this format, again with the |
| 277 | `capability` argument. Additional lines may be added in the future; callers |
| 278 | should ignore lines which they don't understand. |
| 279 | |
| 280 | Because this is a new part of the credential helper protocol, older versions of |
| 281 | Git, as well as some credential helpers, may not support it. If a non-zero |
| 282 | exit status is received, or if the first line doesn't start with the word |
| 283 | `version` and a space, callers should assume that no capabilities are supported. |
| 284 | |
| 285 | The intention of this format is to differentiate it from the credential output |
| 286 | in an unambiguous way. It is possible to use very simple credential helpers |
| 287 | (e.g., inline shell scripts) which always produce identical output. Using a |
| 288 | distinct format allows users to continue to use this syntax without having to |
| 289 | worry about correctly implementing capability advertisements or accidentally |
| 290 | confusing callers querying for capabilities. |
| 291 | |
| 292 | GIT |
| 293 | --- |
| 294 | Part of the linkgit:git[1] suite |