From 865cb5a141127e621bd9af1d30c2021fbd59d5b5 Mon Sep 17 00:00:00 2001 From: Aaron Weitekamp Date: Tue, 4 Oct 2016 22:38:18 -0400 Subject: [PATCH 1/2] Signature file layout specification --- docs/signature-layout.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs/signature-layout.md diff --git a/docs/signature-layout.md b/docs/signature-layout.md new file mode 100644 index 0000000000..174110c6b8 --- /dev/null +++ b/docs/signature-layout.md @@ -0,0 +1,29 @@ +# Signature File Layout + +A common file layout for storing and serving signatures provides a consistent way to reference image signatures. Signatures on a filesystem or a web server shall use this common layout. Signatures stored in a REST API are not required to use this common layout. + +## Specification + +**SCHEME://[URI]/PATH_PREFIX/REGISTRY/REPOSITORY/IMAGE@MANIFEST_DIGEST/signature-INT** + +* **SCHEME**: The transport scheme, e.g. **file://** or **https://** +* **URI**: For remote transport schemes, the signature server URI, e.g. **example.com** +* **PATH_PREFIX**: The path to the base of the registry directory +* **REGISTRY**: The registry URI and optional port, e.g. **registry.example.com:5000** +* **REPOSITORY**: The repository namespace. May occur multiple times for registries that support multiple repository namespaces. +* **IMAGE**: The name of the image +* **MANIFEST_DIGEST**: The value of the manifest digest, including the hash function and hash, e.g. **sha256:HASH** +* **INT**: An integer of the signature starting with 1. For multiple signatures increment by 1, e.g. **signature-1**, **signature-2**. + +## Examples + +1. A reference to a local file signature + + file:///var/lib/atomic/sigstore/registry.example.com:5000/acme/myimage@sha256:b1c302ecc8e21804a288491cedfed9bd3db972ac8367ccab7340b33ecd1cb8eb/signature-1 +1. A reference to a signature on a web server + + https://sigs.example.com/signatures/registry.example.com:5000/acme/myimage@sha256:b1c302ecc8e21804a288491cedfed9bd3db972ac8367ccab7340b33ecd1cb8eb/signature-1 +1. A reference to two signatures on a web server + + https://sigs.example.com/signatures/registry.example.com:5000/acme/myimage@sha256:b1c302ecc8e21804a288491cedfed9bd3db972ac8367ccab7340b33ecd1cb8eb/signature-1 + https://sigs.example.com/signatures/registry.example.com:5000/acme/myimage@sha256:b1c302ecc8e21804a288491cedfed9bd3db972ac8367ccab7340b33ecd1cb8eb/signature-2 From 4a38060279511d7a0219aaad8bf316203bd27645 Mon Sep 17 00:00:00 2001 From: Aaron Weitekamp Date: Fri, 14 Oct 2016 11:00:47 -0400 Subject: [PATCH 2/2] updated based on review feedback Signed-off-by: Aaron Weitekamp --- docs/signature-layout.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/signature-layout.md b/docs/signature-layout.md index 174110c6b8..3b44dbed04 100644 --- a/docs/signature-layout.md +++ b/docs/signature-layout.md @@ -4,14 +4,16 @@ A common file layout for storing and serving signatures provides a consistent wa ## Specification -**SCHEME://[URI]/PATH_PREFIX/REGISTRY/REPOSITORY/IMAGE@MANIFEST_DIGEST/signature-INT** - -* **SCHEME**: The transport scheme, e.g. **file://** or **https://** -* **URI**: For remote transport schemes, the signature server URI, e.g. **example.com** -* **PATH_PREFIX**: The path to the base of the registry directory -* **REGISTRY**: The registry URI and optional port, e.g. **registry.example.com:5000** -* **REPOSITORY**: The repository namespace. May occur multiple times for registries that support multiple repository namespaces. -* **IMAGE**: The name of the image +This specification relies on [RFC3986](https://tools.ietf.org/html/rfc3986), focusing on defining a [path component](https://tools.ietf.org/html/rfc3986#section-3.3) to compose a concise URI reference to a signature. + +**SCHEME[AUTHORITY]/PATH_PREFIX/IMAGE@MANIFEST_DIGEST/signature-INT** + +**Definitions** + +* **SCHEME**: URI scheme per [RFC3986](https://tools.ietf.org/html/rfc3986#section-3.1), e.g. **file://** or **https://** +* **AUTHORITY**: An optional authority reference per [RFC3986](https://tools.ietf.org/html/rfc3986#section-3.2), e.g. **example.com** +* **PATH_PREFIX**: An arbitrary base path to the image component +* **IMAGE**: The name of the image per [v2 API](https://docs.docker.com/registry/spec/api/#/overview). This would typically take the form of registry/repository/image but is not required to have exactly three parts. There is no requirement to include a **:PORT** component but it should be included if part of the image reference. * **MANIFEST_DIGEST**: The value of the manifest digest, including the hash function and hash, e.g. **sha256:HASH** * **INT**: An integer of the signature starting with 1. For multiple signatures increment by 1, e.g. **signature-1**, **signature-2**. @@ -19,7 +21,7 @@ A common file layout for storing and serving signatures provides a consistent wa 1. A reference to a local file signature - file:///var/lib/atomic/sigstore/registry.example.com:5000/acme/myimage@sha256:b1c302ecc8e21804a288491cedfed9bd3db972ac8367ccab7340b33ecd1cb8eb/signature-1 + file:///var/lib/containers/signatures/registry.example.com:5000/acme/myimage@sha256:b1c302ecc8e21804a288491cedfed9bd3db972ac8367ccab7340b33ecd1cb8eb/signature-1 1. A reference to a signature on a web server https://sigs.example.com/signatures/registry.example.com:5000/acme/myimage@sha256:b1c302ecc8e21804a288491cedfed9bd3db972ac8367ccab7340b33ecd1cb8eb/signature-1 @@ -27,3 +29,7 @@ A common file layout for storing and serving signatures provides a consistent wa https://sigs.example.com/signatures/registry.example.com:5000/acme/myimage@sha256:b1c302ecc8e21804a288491cedfed9bd3db972ac8367ccab7340b33ecd1cb8eb/signature-1 https://sigs.example.com/signatures/registry.example.com:5000/acme/myimage@sha256:b1c302ecc8e21804a288491cedfed9bd3db972ac8367ccab7340b33ecd1cb8eb/signature-2 + +## Signature Indexing and Discovery + +There is no signature indexing mechanism or service defined. Signatures are obtained by iterating with increasing indexes, stopping at first missing index.