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

名称

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

概要

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

描述

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

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

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

如果动作为 approve，`git-credential` 将把描述发送给任何已配置的凭据助手，这些助手可能会存储凭据以供以后使用。

如果动作为 reject，`git-credential` 将把描述发送给任何已配置的凭据助手，这些助手可能会清除任何与描述匹配的已存储凭据。

如果动作为 capability，`git-credential` 将向标准输出宣布它支持的任何能力。

如果动作为 approve 或 reject，则不应产生任何输出。

GIT 凭据的典型用法

使用 `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` 将获取登录信息（例如主机、协议、路径）的键，或者要获取的实际凭据数据（用户名/密码）。

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

键可以包含除 =、换行符或 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

此布尔值指示，如果为真，则凭据助手不应保存 credential 字段中的值，因为其有用性受时间限制。例如，HTTP Digest credential 值是使用随机数计算的，重复使用它将导致认证失败。这也可用于短时间（例如 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] 套件的一部分

scroll-to-top