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