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