Documentation
¶
Overview ¶
Package statebackup exports a service's irreplaceable state (a node identity, a keystore, a wallet) as an encrypted file, and decides whether the user still has a backup of it.
The bundle format is the web app's (GeiserX/CashPilot app/state_backup.py), byte for byte, so one decrypt tool opens a backup from either app:
4-byte big-endian header length | header JSON | ChaCha20-Poly1305 ciphertext
The header carries magic "CASHPILOT-BACKUP", version 1, salt, nonce, mode, metadata and the payload's sha256. It is not encrypted but it is the AEAD's associated data, so changing which service a bundle says it belongs to breaks it. The key comes from scrypt (N=2^15, r=8, p=1) over a passphrase, or from HKDF-SHA256 (info "cashpilot-backup-v1") over an X25519 exchange with the recipient's public key.
CashPilot keeps nothing that could open what it exported: the passphrase is used once and dropped, and in recipient mode no secret enters the app at all. There is no upload and no schedule; a timer would need a stored key.
Index ¶
- Constants
- Variables
- func Fingerprint(facts map[string]MountFact, containerID string) string
- func GenerateKeypair() (string, string, error)
- func Judge(found *Confirmation, live string, now time.Time) string
- func Open(bundle []byte, passphrase, privateKeyHex string) ([]byte, error)
- func Seal(payload []byte, passphrase, recipientHex string, metadata map[string]any) ([]byte, error)
- func SplitArchives(payload []byte) (map[string][]byte, error)
- type Confirmation
- type Header
- type MountFact
- type Row
- type Volume
Constants ¶
const ( Magic = "CASHPILOT-BACKUP" Version = 1 ModePassphrase = "passphrase" ModeRecipient = "recipient" // MinPassphraseLength: shorter than this can be brute-forced offline, and // nothing rate-limits a guess at a stolen file. MinPassphraseLength = 12 // MaxStateBytes is the most state an export reads. Identities and wallets are // kilobytes; anything near this is a storage folder (Storj, Sia), which belongs // in a disk-level backup, not in one file held in memory with the node paused. MaxStateBytes = 256 << 20 )
const ( StateNone = "none" // never confirmed StateConfirmed = "confirmed" // confirmed, same state, under six months old StateChanged = "changed" // the state moved or was recreated since StateRecheck = "recheck" // confirmed when the fingerprint was unknown StateExpired = "expired" // older than MaxAge )
The states a service's backup can be in.
const MaxAge = 183 * 24 * time.Hour
MaxAge is how long a confirmed backup counts before the app asks again. The fingerprint catches a new volume or a moved folder; this catches what it cannot see, such as an identity regenerated inside the same volume. Same as the web.
const MaxArchiveBytes = MaxStateBytes
MaxArchiveBytes is the most file data a restore unpacks. An export never reads more than MaxStateBytes, tar headers included, so every bundle Desktop made fits. The web caps its own exports at 64 MB, so its bundles fit too.
const MaxArchiveEntries = 20_000
MaxArchiveEntries is the most entries a restore accepts. An identity, keystore or wallet folder holds tens of files, a relay folder a few hundred. Past this it is a data folder, which belongs in a disk-level backup. Same number as the web.
Variables ¶
var ErrBackup = errors.New("backup")
ErrBackup marks every error this package returns about a bundle or its inputs. The messages never contain a passphrase or key.
Functions ¶
func Fingerprint ¶
Fingerprint is a short hash of WHERE a service's irreplaceable state lives: each critical mount's type and source, plus a named volume's creation time, or the container id when the state is not on a mount. It changes when a volume is removed and made again or the service points somewhere else; it does not change when the container is recreated over the same volume (every image update). It never reads the files. Same recipe as the web's orchestrator.state_id.
func GenerateKeypair ¶
GenerateKeypair returns a fresh X25519 pair as (private hex, public hex). The private half is for the user to keep; nothing in the app stores it.
func Judge ¶
func Judge(found *Confirmation, live string, now time.Time) string
Judge decides a service's backup state from its confirmation (nil when there is none) and the fingerprint it has now ("" when unknown).
func Open ¶
Open decrypts a bundle with the passphrase or the recipient's private key (hex), whichever its header asks for, and checks the payload against the recorded sha256. A wrong secret and an altered file fail the same way.
func Seal ¶
Seal encrypts payload into a bundle. Exactly one of passphrase or recipientHex (an X25519 public key, 64 hex characters) must be given.
func SplitArchives ¶
SplitArchives turns a decrypted payload into one tar per backed-up mount.
The payload is Docker's archive of each critical mount, one after another, so each archive's entries sit under the mount's last path component (/var/lib/mysterium-node becomes mysterium-node/...). They are regrouped by that name.
Every entry is rebuilt from a short list of fields: name, type, permission bits, owner ids, modification time, size and link target. Owners, modes and times are what `docker cp` and `tar -x` need to put the files back the way the service expects; nothing else from the input reaches the output.
The archives get extracted as root into a volume, and in recipient mode anyone holding the public key can build a bundle that opens cleanly. So every entry is checked on its own and one refused entry fails the whole restore, with an error that names the rule: an absolute name, "..", a link that points out of its folder, a path through a link, a path given twice, a device or pipe, a sparse file, a PAX global header, any extended record such as a file capability, a control character in a name or link target, or an invalid time. Setuid, setgid and sticky bits are dropped. More than MaxArchiveBytes of file data or MaxArchiveEntries entries is refused before the data is read. Same rules as the web's split_archives.
Types ¶
type Confirmation ¶
type Confirmation struct {
Slug string `json:"slug"`
// StateID is the fingerprint when it was confirmed; "" when it could not be read.
StateID string `json:"stateId"`
// Method is "manual" (the button) or "export" (a backup saved from the app).
Method string `json:"method"`
ConfirmedAt time.Time `json:"confirmedAt"`
}
Confirmation is the user's word that a service's state is backed up.
type Header ¶
type Header struct {
Magic string `json:"magic"`
Version int `json:"version"`
Mode string `json:"mode"`
Salt string `json:"salt"`
Nonce string `json:"nonce"`
EphemeralPublicKey string `json:"ephemeral_public_key"`
SHA256 string `json:"sha256"`
Metadata map[string]any `json:"metadata"`
}
Header is the bundle's unencrypted, authenticated header. It never holds key material.
func ReadHeader ¶
ReadHeader returns the header without decrypting anything.
type MountFact ¶
type MountFact struct {
// Mounted is false when nothing is mounted there: the state lives in the
// container's own layer and dies with the container.
Mounted bool
Type string // "volume", "bind", ...
Name string // a named volume's name
Source string // a bind mount's host path
// Created is a named volume's CreatedAt.
Created string
}
MountFact is what Docker says about the mount at one critical target.
type Row ¶
type Row struct {
Slug string `json:"slug"`
Name string `json:"name"`
Volumes []Volume `json:"volumes"`
State string `json:"state"`
ConfirmedAt string `json:"confirmedAt"`
Method string `json:"method"`
// TracksChanges is false when the fingerprint could not be read (the
// container is gone, Docker is down), so only the time limit re-arms it.
TracksChanges bool `json:"tracksChanges"`
}
Row is one deployed service with irreplaceable state, as the card shows it.