Offering an alternative to the deprecated apt-key tool

[denis-roy]

Proposed changes

As of Debian 10 / Ubuntu 20.10, apt-key is deprecated and will not be available after Debian 11 / Ubuntu 22.04

Although adding keys directly to /etc/apt/trusted.gpg.d/ is suggested by apt-key deprecation message, as per Debian Wiki GPG keys for third party repositories should be added to /usr/share/keyrings and referenced with the signed-by option in the source.list.d entry.

With the proposed changes, verifying the key by fingerprint is unneeded and was removed.

Applicable versions

The proposed changes are targeted at Debian 9 (Stretch) / Ubuntu 16.04 (Xenial) and onward, which is corresponding to Docker's own requirements described in the respective OS requirements sections (Debian.md & Ubuntu.md)

Side note

Providing a binary .gpg key instead of the current ASCII Armored one might help shorten the lengthy command by removing the need for the | gpg --dearmor bit.

Related issues & PRs

• Closes Use trusted.gpg.d instead of apt-key #11625
• closes Apt-key is deprecated in 20.20 #11851
• closes Apt-Key is Depreciated #11915
• closes Don't use sudo with apt-key fingerprint command #10778
• closes Updating apt-key command for the Linux Installation Guide #10545
• closes Not truncating cryptographic fingerprint #10505
• closes apt-key fingerprint does not need sudo #10010
• closes ubuntu.md: minor update for apt-key usage #9373
• closes Update debian.md #11974
• closes [RFI] Adding the docker repo's GPG key to the system. #10347
• closes debian repository keys #8298
• closes why sudo the call to apt-key fingerprint? #8725
• closes Piping arbitrary input into apt-key add seems unsafe - why not use a command that may only add a single key, and only AFTER fingerprint is verified? #8341
• closes Simple setup does not work on Ubuntu 20.10 as described. #11776
• closes Fixes docker installation for Ubuntu #12313

[netlify]

Deploy preview for docsdocker ready!

Built with commit 2ddacb4

https://deploy-preview-11990--docsdocker.netlify.app

[m-tmatma]

@denis-roy

I tried the following commands on ubuntu 20.10 while referencing this PR.

sudo apt-get update  -y
sudo apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor | sudo tee /usr/share/keyrings/docker-ce-archive-keyring.gpg > /dev/null

sudo add-apt-repository \
   "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-ce-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

But add-apt-repository failed with the following error.

