1 /*
2  * Copyright (C) the libgit2 contributors. All rights reserved.
3  *
4  * This file is part of libgit2, distributed under the GNU GPL v2 with
5  * a Linking Exception. For full terms see the included COPYING file.
6  */
7 #ifndef INCLUDE_git_credential_h__
8 #define INCLUDE_git_credential_h__
9 
10 #include "common.h"
11 
12 /**
13  * @file git2/credential.h
14  * @brief Git authentication & credential management
15  * @defgroup git_credential Authentication & credential management
16  * @ingroup Git
17  * @{
18  */
19 GIT_BEGIN_DECL
20 
21 /**
22  * Supported credential types
23  *
24  * This represents the various types of authentication methods supported by
25  * the library.
26  */
27 typedef enum {
28 	/**
29 	 * A vanilla user/password request
30 	 * @see git_credential_userpass_plaintext_new
31 	 */
32 	GIT_CREDENTIAL_USERPASS_PLAINTEXT = (1u << 0),
33 
34 	/**
35 	 * An SSH key-based authentication request
36 	 * @see git_credential_ssh_key_new
37 	 */
38 	GIT_CREDENTIAL_SSH_KEY = (1u << 1),
39 
40 	/**
41 	 * An SSH key-based authentication request, with a custom signature
42 	 * @see git_credential_ssh_custom_new
43 	 */
44 	GIT_CREDENTIAL_SSH_CUSTOM = (1u << 2),
45 
46 	/**
47 	 * An NTLM/Negotiate-based authentication request.
48 	 * @see git_credential_default
49 	 */
50 	GIT_CREDENTIAL_DEFAULT = (1u << 3),
51 
52 	/**
53 	 * An SSH interactive authentication request
54 	 * @see git_credential_ssh_interactive_new
55 	 */
56 	GIT_CREDENTIAL_SSH_INTERACTIVE = (1u << 4),
57 
58 	/**
59 	 * Username-only authentication request
60 	 *
61 	 * Used as a pre-authentication step if the underlying transport
62 	 * (eg. SSH, with no username in its URL) does not know which username
63 	 * to use.
64 	 *
65 	 * @see git_credential_username_new
66 	 */
67 	GIT_CREDENTIAL_USERNAME = (1u << 5),
68 
69 	/**
70 	 * An SSH key-based authentication request
71 	 *
72 	 * Allows credentials to be read from memory instead of files.
73 	 * Note that because of differences in crypto backend support, it might
74 	 * not be functional.
75 	 *
76 	 * @see git_credential_ssh_key_memory_new
77 	 */
78 	GIT_CREDENTIAL_SSH_MEMORY = (1u << 6),
79 } git_credential_t;
80 
81 /**
82  * The base structure for all credential types
83  */
84 typedef struct git_credential git_credential;
85 
86 typedef struct git_credential_userpass_plaintext git_credential_userpass_plaintext;
87 
88 /** Username-only credential information */
89 typedef struct git_credential_username git_credential_username;
90 
91 /** A key for NTLM/Kerberos "default" credentials */
92 typedef struct git_credential git_credential_default;
93 
94 /**
95  * A ssh key from disk
96  */
97 typedef struct git_credential_ssh_key git_credential_ssh_key;
98 
99 /**
100  * Keyboard-interactive based ssh authentication
101  */
102 typedef struct git_credential_ssh_interactive git_credential_ssh_interactive;
103 
104 /**
105  * A key with a custom signature function
106  */
107 typedef struct git_credential_ssh_custom git_credential_ssh_custom;
108 
109 /**
110  * Credential acquisition callback.
111  *
112  * This callback is usually involved any time another system might need
113  * authentication. As such, you are expected to provide a valid
114  * git_credential object back, depending on allowed_types (a
115  * git_credential_t bitmask).
116  *
117  * Note that most authentication details are your responsibility - this
118  * callback will be called until the authentication succeeds, or you report
119  * an error. As such, it's easy to get in a loop if you fail to stop providing
120  * the same incorrect credentials.
121  *
122  * @param out The newly created credential object.
123  * @param url The resource for which we are demanding a credential.
124  * @param username_from_url The username that was embedded in a "user\@host"
125  *                          remote url, or NULL if not included.
126  * @param allowed_types A bitmask stating which credential types are OK to return.
127  * @param payload The payload provided when specifying this callback.
128  * @return 0 for success, < 0 to indicate an error, > 0 to indicate
129  *       no credential was acquired
130  */
131 typedef int GIT_CALLBACK(git_credential_acquire_cb)(
132 	git_credential **out,
133 	const char *url,
134 	const char *username_from_url,
135 	unsigned int allowed_types,
136 	void *payload);
137 
138 /**
139  * Free a credential.
140  *
141  * This is only necessary if you own the object; that is, if you are a
142  * transport.
143  *
144  * @param cred the object to free
145  */
146 GIT_EXTERN(void) git_credential_free(git_credential *cred);
147 
148 /**
149  * Check whether a credential object contains username information.
150  *
151  * @param cred object to check
152  * @return 1 if the credential object has non-NULL username, 0 otherwise
153  */
154 GIT_EXTERN(int) git_credential_has_username(git_credential *cred);
155 
156 /**
157  * Return the username associated with a credential object.
158  *
159  * @param cred object to check
160  * @return the credential username, or NULL if not applicable
161  */
162 GIT_EXTERN(const char *) git_credential_get_username(git_credential *cred);
163 
164 /**
165  * Create a new plain-text username and password credential object.
166  * The supplied credential parameter will be internally duplicated.
167  *
168  * @param out The newly created credential object.
169  * @param username The username of the credential.
170  * @param password The password of the credential.
171  * @return 0 for success or an error code for failure
172  */
173 GIT_EXTERN(int) git_credential_userpass_plaintext_new(
174 	git_credential **out,
175 	const char *username,
176 	const char *password);
177 
178 /**
179  * Create a "default" credential usable for Negotiate mechanisms like NTLM
180  * or Kerberos authentication.
181  *
182  * @param out The newly created credential object.
183  * @return 0 for success or an error code for failure
184  */
185 GIT_EXTERN(int) git_credential_default_new(git_credential **out);
186 
187 /**
188  * Create a credential to specify a username.
189  *
190  * This is used with ssh authentication to query for the username if
191  * none is specified in the url.
192  *
193  * @param out The newly created credential object.
194  * @param username The username to authenticate with
195  * @return 0 for success or an error code for failure
196  */
197 GIT_EXTERN(int) git_credential_username_new(git_credential **out, const char *username);
198 
199 /**
200  * Create a new passphrase-protected ssh key credential object.
201  * The supplied credential parameter will be internally duplicated.
202  *
203  * @param out The newly created credential object.
204  * @param username username to use to authenticate
205  * @param publickey The path to the public key of the credential.
206  * @param privatekey The path to the private key of the credential.
207  * @param passphrase The passphrase of the credential.
208  * @return 0 for success or an error code for failure
209  */
210 GIT_EXTERN(int) git_credential_ssh_key_new(
211 	git_credential **out,
212 	const char *username,
213 	const char *publickey,
214 	const char *privatekey,
215 	const char *passphrase);
216 
217 /**
218  * Create a new ssh key credential object reading the keys from memory.
219  *
220  * @param out The newly created credential object.
221  * @param username username to use to authenticate.
222  * @param publickey The public key of the credential.
223  * @param privatekey The private key of the credential.
224  * @param passphrase The passphrase of the credential.
225  * @return 0 for success or an error code for failure
226  */
227 GIT_EXTERN(int) git_credential_ssh_key_memory_new(
228 	git_credential **out,
229 	const char *username,
230 	const char *publickey,
231 	const char *privatekey,
232 	const char *passphrase);
233 
234 /*
235  * If the user hasn't included libssh2.h before git2.h, we need to
236  * define a few types for the callback signatures.
237  */
238 #ifndef LIBSSH2_VERSION
239 typedef struct _LIBSSH2_SESSION LIBSSH2_SESSION;
240 typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT LIBSSH2_USERAUTH_KBDINT_PROMPT;
241 typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE LIBSSH2_USERAUTH_KBDINT_RESPONSE;
242 #endif
243 
244 typedef void GIT_CALLBACK(git_credential_ssh_interactive_cb)(
245 	const char *name,
246 	int name_len,
247 	const char *instruction, int instruction_len,
248 	int num_prompts, const LIBSSH2_USERAUTH_KBDINT_PROMPT *prompts,
249 	LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses,
250 	void **abstract);
251 
252 
253 /**
254  * Create a new ssh keyboard-interactive based credential object.
255  * The supplied credential parameter will be internally duplicated.
256  *
257  * @param username Username to use to authenticate.
258  * @param prompt_callback The callback method used for prompts.
259  * @param payload Additional data to pass to the callback.
260  * @return 0 for success or an error code for failure.
261  */
262 GIT_EXTERN(int) git_credential_ssh_interactive_new(
263 	git_credential **out,
264 	const char *username,
265 	git_credential_ssh_interactive_cb prompt_callback,
266 	void *payload);
267 
268 /**
269  * Create a new ssh key credential object used for querying an ssh-agent.
270  * The supplied credential parameter will be internally duplicated.
271  *
272  * @param out The newly created credential object.
273  * @param username username to use to authenticate
274  * @return 0 for success or an error code for failure
275  */
276 GIT_EXTERN(int) git_credential_ssh_key_from_agent(
277 	git_credential **out,
278 	const char *username);
279 
280 typedef int GIT_CALLBACK(git_credential_sign_cb)(
281 	LIBSSH2_SESSION *session,
282 	unsigned char **sig, size_t *sig_len,
283 	const unsigned char *data, size_t data_len,
284 	void **abstract);
285 
286 /**
287  * Create an ssh key credential with a custom signing function.
288  *
289  * This lets you use your own function to sign the challenge.
290  *
291  * This function and its credential type is provided for completeness
292  * and wraps `libssh2_userauth_publickey()`, which is undocumented.
293  *
294  * The supplied credential parameter will be internally duplicated.
295  *
296  * @param out The newly created credential object.
297  * @param username username to use to authenticate
298  * @param publickey The bytes of the public key.
299  * @param publickey_len The length of the public key in bytes.
300  * @param sign_callback The callback method to sign the data during the challenge.
301  * @param payload Additional data to pass to the callback.
302  * @return 0 for success or an error code for failure
303  */
304 GIT_EXTERN(int) git_credential_ssh_custom_new(
305 	git_credential **out,
306 	const char *username,
307 	const char *publickey,
308 	size_t publickey_len,
309 	git_credential_sign_cb sign_callback,
310 	void *payload);
311 
312 /** @} */
313 GIT_END_DECL
314 #endif
315