Why does the apt-key man page advise against using its add command?

Those projects have outdated instructions. I know this because I publish a Debian repository and I updated my instructions when I found out about the changes in Debian 9 APT. Indeed, this part of the manual is now out of date, as it is the wrong directory.

This is not really to do with .d directories and more to do with preventing a cross-site vulnerability in APT. The older system used separate keyring files for convenience, but this is now a necessity for security; your security.

This is the vulnerability. Consider two repository publishers, A and B. In the world of Debian 8 and before, both publishers' keys went in the single global keyring on users' machines. If publisher A could somehow arrange to supplant the repository WWW site of publisher B, then A could publish subversive packages, signed with A's own key, which APT would happily accept and install. A's key is, after all, trusted globally for all repositories.

The mitigation is for users to use separate keyrings for individual publishers, and to reference those keyrings with individual Signed-By settings in their repository definitions. Specifically, publisher A's key is only used in the Signed-By of repository A and publisher B's key is only used in the Signed-By of repository B. This way, if publisher A supplants publisher B's repository, APT will not accept the subversive packages from it since they and the repository are signed by publisher A's key not by publisher B's.

The /etc/apt/trusted.gpg.d mechanism at hand is an older Poor Man's somewhat flawed halfway house towards this, from back in 2005 or so, that is not quite good enough. It sets up the keyring in a separate file, so that it can be packaged up and just installed in one step by a package manager (or downloaded with fetch/curl/wget) as any other file. (The package manager handles preventing publisher A's special this-is-my-repository-keyring package from installing over publisher B's, in the normal way that it handles file conflicts between packages in general.) But it still adds it to the set of keys that is globally trusted for all repositories. The full mechanism that exists now uses separate, not globally trusted, keyring files in /usr/share/keyrings/.

My instructions are already there. ☺ There are moves afoot to move Debian's own repositories to this mechanism, so that they no longer use globally trusted keys either. You might want to have a word with those "most projects" that you found. After all, they are currently instructing you to hand over global access to APT on your machine to them.

Further reading

• Daniel Kahn Gillmor (2017-05-02). Please ship release-specific keys separately outside of /etc/apt/trusted.gpg.d/. Debian bug #861695.
• Daniel Kahn Gillmor (2017-07-27). debian sources.list entries should have signed-by options pointing to specific keys. Debian bug #877012.
• "Sources.list entry". Instructions to connect to a third-party repository. Debian wiki. 2018.
• Why isn't it a security risk to add to sources.list?
• Debian 9, APT, and "GPG error: ... InRelease: The following signatures were invalid:"