<commit_before>[[integration-encryption]]
=== Encryption service

Secrets used by Ontrack are <<architecture-encryption,encrypted>> using keys
managed by a `ConfidentialStore`.

Ontrack provides three types of storage:

* file based storage (default)
* https://www.vaultproject.io/[Vault] storage
* database storage

If needed, you can also create your own form of storage using
<<extension-encryption,extensions>>.

[[integration-encryption-selection]]
==== Selection of the confidential store

The selection of the confidential store is done at startup time using the
`ontrack.config.key-store`
<<configuration-properties,configuration property>>.

It defaults to `file` (see below).

Additional configuration properties might be needed according to the type of
store.

[[integration-encryption-file]]
==== File confidential store

This is the default store but its selection can be made explicit by setting
the `ontrack.config.key-store`
<<configuration-properties,configuration property>> to `file`.

This store will store the keys in the
<<configuration-properties,working directory>> under the
`security/secrets` subfolder.

A `master.key` file is used to encrypt the individual keys themselves, so
two files will be typically present:

* `master.key`
* `net.nemerosa.ontrack.security.EncryptionServiceImpl.encryption`

[[integration-encryption-jdbc]]
==== JDBC confidential store

This store manages the keys directly in the Ontrack database. It can be
selected by setting the `ontrack.config.key-store`
<<configuration-properties,configuration property>> to `jdbc`.

WARNING: This store is intrinsically insecure since it stores the keys
in the same location where the secrets are themselves stored.

No further configuration is needed.

[[integration-encryption-vault]]
==== Vault confidential store

By setting the `ontrack.config.key-store`
<<configuration-properties,configuration property>> to `vault`, Ontrack
will use https://www.vaultproject.io/[Vault] to store its encryption keys.

Following configuration properties are available to configure the connection
to Vault:

|===
| Property | Default | Description

| `ontrack.config.vault.uri`
| http://localhost:8200
| URI to the Vault end point

| `ontrack.config.vault.token`
| `test`
| Token authentication

| `ontrack.config.vault.prefix`
| `secret/ontrack/key`
| Path prefix for the storage of the keys

WARNING: As of now, the support for Vault storage is *experimental* and is
subject to change in later releases. In particular, the authentication
mechanism might change.

|===

[[integration-encryption-migration]]
==== Migrating encryption keys

In the event you want to migrate the encryption keys from one type of
storage to another, follow this procedure.

NOTE: In the procedure below, `${ONTRACK_URL}` designates the Ontrack URL
and `${ONTRACK_ADMIN_USER}` the name of an Ontrack user which has the
`ADMINISTRATOR` <<security,role>>.

Using the initial configuration for the store, start by exporting the key:

[source,bash]
----
curl ${ONTRACK_URL}/admin/encryption \
   --user ${ONTRACK_ADMIN_USER} \
   --output ontrack.key
----

This command will export the encryption key into the local `ontrack/key` file.

Start Ontrack using the new configuration.

WARNING: There might be errors are startup, when some <<architecture-jobs,jobs>>
start to collect some data from the external applications. Those errors can
be safely ignored for now.

Import the key file into Ontrack:

[source,bash]
----
curl ${ONTRACK_URL}/admin/encryption \
   --user ${ONTRACK_ADMIN_USER} \
   -X PUT \
   -H "Content-Type: text/plain" \
   --data @ontrack.key
----

Restart Ontrack.

[[integration-encryption-lost]]
==== Losing the encryption keys

TODO

[[integration-encryption-extending]]
==== Adding custom confidential store

TODO<commit_msg>#481 Documentation (losing the keys)<commit_after>[[integration-encryption]]
=== Encryption service

Secrets used by Ontrack are <<architecture-encryption,encrypted>> using keys
managed by a `ConfidentialStore`.

Ontrack provides three types of storage:

* file based storage (default)
* https://www.vaultproject.io/[Vault] storage
* database storage

