Re: [PATCH/RFC] credentials helpers+remote helpers

[Junio C Hamano <gitster@pobox.com>]

Javier.Roucher-Iglesias@ensimag.imag.fr writes:

> From: Javier Roucher <jroucher@gmail.com>
>
>
> Add "git credential" plumbing command
>
> The credential API is in C, and not available to scripting languages.
> Expose the functionalities of the API by wrapping them into a new
> plumbing command "git credentials".
>
> Signed-off-by: Pavel Volek <Pavel.Volek@ensimag.imag.fr>
> Signed-off-by: NGUYEN Kim Thuat <Kim-Thuat.Nguyen@ensimag.imag.fr>
> Signed-off-by: ROUCHER IGLESIAS Javier <roucherj@ensimag.imag.fr>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>

In addition to all good comments already given by Matthieu,...

> diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt
> new file mode 100644
> index 0000000..a6e1d0a
> --- /dev/null
> +++ b/Documentation/git-credential.txt
> @@ -0,0 +1,70 @@
> +git-credential(7)
> +=================
> +
> +NAME
> +----
> +git-credential - Providing and storing user credentials to git

This sounds as if we are storing passwords "in git", which is not
exactly the point of the credential API, no?

> +SYNOPSIS
> +--------
> +------------------
> +git credential [fill|approve|reject]
> +
> +------------------
> +
> +DESCRIPTION
> +-----------
> +
> +Git-credential permits to save username, password, host, path and protocol.
> +When you invoke git-credential, you can ask for a password, using the command
> +'git credential fill'.
> +Providing them by STDIN: 
> +
> +		username=admin\n 
> +		protocol=[http|https]\n
> +		host=localhost\n
> +		path=/dir\n\n

It's a bit strange way to convey that the user feeds record
separated by a blank line, and each column in a record is terminated
with a newline.

How about saying that more explicitly?  E.g. "when taking data from
the standard input, the program treats each line as a separate data
item, and the end of series of data item is signalled by a blank
line" or something?

> +-If git-credential system, have the password already stored
> +git-credential will answer by STDOUT:
> +	
> +		username=admin\n
> +		password=*****\n

Does the reading side get any clue that there is no more output,
like you gave yourself on the input side (i.e. it can and should
read until it sees a blank line)?

Shouldn't it?

> +-If it is not stored, git-credential will ask you to enter 
> +the password:
> +		
> +		> Password for '[http|https]admin@localhost':
> +
> +Then if password is correct, you can store using command
> +'git crendential approve' providing the structure, by STDIN.
> +
> +		username=admin\n 
> +		password=*****\n
> +		protocol=[http|https]\n
> +		host=localhost\n
> +		path=/dir\n\n
> +
> +If the password is refused, you can delete using command
> +'git credential reject' providing the same structure.

It is unclear who decides "correct" vs "refused" here.

Perhaps it would help to describe the purpose of the script that
uses this command first.  My understanding is that there are three
actors: the end user, the script that uses "git credential" and an
external system that wants to authenticate the user.

    _
   / \        +------------------+      +-----------------+
  | U |       |                  |      |                 |
   \ /        | Script that uses |      | External system |
  --+--  <==> | "git credential" | <==> |                 | 
    ^         +------------------+      +-----------------+
   / \                 ^
                       |
                       v
                credential API

And the "Script" is trying to respond to the external system with
credential material on behalf of the user.  For that, if the script
knows the username, it can give the <user,proto,host,path> tuple to
"git credential", and if "git credential" knows the password, it
will be given to the script. If it does not, it may ask the user and
obtain it before giving it back to the script.

Is that what is going on?

Assuming it is, after that happens, the script gives the credential
information to the external system. The external system may or may
not accept that credential, and that is what decides "correct" vs
"refused".

After that, the script tells the "git credential" the result; giving
"reject" to it to purge the credential information that it already
knows the external system will reject, for example.