ct.proto 9.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320
  1. syntax = "proto2";
  2. package ct;
  3. ////////////////////////////////////////////////////////////////////////////////
  4. // These protocol buffers should be kept aligned with the I-D. //
  5. ////////////////////////////////////////////////////////////////////////////////
  6. // RFC 5246
  7. message DigitallySigned {
  8. enum HashAlgorithm {
  9. NONE = 0;
  10. MD5 = 1;
  11. SHA1 = 2;
  12. SHA224 = 3;
  13. SHA256 = 4;
  14. SHA384 = 5;
  15. SHA512 = 6;
  16. }
  17. enum SignatureAlgorithm {
  18. ANONYMOUS = 0;
  19. RSA = 1;
  20. DSA = 2;
  21. ECDSA = 3;
  22. }
  23. // 1 byte
  24. optional HashAlgorithm hash_algorithm = 1 [ default = NONE ];
  25. // 1 byte
  26. optional SignatureAlgorithm sig_algorithm = 2 [ default = ANONYMOUS ];
  27. // 0..2^16-1 bytes
  28. optional bytes signature = 3;
  29. }
  30. enum LogEntryType {
  31. X509_ENTRY = 0;
  32. PRECERT_ENTRY = 1;
  33. PRECERT_ENTRY_V2 = 2;
  34. // Not part of the I-D, and outside the valid range.
  35. X_JSON_ENTRY = 32768; // Experimental, don't rely on this!
  36. UNKNOWN_ENTRY_TYPE = 65536;
  37. }
  38. message X509ChainEntry {
  39. // For V1 this entry just includes the certificate in the leaf_certificate
  40. // field
  41. // <1..2^24-1>
  42. optional bytes leaf_certificate = 1;
  43. // For V2 it includes the cert and key hash using CertInfo. The
  44. // leaf_certificate field is not used
  45. optional CertInfo cert_info = 3;
  46. // <0..2^24-1>
  47. // A chain from the leaf to a trusted root
  48. // (excluding leaf and possibly root).
  49. repeated bytes certificate_chain = 2;
  50. }
  51. // opaque TBSCertificate<1..2^16-1>;
  52. // struct {
  53. // opaque issuer_key_hash[32];
  54. // TBSCertificate tbs_certificate;
  55. // } PreCert;
  56. // Retained for V1 API compatibility. May be removed in a future release.
  57. message PreCert {
  58. optional bytes issuer_key_hash = 1;
  59. optional bytes tbs_certificate = 2;
  60. }
  61. // In V2 this is used for both certificates and precertificates in SCTs. It
  62. // replaces PreCert and has the same structure. The older message remains for
  63. // compatibility with existing code that depends on this proto.
  64. message CertInfo {
  65. optional bytes issuer_key_hash = 1;
  66. optional bytes tbs_certificate = 2;
  67. }
  68. message PrecertChainEntry {
  69. // <1..2^24-1>
  70. optional bytes pre_certificate = 1;
  71. // <0..2^24-1>
  72. // The chain certifying the precertificate, as submitted by the CA.
  73. repeated bytes precertificate_chain = 2;
  74. // PreCert input to the SCT. Can be computed from the above.
  75. // Store it alongside the entry data so that the signers don't have to
  76. // parse certificates to recompute it.
  77. optional PreCert pre_cert = 3;
  78. // As above for V2 messages. Only one of these fields will be set in a
  79. // valid message
  80. optional CertInfo cert_info = 4;
  81. }
  82. message XJSONEntry {
  83. optional string json = 1;
  84. }
  85. // TODO(alcutter): Consider using extensions here instead.
  86. message LogEntry {
  87. optional LogEntryType type = 1 [ default = UNKNOWN_ENTRY_TYPE ];
  88. optional X509ChainEntry x509_entry = 2;
  89. optional PrecertChainEntry precert_entry = 3;
  90. optional XJSONEntry x_json_entry = 4;
  91. }
  92. enum SignatureType {
  93. CERTIFICATE_TIMESTAMP = 0;
  94. // TODO(ekasper): called tree_hash in I-D.
  95. TREE_HEAD = 1;
  96. }
  97. enum Version {
  98. V1 = 0;
  99. V2 = 1;
  100. // Not part of the I-D, and outside the valid range.
  101. UNKNOWN_VERSION = 256;
  102. }
  103. message LogID {
  104. // 32 bytes
  105. optional bytes key_id = 1;
  106. }
  107. message SctExtension {
  108. // Valid range is 0-65534
  109. optional uint32 sct_extension_type = 1;
  110. // Data is opaque and type specific. <0..2^16-1> bytes
  111. optional bytes sct_extension_data = 2;
  112. }
  113. // TODO(ekasper): implement support for id.
  114. message SignedCertificateTimestamp {
  115. optional Version version = 1 [ default = UNKNOWN_VERSION ];
  116. optional LogID id = 2;
  117. // UTC time in milliseconds, since January 1, 1970, 00:00.
  118. optional uint64 timestamp = 3;
  119. optional DigitallySigned signature = 4;
  120. // V1 extensions
  121. optional bytes extensions = 5;
  122. // V2 extensions <0..2^16-1>. Must be ordered by type (lowest first)
  123. repeated SctExtension sct_extension = 6;
  124. }
  125. message SignedCertificateTimestampList {
  126. // One or more SCTs, <1..2^16-1> bytes each
  127. repeated bytes sct_list = 1;
  128. }
  129. enum MerkleLeafType {
  130. TIMESTAMPED_ENTRY = 0;
  131. UNKNOWN_LEAF_TYPE = 256;
  132. }
  133. message SignedEntry {
  134. // For V1 signed entries either the x509 or precert field will be set
  135. optional bytes x509 = 1;
  136. optional PreCert precert = 2;
  137. optional bytes json = 3;
  138. // For V2 all entries use the CertInfo field and the above fields are
  139. // not set
  140. optional CertInfo cert_info = 4;
  141. }
  142. message TimestampedEntry {
  143. optional uint64 timestamp = 1;
  144. optional LogEntryType entry_type = 2;
  145. optional SignedEntry signed_entry = 3;
  146. // V1 extensions
  147. optional bytes extensions = 4;
  148. // V2 extensions <0..2^16-1>. Must be ordered by type (lowest first)
  149. repeated SctExtension sct_extension = 5;
  150. }
  151. // Stuff that's hashed into a Merkle leaf.
  152. message MerkleTreeLeaf {
  153. // The version of the corresponding SCT.
  154. optional Version version = 1 [ default = UNKNOWN_VERSION ];
  155. optional MerkleLeafType type = 2 [ default = UNKNOWN_LEAF_TYPE ];
  156. optional TimestampedEntry timestamped_entry = 3;
  157. }
  158. // TODO(benl): No longer needed?
  159. //
  160. // Used by cpp/client/ct: it assembles the one from the I-D JSON
  161. // protocol.
  162. //
  163. // Used by cpp/server/blob-server: it uses one to call a variant of
  164. // LogLookup::AuditProof.
  165. message MerkleAuditProof {
  166. optional Version version = 1 [ default = UNKNOWN_VERSION ];
  167. optional LogID id = 2;
  168. optional int64 tree_size = 3;
  169. optional uint64 timestamp = 4;
  170. optional int64 leaf_index = 5;
  171. repeated bytes path_node = 6;
  172. optional DigitallySigned tree_head_signature = 7;
  173. }
  174. message ShortMerkleAuditProof {
  175. required int64 leaf_index = 1;
  176. repeated bytes path_node = 2;
  177. }
  178. ////////////////////////////////////////////////////////////////////////////////
  179. // Finally, stuff that's not in the I-D but that we use internally //
  180. // for logging entries and tree head state. //
  181. ////////////////////////////////////////////////////////////////////////////////
  182. // TODO(alcutter): Come up with a better name :/
  183. message LoggedEntryPB {
  184. optional int64 sequence_number = 1;
  185. optional bytes merkle_leaf_hash = 2;
  186. message Contents {
  187. optional SignedCertificateTimestamp sct = 1;
  188. optional LogEntry entry = 2;
  189. }
  190. required Contents contents = 3;
  191. }
  192. message SthExtension {
  193. // Valid range is 0-65534
  194. optional uint32 sth_extension_type = 1;
  195. // Data is opaque and type specific <0..2^16-1> bytes
  196. optional bytes sth_extension_data = 2;
  197. }
  198. message SignedTreeHead {
  199. // The version of the tree head signature.
  200. // (Note that each leaf has its own version, so a V2 tree
  201. // can contain V1 leaves, too.
  202. optional Version version = 1 [ default = UNKNOWN_VERSION ];
  203. optional LogID id = 2;
  204. optional uint64 timestamp = 3;
  205. optional int64 tree_size = 4;
  206. optional bytes sha256_root_hash = 5;
  207. optional DigitallySigned signature = 6;
  208. // Only supported in V2. <0..2^16-1>
  209. repeated SthExtension sth_extension = 7;
  210. }
  211. // Stuff the SSL client spits out from a connection.
  212. message SSLClientCTData {
  213. optional LogEntry reconstructed_entry = 1;
  214. optional bytes certificate_sha256_hash = 2;
  215. message SCTInfo {
  216. // There is an entry + sct -> leaf hash mapping.
  217. optional SignedCertificateTimestamp sct = 1;
  218. optional bytes merkle_leaf_hash = 2;
  219. }
  220. repeated SCTInfo attached_sct_info = 3;
  221. }
  222. message ClusterNodeState {
  223. optional string node_id = 1;
  224. optional int64 contiguous_tree_size = 2 [deprecated = true];
  225. optional SignedTreeHead newest_sth = 3;
  226. optional SignedTreeHead current_serving_sth = 4;
  227. // The following host_name/log_port pair are used to allow a log node to
  228. // contact other nodes in the cluster, primarily for the purposes of
  229. // replication.
  230. // hostname/ip which can be used to contact [just] this log node
  231. optional string hostname = 5;
  232. // port on which this log node is listening.
  233. optional int32 log_port = 6;
  234. }
  235. message ClusterControl {
  236. optional bool accept_new_entries = 1 [ default = true ];
  237. }
  238. message ClusterConfig {
  239. /////////////////////////////////
  240. // This section of the config affects the selection of the cluster's current
  241. // serving STH.
  242. // The cluster will always attempt to determine the newest (and
  243. // largest) possible STH which meets the constraints defined below from the
  244. // set of STHs available at the individual cluster nodes.
  245. // (Note that nodes with newer/larger STHs can, of course, serve
  246. // earlier/smaller STHs.)
  247. // The minimum number of nodes which must be able to serve a given STH.
  248. // This setting allows you to configure the level of cluster resiliency
  249. // against data (in the form of node/node database) loss.
  250. // i.e.: Once an STH has been created, it must have been replicated to
  251. // at least this many nodes before being considered as a candidate for
  252. // the overall cluster serving STH.
  253. optional int32 minimum_serving_nodes = 1;
  254. // The minimum fraction of nodes which must be able to serve a given STH.
  255. // This setting allows you to configure the serving capacity redundancy of
  256. // your cluster.
  257. // e.g. you determine you need 3 nodes to serve your expected peak traffic
  258. // levels, but want to be over-provisioned by 25% to ensure the cluster will
  259. // continue to be able to handle the traffic in the case of a single node
  260. // failure, you might set this to 0.75 to ensure that any cluster-wide
  261. // serving STH candidate must be servable from at least 3 of your 4 nodes.
  262. optional double minimum_serving_fraction = 2;
  263. /////////////////////////////////
  264. // When the number of entries in the EtcedConsistentStore exceeds this value,
  265. // the log server will reject all calls to add-[pre-]chain to protect itself
  266. // and etcd.
  267. optional double etcd_reject_add_pending_threshold = 3 [default = 30000];
  268. }
  269. message SequenceMapping {
  270. message Mapping {
  271. optional bytes entry_hash = 1;
  272. optional int64 sequence_number = 2;
  273. }
  274. repeated Mapping mapping = 1;
  275. }