git.oblomov.eu Git - git/blob - Documentation/technical/api-credentials.txt

   1 credentials API
   2 ===============
   3
   4 The credentials API provides an abstracted way of gathering username and
   5 password credentials from the user (even though credentials in the wider
   6 world can take many forms, in this document the word "credential" always
   7 refers to a username and password pair).
   8
   9 Data Structures
  10 ---------------
  11
  12 `struct credential`::
  13
  14         This struct represents a single username/password combination.
  15         The `username` and `password` fields should be heap-allocated
  16         strings (or NULL if they are not yet known). The `unique` field,
  17         if non-NULL, should be a heap-allocated string indicating a
  18         unique context for this credential (e.g., a protocol and server
  19         name for a remote credential). The `description` field, if
  20         non-NULL, should point to a string containing a human-readable
  21         description of this credential.
  22
  23 `struct string_list methods`::
  24
  25         The credential functions take a `string_list` of methods for
  26         acquiring credentials. Each string specifies an external
  27         helper which will be run, in order, to acquire credentials,
  28         until both a username and password have been acquired. A NULL
  29         parameter means to use the default list (as configured by
  30         `credential.helper`); an empty list indicates that the internal
  31         `credential_getpass` function should be used.
  32
  33
  34 Functions
  35 ---------
  36
  37 `credential_fill_gently`::
  38
  39         Attempt to fill the username and password fields of the passed
  40         credential struct. If they cannot be filled after trying each
  41         available method, returns -1. Otherwise, returns 0.
  42
  43 `credential_fill`::
  44
  45         Like `credential_fill_gently`, but `die()` if credentials cannot
  46         be gathered.
  47
  48 `credential_reject`::
  49
  50         Inform the credential subsystem that the provided credentials
  51         have been rejected. This will clear the username and password
  52         fields in `struct credential`, as well as notify any helpers of
  53         the rejection (which may, for example, purge the invalid
  54         credentials from storage).
  55
  56 `credential_getpass`::
  57
  58         Fetch credentials from the user either using an "askpass" helper
  59         (see the discussion of core.askpass and GIT_ASKPASS in
  60         linkgit:git-config[1] and linkgit:git[1], respectively) or by
  61         prompting the user via the terminal.
  62
  63
  64 Credential Helpers
  65 ------------------
  66
  67 Credential helpers are programs executed by git to fetch credentials
  68 from storage or from the user. The default behavior when no helpers are
  69 defined is to use the internal `credential_askpass` function.
  70
  71 When a helper is executed, it may receive the following options on the
  72 command line:
  73
  74 `--reject`::
  75
  76         Specify that the provided credential has been rejected; the
  77         helper may take appropriate action to purge any credential
  78         storage or cache. If this option is not given, the helper should
  79         assume a credential is being requested.
  80
  81 `--description=<X>`::
  82
  83         `<X>` will contain a human-readable description of the
  84         credential being requested. If this option is not given, no
  85         description is available.
  86
  87 `--unique=<X>`::
  88
  89         `<X>` will contain a token to uniquely identify the context of
  90         the credential (e.g., a host name for network authentication).
  91         If this option is not given, no context is available.
  92
  93 `--username=<X>`::
  94
  95         `<X>` will contain the username requested by the user. If this
  96         option is not given, no username is available, and the helper
  97         should provide both a username and password.
  98
  99 The helper should produce a list of items on stdout, each followed by a
 100 newline character. Each item should consist of a key-value pair, separated
 101 by an `=` (equals) sign. The value may contain any bytes except a
 102 newline. When reading the response, git understands the following keys:
 103
 104 `username`::
 105
 106         The username part of the credential. If a username was given to
 107         the helper via `--username`, the new value will override it.
 108
 109 `password`::
 110
 111         The password part of the credential.
 112
 113 It is perfectly acceptable for a helper to provide only part of a
 114 credential, or nothing at all.