t9108: make test hash independent
[git] / 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
95
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.
102  *
103  * This struct should always be initialized with `CREDENTIAL_INIT` or
104  * `credential_init`.
105  */
106 struct credential {
107
108         /**
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.
115          */
116         struct string_list helpers;
117
118         unsigned approved:1,
119                  configured:1,
120                  quit:1,
121                  use_http_path:1,
122                  username_from_proto:1;
123
124         char *username;
125         char *password;
126         char *protocol;
127         char *host;
128         char *path;
129 };
130
131 #define CREDENTIAL_INIT { STRING_LIST_INIT_DUP }
132
133 /* Initialize a credential structure, setting all fields to empty. */
134 void credential_init(struct credential *);
135
136 /**
137  * Free any resources associated with the credential structure, returning
138  * it to a pristine initialized state.
139  */
140 void credential_clear(struct credential *);
141
142 /**
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().
149  */
150 void credential_fill(struct credential *);
151
152 /**
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.
158  */
159 void credential_approve(struct credential *);
160
161 /**
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.
170  */
171 void credential_reject(struct credential *);
172
173 int credential_read(struct credential *, FILE *);
174 void credential_write(const struct credential *, FILE *);
175
176 /*
177  * Parse a url into a credential struct, replacing any existing contents.
178  *
179  * If the url can't be parsed (e.g., a missing "proto://" component), the
180  * resulting credential will be empty but we'll still return success from the
181  * "gently" form.
182  *
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.
188  */
189 void credential_from_url(struct credential *, const char *url);
190 int credential_from_url_gently(struct credential *, const char *url, int quiet);
191
192 int credential_match(const struct credential *have,
193                      const struct credential *want);
194
195 #endif /* CREDENTIAL_H */