SYNOPSIS

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

DESCRIPTION

Gitには、システム固有のヘルパーから資格情報(credentials)を保存および取得したり、ユーザーにユーザー名とパスワードの入力を求めたりするための内部インターフェイスがあります。 git-credentialコマンドは、Gitと同じ方法で資格情報を取得、保存、または要求する可能性のあるスクリプトにこのインターフェイスを公開します。 この、 スクリプトで処理可能なインターフェイスの設計は、 内部 C API をモデルにしています。 概念の背景については、 credential.h を参照してください。

git-credentialは、コマンドラインで「action」オプション(fill または approve または reject のいずれか)を取り、stdinで資格情報の説明(description)を読み取ります(INPUT/OUTPUT FORMAT を参照)

アクションが fill の場合、git-credentialは、構成ファイルを読み取るか、構成された資格情報ヘルパーに連絡するか、ユーザーにプロンプトを表示することにより、説明(description)に「username」および「password」属性を追加しようとします。次に、資格情報の説明(description)のユーザー名とパスワードの属性が、すでに提供されている属性とともにstdoutに出力されます。

アクションが approve(承認)の場合、git-credentialは、構成された資格情報ヘルパーに説明(description)を送信します。ヘルパーは、後で使用するために資格情報を保存する場合があります。

アクションが reject の場合、 git-credential は設定された資格情報ヘルパーに説明(description)を送信します。 これにより、 説明(description)に一致する保存済みの資格情報が消去される場合があります。

アクションが capability の場合、 git-credential はサポートするすべての機能を標準出力に通知します。

アクションが approve(承認)または reject(拒否)の場合、出力は生成されません。

TYPICAL USE OF GIT CREDENTIAL

git-credentialを使用するアプリケーションは、通常、以下の手順に従って git credential を使用します:

  1. コンテキストに基づいて資格情報の説明(description)を生成します。

    たとえば、 https://example.com/foo.git のパスワードが必要な場合は、以下の資格情報の説明(description)を生成できます(最後の空白行を忘れないでください。これは、アプリケーションがすべての情報の提供を終了したことを git credential に通知します):

    protocol=https
host=example.com
path=foo.git

  2. この説明(description)のユーザー名とパスワードを提供するようにgit-credentialに依頼してください。 これは、 git credential fill を実行し、ステップ(1)の説明(description)を標準入力に送ることで実行されます。完全な資格情報の説明(description)(資格情報自体、つまりログインとパスワードを含む)は、以下のように標準出力へ生成されます。 

    protocol=https
host=example.com
username=bob
password=secr3t

    ほとんどの場合、これは入力で指定された属性が出力で繰り返されることを意味しますが、Gitは資格情報の説明(description)を変更する場合もあります。たとえば、プロトコルがHTTP(s)であり、 credential.useHttpPath がfalseの場合、 path 属性を削除します。

    git credential が既にパスワードを知っていた場合、この手順では、ユーザーが password=secr3t を返す前に実際にこのパスワードを入力していなかった可能性があります(ユーザーが代わりにキーチェーンのロックを解除するためにパスワードを入力したか、キーチェーンがすでにロック解除している場合はユーザーの操作が行われなかった可能性があります)。

  3. 資格情報を使用し(たとえば、手順(2)のユーザー名とパスワードを使用してURLにアクセスします)、それが受け入れられるかどうかを確認します。

  4. パスワードの成功または失敗について報告します。資格情報によって操作が正常に完了することが許可された場合は、「approve」アクションでマークを付けて、 git credential に、 次の呼び出しで再利用するように指示できます。操作中に資格情報が拒否された場合は、「reject」アクションを使用して、 git credential が次の呼び出しで新しいパスワードを要求するようにします。 いずれの場合も、 git credential には、ステップ(2)で取得した資格情報の説明(description)(これにはステップ(1)で指定したフィールドも含まれます)を指定する必要があります。

INPUT/OUTPUT FORMAT

git credential は、標準入力/標準出力で(使用するアクションに応じて)資格情報を読み取り および/また は書き込みます。この情報は、 git credential がログイン情報(ホスト、プロトコル、パスなど)を取得するキー、または取得する実際の資格データ(ユーザー名/パスワード)のいずれかに対応できます。

資格情報は、1行に1つの属性を持つ、名前付き属性のセットに分割されます。 各属性は、キーと値のペアで指定され、 = (等号)記号と、改行で続けます。

キーには、 = または改行または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 アクセス・トークンであるパスワードに付随することがあります。 ヘルパーは、 この属性を password 属性と同様に機密(confidential)として扱う必要があります。 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 値とこの値を 1 つの空白で連結して、 Authorization ヘッダーを決定します。

