- add a terminology section

- make the TPA OpenPGP policy file path in the server explicit

- make the Git config path in the server explicit

- link to the profile::openpgp_policy class

- change subsection name from "Policy updates" to "Certificatge updates"
  to better match what's explained there

- explain how to fetch up-to-date certificates before updating the
  OpenPGP policy file, and not some caveats of doing it differently

refs #42099

howto/git.md

@@ -23,6 +23,13 @@ certificates and permissions stored in a centralized OpenPGP policy file. See
 
 [TPA-RFC-90: Signed commits]: policy/tpa-rfc-90-signed-commits
 
+### Terminology
+
+Throughout this section, we use the term "certificate" to refer to OpenPGP
+Transferable Public Keys (see [section 11.1 of RFC 4880][]).
+
+[section 11.1 of RFC 4880]: https://www.rfc-editor.org/rfc/rfc4880#section-11.1
+
 ### `sequoia-git` basics
 
 In order to authenticate changes in a Git repository, `sequoia-git` uses two
@@ -83,34 +90,52 @@ updates.
 
 Puppet deploys in the Puppet server:
 
-  - the TPA OpenPGP policy file ([`openpgp-policy.toml`][]),
+  - the TPA OpenPGP policy file ([`openpgp-policy.toml`][]) to
+    `/etc/openpgp-policy/policies/tpa.toml`,
   - global Git configuration containing per-repo policy file and trust-root
-    configs, and
-  - Git update-hooks in the [Puppet repositories][] that only allow ref updates
+    configs to `/etc/openpgp-policy/gitoconfig/`, and
+  - Git update-hooks to the [Puppet repositories][] that only allow ref updates
     if authentication is valid
 
 [`openpgp-policy.toml`]: https://gitlab.torproject.org/tpo/tpa/puppet-control/-/blob/production/openpgp-policy.toml
 
+See the [`profile::openpgp_policy`][] Puppet profile for the implementation.
+
+[`profile::openpgp_policy`]: https://gitlab.torproject.org/tpo/tpa/puppet-control/-/blob/production/site/profile/manifests/openpgp_policy.pp
+
 With this, ref updates in the Puppet Git repos are only performed if all
 commits since the trust-root are signed with authorized certificates contained
-in the TPA OpenPGP policy file.
+in the installed TPA OpenPGP policy file.
+
+### Certificate updates
 
-### Policy updates
+While a certificate is still valid and has the [`sign_commit`][] capability,
+it's allowed to update any certificate contained in the `openpgp-policy.toml`
+file.
 
-During bootstrap of this mechanism, the TPA OpenPGP policy file was first
-deployed to the Puppet server. This way, all changes are checked against the
-policy file that is already installed in `/etc/openpgp-policy` in the server.
-While a certificate is still valid, it should then be able to push any change
-to the server, which includes the ability to perform updates of the
-`openpgp-policy.toml` file itself.
+[`sign_commit`]: https://sequoia-pgp.gitlab.io/sequoia-git/specification/#section-4.2
 
-To update certificates, make sure you have up-to-date versions in your local
-store and run:
+To update one or more certificates, first make sure you have up-to-date
+versions in your local store. One way to do that is by using `sq` to import the
+certificate from [Tor's Web Key Directory][]:
+
+```
+sq network wkd search <ADDRESS>
+```
+
+[Tor's Web Key Directory]: https://gitlab.torproject.org/tpo/tpa/team/-/wikis/howto/Web-Key-Directory-%5Bwkd%5D---How-keys-are-managed-in-Tor
+
+Then use `sq-git` to update the OpenPGP policy file with certificates from your
+local store:
 
 ```
 sq-git policy sync --disable-keyservers
 ```
 
+Note that, if you don't use `--disable-keyservers`, expired subkeys may end up
+being included by a sync, and you may think that there are updates to the key
+when there really aren't. So it's better to just do as suggested above.
+
 You can also edit the `openpgp-policy.toml` file manually and perform the
 needed changes.