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 /** 85 * The base structure for all credential types 86 */ 87 alias git_credential = libgit2_d.sys.credential.git_credential; 88 89 alias git_credential_userpass_plaintext = libgit2_d.sys.credential.git_credential_userpass_plaintext; 90 91 /** 92 * Username-only credential information 93 */ 94 alias git_credential_username = libgit2_d.sys.credential.git_credential_username; 95 96 /** 97 * A key for NTLM/Kerberos "default" credentials 98 */ 99 alias git_credential_default = .git_credential; 100 101 /** 102 * A ssh key from disk 103 */ 104 alias git_credential_ssh_key = libgit2_d.sys.credential.git_credential_ssh_key; 105 106 /** 107 * Keyboard-interactive based ssh authentication 108 */ 109 alias git_credential_ssh_interactive = libgit2_d.sys.credential.git_credential_ssh_interactive; 110 111 /** 112 * A key with a custom signature function 113 */ 114 alias git_credential_ssh_custom = libgit2_d.sys.credential.git_credential_ssh_custom; 115 116 /** 117 * Credential acquisition callback. 118 * 119 * This callback is usually involved any time another system might need 120 * authentication. As such, you are expected to provide a valid 121 * git_credential object back, depending on allowed_types (a 122 * git_credential_t bitmask). 123 * 124 * Note that most authentication details are your responsibility - this 125 * callback will be called until the authentication succeeds, or you report 126 * an error. As such, it's easy to get in a loop if you fail to stop providing 127 * the same incorrect credentials. 128 * 129 * Params: 130 * out_ = The newly created credential object. 131 * url = The resource for which we are demanding a credential. 132 * username_from_url = The username that was embedded in a "user\@host" remote url, or NULL if not included. 133 * allowed_types = A bitmask stating which credential types are OK to return. 134 * payload = The payload provided when specifying this callback. 135 * 136 * Returns: 0 for success, < 0 to indicate an error, > 0 to indicate no credential was acquired 137 */ 138 alias git_credential_acquire_cb = int function(.git_credential** out_, const (char)* url, const (char)* username_from_url, uint allowed_types, void* payload); 139 140 /** 141 * Free a credential. 142 * 143 * This is only necessary if you own the object; that is, if you are a 144 * transport. 145 * 146 * Params: 147 * cred = the object to free 148 */ 149 //GIT_EXTERN 150 void git_credential_free(.git_credential* cred); 151 152 /** 153 * Check whether a credential object contains username information. 154 * 155 * Params: 156 * cred = object to check 157 * 158 * Returns: 1 if the credential object has non-NULL username, 0 otherwise 159 */ 160 //GIT_EXTERN 161 int git_credential_has_username(.git_credential* cred); 162 163 /** 164 * Return the username associated with a credential object. 165 * 166 * Params: 167 * cred = object to check 168 * 169 * Returns: the credential username, or NULL if not applicable 170 */ 171 //GIT_EXTERN 172 const (char)* git_credential_get_username(.git_credential* cred); 173 174 /** 175 * Create a new plain-text username and password credential object. 176 * The supplied credential parameter will be internally duplicated. 177 * 178 * Params: 179 * out_ = The newly created credential object. 180 * username = The username of the credential. 181 * password = The password of the credential. 182 * 183 * Returns: 0 for success or an error code for failure 184 */ 185 //GIT_EXTERN 186 int git_credential_userpass_plaintext_new(.git_credential** out_, const (char)* username, const (char)* password); 187 188 /** 189 * Create a "default" credential usable for Negotiate mechanisms like NTLM 190 * or Kerberos authentication. 191 * 192 * Params: 193 * out_ = The newly created credential object. 194 * 195 * Returns: 0 for success or an error code for failure 196 */ 197 //GIT_EXTERN 198 int git_credential_default_new(.git_credential** out_); 199 200 /** 201 * Create a credential to specify a username. 202 * 203 * This is used with ssh authentication to query for the username if 204 * none is specified in the url. 205 * 206 * Params: 207 * out_ = The newly created credential object. 208 * username = The username to authenticate with 209 * 210 * Returns: 0 for success or an error code for failure 211 */ 212 //GIT_EXTERN 213 int git_credential_username_new(.git_credential** out_, const (char)* username); 214 215 /** 216 * Create a new passphrase-protected ssh key credential object. 217 * The supplied credential parameter will be internally duplicated. 218 * 219 * Params: 220 * out_ = The newly created credential object. 221 * username = username to use to authenticate 222 * publickey = The path to the public key of the credential. 223 * privatekey = The path to the private key of the credential. 224 * passphrase = The passphrase of the credential. 225 * 226 * Returns: 0 for success or an error code for failure 227 */ 228 //GIT_EXTERN 229 int git_credential_ssh_key_new(.git_credential** out_, const (char)* username, const (char)* publickey, const (char)* privatekey, const (char)* passphrase); 230 231 /** 232 * Create a new ssh key credential object reading the keys from memory. 233 * 234 * Params: 235 * out_ = The newly created credential object. 236 * username = username to use to authenticate. 237 * publickey = The public key of the credential. 238 * privatekey = The private key of the credential. 239 * passphrase = The passphrase of the credential. 240 * 241 * Returns: 0 for success or an error code for failure 242 */ 243 //GIT_EXTERN 244 int git_credential_ssh_key_memory_new(.git_credential** out_, const (char)* username, const (char)* publickey, const (char)* privatekey, const (char)* passphrase); 245 246 /* 247 * If the user hasn't included libssh2.h before git2.h, we need to 248 * define a few types for the callback signatures. 249 */ 250 version (LIBSSH2_VERSION) { 251 } else { 252 struct _LIBSSH2_SESSION; 253 struct _LIBSSH2_USERAUTH_KBDINT_PROMPT; 254 struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE; 255 alias LIBSSH2_SESSION = _LIBSSH2_SESSION; 256 alias LIBSSH2_USERAUTH_KBDINT_PROMPT = _LIBSSH2_USERAUTH_KBDINT_PROMPT; 257 alias LIBSSH2_USERAUTH_KBDINT_RESPONSE = _LIBSSH2_USERAUTH_KBDINT_RESPONSE; 258 } 259 260 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_); 261 262 /** 263 * Create a new ssh keyboard-interactive based credential object. 264 * The supplied credential parameter will be internally duplicated. 265 * 266 * Params: 267 * username = Username to use to authenticate. 268 * prompt_callback = The callback method used for prompts. 269 * payload = Additional data to pass to the callback. 270 * 271 * Returns: 0 for success or an error code for failure. 272 */ 273 //GIT_EXTERN 274 int git_credential_ssh_interactive_new(.git_credential** out_, const (char)* username, .git_credential_ssh_interactive_cb prompt_callback, void* payload); 275 276 /** 277 * Create a new ssh key credential object used for querying an ssh-agent. 278 * The supplied credential parameter will be internally duplicated. 279 * 280 * Params: 281 * out_ = The newly created credential object. 282 * username = username to use to authenticate 283 * 284 * Returns: 0 for success or an error code for failure 285 */ 286 //GIT_EXTERN 287 int git_credential_ssh_key_from_agent(.git_credential** out_, const (char)* username); 288 289 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_); 290 291 /** 292 * Create an ssh key credential with a custom signing function. 293 * 294 * This lets you use your own function to sign the challenge. 295 * 296 * This function and its credential type is provided for completeness 297 * and wraps `libssh2_userauth_publickey()`, which is undocumented. 298 * 299 * The supplied credential parameter will be internally duplicated. 300 * 301 * Params: 302 * out_ = The newly created credential object. 303 * username = username to use to authenticate 304 * publickey = The bytes of the public key. 305 * publickey_len = The length of the public key in bytes. 306 * sign_callback = The callback method to sign the data during the challenge. 307 * payload = Additional data to pass to the callback. 308 * 309 * Returns: 0 for success or an error code for failure 310 */ 311 //GIT_EXTERN 312 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); 313 314 /** @} */