跳到主要内容

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 编码证书组成的数组. 第一个元素为终端实体证书; 第二个链接到第一个, 依此类推直至最后一个, 该证书为根证书或链接到已知根证书的证书.

输出:

  • sct_version: SignedCertificateTimestamp 结构的版本, 十进制. 符合规范的 v1 实现不得期望该值为 0 (即 v1).

  • id: 日志 ID, base64 编码. 由于请求 SCT 以纳入 TLS 握手的日志客户端不要求验证它, 我们不假定它们知道日志的 ID.

  • timestamp: SCT 时间戳, 十进制.

  • extensions: 供将来扩展的不透明类型. 很可能并非所有参与者都需要理解此字段中的数据. 日志宜将此设为空字符串. 客户端应解码 base64 编码的数据并将其纳入 SCT.

  • signature: SCT 签名, base64 编码.

若 sct_version 不是 v1, 则 v1 客户端可能无法验证签名. 其不得将此视为错误. (注: 日志客户端不需要能够验证此结构; 只有 TLS 客户端需要. 若我们将该结构作为二进制块提供, 则可以在不要求 v1 客户端升级的情况下完全改变它.)

4.2. Add PreCertChain to Log (向日志添加预证书链)​

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

输入:

  • chain: base64 编码预证书组成的数组. 第一个元素为终端实体证书; 第二个链接到第一个, 依此类推直至最后一个, 该证书为根证书或链接到已知根证书的证书.

输出与第 4.1 节相同.

4.3. Retrieve Latest Signed Tree Head (获取最新签名树头)​

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

无输入.

输出:

  • tree_size: 树的规模, 以条目数计, 十进制.

  • timestamp: 时间戳, 十进制.

  • sha256_root_hash: 树的 Merkle 树散列, base64.

  • tree_head_signature: 上述数据的 TreeHeadSignature.

4.4. Retrieve Merkle Consistency Proof between Two Signed Tree Heads (获取两个签名树头之间的 Merkle 一致性证明)​

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

输入:

  • first: 第一棵树的 tree_size, 十进制.

  • second: 第二棵树的 tree_size, 十进制.

两个树规模必须来自现有的 v1 STH (Signed Tree Heads).

输出:

  • consistency: Merkle 树结点组成的数组, base64 编码.

注意此数据不需要签名, 因其用于验证已签名的 STH.

4.5. Retrieve Merkle Audit Proof from Log by Leaf Hash (按叶散列从日志获取 Merkle 审计证明)​

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

输入:

  • hash: base64 编码的 v1 叶散列.

  • tree_size: 作为证明基础的树的 tree_size, 十进制.

hash 必须按第 3.4 节定义计算. tree_size 必须指定一个现有的 v1 STH.

输出:

  • leaf_index: 与 hash 参数对应的终端实体的从 0 开始的索引.

  • audit_path: base64 编码的 Merkle 树结点数组, 证明所选证书的包含性.

4.6. Retrieve Entries from Log (从日志获取条目)​

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

输入:

  • start: 要获取的首个条目的从 0 开始的索引, 十进制.

  • end: 要获取的最后一个条目的从 0 开始的索引, 十进制.

输出:

  • entries: 对象数组, 每个对象包含

    • leaf_input: base64 编码的 MerkleTreeLeaf 结构.

    • extra_data: 与日志条目相关的 base64 编码无符号数据. 对于 X509ChainEntry, 此为 certificate_chain. 对于 PrecertChainEntry, 此为整个 PrecertChainEntry.

注意此消息未签名, 获取的数据可通过构造与所获取 STH 对应的 Merkle 树散列来验证. 所有叶必须为 v1. 但是, 符合规范的 v1 客户端不得将无法识别的 MerkleLeafType 或 LogEntryType 值视为错误. 这意味着它可能无法解析某些条目, 但注意每个客户端仍可检查其能够识别的条目, 并通过将无法识别的叶视为对树的不透明输入来验证数据完整性.

start 与 end 参数宜处于 0 <= x < 第 4.3 节 get-sth 返回的 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 (从日志获取条目及 Merkle 审计证明)​

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

输入:

  • leaf_index: 所需条目的索引.

  • tree_size: 需要证明的树的 tree_size.

树规模必须指定一个现有的 STH.

输出:

  • leaf_input: base64 编码的 MerkleTreeLeaf 结构.

  • extra_data: base64 编码的无符号数据, 与第 4.6 节相同.

  • audit_path: base64 编码的 Merkle 树结点数组, 证明所选证书的包含性.

此 API 可能仅对调试有用.

最后于 更新