English ▾ 主题 ▾ 最新版本 ▾ 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 之一），并在 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 在下次调用中要求输入新密码。在任何一种情况下，都应将从步骤 (2) 获得的凭据描述（其中还包含步骤 (1) 中提供的字段）输入到 git credential。

输入/输出格式

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

如果该布尔值为 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] 套件的一部分

scroll-to-top