From 4a012436ce6a07dd435dca33b7ee2c41ea94c844 Mon Sep 17 00:00:00 2001
From: Johannes Schauer Marin Rodrigues <josch@mister-muffin.de>
Date: Wed, 29 Dec 2021 14:34:02 +0100
Subject: doc/apt-key.8.xml: document alternatives to apt-key add (closes:
 #1002820)

[jak@ Also document /etc/apt/keyrings]
---
 doc/apt-key.8.xml | 28 ++++++++++++++++++++++++++++
 doc/apt.ent       |  4 ++++
 2 files changed, 32 insertions(+)

(limited to 'doc')

diff --git a/doc/apt-key.8.xml b/doc/apt-key.8.xml
index eace6a02e..6167a7826 100644
--- a/doc/apt-key.8.xml
+++ b/doc/apt-key.8.xml
@@ -196,6 +196,34 @@
    </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:</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>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>
 
diff --git a/doc/apt.ent b/doc/apt.ent
index 6a3837b95..db4cb6f38 100644
--- a/doc/apt.ent
+++ b/doc/apt.ent
@@ -159,6 +159,10 @@
      be stored here (by other packages or the administrator).
      Configuration Item <literal>Dir::Etc::TrustedParts</literal>.</para></listitem>
      </varlistentry>
+     <varlistentry><term><filename>/etc/apt/keyrings/</filename></term>
+     <listitem><para>Place to store additional keyrings to be used with <literal>Signed-By</literal>.
+     </para></listitem>
+     </varlistentry>
 ">
 
 <!ENTITY file-extended_states "
-- 
cgit v1.2.3-70-g09d2