X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/36b8ebbb4a5db4909c3cf739d8ea472f70703662..70aa55819c08ec979f50400d159daadbfb5c7f54:/doc/apt-key.8.xml?ds=sidebyside diff --git a/doc/apt-key.8.xml b/doc/apt-key.8.xml index 9bfab84b6..eacd18d4d 100644 --- a/doc/apt-key.8.xml +++ b/doc/apt-key.8.xml @@ -1,18 +1,21 @@ - -%aptent; - - -%aptverbatiment; - + %aptent; + %aptverbatiment; + %aptvendor; ]> - &apt-docinfo; - + + &apt-author.jgunthorpe; + &apt-author.team; + &apt-email; + &apt-product; + + 2016-11-25T00:00:00Z + + apt-key 8 @@ -25,15 +28,7 @@ APT key management utility - - - - apt-key - - command - - - + &synopsis-command-apt-key; Description @@ -41,23 +36,56 @@ by apt to authenticate packages. Packages which have been authenticated using these keys will be considered trusted. + + Note that if usage of apt-key is desired the additional + installation of the GNU Privacy Guard suite (packaged in + gnupg) is required. For this reason alone the programmatic + 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. apt-key will + try to detect such usage and generates warnings on stderr in these cases. + + + +Supported keyring files +apt-key supports only the binary OpenPGP format (also known as "GPG key + public ring") in files with the "gpg" 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 gpg --export. + +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 "asc" extension instead which can be + created with gpg --armor --export. + Commands - add filename + - - Add a new key to the list of trusted keys. The key is read - from filename, or standard input if - filename is -. + 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 - + from standard input. + + + It is critical that keys added manually via apt-key are + verified to belong to the owner of the repositories they claim to be for + otherwise the &apt-secure; infrastructure is completely undermined. + + + Note: Instead of using this command a keyring + should be placed directly in the /etc/apt/trusted.gpg.d/ + directory with a descriptive name and either "gpg" or + "asc" as file extension. - - del keyid + @@ -68,18 +96,18 @@ - export keyid + - Output the key keyid to standard output. + Output the key &synopsis-param-keyid; to standard output. - exportall + @@ -90,63 +118,60 @@ - list + , - List trusted keys. + List trusted keys with fingerprints. - - finger - - - - List fingerprints of trusted keys. - - - - - - adv + - - Pass advanced options to gpg. With adv --recv-key you can download the - public key. - + Pass advanced options to gpg. With adv --recv-key you + can e.g. download key from keyservers directly into the the trusted set of + keys. Note that there are no checks performed, so it is + easy to completely undermine the &apt-secure; infrastructure if used without + care. - update + (deprecated) - - Update the local keyring with the keyring of Debian archive - keys and removes from the keyring the archive keys which are no - longer valid. - + 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 archive-keyring package of your + distribution, e.g. the &keyring-package; package in &keyring-distro;. + + + 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 + /etc/apt/trusted.gpg.d/ directory directly as this + avoids a dependency on gnupg and it is easier to manage + keys by simply adding and removing files for maintainers and users alike. - - net-update + - Update the local keyring with the keys of a key server - and removes from the keyring the archive keys which are no - longer valid. This requires an installed wget and an APT - build configured to have a server to fetch from. APT in - Debian does not support this command, but Ubuntu's APT - does. + Perform an update working similarly to the update 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 + update instead, but Ubuntu's APT does. @@ -158,11 +183,11 @@ Options Note that options need to be defined before the commands described in the previous section. - --keyring filename - With this option it is possible to specify a specific keyring + + 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 trusted.gpg file as well as on all parts in the - trusted.gpg.d directory, through trusted.gpg + trusted.gpg.d directory, though trusted.gpg is the primary keyring which means that e.g. new keys are added to this one. @@ -174,18 +199,6 @@ &file-trustedgpg; - /etc/apt/trustdb.gpg - Local trust database of archive keys. - - - /usr/share/keyrings/debian-archive-keyring.gpg - Keyring of Debian archive trusted keys. - - - /usr/share/keyrings/debian-archive-removed-keys.gpg - Keyring of Debian archive removed trusted keys. - -