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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
// -*- Mode: Go; indent-tabs-mode: t -*-
/*
* Copyright (C) 2025 Canonical Ltd
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 3 as
* published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
package assemblestate
type (
// Fingerprint is the sha512 of a TLS certificate
Fingerprint [64]byte
// Proof is a piece of data signed by a device's private key.
//
// TODO: This type probably isn't right, but it will be changed once we
// actually are using it.
Proof [64]byte
// DeviceToken is a cryptographically secure random device token (often
// referred to as RDT) for device, generated by the device itself.
DeviceToken string
)
// Auth is a top-level message used in the assemble protocol. This message is
// used prior to any other communications to prove knowledge of a shared secret.
type Auth struct {
// HMAC is calculated using sha512, using the shared assembly session secret
// as the HMAC key. The hash is applied to the concatenated byte
// representation of the following values:
// 1. The fingerprint of the TLS certificate presented by this message's
// sender
// 2. The device’s RDT value (must match the RDT field)
// Failure to match this pattern will result in authentication being denied.
HMAC []byte `json:"hmac"`
// RDT is the random device token associated with the sender of this message.
RDT DeviceToken `json:"rdt"`
}
// UnknownDevices is a top-level message used in the assemble protocol. This
// message is used to query another device for device identities.
type UnknownDevices struct {
// Devices is the list of devices that the sender of this message would like
// identifying information for.
Devices []DeviceToken `json:"devices"`
}
// Devices is a top-level message used in the assemble protocol. This message is
// used in response to the [UnknownDevices] message.
type Devices struct {
// Devices contains identifying information about the devices that the
// sender of this message was queried for.
Devices []Identity `json:"devices"`
}
// Identity carries the identifying information for a single device in the
// assembly session.
type Identity struct {
// RDT is this device's random device token.
RDT DeviceToken `json:"rdt"`
// TODO: we're not using these yet, but we eventually will.
// FP is the TLS certificate fingerprint used by this device.
FP Fingerprint `json:"fp"`
// Serial is this device's serial assertion.
Serial string `json:"serial"`
// SerialProof is the HMAC that this device would use to authenticate
// itself, signed by this device's private key. This signature can be
// verified using the serial assertion.
SerialProof Proof `json:"serial-proof"`
}
// Routes is a top-level message used in the assemble protocol. This message is
// used to spread information about topology of the cluster to other peers in
// the cluster.
type Routes struct {
// Devices is the set of devices that are involved in the routes that this
// message contains.
//
// TODO: once we start using this field to help with discovery, include
// info about that here.
Devices []DeviceToken `json:"devices"`
// Addresses is the set of addresses that are involved in the routes that
// this message contains.
Addresses []string `json:"addresses"`
// Routes contains triplets of indexes where every group of three
// consecutive values represents one verified route in the cluster:
// - Routes[n] = index into Devices slice (source device)
// - Routes[n+1] = index into Devices slice (destination device)
// - Routes[n+2] = index into Addresses slice (address to reach destination)
//
// For example, if Routes = [0, 1, 0, 2, 1, 1], this represents:
// - Route 1: Devices[0] can reach Devices[1] via Addresses[0]
// - Route 2: Devices[2] can reach Devices[1] via Addresses[1]
Routes []int `json:"routes"`
}
|
