|
|
|
devel:documentation:adm:confidential_storage [2019/03/01 10:06]
kotisovam created parts moved from devel |
devel:documentation:adm:confidential_storage [2021/02/22 19:59] (current)
apeterova updated (moved from devel part), task to generate initialization vector |
| |
| The storage is currently used for: | The storage is currently used for: |
| * saving the identity password | * saving the sensitive data in [[devel:documentation:eav|dynamic forms (EAV)]] (which are used also for connectors configuration - mainly passwords, etc.) |
| * saving the sensitive data in [[..:..:application_configuration:dev:dynamic-forms|dynamic forms]] (which are used also for connectors configuration, etc.) | * saving sensitive configuration items |
| * saving sensitive configuration items (coming soon) | * temporary saving the identity password (when it's provisioned to an end system) |
| |
| The storage is encrypted by a key that is saved in the application property **cipher.crypt.secret.key** or in a file which is set in the application property **cipher.crypt.secret.keyPath**. | The current implementation of the confidential storage saves data into a separate database chart (owner, key, value). |
| |
| <note important>In default installation, CzechIdM doesn't contain any key. Remember therefore to set a key for crypt confidential storage before running your application in production mode.</note> | ===== The cipher and the secret key ===== |
| |
| <note tip> | The storage is encrypted by the key that is saved in the application property **cipher.crypt.secret.key** or in a file which is set in the application property **cipher.crypt.secret.keyPath**. |
| In production mode, it is possible to change the key for crypting (encoding/decoding) values in confidential storage. For this purpose a new LRT (ChangeConfidentialStorageKey) was designed. LRT must be started **after you have replaced the confidential storage key with a new one**. As parameter the old key is given. | |
| </note> | |
| | |
| <note tip> | |
| Search key order: | |
| - The highest priority has value in property 'cipher.crypt.secret.key'. | |
| - Second is file with a key on the path in property 'cipher.crypt.secret.keyPath'. | |
| </note> | |
| |
| Example settings: | Example settings: |
| cipher.crypt.secret.keyPath=/path/to/key/file | cipher.crypt.secret.keyPath=/path/to/key/file |
| |
| ===== Change confidential storage key ===== | Search key order: |
| The key can be changed in production mode by a long running task **ChangeConfidentialStorageKey**. **This task must be started when you have changed a key to a new one.** As parameter the old key for confidential storage will be given. | - The highest priority has value in property 'cipher.crypt.secret.key'. |
| | - Second is file with key on the path in property 'cipher.crypt.secret.keyPath'. |
| | |
| | IdM uses the algorithm AES/CBC/PKCS5Padding ([[https://docs.oracle.com/javase/7/docs/api/javax/crypto/Cipher.html|more info]]) for encryption of the confidential storage values. The algorithm operates with 128bit or 256bit key (**key must be only 128 or 256 bits!!**). To generate the key, you can use one of these commands: |
| | cat /dev/urandom | tr -dc 'a-z0-9' | head -c 16 |
| | cat /dev/urandom | tr -dc 'a-z0-9' | head -c 32 |
| | |
| | <note important>In basic installation, CzechIdM doesn't contain any key. Make sure to set some key for encryption of the confidential storage before you start the application in production mode. Recommended way is to install CzechIdM by the standard installation tutorial, which will guide you to set this important configuration in one of the installation steps ([[tutorial:adm:czechidm_installation#create_czechidm_configuration|Installation of CzechIdM - Create CzechIdM configuration]]).</note> |
| | |
| | <note tip> |
| | In production mode, it is possible to change key for encryption (encoding/decoding) of the values in the confidential storage. For this purpose was created new LRT (ChangeConfidentialStorageKey), see below. |
| | </note> |
| | |
| | ===== Change the confidential storage key ===== |
| | |
| | The storage key can be changed during production mode by long running task **Change confidential storage key (ChangeConfidentialStorageKey)**. **This task must be started after you changed key to newer** and restarted IdM for the change to take place. Use the old key for the confidential storage as a parameter of this task. |
| | |
| | This task should be used only for changing the key, i.e. you will never use the old value again for encrypting the confidential storage. Typically, when your secret key was compromised, or you want to use a longer key to increase security. The reason is that the old key is saved in the history of the all long running tasks, so it's no longer a secret after you use it this way. |
| | |
| | Note that after you change the confidential storage key with this task, all your current backups of the IdM database can't (or shouldn't) be used any longer for a full recovery in case of some failure. They contain values encrypted with the old key, which is no longer secret. So it's recommended to change the confidential storage key only as a separate action in a stable IdM environment, not as a part of some other (potentially breaking) changes in the production environment. |
| | |
| | To sum up the steps required to change the confidential storage key: |
| | - Backup the IdM database. |
| | - Backup the original confidential storage key (the file specified by the property ``cipher.crypt.secret.keyPath`` or directly in the property ``cipher.crypt.secret.key``, both would be in the ``application-xxx.properties`` file on the server with IdM). |
| | - Generate a new confidential storage key and save it to the file or the configuration property. |
| | - Restart IdM. |
| | - Schedule the task **Change confidential storage key (ChangeConfidentialStorageKey)** in IdM, set the original key to the parameter **old key**, and run the task. |
| | - Check the processed items of the task for any failures. |
| | - Backup the IdM database. |
| | - As the old encryption key is now considered "not secret", you have to take care of historical IdM database backups. Those backups could potentially leak sometime in the past and now they could become decryptable since the historical encryption key is no longer kept secret. Follow your company guidelines on destroying secret information. |
| | |
| | ===== Generate initialization vectors ===== |
| | |
| | The long running task **Generate initialization vectors for the confidential storage** (GenerateConfidentialStorageInitializationVectorsTaskExecutor, available since 10.8) should be used when upgrading from CzechIdM versions older than 10.6 to a newer version. The reason is improved security - avoiding potential cryptography attacks on the data saved in the confidential storage by older versions of the application, which used a static initialization vector. |
| | |
| | Recommended steps: |
| | - Backup the IdM database. |
| | - Schedule the task **Generate initialization vectors for the confidential storage** in IdM and run the task. |
| | - Check the processed items of the task for any failures. |
| | |
| | Note: When the tasks runs after the upgrade, you could notice the following warnings in IdM logs: ''IdM use old behavior with static vector. Please don't use this deprecated method.'' This is expected. After the task ends, you should never see this warning again. |
| | |