restructured notary project documentation

content/en/docs/developer/_index.md

@@ -0,0 +1,5 @@
+---
+title: Developer Documentation
+description: This documentation will go over how to develop plugins for Notation, how to securely deploy notation, and best practices for implementing Notary project specifications.
+weight: 4
+---

content/en/docs/developer/experimental-features.md

@@ -0,0 +1,20 @@
+---
+title: "Experimental features"
+description: "Explanation of experimental features"
+type: docs
+weight: 3
+---
+
+Starting in version `v1.0.0-rc.4`, Notation began introducing experimental features. Experimental features are features that are not yet ready for production use but are available for testing and evaluation. Experimental features may change significantly in later releases or be completely removed. Experimental features are not enabled by default and are not supported.
+
+Currently, Notation has the following experimental features:
+
+- [Signing, listing and verifying images as OCI image layout]({{< ref "/docs/notation/how-to/oci-image-layout" >}})
+- Store signatures using artifact manifest (requires registry support). Deprecated in `v1.0.0-rc.5`.
+- Use [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc2/spec.md#enabling-the-referrers-api)
+
+To enable experimental features, set the `NOTATION_EXPERIMENTAL` environment variable to `1`, for example:
+
+```console
+export NOTATION_EXPERIMENTAL=1
+```

content/en/docs/developer/secure-deployment.md

@@ -0,0 +1,57 @@
+---
+title: "Securely deploying Notation"
+description: "Best practices for securely deploying Notation"
+type: docs
+weight: 2
+---
+
+A deployment of Notation, specifically the `notation` CLI, is used for signing and verifying container images. The `notation` CLI is usually deployed on a development computer or in a CI/CD pipeline, such as GitHub Actions.
+
+A deployment has several sensitive components:
+
+- [Trust policies]({{< ref "/docs/notation/how-to/manage-trust-policy" >}})
+- [Trust stores and certificates]({{< ref "/docs/notation/concepts/directory-structure" >}})
+- Plugins
+
+It is strongly recommended that you follow the best practices in this document to secure your deployment of Notation. Notation works with a shared responsibility model, meaning users and organizations are responsible for securing the `notation` CLI deployment.
+
+Failure to secure the filesystem on development computers and hosts with `notation` CLI deployments can result in malicious plugins being installed, trust policies being modified to allow verification compromised or untrusted artifacts, and trust stores being modified to have untrusted or compromised certificates.
+
+## Secure the installation and binary
+
+When manually installing the binary, it is critical to download both the binary and its checksum from a trusted source, such as the [notation GitHub repo](https://github.com/notaryproject/notation/releases), over HTTPS. You should also verify the checksum of the binary before using it. When using a package manager, such as [Homebrew](https://brew.sh/), it is critical to use a package manager that provides authenticity guarantees. For example, Homebrew uses [GPG](https://gnupg.org/) to verify the authenticity of the packages it installs. 
+
+When downloading the binary without installing it, for example to use it in a CI/CD pipeline, it is critical to download both the binary and checksum from a trusted source, such as the [notation GitHub repo](https://github.com/notaryproject/notation/releases), over HTTPS. You should also verify the checksum of the binary. If all users on the host will need access to the binary, copy the binary to `/usr/local/bin` with the owner set to `root` and the permission set to `rwxr-xr-x (755)`. This operation will require `sudo` or root access. If only one user, such as your account, will need access to the binary, copy the binary to a directory that users own with the owner set to that user and the permission set to `rwx------ (700)`. 
+
+## Secure the trust policy file
+
+When creating a trust policy that only one user, such as your account, needs create the policy using `notation policy import` as that user without `sudo`. This approach ensures the policy file is stored in the correct directory with appropriate permissions. 
+
+Manually moving the trust file and setting the directory and file permissions is not recommended, but if you choose to do so, you must adhere to the following guidelines:
+- The policy file should be stored in a directory that user owns with the permission set to `rwx------ (700)`. 
+- The policy file should have the permission set to `rw------- (600)`. 
+
+## Secure certificates
+
+When setting up a signing key for yourself, you should use your own account to do that. Never use `sudo` or as a separate user unless you are an admin and try to set up the signing key for that user. This recommendation applies for both the binary installed for all users on the system or just for you.
+
+When downloading certificates for validation, always obtain them from trusted sources. For web-based downloads, using HTTPS. For vendor-specific sources, use the tools provided by the vendor. Use `notation cert add` to add the certificates to the trust store. 
+
+Manually moving certificates and setting the directory and file permissions is not recommended, but if you choose to do so, you must set the permissions for those certificate files to `rw------- (600)` to prevent access from other users since those certificates may contain confidential information.
+
+## Secure filesystem access
+
+The sensitive components of a deployment of Notation are stored on the filesystem. For development computers managed by individuals and hosts directly managed by your organization, you should follow general best practices as well as your organization's best practices for securing those development computers and hosts, such as:
+
+- Ensuring the operating system is fully patched
+- The disk encryption follows your organizations encryption policies
+- Use strong passwords and adhere to your organization's password policies
+- Access to the Notation deployment directory is restricted to only authorized users, such as those with `sudo` access, administrators, or the user that owns the directory 
+
+Every organization has different policies and best practices for securing development computers and hosts, and they should be followed as a part securing filesystem on development computers and hosts with `notation` CLI deployments.
+
+## Other security best practices
+
+For development computers managed by individuals and hosts directly managed by your organization, ensure the access to those systems as well as locations of the sensitive components of a deployment of Notation are restricted to only authorized users.
+
+For computers not directly managed by individuals or your organization, such as hosts used for CI/CD pipelines, ensure manner in which the sensitive components of a deployment of Notation are stored, accessed, and transmitted to those computers follows your organizations best practices and are restricted only to authorized users.

content/en/docs/developer/secure-plugin-development.md

@@ -0,0 +1,28 @@
+---
+title: "Securely develop plugins for Notation"
+description: "Best practices for securely developing and distributing plugins for Notation"
+type: docs
+weight: 1
+---
+
+{{% alert title="Important" color="important" %}}
+Best practices for developing and distributing plugins for Notation are covered in the [Notary Project specification for plugins](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md). Carefully review that specification before developing and distributing plugins for Notation.
+
+The following guidance is not a substitute for the Notary Project specification for plugins. It is intended to highlight key security considerations for developing and distributing plugins for Notation.
+{{% /alert %}}
+
+## General security guidance
+
+In general when developing your plugin, ensure you strictly adhere to the [Notary Project specification for plugins](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md).
+
+Plugins run as a binary and are invoked by Notation. This means that the plugin has access to the same resources as the user running Notation. This includes access to the filesystem, network, and other resources. Ensure you are only accessing resources that are required for your plugin to function.
+
+In some cases, your plugin may have access to sensitive data such as private keys. Ensure that you are not leaking this data to the filesystem, network, or other resources, including `stdout` and `stderr`.
+
+If using the `pluginConfig` key/value store, do not store sensitive data in as the data is not encrypted and is stored as plaintext.
+
+## Securely distributing plugins
+
+Ensure that you are distributing your plugin from a secure location and over a secure channel. For example, using a website or server you control and using HTTPS. If you are using a public repository, ensure it is a known, reputable repository that uses HTTPS, such as GitHub.
+
+It is strongly recommended that you provide some way for users to verify the integrity of the plugin binary, such as providing a checksum or signature. This allows users to verify that the plugin binary has not been corrupted or tampered with.

content/en/docs/developer/specs-requirements.md

@@ -0,0 +1,8 @@
+---
+title: "Notary project specifications and requirements"
+description: "Notary project specifications and requirements"
+type: docs
+weight: 4
+---
+
+More information on the specifications, requirements, and other details about the Notary project can be found in the [Notary repository](https://github.com/notaryproject/notaryproject/tree/main).

content/en/docs/faq.md

@@ -2,7 +2,7 @@
 title: "Frequently asked questions"
 description: "Frequently asked questions about Notary"
 type: docs
-weight: 8
+weight: 5
 ---
 
 ## What registries are compatible with Notary?

content/en/docs/notation/_index.md

@@ -0,0 +1,7 @@
+---
+title: Notation
+description: CLI tool and libraries for signing and verifying artifacts
+weight: 2
+---
+
+Notation is a CLI project to add signatures as standard items in the registry ecosystem, and to build a set of simple tooling for signing and verifying these signatures. This should be viewed as similar security to checking git commit signatures, although the signatures are generic and can be used for additional purposes. Notation is an implementation of the [Notary project specifications](https://github.com/notaryproject/notaryproject/tree/main/specs).

content/en/docs/notation/cli-reference/_index.md

@@ -0,0 +1,5 @@
+---
+title: CLI Reference
+description: Reference documentation for notation
+weight: 6
+---

content/en/docs/notation/cli-reference/notation.md

@@ -0,0 +1,10 @@
+---
+title: notation
+---
+Notation - a tool to sign and verify artifacts
+
+### Options
+
+```console
+  -h, --help   help for notation
+```

content/en/docs/notation/cli-reference/notation_certificate.md

@@ -0,0 +1,15 @@
+---
+title: notation certificate
+---
+
+Manage certificates in trust store
+
+### Synopsis
+
+Manage certificates in trust store for signature verification.
+
+### Options
+
+```console
+  -h, --help   help for certificate
+```

content/en/docs/notation/cli-reference/notation_certificate_add.md

@@ -0,0 +1,35 @@
+---
+title: notation certificate add
+---
+
+Add certificates to the trust store.
+
+### Synopsis
+
+Add certificates to the trust store
+
+Example - Add a certificate to the "ca" type of a named store "acme-rockets":
+
+```shell
+notation cert add --type ca --store acme-rockets acme-rockets.crt
+```
+
+Example - Add a certificate to the "signingAuthority" type of a named store "wabbit-networks":
+
+```shell
+notation cert add --type signingAuthority --store wabbit-networks wabbit-networks.pem
+```
+
+General usage:
+```shell
+notation certificate add --type <type> --store <name> [flags] <cert_path>...
+```
+
+### Options
+
+```
+  -h, --help           help for add
+  -s, --store string   specify named store
+  -t, --type string    specify trust store type, options: ca, signingAuthority
+```
+

content/en/docs/notation/cli-reference/notation_certificate_delete.md

@@ -0,0 +1,43 @@
+---
+title: notation certificate delete
+---
+
+Delete certificates from the trust store.
+
+### Synopsis
+
+Delete certificates from the trust store
+
+Example - Delete all certificates with "ca" type from the trust store "acme-rockets":
+
+```shell
+notation cert delete --type ca --store acme-rockets --all
+```
+
+Example - Delete certificate "cert1.pem" with "signingAuthority" type from trust store wabbit-networks:
+
+```shell
+notation cert delete --type signingAuthority --store wabbit-networks cert1.pem
+```
+
+Example - Delete all certificates with "ca" type from the trust store "acme-rockets", without prompt for confirmation:
+
+```shell
+notation cert delete --type ca --store acme-rockets -y --all 
+```
+
+General usage:
+```shell
+notation certificate delete --type <type> --store <name> [flags] (--all | <cert_fileName>)
+```
+
+### Options
+
+```
+  -a, --all            delete all certificates in the named store
+  -h, --help           help for delete
+  -s, --store string   specify named store
+  -t, --type string    specify trust store type, options: ca, signingAuthority
+  -y, --yes            do not prompt for confirmation
+```
+

content/en/docs/notation/cli-reference/notation_certificate_generate-test.md

@@ -0,0 +1,33 @@
+---
+title: notation certificate generate-test
+---
+
+Generate a test RSA key and a corresponding self-signed certificate.
+
+### Synopsis
+
+Generate a test RSA key and a corresponding self-signed certificate
+
+Example - Generate a test RSA key and a corresponding self-signed certificate named "wabbit-networks.io":
+```shell
+notation cert generate-test "wabbit-networks.io"
+```
+
+Example - Generate a test RSA key and a corresponding self-signed certificate, set RSA key as a default signing key:
+```shell
+notation cert generate-test --default "wabbit-networks.io"
+```
+
+General usage:
+```shell
+notation certificate generate-test [flags] <common_name>
+```
+
+### Options
+
+```
+  -b, --bits int   RSA key bits (default 2048)
+      --default    mark as default signing key
+  -h, --help       help for generate-test
+```
+

content/en/docs/notation/cli-reference/notation_certificate_list.md

@@ -0,0 +1,45 @@
+---
+title: notation certificate list
+---
+
+List certificates in the trust store.
+
+### Synopsis
+
+List certificates in the trust store
+
+Example - List all certificate files stored in the trust store
+```shell
+notation cert ls
+```
+
+Example - List all certificate files of trust store "acme-rockets"
+```shell
+notation cert ls --store "acme-rockets"
+```
+
+Example - List all certificate files from trust store of type "ca"
+```shell
+notation cert ls --type ca
+```
+
+Example - List all certificate files from trust store "wabbit-networks" of type "signingAuthority"
+```shell
+notation cert ls --type signingAuthority --store "wabbit-networks"
+```
+
+General usage:
+```shell
+notation certificate list [flags]
+```
+
+### Options
+
+```
+  -d, --debug          debug mode
+  -h, --help           help for list
+  -s, --store string   specify named store
+  -t, --type string    specify trust store type, options: ca, signingAuthority
+  -v, --verbose        verbose mode
+```
+

content/en/docs/notation/cli-reference/notation_certificate_show.md

@@ -0,0 +1,35 @@
+---
+title: notation certificate show
+---
+
+Show certificate details given trust store type, named store, and certificate file name. If the certificate file contains multiple certificates, then all certificates are displayed.
+
+### Synopsis
+
+Show certificate details of given trust store name, trust store type, and certificate file name. If the certificate file contains multiple certificates, then all certificates are displayed
+
+Example - Show details of certificate "cert1.pem" with type "ca" from trust store "acme-rockets":
+```shell
+notation cert show --type ca --store acme-rockets cert1.pem
+```
+
+Example - Show details of certificate "cert2.pem" with type "signingAuthority" from trust store "wabbit-networks":
+```shell
+notation cert show --type signingAuthority --store wabbit-networks cert2.pem
+```
+
+General usage:
+```shell
+notation certificate show --type <type> --store <name> [flags] <cert_fileName>
+```
+
+### Options
+
+```
+  -d, --debug          debug mode
+  -h, --help           help for show
+  -s, --store string   specify named store
+  -t, --type string    specify trust store type, options: ca, signingAuthority
+  -v, --verbose        verbose mode
+```
+