git/credential.h
brian m. carlson ffff4ac065 credential: add method for querying capabilities
Right now, there's no specific way to determine whether a credential
helper or git credential itself supports a given set of capabilities.
It would be helpful to have such a way, so let's let credential helpers
and git credential take an argument, "capability", which has it list the
capabilities and a version number on standard output.

Specifically choose a format that is slightly different from regular
credential output and assume that no capabilities are supported if a
non-zero exit status occurs or the data deviates from the format.  It is
common for users to write small shell scripts as the argument to
credential.helper, which will almost never be designed to emit
capabilities.  We want callers to gracefully handle this case by
assuming that they are not capable of extended support because that is
almost certainly the case, and specifying the error behavior up front
does this and preserves backwards compatibility in a graceful way.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2024-04-16 22:39:08 -07:00

303 lines
9.6 KiB
C

#ifndef CREDENTIAL_H
#define CREDENTIAL_H
#include "string-list.h"
#include "strvec.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;
* }
* -----------------------------------------------------------------------
*/
/*
* These values define the kind of operation we're performing and the
* capabilities at each stage. The first is either an external request (via git
* credential fill) or an internal request (e.g., via the HTTP) code. The
* second is the call to the credential helper, and the third is the response
* we're providing.
*
* At each stage, we will emit the capability only if the previous stage
* supported it.
*/
enum credential_op_type {
CREDENTIAL_OP_INITIAL = 1,
CREDENTIAL_OP_HELPER = 2,
CREDENTIAL_OP_RESPONSE = 3,
};
struct credential_capability {
unsigned request_initial:1,
request_helper:1,
response:1;
};
/**
* 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;
/**
* A `strvec` of WWW-Authenticate header values. Each string
* is the value of a WWW-Authenticate header in an HTTP response,
* in the order they were received in the response.
*/
struct strvec wwwauth_headers;
/**
* A `strvec` of state headers received from credential helpers.
*/
struct strvec state_headers;
/**
* A `strvec` of state headers to send to credential helpers.
*/
struct strvec state_headers_to_send;
/**
* Internal use only. Keeps track of if we previously matched against a
* WWW-Authenticate header line in order to re-fold future continuation
* lines into one value.
*/
unsigned header_is_last_match:1;
unsigned approved:1,
ephemeral:1,
configured:1,
multistage: 1,
quit:1,
use_http_path:1,
username_from_proto:1;
struct credential_capability capa_authtype;
struct credential_capability capa_state;
char *username;
char *password;
char *credential;
char *protocol;
char *host;
char *path;
char *oauth_refresh_token;
timestamp_t password_expiry_utc;
/**
* The authorization scheme to use. If this is NULL, libcurl is free to
* negotiate any scheme it likes.
*/
char *authtype;
};
#define CREDENTIAL_INIT { \
.helpers = STRING_LIST_INIT_DUP, \
.password_expiry_utc = TIME_MAX, \
.wwwauth_headers = STRVEC_INIT, \
.state_headers = STRVEC_INIT, \
.state_headers_to_send = STRVEC_INIT, \
}
/* 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().
*
* If all_capabilities is set, this is an internal user that is prepared
* to deal with all known capabilities, and we should advertise that fact.
*/
void credential_fill(struct credential *, int all_capabilities);
/**
* 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 *);
/**
* Enable all of the supported credential flags in this credential.
*/
void credential_set_all_capabilities(struct credential *c,
enum credential_op_type op_type);
/**
* Clear the secrets in this credential, but leave other data intact.
*
* This is useful for resetting credentials in preparation for a subsequent
* stage of filling.
*/
void credential_clear_secrets(struct credential *c);
/**
* Print a list of supported capabilities and version numbers to standard
* output.
*/
void credential_announce_capabilities(struct credential *c, FILE *fp);
/**
* Prepares the credential for the next iteration of the helper protocol by
* updating the state headers to send with the ones read by the last iteration
* of the protocol.
*
* Except for internal callers, this should be called exactly once between
* reading credentials with `credential_fill` and writing them.
*/
void credential_next_state(struct credential *c);
/**
* Return true if the capability is enabled for an operation of op_type.
*/
int credential_has_capability(const struct credential_capability *capa,
enum credential_op_type op_type);
int credential_read(struct credential *, FILE *,
enum credential_op_type);
void credential_write(const struct credential *, FILE *,
enum credential_op_type);
/*
* 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 and the function will return an
* error (even in 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 *want,
const struct credential *have, int match_password);
#endif /* CREDENTIAL_H */