diff options
Diffstat (limited to 'third_party/git/credential.h')
| -rw-r--r-- | third_party/git/credential.h | 162 |
1 files changed, 1 insertions, 161 deletions
diff --git a/third_party/git/credential.h b/third_party/git/credential.h index d99ec42b2a8c..6b0cd16be2b9 100644 --- a/third_party/git/credential.h +++ b/third_party/git/credential.h @@ -3,123 +3,12 @@ #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; - * } - * ----------------------------------------------------------------------- - */ - - -/** - * 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, - use_http_path:1, - username_from_proto:1; + use_http_path:1; char *username; char *password; @@ -130,65 +19,16 @@ 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 a credential struct, replacing any existing contents. - * - * If the url can't be parsed (e.g., a missing "proto://" component), the - * resulting credential will be empty but we'll still return success from the - * "gently" form. - * - * If we encounter a component which cannot be represented as a credential - * value (e.g., because it contains a newline), the "gently" form will return - * an error but leave the broken state in the credential object for further - * examination. The non-gentle form will issue a warning to stderr and return - * an empty credential. - */ void credential_from_url(struct credential *, const char *url); -int credential_from_url_gently(struct credential *, const char *url, int quiet); - int credential_match(const struct credential *have, const struct credential *want); |