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 /** @} */