196 lines
6.4 KiB
C
196 lines
6.4 KiB
C
#ifndef CREDENTIAL_H
|
|
#define CREDENTIAL_H
|
|
|
|
#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;
|
|
|
|
char *username;
|
|
char *password;
|
|
char *protocol;
|
|
char *host;
|
|
char *path;
|
|
};
|
|
|
|
#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);
|
|
|
|
#endif /* CREDENTIAL_H */
|