apt-key.8.xml 7.14 KB
Newer Older
1
<?xml version="1.0" encoding="utf-8" standalone="no"?>
2 3
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 5 6
<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
7 8 9
]>

<refentry>
10 11 12 13 14 15
 <refentryinfo>
   &apt-author.jgunthorpe;
   &apt-author.team;
   &apt-email;
   &apt-product;
   <!-- The last update date -->
Julian Andres Klode's avatar
Julian Andres Klode committed
16
   <date>2016-07-07T00:00:00Z</date>
17 18
 </refentryinfo>

19 20 21
 <refmeta>
   <refentrytitle>apt-key</refentrytitle>
   <manvolnum>8</manvolnum>
22
   <refmiscinfo class="manual">APT</refmiscinfo>
23 24 25 26 27 28 29 30
 </refmeta>
 
 <!-- Man page title -->
 <refnamediv>
    <refname>apt-key</refname>
    <refpurpose>APT key management utility</refpurpose>
 </refnamediv>

David Kalnischkies's avatar
David Kalnischkies committed
31
 &synopsis-command-apt-key;
32 33 34 35 36 37 38

 <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>
39 40 41
   <para>
   Note that if usage of <command>apt-key</command> is desired the additional
   installation of the GNU Privacy Guard suite (packaged in
42
   <package>gnupg</package>) is required. For this reason alone the programmatic
43 44 45 46 47
   usage (especially in package maintainerscripts!) is strongly discouraged.
   Further more the output format of all commands is undefined and can and does
   change whenever the underlying commands change. <command>apt-key</command> will
   try to detect such usage and generates warnings on stderr in these cases.
   </para>
48 49
</refsect1>

50 51 52 53 54 55 56 57 58 59 60 61 62 63
<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>

64 65
<refsect1><title>Commands</title>
   <variablelist>
66
     <varlistentry><term><option>add</option> <option>&synopsis-param-filename;</option></term>
67 68
     <listitem>
     <para>
David Kalnischkies's avatar
David Kalnischkies committed
69 70 71 72
       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.
73
     </para>
74 75 76 77 78
     <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>
79
     <para>
80 81 82 83
       <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.
84
     </para>
85 86 87
     </listitem>
     </varlistentry>

88
     <varlistentry><term><option>del</option> <option>&synopsis-param-keyid;</option></term>
89 90 91 92 93 94 95 96 97 98
     <listitem>
     <para>

       Remove a key from the list of trusted keys.

     </para>

     </listitem>
     </varlistentry>

99
     <varlistentry><term><option>export</option> <option>&synopsis-param-keyid;</option></term>
100 101 102
     <listitem>
     <para>

David Kalnischkies's avatar
David Kalnischkies committed
103
        Output the key &synopsis-param-keyid; to standard output.
104 105 106 107 108 109

     </para>

     </listitem>
     </varlistentry>

110
     <varlistentry><term><option>exportall</option></term>
111 112 113 114 115 116 117 118 119 120
     <listitem>
     <para>

        Output all trusted keys to standard output.

     </para>

     </listitem>
     </varlistentry>

121
     <varlistentry><term><option>list</option>, <option>finger</option></term>
122 123 124
     <listitem>
     <para>

125
       List trusted keys with fingerprints.
126

127 128
     </para>

129 130 131
     </listitem>
     </varlistentry>

132
     <varlistentry><term><option>adv</option></term>
133 134
     <listitem>
     <para>
135 136 137 138 139
     Pass advanced options to gpg. With <command>adv --recv-key</command> you
     can e.g. download key from keyservers directly into the 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.
140 141
     </para>

142 143
     </listitem>
     </varlistentry>
144

145
     <varlistentry><term><option>update</option> (deprecated)</term>
146 147
     <listitem>
     <para>
Michael Vogt's avatar
Michael Vogt committed
148 149 150
       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
151
       distribution, e.g. the &keyring-package; package in &keyring-distro;.
152
     </para>
153 154 155
     <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
156
       <filename>/etc/apt/trusted.gpg.d/</filename> directory directly as this
157 158 159
       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>
160 161
     </listitem>
     </varlistentry>
162
     
163
     <varlistentry><term><option>net-update</option></term>
164 165 166
     <listitem>
     <para>

Justin B Rye's avatar
Justin B Rye committed
167 168
       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.
Michael Vogt's avatar
Michael Vogt committed
169 170 171 172

       This requires an installed &wget; and an APT build configured to have
       a server to fetch from and a master keyring to validate.

Justin B Rye's avatar
Justin B Rye committed
173
       APT in Debian does not support this command, relying on
Michael Vogt's avatar
Michael Vogt committed
174
       <command>update</command> instead, but Ubuntu's APT does.
175 176 177 178 179

     </para>

     </listitem>
     </varlistentry>
180 181 182
   </variablelist>
</refsect1>

183 184 185
 <refsect1><title>Options</title>
<para>Note that options need to be defined before the commands described in the previous section.</para>
   <variablelist>
186
      <varlistentry><term><option>--keyring</option> <option>&synopsis-param-filename;</option></term>
Justin B Rye's avatar
Justin B Rye committed
187
      <listitem><para>With this option it is possible to specify a particular keyring
188 189
      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
190
      <filename>trusted.gpg.d</filename> directory, though <filename>trusted.gpg</filename>
191 192 193 194 195 196
      is the primary keyring which means that e.g. new keys are added to this one.
      </para></listitem>
      </varlistentry>
   </variablelist>
 </refsect1>

197 198
 <refsect1><title>Files</title>
   <variablelist>
199 200

     &file-trustedgpg;
201

202
   </variablelist>
203

204 205
</refsect1>

206 207 208 209 210
<refsect1><title>See Also</title>
<para>
&apt-get;, &apt-secure;
</para>
</refsect1>
211 212 213 214 215 216

 &manbugs;
 &manauthor;

</refentry>