aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorRasmus Dahlberg <rasmus.dahlberg@kau.se>2021-06-11 01:17:13 +0200
committerRasmus Dahlberg <rasmus.dahlberg@kau.se>2021-06-11 01:17:13 +0200
commit712def3b41414a627a11463e17d383e2d52e43e0 (patch)
treed3365fd96fb393928b5087fb00d7cc0c14125073 /README.md
parent22e3e0954fe9ef784dfdd276ba4e9bedf3c262b3 (diff)
improved readme based on ln5 feedback
Diffstat (limited to 'README.md')
-rw-r--r--README.md84
1 files changed, 52 insertions, 32 deletions
diff --git a/README.md b/README.md
index 382d378..7d4d6e2 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,45 @@
-# System Transparency Front-End (STFE)
-STFE is a [Trillian](https://transparency.dev/#trillian)
-[personality](https://github.com/google/trillian/blob/master/docs/Personalities.md)
-that allows you to log signed checksums. What a checksum represents is up to the
-submitter. For example, it could be a Firefox update, a Debian package, or a
-document. You can use STFE to:
+# Signature Transparency Logging
+Signature Transparency Logging allows you to add signed checksums into an
+append-only and tamper-evident log. What a checksum represents is up to the
+submitter. For example, it could be a cryptographic hash of a Firefox update, a
+Debian package, or a document. You can use Signature Transparency Logging to:
1. Discover which signatures were produced by what secret signing keys.
2. Be sure that everyone observes the same signed checksums.
-**It works as follows.**
+We abbreviate Signature Transparency Logging as _siglog_.
+
+## How it works
Suppose that you develop software and publish binaries. You sign those binaries
-and make them available to users in a database. You are committed to distribute
-the same non-malicious binaries to every user. That is an easy claim to make.
-However, word is cheap and sometimes things go wrong. How would you even know
-if your secret signing key or build environment got compromised? A few select
-users might receive maliciously signed binaries that include back-doors.
-This is where STFE can help by adding transparency.
+and make them available to users in a package repository. You are committed to
+distribute the same signed binaries to every user. That is an easy claim to
+make. However, word is cheap and sometimes things go wrong. How would you even
+know if your signing infrastructure got compromised? A few select users might
+already receive maliciously signed binaries that include a backdoor. This is
+where siglog can help by adding transparency in the future.
+
+For each binary you can log a signed checksum that corresponds to that binary.
+If a signed checksum appears in the log that you did not expect: excellent, now
+you know that your signing infrastructure was compromised at some point. Anyone
+can also detect if a logged checksum is unaccounted for in your package
+repository by inspecting the log. In other words, the claim that the same
+binaries are published for everyone can be _verified_.
-For each binary you can log a signed checksum. If a signed checksum appears in
-the log that you did not expect: excellent, now you know that your secret
-signing key or build environment was compromised at some point. Anyone can also
-detect if a logged checksum is unaccounted for in your database by inspecting
-the log. In other words, the claim that the same non-malicious binaries are
-published for everyone can be _verified_.
+Adding signed checksums into a log is already an improvement without any
+end-user enforcement. Honest mistakes can be detected. However, end-users need
+to enforce public logging to get the most out of siglog. This means that a
+binary in the above example would be rejected unless a corresponding signed
+checksum is logged.
-## Design
-We had several design considerations in mind while developing STFE. A short
+## Design considerations
+We had several design considerations in mind while developing siglog. A short
preview is listed below. Please refer to our [design document](https://github.com/system-transparency/stfe/blob/main/doc/design.md)
and [API specification](https://github.com/system-transparency/stfe/blob/main/doc/api.md)
for additional details. Feedback is welcomed and encouraged!
-- **Preserved data flows:** an end-user can enforce transparency logging without
-making additional outbound connections. The data publisher should distribute
-proofs of public logging as part of their database.
+- **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.
@@ -45,16 +54,21 @@ 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 simpler and more secure.
-- **Few simple (de)serialization parsers:** complex (de)serialization
-parsers would increase our attack surface and make the system more difficult
-to use in constrained environments. End-users need a small subset of Trunnel to
-work with signed and logged data. Log clients additionally need to parse ASCII
+- **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 to work with
+signed and logged data. The log's network clients also need to parse ASCII
key-value pairs.
-## Public Prototype
-We have a public prototype that is up and running with zero promises of uptime,
-stability, etc. You can talk to the log by passing ASCII-encoded key-value
-pairs. For example, go ahead and fetch the latest tree head:
+## Public prototype
+We implemented siglog 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`.
+
+You can talk to the log by passing ASCII key-value pairs. For example,
+fetch a tree head and a log entry:
```
$ curl http://tlog-poc.system-transparency.org:4780/st/v0/get-tree-head-latest
timestamp=1623053394
@@ -62,6 +76,12 @@ tree_size=1
root_hash=f337c7045b3233a921acc64688b729816a10f95f8be00910418aaa3c71245d5d
signature=50e88b935f6010dedb61314685371d16bf180be99bbd3463a0b6934be78c11ebf8cc81688e7d11b0dc593f2ea0453f6be8ed60abb825b5a08535a68cc007e20e
key_hash=2c27a6bafcbe210753c64666ca108025c68f28ded8933ebb2c4ef0987d7a6302
+$
+$ printf "start_size=0\nend_size=0\n" | curl --data-binary @- http://tlog-poc.system-transparency.org:4780/st/v0/get-leaves
+shard_hint=0
+checksum=0000000000000000000000000000000000000000000000000000000000000000
+signature_over_message=0e0424c7288dc8ebec6b2ebd45e14e7d7f86dd7b0abc03861976a1c0ad8ca6120d4efd58aeab167e5e84fcffd0fab5861ceae85dec7f4e244e7465e41c5d5207
+key_hash=9d6c91319b27ff58043ff6e6e654438a4ca15ee11dd2780b63211058b274f1f6
```
We are currently working on tooling that makes it easier to interact with the