If needed, you can also create your own form of storage using
<<extension-encryption,extensions>>.

[[integration-encryption-selection]]
==== Selection of the confidential store

The selection of the confidential store is done at startup time using the
`ontrack.config.key-store`
<<configuration-properties,configuration property>>.

It defaults to `file` (see below).

Additional configuration properties might be needed according to the type of
store.

[[integration-encryption-file]]
==== File confidential store

This is the default store but its selection can be made explicit by setting
the `ontrack.config.key-store`
<<configuration-properties,configuration property>> to `file`.

This store will store the keys in the
<<configuration-properties,working directory>> under the
`security/secrets` subfolder.

A `master.key` file is used to encrypt the individual keys themselves, so
two files will be typically present:

* `master.key`
* `net.nemerosa.ontrack.security.EncryptionServiceImpl.encryption`

[[integration-encryption-jdbc]]
==== JDBC confidential store

This store manages the keys directly in the Ontrack database. It can be
selected by setting the `ontrack.config.key-store`
<<configuration-properties,configuration property>> to `jdbc`.

WARNING: This store is intrinsically insecure since it stores the keys
in the same location where the secrets are themselves stored.

No further configuration is needed.

[[integration-encryption-vault]]
==== Vault confidential store

By setting the `ontrack.config.key-store`
<<configuration-properties,configuration property>> to `vault`, Ontrack
will use https://www.vaultproject.io/[Vault] to store its encryption keys.

Following configuration properties are available to configure the connection
to Vault:

|===
| Property | Default | Description

| `ontrack.config.vault.uri`
| http://localhost:8200
| URI to the Vault end point

| `ontrack.config.vault.token`
| `test`
| Token authentication

| `ontrack.config.vault.prefix`
| `secret/ontrack/key`
| Path prefix for the storage of the keys

WARNING: As of now, the support for Vault storage is *experimental* and is
subject to change in later releases. In particular, the authentication
mechanism might change.

|===

[[integration-encryption-migration]]
==== Migrating encryption keys

In the event you want to migrate the encryption keys from one type of
storage to another, follow this procedure.

NOTE: In the procedure below, `${ONTRACK_URL}` designates the Ontrack URL
and `${ONTRACK_ADMIN_USER}` the name of an Ontrack user which has the
`ADMINISTRATOR` <<security,role>>.

Using the initial configuration for the store, start by exporting the key:

[source,bash]
----
curl ${ONTRACK_URL}/admin/encryption \
   --user ${ONTRACK_ADMIN_USER} \
   --output ontrack.key
----

This command will export the encryption key into the local `ontrack/key` file.

Start Ontrack using the new configuration.

WARNING: There might be errors are startup, when some <<architecture-jobs,jobs>>
start to collect some data from the external applications. Those errors can
be safely ignored for now.

Import the key file into Ontrack:

[source,bash]
----
curl ${ONTRACK_URL}/admin/encryption \
   --user ${ONTRACK_ADMIN_USER} \
   -X PUT \
   -H "Content-Type: text/plain" \
   --data @ontrack.key
----

Restart Ontrack.

[[integration-encryption-lost]]
==== Losing the encryption keys

In case you lose the encryption keys, the consequence will be that the secrets
stored by Ontrack won't be able to be decrypted. This will typically make the
external applications your Ontrack instance connects to unreachable.

The only to fix this is to reenter the secrets.

CAUTION: Some pages might not display correctly if some applications are not
reachable.

[[integration-encryption-extending]]
==== Adding custom confidential store

See <<extending-encryption>>.
{'fraction_non_alphanumeric': 0.09380067356866659, 'fraction_numerical': 0.0013720843208182613, 'mean_word_length': 4.921713441654357, 'pattern_counts': {'":': 0, '<': 41, '<?xml version=': 0, '>': 41, 'https://': 4, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6199976', 'n_tokens_mistral': 2232, 'n_tokens_neox': 2161, 'n_words': 898}