# CNAB and Notary v2

### Introduction

[CNAB (Cloud Native Application Bundles)][cnab] is a _package format specification that describes a technology for bundling, installing, and managing distributed applications, that are by design, cloud agnostic._ Specifically, it uses container images to incapsulate installation logic and all runtime dependencies required to deploy a distributed application.

According to [version 1.0 of the CNAB Core specification][core1], a bundle consists of:
- a [bundle definition][bundle-json] that contains metadata, a list of components distributed as OCI images, parameters, credentials (or credential locations), or environment variables required to execute the bundle, and
- an [invocation image][invoc] - an OCI image that encapsulates all logic required for managing the application lifecycle (for example install, upgrade, delete).

Bundles have two canonical representations:

- a _thin_ bundle consists of just a bundle definition
- a _thick_ bundle consists of a packaged archive that contains both the bundle definition and an encoded representation of all of the invocation images and images, and is used in air-gapped environments, when access to network and/or a registry is not guaranteed.

In order for bundles to be usable, they have to be distributed. And since a bundle represents a collection of metadata and container images that are needed for an application, one way of distributing them is by using OCI registries - by representing a _thin_ bundle as an [OCI index][index] through [`cnab-to-oci`][cnab-to-oci], the implementation for distributing bundles through OCI registries.
([This][cto] article talks about the current state of the implementation, and [this][dist] article examines the requirements needed for distributing bundles with OCI registries).

> Image from [the blog post announcing the donation of `cnab-to-oci` to the CNAB community by Docker][cto].

### Securing the delivery of bundles between registries and clients

The [CNAB Security specification][sec-spec] proposes the use of TUF to ensure the authenticity and integrity of bundles distributed between registries and clients.
The specification does not prescribe or restrict the use of _a specific_ TUF implementation, but it does prescribe the way metadata should be stored in a TUF collection, and the [implementation][signy] uses the current Notary client libraries to push bundle metadata to a Notary server.

When pushing a bundle to an OCI registry, clients will:

- push images referenced in the bundle metadata to the OCI registry, as described in the image (and articles) above
- sign the content digest _of the bundle file itself_ and push the signature to Notary

$ sha256sum testdata/cnab/bundle.json
c7e92bd51f059d60b15ad456edf194648997d739f60799b37e08edafd88a81b5  testdata/cnab/bundle.json

$ signy 
    --tlscacert=$NOTARY_CA 
    --server https://localhost:4443 
    sign testdata/cnab/bundle.json localhost:5000/thin-bundle:v1
    
INFO[0000] Starting to copy image cnab/helloworld:0.1.1
INFO[0002] Completed image cnab/helloworld:0.1.1 copy
INFO[0002] Generated relocation map: relocation.ImageRelocationMap{"cnab/helloworld:0.1.1":"localhost:5000/thin-bundle@sha256:a59a4e74d9cc89e4e75dfb2cc7ea5c108e4236ba6231b53081a9e2506d1197b6"}
INFO[0002] Pushed successfully, with digest "sha256:b4936e42304c184bafc9b06dde9ea1f979129e09a021a8f40abc07f736de9268"
INFO[0000] Pushed trust data for localhost:5000/thin-bundle:v1: c7e92bd51f059d60b15ad456edf194648997d739f60799b37e08edafd88a81b5

$ signy 
    --tlscacert=$NOTARY_CA 
    --server https://localhost:4443 
    verify localhost:5000/thin-bundle:v1
    
INFO[0000] Pulled trust data for localhost:5000/thin-bundle:v1, with role targets - SHA256: c7e92bd51f059d60b15ad456edf194648997d739f60799b37e08edafd88a81b5
INFO[0000] Pulling bundle from registry: localhost:5000/thin-bundle:v1
INFO[0000] Computed SHA: c7e92bd51f059d60b15ad456edf194648997d739f60799b37e08edafd88a81b5
INFO[0000] The SHA sums are equal: c7e92bd51f059d60b15ad456edf194648997d739f60799b37e08edafd88a81b5

#### Why sign the content digest of the artifact and not the digest of the resulting manifest?

Users can choose to distribute bundles without OCI registries.
This means that the object we apply the signature to cannot be dependent on a a particular representation of that content - which is the case for the current signature model for OCI artifacts (signing the content digest of the _manifest_).

So the object we are signing is `bundle.json` - below is a subset of a `bundle.json` that describes two images used:

