api-credentials.txt: show the big picture first
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@peff.net> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Matthieu Moy committed
Jun 4, 2012 at 22:17 UTC
223988808971eb5429efd914e9e88855ea0b0e01
1 file changed
+47
-3
Documentation/technical/api-credentials.txt
+47
-3
@@ -6,8 +6,52 @@ password credentials from the user (even though credentials in the wider
6
world can take many forms, in this document the word "credential" always
7
refers to a username and password pair).
8
9
+This document describes two interfaces: the C API that the credential
10
+subsystem provides to the rest of git, and the protocol that git uses to
11
+communicate with system-specific "credential helpers". If you are
12
+writing git code that wants to look up or prompt for credentials, see
13
+the section "C API" below. If you want to write your own helper, see
14
+the section on "Credential Helpers" below.
15
+
16
+Typical setup
17
+-------------
18
+
19
+------------
20
++-----------------------+
21
+| git code (C) |--- to server requiring --->
22
+| | authentication
23
+|.......................|
24
+| C credential API |--- prompt ---> User
25
++-----------------------+
26
+ ^ |
27
+ | pipe |
28
+ | v
29
++-----------------------+
30
+| git credential helper |
31
++-----------------------+
32
+------------
33
+
34
+The git code (typically a remote-helper) will call the C API to obtain
35
+credential data like a login/password pair (credential_fill). The
36
+API will itself call a remote helper (e.g. "git credential-cache" or
37
+"git credential-store") that may retrieve credential data from a
38
+store. If the credential helper cannot find the information, the C API
39
+will prompt the user. Then, the caller of the API takes care of
40
+contacting the server, and does the actual authentication.
41
+
42
+C API
43
+-----
44
+
45
+The credential C API is meant to be called by git code which needs to
46
+acquire or store a credential. It is centered around an object
47
+representing a single credential and provides three basic operations:
48
+fill (acquire credentials by calling helpers and/or prompting the user),
49
+approve (mark a credential as successfully used so that it can be stored
50
+for later use), and reject (mark a credential as unsuccessful so that it
51
+can be erased from any persistent storage).
52
+
53
Data Structures
10
----------------
54
+~~~~~~~~~~~~~~~
55
56
`struct credential`::
57
@@ -28,7 +72,7 @@ This struct should always be initialized with `CREDENTIAL_INIT` or
72
73
74
Functions
31
----------
75
+~~~~~~~~~
76
77
`credential_init`::
78
@@ -72,7 +116,7 @@ Functions
116
Parse a URL into broken-down credential fields.
117
118
Example
75
--------
119
+~~~~~~~
120
121
The example below shows how the functions of the credential API could be
122
used to login to a fictitious "foo" service on a remote host: