diff options
| -rw-r--r-- | Documentation/git-credential.txt | 3 | ||||
| -rw-r--r-- | Documentation/gitcredentials.txt | 3 | ||||
| -rw-r--r-- | Documentation/technical/api-credentials.txt | 271 | ||||
| -rw-r--r-- | credential.h | 236 |
4 files changed, 238 insertions, 275 deletions
diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index b211440373..6f0c7ca80f 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -19,8 +19,7 @@ from system-specific helpers, as well as prompting the user for usernames and passwords. The git-credential command exposes this interface to scripts which may want to retrieve, store, or prompt for credentials in the same manner as Git. The design of this scriptable -interface models the internal C API; see -link:technical/api-credentials.html[the Git credential API] for more +interface models the internal C API; see credential.h for more background on the concepts. git-credential takes an "action" option on the command-line (one of diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index adc759612d..ea759fdee5 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -186,8 +186,7 @@ CUSTOM HELPERS -------------- You can write your own custom helpers to interface with any system in -which you keep credentials. See the documentation for Git's -link:technical/api-credentials.html[credentials API] for details. +which you keep credentials. See credential.h for details. GIT --- diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt deleted file mode 100644 index 75368f26ca..0000000000 --- a/Documentation/technical/api-credentials.txt +++ /dev/null @@ -1,271 +0,0 @@ -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[1] 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[1] (See configuration variables `credential.*`) 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); |