{
  "images": {
    "backend": {
      "contentDigest": "sha256:bca460afa270d4c527981ef9ca4989346c56cf9b20217dcea37df1ece8120686",
      "description": "backend component image",
      "image": "example.com/example/vote-backend@sha256:bca460afa270d4c527981ef9ca4989346c56cf9b20217dcea37df1ece8120686",
      "imageType": "docker"
    },
    "frontend": {
      "contentDigest": "sha256:aca460afa270d4c527981ef9ca4989346c56cf9b20217dcea37df1ece8120685",
      "description": "frontend component image",
      "image": "example.com/example/vote-frontend@sha256:aca460afa270d4c527981ef9ca4989346c56cf9b20217dcea37df1ece8120685",
      "imageType": "docker"
    }
  }
}

CNAB also defines a process for [_relocation_][rel] - where the bundle and all referenced images are moved from one registry to another.
This process can be performed by also maintaining any original bundle signature, with the requirement that the new registry yields the same content digest for the images referenced in the bundle.

#### Signing artifacts distributed _without_ OCI registries

There are scenarios where users want to distribute bundles without OCI registries - either because they have an existing method for distributing artifacts they want to reuse, or they want a _thick_ bundle representation they want to distribute in air-gapped environments.
In either case, they should be able to reuse the same signing model. Particularly, this generates the following requirements:

- a signature should be able to exist in Notary without a corresponding artifact in the registry
- registries do not garbage collect trust collections that do not have a corresponding artifact

### Bundle provenance and attestation

We currently use the `custom` field in a TUF collection to distribute in-toto metadata associated with a bundle, process derived from [this in-toto enhancement proposal for TUF interoperability][ite].

[cnab]: https://cnab.io/
[core1]: https://github.com/cnabio/cnab-spec/blob/master/100-CNAB.md
[bundle-json]: https://github.com/cnabio/cnab-spec/blob/master/101-bundle-json.md
[invoc]: https://github.com/cnabio/cnab-spec/blob/master/102-invocation-image.md
[dist]: https://deislabs.io/posts/state-of-cnab-part-2/
[index]: https://github.com/opencontainers/image-spec/blob/master/image-index.md
[cnab-to-oci]: https://github.com/cnabio/cnab-to-oci
[cto]: https://www.docker.com/blog/docker-donates-cnab-to-oci-library/
[sec-spec]: https://github.com/cnabio/cnab-spec/blob/master/300-CNAB-security.md
[signy]: https://github.com/cnabio/signy
[rel]: https://github.com/cnabio/cnab-spec/blob/master/103-bundle-runtime.md#image-relocation
[ite]: https://github.com/trishankatdatadog/ITE/blob/trishankatdatadog/ITE-2/ITE/2/README.adoc
------

## Requirements

CNAB Security needs to be able to support all of the following requirements:

