@@ -750,7 +750,7 @@ <h2 id="_synopsis">SYNOPSIS</h2>
750750< div class ="sectionbody ">
751751< div class ="listingblock ">
752752< div class ="content ">
753- < pre > < code > 'git credential' (fill|approve|reject)</ code > </ pre >
753+ < pre > < code > 'git credential' (fill|approve|reject|capability )</ code > </ pre >
754754</ div > </ div >
755755</ div >
756756</ div >
@@ -779,6 +779,8 @@ <h2 id="_description">DESCRIPTION</h2>
779779< div class ="paragraph "> < p > If the action is < code > reject</ code > , git-credential will send the description to
780780any configured credential helpers, which may erase any stored
781781credentials matching the description.</ p > </ div >
782+ < div class ="paragraph "> < p > If the action is < code > capability</ code > , git-credential will announce any capabilities
783+ it supports to standard output.</ p > </ div >
782784< div class ="paragraph "> < p > If the action is < code > approve</ code > or < code > reject</ code > , no output should be emitted.</ p > </ div >
783785</ div >
784786</ div >
@@ -863,7 +865,9 @@ <h2 id="IOFMT">INPUT/OUTPUT FORMAT</h2>
863865attribute per line. Each attribute is specified by a key-value pair,
864866separated by an < code > =</ code > (equals) sign, followed by a newline.</ p > </ div >
865867< div class ="paragraph "> < p > The key may contain any bytes except < code > =</ code > , newline, or NUL. The value may
866- contain any bytes except newline or NUL.</ p > </ div >
868+ contain any bytes except newline or NUL. A line, including the trailing
869+ newline, may not exceed 65535 bytes in order to allow implementations to
870+ parse efficiently.</ p > </ div >
867871< div class ="paragraph "> < p > Attributes with keys that end with C-style array brackets < code > []</ code > can have
868872multiple values. Each instance of a multi-valued attribute forms an
869873ordered list of values - the order of the repeated attributes defines
@@ -958,6 +962,80 @@ <h2 id="IOFMT">INPUT/OUTPUT FORMAT</h2>
958962username in the example above) will be left unset.</ p > </ div >
959963</ dd >
960964< dt class ="hdlist1 ">
965+ < code > authtype</ code >
966+ </ dt >
967+ < dd >
968+ < p >
969+ This indicates that the authentication scheme in question should be used.
970+ Common values for HTTP and HTTPS include < code > basic</ code > , < code > bearer</ code > , and < code > digest</ code > ,
971+ although the latter is insecure and should not be used. If < code > credential</ code >
972+ is used, this may be set to an arbitrary string suitable for the protocol in
973+ question (usually HTTP).
974+ </ p >
975+ < div class ="paragraph "> < p > This value should not be sent unless the appropriate capability (see below) is
976+ provided on input.</ p > </ div >
977+ </ dd >
978+ < dt class ="hdlist1 ">
979+ < code > credential</ code >
980+ </ dt >
981+ < dd >
982+ < p >
983+ The pre-encoded credential, suitable for the protocol in question (usually
984+ HTTP). If this key is sent, < code > authtype</ code > is mandatory, and < code > username</ code > and
985+ < code > password</ code > are not used. For HTTP, Git concatenates the < code > authtype</ code > value and
986+ this value with a single space to determine the < code > Authorization</ code > header.
987+ </ p >
988+ < div class ="paragraph "> < p > This value should not be sent unless the appropriate capability (see below) is
989+ provided on input.</ p > </ div >
990+ </ dd >
991+ < dt class ="hdlist1 ">
992+ < code > ephemeral</ code >
993+ </ dt >
994+ < dd >
995+ < p >
996+ This boolean value indicates, if true, that the value in the < code > credential</ code >
997+ field should not be saved by the credential helper because its usefulness is
998+ limited in time. For example, an HTTP Digest < code > credential</ code > value is computed
999+ using a nonce and reusing it will not result in successful authentication.
1000+ This may also be used for situations with short duration (e.g., 24-hour)
1001+ credentials. The default value is false.
1002+ </ p >
1003+ < div class ="paragraph "> < p > The credential helper will still be invoked with < code > store</ code > or < code > erase</ code > so that it
1004+ can determine whether the operation was successful.</ p > </ div >
1005+ < div class ="paragraph "> < p > This value should not be sent unless the appropriate capability (see below) is
1006+ provided on input.</ p > </ div >
1007+ </ dd >
1008+ < dt class ="hdlist1 ">
1009+ < code > state[]</ code >
1010+ </ dt >
1011+ < dd >
1012+ < p >
1013+ This value provides an opaque state that will be passed back to this helper
1014+ if it is called again. Each different credential helper may specify this
1015+ once. The value should include a prefix unique to the credential helper and
1016+ should ignore values that don’t match its prefix.
1017+ </ p >
1018+ < div class ="paragraph "> < p > This value should not be sent unless the appropriate capability (see below) is
1019+ provided on input.</ p > </ div >
1020+ </ dd >
1021+ < dt class ="hdlist1 ">
1022+ < code > continue</ code >
1023+ </ dt >
1024+ < dd >
1025+ < p >
1026+ This is a boolean value, which, if enabled, indicates that this
1027+ authentication is a non-final part of a multistage authentication step. This
1028+ is common in protocols such as NTLM and Kerberos, where two rounds of client
1029+ authentication are required, and setting this flag allows the credential
1030+ helper to implement the multistage authentication step. This flag should
1031+ only be sent if a further stage is required; that is, if another round of
1032+ authentication is expected.
1033+ </ p >
1034+ < div class ="paragraph "> < p > This value should not be sent unless the appropriate capability (see below) is
1035+ provided on input. This attribute is < em > one-way</ em > from a credential helper to
1036+ pass information to Git (or other programs invoking < code > git credential</ code > ).</ p > </ div >
1037+ </ dd >
1038+ < dt class ="hdlist1 ">
9611039< code > wwwauth[]</ code >
9621040</ dt >
9631041< dd >
@@ -971,8 +1049,47 @@ <h2 id="IOFMT">INPUT/OUTPUT FORMAT</h2>
9711049they appear in the HTTP response. This attribute is < em > one-way</ em > from Git
9721050to pass additional information to credential helpers.</ p > </ div >
9731051</ dd >
1052+ < dt class ="hdlist1 ">
1053+ < code > capability[]</ code >
1054+ </ dt >
1055+ < dd >
1056+ < p >
1057+ This signals that Git, or the helper, as appropriate, supports the capability
1058+ in question. This can be used to provide better, more specific data as part
1059+ of the protocol. A < code > capability[]</ code > directive must precede any value depending
1060+ on it and these directives < em > should</ em > be the first item announced in the
1061+ protocol.
1062+ </ p >
1063+ < div class ="paragraph "> < p > There are two currently supported capabilities. The first is < code > authtype</ code > , which
1064+ indicates that the < code > authtype</ code > , < code > credential</ code > , and < code > ephemeral</ code > values are
1065+ understood. The second is < code > state</ code > , which indicates that the < code > state[]</ code > and
1066+ < code > continue</ code > values are understood.</ p > </ div >
1067+ < div class ="paragraph "> < p > It is not obligatory to use the additional features just because the capability
1068+ is supported, but they should not be provided without the capability.</ p > </ div >
1069+ </ dd >
9741070</ dl > </ div >
975- < div class ="paragraph "> < p > Unrecognised attributes are silently discarded.</ p > </ div >
1071+ < div class ="paragraph "> < p > Unrecognised attributes and capabilities are silently discarded.</ p > </ div >
1072+ </ div >
1073+ </ div >
1074+ < div class ="sect1 ">
1075+ < h2 id ="CAPA-IOFMT "> CAPABILITY INPUT/OUTPUT FORMAT</ h2 >
1076+ < div class ="sectionbody ">
1077+ < div class ="paragraph "> < p > For < code > git credential capability</ code > , the format is slightly different. First, a
1078+ < code > version 0</ code > announcement is made to indicate the current version of the
1079+ protocol, and then each capability is announced with a line like < code > capability
1080+ authtype</ code > . Credential helpers may also implement this format, again with the
1081+ < code > capability</ code > argument. Additional lines may be added in the future; callers
1082+ should ignore lines which they don’t understand.</ p > </ div >
1083+ < div class ="paragraph "> < p > Because this is a new part of the credential helper protocol, older versions of
1084+ Git, as well as some credential helpers, may not support it. If a non-zero
1085+ exit status is received, or if the first line doesn’t start with the word
1086+ < code > version</ code > and a space, callers should assume that no capabilities are supported.</ p > </ div >
1087+ < div class ="paragraph "> < p > The intention of this format is to differentiate it from the credential output
1088+ in an unambiguous way. It is possible to use very simple credential helpers
1089+ (e.g., inline shell scripts) which always produce identical output. Using a
1090+ distinct format allows users to continue to use this syntax without having to
1091+ worry about correctly implementing capability advertisements or accidentally
1092+ confusing callers querying for capabilities.</ p > </ div >
9761093</ div >
9771094</ div >
9781095< div class ="sect1 ">
@@ -986,7 +1103,7 @@ <h2 id="_git">GIT</h2>
9861103< div id ="footer ">
9871104< div id ="footer-text ">
9881105Last updated
989- 2023-10-23 14:43:46 PDT
1106+ 2024-05-13 12:26:56 PDT
9901107</ div >
9911108</ div >
9921109</ body >
0 commit comments