include/git2/credential.h

   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