1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
# sigsum_log_go design
This document describes the design of `sigsum_log_go`, an
implementation of
[Sigsum](https://git.sigsum.org/sigsum/tree/doc/design.md).
## General
TODO: add general design info
A log instance
- has one signing key,
- is made up of one or more log nodes -- primary and secondary,
- has at any given time exactly one primary and zero or more,
secondaries
- should really have at least one secondary node, to not risk losing
data,
- confirms new leaves (add-leaf returning HTTP code 200) once they
have been incorporated in the tree and sequenced but not before.
Log nodes
- publish two API:s, one public and one for use by other nodes of the
same log instance.
## Roles -- primary and secondary
A log node is configured to act as the `primary` node, or to act as a
`secondary` node. A primary is configured to know the base URL and
pubkey of zero or more secondaries. A secondary is configured to know
the base URL and pubkey of one primary.
### Interaction
A primary node that has no secondary nodes configured is the single
node in a test instance and lacks all means of recovering from storage
failures. This configuration is only recommended for testing of the
software.
A primary node that has at least one secondary node configured
- fetches and verifies the tree head from all its secondaries using
the internal API endpoint `getTreeHeadToCosign` (TBD: rename
endpoint to be uniquely named across both API:s?)
- considers a secondary node that can not be reached to have a tree
size of zero,
- advances its tree head no further than to the lowest tree size of
all its secondary nodes.
A secondary node:
- runs a Trillian server configured with a `PREORDERED_LOG` tree and
without a sequencer,
- periodically fetches all leaves from the primary using the internal
API endpoints `getTreeHeadUnsigned` and `getLeaves`,
- populates Trillian with the leaves fetched from its primary, in the
order that they are delivered,
- should advance its tree head more often than its primary node,
typically every few seconds.
### Promoting a secondary to become the primary
In order to promote a secondary node to become the primary node of a
log instance, the following things need to be done:
1. Shutting down the secondary. This effectively stops the primary
from advancing its tree head, regardless of its current status.
1. Converting the Trillian tree from type `PREORDERED_LOG` to type
`LOG`, using `updatetree`. Note that the tree needs to be `FROZEN`
before changing the tree type and unfrozen (`ACTIVE`) afterwards.
1. Configuring the secondary to use the signing key of the log instance.
1. Starting the secondary with `-role primary` and at least one
secondary node.
In order for clients to reach the new primary rather than the old one,
DNS record changes are usually needed as well.
### Open questions
- should secondaries publish the public API as well, but reply with
"404 not primary"? clients ending up at a secondary might benefit
from this
|
