Merge branch 'bye-apt-key' into 'main'

Stop using apt-key for verification and move apt-key to test/

See merge request apt-team/apt!406

5 files changed, 37 insertions, 271 deletions

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 493c36c08..2df0ce721 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -84,7 +84,6 @@ add_docbook(apt-man MANPAGE ALL
         apt-extracttemplates.1.xml
         apt-ftparchive.1.xml
         apt-get.8.xml
-        apt-key.8.xml
         apt-mark.8.xml
         apt_preferences.5.xml
         apt-patterns.7.xml
diff --git a/doc/apt-key.8.xml b/doc/apt-key.8.xml
deleted file mode 100644
index c6c2d192e..000000000
--- a/doc/apt-key.8.xml
+++ /dev/null
@@ -1,246 +0,0 @@
-<?xml version="1.0" encoding="utf-8" standalone="no"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
-<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
-<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
-]>
-
-<refentry>
- <refentryinfo>
-   &apt-author.jgunthorpe;
-   &apt-author.team;
-   &apt-email;
-   &apt-product;
-   <!-- The last update date -->
-   <date>2024-02-20T00:00:00Z</date>
- </refentryinfo>
-
- <refmeta>
-   <refentrytitle>apt-key</refentrytitle>
-   <manvolnum>8</manvolnum>
-   <refmiscinfo class="manual">APT</refmiscinfo>
- </refmeta>
- 
- <!-- Man page title -->
- <refnamediv>
-    <refname>apt-key</refname>
-    <refpurpose>Deprecated APT key management utility</refpurpose>
- </refnamediv>
-
- &synopsis-command-apt-key;
-
- <refsect1><title>Description</title>
-   <para>
-   <command>apt-key</command> is used to manage the list of keys used
-   by apt to authenticate packages.  Packages which have been
-   authenticated using these keys will be considered trusted.
-   </para>
-   <para>
-   Use of <command>apt-key</command> is deprecated, except for the use of
-   <command>apt-key del</command> in maintainer scripts to remove existing
-   keys from the main keyring.
-   If such usage of <command>apt-key</command> is desired the additional
-   installation of the GNU Privacy Guard suite (packaged in
-   <package>gnupg</package>) is required.
-   </para>
-   <para>
-   apt-key(8) will last be available in Debian 12 and Ubuntu 24.04.
-   </para>
-</refsect1>
-
-<refsect1><title>Supported keyring files</title>
-<para>apt-key supports only the binary OpenPGP format (also known as "GPG key
-   public ring") in files with the "<literal>gpg</literal>" extension, not
-   the keybox database format introduced in newer &gpg; versions as default
-   for keyring files. Binary keyring files intended to be used with any apt
-   version should therefore always be created with <command>gpg --export</command>.
-</para>
-<para>Alternatively, if all systems which should be using the created keyring
-   have at least apt version >= 1.4 installed, you can use the ASCII armored
-   format with the "<literal>asc</literal>" extension instead which can be
-   created with <command>gpg --armor --export</command>.
-</para>
-</refsect1>
-
-<refsect1><title>Commands</title>
-   <variablelist>
-     <varlistentry><term><option>add</option> <option>&synopsis-param-filename;</option>  (deprecated)</term>
-     <listitem>
-     <para>
-       Add a new key to the list of trusted keys.
-       The key is read from the filename given with the parameter
-       &synopsis-param-filename; or if the filename is <literal>-</literal>
-       from standard input.
-     </para>
-     <para>
-     It is critical that keys added manually via <command>apt-key</command> are
-     verified to belong to the owner of the repositories they claim to be for
-     otherwise the &apt-secure; infrastructure is completely undermined.
-     </para>
-     <para>
-       <emphasis>Note</emphasis>: Instead of using this command a keyring
-       should be placed directly in the <filename>/etc/apt/trusted.gpg.d/</filename>
-       directory with a descriptive name and either "<literal>gpg</literal>" or
-       "<literal>asc</literal>" as file extension.
-     </para>
-     </listitem>
-     </varlistentry>
-
-     <varlistentry><term><option>del</option> <option>&synopsis-param-keyid;</option>  (mostly deprecated)</term>
-     <listitem>
-     <para>
-
-       Remove a key from the list of trusted keys.
-
-     </para>
-
-     </listitem>
-     </varlistentry>
-
-     <varlistentry><term><option>export</option> <option>&synopsis-param-keyid;</option>  (deprecated)</term>
-     <listitem>
-     <para>
-
-        Output the key &synopsis-param-keyid; to standard output.
-
-     </para>
-
-     </listitem>
-     </varlistentry>
-
-     <varlistentry><term><option>exportall</option>  (deprecated)</term>
-     <listitem>
-     <para>
-
-        Output all trusted keys to standard output.
-
-     </para>
-
-     </listitem>
-     </varlistentry>
-
-     <varlistentry><term><option>list</option>, <option>finger</option>  (deprecated)</term>
-     <listitem>
-     <para>
-
-       List trusted keys with fingerprints.
-
-     </para>
-
-     </listitem>
-     </varlistentry>
-
-     <varlistentry><term><option>adv</option>  (deprecated)</term>
-     <listitem>
-     <para>
-     Pass advanced options to gpg. With <command>adv --recv-key</command> you
-     can e.g. download key from keyservers directly into the trusted set of
-     keys. Note that there are <emphasis>no</emphasis> checks performed, so it is
-     easy to completely undermine the &apt-secure; infrastructure if used without
-     care.
-     </para>
-
-     </listitem>
-     </varlistentry>
-
-     <varlistentry><term><option>update</option> (deprecated)</term>
-     <listitem>
-     <para>
-       Update the local keyring with the archive keyring and remove from
-       the local keyring the archive keys which are no longer valid.
-       The archive keyring is shipped in the <literal>archive-keyring</literal> package of your
-       distribution, e.g. the &keyring-package; package in &keyring-distro;.
-     </para>
-     <para>
-       Note that a distribution does not need to and in fact should not use
-       this command any longer and instead ship keyring files in the
-       <filename>/etc/apt/trusted.gpg.d/</filename> directory directly as this
-       avoids a dependency on <package>gnupg</package> and it is easier to manage
-       keys by simply adding and removing files for maintainers and users alike.
-     </para>
-     </listitem>
-     </varlistentry>
-     
-     <varlistentry><term><option>net-update</option>  (deprecated)</term>
-     <listitem>
-     <para>
-
-       Perform an update working similarly to the <command>update</command> command above,
-       but get the archive keyring from a URI instead and validate it against a master key.
-
-       This requires an installed &wget; and an APT build configured to have
-       a server to fetch from and a master keyring to validate.
-
-       APT in Debian does not support this command, relying on
-       <command>update</command> instead, but Ubuntu's APT does.
-
-     </para>
-
-     </listitem>
-     </varlistentry>
-   </variablelist>
-</refsect1>
-
- <refsect1><title>Options</title>
-<para>Note that options need to be defined before the commands described in the previous section.</para>
-   <variablelist>
-      <varlistentry><term><option>--keyring</option> <option>&synopsis-param-filename;</option>  (deprecated)</term>
-      <listitem><para>With this option it is possible to specify a particular keyring
-      file the command should operate on. The default is that a command is executed
-      on the <filename>trusted.gpg</filename> file as well as on all parts in the
-      <filename>trusted.gpg.d</filename> directory, though <filename>trusted.gpg</filename>
-      is the primary keyring which means that e.g. new keys are added to this one.
-      </para></listitem>
-      </varlistentry>
-   </variablelist>
- </refsect1>
-
- <refsect1><title>Deprecation</title>
-
-	 <para>Except for using <command>apt-key del</command> in maintainer scripts, the use of <command>apt-key</command> is deprecated. This section shows how to replace existing use of <command>apt-key</command>.</para>
-
-<para>If your existing use of <command>apt-key add</command> looks like this:</para>
-<para><literal>wget -qO- https://myrepo.example/myrepo.asc | sudo apt-key add -</literal></para>
-<para>Then you can directly replace this with (though note the recommendation below):</para>
-<para><literal>wget -qO- https://myrepo.example/myrepo.asc | sudo tee /etc/apt/trusted.gpg.d/myrepo.asc</literal></para>
-<para>Make sure to use the "<literal>asc</literal>" extension for ASCII armored
-keys and the "<literal>gpg</literal>" extension for the binary OpenPGP
-format (also known as "GPG key public ring"). The binary OpenPGP format works
-for all apt versions, while the ASCII armored format works for apt version >=
-1.4.</para>
-<para><emphasis>Recommended:</emphasis> Instead of placing keys into the <filename>/etc/apt/trusted.gpg.d</filename>
-directory, you can place them anywhere on your filesystem by using the
-<literal>Signed-By</literal> option in your <literal>sources.list</literal> and
-pointing to the filename of the key. See &sources-list; for details.
-Since APT 2.4, <filename>/etc/apt/keyrings</filename> is provided as the recommended
-location for keys not managed by packages.
-When using a deb822-style sources.list, and with apt version >= 2.4, the
-<literal>Signed-By</literal> option can also be used to include the full ASCII
-armored keyring directly in the <literal>sources.list</literal> without an
-additional file.
-</para>
-
- </refsect1>
-
-
- <refsect1><title>Files</title>
-   <variablelist>
-
-     &file-trustedgpg;
-
-   </variablelist>
-
-</refsect1>
-
-<refsect1><title>See Also</title>
-<para>
-&apt-get;, &apt-secure;
-</para>
-</refsect1>
-
- &manbugs;
- &manauthor;
-
-</refentry>
-
diff --git a/doc/apt-secure.8.xml b/doc/apt-secure.8.xml
index 7e40a2b1c..0549011e4 100644
--- a/doc/apt-secure.8.xml
+++ b/doc/apt-secure.8.xml
@@ -60,6 +60,40 @@
    and &synaptic; support this authentication feature, so this manpage uses
    <literal>APT</literal> to refer to them all for simplicity only.
    </para>
+ </refsect1>
+
+<refsect1><title>User Configuration</title>
+  <para>
+    Keys should usually be included inside their corresponding <literal>.sources</literal>
+    by embedding the ASCII-armored key in the <literal>Signed-By</literal> option.
+    To do so, replace the empty line with a dot, and then indent all lines by two spaces.
+    See &sources-list; for more information.
+  </para>
+
+  <para>
+    Alternatively, keys may be placed in <filename>/etc/apt/keyrings</filename> for local keys,
+    or <filename>/usr/share/keyrings</filename> for keys managed by packages, and then referenced
+    by <literal>Signed-By: /etc/apt/keyrings/example-archive-keyring.asc</literal> option in a <literal>.sources</literal>
+    file or using <literal>deb [signed-by=/etc/apt/keyrings/example-archive-keyring.asc] ...</literal> in the legacy
+    <literal>.list</literal> format. This may be useful for APT versions prior to 2.4, which do not
+    support embedded keys. ASCII-armored keys must use an extension of <literal>.asc</literal>, and
+    unarmored keys an extension of <literal>.gpg</literal>.
+  </para>
+
+  <para>
+    To generate keys suitable for use in APT using GnuPG, you will need to use the 
+    <command>gpg --export-options export-minimal [--armor] --export</command> command.
+    Earlier solutions involving <command>--keyring file --import</command> no longer work
+    with recent GnuPG versions as they use a new internal format ("GPG keybox database").
+  </para>
+
+  <para>
+    Note that a default installation already contains all keys to securely
+    acquire packages from the default repositories, so managing keys
+    is only needed if third-party repositories are added.
+    The <command>extrepo</command> package can be used to manage several
+    external repositories with ease.
+  </para>
 </refsect1>
 
  <refsect1><title>Unsigned Repositories</title>
@@ -180,26 +214,6 @@
    </para>
 </refsect1>
 
-<refsect1><title>User Configuration</title>
-   <para>
-   <command>apt-key</command> is the program that manages the list of keys used
-   by APT to trust repositories. It can be used to add or remove keys as well
-   as list the trusted keys. Limiting which key(s) are able to sign which archive
-   is possible via the <option>Signed-By</option> in &sources-list;.
-   </para><para>
-   Note that a default installation already contains all keys to securely
-   acquire packages from the default repositories, so fiddling with
-   <command>apt-key</command> is only needed if third-party repositories are
-   added.
-   </para><para>
-   In order to add a new key you need to first download it
-   (you should make sure you are using a trusted communication channel
-   when retrieving it), add it with <command>apt-key</command> and
-   then run <command>apt-get update</command> so that apt can download
-   and verify the <filename>InRelease</filename> or <filename>Release.gpg</filename>
-   files from the archives you have configured.
-   </para>
-</refsect1>
 
 <refsect1><title>Repository Configuration</title>
    <para>
@@ -243,7 +257,7 @@
 
 <refsect1><title>See Also</title> 
 <para> 
-&apt-conf;, &apt-get;, &sources-list;, &apt-key;, &apt-ftparchive;,
+&apt-conf;, &apt-get;, &sources-list;, &apt-ftparchive;,
 &debsign;, &debsig-verify;, &gpg;
 </para>
 
diff --git a/doc/po4a.conf b/doc/po4a.conf
index 0798eac68..3cf4d5ea8 100644
--- a/doc/po4a.conf
+++ b/doc/po4a.conf
@@ -15,7 +15,6 @@
 [type: manpage] apt.8.xml $lang:$lang/apt.$lang.8.xml add_$lang:xml.add
 [type: manpage] apt-get.8.xml $lang:$lang/apt-get.$lang.8.xml add_$lang:xml.add
 [type: manpage] apt-cache.8.xml $lang:$lang/apt-cache.$lang.8.xml add_$lang:xml.add
-[type: manpage] apt-key.8.xml $lang:$lang/apt-key.$lang.8.xml add_$lang:xml.add
 [type: manpage] apt-mark.8.xml $lang:$lang/apt-mark.$lang.8.xml add_$lang:xml.add
 [type: manpage] apt-secure.8.xml $lang:$lang/apt-secure.$lang.8.xml add_$lang:xml.add
 [type: manpage] apt-cdrom.8.xml $lang:$lang/apt-cdrom.$lang.8.xml add_$lang:xml.add
diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml
index 4fa7a245b..a463d4333 100644
--- a/doc/sources.list.5.xml
+++ b/doc/sources.list.5.xml
@@ -304,8 +304,8 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [.
 		and <filename>/etc/apt/keyrings</filename> for keyrings managed by the system operator.
 		If no keyring files are specified
 		the default is the <filename>trusted.gpg</filename> keyring and
-		all keyrings in the <filename>trusted.gpg.d/</filename> directory
-		(see <command>apt-key fingerprint</command>). If no fingerprint is
+		all keyrings in the <filename>trusted.gpg.d/</filename> directory.
+		If no fingerprint is
 		specified all keys in the keyrings are selected. A fingerprint will
 		accept also all signatures by a subkey of this key, if this isn't
 		desired an exclamation mark (<literal>!</literal>) can be appended to