git/credential.h

#ifndef CREDENTIAL_H
#define CREDENTIAL_H

#include "string-list.h"
#include "strvec.h"

/**
 * The credentials API provides an abstracted way of gathering
 * authentication 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 { … };

struct credential_capability { … };

/**
 * This struct represents a single login credential (typically a
 * 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 { … };

#define CREDENTIAL_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 (or authtype and credential) fields of the passed
 * credential struct by first consulting helpers, then asking the
 * user. After this function returns, either the username and
 * password fields or the credential field 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, password, and credential 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 */