credential.h

   1 #ifndef CREDENTIAL_H
   2 #define CREDENTIAL_H
   3
   4 #include "string-list.h"
   5
   6 /**
   7  * The credentials API provides an abstracted way of gathering username and
   8  * password credentials from the user.
   9  *
  10  * Typical setup
  11  * -------------
  12  *
  13  * ------------
  14  * +-----------------------+
  15  * | Git code (C)          |--- to server requiring --->
  16  * |                       |        authentication
  17  * |.......................|
  18  * | C credential API      |--- prompt ---> User
  19  * +-----------------------+
  20  *      ^      |
  21  *      | pipe |
  22  *      |      v
  23  * +-----------------------+
  24  * | Git credential helper |
  25  * +-----------------------+
  26  * ------------
  27  *
  28  * The Git code (typically a remote-helper) will call the C API to obtain
  29  * credential data like a login/password pair (credential_fill). The
  30  * API will itself call a remote helper (e.g. "git credential-cache" or
  31  * "git credential-store") that may retrieve credential data from a
  32  * store. If the credential helper cannot find the information, the C API
  33  * will prompt the user. Then, the caller of the API takes care of
  34  * contacting the server, and does the actual authentication.
  35  *
  36  * C API
  37  * -----
  38  *
  39  * The credential C API is meant to be called by Git code which needs to
  40  * acquire or store a credential. It is centered around an object
  41  * representing a single credential and provides three basic operations:
  42  * fill (acquire credentials by calling helpers and/or prompting the user),
  43  * approve (mark a credential as successfully used so that it can be stored
  44  * for later use), and reject (mark a credential as unsuccessful so that it
  45  * can be erased from any persistent storage).
  46  *
  47  * Example
  48  * ~~~~~~~
  49  *
  50  * The example below shows how the functions of the credential API could be
  51  * used to login to a fictitious "foo" service on a remote host:
  52  *
  53  * -----------------------------------------------------------------------
  54  * int foo_login(struct foo_connection *f)
  55  * {
  56  *      int status;
  57  *      // Create a credential with some context; we don't yet know the
  58  *      // username or password.
  59  *
  60  * struct credential c = CREDENTIAL_INIT;
  61  * c.protocol = xstrdup("foo");
  62  * c.host = xstrdup(f->hostname);
  63  *
  64  * // Fill in the username and password fields by contacting
  65  * // helpers and/or asking the user. The function will die if it
  66  * // fails.
  67  * credential_fill(&c);
  68  *
  69  * // Otherwise, we have a username and password. Try to use it.
  70  *
  71  * status = send_foo_login(f, c.username, c.password);
  72  * switch (status) {
  73  * case FOO_OK:
  74  * // It worked. Store the credential for later use.
  75  * credential_accept(&c);
  76  * break;
  77  * case FOO_BAD_LOGIN:
  78  * // Erase the credential from storage so we don't try it again.
  79  * credential_reject(&c);
  80  * break;
  81  * default:
  82  * // Some other error occurred. We don't know if the
  83  * // credential is good or bad, so report nothing to the
  84  * // credential subsystem.
  85  * }
  86  *
  87  * // Free any associated resources.
  88  * credential_clear(&c);
  89  *
  90  * return status;
  91  * }
  92  * -----------------------------------------------------------------------
  93  *
  94  * Credential Helpers
  95  * ------------------
  96  *
  97  * Credential helpers are programs executed by Git to fetch or save
  98  * credentials from and to long-term storage (where "long-term" is simply
  99  * longer than a single Git process; e.g., credentials may be stored
 100  * in-memory for a few minutes, or indefinitely on disk).
 101  *
 102  * Each helper is specified by a single string in the configuration
 103  * variable `credential.helper` (and others, see Documentation/git-config.txt).
 104  * The string is transformed by Git into a command to be executed using
 105  * these rules:
 106  *
 107  *   1. If the helper string begins with "!", it is considered a shell
 108  *      snippet, and everything after the "!" becomes the command.
 109  *
 110  *   2. Otherwise, if the helper string begins with an absolute path, the
 111  *      verbatim helper string becomes the command.
 112  *
 113  *   3. Otherwise, the string "git credential-" is prepended to the helper
 114  *      string, and the result becomes the command.
 115  *
 116  * The resulting command then has an "operation" argument appended to it
 117  * (see below for details), and the result is executed by the shell.
 118  *
 119  * Here are some example specifications:
 120  *
 121  * ----------------------------------------------------
 122  * # run "git credential-foo"
 123  * foo
 124  *
 125  * # same as above, but pass an argument to the helper
 126  * foo --bar=baz
 127  *
 128  * # the arguments are parsed by the shell, so use shell
 129  * # quoting if necessary
 130  * foo --bar="whitespace arg"
 131  *
 132  * # you can also use an absolute path, which will not use the git wrapper
 133  * /path/to/my/helper --with-arguments
 134  *
 135  * # or you can specify your own shell snippet
 136  * !f() { echo "password=`cat $HOME/.secret`"; }; f
 137  * ----------------------------------------------------
 138  *
 139  * Generally speaking, rule (3) above is the simplest for users to specify.
 140  * Authors of credential helpers should make an effort to assist their
 141  * users by naming their program "git-credential-$NAME", and putting it in
 142  * the $PATH or $GIT_EXEC_PATH during installation, which will allow a user
 143  * to enable it with `git config credential.helper $NAME`.
 144  *
 145  * When a helper is executed, it will have one "operation" argument
 146  * appended to its command line, which is one of:
 147  *
 148  * `get`::
 149  *
 150  *      Return a matching credential, if any exists.
 151  *
 152  * `store`::
 153  *
 154  *      Store the credential, if applicable to the helper.
 155  *
 156  * `erase`::
 157  *
 158  *      Remove a matching credential, if any, from the helper's storage.
 159  *
 160  * The details of the credential will be provided on the helper's stdin
 161  * stream. The exact format is the same as the input/output format of the
 162  * `git credential` plumbing command (see the section `INPUT/OUTPUT
 163  * FORMAT` in Documentation/git-credential.txt for a detailed specification).
 164  *
 165  * For a `get` operation, the helper should produce a list of attributes
 166  * on stdout in the same format. A helper is free to produce a subset, or
 167  * even no values at all if it has nothing useful to provide. Any provided
 168  * attributes will overwrite those already known about by Git.  If a helper
 169  * outputs a `quit` attribute with a value of `true` or `1`, no further
 170  * helpers will be consulted, nor will the user be prompted (if no
 171  * credential has been provided, the operation will then fail).
 172  *
 173  * For a `store` or `erase` operation, the helper's output is ignored.
 174  * If it fails to perform the requested operation, it may complain to
 175  * stderr to inform the user. If it does not support the requested
 176  * operation (e.g., a read-only store), it should silently ignore the
 177  * request.
 178  *
 179  * If a helper receives any other operation, it should silently ignore the
 180  * request. This leaves room for future operations to be added (older
 181  * helpers will just ignore the new requests).
 182  *
 183  */
 184
 185
 186 /**
 187  * This struct represents a single username/password combination
 188  * along with any associated context. All string fields should be
 189  * heap-allocated (or NULL if they are not known or not applicable).
 190  * The meaning of the individual context fields is the same as
 191  * their counterparts in the helper protocol.
 192  *
 193  * This struct should always be initialized with `CREDENTIAL_INIT` or
 194  * `credential_init`.
 195  */
 196 struct credential {
 197
 198         /**
 199          * A `string_list` of helpers. Each string specifies an external
 200          * helper which will be run, in order, to either acquire or store
 201          * credentials. This list is filled-in by the API functions
 202          * according to the corresponding configuration variables before
 203          * consulting helpers, so there usually is no need for a caller to
 204          * modify the helpers field at all.
 205          */
 206         struct string_list helpers;
 207
 208         unsigned approved:1,
 209                  configured:1,
 210                  quit:1,
 211                  use_http_path:1;
 212
 213         char *username;
 214         char *password;
 215         char *protocol;
 216         char *host;
 217         char *path;
 218 };
 219
 220 #define CREDENTIAL_INIT { STRING_LIST_INIT_DUP }
 221
 222 /* Initialize a credential structure, setting all fields to empty. */
 223 void credential_init(struct credential *);
 224
 225 /**
 226  * Free any resources associated with the credential structure, returning
 227  * it to a pristine initialized state.
 228  */
 229 void credential_clear(struct credential *);
 230
 231 /**
 232  * Instruct the credential subsystem to fill the username and
 233  * password fields of the passed credential struct by first
 234  * consulting helpers, then asking the user. After this function
 235  * returns, the username and password fields of the credential are
 236  * guaranteed to be non-NULL. If an error occurs, the function will
 237  * die().
 238  */
 239 void credential_fill(struct credential *);
 240
 241 /**
 242  * Inform the credential subsystem that the provided credentials
 243  * were successfully used for authentication.  This will cause the
 244  * credential subsystem to notify any helpers of the approval, so
 245  * that they may store the result to be used again.  Any errors
 246  * from helpers are ignored.
 247  */
 248 void credential_approve(struct credential *);
 249
 250 /**
 251  * Inform the credential subsystem that the provided credentials
 252  * have been rejected. This will cause the credential subsystem to
 253  * notify any helpers of the rejection (which allows them, for
 254  * example, to purge the invalid credentials from storage). It
 255  * will also free() the username and password fields of the
 256  * credential and set them to NULL (readying the credential for
 257  * another call to `credential_fill`). Any errors from helpers are
 258  * ignored.
 259  */
 260 void credential_reject(struct credential *);
 261
 262 int credential_read(struct credential *, FILE *);
 263 void credential_write(const struct credential *, FILE *);
 264
 265 /* Parse a URL into broken-down credential fields. */
 266 void credential_from_url(struct credential *, const char *url);
 267
 268 int credential_match(const struct credential *have,
 269                      const struct credential *want);
 270
 271 #endif /* CREDENTIAL_H */