简体中文 ▾ 主题 ▾ 最新版本 ▾ git-credential 最后更新于 2.46.0

名称

git-credential - 检索和存储用户凭据

概要

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

描述

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

git-credential 在命令行中接受一个“action”选项（fill、approve 或 reject 之一），并在标准输入中读取凭据描述（参见 输入/输出格式）。

如果 action 为 fill，git-credential 将尝试通过读取配置文件、联系任何已配置的凭据辅助工具或提示用户来为描述添加“username”和“password”属性。然后，凭据描述的用户名和密码属性将与已提供的属性一起打印到标准输出。

如果 action 为 approve，git-credential 将把描述发送给任何已配置的凭据辅助工具，这些辅助工具可能会存储凭据以备将来使用。

如果 action 为 reject，git-credential 将把描述发送给任何已配置的凭据辅助工具，这些辅助工具可能会删除与描述匹配的任何已存储凭据。

如果 action 为 capability，git-credential 将向标准输出宣布其支持的任何功能。

如果 action 为 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 在下一次调用时会要求输入新密码。无论哪种情况，都应使用从第 (2) 步获得的凭据描述（其中还包含第 (1) 步提供的字段）来处理 git credential。

输入/输出格式

git credential 在其标准输入/输出中读取和/或写入（取决于使用的 action）凭据信息。此信息可以对应于 git credential 将获取登录信息的键（例如，主机、协议、路径），或者是要获取的实际凭据数据（用户名/密码）。

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

键可以包含除 =、换行符或 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”），则凭据将包含一个主机名属性，其值为一个空字符串。

URL 中缺失的组件（例如，上面的示例中没有用户名）将保持未设置状态。

authtype

这表示应使用所讨论的认证方案。HTTP 和 HTTPS 的常见值包括 basic、bearer 和 digest，尽管后者不安全，不应使用。如果使用 credential，则此属性可设置为适用于所讨论协议（通常是 HTTP）的任意字符串。

除非在输入时提供了相应的功能（见下文），否则不应发送此值。

credential

预编码的凭据，适用于所讨论协议（通常是 HTTP）。如果发送了此键，则 authtype 是强制性的，并且不使用 username 和 password。对于 HTTP，Git 将 authtype 值和此值用一个空格连接起来，以确定 Authorization 标头。

除非在输入时提供了相应的功能（见下文），否则不应发送此值。

ephemeral

此布尔值表示（如果为 true）credential 字段中的值不应被凭据辅助工具保存，因为其有效性是暂时的。例如，HTTP Digest credential 值是使用 nonce 计算的，重用它不会导致成功认证。这也可以用于短暂（例如 24 小时）凭据的情况。默认值为 false。

凭据辅助工具仍会被调用 store 或 erase，以便它可以确定操作是否成功。

除非在输入时提供了相应的功能（见下文），否则不应发送此值。

state[]

此值提供一个不透明状态，如果再次调用该辅助工具，该状态将传递回该辅助工具。每个不同的凭据辅助工具都可以指定此项一次。该值应包含一个对该凭据辅助工具唯一的前缀，并且应忽略不匹配其前缀的值。

除非在输入时提供了相应的功能（见下文），否则不应发送此值。

continue

这是一个布尔值，如果启用，表示此认证是多阶段认证步骤的非最终部分。这在 NTLM 和 Kerberos 等协议中很常见，需要两轮客户端认证，设置此标志允许凭据辅助工具实现多阶段认证步骤。仅当需要进一步阶段时（即，当期望另一轮认证时）才应发送此标志。

除非在输入时提供了相应的功能（见下文），否则不应发送此值。此属性是单向的，从凭据辅助工具传递信息给 Git（或其他调用 git credential 的程序）。

wwwauth[]

当 Git 收到包含一个或多个WWW-Authenticate 认证标头的 HTTP 响应时，Git 会将这些标头传递给凭据辅助工具。

每个WWW-Authenticate 标头值都作为多值属性wwwauth[]传递，其中属性的顺序与它们在 HTTP 响应中出现的顺序相同。此属性是单向的，从 Git 传递其他信息给凭据辅助工具。

capability[]

这表明 Git 或辅助工具（视情况而定）支持所讨论的功能。这可以用于在协议中提供更好、更具体的数据。一个 capability[] 指令必须出现在任何依赖于它的值之前，并且这些指令应该是协议中宣布的第一个项目。

目前支持两种功能。第一种是 authtype，它表示理解 authtype、credential 和 ephemeral 值。第二种是 state，它表示理解 state[] 和 continue 值。

尽管支持某项功能，但并非强制使用这些附加功能，但如果没有该功能，则不应提供它们。

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

功能输入/输出格式

对于 git credential capability，格式略有不同。首先，会发出 version 0 声明，以指示协议的当前版本，然后每个功能会以类似 capability authtype 的行进行宣布。凭据辅助工具也可以实现此格式，同样使用 capability 参数。将来可能会添加其他行；调用者应忽略他们不理解的行。

由于这是凭据辅助工具协议的新部分，因此旧版本的 Git 以及一些凭据辅助工具可能不支持它。如果收到非零的退出状态，或者第一行不以单词 version 和空格开头，调用者应假定不支持任何功能。

此格式的目的是使其与凭据输出区分开来，且无歧义。可以使用非常简单的凭据辅助工具（例如，内联 shell 脚本），它们总是产生相同的输出。使用不同的格式允许用户继续使用此语法，而无需担心正确实现功能声明或意外混淆查询功能的调用者。

GIT

Git[1] 套件的一部分