include/git2/transport.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_transport_h__
   8 #define INCLUDE_git_transport_h__
   9
  10 #include "indexer.h"
  11 #include "net.h"
  12 #include "types.h"
  13
  14 /**
  15  * @file git2/transport.h
  16  * @brief Git transport interfaces and functions
  17  * @defgroup git_transport interfaces and functions
  18  * @ingroup Git
  19  * @{
  20  */
  21 GIT_BEGIN_DECL
  22
  23 /** Signature of a function which creates a transport */
  24 typedef int (*git_transport_cb)(git_transport **out, git_remote *owner, void *param);
  25
  26 /**
  27  * Type of SSH host fingerprint
  28  */
  29 typedef enum {
  30         /** MD5 is available */
  31         GIT_CERT_SSH_MD5 = (1 << 0),
  32         /** SHA-1 is available */
  33         GIT_CERT_SSH_SHA1 = (1 << 1),
  34 } git_cert_ssh_t;
  35
  36 /**
  37  * Hostkey information taken from libssh2
  38  */
  39 typedef struct {
  40         git_cert parent;
  41
  42         /**
  43          * A hostkey type from libssh2, either
  44          * `GIT_CERT_SSH_MD5` or `GIT_CERT_SSH_SHA1`
  45          */
  46         git_cert_ssh_t type;
  47
  48         /**
  49          * Hostkey hash. If type has `GIT_CERT_SSH_MD5` set, this will
  50          * have the MD5 hash of the hostkey.
  51          */
  52         unsigned char hash_md5[16];
  53
  54         /**
  55          * Hostkey hash. If type has `GIT_CERT_SSH_SHA1` set, this will
  56          * have the SHA-1 hash of the hostkey.
  57          */
  58         unsigned char hash_sha1[20];
  59 } git_cert_hostkey;
  60
  61 /**
  62  * X.509 certificate information
  63  */
  64 typedef struct {
  65         git_cert parent;
  66         /**
  67          * Pointer to the X.509 certificate data
  68          */
  69         void *data;
  70         /**
  71          * Length of the memory block pointed to by `data`.
  72          */
  73         size_t len;
  74 } git_cert_x509;
  75
  76 /*
  77  *** Begin interface for credentials acquisition ***
  78  */
  79
  80 /** Authentication type requested */
  81 typedef enum {
  82         /* git_cred_userpass_plaintext */
  83         GIT_CREDTYPE_USERPASS_PLAINTEXT = (1u << 0),
  84
  85         /* git_cred_ssh_key */
  86         GIT_CREDTYPE_SSH_KEY = (1u << 1),
  87
  88         /* git_cred_ssh_custom */
  89         GIT_CREDTYPE_SSH_CUSTOM = (1u << 2),
  90
  91         /* git_cred_default */
  92         GIT_CREDTYPE_DEFAULT = (1u << 3),
  93
  94         /* git_cred_ssh_interactive */
  95         GIT_CREDTYPE_SSH_INTERACTIVE = (1u << 4),
  96
  97         /**
  98          * Username-only information
  99          *
 100          * If the SSH transport does not know which username to use,
 101          * it will ask via this credential type.
 102          */
 103         GIT_CREDTYPE_USERNAME = (1u << 5),
 104
 105         /**
 106          * Credentials read from memory.
 107          *
 108          * Only available for libssh2+OpenSSL for now.
 109          */
 110         GIT_CREDTYPE_SSH_MEMORY = (1u << 6),
 111 } git_credtype_t;
 112
 113 /* The base structure for all credential types */
 114 typedef struct git_cred git_cred;
 115
 116 struct git_cred {
 117         git_credtype_t credtype;
 118         void (*free)(git_cred *cred);
 119 };
 120
 121 /** A plaintext username and password */
 122 typedef struct {
 123         git_cred parent;
 124         char *username;
 125         char *password;
 126 } git_cred_userpass_plaintext;
 127
 128
 129 /*
 130  * If the user hasn't included libssh2.h before git2.h, we need to
 131  * define a few types for the callback signatures.
 132  */
 133 #ifndef LIBSSH2_VERSION
 134 typedef struct _LIBSSH2_SESSION LIBSSH2_SESSION;
 135 typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT LIBSSH2_USERAUTH_KBDINT_PROMPT;
 136 typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE LIBSSH2_USERAUTH_KBDINT_RESPONSE;
 137 #endif
 138
 139 typedef int (*git_cred_sign_callback)(LIBSSH2_SESSION *session, unsigned char **sig, size_t *sig_len, const unsigned char *data, size_t data_len, void **abstract);
 140 typedef void (*git_cred_ssh_interactive_callback)(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);
 141
 142 /**
 143  * A ssh key from disk
 144  */
 145 typedef struct git_cred_ssh_key {
 146         git_cred parent;
 147         char *username;
 148         char *publickey;
 149         char *privatekey;
 150         char *passphrase;
 151 } git_cred_ssh_key;
 152
 153 /**
 154  * Keyboard-interactive based ssh authentication
 155  */
 156 typedef struct git_cred_ssh_interactive {
 157         git_cred parent;
 158         char *username;
 159         git_cred_ssh_interactive_callback prompt_callback;
 160         void *payload;
 161 } git_cred_ssh_interactive;
 162
 163 /**
 164  * A key with a custom signature function
 165  */
 166 typedef struct git_cred_ssh_custom {
 167         git_cred parent;
 168         char *username;
 169         char *publickey;
 170         size_t publickey_len;
 171         git_cred_sign_callback sign_callback;
 172         void *payload;
 173 } git_cred_ssh_custom;
 174
 175 /** A key for NTLM/Kerberos "default" credentials */
 176 typedef struct git_cred git_cred_default;
 177
 178 /** Username-only credential information */
 179 typedef struct git_cred_username {
 180         git_cred parent;
 181         char username[1];
 182 } git_cred_username;
 183
 184 /**
 185  * Check whether a credential object contains username information.
 186  *
 187  * @param cred object to check
 188  * @return 1 if the credential object has non-NULL username, 0 otherwise
 189  */
 190 GIT_EXTERN(int) git_cred_has_username(git_cred *cred);
 191
 192 /**
 193  * Create a new plain-text username and password credential object.
 194  * The supplied credential parameter will be internally duplicated.
 195  *
 196  * @param out The newly created credential object.
 197  * @param username The username of the credential.
 198  * @param password The password of the credential.
 199  * @return 0 for success or an error code for failure
 200  */
 201 GIT_EXTERN(int) git_cred_userpass_plaintext_new(
 202         git_cred **out,
 203         const char *username,
 204         const char *password);
 205
 206 /**
 207  * Create a new passphrase-protected ssh key credential object.
 208  * The supplied credential parameter will be internally duplicated.
 209  *
 210  * @param out The newly created credential object.
 211  * @param username username to use to authenticate
 212  * @param publickey The path to the public key of the credential.
 213  * @param privatekey The path to the private key of the credential.
 214  * @param passphrase The passphrase of the credential.
 215  * @return 0 for success or an error code for failure
 216  */
 217 GIT_EXTERN(int) git_cred_ssh_key_new(
 218         git_cred **out,
 219         const char *username,
 220         const char *publickey,
 221         const char *privatekey,
 222         const char *passphrase);
 223
 224 /**
 225  * Create a new ssh keyboard-interactive based credential object.
 226  * The supplied credential parameter will be internally duplicated.
 227  *
 228  * @param username Username to use to authenticate.
 229  * @param prompt_callback The callback method used for prompts.
 230  * @param payload Additional data to pass to the callback.
 231  * @return 0 for success or an error code for failure.
 232  */
 233 GIT_EXTERN(int) git_cred_ssh_interactive_new(
 234         git_cred **out,
 235         const char *username,
 236         git_cred_ssh_interactive_callback prompt_callback,
 237         void *payload);
 238
 239 /**
 240  * Create a new ssh key credential object used for querying an ssh-agent.
 241  * The supplied credential parameter will be internally duplicated.
 242  *
 243  * @param out The newly created credential object.
 244  * @param username username to use to authenticate
 245  * @return 0 for success or an error code for failure
 246  */
 247 GIT_EXTERN(int) git_cred_ssh_key_from_agent(
 248         git_cred **out,
 249         const char *username);
 250
 251 /**
 252  * Create an ssh key credential with a custom signing function.
 253  *
 254  * This lets you use your own function to sign the challenge.
 255  *
 256  * This function and its credential type is provided for completeness
 257  * and wraps `libssh2_userauth_publickey()`, which is undocumented.
 258  *
 259  * The supplied credential parameter will be internally duplicated.
 260  *
 261  * @param out The newly created credential object.
 262  * @param username username to use to authenticate
 263  * @param publickey The bytes of the public key.
 264  * @param publickey_len The length of the public key in bytes.
 265  * @param sign_callback The callback method to sign the data during the challenge.
 266  * @param payload Additional data to pass to the callback.
 267  * @return 0 for success or an error code for failure
 268  */
 269 GIT_EXTERN(int) git_cred_ssh_custom_new(
 270         git_cred **out,
 271         const char *username,
 272         const char *publickey,
 273         size_t publickey_len,
 274         git_cred_sign_callback sign_callback,
 275         void *payload);
 276
 277 /**
 278  * Create a "default" credential usable for Negotiate mechanisms like NTLM
 279  * or Kerberos authentication.
 280  *
 281  * @return 0 for success or an error code for failure
 282  */
 283 GIT_EXTERN(int) git_cred_default_new(git_cred **out);
 284
 285 /**
 286  * Create a credential to specify a username.
 287  *
 288  * This is used with ssh authentication to query for the username if
 289  * none is specified in the url.
 290  */
 291 GIT_EXTERN(int) git_cred_username_new(git_cred **cred, const char *username);
 292
 293 /**
 294  * Create a new ssh key credential object reading the keys from memory.
 295  *
 296  * @param out The newly created credential object.
 297  * @param username username to use to authenticate.
 298  * @param publickey The public key of the credential.
 299  * @param privatekey The private key of the credential.
 300  * @param passphrase The passphrase of the credential.
 301  * @return 0 for success or an error code for failure
 302  */
 303 GIT_EXTERN(int) git_cred_ssh_key_memory_new(
 304         git_cred **out,
 305         const char *username,
 306         const char *publickey,
 307         const char *privatekey,
 308         const char *passphrase);
 309
 310
 311 /**
 312  * Free a credential.
 313  *
 314  * This is only necessary if you own the object; that is, if you are a
 315  * transport.
 316  *
 317  * @param cred the object to free
 318  */
 319 GIT_EXTERN(void) git_cred_free(git_cred *cred);
 320
 321 /**
 322  * Signature of a function which acquires a credential object.
 323  *
 324  * @param cred The newly created credential object.
 325  * @param url The resource for which we are demanding a credential.
 326  * @param username_from_url The username that was embedded in a "user\@host"
 327  *                          remote url, or NULL if not included.
 328  * @param allowed_types A bitmask stating which cred types are OK to return.
 329  * @param payload The payload provided when specifying this callback.
 330  * @return 0 for success, < 0 to indicate an error, > 0 to indicate
 331  *       no credential was acquired
 332  */
 333 typedef int (*git_cred_acquire_cb)(
 334         git_cred **cred,
 335         const char *url,
 336         const char *username_from_url,
 337         unsigned int allowed_types,
 338         void *payload);
 339
 340 /** @} */
 341 GIT_END_DECL
 342 #endif