適切な機能(下記参照)が入力に提供されていない限り、 この値は送信されるべきではありません。

ephemeral

このブール値が true の場合、 資格情報ヘルパーの有用性は時間的に制限されているため、 credential フィールドの値を資格情報ヘルパーによって保存すべきではないことを示します。 たとえば、HTTP Digest の credential 値は nonce を使用して計算され、 そして、 それを再利用しても認証は成功しません。 これは、 資格情報が短期間(24 時間など)の場合にも使用できます。 デフォルト値は false です。

資格情報ヘルパーは引き続き store または erase を使用して呼び出され、操作が成功したかどうかを判断できます。

適切な機能(下記参照)が入力に提供されていない限り、 この値は送信されるべきではありません。

state[]

この値は、 再度呼び出された場合にこのヘルパーに返される不明瞭な状態(an opaque state)を提供します。 それぞれの異なる資格情報ヘルパーでこれを 1 回指定できます。 値には資格情報ヘルパーに固有のプレフィックスを含める必要があり、かつ、そのプレフィックスと一致しない値は無視する必要があります。

適切な機能(下記参照)が入力に提供されていない限り、 この値は送信されるべきではありません。

continue

これはブール値で、 有効にすると、 この認証が多段階認証ステップの最終部分ではないことを示します。 これは、 2 ラウンドのクライアント認証が必要な NTLM や Kerberos などのプロトコルで一般的であり、 このフラグを設定すると、 資格情報ヘルパーが多段階認証ステップを実装できるようになります。 このフラグは、 さらなる段階が必要な場合にのみ送信する必要があります。 つまり、 別の認証ラウンドが予期される場合です。

適切な機能(下記参照)が入力に提供されていない限り、 この値は送信されるべきではありません。 この属性は、 認証情報ヘルパーから Git (または git credential を呼び出す他のプログラム)に情報を渡すための「一方通行」の属性です。

wwwauth[]

1 つ以上の WWW-Authenticate 認証ヘッダーを含む HTTP レスポンスが Git によって受信されると、 これらは Git によって資格情報ヘルパーに渡されます。

各 WWW-Authenticate ヘッダー値は、 複数値属性 wwwauth[] として渡されます。 属性の順序は、HTTP レスポンスに表示される順序と同じです。 この属性は、 Gitから資格情報ヘルパーに追加情報を渡すための「一方通行」の属性です。

capability[]

これは、 Git またはヘルパーが必要に応じて当該の機能をサポートしていることを示します。 これを使用すると、 プロトコルの一部として、 より適切でより具体的なデータを提供できます。 capability[] ディレクティブは、 それに応じた値の前に置く必要があり、 これらのディレクティブはプロトコルでアナウンスされる最初の項目であるべきです。

現在サポートされている機能は 2 つあります。 1 つ目は authtype で、 これは authtype や credential や ephemeral の値が理解されることを示します。 2 番目は state で state[] や ` continue` の値が理解されることを示します。

機能(capability)がサポートされているからといって、 その追加機能(additional features)を使用することは必須ではありませんが、 機能なしで追加機能を提供すべきではありません。

※認識されない属性(attributes)と機能(capabilities)は通知なく破棄されます。

CAPABILITY INPUT/OUTPUT FORMAT

git credential capability の場合、形式は少し異なります。まず、プロトコルの現在のバージョンを示すために version 0 のアナウンスが行われ、 次に capability authtype のような行で各機能(capability)がアナウンスされます。 資格情報ヘルパーも、 やはり capability 引数を使用してこの形式を実装できます。 将来的には追加の行が追加される可能性があります。 呼び出し側は理解できない行を無視する必要があります。

これは認証情報ヘルパー・プロトコルの新しい部分であるため、 古いバージョンの Git や一部の認証情報ヘルパーはこれをサポートしていない可能性があります。 ゼロ以外の終了ステータスを受信した場合、 または最初の行が単語 version と空白1文字で始まっていない場合、 呼び出し側は機能がサポートされていないと想定する必要があります。

この形式の目的は、 資格情報の出力と明確に区​​別することです。 常に同一の出力を生成する非常に単純な資格情報ヘルパー(インライン・シェル・スクリプトなど)を使用することが可能です。 個別の形式を使用すると、 ユーザーは、 機能広告(capability advertisements)を正しく実装したり、 機能をクエリ(querying for capabilities)する呼び出し元を誤って混乱させたりすることを心配することなく、この構文を使い続けることができます。

GIT

Part of the git(1) suite