credential.h

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