From 29cf46a6d52e8a46ed7821444b53fdd89789a199 Mon Sep 17 00:00:00 2001 From: Timothy Stone Date: Tue, 28 May 2024 14:22:06 -0400 Subject: [PATCH] docs: update README for artifact coordinates, correct configuration properties, tighten style The README referenced the old Maven coordinate for the AWS KMS. Update to the new coordinate and add some additional best practices in Maven such as the use of versions in `properties`. In code fences, add a syntax hint. Unify the use of YAML mappings over "property" style keys, c.f., spring.cloud.aws. Where keys used camelCase, correct and use kebab-case for Spring recognition. Apply inline code style where needed, e.g., `{cipher}`. Use common YAML file extension, c.f., "yml" vs. "yaml". Signed-off-by: Timothy Stone --- zalando-cloud-aws-kms/README.md | 126 +++++++++++++++++--------------- 1 file changed, 67 insertions(+), 59 deletions(-) diff --git a/zalando-cloud-aws-kms/README.md b/zalando-cloud-aws-kms/README.md index 62e9e22..5afdfd7 100644 --- a/zalando-cloud-aws-kms/README.md +++ b/zalando-cloud-aws-kms/README.md @@ -19,67 +19,77 @@ Given you have a [Spring Boot](http://projects.spring.io/spring-boot/) applicati ### Step 1 -Add our starter as dependency to your Maven pom.xml or Gradle build file. +#### Add a property to ``. +```xml + +... +3.1.1 + ``` + +#### Add the starter as dependency to your Maven `pom.xml` or Gradle build file. + +```xml - org.zalando - zalando-cloud-awsspring-kms-starter - ${zalando-cloud-aws.version} + org.zalando.awspring.cloud + zalando-cloud-aws-kms + ${zalando-cloud-aws.version} ``` ### Step 2 (optional) -Apply configuration to the application's [Bootstrap Context](https://docs.spring.io/spring-cloud-commons/reference/spring-cloud-commons/application-context-services.html#the-bootstrap-application-context) - -E.g. `bootstrap.yml`: - -``` -spring.cloud: - decrypt-environment-post-processor.enabled: false # disable environment post processor for rsa keys - -spring.cloud.aws: - region: - static: eu-central-1 # optional +Apply configuration to the application's [Bootstrap Context](https://docs.spring.io/spring-cloud-commons/reference/spring-cloud-commons/application-context-services.html#the-bootstrap-application-context), e.g., `bootstrap.yml`: + +```yaml +spring: + cloud: + decrypt-environment-post-processor: + enabled: false # disable environment post processor for rsa keys +--- +spring: + cloud: + aws: + region: + static: eu-central-1 # optional + kms: + endpoint: http://localhost:4566 # only needed for endpoint override + +encrypt: kms: - endpoint: http://localhost:4566 # only needed for endpoint override + # Optional: Turn off the KMS feature completely (e.g. for local development) + enabled: false -encrypt.kms: - - # Optional: Turn off the KMS feature completely (e.g. for local development) - enabled: false - - # Optional for decrypting values with SYMMETRIC_DEFAULT algorithm. - # Required for encrypting values. - # Required for decrypting values with some asymmetric algorithm. - keyId: 9d9fca31-54c5-4df5-ba4f-127dfb9a5031 + # Optional for decrypting values with SYMMETRIC_DEFAULT algorithm. + # Required for encrypting values. + # Required for decrypting values with some asymmetric algorithm. + key-id: 9d9fca31-54c5-4df5-ba4f-127dfb9a5031 - # Optional: Switch to asymmetric algorithm. - # See com.amazonaws.services.kms.model.EncryptionAlgorithmSpec for available values. - encryptionAlgorithm: "RSAES_OAEP_SHA_256" + # Optional: Switch to asymmetric algorithm. + # See com.amazonaws.services.kms.model.EncryptionAlgorithmSpec for available values. + encryption-algorithm: "RSAES_OAEP_SHA_256" ``` -The `aws.kms.keyId` property must be set if +The `spring.cloud.aws.kms.key-id` property must be set if - values need to be decrypted with an asymmetric key - values need to be encrypted (with any algorithm) Those are the properties used by this library: - `encrypt.kms.enabled`: (defaults to true) -- `encrypt.kms.keyId`: either the keyId or the full ARN of the KMS key -- `encrypt.kms.encryptionAlgorithm`: the encryption algorithm to use +- `encrypt.kms.key-id`: either the keyId or the full ARN of the KMS key +- `encrypt.kms.encryption-algorithm`: the encryption algorithm to use ## Usage Now you can add encrypted values to you property files. An encrypted value must always start with `{cipher}`. -Those properties are automatically decrypted on application startup. - -E.g. `application.yml` +Those properties are automatically decrypted on application startup, e.g., `application.yml` +```yaml secretPassword: '{cipher}CiA47hYvQqWFFGq3TLtzQO5FwZMam2AnaeQt4PGEZHhDLxFTAQEBAgB4OO4WL0KlhRRqt0y7c0DuRcGTGptgJ8nkLeDxhGR4Qy8AAABqMGgGCSqGSIb3DQEHBqBbMFkCAQAwVAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAx61LJpXQwgTcnGeSQCARCAJ4xhpGC5HT2xT+Vhy2iAuT+P/PLliZK5u6CiGhgudteZsCr7VJ/1aw==' - +``` ### Use an encryption context An [encryption context](http://docs.aws.amazon.com/kms/latest/developerguide/encryption-context.html) @@ -87,14 +97,13 @@ is a set of key-value pairs used for encrypt and decrypt values, which might be enhancement. To use an encryption context with this library, you will have to use a custom syntax, that is not part -of Spring Security (as the {cipher} prefix). - -E.g. `application.yml` +of Spring Security (as the `{cipher}` prefix), e.g., `application.yml` +```yaml secretPassword: '{cipher}(Country=UG9ydHVnYWw=,Code=MzUx)CiA47hYvQqWFFGq3TLtzQO5FwZMam2AnaeQt4PGEZHhDLxFTAQEBAgB4OO4WL0KlhRRqt0y7c0DuRcGTGptgJ8nkLeDxhGR4Qy8AAABqMGgGCSqGSIb3DQEHBqBbMFkCAQAwVAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAx61LJpXQwgTcnGeSQCARCAJ4xhpGC5HT2xT+Vhy2iAuT+P/PLliZK5u6CiGhgudteZsCr7VJ/1aw==' - +``` The `(Country=UG9ydHVnYWw=,Code=MzUx)` part is the encryption context, where we used two keys for -this example: Country and Code. And the values are Base64 encoded. +this example: Country and Code. The values are Base64 encoded. Key-value pairs must be comma separated, and it is fine to use spaces to separate values. The order of the values in the context is not important. And one last note, is that the values used in the encryption @@ -106,37 +115,36 @@ AWS KMS supports [symmetric and asymmetric keys](https://docs.aws.amazon.com/kms #### Encryption -Add `keyId` and `encryptionAlgorithm` to the `bootstrap.yaml`: +Add `key-id` and `encryption-algorithm` to the `bootstrap.yml`: -``` -encrypt.kms: - keyId: "9d9fca31-54c5-4df5-ba4f-127dfb9a5031" - encryptionAlgorithm: "RSAES_OAEP_SHA_256" # or "RSAES_OAEP_SHA_1" +```yaml +encrypt: + kms: + key-id: "9d9fca31-54c5-4df5-ba4f-127dfb9a5031" + encryption-algorithm: "RSAES_OAEP_SHA_256" # or "RSAES_OAEP_SHA_1" ``` #### Decryption -If all cipher values of your application have been encrypted with the -same KMS key and algorithm, you can configure the `keyId` and `encryptionAlgorithm` -globally in the `bootstrap.yaml` as shown above. In case you have to decrypt -ciphers from different keys or different algorithms, you can specify those -separately for each key using the ["extra options"](#use-extra-options) approach: - -e.g. `application.yml` +If all cipher values of your application have been encrypted with the same KMS key and algorithm, you can configure +the `keyId` and `encryptionAlgorithm` globally in the `bootstrap.yml` as shown above. In case you have to decrypt +ciphers from different keys or different algorithms, you can specify those separately for each key using the +["extra options"](#use-extra-options) approach, e.g., `application.yml` +```yaml secret1: "{cipher}SSdtIHNvbWUgYXN5bW1ldHJpY2FsbHkgZW5jcnlwdGVkIHNlY3JldA==" secret2: "{cipher}[algorithm=SYMMETRIC_DEFAULT]U3ltbWV0cmljIGFuZCBhc3ltbWV0cmljIHNlY3JldHMgY2FuIGJlIG1peGVk" secret3: "{cipher}[algorithm=RSAES_OAEP_SHA_256,keyId=9d9fca31-54c5-4df5-ba4f-127dfb9a5031]SSBoYXZlIGEgY3VzdG9tIGtleSBhbmQgYWxnb3JpdGht" - +``` ### Use extra options While decrypting config values, extra arguments can be supplied to control the output behavior. -Extra args do also require a custom syntax, that is not part of Spring Security (as the {cipher} prefix). - -E.g. `application.yml` +Extra args do also require a custom syntax, that is not part of Spring Security (as the `{cipher}` prefix), e.g., `application.yml` +```yaml secretKey: '{cipher}[output=base64]CiA47hYvQqWFFGq3TLtzQO5FwZMam2AnaeQt4PGEZHhDLxFTAQEBAgB4OO4WL0KlhRRqt0y7c0DuRcGTGptgJ8nkLeDxhGR4Qy8AAABqMGgGCSqGSIb3DQEHBqBbMFkCAQAwVAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAx61LJpXQwgTcnGeSQCARCAJ4xhpGC5HT2xT+Vhy2iAuT+P/PLliZK5u6CiGhgudteZsCr7VJ/1aw==' +``` The `[output=base64]` part defines the extra options. @@ -156,13 +164,13 @@ Encryption context and extra options can be combined in any order. ### Run Test Suite -``` +```shell mvn clean test ``` ### Coverage Report -``` +```shell open coverage/target/site/jacoco/index.html ``` @@ -170,7 +178,7 @@ open coverage/target/site/jacoco/index.html ### Release to Maven Central -``` +```shell mvn clean release:prepare -Dresume=false mvn release:perform ```