chore: sync main branch to v1.2.0

config.yaml

@@ -1,4 +1,5 @@
 baseURL: https://notaryproject.dev/
+
 enableRobotsTxt: true
 
 theme: [docsy]
@@ -53,6 +54,25 @@ markup:
 # Everything below this are Site Params
 
 params:
+  versions:
+    - version: main
+      name: main
+      url: "https://notaryproject.dev/"
+    - version: v1.2
+      name: v1.2
+      url: "https://v1-2.notaryproject.dev/"
+    - version: v1.1
+      name: v1.1
+      url: "https://v1-1.notaryproject.dev/"
+    - version: v1.0
+      name: v1.0
+      url: "https://v1-0.notaryproject.dev/"
+  version_menu: "Version"
+  version_menu_pagelinks: true
+  archived_version: true
+  version: "0.1"
+  url_latest_version: "https://notaryproject.dev/docs/"
+
   copyright: Notary Project Authors
   description: >-
     A distributed, reliable key-value store for the most critical data of a

content/en/blog/2024/announcing-notation-v1-2.md

@@ -0,0 +1,55 @@
+---
+title: Notary Project announces Specification v1.1.0 and Notation v1.2.0!
+author:  "Notary Project Release Team"
+date: 2024-08-30
+draft: false
+---
+
+The Notary Project maintainers are excited to announce new releases, including [Notary Project specifications v1.1.0](https://github.com/notaryproject/specifications/releases/tag/v1.1.0), [notation v1.2.0](https://github.com/notaryproject/notation/releases/tag/v1.2.0), [notation-go v1.2.0](https://github.com/notaryproject/notation-go/releases/tag/v1.1.0), and [notation-core-go v1.1.0](https://github.com/notaryproject/notation-core-go/releases/tag/v1.1.0). These versions are now ready for production use!
+
+## Deprecation
+
+The experimental flag `--allow-referrers-api` used by `notation sign` and `notation verify` commands is now deprecated. See [Support OCI specification v1.1.0](#support-oci-specification-v110) for details.
+
+## Notable Capabilities in this Release
+
+Here are some of the major capabilities and features included in this release.
+
+### Notary Project specifications
+
+The Notary Project specifications now include support for [RFC 3161](https://www.rfc-editor.org/rfc/rfc3161) timestamping and introduce Notation plugin conventions in the [plugin specification](https://github.com/notaryproject/specifications/blob/v1.1.0/specs/plugin-extensibility.md).
+
+### Support OCI specification v1.1.0
+
+In Feb 2024, the Open Container Initiative (OCI) community released version 1.1.0, which includes the [OCI image specification v1.1.0](https://github.com/opencontainers/image-spec/releases/tag/v1.1.0) and the [OCI distribution specification v1.1.0](https://github.com/opencontainers/distribution-spec/releases/tag/v1.1.0). Notation now adheres to the OCI spec v1.1.0, leading to the deprecation of the experimental flag `--allow-referrers-api`. A new flag, `--force-referrers-tag` (default to `true`), has been introduced to the `notation sign` command, enabling users to choose the referrers tag schema over the [referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#enabling-the-referrers-api) if the registry they are using does not yet support the referrers API. The `notation verify/list/inspect` commands attempt to use the referrers API first and automatically fall back to the [referrers tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#referrers-tag-schema) if the referrers API is not supported by the registry.
+
+> [!NOTE]
+> We will change the default value of `--force-referrers-tag` to `false` in Notation v2.0 release, making referrers API usage as the default.
+
+### Support for RFC 3161 compliant timestamping
+
+Since this release, Notation supports RFC 3161 compliant timestamping. Digital signatures must be generated within the certificate's validity period, as expired certificates compromise the signature's trustworthiness. Timestamping extends the trust of signatures created within certificate validity, allowing successful signature verification even after certificates have expired. Notation's timestamping feature is built on top of the [tspclient-go](https://github.com/notaryproject/tspclient-go) library.
+
+Learn more at the document [how to sign and verify artifacts in OCI-compliant registries with timestamping](/docs/user-guides/how-to/timestamping/).
+
+### Other changes
+
+Notation CLI now offers the `armv7` binary, enabling its usage in environments such as Internet of Things (IoT) or embedded systems.
+
+## Get started with Notation v1.2.0
+
+You can follow the [quick start guide](/docs/quickstart-guides/quickstart-sign-image-artifact/) to try Notation v1.2.0 for basic signing and verification workflow.
+
+## What's next
+
+The Notary Project maintainers are considering the following features for future milestones. Feel free to reach out on the [Slack channel](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/) or [GitHub issues](https://github.com/notaryproject/notation/issues) to ask questions, provide feedback, or share ideas.
+
+- Revocation checking using Certificate Revocation List (CRL)
+- Sign and verify arbitrary blobs
+- Attestations
+
+And more!
+
+## Acknowledgements
+
+The Notary Project release team wants to thank the entire Notary Project community for all the activity and engagement that has been vital for helping the project grow and reach this milestone.

content/en/docs/user-guides/how-to/timestamping.md

@@ -0,0 +1,145 @@
+---
+title: "Timestamping"
+description: "How to sign and verify artifacts in OCI-compliant registries with timestamping"
+type: docs
+weight: 9
+---
+
+In the X.509 Public Key Infrastructure (PKI) system, digital signatures must be generated within the certificate's validity period, as expired certificates compromise the signature's trustworthiness. The [RFC 3161](https://www.rfc-editor.org/rfc/rfc3161) standard defines the internet X.509 PKI Time-Stamp Protocol (TSP), where a timestamp is issued by a trusted third party acting as a Time Stamping Authority (TSA). These trusted timestamps extend the trust of signatures created within certificates validity, enabling successful signature verification even after certificates have expired.
+
+Since Notation v1.2.0 release, Notation supports RFC 3161 compliant timestamping. During signing, a timestamp countersignature is added to the Notary Project signature envelope for the signing artifact, ensuring the trustworthiness of the signature through validation. However, Notation does not use timestamp to verify that the signature was created before any certificate revocation, as the revocation time is not deterministic. For example, the revocation time may not coincide with the time the certificates are compromised.
+
+This guide describes how to sign and verify artifacts in OCI ([Open Container Initiative](https://github.com/opencontainers)) compliant registries with timestamping. Artifacts in OCI-compliant registries can be container images or other artifacts such as Software Bill of Materials (SBOM).
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+* Learned the basic signing and verification workflow following the [guide](https://notaryproject.dev/docs/quickstart-guides/) since Timestamping feature was added on top of existing signing and verification workflows.
+* Installed Notation CLI v1.2.0. If not, follow the [installation guides](https://notaryproject.dev/docs/user-guides/installation/).
+* Installed Notation plugins for signing with keys stored in a KMS (Key Management System), such as Azure Key Vault.
+* A container image or artifact stored in an OCI-compliant registry.
+
+## Sign artifacts in OCI-compliant registries with timestamping
+
+To sign artifacts in OCI-compliant registries with timestamping, you need to select a trusted [RFC 3161](https://www.rfc-editor.org/rfc/rfc3161) compliant TSA. There are public TSAs available, such as [DigitCert](https://www.digicert.com/) TSA and [Globalsign](https://www.globalsign.com/) TSA. Since Notation CLI v1.2.0, two flags `--timestamp-url` and `--timestamp-root-cert` are introduced to the `notation sign` command for RFC 3161 timestamping. Use the flag `--timestamp-url` to specify the URL of the TSA that you trusted. Use the flag `--timestamp-root-cert` to specify the filepath of downloaded root cert file for the trusted TSA. The root cert serves as the trust anchor to establish the chain of trust of the TSA. This is to protect you from MITM (Man-in-the-Middle) attacks. Upon successful execution of `notation sign`, the TSA response will be stored in the signature envelope. An example command:
+
+```shell
+notation sign --timestamp-url <TSA_URL> --timestamp-root-cert <TSA_ROOT_CERT> --key <KEY_NAME> <REFERENCE_TO_ARTIFACT> 
+```
+
+For example, if you choose DigiCert public TSA, the URL is `http://timestamp.digicert.com`, and you can download the root certificate [here](https://cacerts.digicert.com/DigiCertTrustedRootG4.crt) and name it as `digicert_root_cert.crt`. The command looks like:
+
+```shell
+notation sign --timestamp-url "http://timestamp.digicert.com" --timestamp-root-cert "digicert_root_cert.crt" --key <KEY_NAME> <REFERENCE_TO_ARTIFACT> 
+```
+
+If you do not specify the two flags `--timestamp-url` and `--timestamp-root-cert`, artifacts are signed without timestamping.
+
+## Inspect signatures with RFC 3161 timestamp
+
+Since Notation v1.2.0, the `notation inspect` command is enhanced to show RFC 3161 timestamp in the output.
+
+```shell
+notation inspect <REFERENCE_TO_ARTIFACT>
+```
+
+An example output:
+
+```text
+├── unsigned attributes
+│   ├── timestamp signature
+│   │   ├── timestamp: [Tue Aug 20 00:14:59 2024, Tue Aug 20 00:14:59 2024]
+│   │   └── certificates
+│   │       ├── SHA256 fingerprint: d2f6e46ded7422ccd1d440576841366f828ada559aae3316af4d1a9ad40c7828
+│   │       │   ├── issued to: CN=DigiCert Timestamp 2023,O=DigiCert\, Inc.,C=US
+│   │       │   ├── issued by: CN=DigiCert Trusted G4 RSA4096 SHA256 TimeStamping CA,O=DigiCert\, Inc.,C=US
+│   │       │   └── expiry: Fri Oct 13 23:59:59 2034
+│   │       ├── SHA256 fingerprint: 281734d4592d1291d27190709cb510b07e22c405d5e0d6119b70e73589f98acf
+│   │       │   ├── issued to: CN=DigiCert Trusted G4 RSA4096 SHA256 TimeStamping CA,O=DigiCert\, Inc.,C=US
+│   │       │   ├── issued by: CN=DigiCert Trusted Root G4,OU=www.digicert.com,O=DigiCert Inc,C=US
+│   │       │   └── expiry: Sun Mar 22 23:59:59 2037
+│   │       └── SHA256 fingerprint: 33846b545a49c9be4903c60e01713c1bd4e4ef31ea65cd95d69e62794f30b941
+│   │           ├── issued to: CN=DigiCert Trusted Root G4,OU=www.digicert.com,O=DigiCert Inc,C=US
+│   │           ├── issued by: CN=DigiCert Assured ID Root CA,OU=www.digicert.com,O=DigiCert Inc,C=US
+│   │           └── expiry: Sun Nov  9 23:59:59 2031
+```
+
+Under the field `timestamp signature`, there are `timestamp` and `certificates` fields. The value of `certificates` lists all the certificates included in the TSA response.
+
+## Verify artifacts in OCI-compliant registries with timestamping
+
+To verify artifacts in OCI-compliant registries with timestamping, you need to create a trust store with the type of `tsa`, add the downloaded TSA root certificate, and use the trust store in the trust policy for verification.
+
+Here are the steps:
+
+1. Create the trust store with the type `tsa`:
+
+```shell
+notation cert add --type tsa --store <TSA_STORE_NAME> <TSA_ROOT_CERT_FILEPATH>
+```
+
+2. Update your trust policy to add the `tsa` trust store to the property `trustStores`.
+
+```json
+{
+    "version": "1.0",
+    "trustPolicies": [
+        {
+            "name": "<POLICY_NAME>",
+            "registryScopes": [ "<REPO_URL>" ],
+            "signatureVerification": {
+                "level" : "strict"
+            },
+            "trustStores": ["ca:<CA_STORE_NAME>", "tsa:<TSA_STORE_NAME>" ],
+            "trustedIdentities": [
+                "x509.subject: <SUBJECT_OF_SIGNING_CERT>"
+            ]
+        }
+    ]
+}
+```
+
+3. Import and use the new trust policy:
+
+```shell
+notation policy import <POLICY_FILE_NAME>.json
+```
+
+4. Verify artifacts, optionally you can use flag `-v` to view the verbose logs:
+
+```shell
+notation verify -v <REFERENCE_TO_ARTIFACT>
+```
+
+If the signature was generated with timestamping before certificates expiry, the signature verification will succeed despite certificates expiry at verification time. However, if the trust store of the `tsa` type is not properly established or not configured within the trust policy, the signature verification will fail due to certificates expire.
+
+## Configuration for timestamp verification
+
+By default, if the trust store of `tsa` type is created and configured in the trust policy, Notation will always perform timestamp verification no matter the certificates expire or not. In scenarios you may want to perform timestamp verification only after certificates expire, you can configure additional property `verifyTimestamp` under the parent property `signatureVerification` and set the value to `afterCertExpiry` in the trust policy. For example,
+
+```json
+{
+    "version": "1.0",
+    "trustPolicies": [
+        {
+            "name": "<POLICY_NAME>",
+            "registryScopes": [ "<REPO_URL>" ],
+            "signatureVerification": {
+                "level" : "strict",
+                "verifyTimestamp": "afterCertExpiry"
+            },
+            "trustStores": ["ca:<CA_STORE_NAME>", "tsa:<TSA_STORE_NAME>" ],
+            "trustedIdentities": [
+                "x509.subject: <SUBJECT_OF_SIGNING_CERT>"
+            ]
+        }
+    ]
+}
+```
+
+To restore to the default behavior, you can either remove the property `verifyTimestamp`, or set the value to `always`.
+
+## What is the next?
+
+In the future, we'll use the system certificate store to verify the chain of trust of a TSA, eliminating the need for you to download and use the root certificate.

content/en/docs/user-guides/how-to/verify.md

@@ -2,7 +2,7 @@
 title: "Verification of container image on Kubernetes"
 description: "This guide describes the verification of container image before deploying on Kubernetes Cluster"
 type: docs
-weight: 11
+weight: 8
 ---
 As container images continue to be distributed across various channels, it becomes increasingly important for consumers to ensure that the downloaded container images are authentic before deploying them into their Kubernetes environment. This practice helps mitigate potential cyber threats. Container image verification is the process of evaluating the digital signature of a container image to determine if a container image is considered authentic. Let’s say, you’ve downloaded a signed image from a public source for deployment within your Kubernetes cluster. How do you validate the authenticity and integrity of the image? Which tools should you use for verifying signed images during deployment? This guide describes verification scenarios on Kubernetes and suggests tools for validating signed container images before deploying them on Kubernetes. Let's take a look at this scenario in more detail:
 

content/en/docs/user-guides/installation/cli.md

@@ -2,19 +2,21 @@
 title: Install the notation CLI
 description: Install the notation CLI on Linux, macOS, and Windows
 weight: 1
-cliVer : 1.1.1
+cliVer : 1.2.0
 ---
 
 ## Download and install the CLI for Linux
 
 ### Homebrew
+
 Download the latest stable release of the `notation CLI` on Linux using [Homebrew](https://brew.sh/):
 
 ```console
 brew install notation
 ```
 
 ### Binary download
+
 Download the latest stable release of the notation CLI binary for Linux and checksum file, then verify the integrity of the download.
 
 Set the `NOTATION_VERSION` environment variable to the version of notation you want to download. The latest version is `{{< param cliVer >}}`.
@@ -72,13 +74,15 @@ echo 'export PATH="$PATH:<EXAMPLE_PATH>/notation-cli/"' >> ~/.bashrc
 ## Download and install the CLI for macOS
 
 ### Homebrew
+
 Download the latest stable release of the `notation CLI` on macOS using [Homebrew](https://brew.sh/):
 
 ```console
 brew install notation
 ```
 
 ### Binary download
+
 Download the latest stable release of the notation CLI binary for macOS and checksum file, then verify the integrity of the download.
 
 Set the `NOTATION_VERSION` environment variable to the version of notation you want to download. The latest version is `{{< param cliVer >}}`.
@@ -136,12 +140,15 @@ echo 'export PATH="$PATH:<EXAMPLE_PATH>/notation-cli/"' >> ~/.zshrc
 ## Download and install the CLI for Windows
 
 ### WinGet
+
 Download the latest stable release of the `notation CLI` on Windows using [WinGet (Windows package manager)](https://github.com/microsoft/winget-pkgs):
 
 ```console
 winget install notation -s winget
 ```
+
 ### .exe download
+
 Download the latest stable release of the notation CLI binary for Windows and checksum file:
 
 * [notation_{{< param cliVer >}}_windows_amd64.zip](https://github.com/notaryproject/notation/releases/download/v{{< param cliVer >}}/notation_{{< param cliVer >}}_windows_amd64.zip)

layouts/index.redirects

@@ -1,2 +1 @@
-{{ $latest := site.Params.versions.latest }}
-
+{{ $latest := index .Site.Params.versions (sub (len .Site.Params.versions) 1) }}

layouts/partials/banner.html

@@ -1,6 +1,6 @@
 <section class="news is-medium flex justify-center">
     <p class="is-size-3-mobile">
-      <a href="https://github.com/notaryproject/notation/releases/tag/v1.1.1" class="banner-link">Notation v1.1.1 is available</a>
+      <a href="https://github.com/notaryproject/notation/releases/tag/v1.2.0" class="banner-link">Notation v1.2.0 is available</a>
       <span>
         {{ $rocketIcon := resources.Get "icons/rocket-icon.svg" }}
         <img

layouts/partials/navbar.html

@@ -20,6 +20,18 @@
 				<a class="nav-link{{if $active }} active{{end}}" href="{{ with .Page }}{{ .RelPermalink }}{{ else }}{{ .URL | relLangURL }}{{ end }}" {{ if ne $url.Host $baseurl.Host }}target="_blank" {{ end }}>{{ with .Pre}}{{ $pre }}{{ end }}<span{{if $active }} class="active"{{end}}>{{ .Name }}</span>{{ with .Post}}{{ $post }}{{ end }}</a>
 			</li>
 			{{ end }}
+			{{ if  .Site.Params.versions }}
+			<li class="nav-item dropdown mr-4 d-none d-lg-block">
+				<a class="nav-link dropdown-toggle" id="versionDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+				  {{ $.Site.Params.version_menu }}
+				</a>
+				<div class="dropdown-menu" aria-labelledby="versionDropdown">
+				  {{ range $.Site.Params.versions }}
+					<a class="dropdown-item" href="{{ .url }}">{{ .name }}</a>
+				  {{ end }}
+				</div>
+			  </li>
+			{{ end }}
             <div class="flex gap-md nav-item mr-4 mb-2 mb-lg-0">
                 <div class="img-container-xxsm">
                     <a class="nav-link" href="{{ .Site.Params.navbar.logos.github.url }}">
@@ -40,11 +52,6 @@
                     </a>
                 </div>
             </div>
-			{{ if  .Site.Params.versions }}
-			<li class="nav-item dropdown mr-4 d-none d-lg-block">
-				{{ partial "navbar-version-selector.html" . }}
-			</li>
-			{{ end }}
 			{{ if  (gt (len .Site.Home.Translations) 0) }}
 			<li class="nav-item dropdown mr-4 d-none d-lg-block">
 				{{ partial "navbar-lang-selector.html" . }}