Documentation/technical/api-credentials.txt

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