Re: credential-helpers + remote-helper, starting point?
From: Matthieu Moy <hidden>
Date: 2016-06-15 22:53:54
Jeff King [off-list ref] writes:
https://github.com/git/git/blob/master/Documentation/technical/api-credentials.txt
I just re-read that document (I had a quick glance only before), and started to understand. I think the document really lacks the "big picture". I took time to understand whether the API was to call credential helpers, or to write a new one. Actually, there are two "API": the C one, and the specification of what may flow on the pipe between the two processes. Perhaps something like this should be added: Subject: [PATCH] credential-helper documentation: show the big picture first --- Documentation/technical/api-credentials.txt | 47 +++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 3 deletions(-)
diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index 21ca6a2..5a872c0 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt@@ -6,8 +6,40 @@ 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). +When a function in Git or one of its remote-helpers needs to obtain +credentials (either by asking the user or by fetching from a store), +it can call the functions in the C API. These functions will fork a +new process, and communicate with it by passing command-line arguments +and then communicating through a pipe (see 'Credential Helpers' +below). The credential helper process will be in charge of actually +prompting the user and/or storing and fetching the credentials. + +For example, the execution of a command connecting to an HTTP server +and using the credential helper "cache" will have the following +structure: + +------------ ++-----+ -----> +-----------------+ +| git | pipe | git remote-http | --- to HTTP server ---> ++-----+ <----- +-----------------+ + ^ | + | pipe | + | v + +----------------------+ + | git credential-cache | + +----------------------+ +------------ + +git remote-http will take care of contacting the HTTP server, do the +actual authentication and see if it's accepted by the server. The +credential helper will deal with the credential store (which can be +done by contacting a keyring daemon) and the prompting if needed. + +C API +----- + Data Structures ---------------- +~~~~~~~~~~~~~~~ `struct credential`::
@@ -28,7 +60,7 @@ This struct should always be initialized with `CREDENTIAL_INIT` or Functions ---------- +~~~~~~~~~ `credential_init`::
@@ -72,7 +104,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:
@@ -130,6 +162,9 @@ int foo_login(struct foo_connection *f) Credential Helpers ------------------ +Choosing the credential helper command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Credential helpers are programs executed by git to fetch or save credentials from and to long-term storage (where "long-term" is simply longer than a single git process; e.g., credentials may be stored
@@ -176,6 +211,9 @@ users by naming their program "git-credential-$NAME", and putting it in the $PATH or $GIT_EXEC_PATH during installation, which will allow a user to enable it with `git config credential.helper $NAME`. +Credential helper command-line arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + When a helper is executed, it will have one "operation" argument appended to its command line, which is one of:
@@ -191,6 +229,9 @@ appended to its command line, which is one of: Remove a matching credential, if any, from the helper's storage. +Credential helper protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~ + The details of the credential will be provided on the helper's stdin stream. The credential is split into a set of named attributes. Attributes are provided to the helper, one per line. Each attribute is
--
1.7.10.363.g7fcd3d.dirty
Also, shouldn't the documentation about choosing the command name be
moved to git-config.txt, to document credential.helper? It really seems
to be a user documentation, not a technical one meant for Git
developers.
> But that is the C API, and I assume you are building on the existing
> mediawiki helper that is written in perl.
Right.
> So I think what you really want is a "git credential" command that
> will let scripts hook into the credential API. Something like:
>
> $ git credential get https://example.com
> username=bob
> password=secret
> [...]
This is almost already done by test-credential.c indeed. But that's
probably the simplest way to expose the C API to a perl program.
> Do you guys want to try writing "git credential" as above? It might be a
> fun side project, but I know you are also on a limited timeframe for
> your project. I can work on it if you don't have time.
I leave it up to the students.
--
Matthieu Moy
http://www-verimag.imag.fr/~moy/