service/static-shim.md

@@ -241,6 +241,39 @@ how is this thing built, basically? -->
 
 TODO: design still in flux, see "alternatives considered" below.
 
+### Authentication
+
+The shim assumes that GitLab projects host a private SSH key and can
+access the shim server over SSH with it. Access is granted, by Puppet
+(`tor-puppet.git` repository, `hiera/common.yaml` file, in the
+`staticsync::gitlab_shim::ssh::sites` hash) only to a specific
+site. The restriction occurs in the `authorized_keys` file, with
+`restrict` and `command=` options. The latter restricts the public key
+to only a *specific* site update, with a wrapper that will call
+`static-update-component` on the right component or `rrsync` which is
+`rsync` but limited to a specific directory. We also allow connections
+only from GitLab over SSH.
+
+The public part of that key should be set in the GitLab project, as a
+File variable called `STATIC_GITLAB_SHIM_SSH_PRIVATE_KEY`. This way
+the GitLab runners get access to the private key and can deploy those
+changes.
+
+The impact of this is that a compromise on GitLab or GitLab CI can
+compromise all web sites managed by GitLab CI. While we do restrict
+what individual keys can do, a total compromise of GitLab could, in
+theory, leak all those private keys and therefore defeat those
+mechanisms.
+
+The GitLab runners, in turn, authenticate the SSH server through a
+[instance-level CI/CD variable](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-an-instance) called
+`STATIC_GITLAB_SHIM_SSH_HOST_KEYS` which declares the public SSH host
+keys for the server. Those need to be updated if the server is
+re-deployed, which is unfortunate. An alternative might be to sign
+public keys with an SSH CA (e.g. [this guide](https://blog.liw.fi/posts/2021/09/28/sshca/)) but then the CA
+would also need to be present, so it's unclear that would be a
+benefit.
+
 ## Issues
 
 There is no issue tracker specifically for this project, [File][] or