簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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