Document what a signature is, vs. not

[SteveLasker]

In our weekly calls, the issue was raised that we're intermixing multiple ideas on what a signature could be, and what it represents.
Does a signature represent:

• where the artifact came from physically (what registry), or what entity (a company)
• a specific version of a product, or the company/product?

This issue is to track writing down the various thoughts and discussion points to help scope what we're hoping to cover with Notary v2.

[mtrmac]

My view:

• The idea of signatures implies untrusted registries are in the threat model; otherwise the registries involved in transporting the image could just be considered the source of truth, and the users ask for the truth just by pulling an image from one of them.
• It very much matters for security what exactly the image is, not just what company/product it came from. Today’s version is somewhat likely to be free of known vulnerabilities; a five-year-old-version might work similarly enough that consumers of the image won’t even notice the substitution, but it is extremely likely to contain well-known security bugs, and if those bugs are exposed to clients, they are also likely to be easy to exploit. So, if the user asks for $product:$version, the signatures must ensure they get $product:$version.
  • It is not strictly necessary for signatures-to-indicate-vendor to solve this problem, but if we have signatures to solve end-to-end trust in face of untrusted registries, it’s a natural place to solve the same kind of problem. We shouldn’t have signatures-for-vendors and signatures-for-versions that have to be managed separately and can get out of sync.
• It is infeasible to do this by using a different public key for every version of the product; one of the major benefits of public key cryptography is that trust only has to be established once. If the users had to do extra manual steps to obtain public keys for every new product version by asking the vendor, they could almost as well ask the vendor for the precise image digest and skip signatures altogether.
• The software verifying signatures does not inherently know what $product:$version the user wants to use; the user that decides on the $product:$version must indicate that somehow to the code pulling an image and deciding to use it.
  • It’s hard to introduce this as an extra element throughout all workflows that deal with images, and forcing the user to specify that in addition to the image name is extra UI burden that would be best avoided.
  • On the public Internet, the registry/repo:tag of the original vendor is already a very good $product:$version indication: the domain name of the registry provides a global non-conflicting namespace, and the repo:tag values typically already contain the $product:$version values. Most importantly, users are already providing this information when instructing software to pull/run an image, we don’t have to teach them anything new.
  • The difficulty with using registry/repo:tag arises with private mirrors, disconnected scenarios, and the like, as we’ve run into with Notary. But that’s due to an unstated assumption that the user-specified “image name” has to correspond to the physical location of the image which has to correspond to the name in the signature — and we can break the link either on the physical location vs. signed name side, or on the image name vs. physical location side.
• Hence, the suggested design is:
  • User-facing image names always contain the “original”, on-the-public-internet locations.
  • Given the user-specified image name, the system applies local policy to decide on what public keys are trusted etc.
  • Signatures include the same registry/repo:tag values as defined by the original vendor, and have to match the image name (or possibly, in more obscure cases, have to match some other name defined by the local policy).
  • Physical image location defaults to the image name, but is not generally the same; local configuration can define mirrors/redirections to where the image is physically to be found. (See https://github.com/containers/image/blob/master/docs/containers-registries.conf.5.md#remapping-and-mirroring-registries ).
• Properties of this design:
  • The “image names” used by users are deployment-location-independent; you can always say FROM registry.fedoraproject.org/fedora and it works everywhere. Systems running in a disconnected environment are administrator-configured (not developer-configured) to fetch those images from a local mirror.
  • Signatures validate the $product:$version information implicitly specified by the user, without any extra UI overhead and with minimal impact on K8s or other container management systems that already can work with image names.
  • Moving signed images across several repositories (CI-tested/manually-tested/staging/production) requires extra manual configuration because the enforced name match does not, by default, accept moving such signed images. (The design can’t automatically infer the difference between the difference between staging/production and $product1/$product2). But such configuration can be set up, once — either to accept the “production” name in ”staging” repositories, or possibly to turn off image name enforcement in signature matching altogether.

I believe this design removes much of the the name-dependent problems with using Notary in disconnected environments, without losing the Notary-provided image identity guarantees. (All of this is orthogonal to the Notary freshness guarantees; those have to be compromised to some extent in disconnected scenarios.)

[mtrmac]

In today’s call it’s been pointed out that the $product:$version information does not have to be a part of the signature, it can be inside the signed artifact (e.g. as a manifest or image config annotation, if something like that is supported by the artifact). That’s true, and mostly works well enough; one downside to this is the $version information is invisible to the signature software, so e.g. it seems hard in disconnected scenarios (where images can be mirrored independently of other images from the same server, taking their signatures “with them”) to maintain a $product:branch-v1 repository where the :branch-v1 tag is updated from time to time with v1.x.y updates, but signatures enforce (the way Notary v1 freshness guarantees do) that the client receives the latest image released for that tag.

[mtrmac]

… and of course, if the $product:$version information is not a part of the signature spec, we risk losing interoperability between artifact consumers; each implementation can define its own annotations and enforcement semantics.

[github-actions]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days.