cnabio · radu-matei · May 19, 2020 · Oct 22, 2019
diff --git a/304-known-implementations.md b/304-known-implementations.md
@@ -0,0 +1,123 @@
+---
+title: CNAB Security: Known implementations
+weight: 304
+---
+
+The security implementation prescribes the structure and format that trust metadata SHOULD follow, but _not_ which specific implementations should be used. This document presents known implementations of the CNAB security specification, and as more projects implement the specification, they will be added here.
+
+### [Signy][signy]
+
+[Signy][signy] is a project built to validate the feasability of integrating the [CNAB registry][cnab-reg] and CNAB security specifications by demonstrating the complete sign-push-verify workflow.
+
+The current document is based on [v0.0.3][signy-release] of Signy, which:
+
+- uses the [Notary][notary] client libraries, and communicates with a Notary server.
+- uses an [in-toto Go client][in-toto-golang] to perform structural verification for the in-toto layouts.
+- performs all in-toto verifications in a container based on a _verification image_ - this ensures the desired dependencies and their versions are available for all clients running the in-toto verifications, regardless of the operating system they are running. See [this project][in-toto-container] for an example of how verification images are used.
+- for thin CNAB bundles, signing will push the bundle to a compliant OCI registry, and verifying will pull the bundle from an OCI registry (the push and pull operations are performed using [`cnabio/cnab-to-oci`][cnab-to-oci]).
+- for thick CNAB bundles, Signy will pull the trust metadata from Notary, and will compare it against the content digest of a local file.
+
+> [Notary][notary] is an opinionated implementation of the TUF specification written in Go, which has wide adoption in container registries, through the Docker Content Trust model.
+
+> Because Signy uses Notary, its implementation is very closely related to the Docker Content Trust model. For an architecture of a service running Notary, [see this document][notary-architecture].
+
+#### Using Signy to perform TUF verifications
+
+- signing and pushing a bundle:
+
+```
+$ signy --tlscacert=$NOTARY_CA --server https://localhost:4443 sign testdata/cnab/bundle.json localhost:5000/thin-bundle:v1
+INFO[0000] Pushed trust data for localhost:5000/thin-bundle:v1: c7e92bd51f059d60b15ad456edf194648997d739f60799b37e08edafd88a81b5
+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"
+```
+
+- pulling from an OCI registry and verifying the signature of a bundle:
+
+```
+$ 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
+```
+
+#### Using Signy to also perform in-toto verifications
+
+- when signing a bundle, if in-toto metadata is available, it can be distributed according to the [CNAB Security specification][cnab-sec]:
+
+```
+$ signy --tlscacert=$NOTARY_CA --server https://localhost:4443 sign testdata/cnab/bundle.json localhost:5000/thin-intoto:v2 --in-toto --layout testdata/intoto/demo.layout.template --links testdata/intoto --layout-key testdata/intoto/alice.pub
+INFO[0000] Adding In-Toto layout and links metadata to TUF
+INFO[0000] Pushed trust data for localhost:5000/thin-intoto:v2: c7e92bd51f059d60b15ad456edf194648997d739f60799b37e08edafd88a81b5
+INFO[0000] Starting to copy image cnab/helloworld:0.1.1
+INFO[0001] Completed image cnab/helloworld:0.1.1 copy
+INFO[0001] Generated relocation map: relocation.ImageRelocationMap{"cnab/helloworld:0.1.1":"localhost:5000/thin-intoto@sha256:a59a4e74d9cc89e4e75dfb2cc7ea5c108e4236ba6231b53081a9e2506d1197b6"}
+INFO[0001] Pushed successfully, with digest "sha256:b4936e42304c184bafc9b06dde9ea1f979129e09a021a8f40abc07f736de9268"
+```
+
+- if the TUF metadata associated with a bundle also contains in-toto metadata, Signy will validate all layouts and links, and perform the verifications inside a verification image:
+
+```
+$ signy --tlscacert=$NOTARY_CA --server https://localhost:4443 verify localhost:5000/thin-intoto:v2 --in-toto --target testdata/intoto/foo.tar.gz
+INFO[0000] Pulled trust data for localhost:5000/thin-intoto:v2, with role targets - SHA256: c7e92bd51f059d60b15ad456edf194648997d739f60799b37e08edafd88a81b5
+INFO[0000] Pulling bundle from registry: localhost:5000/thin-intoto:v2
+INFO[0000] Computed SHA: c7e92bd51f059d60b15ad456edf194648997d739f60799b37e08edafd88a81b5
+INFO[0000] The SHA sums are equal: c7e92bd51f059d60b15ad456edf194648997d739f60799b37e08edafd88a81b5
+INFO[0000] Writing In-Toto metadata files into /tmp/intoto-verification169227773
+INFO[0000] copying file /in-toto/layout.template in container for verification...
+INFO[0000] copying file /in-toto/key.pub in container for verification...
+INFO[0000] copying file in-toto/package.2f89b927.link in container for verification...
+INFO[0000] copying file in-toto/write-code.776a00e2.link in container for verification...
+INFO[0000] copying file in-toto/foo.tar.gz in container for verification...
+INFO[0000] Loading layout...
+INFO[0000] Loading layout key(s)...
+INFO[0000] Verifying layout signatures...
+INFO[0001] Verifying layout expiration...
+INFO[0001] Reading link metadata files...
+INFO[0001] Verifying link metadata signatures...
+INFO[0001] Verifying sublayouts...
+INFO[0001] Verifying alignment of reported commands...
+INFO[0001] Verifying command alignment for 'write-code.776a00e2.link'...
+INFO[0001] Verifying command alignment for 'package.2f89b927.link'...
+INFO[0001] Verifying threshold constraints...
+INFO[0001] Skipping threshold verification for step 'write-code' with threshold '1'...
+INFO[0001] Skipping threshold verification for step 'package' with threshold '1'...
+INFO[0001] Verifying Step rules...
+INFO[0001] Verifying material rules for 'write-code'...
+INFO[0001] Verifying product rules for 'write-code'...
+INFO[0001] Verifying 'ALLOW foo.py'...
+INFO[0001] Verifying material rules for 'package'...
+INFO[0001] Verifying 'MATCH foo.py WITH PRODUCTS FROM write-code'...
+INFO[0001] Verifying 'DISALLOW *'...
+INFO[0001] Verifying product rules for 'package'...
+INFO[0001] Verifying 'ALLOW foo.tar.gz'...
+INFO[0001] Verifying 'ALLOW foo.py'...
+INFO[0001] Executing Inspection commands...
+INFO[0001] Executing command for inspection 'untar'...
+INFO[0001] Running 'untar'...
+INFO[0001] Recording materials '.'...
+INFO[0001] Running command 'tar xfz foo.tar.gz'...
+INFO[0001] Recording products '.'...
+INFO[0001] Creating link metadata...
+INFO[0001] Verifying Inspection rules...
+INFO[0001] Verifying material rules for 'untar'...
+INFO[0001] Verifying 'MATCH foo.tar.gz WITH PRODUCTS FROM package'...
+INFO[0001] Verifying 'DISALLOW foo.tar.gz'...
+INFO[0001] Verifying product rules for 'untar'...
+INFO[0001] Verifying 'MATCH foo.py WITH PRODUCTS FROM write-code'...
+INFO[0001] Verifying 'DISALLOW foo.py'...
+INFO[0001] The software product passed all verification.
+```
+
+[signy]: https://github.com/cnabio/signy
+[signy-release]: https://github.com/cnabio/signy/releases/tag/0.0.3
+[cnab-reg]: ./200-CNAB-registries.md
+[cnab-sec]: /300-CNAB-security.md
+[notary]: https://github.com/theupdateframework/notary
+[in-toto-golang]: https://github.com/in-toto/in-toto-golang/
+[in-toto-container]: https://github.com/engineerd/in-toto-container
+[notary-architecture]: https://github.com/theupdateframework/notary/blob/master/docs/service_architecture.md
+[cnab-to-oci]: https://github.com/cnabio/cnab-to-oci