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