The eleventh (aka "ort") batch
[git.git] / credential.h
blobc0e17e3554fce30586abe8a32aad503e4ec92b03
1 #ifndef CREDENTIAL_H
2 #define CREDENTIAL_H
4 #include "string-list.h"
6 /**
7 * The credentials API provides an abstracted way of gathering username and
8 * password credentials from the user.
10 * Typical setup
11 * -------------
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 * ------------
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.
36 * C API
37 * -----
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).
47 * Example
48 * ~~~~~~~
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:
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.
60 * struct credential c = CREDENTIAL_INIT;
61 * c.protocol = xstrdup("foo");
62 * c.host = xstrdup(f->hostname);
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);
69 * // Otherwise, we have a username and password. Try to use it.
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 * }
87 * // Free any associated resources.
88 * credential_clear(&c);
90 * return status;
91 * }
92 * -----------------------------------------------------------------------
96 /**
97 * This struct represents a single username/password combination
98 * along with any associated context. All string fields should be
99 * heap-allocated (or NULL if they are not known or not applicable).
100 * The meaning of the individual context fields is the same as
101 * their counterparts in the helper protocol.
103 * This struct should always be initialized with `CREDENTIAL_INIT` or
104 * `credential_init`.
106 struct credential {
109 * A `string_list` of helpers. Each string specifies an external
110 * helper which will be run, in order, to either acquire or store
111 * credentials. This list is filled-in by the API functions
112 * according to the corresponding configuration variables before
113 * consulting helpers, so there usually is no need for a caller to
114 * modify the helpers field at all.
116 struct string_list helpers;
118 unsigned approved:1,
119 configured:1,
120 quit:1,
121 use_http_path:1,
122 username_from_proto:1;
124 char *username;
125 char *password;
126 char *protocol;
127 char *host;
128 char *path;
131 #define CREDENTIAL_INIT { STRING_LIST_INIT_DUP }
133 /* Initialize a credential structure, setting all fields to empty. */
134 void credential_init(struct credential *);
137 * Free any resources associated with the credential structure, returning
138 * it to a pristine initialized state.
140 void credential_clear(struct credential *);
143 * Instruct the credential subsystem to fill the username and
144 * password fields of the passed credential struct by first
145 * consulting helpers, then asking the user. After this function
146 * returns, the username and password fields of the credential are
147 * guaranteed to be non-NULL. If an error occurs, the function will
148 * die().
150 void credential_fill(struct credential *);
153 * Inform the credential subsystem that the provided credentials
154 * were successfully used for authentication. This will cause the
155 * credential subsystem to notify any helpers of the approval, so
156 * that they may store the result to be used again. Any errors
157 * from helpers are ignored.
159 void credential_approve(struct credential *);
162 * Inform the credential subsystem that the provided credentials
163 * have been rejected. This will cause the credential subsystem to
164 * notify any helpers of the rejection (which allows them, for
165 * example, to purge the invalid credentials from storage). It
166 * will also free() the username and password fields of the
167 * credential and set them to NULL (readying the credential for
168 * another call to `credential_fill`). Any errors from helpers are
169 * ignored.
171 void credential_reject(struct credential *);
173 int credential_read(struct credential *, FILE *);
174 void credential_write(const struct credential *, FILE *);
177 * Parse a url into a credential struct, replacing any existing contents.
179 * If the url can't be parsed (e.g., a missing "proto://" component), the
180 * resulting credential will be empty and the function will return an
181 * error (even in the "gently" form).
183 * If we encounter a component which cannot be represented as a credential
184 * value (e.g., because it contains a newline), the "gently" form will return
185 * an error but leave the broken state in the credential object for further
186 * examination. The non-gentle form will issue a warning to stderr and return
187 * an empty credential.
189 void credential_from_url(struct credential *, const char *url);
190 int credential_from_url_gently(struct credential *, const char *url, int quiet);
192 int credential_match(const struct credential *want,
193 const struct credential *have);
195 #endif /* CREDENTIAL_H */