`Unable to handle repository shortcut 'deb [arch=amd64 signed-by=/usr/share/keyrings/docker-ce-archive-keyring.gpg] https://download.docker.com/linux/ubuntu    groovy    stable'

Did I make a mistake?

[denis-roy]

Did I make a mistake?

No @m-tmatma you did not. But I did and I'm sorry I did! :)

I clearly pasted from the wrong source since the intended change was to replace add-apt-repository by creating an entry in /etc/apt/source.list.d/ directly, as the latest commit reflects

Thank you for pointing it out! ✌️

[m-tmatma]

@denis-roy

it worked.

I used the following command on clean-installed ubuntu 20.10 of VMWARE 16 player.

sudo apt-get update && sudo apt-get upgrade -y
sudo apt install -y open-vm-tools-desktop

#!/bin/sh

sudo apt-get update

sudo apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor | sudo tee /usr/share/keyrings/docker-ce-archive-keyring.gpg > /dev/null
echo \
  "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-ce-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker-ce.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

$ docker --version
Docker version 20.10.1, build 831ebea

[m-tmatma]

@denis-roy

You can remove the installation of software-properties-common because you don't use add-apt-repository.

I re-confirmed these commands on clean-installed Ubuntu 20.10.

#!/bin/sh

sudo apt-get update

sudo apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor | sudo tee /usr/share/keyrings/docker-ce-archive-keyring.gpg > /dev/null
echo \
  "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-ce-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker-ce.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

[denis-roy]

You can remove the installation of software-properties-common because you don't use add-apt-repository.

@m-tmatma

True that! Changes made, thanks again :) ✌️

[usha-mandya]

@denis-roy Thanks for the PR.

@thaJeztah Could you PTAL?

[thaJeztah]

Thanks! Left a comment

Also would love @tianon to have a look at this 🤗

[MichaIng]

I should have searched for similar fixes, made one as well, which the aim first to remove add-apt-repository, which causes issues on Raspbian and probably other Debian-based distros, then replaced apt-key in that turn: #12331

Now things are doubled 😄. Good about this one is that it aligns the Ubuntu instructions as well.

What could be adopted here from my PR is:

• Using gpg -o /path/to/key.gpg argument to avoid another tee in the pipe.
• Replace gnupg-agent with gnupg. The first does not pull in the gpg command, which the seconds does. On Debian Buster and above, there is a gpg package, on Stretch it's a meta package for pulling in gnupg. However with Stretch backports enabled, apt-get install gpg tries to pull gpg from backports, with then missing backports dependencies. It's generally a good idea to pull the whole gnupg suite to assure that everything can deal with this keys.
• Write to key to /etc/apt/trusted.gpg.d/something.gpg to have it used by APT automatically and align with the way how current stable and testing Debian and Ubuntu handle it with their own keys.

The remaining changes in my PR are to reformat instructions so that Raspbian is supported with all methods. I propose that this PR here is merged first, and I can merge and resolve conflicts with mine afterwards.

[denis-roy]

@MichaIng - Thanks for your input

• Using gpg -o /path/to/key.gpg argument to avoid another tee in the pipe.

Definitely 👍

• Replace gnupg-agent with gnupg. The first does not pull in the gpg command, which the seconds does. On Debian Buster and above, there is a gpg package, on Stretch it's a meta package for pulling in gnupg. However with Stretch backports enabled, apt-get install gpg tries to pull gpg from backports, with then missing backports dependencies. It's generally a good idea to pull the whole gnupg suite to assure that everything can deal with this keys.

👍 here as well

• Write to key to /etc/apt/trusted.gpg.d/something.gpg to have it used by APT automatically and align with the way how current stable and testing Debian and Ubuntu handle it with their own keys.

Part of me agrees and the other part of me still want to leans towards Debian Wiki's /usr/share/keyrings suggestion which I have started to use and quite like so will leave this one up for @tianon & @thaJeztah to decide 🎲

Thanks again :)

[MichaIng]

TL;DR: While I find /etc/apt/trusted.gpg.d vs /usr(/local)/share/keyrings an interesting topic, since both ways work just fine, it's not something that must block this PR from being merged IMO 😉. It's perfectly fine as it is my end!

The Debian keyring package btw ships the keys in both directories: /var/lib/dpkg/info/debian-archive-keyring.conffiles
However, debhelper packaging adds all files in /etc automatically to conffiles:

# cat /var/lib/dpkg/info/debian-archive-keyring.conffiles
/etc/apt/trusted.gpg.d/debian-archive-buster-automatic.gpg
/etc/apt/trusted.gpg.d/debian-archive-buster-security-automatic.gpg
/etc/apt/trusted.gpg.d/debian-archive-buster-stable.gpg
/etc/apt/trusted.gpg.d/debian-archive-jessie-automatic.gpg
/etc/apt/trusted.gpg.d/debian-archive-jessie-security-automatic.gpg
/etc/apt/trusted.gpg.d/debian-archive-jessie-stable.gpg
/etc/apt/trusted.gpg.d/debian-archive-stretch-automatic.gpg
/etc/apt/trusted.gpg.d/debian-archive-stretch-security-automatic.gpg
/etc/apt/trusted.gpg.d/debian-archive-stretch-stable.gpg

This means that those are not automatically updated with the package, but only if the admin interactively decides so during package upgrade or uses the --force-confnew dpkg option. Also when any of those is removed, it stays removed with a package upgrade, unless --force-confmiss is used. Since these files are essential for the purpose of the package, it hence makes sense to keep the original keys in a separate directory where it's assured that they are restored and updated together with the package, which then is reasonable for all keyring DEB packages, when assuming that debhelper is used and that no package shall forcefully override by admin removed or edited files. For an installer script however, is not executed as part of "apt upgrade" but only manually by the admin, these arguments do not fully apply.

I found this wiki, which suggests to use trusted.gpg.d: https://wiki.debian.org/SecureApt#Basic_concepts
The Wiki page you linked above is newer and contrary states:

The key MUST NOT be placed in /etc/apt/trusted.gpg.d or loaded by apt-key add.
...
The reason we point to a file instead of a fingerprint is that the latter forces the user to add the key to the global SecureApt trust anchor in /etc/apt/trusted.gpg.d, which would cause the system to accept signatures from the third-party keyholder on all other repositories configured on the system that don't have a signed-by option (including the official Debian repositories).

On that argument: But no other configured repository is able to ship a signature that satisfies this key, otherwise the whole signing effort would all be nonsense 😄. And since Debian ships it's keyrings in trusted.gpg.d, the other way round, Debian signatures from Debian are accepted for all other repositories, so I don't see why this rule should apply for 3rd party repositories but not for Debian itself. If one does not trust a third party repository, it must not be added, that's it, and that's the same for the Debian repository. To me it looks like this Wiki page was written from a very single-sided perspective where Debian is trusted and 3rd party repositories are not trusted, but that is naturally not a trustable perspective.
Or do I oversee something?

Interesting topic definitely, especially since we (DietPi OS) are using /etc/apt/trusted.gpg.d for third party repositories currently, and I'm now considering to switch to /usr/local/share/keyrings or similar to satisfy Debian's rules according to this newer Wiki, if those those turn out to be reasonable 🤔.

[denis-roy]

Fixed by these commit:

• 11c3fb6
• 694aaad

[MichaIng]

Btw: gpg -o has the other benefit, that it does not create/overwrite the file with an empty file when it fails, but similarly to curl -o the output file is only created/overwritten when the command succeeds. Also without --yes, gpg will ask for verification if the file exists already, which is IMO a good safety measure as well.

[tianon]

LGTM

[thaJeztah]

Thank you! Sorry for the long delay; this one kept dropping down my list 😊 😓.

LGTM

[denis-roy]

Thank you to all who participated 👍

[doolio]

@denis-roy has these changes since been removed from the official docs? It seems so.

[denis-roy]

@doolio quite possible, I have not kept up since these changes were merged.

It's possible for you to look at the git history if you want some insight as to when and why it might have changed:

https://github.com/docker/docs/commits/main/content/engine/install/debian.md