From 01d7bd4785be2c82cc4765ba6e27cbcf61188862 Mon Sep 17 00:00:00 2001 From: Rasmus Dahlberg Date: Thu, 30 Sep 2021 01:44:13 +0200 Subject: cleaned-up README.md - Removed text that is now featured in design.md - Updated outdated URLs - Updated output of curl examples - Minor edits --- README.md | 69 +++++++++++++++++++++------------------------------------------ 1 file changed, 23 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 1395953..08afae2 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # sigsum-log-go -_Sigsum_ logging brings transparency to **sig**ned check**sum**s. What a +Sigsum logging brings transparency to **sig**ned check**sum**s. What a checksum represents is up to you. For example, it could be the cryptographic hash of a [provenance file](https://security.googleblog.com/2021/06/introducing-slsa-end-to-end-framework.html), a [Firefox binary](https://wiki.mozilla.org/Security/Binary_Transparency), or a text document. -Sigsum logging can be used to: +You can use sigsum logging to: 1. Discover which checksum signatures were produced by what secret signing keys. 2. Be sure that everyone observes the same signed checksums. @@ -19,7 +19,7 @@ select users might already receive maliciously signed binaries that include a backdoor. This is where we can help by adding transparency. For each binary you can log a signed checksum that corresponds to that binary. -If such a _sigsum_ appears in the log that you did not expect: excellent, now +If such a sigsum appears in the log that you did not expect: excellent, now you know that your signing infrastructure was compromised at some point. Similarly, you can also detect if a binary from your website or package repository misses a corresponding log entry by inspecting the log. The claim @@ -33,62 +33,39 @@ To make the most out of a sigsum log, end-users should start to enforce public logging in the future. This means that a binary in the above example would be _rejected_ unless a corresponding sigsum is publicly logged. -## Design considerations -We had several design considerations in mind while developing sigsum logging. A -short preview is listed below. Refer to our [design document](https://github.com/sigsum/sigsum/blob/main/doc/design.md) -and [API specification](https://github.com/sigsum/sigsum/blob/main/doc/api.md) -for additional details. Feedback is welcomed and encouraged! -- **Preserved data flows:** an end-user can enforce transparent logging without -making additional outbound network connections. Proofs of public logging should -be provided using the same distribution mechanism as the data. In the above -example the software publisher would put these proofs into their package -repository. -- **Sharding to simplify log life cycles:** starting to operate a log is easier -than closing it down in a reliable way. We have a predefined sharding interval -that determines the time during which the log will be active. -- **Defenses against log spam and poisoning:** to maximize a log's utility it -should be open for anyone to use. However, accepting logging requests from -anyone at arbitrary rates can lead to abusive usage patterns. We store as -little metadata as possible to combat log poisoning. We piggyback on DNS to -combat log spam. -- **Built-in mechanisms that ensure a globally consistent log:** transparency -logs rely on gossip protocols to detect forks. We built a proactive gossip -protocol directly into the log. It is based on witness cosigning. -- **No cryptographic agility**: the only supported signature scheme is Ed25519. -The only supported hash function is SHA256. Not having any cryptographic -agility makes the protocol and the data formats simpler and more secure. -- **Few and simple (de)serialization parsers:** complex (de)serialization -parsers increase attack surfaces and make the system more difficult to use in -constrained environments. End-users need a small subset of [Trunnel](https://gitlab.torproject.org/tpo/core/trunnel/-/blob/main/doc/trunnel.md) -to work with signed and logged data. The log's network clients also need to -parse ASCII key-value pairs. +Please refer to our +[design document](https://git.sigsum.org/sigsum/tree/doc/design.md) and +[API specification](https://git.sigsum.org/sigsum/tree/doc/api.md) +for additional details. ## Public prototype We implemented sigsum logging as a [Trillian](https://transparency.dev/#trillian) [personality](https://github.com/google/trillian/blob/master/docs/Personalities.md). A public prototype is up and running with zero promises of uptime, stability, -etc. The log's base URL is `http://tlog-poc.system-transparency.org:4780/st/v0`. -The log's public verification key is `bc9308dab23781b8a13d59a9e67bc1b8c1585550e72956525a20e479b1f74404`. +etc. +The log's base URL is http://poc.sigsum.org:4780/st/v0. +The log's public verification key is +`bc9308dab23781b8a13d59a9e67bc1b8c1585550e72956525a20e479b1f74404`. +The log's shard interval is [X, Y]. -An [experimental witness](https://github.com/sigsum/sigsum-witness-py) -is also up and running with zero promises of uptime, stability, etc. The -public verification key is `777528f5fd96f95713b8c2bb48bce2c83628e39ad3bfbd95bc0045b143fe5c34`. +An experimental [witness](https://github.com/sigsum/sigsum-witness-py) is also +up and running with zero-promises of uptime, stability, etc. +The public verification key is +`777528f5fd96f95713b8c2bb48bce2c83628e39ad3bfbd95bc0045b143fe5c34`. You can talk to the log by passing ASCII key-value pairs. For example, fetch a tree head and a log entry: ``` -$ echo "TODO: update to sigsum links" -$ curl http://tlog-poc.system-transparency.org:4780/st/v0/get-tree-head-latest -timestamp=1623053394 -tree_size=1 -root_hash=f337c7045b3233a921acc64688b729816a10f95f8be00910418aaa3c71245d5d -signature=50e88b935f6010dedb61314685371d16bf180be99bbd3463a0b6934be78c11ebf8cc81688e7d11b0dc593f2ea0453f6be8ed60abb825b5a08535a68cc007e20e -key_hash=2c27a6bafcbe210753c64666ca108025c68f28ded8933ebb2c4ef0987d7a6302 +$ curl http://poc.sigsum.org:4780/sigsum/v0/get-tree-head-latest +timestamp=1632956637 +tree_size=17 +root_hash=51ce7e8e7fa98d48ab84750ae9dcbabda268fbcca74ab907836a35a513396f9d +signature=c4bb2429410523d109540e0bd47e46b46bce6b233eb895fce4c761e60f15ac8a9d245153e3eaf30c7360b0f7bd49a6f7e4327bb1e7dc2396535726191b42c90b $ -$ printf "start_size=0\nend_size=0\n" | curl --data-binary @- http://tlog-poc.system-transparency.org:4780/st/v0/get-leaves +$ printf "start_size=0\nend_size=0\n" | curl --data-binary @- http://poc.sigsum.org:4780/sigsum/v0/get-leaves shard_hint=0 checksum=0000000000000000000000000000000000000000000000000000000000000000 -signature_over_message=0e0424c7288dc8ebec6b2ebd45e14e7d7f86dd7b0abc03861976a1c0ad8ca6120d4efd58aeab167e5e84fcffd0fab5861ceae85dec7f4e244e7465e41c5d5207 +signature=0e0424c7288dc8ebec6b2ebd45e14e7d7f86dd7b0abc03861976a1c0ad8ca6120d4efd58aeab167e5e84fcffd0fab5861ceae85dec7f4e244e7465e41c5d5207 key_hash=9d6c91319b27ff58043ff6e6e654438a4ca15ee11dd2780b63211058b274f1f6 ``` -- cgit v1.2.3