.gitbay/wiki/Architecture/06-Data-and-Cryptography.org
118 lines · 9017 bytes
1#+title: Data and cryptography
2
3* Data inventory
4
5Schema: =internal/store/migrations/=, 66 migrations. Classification:
6*C* credential or secret, *P* personal data, *R* private repository
7content (as confidential as the repository), *O* operational.
8
9| Domain | Tables | Class | Notes |
10|-----------------+---------------------------------------------------------------------------------------------+-------+-------------------------------------------------|
11| Identity | =users=, =emails=, =ssh_keys=, =pgp_keys=, =orgs=, =org_members=, =teams=, =team_members= | P | email addresses in clear; keys are public |
12| Credentials | =api_tokens=, =web_sessions=, =login_tokens=, =email_tokens=, =invites= | C | SHA-256 hashes only |
13| Repositories | =repos=, =repo_access=, =team_repos=, =repo_topics=, =repo_watchers=, =repo_pins=, =repo_bookmarks=, =page_domains= | O | |
14| Collaboration | =issues=, =issue_*=, =merge_requests=, =mr_*=, =labels=, =milestones=, =mentions= | R | bodies of issues, comments and reviews |
15| Releases, snippets | =releases=, =release_assets=, =snippets=, =snippet_files= | R | |
16| CI | =builds= (includes logs), =build_schedules=, =runner_repos=, =runner_seen= | R | build logs can echo anything a step prints |
17| CI secrets | =build_secrets= | C | sealed (AES-256-GCM) |
18| Integrations | =webhooks= (secret), =webhook_deliveries=, =mirrors= (username, token) | C | webhook secret and mirror token sealed |
19| Notifications | =notifications= (mail queue), =inbox=, =push_devices= (APNs token), =push_queue= | P | device tokens sealed; looked up by SHA-256 |
20| Signatures | =commit_signatures=, =settings.key_epoch= | O | verification cache |
21| Audit and feed | =audit_log=, =events= | O, P | actor ids, pruned argv, fingerprints and IPs in some audit rows, a hash chain (=prev_hash=, =hash=) |
22| Dependencies | =dep_checks=, =dep_reports= | O | |
23
24Outside the database:
25
26| Data | Location | Class |
27|----------------------------+-----------------------------------+-------|
28| Repository contents | =<root>/repos= | R |
29| LFS objects | =<root>/lfs= | R |
30| SSH host key | =<root>/ssh/host_ed25519= | C |
31| TLS keys (ACME) | =<root>/acme= | C |
32| SMTP password | =/etc/gitbay/config.toml= | C |
33| APNs signing key (.p8) | path in =push.key_file= | C |
34| Secret key file | =server.secret_key_file= (=/etc/gitbay/secret.key=) | C |
35| Backups | =/var/backups/gitbay=, offsite | all of the above |
36
37No table stores client IP addresses as a column. The daemon writes a
38client IP into an audit row only for authentication failures and
39throttling (=internal/sshd/sshd.go=).
40
41* At rest
42
43| Item | Protection |
44|---------------------------------------+----------------------------------------------------------------|
45| API tokens, sessions, login links, email codes, invites | SHA-256 of a 256-bit random value; the value is shown once and never stored (=internal/store/sessions.go=) |
46| CI secrets, webhook secrets, mirror tokens, APNs device tokens | AES-256-GCM under a key file outside the database and outside =server.root=; additional data binds table, column and row (=internal/seal=, =internal/store/secrets.go=) |
47| SQLite file | mode 0640, directory 0750 |
48| Backups | local archives age-encrypted when =[backup] age_recipients= is set; restic encrypts the offsite copy; neither carries the secret key file, which is copied off the host by hand until a separate keys repository is set up |
49| Disk | no application-level encryption; any disk encryption is the host's |
50
51The database file or a backup read by anyone other than the =gitbay=
52user discloses no CI secret, webhook secret, mirror token or device
53token without the key file, which neither carries. Rotation:
54=gitbayd admin secrets rotate= (Admin wiki).
55
56* In transit
57
58| Channel | Protection |
59|--------------------------+--------------------------------------------------------------|
60| SSH | Go =x/crypto/ssh=; ed25519 host key generated on first start |
61| HTTPS | TLS 1.2 minimum (=cmd/gitbayd/tls.go=), ACME or operator certificates; HSTS one year |
62| HTTP port 80 | ACME challenges and redirect only |
63| git:// | none (public data only; off by default) |
64| Runner ↔ server | SSH |
65| SMTP | STARTTLS required unless the relay is local (=mail.require_tls=), or implicit TLS (=mail.tls=) |
66| APNs | TLS, HTTP/2 |
67| Webhooks | TLS when the URL is https; HMAC-SHA256 body signature in =X-Gitbay-Signature-256= (=internal/webhook/webhook.go=) |
68| Mirrors | per URL; token passed through =GIT_ASKPASS=, never argv (=internal/mirror/mirror.go=) |
69
70TLS 1.2 is the minimum, set in code (=serverTLS= in
71=cmd/gitbayd/tls.go=); cipher suites are Go's defaults.
72
73* Cryptographic primitives
74
75| Use | Primitive | Code |
76|---------------------------------+--------------------------------------------+------------------------------------|
77| Token generation | =crypto/rand=, 32 bytes | =internal/store/sessions.go= |
78| Token storage | SHA-256 | =sessions.go= |
79| LFS transfer tokens | HMAC-SHA256, secret in =settings= | =internal/lfs/lfs.go= |
80| Webhook signatures | HMAC-SHA256 | =internal/webhook/webhook.go= |
81| APNs provider token | ES256 JWT (ECDSA P-256) | =internal/push/token.go= |
82| SSH host key | ed25519 | =internal/sshd/sshd.go= |
83| Commit and tag signatures | verify OpenPGP (ProtonMail go-crypto) and SSHSIG | =internal/sig= |
84| LFS object ids | SHA-256 | =internal/lfs/lfs.go= |
85
86Signature verification results are cached in =commit_signatures= with
87the global =key_epoch= at the time of verification. Any change to a
88trust input (a key added or removed, an email verified) bumps the
89epoch, which invalidates every cached result (=internal/store/users.go=,
90=internal/control/sig.go=).
91
92The server holds no signing key and signs nothing. A "verified" badge
93means a user's own key signed the commit.
94
95* Secret handling rules
96
97- Secrets enter only on stdin. A command must set =ReadsStdin=
98 to receive stdin at all; =TestStdinCommandsReadStdin= enforces it.
99 Examples: =repo secret set=, =repo deploy-key add=, =repo import
100 --token-stdin= (=internal/control/build.go=, =import.go=).
101- Secrets are listed by name, never echoed back.
102- The audit log stores argv with flag values stripped
103 (=internal/control/control.go=).
104- Mail errors are logged with addresses redacted
105 (=internal/notify/notify.go=).
106- CI secrets travel in the runner's claim only for trusted builds and
107 reach the container as environment variables through a 0600 env file
108 or podman's =--env NAME= pass-through, never argv
109 (=cmd/gitbay-runner/isolate.go=).
110
111* Retention
112
113Configured under =[retention]= for =audit=, =events=,
114=webhook_deliveries=, =mail= and =push=; unset means keep forever.
115Expired sessions and tokens are swept hourly regardless
116(=internal/config/config.go=, =cmd/gitbayd/main.go=).
117Accounts that never verify are removed after
118=registration.pending_expiry=. =account export= gives a user their data.