Merge pull request #4879 from libgit2/ethomson/defer_cert_cred_cb

Allow certificate and credential callbacks to decline to act

3 files changed, 12 insertions, 3 deletions

diff --git a/include/git2/errors.h b/include/git2/errors.h
index b0ce45fe5..2c0ac1c71 100644
--- a/include/git2/errors.h
+++ b/include/git2/errors.h
@@ -52,7 +52,7 @@ typedef enum {
 	GIT_EDIRECTORY      = -23,      /**< The operation is not valid for a directory */
 	GIT_EMERGECONFLICT  = -24,	/**< A merge conflict exists and cannot continue */
 
-	GIT_PASSTHROUGH     = -30,	/**< Internal only */
+	GIT_PASSTHROUGH     = -30,	/**< A user-configured callback refused to act */
 	GIT_ITEROVER        = -31,	/**< Signals end of iteration with iterator */
 	GIT_RETRY           = -32,	/**< Internal only */
 	GIT_EMISMATCH       = -33,	/**< Hashsum mismatch in object */
diff --git a/include/git2/sys/transport.h b/include/git2/sys/transport.h
index a395de5ed..aac6f9f36 100644
--- a/include/git2/sys/transport.h
+++ b/include/git2/sys/transport.h
@@ -226,7 +226,10 @@ GIT_EXTERN(int) git_transport_smart(
  * @param cert the certificate to pass to the caller
  * @param valid whether we believe the certificate is valid
  * @param hostname the hostname we connected to
- * @return the return value of the callback
+ * @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH
+ *         to indicate that there is no callback registered (or the callback
+ *         refused to validate the certificate and callers should behave as
+ *         if no callback was set), or < 0 for an error
  */
 GIT_EXTERN(int) git_transport_smart_certificate_check(git_transport *transport, git_cert *cert, int valid, const char *hostname);
 
@@ -237,7 +240,10 @@ GIT_EXTERN(int) git_transport_smart_certificate_check(git_transport *transport,
  * @param transport a smart transport
  * @param user the user we saw on the url (if any)
  * @param methods available methods for authentication
- * @return the return value of the callback
+ * @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH
+ *         to indicate that there is no callback registered (or the callback
+ *         refused to provide credentials and callers should behave as if no
+ *         callback was set), or < 0 for an error
  */
 GIT_EXTERN(int) git_transport_smart_credentials(git_cred **out, git_transport *transport, const char *user, int methods);
 
diff --git a/include/git2/types.h b/include/git2/types.h
index e77e6288d..3c127e3eb 100644
--- a/include/git2/types.h
+++ b/include/git2/types.h
@@ -333,6 +333,9 @@ typedef struct {
  * this certificate is valid
  * @param host Hostname of the host libgit2 connected to
  * @param payload Payload provided by the caller
+ * @return 0 to proceed with the connection, < 0 to fail the connection
+ *         or > 0 to indicate that the callback refused to act and that
+ *         the existing validity determination should be honored
  */
 typedef int (*git_transport_certificate_check_cb)(git_cert *cert, int valid, const char *host, void *payload);