Re: credential-helpers + remote-helper, starting point?

From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: May 24, 2012, 20:23 UTC
Message-ID: <vpq8vghxr9w.fsf@bauges.imag.fr>
In-Reply-To: <20120524200122.GA18936@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 9 quoted lines

>> +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).
>
> We might or might not fork a new process. It depends on which helpers
> are defined.

OK, so s/will fork/may fork/ may be more appropriate.

Show 23 quoted lines

>> +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.
>
> I feel like adding remote-helpers into the mix just makes the situation
> more complex (and necessitates the diagram).

The helper is not strictly needed, but that seems to be a common situation, so I thought describing the common case made sense.

I think it's important to show the difference between the actual authentication process (e.g. HTTP) and the credential helper. I took time to understand the example later:

	credential_fill(&c);
        /* [...] */
	status = send_foo_login(f, c.username, c.password);
	switch (status) {

then I understood that send_foo_login was the one doing the actual authentication, and that further calls to the credential API was needed to say how it went. Making explicit the fact that the Git code talks both the helper and the server on which we are authenticating would have helped me to understand at least.

I think mentionning the fact that a credential helper may connect to a keyring daemon was important also. I first read some discussions about credential helpers thinking that we would have to re-implement the storing mechanism, and really understood what it was all about when I saw patches for KDE support for example.

Other than that, I do like your wording. If it was just me, I'd take your introduction, but keep my example + diagram.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/