メインコンテンツまでスキップ

4. Log Client Messages (ログクライアントメッセージ)

4. Log Client Messages (ログクライアントメッセージ)​

メッセージは HTTPS GET または POST リクエストとして送られます。POST のパラメータおよびすべての応答は JavaScript Object Notation (JSON) オブジェクト [RFC4627] としてエンコードされます。GET のパラメータは順序に依存しないキー/値の URL パラメータとして, 「HTML 4.01 Specification」 [HTML401] で説明される application/x-www-form-urlencoded 形式でエンコードされます。バイナリデータは各メッセージで指定されるとおり base64 エンコード [RFC4648] されます。

JSON オブジェクトおよび URL パラメータには, ここで指定されていないフィールドが含まれてもよいです。これらの追加フィールドは無視すべきです。

<log server> プレフィックスにはサーバ名とポートに加えパスを含めてもよいです。

一般に必要な場合, version は v1 であり, id は照会したログサーバのログ id です。

エラーは HTTP 4xx または 5xx 応答として返され, 人間が読めるエラーメッセージが付きます。

4.1. Add Chain to Log (ログへのチェーン追加)​

POST https://<log server>/ct/v1/add-chain

入力:

  • chain: base64 エンコードされた証明書の配列。最初の要素はエンドエンティティ証明書, 2番目が最初にチェーンし, 最後はルート証明書か, 既知のルートにチェーンする証明書です。

出力:

  • sct_version: SignedCertificateTimestamp 構造のバージョンを10進で表した値。適合する v1 実装は, これが 0 (すなわち v1) であることを期待してはなりません。

  • id: ログ ID を base64 エンコードしたもの。TLS ハンドシェイクに含めるために SCT を要求するログクライアントはこれを検証する必要がないため, ログの ID を知っていると仮定しません。

  • timestamp: SCT のタイムスタンプを10進で表したもの。

  • extensions: 将来拡張のための不透明型です。すべての参加者がこのフィールドのデータを理解する必要はないでしょう。ログはこれを空文字列に設定すべきです。クライアントは base64 エンコードされたデータをデコードし, SCT に含めるべきです。

  • signature: SCT 署名を base64 エンコードしたもの。

sct_version が v1 でない場合, v1 クライアントは署名を検証できない可能性があります。これを誤りと解釈してはなりません (注: ログクライアントはこの構造を検証できる必要はありません。TLS クライアントだけが必要です。構造をバイナリ BLOB として提供するなら, v1 クライアントのアップグレードなしに完全に変更できます)。

4.2. Add PreCertChain to Log (ログへのPreCertChain追加)​

POST https://<log server>/ct/v1/add-pre-chain

入力:

  • chain: base64 エンコードされた Precertificate の配列。最初の要素はエンドエンティティ証明書, 2番目が最初にチェーンし, 最後はルート証明書か, 既知のルートにチェーンする証明書です。

出力は第4.1節と同じです。

4.3. Retrieve Latest Signed Tree Head (最新の署名付きツリーヘッドの取得)​

GET https://<log server>/ct/v1/get-sth

入力はありません。

出力:

  • tree_size: 木のサイズ (エントリ数) を10進で表したもの。

  • timestamp: タイムスタンプを10進で表したもの。

  • sha256_root_hash: 木のメルクルツリーハッシュを base64 で表したもの。

  • tree_head_signature: 上記データに対する TreeHeadSignature です。

4.4. Retrieve Merkle Consistency Proof between Two Signed Tree Heads (2つの署名付きツリーヘッド間のメルクル一貫性証明の取得)​

GET https://<log server>/ct/v1/get-sth-consistency

入力:

  • first: 最初の木の tree_size を10進で表したもの。

  • second: 2番目の木の tree_size を10進で表したもの。

両方の木サイズは, 既存の v1 STH (Signed Tree Heads) からのものでなければなりません。

出力:

  • consistency: メルクル木ノードの配列を base64 エンコードしたもの。

このデータに署名は不要です。STH を検証するために使われ, STH は署名されています。

4.5. Retrieve Merkle Audit Proof from Log by Leaf Hash (リーフハッシュによるメルクル監査証明の取得)​

GET https://<log server>/ct/v1/get-proof-by-hash

入力:

  • hash: v1 リーフハッシュを base64 エンコードしたもの。

  • tree_size: 証明の基準とする木の tree_size を10進で表したもの。

hash は第3.4節で定義されたとおりに計算されなければなりません。tree_size は既存の v1 STH を指さなければなりません。

出力:

  • leaf_index: hash パラメータに対応するエンドエンティティの0始まりインデックスです。

  • audit_path: 選択した証明書の包含を証明する, base64 エンコードされたメルクル木ノードの配列です。

4.6. Retrieve Entries from Log (ログからのエントリ取得)​

GET https://<log server>/ct/v1/get-entries

入力:

  • start: 取得する最初のエントリの0始まりインデックスを10進で表したもの。

  • end: 取得する最後のエントリの0始まりインデックスを10進で表したもの。

出力:

  • entries: 次からなるオブジェクトの配列です。

    • leaf_input: MerkleTreeLeaf 構造を base64 エンコードしたもの。

    • extra_data: ログエントリに関する符号なしデータを base64 エンコードしたもの。X509ChainEntry の場合は certificate_chain です。PrecertChainEntry の場合は PrecertChainEntry 全体です。

このメッセージは署名されません。取得データは, 取得した STH に対応するメルクルツリーハッシュを構築することで検証できます。すべての葉は v1 でなければなりません。ただし, 適合する v1 クライアントは, 認識できない MerkleLeafType または LogEntryType の値を誤りと解釈してはなりません。すなわち, 一部のエントリを解析できない場合がありますが, 各クライアントは認識するエントリを調べ, 認識できない葉を木への不透明入力として扱うことでデータの完全性を検証できます。

start および end パラメータは, 第4.3節の get-sth が返す tree_size に対して 0 <= x < tree_size の範囲内にあるべきです。

ログは, 0 <= start < tree_size かつ end >= tree_size の要求を, 指定範囲内の有効なエントリのみをカバーする部分応答を返すことで応じてもよいです。次の制限も適用される場合があることに注意してください。

ログは, get-entries リクエストあたりに取得できるエントリ数を制限してもよいです。クライアントが許可数より多くのエントリを要求した場合, ログは許容される最大数のエントリを返さなければなりません。これらのエントリは start で指定されたエントリから連続していなければなりません。

4.7. Retrieve Accepted Root Certificates (受理されたルート証明書の取得)​

GET https://<log server>/ct/v1/get-roots

入力はありません。

出力:

  • certificates: ログが受理するルート証明書を base64 エンコードした配列です。

4.8. Retrieve Entry+Merkle Audit Proof from Log (エントリとメルクル監査証明の取得)​

GET https://<log server>/ct/v1/get-entry-and-proof

入力:

  • leaf_index: 望むエントリのインデックス。

  • tree_size: 証明を求める木の tree_size です。

木サイズは既存の STH を指さなければなりません。

出力:

  • leaf_input: MerkleTreeLeaf 構造を base64 エンコードしたもの。

  • extra_data: 第4.6節と同じ符号なしデータを base64 エンコードしたもの。

  • audit_path: 選択した証明書の包含を証明する, base64 エンコードされたメルクル木ノードの配列です。

この API はおそらくデバッグにのみ有用です。

に最終更新