English ▾ 主題 ▾ 最新版本 ▾ 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），並從標準輸入讀取憑證描述（請參閱 輸入/輸出格式）。

如果動作是 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 在下次呼叫時要求輸入新密碼。無論哪種情況，都應將從步驟 (2) 獲得的憑證描述（其中也包含步驟 (1) 中提供的欄位）輸入給 git credential。

輸入/輸出格式

git credential 在其標準輸入/輸出中讀取和/或寫入（取決於所使用的動作）憑證資訊。此資訊可以對應於 git credential 將從中獲取登入資訊的鍵（例如 host、protocol、path），或者對應於要獲取的實際憑證資料（使用者名稱/密碼）。

憑證被拆分為一組具名屬性，每行一個屬性。每個屬性由鍵值對指定，中間以 =（等號）分隔，並以換行符結尾。

鍵可以包含除 =、換行符或 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] 套件的一部分