diff options
Diffstat (limited to 'credential.h')
| -rw-r--r-- | credential.h | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/credential.h b/credential.h index 6b0cd16be2..5772d50577 100644 --- a/credential.h +++ b/credential.h @@ -3,8 +3,208 @@ #include "string-list.h" +/** + * The credentials API provides an abstracted way of gathering username and + * password credentials from the user. + * + * 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). + * + * 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 Documentation/git-config.txt). + * 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 Documentation/git-credential.txt 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). + * + */ + + +/** + * 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. + * + * This struct should always be initialized with `CREDENTIAL_INIT` or + * `credential_init`. + */ struct credential { + + /** + * A `string_list` of helpers. Each string specifies an external + * helper which will be run, in order, to either acquire or store + * credentials. 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. + */ struct string_list helpers; + unsigned approved:1, configured:1, quit:1, @@ -19,16 +219,52 @@ struct credential { #define CREDENTIAL_INIT { STRING_LIST_INIT_DUP } +/* Initialize a credential structure, setting all fields to empty. */ void credential_init(struct credential *); + +/** + * Free any resources associated with the credential structure, returning + * it to a pristine initialized state. + */ void credential_clear(struct credential *); +/** + * 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(). + */ void credential_fill(struct credential *); + +/** + * 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. + */ void credential_approve(struct credential *); + +/** + * 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. + */ void credential_reject(struct credential *); int credential_read(struct credential *, FILE *); void credential_write(const struct credential *, FILE *); + +/* Parse a URL into broken-down credential fields. */ void credential_from_url(struct credential *, const char *url); + int credential_match(const struct credential *have, const struct credential *want); |