From 4ae46f06a17965bbc4552dbc0ac77728d0f10f50 Mon Sep 17 00:00:00 2001 From: Joshua Duffney Date: Thu, 26 Sep 2024 09:49:31 -0500 Subject: [PATCH 1/7] docs: nVersionCount support for KMP design doc Signed-off-by: Joshua Duffney --- docs/design/kmp-nversions.md | 41 ++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/design/kmp-nversions.md diff --git a/docs/design/kmp-nversions.md b/docs/design/kmp-nversions.md new file mode 100644 index 000000000..883dd7f5f --- /dev/null +++ b/docs/design/kmp-nversions.md @@ -0,0 +1,41 @@ +# nVersionCount support for Key Management Provider + +Author: Josh Duffney (@duffney) + +Tracked issues in scope: + +- https://github.com/ratify-project/ratify/issues/1751 + +Proposal ref: + +- https://github.com/ratify-project/ratify/blob/dev/docs/proposals/Automated-Certificate-and-Key-Updates.md + +## Problem Statement + +In version 1.3.0 and earlier, Ratify does not support the nVersionCount parameter for Key Management Provider (KMP) resources. This means that when a certificate or key is rotated, Ratify updates the cache with the new version and removes the previous one, which may not suit all use cases. + +For instance, if a user needs to retain the last three versions of a certificate or key in the cache, Ratify cannot meet this requirement without manually adjusting the KMP resource for each new version. + +By supporting nVersionCount, Ratify would allow users to specify how many versions of a certificate or key should be kept in the cache, eliminating the need for manual updates to the KMP resource. + +## Proposed Solution + +To address this challenge, this proposal suggests adding support for the `maxVersionCount` parameter to the KMP resource in Ratify. This parameter will allow users to specify the number of versions of a certificate or key that should be retained in the cache. + +When a new version of a certificate or key is created, Ratify will check the `maxVersionCount` parameter to determine how many versions should be retained in the cache. If the number of versions exceeds the specified count, Ratify will remove the oldest version from the cache. + +If a version is disabled, Ratify will remove it from the cache. This ensures that disabled versions are not retained in the cache, reducing the risk of using compromised keys or certificates being passed to the verifiers. + +## Implementation Details + +## Dev Work Items + +## Open Questions + +- If a version is disabled, should it be removed from the cache or retained based on the nVersionCount and marked as inactive\disabled? + - Retaining the disabled version would require changing the KMP data structure to hold a list of versions and their status. +- If a version is disabled, does that count towards the nVersionCount? For example, if nVersionCount is set to 3 and one of the versions is disabled, should Ratify retain the last three active versions or the last three versions, regardless of their status? +- What does the KMP status look like when multiple versions are retained in the cache? +- Should the inlined provider support nVersionCount? + +## Future Considerations From 1c31ebdbd8ecfe11be855502e93c664d688aed7e Mon Sep 17 00:00:00 2001 From: Joshua Duffney Date: Thu, 26 Sep 2024 09:53:41 -0500 Subject: [PATCH 2/7] mod: include implementation details Signed-off-by: Joshua Duffney --- docs/design/kmp-nversions.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/design/kmp-nversions.md b/docs/design/kmp-nversions.md index 883dd7f5f..af04cc90e 100644 --- a/docs/design/kmp-nversions.md +++ b/docs/design/kmp-nversions.md @@ -28,6 +28,10 @@ If a version is disabled, Ratify will remove it from the cache. This ensures tha ## Implementation Details +- Add the `maxVersionCount` parameter to the KMP resource in Ratify. +- Update the `azurekeyvalut` provider to support the `maxVersionCount` parameter +- Update the `GetCertificates` and `GetKeys` methods to respect the `maxVersionCount` parameter retriving multiple versions of the certificate or key. + ## Dev Work Items ## Open Questions From adf6c1f68cabcf60c406a9af506c7c669c9d5cac Mon Sep 17 00:00:00 2001 From: Joshua Duffney Date: Wed, 2 Oct 2024 10:27:32 -0500 Subject: [PATCH 3/7] mod: add kmp resource crd and status examples Signed-off-by: Joshua Duffney --- docs/design/kmp-nversions.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/design/kmp-nversions.md b/docs/design/kmp-nversions.md index af04cc90e..e884cc167 100644 --- a/docs/design/kmp-nversions.md +++ b/docs/design/kmp-nversions.md @@ -26,6 +26,42 @@ When a new version of a certificate or key is created, Ratify will check the `ma If a version is disabled, Ratify will remove it from the cache. This ensures that disabled versions are not retained in the cache, reducing the risk of using compromised keys or certificates being passed to the verifiers. +Example: AKV KMP resource with `maxVersionCount` parameter + +```yaml +apiVersion: config.ratify.deislabs.io/v1beta1 +kind: KeyManagementProvider +metadata: + name: keymanagementprovider-akv +spec: + type: azurekeyvault + refreshInterval: 1m + maxVersionCount: 3 + parameters: + vaultURI: https://yourkeyvault.vault.azure.net/ + certificates: + - name: yourCertName + version: yourCertVersion # Optional, fetch latest version if empty + tenantID: + clientID: +``` + +Example: AKV KMP resource status with multiple versions retained in the cache + +```yaml +Status: + Issuccess: true + Lastfetchedtime: 2024-10-02T14:58:54Z + Properties: + Certificates: + Last Refreshed: 2024-10-02T14:58:54Z + Name: yourCertName + Version: a1b2c3d4e5f67890abcdef1234567890 + Last Refreshed: 2024-10-02T14:58:54Z + Name: yourCertName + Version: 0ff373a9259c4578a247cfd7861a8805 +``` + ## Implementation Details - Add the `maxVersionCount` parameter to the KMP resource in Ratify. From f437e49875d5227a7ac7cc3dd0c71c2cf3f4ac5b Mon Sep 17 00:00:00 2001 From: Joshua Duffney Date: Wed, 2 Oct 2024 16:00:18 -0500 Subject: [PATCH 4/7] mod: added open questions Signed-off-by: Joshua Duffney --- docs/design/kmp-nversions.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/design/kmp-nversions.md b/docs/design/kmp-nversions.md index e884cc167..1655575c1 100644 --- a/docs/design/kmp-nversions.md +++ b/docs/design/kmp-nversions.md @@ -65,8 +65,11 @@ Status: ## Implementation Details - Add the `maxVersionCount` parameter to the KMP resource in Ratify. + - ensure the value cannot be less than 1 or a negative number - Update the `azurekeyvalut` provider to support the `maxVersionCount` parameter - Update the `GetCertificates` and `GetKeys` methods to respect the `maxVersionCount` parameter retriving multiple versions of the certificate or key. +- Update the `GetCertificates` and `GetKeys` methods to remove the oldest version from the cache if the number of versions exceeds the `maxVersionCount` parameter. +- Update the `GetCertificates` and `GetKeys` methods to remove disabled versions from the cache. ## Dev Work Items @@ -76,6 +79,7 @@ Status: - Retaining the disabled version would require changing the KMP data structure to hold a list of versions and their status. - If a version is disabled, does that count towards the nVersionCount? For example, if nVersionCount is set to 3 and one of the versions is disabled, should Ratify retain the last three active versions or the last three versions, regardless of their status? - What does the KMP status look like when multiple versions are retained in the cache? -- Should the inlined provider support nVersionCount? +- Should the existing KMP data structure be changed to group versions by key or certificate name? +- Should the KMP status return a flat list of versions or group them by key or certificate name? ## Future Considerations From c391f5b24d1a15e486b5a875701f1f1672863cd7 Mon Sep 17 00:00:00 2001 From: Joshua Duffney Date: Fri, 4 Oct 2024 11:35:01 -0500 Subject: [PATCH 5/7] mod: include community meeting discussion feedback Signed-off-by: Joshua Duffney --- docs/design/kmp-nversions.md | 39 +++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/docs/design/kmp-nversions.md b/docs/design/kmp-nversions.md index 1655575c1..f3c612931 100644 --- a/docs/design/kmp-nversions.md +++ b/docs/design/kmp-nversions.md @@ -36,12 +36,11 @@ metadata: spec: type: azurekeyvault refreshInterval: 1m - maxVersionCount: 3 parameters: vaultURI: https://yourkeyvault.vault.azure.net/ certificates: - name: yourCertName - version: yourCertVersion # Optional, fetch latest version if empty + maxVersionCount: 3 tenantID: clientID: ``` @@ -57,29 +56,51 @@ Status: Last Refreshed: 2024-10-02T14:58:54Z Name: yourCertName Version: a1b2c3d4e5f67890abcdef1234567890 + Status: Enabled Last Refreshed: 2024-10-02T14:58:54Z Name: yourCertName Version: 0ff373a9259c4578a247cfd7861a8805 + Status: Disabled ``` ## Implementation Details +- Modify the KMP data structure to include the status of the version. + ```go + type KMPMapKey struct { + Name string + Version string + Status string // Enabled or Disabled + Created time.Time // Time the version was created used for determining the oldest version + } + ``` - Add the `maxVersionCount` parameter to the KMP resource in Ratify. - ensure the value cannot be less than 1 or a negative number -- Update the `azurekeyvalut` provider to support the `maxVersionCount` parameter -- Update the `GetCertificates` and `GetKeys` methods to respect the `maxVersionCount` parameter retriving multiple versions of the certificate or key. -- Update the `GetCertificates` and `GetKeys` methods to remove the oldest version from the cache if the number of versions exceeds the `maxVersionCount` parameter. -- Update the `GetCertificates` and `GetKeys` methods to remove disabled versions from the cache. + - default to 0 if not specified + - maximum value should be (TBD) + - specify the value at the object level within the parameters of the KMP resource. +- Changes to `azurekeyvault` provider: + - support for the `maxVersionCount` parameter. + - allowing retrieval of multiple versions of certificates or keys. + - remove the oldest version from the cache when the number of versions exceeds the `maxVersionCount` parameter. + - update disabled certs status in the cache & remove the certData from the cache. +- Log when the status of a version changes. +- Log when a conflict between the `maxVersionCount` and the number of specified certificate versions occurs. ## Dev Work Items ## Open Questions - If a version is disabled, should it be removed from the cache or retained based on the nVersionCount and marked as inactive\disabled? - - Retaining the disabled version would require changing the KMP data structure to hold a list of versions and their status. + - [x] Keep the disabled version in the cache and mark it as disabled. - If a version is disabled, does that count towards the nVersionCount? For example, if nVersionCount is set to 3 and one of the versions is disabled, should Ratify retain the last three active versions or the last three versions, regardless of their status? -- What does the KMP status look like when multiple versions are retained in the cache? + - [x] Yes, disabled versions should count towards the nVersionCount. The reason for this is that disabled versions may be re-enabled in the future, and it is important to retain them in the cache. - Should the existing KMP data structure be changed to group versions by key or certificate name? -- Should the KMP status return a flat list of versions or group them by key or certificate name? + - [x] No, a flat list of versions is sufficient. At this time, there is no need to group versions by key or certificate name because the verifiers do not need to know the history of the versions. +- Should the KMP status return a flat list of versions? + - [x] Yes, the status should return a flat list of versions. +- What should the maximum value for nVersionCount be? + - [ ] TBD + ## Future Considerations From 5a453d0c8947ad56cd1091c67ca5b1422972fd18 Mon Sep 17 00:00:00 2001 From: Joshua Duffney Date: Thu, 17 Oct 2024 13:24:53 -0500 Subject: [PATCH 6/7] mod: update with decisions from community meeting Signed-off-by: Joshua Duffney --- docs/design/kmp-nversions.md | 48 ++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/design/kmp-nversions.md b/docs/design/kmp-nversions.md index f3c612931..f30603d9a 100644 --- a/docs/design/kmp-nversions.md +++ b/docs/design/kmp-nversions.md @@ -20,13 +20,13 @@ By supporting nVersionCount, Ratify would allow users to specify how many versio ## Proposed Solution -To address this challenge, this proposal suggests adding support for the `maxVersionCount` parameter to the KMP resource in Ratify. This parameter will allow users to specify the number of versions of a certificate or key that should be retained in the cache. +To address this challenge, this proposal suggests adding support for the `versionHistory` parameter to the KMP resource in Ratify. This parameter will allow users to specify the number of versions of a certificate or key that should be retained in the cache. -When a new version of a certificate or key is created, Ratify will check the `maxVersionCount` parameter to determine how many versions should be retained in the cache. If the number of versions exceeds the specified count, Ratify will remove the oldest version from the cache. +When a new version of a certificate or key is created, Ratify will check the `versionHistory` parameter to determine how many versions should be retained in the cache. If the number of versions exceeds the specified count, Ratify will remove the oldest version from the cache. If a version is disabled, Ratify will remove it from the cache. This ensures that disabled versions are not retained in the cache, reducing the risk of using compromised keys or certificates being passed to the verifiers. -Example: AKV KMP resource with `maxVersionCount` parameter +Example: AKV KMP resource with `versionHistory` parameter ```yaml apiVersion: config.ratify.deislabs.io/v1beta1 @@ -40,7 +40,7 @@ spec: vaultURI: https://yourkeyvault.vault.azure.net/ certificates: - name: yourCertName - maxVersionCount: 3 + versionHistory: 2 tenantID: clientID: ``` @@ -56,36 +56,36 @@ Status: Last Refreshed: 2024-10-02T14:58:54Z Name: yourCertName Version: a1b2c3d4e5f67890abcdef1234567890 - Status: Enabled + Enabled: true Last Refreshed: 2024-10-02T14:58:54Z Name: yourCertName Version: 0ff373a9259c4578a247cfd7861a8805 - Status: Disabled + Enabled: false ``` ## Implementation Details - Modify the KMP data structure to include the status of the version. - ```go - type KMPMapKey struct { - Name string - Version string - Status string // Enabled or Disabled - Created time.Time // Time the version was created used for determining the oldest version - } - ``` -- Add the `maxVersionCount` parameter to the KMP resource in Ratify. + ```go + type KMPMapKey struct { + Name string + Version string + Enabled string // true or false + Created time.Time // Time the version was created used for determining the oldest version + } + ``` +- Add the `versionHistory` parameter to the KMP resource in Ratify. - ensure the value cannot be less than 1 or a negative number - - default to 0 if not specified + - default to 2 if not specified by passing an empty value - maximum value should be (TBD) - specify the value at the object level within the parameters of the KMP resource. - Changes to `azurekeyvault` provider: - - support for the `maxVersionCount` parameter. - - allowing retrieval of multiple versions of certificates or keys. - - remove the oldest version from the cache when the number of versions exceeds the `maxVersionCount` parameter. - - update disabled certs status in the cache & remove the certData from the cache. + - support for the `versionHistory` parameter. + - allowing retrieval of multiple versions of certificates or keys. + - remove the oldest version from the cache when the number of versions exceeds the `versionHistory` parameter. + - update disabled certs status in the cache & remove the certData from the cache. - Log when the status of a version changes. -- Log when a conflict between the `maxVersionCount` and the number of specified certificate versions occurs. +- Log when a conflict between the `versionHistory` and the number of specified certificate versions occurs. ## Dev Work Items @@ -99,8 +99,8 @@ Status: - [x] No, a flat list of versions is sufficient. At this time, there is no need to group versions by key or certificate name because the verifiers do not need to know the history of the versions. - Should the KMP status return a flat list of versions? - [x] Yes, the status should return a flat list of versions. -- What should the maximum value for nVersionCount be? - - [ ] TBD - ## Future Considerations + +- What should the maximum value for nVersionCount be? + - [ ] TBD From 48a99aa3cad30beb2d1cfde8d8db153e7a18e603 Mon Sep 17 00:00:00 2001 From: Joshua Duffney Date: Fri, 18 Oct 2024 09:21:10 -0500 Subject: [PATCH 7/7] mod: value cannot be less than 0 Signed-off-by: Joshua Duffney --- docs/design/kmp-nversions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/kmp-nversions.md b/docs/design/kmp-nversions.md index f30603d9a..afc2421db 100644 --- a/docs/design/kmp-nversions.md +++ b/docs/design/kmp-nversions.md @@ -75,7 +75,7 @@ Status: } ``` - Add the `versionHistory` parameter to the KMP resource in Ratify. - - ensure the value cannot be less than 1 or a negative number + - ensure the value cannot be less than 0 or a negative number - default to 2 if not specified by passing an empty value - maximum value should be (TBD) - specify the value at the object level within the parameters of the KMP resource.