Git
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 憑證的典型使用

使用 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