Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update README for artifact coordinates, correct configuration properties, tighten style #175

Merged
merged 1 commit into from
Jun 7, 2024
Merged

docs: update README for artifact coordinates, correct configuration properties, tighten style #175

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 67 additions & 59 deletions zalando-cloud-aws-kms/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,82 +19,91 @@ 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 `<properties>`.

```xml
<properties>
...
<zalando-cloud-aws.version>3.1.1</zalando-cloud-aws.version>
</properties>
```

#### Add the starter as dependency to your Maven `pom.xml` or Gradle build file.

```xml
<dependency>
<groupId>org.zalando</groupId>
<artifactId>zalando-cloud-awsspring-kms-starter</artifactId>
<version>${zalando-cloud-aws.version}</version>
<groupId>org.zalando.awspring.cloud</groupId>
<artifactId>zalando-cloud-aws-kms</artifactId>
<version>${zalando-cloud-aws.version}</version>
</dependency>
```

### 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)
is a set of key-value pairs used for encrypt and decrypt values, which might be useful as security
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
Expand All @@ -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
Copy link
Contributor Author

@timothystone-knsl timothystone-knsl May 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The use of keyId and encryptionAlgorithm here were left as I was not certain how the "extra options" might be defined in the YAML, i.e., should the form be kebab-case or camelCase?

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.

Expand All @@ -156,21 +164,21 @@ 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
```

## Releases

### Release to Maven Central

```
```shell
mvn clean release:prepare -Dresume=false
mvn release:perform
```
Expand Down
Loading