documentation changes after peer reviews (Daniel and ChatGPT)

Author: Daniel-Nashed

README.md

@@ -1,7 +1,7 @@
 # srvguard
 
 **Nash!Com Service Guard** — a universal service launcher and secret manager
-for [HashiCorp Vault](https://www.vaultproject.io/)-integrated workloads.
+for secure, automated secret delivery to any workload.
 
 `srvguard` solves a fundamental bootstrap problem: a service needs its
 secrets (TLS certificate, private key, password) before it can start, but
@@ -491,7 +491,7 @@ docker build --target release -t srvguard:latest .
 
 `srvguard` expects a flat KV v2 secret. Field names are flexible —
 configure the consumer to read whichever fields are present. The defaults
-used by [nashcom-vault](https://github.com/nashcom/nashcom-vault) are:
+used by [nsh-vault-deploy](https://github.com/nashcom/nsh-vault-deploy) are:
 
 **TLS credentials:**
 

docs/architecture.md

@@ -37,7 +37,7 @@ operator                 systemd                   srvguard            Vault
    │                         │────────────────────────►│                  │
    │                         │                         │  GET /v1/secret/ │
    │                         │                         │─────────────────►│
-   │                         │◄─────────────────────────────────────────── │
+   │                         │◄────────────────────────────────────────────│
    │                         │                         │  write to tmpfs  │
    │                         │                         │  signal service  │
 ```

docs/linux-kernel-keyring.md

@@ -3,9 +3,10 @@
 ## What It Is
 
 The Linux kernel keyring is an in-kernel storage facility for small secrets —
-passwords, tokens, cryptographic keys — that never leave kernel memory.
-Secrets placed in the keyring are not visible in `/proc`, are not swapped to
-disk, and survive only as long as the keyring that holds them exists.
+passwords, tokens, cryptographic keys — stored in kernel memory and not
+exposed via normal userspace interfaces. Secrets placed in the keyring are
+not directly written to disk by the keyring subsystem, and survive only as
+long as the keyring that holds them exists.
 
 It was introduced in Linux 2.6.10 and is present in every modern Linux
 distribution. No additional software is required.
@@ -19,8 +20,9 @@ distribution. No additional software is required.
 keyring is destroyed, all keys in it are destroyed.
 
 **Session keyring:** created when a process session starts, destroyed when it
-ends. Each login session or service invocation gets its own keyring that
-cannot be accessed by other sessions.
+ends. Each login session or service invocation gets its own keyring that is
+isolated by default from other sessions, unless explicitly shared or accessed
+by a sufficiently privileged process.
 
 **Key permissions:** each key has owner/group/other permission bits controlling
 who can read, write, search, or link it. A key created by `srvguard` with
@@ -30,13 +32,16 @@ who can read, write, search, or link it. A key created by `srvguard` with
 
 The keyring provides properties that files on disk cannot:
 
-- **Memory-only:** the payload never touches the filesystem, swap, or any disk
-  buffer. Hibernation aside, it is never written anywhere persistent.
+- **Not written to disk by the subsystem:** the keyring itself does not write
+  payloads to the filesystem or any disk buffer. Kernel memory can theoretically
+  be swapped or captured in a hibernation image or crash dump, but the keyring
+  does not actively persist secrets — unlike a file or environment variable.
 - **Lifecycle-bound:** a key attached to a session keyring is automatically
   destroyed when the session ends — no cleanup required.
 - **Kernel-enforced access control:** the kernel enforces permissions on every
-  read attempt. Even root cannot read a key owned by another user without
-  `CAP_SYS_ADMIN`.
+  read attempt. Key payload is not exposed via `/proc` — though key metadata
+  (serial number, description) may be visible in `/proc/keys`. Even root
+  cannot read a key payload owned by another user without `CAP_SYS_ADMIN`.
 - **Read-once pattern:** the consumer reads the key payload once and
   immediately revokes it. After revocation the key is gone — any second read
   fails, even by the original owner.

docs/systemd-credentials.md

@@ -2,14 +2,14 @@
 
 ## What They Are
 
-systemd credentials are encrypted, service-scoped secrets injected into
-services at startup by the service manager. They are the systemd-native answer
-to the question: *how does a service get a secret without storing it in a
-config file?*
+systemd credentials are service-scoped secrets injected into services at
+startup by the service manager. They can optionally be encrypted at rest.
+They are the systemd-native answer to the question: *how does a service get
+a secret without storing it in a config file?*
 
-Introduced in systemd v250 (released December 2021, standard in RHEL 9,
-Debian 12, Ubuntu 22.04+), credentials are available on every current
-enterprise Linux distribution.
+Introduced in systemd v250 (released December 2021), credentials are
+available on distributions shipping systemd v250 or newer — including
+RHEL 9+, Debian 12+, and Ubuntu 22.04+.
 
 ## How They Work
 
@@ -20,9 +20,9 @@ enterprise Linux distribution.
 systemd-creds encrypt --name=vault-token - /etc/srvguard/vault-token.cred
 ```
 
-The credential is encrypted using the machine's TPM2 binding or, on machines
-without TPM2, a machine-specific key derived from `/var/lib/systemd/credential.secret`.
-The resulting `.cred` file is unreadable on any other machine.
+The credential is encrypted using TPM2 (if available) or a machine-specific
+secret stored in `/var/lib/systemd/credential.secret`. The resulting `.cred`
+file cannot be decrypted elsewhere unless that machine secret is also copied.
 
 **Delivery (automatic, at service start):**
 
@@ -34,44 +34,48 @@ LoadCredentialEncrypted=vault-token:/etc/srvguard/vault-token.cred
 
 systemd decrypts the credential before starting the service and places the
 plaintext in `$CREDENTIALS_DIRECTORY/<name>`. The directory is:
-- On a `tmpfs` mount (memory only, never hits disk)
+- On a `tmpfs` mount — memory-backed, not intentionally written to disk
+  (though kernel memory may still be captured in swap or hibernation images)
 - Owned by the service user
-- Mode `0500` — no other user or service can read it
-- Destroyed when the service stops
+- Mode `0500` — inaccessible to other unprivileged users and services
+- Removed when the service stops as part of systemd cleanup
 
 The service reads the secret from `$CREDENTIALS_DIRECTORY/vault-token`. By the
 time the service sees it, decryption is complete and the secret is in memory.
 
 ## Security Properties
 
 **Encrypted at rest:** the `.cred` file stored in `/etc/srvguard/` is
-ciphertext. Even full disk access does not yield the secret.
+ciphertext. Disk access alone does not reveal the secret unless the
+machine-specific key (`credential.secret` or TPM2) is also compromised.
 
-**Machine-bound:** the encryption key is derived from TPM2 or a machine secret
-that does not leave the host. The credential cannot be decrypted on another
-machine.
+**Machine-bound (with TPM2):** when TPM2 is available, the encryption key
+is hardware-bound and the credential cannot be decrypted on another machine.
+Without TPM2, the binding is only as strong as the protection of
+`/var/lib/systemd/credential.secret`.
 
 **Memory-only at runtime:** `$CREDENTIALS_DIRECTORY` lives in tmpfs. The
-plaintext secret is never written to any persistent storage during service
-execution.
+plaintext secret is not intentionally written to persistent storage during
+service execution, though it may appear in swap or hibernation images.
 
-**Service-scoped:** each service gets its own `$CREDENTIALS_DIRECTORY`. Other
-services on the same host cannot read another service's credentials — enforced
-by the kernel via mount namespaces and file permissions.
+**Service-scoped:** each service gets its own `$CREDENTIALS_DIRECTORY`.
+Other unprivileged services on the same host cannot read another service's
+credentials — enforced via mount namespaces and file permissions. Privileged
+processes (root) can bypass these controls.
 
 **No daemon process required:** unlike Vault Agent or similar, systemd
 credentials need no running sidecar. The service manager handles decryption as
 part of normal service startup.
 
 ## Comparison with Alternatives
 
-| Mechanism | Encrypted at rest | Memory-only runtime | Machine-bound | Service-scoped |
-|---|---|---|---|---|
-| systemd credential | ✓ | ✓ | ✓ | ✓ |
-| Environment variable | ✗ | ✗ | ✗ | ✗ |
-| File on disk | ✗ | ✗ | ✗ | ✗ |
-| Vault Agent | ✓ | Optional | ✗ | Optional |
-| Linux kernel keyring | N/A | ✓ | ✗ | ✓ (session) |
+| Mechanism            | Encrypted at rest | Memory-only runtime | Machine-bound    | Service-scoped        |
+|----------------------|-------------------|---------------------|------------------|-----------------------|
+| systemd credential   | ✓ (with Encrypted=) | ✓ (tmpfs)         | ✓ with TPM2      | ✓                     |
+| Environment variable | ✗                 | ✗                   | ✗                | ✗                     |
+| File on disk         | ✗                 | ✗                   | ✗                | ✗                     |
+| Vault Agent          | ✓                 | Optional            | ✗                | Optional              |
+| Linux kernel keyring | N/A               | ✓                   | ✗                | ✓ (per user/session)  |
 
 ## How srvguard Uses Them
 
@@ -81,34 +85,34 @@ uses the content as a pre-issued Vault token. No login HTTP call is made — the
 token is the credential.
 
 This means the Vault authentication step has no network round-trip: the token
-is already present in memory before srvguard starts. Vault sees an
-authenticated request for the secret; it does not need to validate a role or
-certificate.
+is already present in memory before srvguard starts. No authentication
+exchange is required — the token is pre-issued and Vault validates it
+directly on the first secret request.
 
 The typical deployment on a VM:
 
 ```
 operator                 systemd                  srvguard              Vault
    │                        │                        │                    │
-   │  systemd-creds encrypt  │                        │                    │
-   │  vault-token.cred       │                        │                    │
-   │────────────────────────►│                        │                    │
-   │                         │  service start         │                    │
-   │                         │  decrypt → tmpfs       │                    │
-   │                         │───────────────────────►│                    │
-   │                         │                        │  GET /v1/secret/.. │
-   │                         │                        │───────────────────►│
-   │                         │                        │◄───────────────────│
-   │                         │                        │  write to tmpfs    │
-   │                         │                        │  signal NGINX      │
+   │  systemd-creds encrypt │                        │                    │
+   │  vault-token.cred      │                        │                    │
+   │───────────────────────►│                        │                    │
+   │                        │  service start         │                    │
+   │                        │  decrypt → tmpfs       │                    │
+   │                        │───────────────────────►│                    │
+   │                        │                        │  GET /v1/secret/.. │
+   │                        │                        │───────────────────►│
+   │                        │                        │◄───────────────────│
+   │                        │                        │  write to tmpfs    │
+   │                        │                        │  signal NGINX      │
 ```
 
 ## Practical Notes
 
 - `systemd-creds` is in the `systemd` package — no additional install needed
 - Use `LoadCredentialEncrypted=` for secrets (TPM2/machine-bound encryption)
 - Use `LoadCredential=` for non-secret data that must just be injected
-- On containers: systemd is usually not PID 1; use the file-on-tmpfs approach
+- On containers: systemd is often not PID 1; use the file-on-tmpfs approach
   instead and let the host VM manage credentials for the container
 - Re-provisioning: encrypt a new token, replace the `.cred` file, restart the
   service — no host reboot required