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 70`credential_from_url`:: 71 72 Parse a URL into broken-down credential fields. 73 74Example 75------- 76 77The example below shows how the functions of the credential API could be 78used to login to a fictitious "foo" service on a remote host: 79 80----------------------------------------------------------------------- 81int foo_login(struct foo_connection *f) 82{ 83 int status; 84 /* 85 * Create a credential with some context; we don't yet know the 86 * username or password. 87 */ 88 89 struct credential c = CREDENTIAL_INIT; 90 c.protocol = xstrdup("foo"); 91 c.host = xstrdup(f->hostname); 92 93 /* 94 * Fill in the username and password fields by contacting 95 * helpers and/or asking the user. The function will die if it 96 * fails. 97 */ 98 credential_fill(&c); 99 100 /* 101 * Otherwise, we have a username and password. Try to use it. 102 */ 103 status = send_foo_login(f, c.username, c.password); 104 switch (status) { 105 case FOO_OK: 106 /* It worked. Store the credential for later use. */ 107 credential_accept(&c); 108 break; 109 case FOO_BAD_LOGIN: 110 /* Erase the credential from storage so we don't try it 111 * again. */ 112 credential_reject(&c); 113 break; 114 default: 115 /* 116 * Some other error occured. We don't know if the 117 * credential is good or bad, so report nothing to the 118 * credential subsystem. 119 */ 120 } 121 122 /* Free any associated resources. */ 123 credential_clear(&c); 124 125 return status; 126} 127----------------------------------------------------------------------- 128 129 130Credential Helpers 131------------------ 132 133Credential helpers are programs executed by git to fetch or save 134credentials from and to long-term storage (where "long-term" is simply 135longer than a single git process; e.g., credentials may be stored 136in-memory for a few minutes, or indefinitely on disk). 137 138Each helper is specified by a single string. The string is transformed 139by git into a command to be executed using these rules: 140 141 1. If the helper string begins with "!", it is considered a shell 142 snippet, and everything after the "!" becomes the command. 143 144 2. Otherwise, if the helper string begins with an absolute path, the 145 verbatim helper string becomes the command. 146 147 3. Otherwise, the string "git credential-" is prepended to the helper 148 string, and the result becomes the command. 149 150The resulting command then has an "operation" argument appended to it 151(see below for details), and the result is executed by the shell. 152 153Here are some example specifications: 154 155---------------------------------------------------- 156# run "git credential-foo" 157foo 158 159# same as above, but pass an argument to the helper 160foo --bar=baz 161 162# the arguments are parsed by the shell, so use shell 163# quoting if necessary 164foo --bar="whitespace arg" 165 166# you can also use an absolute path, which will not use the git wrapper 167/path/to/my/helper --with-arguments 168 169# or you can specify your own shell snippet 170!f() { echo "password=`cat $HOME/.secret`"; }; f 171---------------------------------------------------- 172 173Generally speaking, rule (3) above is the simplest for users to specify. 174Authors of credential helpers should make an effort to assist their 175users by naming their program "git-credential-$NAME", and putting it in 176the $PATH or $GIT_EXEC_PATH during installation, which will allow a user 177to enable it with `git config credential.helper $NAME`. 178 179When a helper is executed, it will have one "operation" argument 180appended to its command line, which is one of: 181 182`get`:: 183 184 Return a matching credential, if any exists. 185 186`store`:: 187 188 Store the credential, if applicable to the helper. 189 190`erase`:: 191 192 Remove a matching credential, if any, from the helper's storage. 193 194The details of the credential will be provided on the helper's stdin 195stream. The credential is split into a set of named attributes. 196Attributes are provided to the helper, one per line. Each attribute is 197specified by a key-value pair, separated by an `=` (equals) sign, 198followed by a newline. The key may contain any bytes except `=`, 199newline, or NUL. The value may contain any bytes except newline or NUL. 200In both cases, all bytes are treated as-is (i.e., there is no quoting, 201and one cannot transmit a value with newline or NUL in it). The list of 202attributes is terminated by a blank line or end-of-file. 203 204Git will send the following attributes (but may not send all of 205them for a given credential; for example, a `host` attribute makes no 206sense when dealing with a non-network protocol): 207 208`protocol`:: 209 210 The protocol over which the credential will be used (e.g., 211 `https`). 212 213`host`:: 214 215 The remote hostname for a network credential. 216 217`path`:: 218 219 The path with which the credential will be used. E.g., for 220 accessing a remote https repository, this will be the 221 repository's path on the server. 222 223`username`:: 224 225 The credential's username, if we already have one (e.g., from a 226 URL, from the user, or from a previously run helper). 227 228`password`:: 229 230 The credential's password, if we are asking it to be stored. 231 232For a `get` operation, the helper should produce a list of attributes 233on stdout in the same format. A helper is free to produce a subset, or 234even no values at all if it has nothing useful to provide. Any provided 235attributes will overwrite those already known about by git. 236 237For a `store` or `erase` operation, the helper's output is ignored. 238If it fails to perform the requested operation, it may complain to 239stderr to inform the user. If it does not support the requested 240operation (e.g., a read-only store), it should silently ignore the 241request. 242 243If a helper receives any other operation, it should silently ignore the 244request. This leaves room for future operations to be added (older 245helpers will just ignore the new requests).