diff options
Diffstat (limited to 'include/git2/transport.h')
| -rw-r--r-- | include/git2/transport.h | 230 |
1 files changed, 158 insertions, 72 deletions
diff --git a/include/git2/transport.h b/include/git2/transport.h index 81bb3abe1..caabd0465 100644 --- a/include/git2/transport.h +++ b/include/git2/transport.h @@ -28,22 +28,31 @@ GIT_BEGIN_DECL *** Begin interface for credentials acquisition *** */ +/** Authentication type requested */ typedef enum { /* git_cred_userpass_plaintext */ - GIT_CREDTYPE_USERPASS_PLAINTEXT = 1, - GIT_CREDTYPE_SSH_KEYFILE_PASSPHRASE = 2, - GIT_CREDTYPE_SSH_PUBLICKEY = 3, + GIT_CREDTYPE_USERPASS_PLAINTEXT = (1u << 0), + + /* git_cred_ssh_key */ + GIT_CREDTYPE_SSH_KEY = (1u << 1), + + /* git_cred_ssh_custom */ + GIT_CREDTYPE_SSH_CUSTOM = (1u << 2), + + /* git_cred_default */ + GIT_CREDTYPE_DEFAULT = (1u << 3), } git_credtype_t; /* The base structure for all credential types */ -typedef struct git_cred { +typedef struct git_cred git_cred; + +struct git_cred { git_credtype_t credtype; - void (*free)( - struct git_cred *cred); -} git_cred; + void (*free)(git_cred *cred); +}; -/* A plaintext username and password */ -typedef struct git_cred_userpass_plaintext { +/** A plaintext username and password */ +typedef struct { git_cred parent; char *username; char *password; @@ -51,27 +60,46 @@ typedef struct git_cred_userpass_plaintext { #ifdef GIT_SSH typedef LIBSSH2_USERAUTH_PUBLICKEY_SIGN_FUNC((*git_cred_sign_callback)); +#else +typedef int (*git_cred_sign_callback)(void *, ...); +#endif -/* A ssh key file and passphrase */ -typedef struct git_cred_ssh_keyfile_passphrase { +/** + * A ssh key from disk + */ +typedef struct git_cred_ssh_key { git_cred parent; + char *username; char *publickey; char *privatekey; char *passphrase; -} git_cred_ssh_keyfile_passphrase; +} git_cred_ssh_key; -/* A ssh public key and authentication callback */ -typedef struct git_cred_ssh_publickey { +/** + * A key with a custom signature function + */ +typedef struct git_cred_ssh_custom { git_cred parent; + char *username; char *publickey; - size_t publickey_len; + size_t publickey_len; void *sign_callback; void *sign_data; -} git_cred_ssh_publickey; -#endif +} git_cred_ssh_custom; + +/** A key for NTLM/Kerberos "default" credentials */ +typedef struct git_cred git_cred_default; + +/** + * Check whether a credential object contains username information. + * + * @param cred object to check + * @return 1 if the credential object has non-NULL username, 0 otherwise + */ +GIT_EXTERN(int) git_cred_has_username(git_cred *cred); /** - * Creates a new plain-text username and password credential object. + * Create a new plain-text username and password credential object. * The supplied credential parameter will be internally duplicated. * * @param out The newly created credential object. @@ -84,52 +112,68 @@ GIT_EXTERN(int) git_cred_userpass_plaintext_new( const char *username, const char *password); -#ifdef GIT_SSH /** - * Creates a new ssh key file and passphrase credential object. + * Create a new passphrase-protected ssh key credential object. * The supplied credential parameter will be internally duplicated. * * @param out The newly created credential object. + * @param username username to use to authenticate * @param publickey The path to the public key of the credential. * @param privatekey The path to the private key of the credential. * @param passphrase The passphrase of the credential. * @return 0 for success or an error code for failure */ -GIT_EXTERN(int) git_cred_ssh_keyfile_passphrase_new( +GIT_EXTERN(int) git_cred_ssh_key_new( git_cred **out, + const char *username, const char *publickey, const char *privatekey, - const char *passphrase); + const char *passphrase); /** - * Creates a new ssh public key credential object. + * Create an ssh key credential with a custom signing function. + * + * This lets you use your own function to sign the challenge. + * + * This function and its credential type is provided for completeness + * and wraps `libssh2_userauth_publickey()`, which is undocumented. + * * The supplied credential parameter will be internally duplicated. * * @param out The newly created credential object. + * @param username username to use to authenticate * @param publickey The bytes of the public key. * @param publickey_len The length of the public key in bytes. - * @param sign_callback The callback method for authenticating. - * @param sign_data The abstract data sent to the sign_callback method. + * @param sign_fn The callback method to sign the data during the challenge. + * @param sign_data The data to pass to the sign function. * @return 0 for success or an error code for failure */ -GIT_EXTERN(int) git_cred_ssh_publickey_new( +GIT_EXTERN(int) git_cred_ssh_custom_new( git_cred **out, + const char *username, const char *publickey, - size_t publickey_len, - git_cred_sign_callback, - void *sign_data); -#endif + size_t publickey_len, + git_cred_sign_callback sign_fn, + void *sign_data); + +/** + * Create a "default" credential usable for Negotiate mechanisms like NTLM + * or Kerberos authentication. + * + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_cred_default_new(git_cred **out); /** * Signature of a function which acquires a credential object. * - * @param cred The newly created credential object. - * @param url The resource for which we are demanding a credential. - * @param username_from_url The username that was embedded in a "user@host" + * - cred: The newly created credential object. + * - url: The resource for which we are demanding a credential. + * - username_from_url: The username that was embedded in a "user@host" * remote url, or NULL if not included. - * @param allowed_types A bitmask stating which cred types are OK to return. - * @param payload The payload provided when specifying this callback. - * @return 0 for success or an error code for failure + * - allowed_types: A bitmask stating which cred types are OK to return. + * - payload: The payload provided when specifying this callback. + * - returns 0 for success or non-zero to indicate an error */ typedef int (*git_cred_acquire_cb)( git_cred **cred, @@ -150,39 +194,45 @@ typedef enum { GIT_TRANSPORTFLAGS_NO_CHECK_CERT = 1 } git_transport_flags_t; -typedef void (*git_transport_message_cb)(const char *str, int len, void *data); +typedef int (*git_transport_message_cb)(const char *str, int len, void *data); + +typedef struct git_transport git_transport; -typedef struct git_transport { +struct git_transport { unsigned int version; /* Set progress and error callbacks */ - int (*set_callbacks)(struct git_transport *transport, + int (*set_callbacks)( + git_transport *transport, git_transport_message_cb progress_cb, git_transport_message_cb error_cb, void *payload); /* Connect the transport to the remote repository, using the given * direction. */ - int (*connect)(struct git_transport *transport, + int (*connect)( + git_transport *transport, const char *url, git_cred_acquire_cb cred_acquire_cb, void *cred_acquire_payload, int direction, int flags); - /* This function may be called after a successful call to connect(). The - * provided callback is invoked for each ref discovered on the remote - * end. */ - int (*ls)(struct git_transport *transport, - git_headlist_cb list_cb, - void *payload); + /* This function may be called after a successful call to + * connect(). The array returned is owned by the transport and + * is guranteed until the next call of a transport function. */ + int (*ls)( + const git_remote_head ***out, + size_t *size, + git_transport *transport); /* Executes the push whose context is in the git_push object. */ - int (*push)(struct git_transport *transport, git_push *push); + int (*push)(git_transport *transport, git_push *push); /* This function may be called after a successful call to connect(), when * the direction is FETCH. The function performs a negotiation to calculate * the wants list for the fetch. */ - int (*negotiate_fetch)(struct git_transport *transport, + int (*negotiate_fetch)( + git_transport *transport, git_repository *repo, const git_remote_head * const *refs, size_t count); @@ -190,28 +240,29 @@ typedef struct git_transport { /* This function may be called after a successful call to negotiate_fetch(), * when the direction is FETCH. This function retrieves the pack file for * the fetch from the remote end. */ - int (*download_pack)(struct git_transport *transport, + int (*download_pack)( + git_transport *transport, git_repository *repo, git_transfer_progress *stats, git_transfer_progress_callback progress_cb, void *progress_payload); /* Checks to see if the transport is connected */ - int (*is_connected)(struct git_transport *transport); + int (*is_connected)(git_transport *transport); /* Reads the flags value previously passed into connect() */ - int (*read_flags)(struct git_transport *transport, int *flags); + int (*read_flags)(git_transport *transport, int *flags); /* Cancels any outstanding transport operation */ - void (*cancel)(struct git_transport *transport); + void (*cancel)(git_transport *transport); /* This function is the reverse of connect() -- it terminates the * connection to the remote end. */ - int (*close)(struct git_transport *transport); + int (*close)(git_transport *transport); /* Frees/destructs the git_transport object. */ - void (*free)(struct git_transport *transport); -} git_transport; + void (*free)(git_transport *transport); +}; #define GIT_TRANSPORT_VERSION 1 #define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION} @@ -231,6 +282,40 @@ GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const /* Signature of a function which creates a transport */ typedef int (*git_transport_cb)(git_transport **out, git_remote *owner, void *param); +/** + * Add a custom transport definition, to be used in addition to the built-in + * set of transports that come with libgit2. + * + * The caller is responsible for synchronizing calls to git_transport_register + * and git_transport_unregister with other calls to the library that + * instantiate transports. + * + * @param prefix The scheme (ending in "://") to match, i.e. "git://" + * @param priority The priority of this transport relative to others with + * the same prefix. Built-in transports have a priority of 1. + * @param cb The callback used to create an instance of the transport + * @param param A fixed parameter to pass to cb at creation time + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_register( + const char *prefix, + unsigned priority, + git_transport_cb cb, + void *param); + +/** + * + * Unregister a custom transport definition which was previously registered + * with git_transport_register. + * + * @param prefix From the previous call to git_transport_register + * @param priority From the previous call to git_transport_register + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_unregister( + const char *prefix, + unsigned priority); + /* Transports which come with libgit2 (match git_transport_cb). The expected * value for "param" is listed in-line below. */ @@ -299,35 +384,36 @@ typedef enum { GIT_SERVICE_RECEIVEPACK = 4, } git_smart_service_t; -struct git_smart_subtransport; +typedef struct git_smart_subtransport git_smart_subtransport; +typedef struct git_smart_subtransport_stream git_smart_subtransport_stream; /* A stream used by the smart transport to read and write data * from a subtransport */ -typedef struct git_smart_subtransport_stream { +struct git_smart_subtransport_stream { /* The owning subtransport */ - struct git_smart_subtransport *subtransport; + git_smart_subtransport *subtransport; int (*read)( - struct git_smart_subtransport_stream *stream, - char *buffer, - size_t buf_size, - size_t *bytes_read); + git_smart_subtransport_stream *stream, + char *buffer, + size_t buf_size, + size_t *bytes_read); int (*write)( - struct git_smart_subtransport_stream *stream, - const char *buffer, - size_t len); + git_smart_subtransport_stream *stream, + const char *buffer, + size_t len); void (*free)( - struct git_smart_subtransport_stream *stream); -} git_smart_subtransport_stream; + git_smart_subtransport_stream *stream); +}; /* An implementation of a subtransport which carries data for the * smart transport */ -typedef struct git_smart_subtransport { +struct git_smart_subtransport { int (* action)( git_smart_subtransport_stream **out, - struct git_smart_subtransport *transport, + git_smart_subtransport *transport, const char *url, git_smart_service_t action); @@ -337,10 +423,10 @@ typedef struct git_smart_subtransport { * * 1. UPLOADPACK_LS -> UPLOADPACK * 2. RECEIVEPACK_LS -> RECEIVEPACK */ - int (* close)(struct git_smart_subtransport *transport); + int (*close)(git_smart_subtransport *transport); - void (* free)(struct git_smart_subtransport *transport); -} git_smart_subtransport; + void (*free)(git_smart_subtransport *transport); +}; /* A function which creates a new subtransport for the smart transport */ typedef int (*git_smart_subtransport_cb)( |