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