From 1084b49bf2473853f4766256256df4ef09110e25 Mon Sep 17 00:00:00 2001 From: marinamoore Date: Mon, 15 Jun 2020 14:41:56 -0700 Subject: [PATCH 1/4] add initial key management scenarios Signed-off-by: marinamoore Signed-off-by: marinamoore --- key-management-scenarios.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 key-management-scenarios.md diff --git a/key-management-scenarios.md b/key-management-scenarios.md new file mode 100644 index 00000000..00e38e87 --- /dev/null +++ b/key-management-scenarios.md @@ -0,0 +1,19 @@ +# Notary Key Management Scenarios +In order to allow for end to end signing of artifacts, Notary v2 will require the use of cryptographic keys. These scenarios define how these keys will be generated, distributed, and trusted in Notary v2. + +## Scenarios + +### Scenario #1: A developer signs a package for the first time +The first time a developer signs a package, they will need to set up a signing key and their local environment. + 1. Generate a developer signing key. + 1. Create a local repository that delegates to the developer key notary-tool --create-local-repository, notary-tool --delegate developer-key.pub + +### Scenario #2: A developer is given permission to upload to a registry (for the first time) +The first time a developer uploads to a registry, they need to establish that they are a trusted developer. + 1. Add the developer key to delegating metadata on the registry. The delegating metadata may be top-level targets metadata, an organization-hosted targets metadata file (see TAP 13 for how organization-specific targets metadata can be used), or a different targets metadata file. + +### Scenario #3: A developer updates their signing key +In the event of a compromised or lost key, a developer may need to switch to a new signing key. + 1. The developer will generate a new signing key. + 1. The new developer key will need to be added to the delegating targets metadata. + 1. The previous developer key should no longer be trusted. From 1937f3ff72d881b7f1d486951e62fa0951b1db8e Mon Sep 17 00:00:00 2001 From: marinamoore Date: Sun, 21 Jun 2020 12:01:29 -0700 Subject: [PATCH 2/4] Make descriptions more generic Signed-off-by: marinamoore Signed-off-by: marinamoore --- key-management-scenarios.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/key-management-scenarios.md b/key-management-scenarios.md index 00e38e87..c03d94fd 100644 --- a/key-management-scenarios.md +++ b/key-management-scenarios.md @@ -6,14 +6,15 @@ In order to allow for end to end signing of artifacts, Notary v2 will require th ### Scenario #1: A developer signs a package for the first time The first time a developer signs a package, they will need to set up a signing key and their local environment. 1. Generate a developer signing key. - 1. Create a local repository that delegates to the developer key notary-tool --create-local-repository, notary-tool --delegate developer-key.pub + 1. Create a local environment that delegates to the developer key for testing. + 1. The developer signs local content. ### Scenario #2: A developer is given permission to upload to a registry (for the first time) The first time a developer uploads to a registry, they need to establish that they are a trusted developer. - 1. Add the developer key to delegating metadata on the registry. The delegating metadata may be top-level targets metadata, an organization-hosted targets metadata file (see TAP 13 for how organization-specific targets metadata can be used), or a different targets metadata file. + 1. Add the developer key to delegating party on the registry. There may be a single delegating party on a registry, or multiple that are trusted for different images. ### Scenario #3: A developer updates their signing key In the event of a compromised or lost key, a developer may need to switch to a new signing key. 1. The developer will generate a new signing key. - 1. The new developer key will need to be added to the delegating targets metadata. + 1. The new developer key will need to be added to the delegating party on the registry. 1. The previous developer key should no longer be trusted. From d85d1c93f5d7833365950834d6596d75d8e1fea9 Mon Sep 17 00:00:00 2001 From: marinamoore Date: Mon, 22 Jun 2020 09:10:49 -0700 Subject: [PATCH 3/4] images -> artifacts Signed-off-by: marinamoore --- key-management-scenarios.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/key-management-scenarios.md b/key-management-scenarios.md index c03d94fd..e252684f 100644 --- a/key-management-scenarios.md +++ b/key-management-scenarios.md @@ -11,7 +11,7 @@ The first time a developer signs a package, they will need to set up a signing k ### Scenario #2: A developer is given permission to upload to a registry (for the first time) The first time a developer uploads to a registry, they need to establish that they are a trusted developer. - 1. Add the developer key to delegating party on the registry. There may be a single delegating party on a registry, or multiple that are trusted for different images. + 1. Add the developer key to delegating party on the registry. There may be a single delegating party on a registry, or multiple that are trusted for different artifacts. ### Scenario #3: A developer updates their signing key In the event of a compromised or lost key, a developer may need to switch to a new signing key. From 81f434dd991e8a1f4dafa5fab4c3e474ca869ac5 Mon Sep 17 00:00:00 2001 From: marinamoore Date: Wed, 2 Sep 2020 11:46:32 -0700 Subject: [PATCH 4/4] Add clarifications Signed-off-by: marinamoore --- key-management-scenarios.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/key-management-scenarios.md b/key-management-scenarios.md index e252684f..53085662 100644 --- a/key-management-scenarios.md +++ b/key-management-scenarios.md @@ -9,12 +9,12 @@ The first time a developer signs a package, they will need to set up a signing k 1. Create a local environment that delegates to the developer key for testing. 1. The developer signs local content. -### Scenario #2: A developer is given permission to upload to a registry (for the first time) -The first time a developer uploads to a registry, they need to establish that they are a trusted developer. +### Scenario #2: A developer is given permission to push artifacts to a registry (for the first time) +The first time a developer pushes an artifact to a registry, they need to establish that their keys are trusted for the artifacts they push. 1. Add the developer key to delegating party on the registry. There may be a single delegating party on a registry, or multiple that are trusted for different artifacts. ### Scenario #3: A developer updates their signing key In the event of a compromised or lost key, a developer may need to switch to a new signing key. 1. The developer will generate a new signing key. 1. The new developer key will need to be added to the delegating party on the registry. - 1. The previous developer key should no longer be trusted. + 1. The compromised developer key should no longer be trusted.