From d4f4c01496261fbbc7cab2fe619e1e812059abcf Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Thu, 12 May 2022 23:57:50 +0800 Subject: [PATCH 01/12] directory structure Signed-off-by: Shiwei Zhang --- specs/directory.md | 167 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 specs/directory.md diff --git a/specs/directory.md b/specs/directory.md new file mode 100644 index 000000000..1b13988c0 --- /dev/null +++ b/specs/directory.md @@ -0,0 +1,167 @@ +# Notation Directory Structure + +The `notation` CLI requires local file systems support for the following components across various platforms. + +- `notation` binary +- Plugins +- Configurations +- Trust stores +- Trust policies +- Signature caches +- Local key store + +This documentation specifies the recommended directory structure for those components. + +## Category + +The directories for various components are classified into the following catagories. + +| Alias | Description | +| --------- | ----------------------------------------------------------------------------------- | +| `BIN` | Directory for executable binaries | +| `LIBEXEC` | Directory for binaries not meant to be executed directly by users' shell or scripts | +| `CONFIG` | Directory for configurations | +| `CACHE` | Directory for user-specific cache | + +Although it is recommended to install `notation` with its plugins and default configurations at the system level, it is possible to install at the user level. + +On Unix systems, `notation` follows [Filesystem Hierarchy Standard][FHS] for system level directories and [XDG Base Directory Specification][XDG] for user level directories. On Windows, [Known Folders][KF] and [App Settings][AS] are followed equivalently. On Darwin, [macOS File System][macOS_FS] with [System Integrity Protection][SIP] is followed equivalently. If a file with the same name exists at the system level and the user level, the file at the user level takes over the priority. + +### System Level + +Default directory paths for various operating systems at system level are specified as below. + +| Directory | Unix | Windows | Darwin | +| --------- | -------------- | ----------------------------- | ------------------------------ | +| `BIN` | `/usr/bin` | `%ProgramFiles%/notation/bin` | `/usr/local/bin` | +| `LIBEXEC` | `/usr/libexec` | `%ProgramFiles%` | `/usr/local/lib` | +| `CONFIG` | `/etc` | `%ProgramData%` | `/Library/Application Support` | + +`CACHE` is omitted since it is user specific. + +### User Level + +Default directory paths for various operating systems at user level are specified as below. + +| Directory | Unix | Windows | Darwin | +| --------- | ------------------ | ---------------- | ------------------------------- | +| `LIBEXEC` | `$XDG_CONFIG_HOME` | `%AppData%` | `~/Library/Application Support` | +| `CONFIG` | `$XDG_CONFIG_HOME` | `%AppData%` | `~/Library/Application Support` | +| `CACHE` | `$XDG_CACHE_HOME` | `%LocalAppData%` | `~/Library/Caches` | + +There is no default `BIN` path at user level since the `notation` binary can be put anywhere as long as it in the `PATH` environment variable. Common directories on Unix/Darwin are `~/bin` and `~/.local/bin` where manual `PATH` update by users may be required. + +## Structure + +The overall directory structure for `notation` is summarized as follows. + +``` +{BIN} +└── notation +{CONFIG} +└── notation + ├── config.json + ├── private + │   ├── {key-name}.crt + │   └── {key-name}.key + └── trust + ├── policy.json + └── store + └── {trust-store-type} + └── {named-store} + └── {cert-file} +{CACHE} +└── notation + └── signature + └── {manifest-digest-algorithm} + └── {manifest-digest} + └── {signature-digest-algorithm} + └── {signature-digest}.sig +{LIBEXEC} +└── notation + └── plugins + └── {plugin-name} + └── notation-{plugin-name} +``` + +### Notation Binary + +The path for the `notation` binary is + +``` +{BIN}/notation +``` + +### Plugin + +Plugin are binaries not meant to be executed directly by users' shell or scripts. The path of a plugin follows the pattern below. + +``` +{LIBEXEC}/notation/plugins/{plugin-name}/notation-{plugin-name} +``` + +### General Configuration + +The path of the general configuration file of the `notation` CLI is + +``` +{CONFIG}/notation/config.json +``` + +### Trust Store + +The path of a certificate file in a [Trust Store][TS] follows the pattern of + +``` +{CONFIG}/notation/trust/store/{trust-store-type}/{named-store}/{cert-file} +``` + +### Trust Policy + +The path of the [Trust Policy][TP] file is + +``` +{CONFIG}/notation/trust/policy.json +``` + +### Signature Caches + +The signatures are cached to optimize the network traffic. The path of a cached signature for a certain manifest follows the pattern below. + +``` +{CACHE}/notation/signature/{manifest-digest-algorithm}/{manifest-digest}/{signature-digest-algorithm}/{signature-digest}.sig +``` + +or in a hierarchical view + +``` +{CACHE} +└── notation + └── signature + └── {manifest-digest-algorithm} + └── {manifest-digest} + └── {signature-digest-algorithm} + └── {signature-digest}.sig +``` + +### Local key store + +Developers sign artifacts using local private keys with associated certificate chain. The default directory structure for testing purpose is suggested as follows. + +``` +{CONFIG}/notation/private/{key-name}.crt +{CONFIG}/notation/private/{key-name}.key +``` + +Developers SHOULD consider safer places to store the passphrase-protected key and certificate pair, or opt to remote signing. + +[References]:: + +[FHS]: https://refspecs.linuxfoundation.org/fhs.shtml "Filesystem Hierarchy Standard" +[XDG]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html "XDG Base Directory Specification" +[KF]: https://docs.microsoft.com/windows/win32/shell/knownfolderid "Known Folders" +[AS]: https://docs.microsoft.com/windows/apps/design/app-settings/store-and-retrieve-app-data "App Settings" +[macOS_FS]: https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW14 "macOS File System" +[SIP]: https://support.apple.com/HT204899 "System Integrity Protection" +[TS]: https://github.com/notaryproject/notaryproject/blob/main/trust-store-trust-policy-specification.md#trust-store "Trust Store" +[TP]: https://github.com/notaryproject/notaryproject/blob/main/trust-store-trust-policy-specification.md#trust-policy "Trust Policy" From be10005b3f83b419ab0f965cd17b1a2071edb511 Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Fri, 13 May 2022 11:36:23 +0800 Subject: [PATCH 02/12] split config.json and add keys.json Signed-off-by: Shiwei Zhang --- specs/directory.md | 43 +++++++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/specs/directory.md b/specs/directory.md index 1b13988c0..6e9c1094e 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -8,7 +8,7 @@ The `notation` CLI requires local file systems support for the following compone - Trust stores - Trust policies - Signature caches -- Local key store +- Signing key store This documentation specifies the recommended directory structure for those components. @@ -58,25 +58,28 @@ The overall directory structure for `notation` is summarized as follows. ``` {BIN} └── notation +{CACHE} +└── notation + └── signature + └── {manifest-digest-algorithm} + └── {manifest-digest} + └── {signature-digest-algorithm} + └── {signature-digest}.sig {CONFIG} └── notation ├── config.json - ├── private - │   ├── {key-name}.crt - │   └── {key-name}.key + ├── signing + │   ├── certificates + │   │   └── {key-name}.crt + │   ├── keys + │   │   └── {key-name}.pem + │   └── keys.json └── trust ├── policy.json └── store └── {trust-store-type} └── {named-store} └── {cert-file} -{CACHE} -└── notation - └── signature - └── {manifest-digest-algorithm} - └── {manifest-digest} - └── {signature-digest-algorithm} - └── {signature-digest}.sig {LIBEXEC} └── notation └── plugins @@ -144,16 +147,24 @@ or in a hierarchical view └── {signature-digest}.sig ``` -### Local key store +### Signing key store + +Developers sign artifacts using local private keys with associated certificate chain. The signing key information is tracked in a JSON file at + +``` +{CONFIG}/notation/signing/keys.json +``` + +Developers SHOULD consider safe places to store the passphrase-protected key and certificate pairs, or opt to remote signing. -Developers sign artifacts using local private keys with associated certificate chain. The default directory structure for testing purpose is suggested as follows. +For testing purpose, the following directory structure is suggested. ``` -{CONFIG}/notation/private/{key-name}.crt -{CONFIG}/notation/private/{key-name}.key +{CONFIG}/notation/signing/certificates/{key-name}.crt +{CONFIG}/notation/signing/keys/{key-name}.pem ``` -Developers SHOULD consider safer places to store the passphrase-protected key and certificate pair, or opt to remote signing. +Since `keys.json` takes references in absolute paths, it is not required to copy the private keys and certificates used for signing to the above directory structure. [References]:: From 14c434bb3820bc7a23fe7f8cfdc83b4f004a8b86 Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Fri, 13 May 2022 13:19:47 +0800 Subject: [PATCH 03/12] add examples Signed-off-by: Shiwei Zhang --- specs/directory.md | 198 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 197 insertions(+), 1 deletion(-) diff --git a/specs/directory.md b/specs/directory.md index 6e9c1094e..1883cd70f 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -155,7 +155,7 @@ Developers sign artifacts using local private keys with associated certificate c {CONFIG}/notation/signing/keys.json ``` -Developers SHOULD consider safe places to store the passphrase-protected key and certificate pairs, or opt to remote signing. +Since the signing key store is user-specific, the system level `{CONFIG}` is not recommended. Developers SHOULD consider safe places to store the passphrase-protected key and certificate pairs, or opt to remote signing. For testing purpose, the following directory structure is suggested. @@ -166,6 +166,202 @@ For testing purpose, the following directory structure is suggested. Since `keys.json` takes references in absolute paths, it is not required to copy the private keys and certificates used for signing to the above directory structure. +## Examples + +Examples are shown on various platforms where the user `exampleuser` overrides the `notation` config and the trust policy. + +### Unix + +``` +/ +├── etc +│   └── notation +│   ├── config.json +│   └── trust +│   ├── policy.json +│   └── store +│   ├── ca +│   │   ├── acme-rockets +│   │   │   ├── cert1.pem +│   │   │   └── cert2.pem +│   │   └── wabbit-networks +│   │   └── cert3.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert1.pem +├── home +│   └── exampleuser +│   ├── .cache +│   │   └── notation +│   │   └── signature +│   │   └── sha256 +│   │   └── 05b3abf2579a5eb66403cd78be557fd860633a1fe2103c7642030defe32c657f +│   │   └── sha256 +│   │   ├── 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae.sig +│   │   ├── b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9.sig +│   │   └── fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9.sig +│   └── .config +│   └── notation +│   ├── config.json +│   ├── plugins +│   │   └── com.example.bar +│   │   └── notation-com.example.bar +│   ├── signing +│   │   ├── certificates +│   │   │   ├── dev.crt +│   │   │   └── test.crt +│   │   ├── keys +│   │   │   ├── dev.pem +│   │   │   └── test.pem +│   │   └── keys.json +│   └── trust +│   ├── policy.json +│   └── store +│   ├── ca +│   │   └── acme-rockets +│   │   └── cert4.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert2.pem +└── usr + ├── bin + │   └── notation + └── libexec + └── notation + └── plugins + └── com.example.foo + └── notation-com.example.foo +``` + +### Windows + +``` +C:. +├── Program Files +│   └── notation +│   ├── bin +│   │   └── notation +│   └── plugins +│   └── com.example.foo +│   └── notation-com.example.foo +├── ProgramData +│   └── notation +│   ├── config.json +│   └── trust +│   ├── policy.json +│   └── store +│   ├── ca +│   │   ├── acme-rockets +│   │   │   ├── cert1.pem +│   │   │   └── cert2.pem +│   │   └── wabbit-networks +│   │   └── cert3.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert1.pem +└── Users + └── exampleuser + └── AppData + ├── Local + │   └── notation + │   └── signature + │   └── sha256 + │   └── 05b3abf2579a5eb66403cd78be557fd860633a1fe2103c7642030defe32c657f + │   └── sha256 + │   ├── 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae.sig + │   ├── b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9.sig + │   └── fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9.sig + └── Roaming + └── notation + ├── config.json + ├── plugins + │   └── com.example.bar + │   └── notation-com.example.bar + ├── signing + │   ├── certificates + │   │   ├── dev.crt + │   │   └── test.crt + │   ├── keys + │   │   ├── dev.pem + │   │   └── test.pem + │   └── keys.json + └── trust + ├── policy.json + └── store + ├── ca + │   └── acme-rockets + │   └── cert4.pem + └── tsa + └── publicly-trusted-tsa + └── tsa-cert2.pem +``` + +### Darwin + +``` +/ +├── Library +│   └── Application Support +│   └── notation +│   ├── config.json +│   └── trust +│   ├── policy.json +│   └── store +│   ├── ca +│   │   ├── acme-rockets +│   │   │   ├── cert1.pem +│   │   │   └── cert2.pem +│   │   └── wabbit-networks +│   │   └── cert3.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert1.pem +├── Users +│   └── exampleuser +│   └── Library +│   ├── Application Support +│   │   └── notation +│   │   ├── config.json +│   │   ├── plugins +│   │   │   └── com.example.bar +│   │   │   └── notation-com.example.bar +│   │   ├── signing +│   │   │   ├── certificates +│   │   │   │   ├── dev.crt +│   │   │   │   └── test.crt +│   │   │   ├── keys +│   │   │   │   ├── dev.pem +│   │   │   │   └── test.pem +│   │   │   └── keys.json +│   │   └── trust +│   │   ├── policy.json +│   │   └── store +│   │   ├── ca +│   │   │   └── acme-rockets +│   │   │   └── cert4.pem +│   │   └── tsa +│   │   └── publicly-trusted-tsa +│   │   └── tsa-cert2.pem +│   └── Caches +│   └── notation +│   └── signature +│   └── sha256 +│   └── 05b3abf2579a5eb66403cd78be557fd860633a1fe2103c7642030defe32c657f +│   └── sha256 +│   ├── 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae.sig +│   ├── b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9.sig +│   └── fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9.sig +└── usr + └── local + ├── bin + │   └── notation + └── lib + └── notation + └── plugins + └── com.example.foo + └── notation-com.example.foo +``` + [References]:: [FHS]: https://refspecs.linuxfoundation.org/fhs.shtml "Filesystem Hierarchy Standard" From 2b81b2f48f29c38e875770ea9a3e812a8f1bf3c3 Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Fri, 13 May 2022 13:36:55 +0800 Subject: [PATCH 04/12] add link for plugins Signed-off-by: Shiwei Zhang --- specs/directory.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specs/directory.md b/specs/directory.md index 1883cd70f..50d7d0876 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -97,7 +97,7 @@ The path for the `notation` binary is ### Plugin -Plugin are binaries not meant to be executed directly by users' shell or scripts. The path of a plugin follows the pattern below. +[Plugins][Plugin] are binaries not meant to be executed directly by users' shell or scripts. The path of a plugin follows the pattern below. ``` {LIBEXEC}/notation/plugins/{plugin-name}/notation-{plugin-name} @@ -370,5 +370,6 @@ C:. [AS]: https://docs.microsoft.com/windows/apps/design/app-settings/store-and-retrieve-app-data "App Settings" [macOS_FS]: https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW14 "macOS File System" [SIP]: https://support.apple.com/HT204899 "System Integrity Protection" +[Plugin]: https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md "Notation Extensibility for Signing and Verification" [TS]: https://github.com/notaryproject/notaryproject/blob/main/trust-store-trust-policy-specification.md#trust-store "Trust Store" [TP]: https://github.com/notaryproject/notaryproject/blob/main/trust-store-trust-policy-specification.md#trust-policy "Trust Policy" From 6e130ed81d3a652b776f2f26eaa93f2f676013f8 Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Fri, 13 May 2022 13:40:41 +0800 Subject: [PATCH 05/12] refine format Signed-off-by: Shiwei Zhang --- specs/directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/directory.md b/specs/directory.md index 50d7d0876..e09d8fca9 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -147,7 +147,7 @@ or in a hierarchical view └── {signature-digest}.sig ``` -### Signing key store +### Signing Key Store Developers sign artifacts using local private keys with associated certificate chain. The signing key information is tracked in a JSON file at From e412cdf3574f9229f29fae97a47930363a989afa Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Mon, 16 May 2022 19:59:47 +0800 Subject: [PATCH 06/12] .exe for Windows Signed-off-by: Shiwei Zhang --- specs/directory.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/specs/directory.md b/specs/directory.md index e09d8fca9..3c981b0f3 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -95,6 +95,12 @@ The path for the `notation` binary is {BIN}/notation ``` +On Windows, the `.exe` extension is required for executables. + +``` +{BIN}/notation.exe +``` + ### Plugin [Plugins][Plugin] are binaries not meant to be executed directly by users' shell or scripts. The path of a plugin follows the pattern below. @@ -103,6 +109,12 @@ The path for the `notation` binary is {LIBEXEC}/notation/plugins/{plugin-name}/notation-{plugin-name} ``` +On Windows, the `.exe` extension is required for executables. + +``` +{LIBEXEC}/notation/plugins/{plugin-name}/notation-{plugin-name}.exe +``` + ### General Configuration The path of the general configuration file of the `notation` CLI is @@ -240,10 +252,10 @@ C:. ├── Program Files │   └── notation │   ├── bin -│   │   └── notation +│   │   └── notation.exe │   └── plugins │   └── com.example.foo -│   └── notation-com.example.foo +│   └── notation-com.example.foo.exe ├── ProgramData │   └── notation │   ├── config.json @@ -276,7 +288,7 @@ C:. ├── config.json ├── plugins │   └── com.example.bar - │   └── notation-com.example.bar + │   └── notation-com.example.bar.exe ├── signing │   ├── certificates │   │   ├── dev.crt From 537975b3d92badd97e4150bbf07c8e1fe8ec179a Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Wed, 8 Jun 2022 12:01:29 +0800 Subject: [PATCH 07/12] specify default XDG folders Signed-off-by: Shiwei Zhang --- specs/directory.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specs/directory.md b/specs/directory.md index 3c981b0f3..4f0bb4ac0 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -49,6 +49,8 @@ Default directory paths for various operating systems at user level are specifie | `CONFIG` | `$XDG_CONFIG_HOME` | `%AppData%` | `~/Library/Application Support` | | `CACHE` | `$XDG_CACHE_HOME` | `%LocalAppData%` | `~/Library/Caches` | +On Unix, `$XDG_CONFIG_HOME` is default to `~/.config` and `$XDG_CACHE_HOME` is default to `~/.cache` if XDG environment variables are empty. + There is no default `BIN` path at user level since the `notation` binary can be put anywhere as long as it in the `PATH` environment variable. Common directories on Unix/Darwin are `~/bin` and `~/.local/bin` where manual `PATH` update by users may be required. ## Structure From 544fb3333c1383011cdf4f60494cb23260587831 Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Wed, 8 Jun 2022 20:50:38 +0800 Subject: [PATCH 08/12] update example Signed-off-by: Shiwei Zhang --- specs/directory.md | 96 ++++++++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 45 deletions(-) diff --git a/specs/directory.md b/specs/directory.md index 4f0bb4ac0..911f69b04 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -194,15 +194,16 @@ Examples are shown on various platforms where the user `exampleuser` overrides t │   └── trust │   ├── policy.json │   └── store -│   ├── ca -│   │   ├── acme-rockets -│   │   │   ├── cert1.pem -│   │   │   └── cert2.pem -│   │   └── wabbit-networks -│   │   └── cert3.pem -│   └── tsa -│   └── publicly-trusted-tsa -│   └── tsa-cert1.pem +│   └── x509 +│   ├── ca +│   │   ├── acme-rockets +│   │   │   ├── cert1.pem +│   │   │   └── cert2.pem +│   │   └── wabbit-networks +│   │   └── cert3.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert1.pem ├── home │   └── exampleuser │   ├── .cache @@ -231,12 +232,13 @@ Examples are shown on various platforms where the user `exampleuser` overrides t │   └── trust │   ├── policy.json │   └── store -│   ├── ca -│   │   └── acme-rockets -│   │   └── cert4.pem -│   └── tsa -│   └── publicly-trusted-tsa -│   └── tsa-cert2.pem +│   └── x509 +│   ├── ca +│   │   └── acme-rockets +│   │   └── cert4.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert2.pem └── usr ├── bin │   └── notation @@ -264,15 +266,16 @@ C:. │   └── trust │   ├── policy.json │   └── store -│   ├── ca -│   │   ├── acme-rockets -│   │   │   ├── cert1.pem -│   │   │   └── cert2.pem -│   │   └── wabbit-networks -│   │   └── cert3.pem -│   └── tsa -│   └── publicly-trusted-tsa -│   └── tsa-cert1.pem +│   └── x509 +│   ├── ca +│   │   ├── acme-rockets +│   │   │   ├── cert1.pem +│   │   │   └── cert2.pem +│   │   └── wabbit-networks +│   │   └── cert3.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert1.pem └── Users └── exampleuser └── AppData @@ -302,12 +305,13 @@ C:. └── trust ├── policy.json └── store - ├── ca - │   └── acme-rockets - │   └── cert4.pem - └── tsa - └── publicly-trusted-tsa - └── tsa-cert2.pem + └── x509 + ├── ca + │   └── acme-rockets + │   └── cert4.pem + └── tsa + └── publicly-trusted-tsa + └── tsa-cert2.pem ``` ### Darwin @@ -321,15 +325,16 @@ C:. │   └── trust │   ├── policy.json │   └── store -│   ├── ca -│   │   ├── acme-rockets -│   │   │   ├── cert1.pem -│   │   │   └── cert2.pem -│   │   └── wabbit-networks -│   │   └── cert3.pem -│   └── tsa -│   └── publicly-trusted-tsa -│   └── tsa-cert1.pem +│   └── x509 +│   ├── ca +│   │   ├── acme-rockets +│   │   │   ├── cert1.pem +│   │   │   └── cert2.pem +│   │   └── wabbit-networks +│   │   └── cert3.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert1.pem ├── Users │   └── exampleuser │   └── Library @@ -350,12 +355,13 @@ C:. │   │   └── trust │   │   ├── policy.json │   │   └── store -│   │   ├── ca -│   │   │   └── acme-rockets -│   │   │   └── cert4.pem -│   │   └── tsa -│   │   └── publicly-trusted-tsa -│   │   └── tsa-cert2.pem +│   │   └── x509 +│   │   ├── ca +│   │   │   └── acme-rockets +│   │   │   └── cert4.pem +│   │   └── tsa +│   │   └── publicly-trusted-tsa +│   │   └── tsa-cert2.pem │   └── Caches │   └── notation │   └── signature From bb8d0d22ea5ca91df059e663be1d16d7499aeaea Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Wed, 8 Jun 2022 21:15:04 +0800 Subject: [PATCH 09/12] rename signature to signatures Signed-off-by: Shiwei Zhang --- specs/directory.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specs/directory.md b/specs/directory.md index 911f69b04..b532cd6ff 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -62,7 +62,7 @@ The overall directory structure for `notation` is summarized as follows. └── notation {CACHE} └── notation - └── signature + └── signatures └── {manifest-digest-algorithm} └── {manifest-digest} └── {signature-digest-algorithm} @@ -146,7 +146,7 @@ The path of the [Trust Policy][TP] file is The signatures are cached to optimize the network traffic. The path of a cached signature for a certain manifest follows the pattern below. ``` -{CACHE}/notation/signature/{manifest-digest-algorithm}/{manifest-digest}/{signature-digest-algorithm}/{signature-digest}.sig +{CACHE}/notation/signatures/{manifest-digest-algorithm}/{manifest-digest}/{signature-digest-algorithm}/{signature-digest}.sig ``` or in a hierarchical view @@ -154,7 +154,7 @@ or in a hierarchical view ``` {CACHE} └── notation - └── signature + └── signatures └── {manifest-digest-algorithm} └── {manifest-digest} └── {signature-digest-algorithm} @@ -208,7 +208,7 @@ Examples are shown on various platforms where the user `exampleuser` overrides t │   └── exampleuser │   ├── .cache │   │   └── notation -│   │   └── signature +│   │   └── signatures │   │   └── sha256 │   │   └── 05b3abf2579a5eb66403cd78be557fd860633a1fe2103c7642030defe32c657f │   │   └── sha256 @@ -281,7 +281,7 @@ C:. └── AppData ├── Local │   └── notation - │   └── signature + │   └── signatures │   └── sha256 │   └── 05b3abf2579a5eb66403cd78be557fd860633a1fe2103c7642030defe32c657f │   └── sha256 @@ -364,7 +364,7 @@ C:. │   │   └── tsa-cert2.pem │   └── Caches │   └── notation -│   └── signature +│   └── signatures │   └── sha256 │   └── 05b3abf2579a5eb66403cd78be557fd860633a1fe2103c7642030defe32c657f │   └── sha256 From c18c9011cd0686c628eeed486197f784d40fd1dc Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Tue, 14 Jun 2022 21:41:38 +0800 Subject: [PATCH 10/12] clarify signature blob Signed-off-by: Shiwei Zhang --- specs/directory.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/directory.md b/specs/directory.md index b532cd6ff..7af0c8f14 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -65,7 +65,7 @@ The overall directory structure for `notation` is summarized as follows. └── signatures └── {manifest-digest-algorithm} └── {manifest-digest} - └── {signature-digest-algorithm} + └── {signature-blob-digest-algorithm} └── {signature-digest}.sig {CONFIG} └── notation @@ -146,7 +146,7 @@ The path of the [Trust Policy][TP] file is The signatures are cached to optimize the network traffic. The path of a cached signature for a certain manifest follows the pattern below. ``` -{CACHE}/notation/signatures/{manifest-digest-algorithm}/{manifest-digest}/{signature-digest-algorithm}/{signature-digest}.sig +{CACHE}/notation/signatures/{manifest-digest-algorithm}/{manifest-digest}/{signature-blob-digest-algorithm}/{signature-digest}.sig ``` or in a hierarchical view @@ -157,7 +157,7 @@ or in a hierarchical view └── signatures └── {manifest-digest-algorithm} └── {manifest-digest} - └── {signature-digest-algorithm} + └── {signature-blob-digest-algorithm} └── {signature-digest}.sig ``` From 416b30ff98d01298706ea449f925b3282da7d063 Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Tue, 14 Jun 2022 21:42:53 +0800 Subject: [PATCH 11/12] reword Signed-off-by: Shiwei Zhang --- specs/directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/directory.md b/specs/directory.md index 7af0c8f14..004d2bfcb 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -143,7 +143,7 @@ The path of the [Trust Policy][TP] file is ### Signature Caches -The signatures are cached to optimize the network traffic. The path of a cached signature for a certain manifest follows the pattern below. +The signatures are cached to optimize the network traffic. The path of cached signatures for a certain target manifest (e.g. an image manifest) follows the pattern below. ``` {CACHE}/notation/signatures/{manifest-digest-algorithm}/{manifest-digest}/{signature-blob-digest-algorithm}/{signature-digest}.sig From 37c36505062bd035f3c9cd25470b64408793ac55 Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Tue, 14 Jun 2022 22:03:32 +0800 Subject: [PATCH 12/12] update struct Signed-off-by: Shiwei Zhang --- specs/directory.md | 207 +++++++++++++++++++++------------------------ 1 file changed, 96 insertions(+), 111 deletions(-) diff --git a/specs/directory.md b/specs/directory.md index 004d2bfcb..074b1cc72 100644 --- a/specs/directory.md +++ b/specs/directory.md @@ -70,18 +70,15 @@ The overall directory structure for `notation` is summarized as follows. {CONFIG} └── notation ├── config.json - ├── signing - │   ├── certificates - │   │   └── {key-name}.crt - │   ├── keys - │   │   └── {key-name}.pem - │   └── keys.json - └── trust - ├── policy.json - └── store - └── {trust-store-type} - └── {named-store} - └── {cert-file} + ├── localkeys + │   ├── {key-name}.crt + │   └── {key-name}.pem + ├── signingkeys.json + ├── trustpolicy.json + └── truststore + └── {trust-store-type} + └── {named-store} + └── {cert-file} {LIBEXEC} └── notation └── plugins @@ -130,7 +127,7 @@ The path of the general configuration file of the `notation` CLI is The path of a certificate file in a [Trust Store][TS] follows the pattern of ``` -{CONFIG}/notation/trust/store/{trust-store-type}/{named-store}/{cert-file} +{CONFIG}/notation/truststore/{trust-store-type}/{named-store}/{cert-file} ``` ### Trust Policy @@ -138,7 +135,7 @@ The path of a certificate file in a [Trust Store][TS] follows the pattern of The path of the [Trust Policy][TP] file is ``` -{CONFIG}/notation/trust/policy.json +{CONFIG}/notation/trustpolicy.json ``` ### Signature Caches @@ -166,7 +163,7 @@ or in a hierarchical view Developers sign artifacts using local private keys with associated certificate chain. The signing key information is tracked in a JSON file at ``` -{CONFIG}/notation/signing/keys.json +{CONFIG}/notation/signingkeys.json ``` Since the signing key store is user-specific, the system level `{CONFIG}` is not recommended. Developers SHOULD consider safe places to store the passphrase-protected key and certificate pairs, or opt to remote signing. @@ -174,11 +171,11 @@ Since the signing key store is user-specific, the system level `{CONFIG}` is not For testing purpose, the following directory structure is suggested. ``` -{CONFIG}/notation/signing/certificates/{key-name}.crt -{CONFIG}/notation/signing/keys/{key-name}.pem +{CONFIG}/notation/localkeys/{key-name}.crt +{CONFIG}/notation/localkeys/{key-name}.pem ``` -Since `keys.json` takes references in absolute paths, it is not required to copy the private keys and certificates used for signing to the above directory structure. +Since `signingkeys.json` takes references in absolute paths, it is not required to copy the private keys and certificates used for signing to the above directory structure. ## Examples @@ -191,19 +188,18 @@ Examples are shown on various platforms where the user `exampleuser` overrides t ├── etc │   └── notation │   ├── config.json -│   └── trust -│   ├── policy.json -│   └── store -│   └── x509 -│   ├── ca -│   │   ├── acme-rockets -│   │   │   ├── cert1.pem -│   │   │   └── cert2.pem -│   │   └── wabbit-networks -│   │   └── cert3.pem -│   └── tsa -│   └── publicly-trusted-tsa -│   └── tsa-cert1.pem +│   ├── trustpolicy.json +│   └── truststore +│   └── x509 +│   ├── ca +│   │   ├── acme-rockets +│   │   │   ├── cert1.pem +│   │   │   └── cert2.pem +│   │   └── wabbit-networks +│   │   └── cert3.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert1.pem ├── home │   └── exampleuser │   ├── .cache @@ -218,27 +214,24 @@ Examples are shown on various platforms where the user `exampleuser` overrides t │   └── .config │   └── notation │   ├── config.json +│   ├── localkeys +│   │   ├── dev.crt +│   │   ├── dev.pem +│   │   ├── test.crt +│   │   └── test.pem │   ├── plugins │   │   └── com.example.bar │   │   └── notation-com.example.bar -│   ├── signing -│   │   ├── certificates -│   │   │   ├── dev.crt -│   │   │   └── test.crt -│   │   ├── keys -│   │   │   ├── dev.pem -│   │   │   └── test.pem -│   │   └── keys.json -│   └── trust -│   ├── policy.json -│   └── store -│   └── x509 -│   ├── ca -│   │   └── acme-rockets -│   │   └── cert4.pem -│   └── tsa -│   └── publicly-trusted-tsa -│   └── tsa-cert2.pem +│   ├── signingkeys.json +│   ├── trustpolicy.json +│   └── truststore +│   └── x509 +│   ├── ca +│   │   └── acme-rockets +│   │   └── cert4.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert2.pem └── usr ├── bin │   └── notation @@ -263,19 +256,18 @@ C:. ├── ProgramData │   └── notation │   ├── config.json -│   └── trust -│   ├── policy.json -│   └── store -│   └── x509 -│   ├── ca -│   │   ├── acme-rockets -│   │   │   ├── cert1.pem -│   │   │   └── cert2.pem -│   │   └── wabbit-networks -│   │   └── cert3.pem -│   └── tsa -│   └── publicly-trusted-tsa -│   └── tsa-cert1.pem +│   ├── trustpolicy.json +│   └── truststore +│   └── x509 +│   ├── ca +│   │   ├── acme-rockets +│   │   │   ├── cert1.pem +│   │   │   └── cert2.pem +│   │   └── wabbit-networks +│   │   └── cert3.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert1.pem └── Users └── exampleuser └── AppData @@ -291,27 +283,24 @@ C:. └── Roaming └── notation ├── config.json + ├── localkeys + │   ├── dev.crt + │   ├── dev.pem + │   ├── test.crt + │   └── test.pem ├── plugins │   └── com.example.bar │   └── notation-com.example.bar.exe - ├── signing - │   ├── certificates - │   │   ├── dev.crt - │   │   └── test.crt - │   ├── keys - │   │   ├── dev.pem - │   │   └── test.pem - │   └── keys.json - └── trust - ├── policy.json - └── store - └── x509 - ├── ca - │   └── acme-rockets - │   └── cert4.pem - └── tsa - └── publicly-trusted-tsa - └── tsa-cert2.pem + ├── signingkeys.json + ├── trustpolicy.json + └── truststore + └── x509 + ├── ca + │   └── acme-rockets + │   └── cert4.pem + └── tsa + └── publicly-trusted-tsa + └── tsa-cert2.pem ``` ### Darwin @@ -322,46 +311,42 @@ C:. │   └── Application Support │   └── notation │   ├── config.json -│   └── trust -│   ├── policy.json -│   └── store -│   └── x509 -│   ├── ca -│   │   ├── acme-rockets -│   │   │   ├── cert1.pem -│   │   │   └── cert2.pem -│   │   └── wabbit-networks -│   │   └── cert3.pem -│   └── tsa -│   └── publicly-trusted-tsa -│   └── tsa-cert1.pem +│   ├── trustpolicy.json +│   └── truststore +│   └── x509 +│   ├── ca +│   │   ├── acme-rockets +│   │   │   ├── cert1.pem +│   │   │   └── cert2.pem +│   │   └── wabbit-networks +│   │   └── cert3.pem +│   └── tsa +│   └── publicly-trusted-tsa +│   └── tsa-cert1.pem ├── Users │   └── exampleuser │   └── Library │   ├── Application Support │   │   └── notation │   │   ├── config.json +│   │   ├── localkeys +│   │   │   ├── dev.crt +│   │   │   ├── dev.pem +│   │   │   ├── test.crt +│   │   │   └── test.pem │   │   ├── plugins │   │   │   └── com.example.bar │   │   │   └── notation-com.example.bar -│   │   ├── signing -│   │   │   ├── certificates -│   │   │   │   ├── dev.crt -│   │   │   │   └── test.crt -│   │   │   ├── keys -│   │   │   │   ├── dev.pem -│   │   │   │   └── test.pem -│   │   │   └── keys.json -│   │   └── trust -│   │   ├── policy.json -│   │   └── store -│   │   └── x509 -│   │   ├── ca -│   │   │   └── acme-rockets -│   │   │   └── cert4.pem -│   │   └── tsa -│   │   └── publicly-trusted-tsa -│   │   └── tsa-cert2.pem +│   │   ├── signingkeys.json +│   │   ├── trustpolicy.json +│   │   └── truststore +│   │   └── x509 +│   │   ├── ca +│   │   │   └── acme-rockets +│   │   │   └── cert4.pem +│   │   └── tsa +│   │   └── publicly-trusted-tsa +│   │   └── tsa-cert2.pem │   └── Caches │   └── notation │   └── signatures