geronimo-microprofile-site/src/main/jbake/content/extensions.adoc

= Apache Geronimo Microprofile Extensions
:jbake-date: 2018-07-24
:icons: font

Apache Geronimo Extension is a set of module integration with Microprofile and enriching it
transparently with production/cloud ready features.

== Secured credentials

Instead of ensuring all the `ConfigSource` you use through Microprofile Config are secured
you can plug our `secured-string-converter` and all string values will get support for a secured storage.

=== Dependency

[source,xml]
----
<dependency>
  <groupId>org.apache.geronimo</groupId>
  <artifactId>secured-string-converter</artifactId>
  <version>${geronimo-microprofile.version}</version>
</dependency>
----

=== Usage

A security mechanism allows to use a ciphered value instead of a clear value for passing sensitive data (password, secret, token, etc.).

It relies on `org.apache.geronimo.microprofile.extensions.config.converter.secure.ConfigurationMain`, which allows you to:

1. create a `master_key` file
2. encrypt a value
3. decrypt a value (for testing purposes)

A master password is stored and obfuscated in a `master_key` file. The algorithm `AES/CBC/PKCS5Padding` ciphers the value and encodes the result in base64. This mechanism allows to manage the value as plain text and easily pass it through all potential ways you can set the configuration.

Once value ciphered with the master key you can reference their ciphered value prefixed by `secure:` in your configuration
and the library will decipher them before passing the value to your application.

The command examples in the sections below assume you have set the alias in your profile:

[source,sh]
----
alias gssc="java -cp secured-string-converter.jar org.apache.geronimo.microprofile.extensions.config.converter.secure.ConfigurationMain"
----

If it is not the case, replace `gssc` by the full alias value.

==== Generating the master key

To generate the master key, use the provided main:

[source,sh]
----
gssc --master-key /path/to/my_master_key [secret-value]
----

IMPORTANT: Set the `geronimo.microprofile.extensions.config.converter.secure.master_key.location` system property on the server to ensure it uses this master key. Make sure that only the applications needing this key can read it.

==== Encrypting a value

To encrypt a value, use the provided main:

[source,sh]
----
gssc --encrypt /path/to/my_master_key my_credential_to_encrypt
----

==== Decrypting a value

To decrypt a value, use the provided main:

[source,sh]
----
gssc --decrypt /path/to/my_master_key secure:my_credential_to_encrypt
----

== Docker configs/secrets integration

=== Docker Config

org.apache.geronimo.microprofile.extensions.config.docker.DockerConfigConfigSource.ordinal:: config source ordinal. Defaults to `100`.
org.apache.geronimo.microprofile.extensions.config.docker.DockerConfigConfigSource.base:: configuration location. Defaults to `/`.
org.apache.geronimo.microprofile.extensions.config.docker.DockerConfigConfigSource.prefixes:: file name prefixes to take into account. Defaults to nothing, which means that all prefixes but the common UNIx exclusions are taken into account.

For example, creating a `/app.foo.bar` file makes its content available under the `app.foo.bar` key.

=== Docker Secrets

org.apache.geronimo.microprofile.extensions.config.docker.DockerSecretConfigSource.ordinal:: config source ordinal. Defaults to `100`.
org.apache.geronimo.microprofile.extensions.config.docker.DockerSecretConfigSource.base:: secrets location. Defaults to `/run/secrets`.

For example, creating a `/run/secrets/app.foo.bar` file makes its content available under the `app.foo.bar` key.