.gitbay/wiki/Architecture/06-Data-and-Cryptography.org
116 lines · 8671 bytes
1#+title: Data and cryptography
2
3* Data inventory
4
5Schema: =internal/store/migrations/=, 59 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 | *plaintext* |
18| Integrations | =webhooks= (secret), =webhook_deliveries=, =mirrors= (username, token) | C | *plaintext* secrets and tokens |
19| Notifications | =notifications= (mail queue), =inbox=, =push_devices= (APNs token), =push_queue= | P | device tokens in clear |
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| Backups | =/var/backups/gitbay=, offsite | all of the above |
35
36No table stores client IP addresses as a column. The daemon writes a
37client IP into an audit row only for authentication failures and
38throttling (=internal/sshd/sshd.go=).
39
40* At rest
41
42| Item | Protection |
43|---------------------------------------+----------------------------------------------------------------|
44| 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=) |
45| CI secrets, webhook secrets, mirror tokens, APNs device tokens | stored in clear in SQLite; protection is filesystem permissions and the rule that values are write-only through the interface |
46| SQLite file | mode 0640, directory 0750 |
47| Backups | the local archive is not encrypted; restic encrypts the offsite copy |
48| Disk | no application-level encryption; any disk encryption is the host's |
49
50The code base contains no symmetric encryption. A database or backup
51file read by anyone other than the =gitbay= user discloses every CI
52secret, webhook secret and mirror token.
53
54* In transit
55
56| Channel | Protection |
57|--------------------------+--------------------------------------------------------------|
58| SSH | Go =x/crypto/ssh=; ed25519 host key generated on first start |
59| HTTPS | TLS 1.2 minimum (=cmd/gitbayd/tls.go=), ACME or operator certificates; HSTS one year |
60| HTTP port 80 | ACME challenges and redirect only |
61| git:// | none (public data only; off by default) |
62| Runner ↔ server | SSH |
63| SMTP | STARTTLS required unless the relay is local (=mail.require_tls=), or implicit TLS (=mail.tls=) |
64| APNs | TLS, HTTP/2 |
65| Webhooks | TLS when the URL is https; HMAC-SHA256 body signature in =X-Gitbay-Signature-256= (=internal/webhook/webhook.go=) |
66| Mirrors | per URL; token passed through =GIT_ASKPASS=, never argv (=internal/mirror/mirror.go=) |
67
68TLS 1.2 is the minimum, set in code (=serverTLS= in
69=cmd/gitbayd/tls.go=); cipher suites are Go's defaults.
70
71* Cryptographic primitives
72
73| Use | Primitive | Code |
74|---------------------------------+--------------------------------------------+------------------------------------|
75| Token generation | =crypto/rand=, 32 bytes | =internal/store/sessions.go= |
76| Token storage | SHA-256 | =sessions.go= |
77| LFS transfer tokens | HMAC-SHA256, secret in =settings= | =internal/lfs/lfs.go= |
78| Webhook signatures | HMAC-SHA256 | =internal/webhook/webhook.go= |
79| APNs provider token | ES256 JWT (ECDSA P-256) | =internal/push/token.go= |
80| SSH host key | ed25519 | =internal/sshd/sshd.go= |
81| Commit and tag signatures | verify OpenPGP (ProtonMail go-crypto) and SSHSIG | =internal/sig= |
82| LFS object ids | SHA-256 | =internal/lfs/lfs.go= |
83
84Signature verification results are cached in =commit_signatures= with
85the global =key_epoch= at the time of verification. Any change to a
86trust input (a key added or removed, an email verified) bumps the
87epoch, which invalidates every cached result (=internal/store/users.go=,
88=internal/control/sig.go=).
89
90The server holds no signing key and signs nothing. A "verified" badge
91means a user's own key signed the commit.
92
93* Secret handling rules
94
95- Secrets enter only on stdin. A command must set =ReadsStdin=
96 to receive stdin at all; =TestStdinCommandsReadStdin= enforces it.
97 Examples: =repo secret set=, =repo deploy-key add=, =repo import
98 --token-stdin= (=internal/control/build.go=, =import.go=).
99- Secrets are listed by name, never echoed back.
100- The audit log stores argv with flag values stripped
101 (=internal/control/control.go=).
102- Mail errors are logged with addresses redacted
103 (=internal/notify/notify.go=).
104- CI secrets travel in the runner's claim only for trusted builds and
105 reach the container as environment variables through a 0600 env file
106 or podman's =--env NAME= pass-through, never argv
107 (=cmd/gitbay-runner/isolate.go=).
108
109* Retention
110
111Configured under =[retention]= for =audit=, =events=,
112=webhook_deliveries=, =mail= and =push=; unset means keep forever.
113Expired sessions and tokens are swept hourly regardless
114(=internal/config/config.go=, =cmd/gitbayd/main.go=).
115Accounts that never verify are removed after
116=registration.pending_expiry=. =account export= gives a user their data.