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 9This document describes two interfaces: the C API that the credential 10subsystem provides to the rest of Git, and the protocol that Git uses to 11communicate with system-specific "credential helpers". If you are 12writing Git code that wants to look up or prompt for credentials, see 13the section "C API" below. If you want to write your own helper, see 14the section on "Credential Helpers" below. 15 16Typical setup 17------------- 18 19------------ 20+-----------------------+ 21| Git code (C) |--- to server requiring ---> 22| | authentication 23|.......................| 24| C credential API |--- prompt ---> User 25+-----------------------+ 26 ^ | 27 | pipe | 28 | v 29+-----------------------+ 30| Git credential helper | 31+-----------------------+ 32------------ 33 34The Git code (typically a remote-helper) will call the C API to obtain 35credential data like a login/password pair (credential_fill). The 36API will itself call a remote helper (e.g. "git credential-cache" or 37"git credential-store") that may retrieve credential data from a 38store. If the credential helper cannot find the information, the C API 39will prompt the user. Then, the caller of the API takes care of 40contacting the server, and does the actual authentication. 41 42C API 43----- 44 45The credential C API is meant to be called by Git code which needs to 46acquire or store a credential. It is centered around an object 47representing a single credential and provides three basic operations: 48fill (acquire credentials by calling helpers and/or prompting the user), 49approve (mark a credential as successfully used so that it can be stored 50for later use), and reject (mark a credential as unsuccessful so that it 51can be erased from any persistent storage). 52 53Data Structures 54~~~~~~~~~~~~~~~ 55 56`struct credential`:: 57 58 This struct represents a single username/password combination 59 along with any associated context. All string fields should be 60 heap-allocated (or NULL if they are not known or not applicable). 61 The meaning of the individual context fields is the same as 62 their counterparts in the helper protocol; see the section below 63 for a description of each field. 64+ 65The `helpers` member of the struct is a `string_list` of helpers. Each 66string specifies an external helper which will be run, in order, to 67either acquire or store credentials. See the section on credential 68helpers below. This list is filled-in by the API functions 69according to the corresponding configuration variables before 70consulting helpers, so there usually is no need for a caller to 71modify the helpers field at all. 72+ 73This struct should always be initialized with `CREDENTIAL_INIT` or 74`credential_init`. 75 76 77Functions 78~~~~~~~~~ 79 80`credential_init`:: 81 82 Initialize a credential structure, setting all fields to empty. 83 84`credential_clear`:: 85 86 Free any resources associated with the credential structure, 87 returning it to a pristine initialized state. 88 89`credential_fill`:: 90 91 Instruct the credential subsystem to fill the username and 92 password fields of the passed credential struct by first 93 consulting helpers, then asking the user. After this function 94 returns, the username and password fields of the credential are 95 guaranteed to be non-NULL. If an error occurs, the function will 96 die(). 97 98`credential_reject`:: 99 100 Inform the credential subsystem that the provided credentials 101 have been rejected. This will cause the credential subsystem to 102 notify any helpers of the rejection (which allows them, for 103 example, to purge the invalid credentials from storage). It 104 will also free() the username and password fields of the 105 credential and set them to NULL (readying the credential for 106 another call to `credential_fill`). Any errors from helpers are 107 ignored. 108 109`credential_approve`:: 110 111 Inform the credential subsystem that the provided credentials 112 were successfully used for authentication. This will cause the 113 credential subsystem to notify any helpers of the approval, so 114 that they may store the result to be used again. Any errors 115 from helpers are ignored. 116 117`credential_from_url`:: 118 119 Parse a URL into broken-down credential fields. 120 121Example 122~~~~~~~ 123 124The example below shows how the functions of the credential API could be 125used to login to a fictitious "foo" service on a remote host: 126 127----------------------------------------------------------------------- 128int foo_login(struct foo_connection *f) 129{ 130 int status; 131 /* 132 * Create a credential with some context; we don't yet know the 133 * username or password. 134 */ 135 136 struct credential c = CREDENTIAL_INIT; 137 c.protocol = xstrdup("foo"); 138 c.host = xstrdup(f->hostname); 139 140 /* 141 * Fill in the username and password fields by contacting 142 * helpers and/or asking the user. The function will die if it 143 * fails. 144 */ 145 credential_fill(&c); 146 147 /* 148 * Otherwise, we have a username and password. Try to use it. 149 */ 150 status = send_foo_login(f, c.username, c.password); 151 switch (status) { 152 case FOO_OK: 153 /* It worked. Store the credential for later use. */ 154 credential_accept(&c); 155 break; 156 case FOO_BAD_LOGIN: 157 /* Erase the credential from storage so we don't try it 158 * again. */ 159 credential_reject(&c); 160 break; 161 default: 162 /* 163 * Some other error occurred. We don't know if the 164 * credential is good or bad, so report nothing to the 165 * credential subsystem. 166 */ 167 } 168 169 /* Free any associated resources. */ 170 credential_clear(&c); 171 172 return status; 173} 174----------------------------------------------------------------------- 175 176 177Credential Helpers 178------------------ 179 180Credential helpers are programs executed by Git to fetch or save 181credentials from and to long-term storage (where "long-term" is simply 182longer than a single Git process; e.g., credentials may be stored 183in-memory for a few minutes, or indefinitely on disk). 184 185Each helper is specified by a single string in the configuration 186variable `credential.helper` (and others, see linkgit:git-config[1]). 187The string is transformed by Git into a command to be executed using 188these rules: 189 190 1. If the helper string begins with "!", it is considered a shell 191 snippet, and everything after the "!" becomes the command. 192 193 2. Otherwise, if the helper string begins with an absolute path, the 194 verbatim helper string becomes the command. 195 196 3. Otherwise, the string "git credential-" is prepended to the helper 197 string, and the result becomes the command. 198 199The resulting command then has an "operation" argument appended to it 200(see below for details), and the result is executed by the shell. 201 202Here are some example specifications: 203 204---------------------------------------------------- 205# run "git credential-foo" 206foo 207 208# same as above, but pass an argument to the helper 209foo --bar=baz 210 211# the arguments are parsed by the shell, so use shell 212# quoting if necessary 213foo --bar="whitespace arg" 214 215# you can also use an absolute path, which will not use the git wrapper 216/path/to/my/helper --with-arguments 217 218# or you can specify your own shell snippet 219!f() { echo "password=`cat $HOME/.secret`"; }; f 220---------------------------------------------------- 221 222Generally speaking, rule (3) above is the simplest for users to specify. 223Authors of credential helpers should make an effort to assist their 224users by naming their program "git-credential-$NAME", and putting it in 225the $PATH or $GIT_EXEC_PATH during installation, which will allow a user 226to enable it with `git config credential.helper $NAME`. 227 228When a helper is executed, it will have one "operation" argument 229appended to its command line, which is one of: 230 231`get`:: 232 233 Return a matching credential, if any exists. 234 235`store`:: 236 237 Store the credential, if applicable to the helper. 238 239`erase`:: 240 241 Remove a matching credential, if any, from the helper's storage. 242 243The details of the credential will be provided on the helper's stdin 244stream. The exact format is the same as the input/output format of the 245`git credential` plumbing command (see the section `INPUT/OUTPUT 246FORMAT` in linkgit:git-credential[7] for a detailed specification). 247 248For a `get` operation, the helper should produce a list of attributes 249on stdout in the same format. A helper is free to produce a subset, or 250even no values at all if it has nothing useful to provide. Any provided 251attributes will overwrite those already known about by Git. 252 253For a `store` or `erase` operation, the helper's output is ignored. 254If it fails to perform the requested operation, it may complain to 255stderr to inform the user. If it does not support the requested 256operation (e.g., a read-only store), it should silently ignore the 257request. 258 259If a helper receives any other operation, it should silently ignore the 260request. This leaves room for future operations to be added (older 261helpers will just ignore the new requests). 262 263See also 264-------- 265 266linkgit:gitcredentials[7] 267 268linkgit:git-config[5] (See configuration variables `credential.*`)