[enhancement]: improve get gpg keyserver documentation in schema and examples

[dennisvang]

Enhancement

Background

Trying to install docker using apt config in cloud-init.

The docker docs get the gpg key directly from https://download.docker.com/linux/ubuntu/gpg.

I can get this to work in cloud-init (and multipass) by manually extracting the keyid from the actual key, for example using

wget -qO- https://download.docker.com/linux/ubuntu/gpg | gpg --with-fingerprint --with-colons

and doing the following:

apt:
  sources:
    docker:
      keyid: 9DC858229FC7DD38854AE2D88D81803C0EBFCD88
      keyserver: https://download.docker.com/linux/ubuntu/gpg
      source: deb [arch=amd64 signed-by=$KEY_FILE] https://download.docker.com/linux/ubuntu $RELEASE stable

Note this seems to work both with signed-by=$KEY_FILE and without.

Another option is just to download the key manually and include the raw value under apt.sources.docker.key.

However, both approaches require a manual step that is not so obvious, as may be apparent from the number of views and variety of responses to this so question.

Proposal

Would it not be possible to simply get the key directly from a url, in line with the docker docs?

For example, something like the following would make sense to me:

apt:
  sources:
    docker:
      key: https://download.docker.com/linux/ubuntu/gpg
      source: deb [arch=amd64] https://download.docker.com/linux/ubuntu $RELEASE stable

or, alternatively, using keyserver without the need for the keyid:

apt:
  sources:
    docker:
      keyserver: https://download.docker.com/linux/ubuntu/gpg
      source: deb [arch=amd64] https://download.docker.com/linux/ubuntu $RELEASE stable

Neither of those options seem to work presently.

Docs

On a related note: the cloud-init docs mention keyserver as an "alternate keyserver":

• keyid: a key to import via shortid or fingerprint.
• key: a raw PGP key.
• keyserver: alternate keyserver to pull keyid key from.

The word alternate implies there is also a default keyserver.

I assume it's this:

https://github.com/canonical/cloud-init/blob/c3e881f2c4f161b42c0afcb6efee3fbbe9de472a/cloudinit/config/cc_apt_configure.py#L58

Afaik this is only mentioned in some comments in the documentation examples, but it is not mentioned explicitly in the actual "apt configure" docs.

[blackboxsw]

Thank you for this feature request. While the two step approach to extraction of the known keyid from the known trusted source and injection of such a keyid directly into the apt:souces:docker:keyid feels tedious, those steps for expected keyid validation are there for security purposed to avoid MITM type attacks where a bad actor intercepts and signs malicious packages with a different keyid than what is expected during instance launch.

I also think keyservers typically will host mulitple keys, and APT needs to know which keyid it's expected to honor when configuring APT repos that it will allow.

Shouldn't the docker repo signing keyid remain fairly stable and be well known, so that the initial keyid extraction is unnecessary unless the project changes signing keys frequently?

Many thanks for clarifying any invalid assumptions I've made.

Per the comment about incorrect/invalid docs on keyserver keyserver: alternate keyserver to pull keyid key from. I see that as something we definitely should fix and should be a great first PR for documentation cleanup:

The fix would only need to update https://github.com/canonical/cloud-init/blob/main/cloudinit/config/schemas/schema-cloud-config-v1.json#L1132 and other key* descriptions to better represent a "default": "keyserver.ubuntu.com" and add more specific desriptions for each nested key under apt:sources. Changes can be tested locally with tox -e doc; xdg-open doc/rtd_html/reference/modules.html#apt-configure and expanding the schema tab to ensure content is properly rendered.

Adding documentation and good first issue to this bug if we consider it just a docs change and we are avoiding the addition of functionality to support url-only reads of keys from a known keyserver.

[dennisvang]

Thank you for this feature request. While the two step approach to extraction of the known keyid from the known trusted source and injection of such a keyid directly into the apt:souces:docker:keyid feels tedious, those steps for expected keyid validation are there for security purposed to avoid MITM type attacks where a bad actor intercepts and signs malicious packages with a different keyid than what is expected during instance launch.

I also think keyservers typically will host mulitple keys, and APT needs to know which keyid it's expected to honor when configuring APT repos that it will allow.

Shouldn't the docker repo signing keyid remain fairly stable and be well known, so that the initial keyid extraction is unnecessary unless the project changes signing keys frequently?

Thanks @blackboxsw, although I get your point, I think it does complicate things for people trying to follow the official docker installation instructions, which do tell us to get the key directly from a url:

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update