1credentials API 2=============== 3 4The credentials API provides an abstracted way of gathering username and 5password credentials from the user (even though credentials in the wider 6world can take many forms, in this document the word "credential" always 7refers to a username and password pair). 8 9Data 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+ 21The `helpers` member of the struct is a `string_list` of helpers. Each 22string specifies an external helper which will be run, in order, to 23either acquire or store credentials. See the section on credential 24helpers below. 25+ 26This struct should always be initialized with `CREDENTIAL_INIT` or 27`credential_init`. 28 29 30Functions 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 70Example 71------- 72 73The example below shows how the functions of the credential API could be 74used to login to a fictitious "foo" service on a remote host: 75 76----------------------------------------------------------------------- 77int 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 126Credential Helpers 127------------------ 128 129Credential helpers are programs executed by git to fetch or save 130credentials from and to long-term storage (where "long-term" is simply 131longer than a single git process; e.g., credentials may be stored 132in-memory for a few minutes, or indefinitely on disk). 133 134Each helper is specified by a single string. The string is transformed 135by 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 146The resulting command then has an "operation" argument appended to it 147(see below for details), and the result is executed by the shell. 148 149Here are some example specifications: 150 151---------------------------------------------------- 152# run "git credential-foo" 153foo 154 155# same as above, but pass an argument to the helper 156foo --bar=baz 157 158# the arguments are parsed by the shell, so use shell 159# quoting if necessary 160foo --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 169Generally speaking, rule (3) above is the simplest for users to specify. 170Authors of credential helpers should make an effort to assist their 171users by naming their program "git-credential-$NAME", and putting it in 172the $PATH or $GIT_EXEC_PATH during installation, which will allow a user 173to enable it with `git config credential.helper $NAME`. 174 175When a helper is executed, it will have one "operation" argument 176appended 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 190The details of the credential will be provided on the helper's stdin 191stream. The credential is split into a set of named attributes. 192Attributes are provided to the helper, one per line. Each attribute is 193specified by a key-value pair, separated by an `=` (equals) sign, 194followed by a newline. The key may contain any bytes except `=`, 195newline, or NUL. The value may contain any bytes except newline or NUL. 196In both cases, all bytes are treated as-is (i.e., there is no quoting, 197and one cannot transmit a value with newline or NUL in it). The list of 198attributes is terminated by a blank line or end-of-file. 199 200Git will send the following attributes (but may not send all of 201them for a given credential; for example, a `host` attribute makes no 202sense 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 228For a `get` operation, the helper should produce a list of attributes 229on stdout in the same format. A helper is free to produce a subset, or 230even no values at all if it has nothing useful to provide. Any provided 231attributes will overwrite those already known about by git. 232 233For a `store` or `erase` operation, the helper's output is ignored. 234If it fails to perform the requested operation, it may complain to 235stderr to inform the user. If it does not support the requested 236operation (e.g., a read-only store), it should silently ignore the 237request. 238 239If a helper receives any other operation, it should silently ignore the 240request. This leaves room for future operations to be added (older 241helpers will just ignore the new requests).