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