doc/apt-key.8.xml

   1 <?xml version="1.0" encoding="utf-8" standalone="no"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4 <!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
   5 <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
   6 <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
   7 ]>
   8
   9 <refentry>
  10  <refentryinfo>
  11    &apt-author.jgunthorpe;
  12    &apt-author.team;
  13    &apt-email;
  14    &apt-product;
  15    <!-- The last update date -->
  16    <date>2016-11-25T00:00:00Z</date>
  17  </refentryinfo>
  18
  19  <refmeta>
  20    <refentrytitle>apt-key</refentrytitle>
  21    <manvolnum>8</manvolnum>
  22    <refmiscinfo class="manual">APT</refmiscinfo>
  23  </refmeta>
  24
  25  <!-- Man page title -->
  26  <refnamediv>
  27     <refname>apt-key</refname>
  28     <refpurpose>APT key management utility</refpurpose>
  29  </refnamediv>
  30
  31  &synopsis-command-apt-key;
  32
  33  <refsect1><title>Description</title>
  34    <para>
  35    <command>apt-key</command> is used to manage the list of keys used
  36    by apt to authenticate packages.  Packages which have been
  37    authenticated using these keys will be considered trusted.
  38    </para>
  39    <para>
  40    Note that if usage of <command>apt-key</command> is desired the additional
  41    installation of the GNU Privacy Guard suite (packaged in
  42    <package>gnupg</package>) is required. For this reason alone the programmatic
  43    usage (especially in package maintainerscripts!) is strongly discouraged.
  44    Further more the output format of all commands is undefined and can and does
  45    change whenever the underlying commands change. <command>apt-key</command> will
  46    try to detect such usage and generates warnings on stderr in these cases.
  47    </para>
  48 </refsect1>
  49
  50 <refsect1><title>Supported keyring files</title>
  51 <para>apt-key supports only the binary OpenPGP format (also known as "GPG key
  52    public ring") in files with the "<literal>gpg</literal>" extension, not
  53    the keybox database format introduced in newer &gpg; versions as default
  54    for keyring files. Binary keyring files intended to be used with any apt
  55    version should therefore always be created with <command>gpg --export</command>.
  56 </para>
  57 <para>Alternatively, if all systems which should be using the created keyring
  58    have at least apt version >= 1.4 installed, you can use the ASCII armored
  59    format with the "<literal>asc</literal>" extension instead which can be
  60    created with <command>gpg --armor --export</command>.
  61 </para>
  62 </refsect1>
  63
  64 <refsect1><title>Commands</title>
  65    <variablelist>
  66      <varlistentry><term><option>add</option> <option>&synopsis-param-filename;</option></term>
  67      <listitem>
  68      <para>
  69        Add a new key to the list of trusted keys.
  70        The key is read from the filename given with the parameter
  71        &synopsis-param-filename; or if the filename is <literal>-</literal>
  72        from standard input.
  73      </para>
  74      <para>
  75      It is critical that keys added manually via <command>apt-key</command> are
  76      verified to belong to the owner of the repositories they claim to be for
  77      otherwise the &apt-secure; infrastructure is completely undermined.
  78      </para>
  79      <para>
  80        <emphasis>Note</emphasis>: Instead of using this command a keyring
  81        should be placed directly in the <filename>/etc/apt/trusted.gpg.d/</filename>
  82        directory with a descriptive name and either "<literal>gpg</literal>" or
  83        "<literal>asc</literal>" as file extension.
  84      </para>
  85      </listitem>
  86      </varlistentry>
  87
  88      <varlistentry><term><option>del</option> <option>&synopsis-param-keyid;</option></term>
  89      <listitem>
  90      <para>
  91
  92        Remove a key from the list of trusted keys.
  93
  94      </para>
  95
  96      </listitem>
  97      </varlistentry>
  98
  99      <varlistentry><term><option>export</option> <option>&synopsis-param-keyid;</option></term>
 100      <listitem>
 101      <para>
 102
 103         Output the key &synopsis-param-keyid; to standard output.
 104
 105      </para>
 106
 107      </listitem>
 108      </varlistentry>
 109
 110      <varlistentry><term><option>exportall</option></term>
 111      <listitem>
 112      <para>
 113
 114         Output all trusted keys to standard output.
 115
 116      </para>
 117
 118      </listitem>
 119      </varlistentry>
 120
 121      <varlistentry><term><option>list</option>, <option>finger</option></term>
 122      <listitem>
 123      <para>
 124
 125        List trusted keys with fingerprints.
 126
 127      </para>
 128
 129      </listitem>
 130      </varlistentry>
 131
 132      <varlistentry><term><option>adv</option></term>
 133      <listitem>
 134      <para>
 135      Pass advanced options to gpg. With <command>adv --recv-key</command> you
 136      can e.g. download key from keyservers directly into the the trusted set of
 137      keys. Note that there are <emphasis>no</emphasis> checks performed, so it is
 138      easy to completely undermine the &apt-secure; infrastructure if used without
 139      care.
 140      </para>
 141
 142      </listitem>
 143      </varlistentry>
 144
 145      <varlistentry><term><option>update</option> (deprecated)</term>
 146      <listitem>
 147      <para>
 148        Update the local keyring with the archive keyring and remove from
 149        the local keyring the archive keys which are no longer valid.
 150        The archive keyring is shipped in the <literal>archive-keyring</literal> package of your
 151        distribution, e.g. the &keyring-package; package in &keyring-distro;.
 152      </para>
 153      <para>
 154        Note that a distribution does not need to and in fact should not use
 155        this command any longer and instead ship keyring files in the
 156        <filename>/etc/apt/trusted.gpg.d/</filename> directory directly as this
 157        avoids a dependency on <package>gnupg</package> and it is easier to manage
 158        keys by simply adding and removing files for maintainers and users alike.
 159      </para>
 160      </listitem>
 161      </varlistentry>
 162
 163      <varlistentry><term><option>net-update</option></term>
 164      <listitem>
 165      <para>
 166
 167        Perform an update working similarly to the <command>update</command> command above,
 168        but get the archive keyring from a URI instead and validate it against a master key.
 169
 170        This requires an installed &wget; and an APT build configured to have
 171        a server to fetch from and a master keyring to validate.
 172
 173        APT in Debian does not support this command, relying on
 174        <command>update</command> instead, but Ubuntu's APT does.
 175
 176      </para>
 177
 178      </listitem>
 179      </varlistentry>
 180    </variablelist>
 181 </refsect1>
 182
 183  <refsect1><title>Options</title>
 184 <para>Note that options need to be defined before the commands described in the previous section.</para>
 185    <variablelist>
 186       <varlistentry><term><option>--keyring</option> <option>&synopsis-param-filename;</option></term>
 187       <listitem><para>With this option it is possible to specify a particular keyring
 188       file the command should operate on. The default is that a command is executed
 189       on the <filename>trusted.gpg</filename> file as well as on all parts in the
 190       <filename>trusted.gpg.d</filename> directory, though <filename>trusted.gpg</filename>
 191       is the primary keyring which means that e.g. new keys are added to this one.
 192       </para></listitem>
 193       </varlistentry>
 194    </variablelist>
 195  </refsect1>
 196
 197  <refsect1><title>Files</title>
 198    <variablelist>
 199
 200      &file-trustedgpg;
 201
 202    </variablelist>
 203
 204 </refsect1>
 205
 206 <refsect1><title>See Also</title>
 207 <para>
 208 &apt-get;, &apt-secure;
 209 </para>
 210 </refsect1>
 211
 212  &manbugs;
 213  &manauthor;
 214
 215 </refentry>
 216