Skip to content

Commit

Permalink
Merge pull request #175 from timothystone-knsl/docs/fix-artifact-coor…
Browse files Browse the repository at this point in the history 
…dinate

docs: update README for artifact coordinates, correct configuration properties, tighten style
  • Loading branch information
@oussewa
oussewa authored Jun 7, 2024
2 parents c5eb3f3 + 29cf46a commit 8b284ed
Showing 1 changed file with 67 additions and 59 deletions.
126 changes: 67 additions & 59 deletions zalando-cloud-aws-kms/README.md
View file
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
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

0 comments on commit 8b284ed

Please sign in to comment.