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. The string is transformed
 183 by git into a command to be executed using these rules:
 184
 185   1. If the helper string begins with "!", it is considered a shell
 186      snippet, and everything after the "!" becomes the command.
 187
 188   2. Otherwise, if the helper string begins with an absolute path, the
 189      verbatim helper string becomes the command.
 190
 191   3. Otherwise, the string "git credential-" is prepended to the helper
 192      string, and the result becomes the command.
 193
 194 The resulting command then has an "operation" argument appended to it
 195 (see below for details), and the result is executed by the shell.
 196
 197 Here are some example specifications:
 198
 199 ----------------------------------------------------
 200 # run "git credential-foo"
 201 foo
 202
 203 # same as above, but pass an argument to the helper
 204 foo --bar=baz
 205
 206 # the arguments are parsed by the shell, so use shell
 207 # quoting if necessary
 208 foo --bar="whitespace arg"
 209
 210 # you can also use an absolute path, which will not use the git wrapper
 211 /path/to/my/helper --with-arguments
 212
 213 # or you can specify your own shell snippet
 214 !f() { echo "password=`cat $HOME/.secret`"; }; f
 215 ----------------------------------------------------
 216
 217 Generally speaking, rule (3) above is the simplest for users to specify.
 218 Authors of credential helpers should make an effort to assist their
 219 users by naming their program "git-credential-$NAME", and putting it in
 220 the $PATH or $GIT_EXEC_PATH during installation, which will allow a user
 221 to enable it with `git config credential.helper $NAME`.
 222
 223 When a helper is executed, it will have one "operation" argument
 224 appended to its command line, which is one of:
 225
 226 `get`::
 227
 228         Return a matching credential, if any exists.
 229
 230 `store`::
 231
 232         Store the credential, if applicable to the helper.
 233
 234 `erase`::
 235
 236         Remove a matching credential, if any, from the helper's storage.
 237
 238 The details of the credential will be provided on the helper's stdin
 239 stream. The credential is split into a set of named attributes.
 240 Attributes are provided to the helper, one per line. Each attribute is
 241 specified by a key-value pair, separated by an `=` (equals) sign,
 242 followed by a newline. The key may contain any bytes except `=`,
 243 newline, or NUL. The value may contain any bytes except newline or NUL.
 244 In both cases, all bytes are treated as-is (i.e., there is no quoting,
 245 and one cannot transmit a value with newline or NUL in it). The list of
 246 attributes is terminated by a blank line or end-of-file.
 247
 248 Git will send the following attributes (but may not send all of
 249 them for a given credential; for example, a `host` attribute makes no
 250 sense when dealing with a non-network protocol):
 251
 252 `protocol`::
 253
 254         The protocol over which the credential will be used (e.g.,
 255         `https`).
 256
 257 `host`::
 258
 259         The remote hostname for a network credential.
 260
 261 `path`::
 262
 263         The path with which the credential will be used. E.g., for
 264         accessing a remote https repository, this will be the
 265         repository's path on the server.
 266
 267 `username`::
 268
 269         The credential's username, if we already have one (e.g., from a
 270         URL, from the user, or from a previously run helper).
 271
 272 `password`::
 273
 274         The credential's password, if we are asking it to be stored.
 275
 276 For a `get` operation, the helper should produce a list of attributes
 277 on stdout in the same format. A helper is free to produce a subset, or
 278 even no values at all if it has nothing useful to provide. Any provided
 279 attributes will overwrite those already known about by git.
 280
 281 For a `store` or `erase` operation, the helper's output is ignored.
 282 If it fails to perform the requested operation, it may complain to
 283 stderr to inform the user. If it does not support the requested
 284 operation (e.g., a read-only store), it should silently ignore the
 285 request.
 286
 287 If a helper receives any other operation, it should silently ignore the
 288 request. This leaves room for future operations to be added (older
 289 helpers will just ignore the new requests).