mirror of
https://github.com/git/git.git
synced 2026-03-15 03:00:07 +01:00
59f5226028
There are a few places in git that need to get a username and password credential from the user; the most notable one is HTTP authentication for smart-http pushing. Right now the only choices for providing credentials are to put them plaintext into your ~/.netrc, or to have git prompt you (either on the terminal or via an askpass program). The former is not very secure, and the latter is not very convenient. Unfortunately, there is no "always best" solution for password management. The details will depend on the tradeoff you want between security and convenience, as well as how git can integrate with other security systems (e.g., many operating systems provide a keychain or password wallet for single sign-on). This patch abstracts the notion of gathering user credentials into a few simple functions. These functions can be backed by our internal git_getpass implementation (which just prompts the user), or by external helpers which are free to consult system-specific password wallets, make custom policy decisions on password caching and storage, or prompt the user in a non-traditional manner. The helper protocol aims for simplicity of helper implementation; see the newly added documentation for details. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
114 lines
3.7 KiB
Plaintext
114 lines
3.7 KiB
Plaintext
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).
|
|
|
|
Data Structures
|
|
---------------
|
|
|
|
`struct credential`::
|
|
|
|
This struct represents a single username/password combination.
|
|
The `username` and `password` fields should be heap-allocated
|
|
strings (or NULL if they are not yet known). The `unique` field,
|
|
if non-NULL, should be a heap-allocated string indicating a
|
|
unique context for this credential (e.g., a protocol and server
|
|
name for a remote credential). The `description` field, if
|
|
non-NULL, should point to a string containing a human-readable
|
|
description of this credential.
|
|
|
|
`struct string_list methods`::
|
|
|
|
The credential functions take a `string_list` of methods for
|
|
acquiring credentials. Each string specifies an external
|
|
helper which will be run, in order, to acquire credentials,
|
|
until both a username and password have been acquired. A NULL or
|
|
empty methods list indicates that the internal
|
|
`credential_getpass` function should be used.
|
|
|
|
|
|
Functions
|
|
---------
|
|
|
|
`credential_fill_gently`::
|
|
|
|
Attempt to fill the username and password fields of the passed
|
|
credential struct. If they cannot be filled after trying each
|
|
available method, returns -1. Otherwise, returns 0.
|
|
|
|
`credential_fill`::
|
|
|
|
Like `credential_fill_gently`, but `die()` if credentials cannot
|
|
be gathered.
|
|
|
|
`credential_reject`::
|
|
|
|
Inform the credential subsystem that the provided credentials
|
|
have been rejected. This will clear the username and password
|
|
fields in `struct credential`, as well as notify any helpers of
|
|
the rejection (which may, for example, purge the invalid
|
|
credentials from storage).
|
|
|
|
`credential_getpass`::
|
|
|
|
Fetch credentials from the user either using an "askpass" helper
|
|
(see the discussion of core.askpass and GIT_ASKPASS in
|
|
linkgit:git-config[1] and linkgit:git[1], respectively) or by
|
|
prompting the user via the terminal.
|
|
|
|
|
|
Credential Helpers
|
|
------------------
|
|
|
|
Credential helpers are programs executed by git to fetch credentials
|
|
from storage or from the user. The default behavior when no helpers are
|
|
defined is to use the internal `credential_askpass` function.
|
|
|
|
When a helper is executed, it may receive the following options on the
|
|
command line:
|
|
|
|
`--reject`::
|
|
|
|
Specify that the provided credential has been rejected; the
|
|
helper may take appropriate action to purge any credential
|
|
storage or cache. If this option is not given, the helper should
|
|
assume a credential is being requested.
|
|
|
|
`--description=<X>`::
|
|
|
|
`<X>` will contain a human-readable description of the
|
|
credential being requested. If this option is not given, no
|
|
description is available.
|
|
|
|
`--unique=<X>`::
|
|
|
|
`<X>` will contain a token to uniquely identify the context of
|
|
the credential (e.g., a host name for network authentication).
|
|
If this option is not given, no context is available.
|
|
|
|
`--username=<X>`::
|
|
|
|
`<X>` will contain the username requested by the user. If this
|
|
option is not given, no username is available, and the helper
|
|
should provide both a username and password.
|
|
|
|
The helper should produce a list of items on stdout, each followed by a
|
|
newline character. Each item should consist of a key-value pair, separated
|
|
by an `=` (equals) sign. The value may contain any bytes except a
|
|
newline. When reading the response, git understands the following keys:
|
|
|
|
`username`::
|
|
|
|
The username part of the credential. If a username was given to
|
|
the helper via `--username`, the new value will override it.
|
|
|
|
`password`::
|
|
|
|
The password part of the credential.
|
|
|
|
It is perfectly acceptable for a helper to provide only part of a
|
|
credential, or nothing at all.
|