1. **Support signatures for bundles in air-gapped environments.** That is, a signature for a bundle should continue to be valid when it is packaged as part of a thick bundle. The signature should be independent of the registry.
2. **Signatures for bundles should work across registries.** That is, a signature for a bundle hosted on one repository should work when both the signature and the bundle are moved to a different registry. As with the previous requirement, the signature should be independent of the registry.
3. **Simple key management for developers.** Developers should manage the least number of keys possible without sacricing significant security. Developers should also be able to reuse keys for different bundles.
4. **Simple key management for registries.** Registries should also be able to manage the least number of keys possible without sacrificing significant security. Registries should also be able to publish and revoke developer keys associated bundles, so that a CNAB bundle runtime can transparently verify bundles without using an out-of-band mechanism for establishing trust (e.g., [GPG web of trust](https://en.wikipedia.org/wiki/Web_of_trust)).
5. **Support using different registries with different roots of trust.** A CNAB bundle runtime should be able pin the root of trust for a registry. It should also be able to control exactly [which registries are trusted for which bundles](https://github.com/theupdateframework/taps/blob/master/tap4.md).
6. **Verify the provenance of a bundle.** A CNAB bundle runtime should be able to verify, if available, the provenance of a bundle, which is a series of cryptographic attestations about how the bundle was produced.

## Limitations

Unfortunately, Notary v1 has a few limitations that prevents CNAB Security from supporting the requirements listed above:

1. **Signatures are not alongside the registry.** While signatures can be manually downloaded and shipped alongside bundles, the current situation is not ideal, especially when moving bundles across registries.
2. **Signatures for bundles do not work across registries.** This is related to the previous limitation. Currently, signatures are tied to the domain name of the registry, which cause signatures to be invalidated when moving bundles across registries.
3. **Key management for developers is complicated.** Currently, developers have to manage a separate set of `root` and `targets` keys _per_ bundle (because there is a separate TUF metadata repository per bundle).
4. **Key management for registries is complicated.** Currently, registries have to manage a separate set of `timestamp` and `snapshot` keys _per_ bundle.
5. **Limited support for using different registries with different roots of trust.** Currently, there is a way to [pin the root of trust](https://docs.docker.com/engine/security/trust/content_trust/#runtime-enforcement-with-docker-content-trust#enabling-dct-within-the-docker-enterprise-engine) _per_ bundle, not an entire registry itself. Furthermore, there is no way to specify which registries are trusted for which bundles.
6. **No way to verify the provenance of a bundle.** Although Notary is based on TUF, it does not provide a way to integrate [in-toto](https://in-toto.io/) metadata to verify the provenance of a bundle.

<!--
## TBD

- Notary v2 SHOULD be compatible out-of-the-box with other popular implementations of TUF such as python-tuf and rust-tuf
- signature of bundle vs. individual artifacts
- just to make things more interesting, there will be higher-level workflows, just like bundles are higher-level to images, so workflows -> bundles -> images
-->

----

# Key management in TUF

There are five design principles for key management in TUF that we believe would be useful in a wide variety of use cases in Notary v2.

## Separation of duties


The first principle is the _separation of duties_, or using different sets of keys to sign different sets of metadata. The notion of a _role_, whether man or machine, is used to distinguish between different sets of keys. This ensures that a compromise of a set of keys belonging to any one role is generally insufficient to compromise the security of the entire system.

Notary v1 has already implemented this principle.

## Threshold signatures


The second principle is allowing for _threshold signatures_, or m out of n keys, to sign any piece of metadata. This is so that a compromise of less than m keys is insufficient to cause false metadata to be signed.

Notary v1 has already implemented this principle.

## Diversity of cryptographic algorithms


The third principle is allowing for using a diversity of cryptographic hashing and signing algorithms at the same time. This is so that a compromise of any signing or hashing algorithm is insufficient to cause false metadata to be trusted.

Notary v1 has _not_ implemented this principle. Signatures are limited to P-384, and hashes limited to SHA2-256.

## Built-in key revocation


The fourth principle is building key rotation and revocation into the system. Keys will inevitably be lost or somehow compromised (e.g., reverse-engineered or stolen), and so there needs to be a way to revoke these keys and replace them with new ones. There are two ways to revoke keys in TUF: _explicitly_ (using old keys to sign for new keys in new pieces of metadata) and _implicitly_ (setting expiration timestamps on pieces of metadata so that keys are not necessarily trusted indefinitely).

Notary v1 has already implemented this principle.

## Delegations: built-in decentralized key distribution


Last but not least, the fifth principle is not usually explicitly discussed, but is nevertheless crucial to the scaling of key distribution, rotation, and revocation in the system.

The use of _delegations_ is a powerful strategy that has successfully been used in a variety of contexts, including distributed systems, role-based access control, and software repositories. In the context of software repositories, delegations are specifically used to distribute permissions to sign packages across different administrators and developers. If A can sign a package K, then A can delegate this permission to B so that B can sign K on behalf of A. The delegation is an indirect package signature, where B "speaks for" A about K.

Consider the following example discussed in the [Diplomat](https://www.usenix.org/node/194973) paper. In the figure above, there is a "projects" role may sign packages because it is the root of trust for all packages. However, it has instead delegated the Django project (or the package path `Django-*`) to the public keys belonging to the developer Alice. Similarly, the Scapy project has been delegated to Sue. A delegation is simply a trusted map of which developer keys are responsible for signing which projects (or sets of packages). Based on this delegation, users would trust only Alice’s signature on a Django package. Developers can further delegate entrusted packages to other developers. In this case, Alice has delegated some packages (any package matching the path `Django-*.tar.gz`) to the developer Bob. Thus, Bob speaks for Alice for only the `Django-*.tar.gz` packages, whereas Alice’s signature on `Django-1.7.1.exe` (not shown) would be trusted instead of Bob’s.

Although Notary v1 has implemented _some_ notion of delegations, it has unfortunately _not_ implemented it in a way that matches the TUF semantics. Without going into technical details, the semantics of delegations in Notary v1 is not rich enough to capture the semantics of delegations in TUF which are needed for some security use cases, such as the one discussed above for CNAB.