git-credential

检索和存储用户凭据

概要

'git credential' (fill|approve|reject|capability)

描述

Git 有一个用于从系统特定辅助程序存储和检索凭据的内部接口，以及提示用户输入用户名和密码的功能。git-credential 命令将此接口暴露给可能希望以与 Git 相同的方式检索、存储或提示凭据的脚本。此可脚本化接口的设计模拟了内部 C API；有关概念的更多背景，请参阅 credential.h。

git-credential 在命令行上接受一个"action"选项（fill、approve 或 reject 之一），并在 stdin 上读取凭据描述（请参阅"输入/输出格式"）。

如果操作是 fill，git-credential 将尝试通过读取配置文件、联系任何配置的凭据辅助程序或提示用户来向描述添加"username"和"password"属性。然后凭据描述的用户名和密码属性与已提供的属性一起打印到 stdout。

如果操作是 approve，git-credential 将描述发送到任何配置的凭据辅助程序，它们可能会存储凭据以供以后使用。

如果操作是 reject，git-credential 将描述发送到任何配置的凭据辅助程序，它们可能会擦除与描述匹配的任何存储凭据。

如果操作是 capability，git-credential 将向标准输出宣布它支持的任何功能。

如果操作是 approve 或 reject，不应发出输出。

git credential 的典型用法

使用 git-credential 的应用程序通常会按照以下步骤使用 git credential：

1. 根据上下文生成凭据描述。

   例如，如果我们想要 https://example.com/foo.git 的密码，我们可能会生成以下凭据描述（不要忘记末尾的空行；它告诉 git credential 应用程序已完成提供其拥有的所有信息）：

   protocol=https
   host=example.com
   path=foo.git

2. 要求 git-credential 为此描述提供用户名和密码。这是通过运行 git credential fill 来完成的，将步骤 (1) 中的描述提供给其标准输入。完整的凭据描述（包括凭据本身，即登录名和密码）将在标准输出上生成，如：

   protocol=https
   host=example.com
   username=bob
   password=secr3t

   在大多数情况下，这意味着输入中给出的属性将在输出中重复，但 Git 也可能修改凭据描述，例如当协议是 HTTP(s) 且 credential.useHttpPath 为 false 时删除 path 属性。

   如果 git credential 知道密码，此步骤可能不涉及用户实际输入此密码（用户可能输入密码来解锁密钥链，或者如果密钥链已解锁则不进行用户交互）然后返回 password=secr3t。

3. 使用凭据（例如使用步骤 (2) 中的用户名和密码访问 URL），并查看是否被接受。

4. 报告密码的成功或失败。如果凭据允许操作成功完成，则可以使用"approve"操作标记它，以告诉 git credential 在下次调用时重用它。如果凭据在操作期间被拒绝，请使用"reject"操作，以便 git credential 在下次调用时请求新密码。在任一情况下，git credential 都应提供从步骤 (2) 获得的凭据描述（其中也包含步骤 (1) 中提供的字段）。

输入/输出格式

git credential 在其标准输入/输出上读取和/或写入凭据信息（取决于使用的操作）。此信息可以对应于 git credential 将获取登录信息的键（例如 host、protocol、path），或要获取的实际凭据数据（username/password）。

凭据被拆分为一组命名属性，每行一个属性。每个属性由键值对指定，用 =（等号）分隔，后跟换行符。

键可以包含除 =、换行符或 NUL 之外的任何字节。值可以包含除换行符或 NUL 之外的任何字节。一行（包括尾随换行符）不得超过 65535 字节，以允许实现高效解析。

以 C 风格数组括号 [] 结尾的键的属性可以有多个值。多值属性的每个实例形成一个有序值列表——重复属性的顺序定义值的顺序。空多值属性（key[]=\n）会清除任何先前的条目并重置列表。

在所有情况下，所有字节都按原样处理（即没有引用，并且无法传输包含换行符或 NUL 的值）。属性列表由空行或文件结尾终止。

Git 理解以下属性：

protocol

凭据将使用的协议（例如 https）。

host

网络凭据的远程主机名。如果指定了端口号，则包括端口号（例如 "example.com:8088"）。

path

凭据将使用的路径。例如，对于访问远程 https 存储库，这将是服务器上存储库的路径。

username

凭据的用户名（如果我们已经有了）（例如来自 URL、配置、用户或先前运行的辅助程序）。

password

凭据的密码（如果我们要求存储它）。

password_expiry_utc

生成的密码（如 OAuth 访问令牌）可能有过期日期。从辅助程序读取凭据时，git credential fill 会忽略过期密码。表示为 Unix 时间 UTC，即自 1970 年以来的秒数。

oauth_refresh_token

OAuth 刷新令牌可能伴随作为 OAuth 访问令牌的密码。辅助程序必须将此属性视为机密，如密码属性。Git 本身对此属性没有特殊行为。

url

当 git credential 读取此特殊属性时，该值被解析为 URL 并被视为已读取其组成部分（例如 url=https://example.com 的行为就像提供了 protocol=https 和 host=example.com）。这可以帮助调用者避免自己解析 URL。 请注意，指定协议是强制性的，如果 URL 未指定主机名（例如 "cert:///path/to/file"），凭据将包含值为空字符串的主机名属性。

authtype

这表示应使用相关身份验证方案。HTTP 和 HTTPS 的常见值包括 basic、bearer 和 digest，但后者不安全，不应使用。 除非在输入上提供适当的功能（见下文），否则不应发送此值。

credential

预编码的凭据，适用于相关协议（通常是 HTTP）。如果发送此键，则 authtype 是必需的，并且不使用 username 和 password。对于 HTTP，Git 将 authtype 值和此值用单个空格连接以确定 Authorization 头。 除非在输入上提供适当的功能（见下文），否则不应发送此值。

ephemeral

此布尔值指示（如果为 true）credential 字段中的值不应由凭据辅助程序保存，因为其有效性在时间上是有限的。 除非在输入上提供适当的功能（见下文），否则不应发送此值。

state[]

此值提供一个不透明状态，如果再次调用此辅助程序，将传递回该状态。每个不同的凭据辅助程序可以指定一次此值。

continue

这是一个布尔值，如果启用，表示此身份验证是多阶段身份验证步骤的非最终部分。仅在需要进一步阶段时才应发送此标志。

wwwauth[]

当 Git 收到包含一个或多个 'WWW-Authenticate' 身份验证头的 HTTP 响应时，Git 会将这些传递给凭据辅助程序。

capability[]

这表示 Git 或辅助程序（视情况而定）支持相关功能。 目前支持两个功能。第一个是 authtype，表示理解 authtype、credential 和 ephemeral 值。第二个是 state，表示理解 state[] 和 continue 值。

未识别的属性和功能被静默丢弃。

功能输入/输出格式

对于 git credential capability，格式略有不同。首先，宣布 version 0 以指示协议的当前版本，然后用类似 capability authtype 的行宣布每个功能。凭据辅助程序也可以实现此格式。将来可能会添加额外的行；调用者应忽略他们不理解的行。

Git

git(1) 套件的一部分