aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/design.md73
1 files changed, 43 insertions, 30 deletions
diff --git a/doc/design.md b/doc/design.md
index 7ef8a4e..da1bcf2 100644
--- a/doc/design.md
+++ b/doc/design.md
@@ -18,38 +18,51 @@ Please let us know if you have any feedback.
## 1 - Introduction
Transparent logs make it possible to detect unwanted events. For example,
- are there any (mis-)issued TLS certificates [\[CT\]](https://tools.ietf.org/html/rfc6962),
- did you get a different Go module than everyone else [\[ChecksumDB\]](https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md),
- or is someone running unexpected commands on your server [\[AuditLog\]](https://transparency.dev/application/reliably-log-all-actions-performed-on-your-servers/).
+are there any (mis-)issued TLS certificates
+ [\[CT\]](https://tools.ietf.org/html/rfc6962),
+did you get a different Go module than everyone else
+ [\[ChecksumDB\]](https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md),
+or is someone running unexpected commands on your server
+ [\[AuditLog\]](https://transparency.dev/application/reliably-log-all-actions-performed-on-your-servers/).
+
A sigsum log brings transparency to **sig**ned check**sum**s.
### 1.1 - Problem description
Suppose you are an entity that distributes some opaque data. For example,
the opaque data might be
a provenance file,
- an executable binary,
- an automatic software update, or
- a TPM quote.
-You claim to distribute the right opaque data to everyone.
-However, past incidents taught us that word is cheap and sometimes things go
-wrong. Trusted parties get compromised and lie about it [\[DigiNotar\]](), or
-they might not even realize it until later on because the break-in was stealthy
-[\[SolarWinds\]](https://www.zdnet.com/article/third-malware-strain-discovered-in-solarwinds-supply-chain-attack/).
-
-The goal of sigsum logging is to make your claims verifiable by you and
-others. To keep the design simple and general, we want to achieve this goal
-with few assumptions about the opaque data or the involved claims. You can
-think of this as some sort of bottom-line for what it takes to apply a
+ an executable binary, or
+ a javascript.
+You claim to distribute the right opaque data to everyone. However, past
+incidents taught us that word is cheap and sometimes things go wrong.
+Trusted parties get compromised and lie about it
+ [\[DigiNotar\]](https://roselabs.nl/files/audit_reports/Fox-IT_-_DigiNotar.pdf),
+or they might not even realize it until later on because the break-in was
+stealthy
+ [\[SolarWinds\]](https://www.zdnet.com/article/third-malware-strain-discovered-in-solarwinds-supply-chain-attack/).
+
+The goal of sigsum logging is to facilitate verification of your claims. To
+keep the design simple and general, we want to achieve this goal with few
+assumptions about the opaque data or the involved claims.
+
+You can think of this as some sort of bottom-line for what it takes to apply a
transparent logging pattern. Past use-cases that wanted to piggy-back on an
-existing reliable log ecosystem fit well into our scope [\[BinTrans\]](https://wiki.mozilla.org/Security/Binary_Transparency).
+existing reliable log ecosystem fit well into our scope
+ [\[BinTrans\]](https://wiki.mozilla.org/Security/Binary_Transparency).
+
+We also want our design to be easy from many different perspectives, for example
+log operations and verification in constrained environments. This includes
+considerations such as simple parsing, protection against log spam and
+poisoning, and a well-defined gossip protocol without complex auditing logic.
-We also want the design to be easy from many different perspectives, for example log operations and
-verification in constrained environments. This includes considerations such as
-simple parsing, protection against log spam and poisoning, and a
-well-defined gossip protocol without any complex auditing logic.
+This is in contrast to Certificate Transparency, which requires ASN.1
+parsing, storage of arbitrary certificate fields, reactive auditing of
+complicated log promises, and deployment of a gossip protocol that suits the web
+ [\[G1,](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7346853&casa_token=5bqmfaLp0Y8AAAAA:pzOJyu_BgWFxwEcM0r_ikDLhofU61PM8PWQnjcalxA3oXo7BxgKcOn0aIKorP02imZOG5i5Ew5sF&tag=1)
+ [G2\]](https://datatracker.ietf.org/doc/html/draft-ietf-trans-gossip-05).
### 1.2 - Abstract setting
-You would like users of the opaque data to _believe_ your claims. Therefore,
+You would like users of some opaque data to _believe_ your claims. Therefore,
we refer to you as a _claimant_ and your users as _believers_. Belief is going
to be reasonable because each claim is expressed as a _signed statement_ that is
transparency logged. The opaque data and relevant proofs of public logging are
@@ -61,8 +74,8 @@ a _verifier_ can discover any statement that you as a claimant produced. If it
turns out that a statement contains a false claim, an _arbiter_ is notified that
can act on it. An overview of these _roles_ and how they interact are shown in
Figure 1. A party may play multiple roles. A role may also be fulfilled by
-multiple parties. Refer to the [claimant model](https://github.com/google/trillian/blob/master/docs/claimantmodel/CoreModel.md)
-for additional detail.
+multiple parties. This is heavily inspired by the
+ [claimant model](https://github.com/google/trillian/blob/master/docs/claimantmodel/CoreModel.md).
```
statement +----------+
@@ -90,16 +103,15 @@ a certain cryptographic hash_. It is stored in a sigsum log for discoverability
claimant may add additional claims that are _implicit_ for each statement. An
implicit claim is not stored by the log and therefore communicated through
policy. Examples of implicit claims:
-- The opaque data can be located in repository Y using X as an identifier.
+- The opaque data can be located in repository X using Y as an identifier.
- The opaque data is a `.buildinfo` file that facilitates a reproducible build
[\[R-B\]](https://wiki.debian.org/ReproducibleBuilds/BuildinfoFiles).
Detailed examples of use-case specific claimant models are defined in a separate
-document [\[CM-Examples\]](https://git.sigsum.org/sigsum/blob/main/doc/claimant.md).
+document [\[CM-Examples\]](https://git.sigsum.org/sigsum/tree/doc/claimant.md).
### 1.3 - Design considerations
-Our main contribution is in the details that surround the log role in practise.
-Below is a brief summary.
+Below is a summary of design considerations that were considered.
- **Preserved data flows:** a believer can enforce sigsum logging without making
additional outbound network connections. Proofs of public logging are provided
using the same distribution mechanism as is used for distributing the opaque data.
@@ -113,13 +125,14 @@ 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:** transparent
logs rely on gossip protocols to detect forks. We built a proactive gossip
-protocol directly into the log. It is a variant of [witness cosigning]().
+protocol directly into the log. It is a variant of
+ [witness cosigning](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7546521&casa_token=W2hlJFylY3sAAAAA:lzSJGF_OlAjHGQf3dCefW2RbYad18U__hGo48BQvOdHuS4zWM2jW7j9ksgXVWlPjxh0nAT28GD4B).
- **No cryptographic agility**: the only supported signature scheme is Ed25519.
The only supported hash function is SHA256. Not having any cryptographic
agility makes protocols and data formats simpler and more secure.
- **Simple (de)serialization parsers:** complex (de)serialization parsers
increase attack surfaces and make the system more difficult to use in
-constrained environments. A sigsum statement can be (de)serialized using
+constrained environments. Signed and logged data can be (de)serialized using
[Trunnel](https://gitlab.torproject.org/tpo/core/trunnel/-/blob/main/doc/trunnel.md),
or "by hand" in many modern programming languages. This is the only parsing
that a believer is required to support. Claimants and verifiers additionally