credential.h

   1 #ifndef CREDENTIAL_H
   2 #define CREDENTIAL_H
   3
   4 #include "string-list.h"
   5 #include "strvec.h"
   6
   7 struct repository;
   8
   9 /**
  10  * The credentials API provides an abstracted way of gathering
  11  * authentication credentials from the user.
  12  *
  13  * Typical setup
  14  * -------------
  15  *
  16  * ------------
  17  * +-----------------------+
  18  * | Git code (C)          |--- to server requiring --->
  19  * |                       |        authentication
  20  * |.......................|
  21  * | C credential API      |--- prompt ---> User
  22  * +-----------------------+
  23  *      ^      |
  24  *      | pipe |
  25  *      |      v
  26  * +-----------------------+
  27  * | Git credential helper |
  28  * +-----------------------+
  29  * ------------
  30  *
  31  * The Git code (typically a remote-helper) will call the C API to obtain
  32  * credential data like a login/password pair (credential_fill). The
  33  * API will itself call a remote helper (e.g. "git credential-cache" or
  34  * "git credential-store") that may retrieve credential data from a
  35  * store. If the credential helper cannot find the information, the C API
  36  * will prompt the user. Then, the caller of the API takes care of
  37  * contacting the server, and does the actual authentication.
  38  *
  39  * C API
  40  * -----
  41  *
  42  * The credential C API is meant to be called by Git code which needs to
  43  * acquire or store a credential. It is centered around an object
  44  * representing a single credential and provides three basic operations:
  45  * fill (acquire credentials by calling helpers and/or prompting the user),
  46  * approve (mark a credential as successfully used so that it can be stored
  47  * for later use), and reject (mark a credential as unsuccessful so that it
  48  * can be erased from any persistent storage).
  49  *
  50  * Example
  51  * ~~~~~~~
  52  *
  53  * The example below shows how the functions of the credential API could be
  54  * used to login to a fictitious "foo" service on a remote host:
  55  *
  56  * -----------------------------------------------------------------------
  57  * int foo_login(struct foo_connection *f)
  58  * {
  59  *      int status;
  60  *      // Create a credential with some context; we don't yet know the
  61  *      // username or password.
  62  *
  63  * struct credential c = CREDENTIAL_INIT;
  64  * c.protocol = xstrdup("foo");
  65  * c.host = xstrdup(f->hostname);
  66  *
  67  * // Fill in the username and password fields by contacting
  68  * // helpers and/or asking the user. The function will die if it
  69  * // fails.
  70  * credential_fill(repo, &c);
  71  *
  72  * // Otherwise, we have a username and password. Try to use it.
  73  *
  74  * status = send_foo_login(f, c.username, c.password);
  75  * switch (status) {
  76  * case FOO_OK:
  77  * // It worked. Store the credential for later use.
  78  * credential_accept(&c);
  79  * break;
  80  * case FOO_BAD_LOGIN:
  81  * // Erase the credential from storage so we don't try it again.
  82  * credential_reject(&c);
  83  * break;
  84  * default:
  85  * // Some other error occurred. We don't know if the
  86  * // credential is good or bad, so report nothing to the
  87  * // credential subsystem.
  88  * }
  89  *
  90  * // Free any associated resources.
  91  * credential_clear(&c);
  92  *
  93  * return status;
  94  * }
  95  * -----------------------------------------------------------------------
  96  */
  97
  98 /*
  99  * These values define the kind of operation we're performing and the
 100  * capabilities at each stage.  The first is either an external request (via git
 101  * credential fill) or an internal request (e.g., via the HTTP) code.  The
 102  * second is the call to the credential helper, and the third is the response
 103  * we're providing.
 104  *
 105  * At each stage, we will emit the capability only if the previous stage
 106  * supported it.
 107  */
 108 enum credential_op_type {
 109         CREDENTIAL_OP_INITIAL  = 1,
 110         CREDENTIAL_OP_HELPER   = 2,
 111         CREDENTIAL_OP_RESPONSE = 3,
 112 };
 113
 114 struct credential_capability {
 115         unsigned request_initial:1,
 116                  request_helper:1,
 117                  response:1;
 118 };
 119
 120 /**
 121  * This struct represents a single login credential (typically a
 122  * username/password combination) along with any associated
 123  * context. All string fields should be heap-allocated (or NULL if
 124  * they are not known or not applicable). The meaning of the
 125  * individual context fields is the same as their counterparts in
 126  * the helper protocol.
 127  *
 128  * This struct should always be initialized with `CREDENTIAL_INIT` or
 129  * `credential_init`.
 130  */
 131 struct credential {
 132
 133         /**
 134          * A `string_list` of helpers. Each string specifies an external
 135          * helper which will be run, in order, to either acquire or store
 136          * credentials. This list is filled-in by the API functions
 137          * according to the corresponding configuration variables before
 138          * consulting helpers, so there usually is no need for a caller to
 139          * modify the helpers field at all.
 140          */
 141         struct string_list helpers;
 142
 143         /**
 144          * A `strvec` of WWW-Authenticate header values. Each string
 145          * is the value of a WWW-Authenticate header in an HTTP response,
 146          * in the order they were received in the response.
 147          */
 148         struct strvec wwwauth_headers;
 149
 150         /**
 151          * A `strvec` of state headers received from credential helpers.
 152          */
 153         struct strvec state_headers;
 154
 155         /**
 156          * A `strvec` of state headers to send to credential helpers.
 157          */
 158         struct strvec state_headers_to_send;
 159
 160         /**
 161          * Internal use only. Keeps track of if we previously matched against a
 162          * WWW-Authenticate header line in order to re-fold future continuation
 163          * lines into one value.
 164          */
 165         unsigned header_is_last_match:1;
 166
 167         unsigned approved:1,
 168                  ephemeral:1,
 169                  configured:1,
 170                  multistage: 1,
 171                  quit:1,
 172                  use_http_path:1,
 173                  username_from_proto:1,
 174                  sanitize_prompt:1,
 175                  protect_protocol:1;
 176
 177         struct credential_capability capa_authtype;
 178         struct credential_capability capa_state;
 179
 180         char *username;
 181         char *password;
 182         char *credential;
 183         char *protocol;
 184         char *host;
 185         char *path;
 186         char *oauth_refresh_token;
 187         timestamp_t password_expiry_utc;
 188
 189         /**
 190          * The authorization scheme to use.  If this is NULL, libcurl is free to
 191          * negotiate any scheme it likes.
 192          */
 193         char *authtype;
 194 };
 195
 196 #define CREDENTIAL_INIT { \
 197         .helpers = STRING_LIST_INIT_DUP, \
 198         .password_expiry_utc = TIME_MAX, \
 199         .wwwauth_headers = STRVEC_INIT, \
 200         .state_headers = STRVEC_INIT, \
 201         .state_headers_to_send = STRVEC_INIT, \
 202         .sanitize_prompt = 1, \
 203         .protect_protocol = 1, \
 204 }
 205
 206 /* Initialize a credential structure, setting all fields to empty. */
 207 void credential_init(struct credential *);
 208
 209 /**
 210  * Free any resources associated with the credential structure, returning
 211  * it to a pristine initialized state.
 212  */
 213 void credential_clear(struct credential *);
 214
 215 /**
 216  * Instruct the credential subsystem to fill the username and
 217  * password (or authtype and credential) fields of the passed
 218  * credential struct by first consulting helpers, then asking the
 219  * user. After this function returns, either the username and
 220  * password fields or the credential field of the credential are
 221  * guaranteed to be non-NULL. If an error occurs, the function
 222  * will die().
 223  *
 224  * If all_capabilities is set, this is an internal user that is prepared
 225  * to deal with all known capabilities, and we should advertise that fact.
 226  */
 227 void credential_fill(struct repository *, struct credential *,
 228                      int all_capabilities);
 229
 230 /**
 231  * Inform the credential subsystem that the provided credentials
 232  * were successfully used for authentication.  This will cause the
 233  * credential subsystem to notify any helpers of the approval, so
 234  * that they may store the result to be used again.  Any errors
 235  * from helpers are ignored.
 236  */
 237 void credential_approve(struct repository *, struct credential *);
 238
 239 /**
 240  * Inform the credential subsystem that the provided credentials
 241  * have been rejected. This will cause the credential subsystem to
 242  * notify any helpers of the rejection (which allows them, for
 243  * example, to purge the invalid credentials from storage). It
 244  * will also free() the username, password, and credential fields
 245  * of the credential and set them to NULL (readying the credential
 246  * for another call to `credential_fill`). Any errors from helpers
 247  * are ignored.
 248  */
 249 void credential_reject(struct repository *, struct credential *);
 250
 251 /**
 252  * Enable all of the supported credential flags in this credential.
 253  */
 254 void credential_set_all_capabilities(struct credential *c,
 255                                      enum credential_op_type op_type);
 256
 257 /**
 258  * Clear the secrets in this credential, but leave other data intact.
 259  *
 260  * This is useful for resetting credentials in preparation for a subsequent
 261  * stage of filling.
 262  */
 263 void credential_clear_secrets(struct credential *c);
 264
 265 /**
 266  * Print a list of supported capabilities and version numbers to standard
 267  * output.
 268  */
 269 void credential_announce_capabilities(struct credential *c, FILE *fp);
 270
 271 /**
 272  * Prepares the credential for the next iteration of the helper protocol by
 273  * updating the state headers to send with the ones read by the last iteration
 274  * of the protocol.
 275  *
 276  * Except for internal callers, this should be called exactly once between
 277  * reading credentials with `credential_fill` and writing them.
 278  */
 279 void credential_next_state(struct credential *c);
 280
 281 /**
 282  * Return true if the capability is enabled for an operation of op_type.
 283  */
 284 int credential_has_capability(const struct credential_capability *capa,
 285                               enum credential_op_type op_type);
 286
 287 int credential_read(struct credential *, FILE *,
 288                     enum credential_op_type);
 289 void credential_write(const struct credential *, FILE *,
 290                       enum credential_op_type);
 291
 292 /*
 293  * Parse a url into a credential struct, replacing any existing contents.
 294  *
 295  * If the url can't be parsed (e.g., a missing "proto://" component), the
 296  * resulting credential will be empty and the function will return an
 297  * error (even in the "gently" form).
 298  *
 299  * If we encounter a component which cannot be represented as a credential
 300  * value (e.g., because it contains a newline), the "gently" form will return
 301  * an error but leave the broken state in the credential object for further
 302  * examination.  The non-gentle form will issue a warning to stderr and return
 303  * an empty credential.
 304  */
 305 void credential_from_url(struct credential *, const char *url);
 306 int credential_from_url_gently(struct credential *, const char *url, int quiet);
 307
 308 int credential_match(const struct credential *want,
 309                      const struct credential *have, int match_password);
 310
 311 #endif /* CREDENTIAL_H */