From 8bf0f7eb26c65b2b937b1f40a384b9b269b0b76d Mon Sep 17 00:00:00 2001 From: Etienne Samson Date: Mon, 9 Sep 2019 13:00:27 +0200 Subject: cred: separate public interface from low-level details --- include/git2.h | 1 + include/git2/cred.h | 308 +++++++++++++++++++++++++++++++++++++++++++++++ include/git2/proxy.h | 2 +- include/git2/sys/cred.h | 90 ++++++++++++++ include/git2/transport.h | 307 +--------------------------------------------- 5 files changed, 402 insertions(+), 306 deletions(-) create mode 100644 include/git2/cred.h create mode 100644 include/git2/sys/cred.h (limited to 'include') diff --git a/include/git2.h b/include/git2.h index c07c26038..82ac1d3e9 100644 --- a/include/git2.h +++ b/include/git2.h @@ -21,6 +21,7 @@ #include "git2/commit.h" #include "git2/common.h" #include "git2/config.h" +#include "git2/cred.h" #include "git2/deprecated.h" #include "git2/describe.h" #include "git2/diff.h" diff --git a/include/git2/cred.h b/include/git2/cred.h new file mode 100644 index 000000000..e89ab2361 --- /dev/null +++ b/include/git2/cred.h @@ -0,0 +1,308 @@ +/* + * Copyright (C) the libgit2 contributors. All rights reserved. + * + * This file is part of libgit2, distributed under the GNU GPL v2 with + * a Linking Exception. For full terms see the included COPYING file. + */ +#ifndef INCLUDE_git_cred_h__ +#define INCLUDE_git_cred_h__ + +#include "common.h" + +/** + * @file git2/cred.h + * @brief Git authentication & credential management + * @defgroup git_cred Authentication & credential management + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Supported credential types + * + * This represents the various types of authentication methods supported by + * the library. + */ +typedef enum { + /** + * A vanilla user/password request + * @see git_cred_userpass_plaintext_new + */ + GIT_CREDTYPE_USERPASS_PLAINTEXT = (1u << 0), + + /** + * An SSH key-based authentication request + * @see git_cred_ssh_key_new + */ + GIT_CREDTYPE_SSH_KEY = (1u << 1), + + /** + * An SSH key-based authentication request, with a custom signature + * @see git_cred_ssh_custom_new + */ + GIT_CREDTYPE_SSH_CUSTOM = (1u << 2), + + /** + * An NTLM/Negotiate-based authentication request. + * @see git_cred_default + */ + GIT_CREDTYPE_DEFAULT = (1u << 3), + + /** + * An SSH interactive authentication request + * @see git_cred_ssh_interactive_new + */ + GIT_CREDTYPE_SSH_INTERACTIVE = (1u << 4), + + /** + * Username-only authentication request + * + * Used as a pre-authentication step if the underlying transport + * (eg. SSH, with no username in its URL) does not know which username + * to use. + * + * @see git_cred_username_new + */ + GIT_CREDTYPE_USERNAME = (1u << 5), + + /** + * An SSH key-based authentication request + * + * Allows credentials to be read from memory instead of files. + * Note that because of differences in crypto backend support, it might + * not be functional. + * + * @see git_cred_ssh_key_memory_new + */ + GIT_CREDTYPE_SSH_MEMORY = (1u << 6), +} git_credtype_t; + +/** + * The base structure for all credential types + */ +typedef struct git_cred git_cred; + +typedef struct git_cred_userpass_plaintext git_cred_userpass_plaintext; + +/** Username-only credential information */ +typedef struct git_cred_username git_cred_username; + +/** A key for NTLM/Kerberos "default" credentials */ +typedef struct git_cred git_cred_default; + +/** + * A ssh key from disk + */ +typedef struct git_cred_ssh_key git_cred_ssh_key; + +/** + * Keyboard-interactive based ssh authentication + */ +typedef struct git_cred_ssh_interactive git_cred_ssh_interactive; + +/** + * A key with a custom signature function + */ +typedef struct git_cred_ssh_custom git_cred_ssh_custom; + +/** + * Credential acquisition callback. + * + * This callback is usually involved any time another system might need + * authentication. As such, you are expected to provide a valid git_cred + * object back, depending on allowed_types (a git_credtype_t bitmask). + * + * Note that most authentication details are your responsibility - this + * callback will be called until the authentication succeeds, or you report + * an error. As such, it's easy to get in a loop if you fail to stop providing + * the same incorrect credentials. + * + * @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" + * 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, < 0 to indicate an error, > 0 to indicate + * no credential was acquired + */ +typedef int GIT_CALLBACK(git_cred_acquire_cb)( + git_cred **cred, + const char *url, + const char *username_from_url, + unsigned int allowed_types, + void *payload); + +/** + * Free a credential. + * + * This is only necessary if you own the object; that is, if you are a + * transport. + * + * @param cred the object to free + */ +GIT_EXTERN(void) git_cred_free(git_cred *cred); + +/** + * 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); + +/** + * Return the username associated with a credential object. + * + * @param cred object to check + * @return the credential username, or NULL if not applicable + */ +GIT_EXTERN(const char *) git_cred_get_username(git_cred *cred); + +/** + * 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. + * @param username The username of the credential. + * @param password The password of the credential. + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_cred_userpass_plaintext_new( + git_cred **out, + const char *username, + const char *password); + +/** + * 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); + +/** + * Create a credential to specify a username. + * + * This is used with ssh authentication to query for the username if + * none is specified in the url. + */ +GIT_EXTERN(int) git_cred_username_new(git_cred **cred, const char *username); + +/** + * 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_key_new( + git_cred **out, + const char *username, + const char *publickey, + const char *privatekey, + const char *passphrase); + +/** + * Create a new ssh key credential object reading the keys from memory. + * + * @param out The newly created credential object. + * @param username username to use to authenticate. + * @param publickey The public key of the credential. + * @param privatekey 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_key_memory_new( + git_cred **out, + const char *username, + const char *publickey, + const char *privatekey, + const char *passphrase); + +/* + * If the user hasn't included libssh2.h before git2.h, we need to + * define a few types for the callback signatures. + */ +#ifndef LIBSSH2_VERSION +typedef struct _LIBSSH2_SESSION LIBSSH2_SESSION; +typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT LIBSSH2_USERAUTH_KBDINT_PROMPT; +typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE LIBSSH2_USERAUTH_KBDINT_RESPONSE; +#endif + +typedef void GIT_CALLBACK(git_cred_ssh_interactive_cb)( + 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); + + +/** + * Create a new ssh keyboard-interactive based credential object. + * The supplied credential parameter will be internally duplicated. + * + * @param username Username to use to authenticate. + * @param prompt_callback The callback method used for prompts. + * @param payload Additional data to pass to the callback. + * @return 0 for success or an error code for failure. + */ +GIT_EXTERN(int) git_cred_ssh_interactive_new( + git_cred **out, + const char *username, + git_cred_ssh_interactive_cb prompt_callback, + void *payload); + +/** + * Create a new ssh key credential object used for querying an ssh-agent. + * The supplied credential parameter will be internally duplicated. + * + * @param out The newly created credential object. + * @param username username to use to authenticate + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_cred_ssh_key_from_agent( + git_cred **out, + const char *username); + +typedef int GIT_CALLBACK(git_cred_sign_cb)( + LIBSSH2_SESSION *session, + unsigned char **sig, size_t *sig_len, + const unsigned char *data, size_t data_len, + void **abstract); + +/** + * 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 to sign the data during the challenge. + * @param payload Additional data to pass to the callback. + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_cred_ssh_custom_new( + git_cred **out, + const char *username, + const char *publickey, + size_t publickey_len, + git_cred_sign_cb sign_callback, + void *payload); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/proxy.h b/include/git2/proxy.h index 8fdcaa31d..0b3b1fac1 100644 --- a/include/git2/proxy.h +++ b/include/git2/proxy.h @@ -8,7 +8,7 @@ #define INCLUDE_git_proxy_h__ #include "common.h" -#include "transport.h" +#include "cred.h" GIT_BEGIN_DECL diff --git a/include/git2/sys/cred.h b/include/git2/sys/cred.h new file mode 100644 index 000000000..7636e79e4 --- /dev/null +++ b/include/git2/sys/cred.h @@ -0,0 +1,90 @@ +/* + * Copyright (C) the libgit2 contributors. All rights reserved. + * + * This file is part of libgit2, distributed under the GNU GPL v2 with + * a Linking Exception. For full terms see the included COPYING file. + */ +#ifndef INCLUDE_sys_git_cred_h__ +#define INCLUDE_sys_git_cred_h__ + +#include "git2/common.h" +#include "git2/cred.h" + +/** + * @file git2/sys/cred.h + * @brief Git credentials low-level implementation + * @defgroup git_cred Git credentials low-level implementation + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * The base structure for all credential types + */ +struct git_cred { + git_credtype_t credtype; /**< A type of credential */ + + /** The deallocator for this type of credentials */ + void GIT_CALLBACK(free)(git_cred *cred); +}; + +/** A plaintext username and password */ +struct git_cred_userpass_plaintext { + git_cred parent; /**< The parent cred */ + char *username; /**< The username to authenticate as */ + char *password; /**< The password to use */ +}; + +/** Username-only credential information */ +struct git_cred_username { + git_cred parent; /**< The parent cred */ + char username[1]; /**< The username to authenticate as */ +}; + +/** + * A ssh key from disk + */ +struct git_cred_ssh_key { + git_cred parent; /**< The parent cred */ + char *username; /**< The username to authenticate as */ + char *publickey; /**< The path to a public key */ + char *privatekey; /**< The path to a private key */ + char *passphrase; /**< Passphrase used to decrypt the private key */ +}; + +/** + * Keyboard-interactive based ssh authentication + */ +struct git_cred_ssh_interactive { + git_cred parent; /**< The parent cred */ + char *username; /**< The username to authenticate as */ + + /** + * Callback used for authentication. + */ + git_cred_ssh_interactive_cb prompt_callback; + + void *payload; /**< Payload passed to prompt_callback */ +}; + +/** + * A key with a custom signature function + */ +struct git_cred_ssh_custom { + git_cred parent; /**< The parent cred */ + char *username; /**< The username to authenticate as */ + char *publickey; /**< The public key data */ + size_t publickey_len; /**< Length of the public key */ + + /** + * Callback used to sign the data. + */ + git_cred_sign_cb sign_callback; + + void *payload; /**< Payload passed to prompt_callback */ +}; + +GIT_END_DECL + +#endif diff --git a/include/git2/transport.h b/include/git2/transport.h index ab45a3a1f..5b42634ad 100644 --- a/include/git2/transport.h +++ b/include/git2/transport.h @@ -10,6 +10,7 @@ #include "indexer.h" #include "net.h" #include "types.h" +#include "cred.h" /** * @file git2/transport.h @@ -75,311 +76,7 @@ typedef struct { size_t len; } git_cert_x509; -/* - *** Begin interface for credentials acquisition *** - */ - -/** - * Supported credential types - * - * This represents the various types of authentication methods supported by - * the library. - */ -typedef enum { - /** - * A vanilla user/password request - * @see git_cred_userpass_plaintext_new - */ - GIT_CREDTYPE_USERPASS_PLAINTEXT = (1u << 0), - - /** - * An SSH key-based authentication request - * @see git_cred_ssh_key_new - */ - GIT_CREDTYPE_SSH_KEY = (1u << 1), - - /** - * An SSH key-based authentication request, with a custom signature - * @see git_cred_ssh_custom_new - */ - GIT_CREDTYPE_SSH_CUSTOM = (1u << 2), - - /** - * An NTLM/Negotiate-based authentication request. - * @see git_cred_default - */ - GIT_CREDTYPE_DEFAULT = (1u << 3), - - /** - * An SSH interactive authentication request - * @see git_cred_ssh_interactive_new - */ - GIT_CREDTYPE_SSH_INTERACTIVE = (1u << 4), - - /** - * Username-only authentication request - * - * Used as a pre-authentication step if the underlying transport - * (eg. SSH, with no username in its URL) does not know which username - * to use. - * - * @see git_cred_username_new - */ - GIT_CREDTYPE_USERNAME = (1u << 5), - - /** - * An SSH key-based authentication request - * - * Allows credentials to be read from memory instead of files. - * Note that because of differences in crypto backend support, it might - * not be functional. - * - * @see git_cred_ssh_key_memory_new - */ - GIT_CREDTYPE_SSH_MEMORY = (1u << 6), -} git_credtype_t; - -typedef struct git_cred git_cred; - -/** - * The base structure for all credential types - */ -struct git_cred { - git_credtype_t credtype; /**< A type of credential */ - - /** The deallocator for this type of credentials */ - void GIT_CALLBACK(free)(git_cred *cred); -}; - -/** A plaintext username and password */ -typedef struct { - git_cred parent; /**< The parent cred */ - char *username; /**< The username to authenticate as */ - char *password; /**< The password to use */ -} git_cred_userpass_plaintext; - - -/* - * If the user hasn't included libssh2.h before git2.h, we need to - * define a few types for the callback signatures. - */ -#ifndef LIBSSH2_VERSION -typedef struct _LIBSSH2_SESSION LIBSSH2_SESSION; -typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT LIBSSH2_USERAUTH_KBDINT_PROMPT; -typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE LIBSSH2_USERAUTH_KBDINT_RESPONSE; -#endif - -typedef int GIT_CALLBACK(git_cred_sign_cb)(LIBSSH2_SESSION *session, unsigned char **sig, size_t *sig_len, const unsigned char *data, size_t data_len, void **abstract); -typedef void GIT_CALLBACK(git_cred_ssh_interactive_cb)(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); - -/** - * A ssh key from disk - */ -typedef struct git_cred_ssh_key { - git_cred parent; /**< The parent cred */ - char *username; /**< The username to authenticate as */ - char *publickey; /**< The path to a public key */ - char *privatekey; /**< The path to a private key */ - char *passphrase; /**< Passphrase used to decrypt the private key */ -} git_cred_ssh_key; - -/** - * Keyboard-interactive based ssh authentication - */ -typedef struct git_cred_ssh_interactive { - git_cred parent; /**< The parent cred */ - char *username; /**< The username to authenticate as */ - - /** - * Callback used for authentication. - */ - git_cred_ssh_interactive_cb prompt_callback; - - void *payload; /**< Payload passed to prompt_callback */ -} git_cred_ssh_interactive; - -/** - * A key with a custom signature function - */ -typedef struct git_cred_ssh_custom { - git_cred parent; /**< The parent cred */ - char *username; /**< The username to authenticate as */ - char *publickey; /**< The public key data */ - size_t publickey_len; /**< Length of the public key */ - - /** - * Callback used to sign the data. - */ - git_cred_sign_cb sign_callback; - - void *payload; /**< Payload passed to prompt_callback */ -} git_cred_ssh_custom; - -/** A key for NTLM/Kerberos "default" credentials */ -typedef struct git_cred git_cred_default; - -/** Username-only credential information */ -typedef struct git_cred_username { - git_cred parent; /**< The parent cred */ - char username[1]; /**< The username to authenticate as */ -} git_cred_username; - -/** - * 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); - -/** - * 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. - * @param username The username of the credential. - * @param password The password of the credential. - * @return 0 for success or an error code for failure - */ -GIT_EXTERN(int) git_cred_userpass_plaintext_new( - git_cred **out, - const char *username, - const char *password); - -/** - * 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_key_new( - git_cred **out, - const char *username, - const char *publickey, - const char *privatekey, - const char *passphrase); - -/** - * Create a new ssh keyboard-interactive based credential object. - * The supplied credential parameter will be internally duplicated. - * - * @param username Username to use to authenticate. - * @param prompt_callback The callback method used for prompts. - * @param payload Additional data to pass to the callback. - * @return 0 for success or an error code for failure. - */ -GIT_EXTERN(int) git_cred_ssh_interactive_new( - git_cred **out, - const char *username, - git_cred_ssh_interactive_cb prompt_callback, - void *payload); - -/** - * Create a new ssh key credential object used for querying an ssh-agent. - * The supplied credential parameter will be internally duplicated. - * - * @param out The newly created credential object. - * @param username username to use to authenticate - * @return 0 for success or an error code for failure - */ -GIT_EXTERN(int) git_cred_ssh_key_from_agent( - git_cred **out, - const char *username); - -/** - * 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 to sign the data during the challenge. - * @param payload Additional data to pass to the callback. - * @return 0 for success or an error code for failure - */ -GIT_EXTERN(int) git_cred_ssh_custom_new( - git_cred **out, - const char *username, - const char *publickey, - size_t publickey_len, - git_cred_sign_cb sign_callback, - void *payload); - -/** - * 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); - -/** - * Create a credential to specify a username. - * - * This is used with ssh authentication to query for the username if - * none is specified in the url. - */ -GIT_EXTERN(int) git_cred_username_new(git_cred **cred, const char *username); - -/** - * Create a new ssh key credential object reading the keys from memory. - * - * @param out The newly created credential object. - * @param username username to use to authenticate. - * @param publickey The public key of the credential. - * @param privatekey 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_key_memory_new( - git_cred **out, - const char *username, - const char *publickey, - const char *privatekey, - const char *passphrase); - - -/** - * Free a credential. - * - * This is only necessary if you own the object; that is, if you are a - * transport. - * - * @param cred the object to free - */ -GIT_EXTERN(void) git_cred_free(git_cred *cred); - -/** - * 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" - * 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, < 0 to indicate an error, > 0 to indicate - * no credential was acquired - */ -typedef int GIT_CALLBACK(git_cred_acquire_cb)( - git_cred **cred, - const char *url, - const char *username_from_url, - unsigned int allowed_types, - void *payload); - /** @} */ GIT_END_DECL + #endif -- cgit v1.2.1