howto/gitlab.md

@@ -65,13 +65,28 @@ notifications in cleartext for private issue](https://gitlab.com/gitlab-org/gitl
 issue.
 
 We have [deployed a workaround for this](https://gitlab.torproject.org/tpo/tpa/gitlab/-/issues/23) which redacts outgoing
-mail, but there's still some metadata leaking there:
+mail, by replacing the email's content with a notification that looks
+like:
+
+> A comment was added to a confidential issue and its content was
+> redacted from this email notification.
+
+If you have an OpenPGP key in the `account-keyring` repository and a
+`@torproject.org` email associated with your GitLab account, the
+contents will instead be encrypted to that key. See
+[tpo/tpa/gitlab#151](https://gitlab.torproject.org/tpo/tpa/gitlab/-/issues/151) for that work and [How do I update my OpenPGP
+key?](howto/ldap#how-do-i-update-my-openpgp-key)
+
+Note that there's still some metadata leaking there:
 
  * the issue number
  * the reporter
  * the project name
  * the reply token (allowing someone to impersonate a reply)
 
+This could be (partly) fixed by using "protected headers" for some of
+those headers.
+
 Some repositories might also have "web hooks" that notify IRC bots in
 clear text as well, although at the time of writing all projects are
 correctly configured. The IRC side of things, of course, might also
@@ -1783,22 +1798,22 @@ confidential_filter   unix  -       n       n       -       10      pipe
 program which does the following:
 
  1. parse the email
- 2. if it has a `X-GitLab-ConfidentialIssue: true` header, parse the
-    email to find the "signature" which links to the relevant GitLab
-    page
+ 2. if it does not have a `X-GitLab-ConfidentialIssue: true` header,
+    resend the email as is (this should never happen, but is still
+    present as a safety check)
+ 3. look for an encryption key for the user in `account-keyring` (and
+    possibly eventually, the GitLab API)
+ 4. if an encryption key is found, resend the message wrapped in
+    PGP/MIME encryption, if not, continue
+ 3. parse the email to find the "signature" which links to the
+    relevant GitLab page
  3. prepend a message to that signature
  4. replace the body of the original message with that redaction
  5. resend the message after changing the `X-GitLab-ConfidentialIssue`
     header to `redacted` to avoid loops
 
-Notes that if a filtered message does not have a
-`X-GitLab-ConfidentialIssue: true` header (which should never happen),
-it just resends the email as is, as a safety fallback.
-
-The canonical copy of the script is in our `tor-puppet.git`
-repository, in
-`modules/profile/files/gitlab/gitlab_confidential_filter.py`. A copy
-of the script from launch time is available [issue gitlab#23](https://gitlab.torproject.org/tpo/tpa/gitlab/-/issues/23#note_2951235).
+The canonical copy of the script is in our [fabric-tasks](https://gitlab.torproject.org/tpo/tpa/fabric-tasks)
+repository, in `gitlab_confidential_filter.py`.
 
 The filter also relies on other GitLab headers to find the original
 issue and synthesize a replacement body for the redaction.
@@ -1829,10 +1844,6 @@ redacted from this email notification.
 All of this is deployed by Puppet in the `profile::gitlab::app` class
 and some hacks buried in the `profile::postfix` class and its templates.
 
-An alternative would be to encrypt outgoing mails with PGP/MIME. Some
-software that could do this was considered in the Schleuder
-retirement, see [TPA-RFC-41](policy/tpa-rfc-41-schleuder-retirement#role-key-and-home-made-schleuder).
-
 Note that this doesn't work with [external participants](https://docs.gitlab.com/ee/user/project/service_desk/external_participants.html), which can
 be used to CC arbitrary email addresses that do not have a GitLab
 account. If such an email gets added, confidential contents *will*