Skip to content

Commit fa3f5b7

Browse files
barchettabarchetta
authored
Add config encryption example (#200)
* Add config encryption example
1 parent 4bdbbef commit fa3f5b7

File tree

6 files changed

+221
-1
lines changed

6 files changed

+221
-1
lines changed

‎examples/config/encryption/README.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Storing Encrypted Values in Helidon Config
2+
3+
This example uses the `helidon-config-encryption` module to encrypt
4+
a value so that it can be stored and retrieved from `application.yaml`.
5+
It uses AES/GCM symmetric key encryption.
6+
7+
## Build and Run
8+
9+
```bash
10+
mvn clean package
11+
java -jar target/helidon-examples-config-encryption.jar
12+
```
13+
14+
The application prints:
15+
16+
```
17+
SECRET!!! secret-key=secret-value
18+
```
19+
20+
But the value is just clear text in the config file. How do we encrypt it?
21+
22+
## Encrypt value using AES/GCM
23+
24+
We encrypt the value using Helidon's encryption tooling.
25+
We use AES/GCM symmetric encryption with the private key
26+
(aka master password) `changeit`.
27+
28+
```base
29+
java -jar target/libs/helidon-config-encryption-*.jar aes changeit secret-value
30+
```
31+
**Note**: for Helidon 4.2.1-4.2.6 you need to provide the classpath when running the command:
32+
`java -cp "target/libs/*" io.helidon.config.encryption.Main aes changeit secret-value`
33+
34+
This will produce an encrypted value suitable for putting in a Helidon configuration file.
35+
It will look something like:
36+
37+
```
38+
${GCM=PAFWz...txS74=}
39+
```
40+
41+
(the three dots above represent a lengthy string of random characters -- not literally three dots)
42+
43+
Now edit `src/main/resources/application.yaml` and replace `secret-value` with the encrypted value.
44+
It will look something like this:
45+
46+
```
47+
secret-key: "${GCM=PAFWz...txS74=}"
48+
```
49+
50+
Now build and re-run your application. You will see the encrypted value returned
51+
from Helidon Config because we have not provided the key to decrypt the value:
52+
53+
```
54+
SECRET!!! secret-key=${GCM=PAF5IWz...txS74=}
55+
```
56+
57+
58+
## Passing the private key to your Helidon application
59+
60+
In this example we are going to pass the private key (master password) to the application using the special environment variable `SECURE_CONFIG_AES_MASTER_PWD`:
61+
62+
```bash
63+
SECURE_CONFIG_AES_MASTER_PWD=changeit java -jar target/helidon-examples-config-encryption.jar
64+
```
65+
66+
So now you see the decrypted value:
67+
68+
```
69+
SECRET!!! secret-key=secret-value
70+
```
71+
72+
## What is happening
73+
74+
The `helidon-config-encryption` module provides config encryption support. When it is added to your
75+
project as a dependency it registers a `ConfigFilter` that understands how to decrypt
76+
encrypted values. This happens automatically when you retrieve the value of an encrypted configuration property.
77+
The [EncryptionFilter](https://helidon.io/docs/latest/apidocs/io.helidon.config.encryption/io/helidon/config/encryption/EncryptionFilter.html)
78+
knows to check the environment variable for the private key.

‎examples/config/encryption/pom.xml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
Copyright (c) 2025 Oracle and/or its affiliates.
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
17+
-->
18+
<project xmlns="http://maven.apache.org/POM/4.0.0"
19+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
20+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
21+
<modelVersion>4.0.0</modelVersion>
22+
<parent>
23+
<groupId>io.helidon.applications</groupId>
24+
<artifactId>helidon-se</artifactId>
25+
<version>4.3.0-SNAPSHOT</version>
26+
<relativePath/>
27+
</parent>
28+
<groupId>io.helidon.examples.config</groupId>
29+
<artifactId>helidon-examples-config-encryption</artifactId>
30+
<version>1.0-SNAPSHOT</version>
31+
32+
<properties>
33+
<mainClass>io.helidon.examples.config.Main</mainClass>
34+
</properties>
35+
36+
<dependencies>
37+
<dependency>
38+
<groupId>io.helidon.config</groupId>
39+
<artifactId>helidon-config</artifactId>
40+
</dependency>
41+
<dependency>
42+
<groupId>io.helidon.config</groupId>
43+
<artifactId>helidon-config-yaml</artifactId>
44+
<scope>runtime</scope>
45+
</dependency>
46+
<dependency>
47+
<groupId>io.helidon.config</groupId>
48+
<artifactId>helidon-config-encryption</artifactId>
49+
<scope>runtime</scope>
50+
</dependency>
51+
</dependencies>
52+
53+
<build>
54+
<plugins>
55+
<plugin>
56+
<groupId>org.apache.maven.plugins</groupId>
57+
<artifactId>maven-dependency-plugin</artifactId>
58+
<executions>
59+
<execution>
60+
<id>copy-libs</id>
61+
</execution>
62+
</executions>
63+
</plugin>
64+
</plugins>
65+
</build>
66+
</project>

‎examples/config/encryption/src/main/java/io/helidon/examples/config/Main.java‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
/*
2+
* Copyright (c) 2025 Oracle and/or its affiliates.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.helidon.examples.config;
17+
18+
import io.helidon.config.Config;
19+
20+
/**
21+
* The application main class.
22+
*/
23+
public class Main {
24+
25+
/**
26+
* Cannot be instantiated.
27+
*/
28+
private Main() {
29+
}
30+
31+
/**
32+
* Application main entry point.
33+
* @param args command line arguments.
34+
*/
35+
public static void main(String[] args) {
36+
// initialize config from default configuration
37+
Config config = Config.global();
38+
39+
System.out.println("SECURE_CONFIG_AES_MASTER_PWD=" + System.getenv("SECURE_CONFIG_AES_MASTER_PWD"));
40+
System.out.println("SECRET!!! secret-key=" + config.get("secret-key").asString().get());
41+
}
42+
}

‎examples/config/encryption/src/main/java/io/helidon/examples/config/package-info.java‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
/*
2+
* Copyright (c) 2025 Oracle and/or its affiliates.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.helidon.examples.config;

‎examples/config/encryption/src/main/resources/application.yaml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#
2+
# Copyright (c) 2025 Oracle and/or its affiliates.
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
#
16+
17+
secret-key: "secret-value"

‎examples/config/pom.xml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<!--
33
4-
Copyright (c) 2017, 2024 Oracle and/or its affiliates.
4+
Copyright (c) 2017, 2025 Oracle and/or its affiliates.
55
66
Licensed under the Apache License, Version 2.0 (the "License");
77
you may not use this file except in compliance with the License.
@@ -40,6 +40,7 @@
4040
<module>sources</module>
4141
<module>profiles</module>
4242
<module>metadata</module>
43+
<module>encryption</module>
4344
</modules>
4445

4546
</project>

0 commit comments

Comments
 (0)