| credentials API |
| =============== |
| |
| The credentials API provides an abstracted way of gathering username and |
| password credentials from the user (even though credentials in the wider |
| world can take many forms, in this document the word "credential" always |
| refers to a username and password pair). |
| |
| This document describes two interfaces: the C API that the credential |
| subsystem provides to the rest of Git, and the protocol that Git uses to |
| communicate with system-specific "credential helpers". If you are |
| writing Git code that wants to look up or prompt for credentials, see |
| the section "C API" below. If you want to write your own helper, see |
| the section on "Credential Helpers" below. |
| |
| Typical setup |
| ------------- |
| |
| ------------ |
| +-----------------------+ |
| | Git code (C) |--- to server requiring ---> |
| | | authentication |
| |.......................| |
| | C credential API |--- prompt ---> User |
| +-----------------------+ |
| ^ | |
| | pipe | |
| | v |
| +-----------------------+ |
| | Git credential helper | |
| +-----------------------+ |
| ------------ |
| |
| The Git code (typically a remote-helper) will call the C API to obtain |
| credential data like a login/password pair (credential_fill). The |
| API will itself call a remote helper (e.g. "git credential-cache" or |
| "git credential-store") that may retrieve credential data from a |
| store. If the credential helper cannot find the information, the C API |
| will prompt the user. Then, the caller of the API takes care of |
| contacting the server, and does the actual authentication. |
| |
| C API |
| ----- |
| |
| The credential C API is meant to be called by Git code which needs to |
| acquire or store a credential. It is centered around an object |
| representing a single credential and provides three basic operations: |
| fill (acquire credentials by calling helpers and/or prompting the user), |
| approve (mark a credential as successfully used so that it can be stored |
| for later use), and reject (mark a credential as unsuccessful so that it |
| can be erased from any persistent storage). |
| |
| Data Structures |
| ~~~~~~~~~~~~~~~ |
| |
| `struct credential`:: |
| |
| This struct represents a single username/password combination |
| along with any associated context. All string fields should be |
| heap-allocated (or NULL if they are not known or not applicable). |
| The meaning of the individual context fields is the same as |
| their counterparts in the helper protocol; see the section below |
| for a description of each field. |
| + |
| The `helpers` member of the struct is a `string_list` of helpers. Each |
| string specifies an external helper which will be run, in order, to |
| either acquire or store credentials. See the section on credential |
| helpers below. This list is filled-in by the API functions |
| according to the corresponding configuration variables before |
| consulting helpers, so there usually is no need for a caller to |
| modify the helpers field at all. |
| + |
| This struct should always be initialized with `CREDENTIAL_INIT` or |
| `credential_init`. |
| |
| |
| Functions |
| ~~~~~~~~~ |
| |
| `credential_init`:: |
| |
| Initialize a credential structure, setting all fields to empty. |
| |
| `credential_clear`:: |
| |
| Free any resources associated with the credential structure, |
| returning it to a pristine initialized state. |
| |
| `credential_fill`:: |
| |
| Instruct the credential subsystem to fill the username and |
| password fields of the passed credential struct by first |
| consulting helpers, then asking the user. After this function |
| returns, the username and password fields of the credential are |
| guaranteed to be non-NULL. If an error occurs, the function will |
| die(). |
| |
| `credential_reject`:: |
| |
| Inform the credential subsystem that the provided credentials |
| have been rejected. This will cause the credential subsystem to |
| notify any helpers of the rejection (which allows them, for |
| example, to purge the invalid credentials from storage). It |
| will also free() the username and password fields of the |
| credential and set them to NULL (readying the credential for |
| another call to `credential_fill`). Any errors from helpers are |
| ignored. |
| |
| `credential_approve`:: |
| |
| Inform the credential subsystem that the provided credentials |
| were successfully used for authentication. This will cause the |
| credential subsystem to notify any helpers of the approval, so |
| that they may store the result to be used again. Any errors |
| from helpers are ignored. |
| |
| `credential_from_url`:: |
| |
| Parse a URL into broken-down credential fields. |
| |
| Example |
| ~~~~~~~ |
| |
| The example below shows how the functions of the credential API could be |
| used to login to a fictitious "foo" service on a remote host: |
| |
| ----------------------------------------------------------------------- |
| int foo_login(struct foo_connection *f) |
| { |
| int status; |
| /* |
| * Create a credential with some context; we don't yet know the |
| * username or password. |
| */ |
| |
| struct credential c = CREDENTIAL_INIT; |
| c.protocol = xstrdup("foo"); |
| c.host = xstrdup(f->hostname); |
| |
| /* |
| * Fill in the username and password fields by contacting |
| * helpers and/or asking the user. The function will die if it |
| * fails. |
| */ |
| credential_fill(&c); |
| |
| /* |
| * Otherwise, we have a username and password. Try to use it. |
| */ |
| status = send_foo_login(f, c.username, c.password); |
| switch (status) { |
| case FOO_OK: |
| /* It worked. Store the credential for later use. */ |
| credential_accept(&c); |
| break; |
| case FOO_BAD_LOGIN: |
| /* Erase the credential from storage so we don't try it |
| * again. */ |
| credential_reject(&c); |
| break; |
| default: |
| /* |
| * Some other error occurred. We don't know if the |
| * credential is good or bad, so report nothing to the |
| * credential subsystem. |
| */ |
| } |
| |
| /* Free any associated resources. */ |
| credential_clear(&c); |
| |
| return status; |
| } |
| ----------------------------------------------------------------------- |
| |
| |
| Credential Helpers |
| ------------------ |
| |
| Credential helpers are programs executed by Git to fetch or save |
| credentials from and to long-term storage (where "long-term" is simply |
| longer than a single Git process; e.g., credentials may be stored |
| in-memory for a few minutes, or indefinitely on disk). |
| |
| Each helper is specified by a single string in the configuration |
| variable `credential.helper` (and others, see linkgit:git-config[1]). |
| The string is transformed by Git into a command to be executed using |
| these rules: |
| |
| 1. If the helper string begins with "!", it is considered a shell |
| snippet, and everything after the "!" becomes the command. |
| |
| 2. Otherwise, if the helper string begins with an absolute path, the |
| verbatim helper string becomes the command. |
| |
| 3. Otherwise, the string "git credential-" is prepended to the helper |
| string, and the result becomes the command. |
| |
| The resulting command then has an "operation" argument appended to it |
| (see below for details), and the result is executed by the shell. |
| |
| Here are some example specifications: |
| |
| ---------------------------------------------------- |
| # run "git credential-foo" |
| foo |
| |
| # same as above, but pass an argument to the helper |
| foo --bar=baz |
| |
| # the arguments are parsed by the shell, so use shell |
| # quoting if necessary |
| foo --bar="whitespace arg" |
| |
| # you can also use an absolute path, which will not use the git wrapper |
| /path/to/my/helper --with-arguments |
| |
| # or you can specify your own shell snippet |
| !f() { echo "password=`cat $HOME/.secret`"; }; f |
| ---------------------------------------------------- |
| |
| Generally speaking, rule (3) above is the simplest for users to specify. |
| Authors of credential helpers should make an effort to assist their |
| users by naming their program "git-credential-$NAME", and putting it in |
| the $PATH or $GIT_EXEC_PATH during installation, which will allow a user |
| to enable it with `git config credential.helper $NAME`. |
| |
| When a helper is executed, it will have one "operation" argument |
| appended to its command line, which is one of: |
| |
| `get`:: |
| |
| Return a matching credential, if any exists. |
| |
| `store`:: |
| |
| Store the credential, if applicable to the helper. |
| |
| `erase`:: |
| |
| Remove a matching credential, if any, from the helper's storage. |
| |
| The details of the credential will be provided on the helper's stdin |
| stream. The exact format is the same as the input/output format of the |
| `git credential` plumbing command (see the section `INPUT/OUTPUT |
| FORMAT` in linkgit:git-credential[7] for a detailed specification). |
| |
| For a `get` operation, the helper should produce a list of attributes |
| on stdout in the same format. A helper is free to produce a subset, or |
| even no values at all if it has nothing useful to provide. Any provided |
| attributes will overwrite those already known about by Git. If a helper |
| outputs a `quit` attribute with a value of `true` or `1`, no further |
| helpers will be consulted, nor will the user be prompted (if no |
| credential has been provided, the operation will then fail). |
| |
| For a `store` or `erase` operation, the helper's output is ignored. |
| If it fails to perform the requested operation, it may complain to |
| stderr to inform the user. If it does not support the requested |
| operation (e.g., a read-only store), it should silently ignore the |
| request. |
| |
| If a helper receives any other operation, it should silently ignore the |
| request. This leaves room for future operations to be added (older |
| helpers will just ignore the new requests). |
| |
| See also |
| -------- |
| |
| linkgit:gitcredentials[7] |
| |
| linkgit:git-config[5] (See configuration variables `credential.*`) |