The API documentation targets two kinds of developers: those using the (C) API, and those writing remote-helpers. The document was not clear about which part was useful to which category, and for example, the C API could be mistakenly thought as an API for writting remote helpers. Based-on-patch-by: Jeff King <peff@xxxxxxxx> Signed-off-by: Matthieu Moy <Matthieu.Moy@xxxxxxx> --- I took Jeff's explanation, but I insist in having a picture ;-). I made the picture more generic compared to my first proposal, and just mention remote-helper in the text (I originally was wondering whether this API could be used from a helper, since the helper has its STDIN and STDOUT bound to the main Git process already, so this explanation would have avoided the confusion for me). Documentation/technical/api-credentials.txt | 50 +++++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 21ca6a2..8804c42 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -6,8 +6,52 @@ password credentials from the user (even though credentials in the wider world can take many forms, in this document the word "credential" always refers to a username and password pair). +This document describes two interfaces: the C API that the credential +subsystem provides to the rest of git, and the protocol that git uses to +communicate with system-specific "credential helpers". If you are +writing git code that wants to look up or prompt for credentials, see +the section "C API" below. If you want to write your own helper, see +the section on "Credential Helpers" below. + +Typical setup +------------- + +------------ ++-----------------------+ +| git code (C) |--- to server requiring ---> +| | authentication +|.......................| +| C credential API |--- prompt ---> User ++-----------------------+ + ^ | + | pipe | + | v ++-----------------------+ +| git credential helper | ++-----------------------+ +------------ + +The git code (typically a remote-helper) will call the C API to obtain +credential data like a login/password couple (credential_fill). The +API will itself call a remote helper (e.g. "git credential-cache" or +"git credential-store") that may retrieve credential data from a +store. If the credential helper cannot find the information, the C API +will prompt the user. Then, the caller of the API takes care of +contacting the server, and do the actual authentication. + +C API +----- + +The credential C API is meant to be called by git code which needs to +acquire or store a credential. It is centered around an object +representing a single credential and provides three basic operations: +fill (acquire credentials by calling helpers and/or prompting the user), +approve (mark a credential as successfully used so that it can be stored +for later use), and reject (mark a credential as unsuccessful so that it +can be erased from any persistent storage). + Data Structures ---------------- +~~~~~~~~~~~~~~~ `struct credential`:: @@ -28,7 +72,7 @@ This struct should always be initialized with `CREDENTIAL_INIT` or Functions ---------- +~~~~~~~~~ `credential_init`:: @@ -72,7 +116,7 @@ Functions Parse a URL into broken-down credential fields. Example -------- +~~~~~~~ The example below shows how the functions of the credential API could be used to login to a fictitious "foo" service on a remote host: -- 1.7.11.rc0.57.g84a04c7 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html