From d49b44b8950e9085f3c17353bd2ba695534c1b71 Mon Sep 17 00:00:00 2001 From: Udara Pathum <46132469+hwupathum@users.noreply.github.com> Date: Fri, 25 Oct 2024 11:40:32 +0530 Subject: [PATCH 1/3] Add AES-256 support --- .../use-symmetric-encryption.md | 68 +------------ .../use-symmetric-encryption.md | 60 +----------- .../encryption/use-symmetric-encryption.md | 96 +++++++++++++++++++ 3 files changed, 98 insertions(+), 126 deletions(-) create mode 100644 en/includes/guides/encryption/use-symmetric-encryption.md diff --git a/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md b/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md index ecfc8bb36c..96b2a259f6 100644 --- a/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md +++ b/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md @@ -1,67 +1 @@ -# Configure symmetric key encryption - -This section explains the configurations related to [symmetric key encryption]({{base_path}}/deploy/security/symmetric-encryption). - -WSO2 Identity Server uses symmetric encryption by default for encrypting the following data: - -- Event publisher passwords -- Secondary user store properties -- TOTP `secretKey` and `verifiedSecretKey` claims -- OAuth 2.0 authorization codes, access tokens, refresh tokens, and consumer secrets (only when encryption enabled) - - !!! note - - To enable encryption of OAuth 2.0 authorization codes, access tokens, refresh tokens, and consumer secrets, add the following configuration to the `deployment.toml` found in the `/repository/conf/` directory. - ```toml - [oauth.extensions] - token_persistence_processor = "org.wso2.carbon.identity.oauth.tokenprocessor.EncryptionDecryptionPersistenceProcessor" - ``` - -- Secondary keystore passwords, and private-key passwords -- BPS profile passwords -- Workflow request credentials - -For other types of encryption, [asymmetric encryption]({{base_path}}/deploy/security/asymmetric-encryption) is used by default. - - -!!! warning - All configuration changes should be applied before starting Identity Server for the first time. Otherwise, a [key rotation]({{base_path}}/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation) will be required. - -## Configure a secret key - -For enhanced security, it is recommended to generate your own secret key for symmetric key encryption in {{product_name}}. To do so, - -1. Generate a unique 128-bit secret key. If you use OpenSSL, the command will be as follows: - - ```bash - openssl rand -hex 16 - ``` - -2. Add your generated key to the `deployment.toml` found in the `/repository/conf/` directory as follows: - - ```toml - [encryption] - key = "03BAFEB27A8E871CAD83C5CD4E771DAB" - ``` - -If a custom encryption key is not provided, the value of `encryption.key` in this configuration file will be used as the default key. - -## Algorithm used - -`AES/GCM/NoPadding` is used as the symmetric key encryption algorithm. - -GCM is a stream cipher. Hence, there is a performance advantage of using it due to the parallel encryption of each block. There is no need to use a padding mechanism in GCM mode. In GCM mode, the initialization vector (IV) should be a unique value for each encryption request. The corresponding IVs of each unique value should be kept track of in order to decrypt this internal data. The keysize supported is AES-128. - -## Internal crypto provider - -The `org.wso2.carbon.crypto.provider.SymmetricKeyInternalCryptoProvider` provider is used as the internal crypto provider. When configuring the `SymmetricKeyInternalCryptoProvider`, the secret key value needs to be provided in the configuration as well. - -The following configuration is enabled by default in the `/repository/resources/conf/default.json` file to use the above-mentioned internal crypto provider. - -```json -"encryption.internal_crypto_provider": "org.wso2.carbon.crypto.provider.SymmetricKeyInternalCryptoProvider" -``` - -## Encrypting symmetric encryption key with cipher tool - -It is advised to encrypt the symmetric encryption key with a cipher tool as mentioned [here]({{base_path}}/deploy/security/encrypt-passwords-with-cipher-tool). +{% include "../../../../../../includes/guides/encryption/use-symmetric-encryption.md" %} diff --git a/en/identity-server/next/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md b/en/identity-server/next/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md index 74ffaa5bca..96b2a259f6 100644 --- a/en/identity-server/next/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md +++ b/en/identity-server/next/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md @@ -1,59 +1 @@ -# Configurations Related to Symmetric Key Encryption - -This section explains the configurations related to [symmetric key encryption]({{base_path}}/deploy/security/symmetric-encryption). This version of WSO2 Identity Server uses symmetric encryption by default. You can switch to [asymmetric key encryption]({{base_path}}/deploy/security/asymmetric-encryption/use-asymmetric-encryption) if required. - -## Algorithm used - -`AES/GCM/NoPadding` is used as the symmetric key encryption algorithm. - -GCM is a stream cipher. Hence, there is a performance advantage of using it due to the parallel encryption of each block. There is no need to use a padding mechanism in GCM mode. In GCM mode, the initialization vector (IV) should be a unique value for each encryption request. The corresponding IVs of each unique value should be kept track of in order to decrypt this internal data. The keysize supported is AES-128. - -The following configuration is enabled by default in the `/repository/conf/carbon.properties` file for the algorithm to be used. - -```xml -org.wso2.CipherTransformation=AES/GCM/NoPadding -``` - -## Internal crypto provider - -The `org.wso2.carbon.crypto.provider.SymmetricKeyInternalCryptoProvider` provider is used as the internal crypto provider. When configuring the `SymmetricKeyInternalCryptoProvider`, the secret key value needs to be provided in the configuration as well. - -The following configuration is enabled by default in the `/repository/resources/conf/default.json` file to use the above-mentioned internal crypto provider. - -```xml -"encryption.internal_crypto_provider": "org.wso2.carbon.crypto.provider.SymmetricKeyInternalCryptoProvider", -"encryption.key": "03BAFEB27A8E871CAD83C5CD4E771DAB" -``` - -The corresponding xml configuration can be found in the `/repository/conf/carbon.xml` file. - -```xml -org.wso2.carbon.crypto.provider.SymmetricKeyInternalCryptoProvider -03BAFEB27A8E871CAD83C5CD4E771DAB -``` - -The `encryption.key` or `` value above is a sample value. Generate a unique secret key of 128 bytes using a tool like OpenSSL as shown below. - -```xml -openssl rand -hex 16 -``` - -Once a secure secret key is generated, configure it using the following configuration in the `/repository/conf/deployment.toml` file. - -```toml -[encryption] -key = "3cc0481b70794667b5bee7e2beed2de4" -``` - -## Userstore password encryption - -In the previous versions, there was a configuration to enable the preferred keystore (internal or primary) to encrypt secondary userstore passwords. -However, with symmetric key encryption, keystore references are not required. So this configuration has a blank as its value. - -```toml -"keystore.userstore_password_encryption": "", -``` - -## Encrypting symmetric encryption key with cipher tool - -It is advised to encrypt the symmetric encryption key with a cipher tool as mentioned [here]({{base_path}}/deploy/security/encrypt-passwords-with-cipher-tool). +{% include "../../../../../../includes/guides/encryption/use-symmetric-encryption.md" %} diff --git a/en/includes/guides/encryption/use-symmetric-encryption.md b/en/includes/guides/encryption/use-symmetric-encryption.md new file mode 100644 index 0000000000..0c927e6b4f --- /dev/null +++ b/en/includes/guides/encryption/use-symmetric-encryption.md @@ -0,0 +1,96 @@ +# Configure symmetric key encryption + +This section explains the configurations related to [symmetric key encryption]({{base_path}}/deploy/security/symmetric-encryption). + +WSO2 Identity Server uses symmetric encryption by default for encrypting the following data: + +- Event publisher passwords +- Secondary user store properties +- TOTP `secretKey` and `verifiedSecretKey` claims +- OAuth 2.0 authorization codes, access tokens, refresh tokens, and consumer secrets (only when encryption enabled) + + !!! note + + To enable encryption of OAuth 2.0 authorization codes, access tokens, refresh tokens, and consumer secrets, add the following configuration to the `deployment.toml` found in the `/repository/conf/` directory. + ```toml + [oauth.extensions] + token_persistence_processor = "org.wso2.carbon.identity.oauth.tokenprocessor.EncryptionDecryptionPersistenceProcessor" + ``` + +- Secondary keystore passwords, and private-key passwords +- BPS profile passwords +- Workflow request credentials + +For other types of encryption, [asymmetric encryption]({{base_path}}/deploy/security/asymmetric-encryption) is used by default. + + +!!! warning + All configuration changes should be applied before starting Identity Server for the first time. Otherwise, a [key rotation]({{base_path}}/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation) will be required. + +## Configure a secret key + +For enhanced security, it is recommended to generate your own secret key for symmetric key encryption in {{product_name}}. To do so, + +{% if is_version == "7.0.0" %} + +1. Generate a unique 128-bit secret key. If you use OpenSSL, the command will be as follows: + + ```bash + openssl rand -hex 16 + ``` + +2. Add your generated key to the `deployment.toml` found in the `/repository/conf/` directory as follows: + + ```toml + [encryption] + key = "9a131db7d3fce3adb0850b486bfc6528" + ``` + +{% else %} + +1. Generate a unique 256-bit secret key. If you use OpenSSL, the command will be as follows: + + ```bash + openssl rand -hex 32 + ``` + +2. Add your generated key to the `deployment.toml` found in the `/repository/conf/` directory as follows: + + ```toml + [encryption] + key = "d13e3b2ea4c42eb4a23fd110facb72a596ecd84ecd5297a13065f1877393eccf" + ``` + +{% endif %} + +If a custom encryption key is not provided, the value of `encryption.key` in this configuration file will be used as the default key. + +## Algorithm used + +`AES/GCM/NoPadding` is used as the symmetric key encryption algorithm. + +GCM is a stream cipher. Hence, there is a performance advantage of using it due to the parallel encryption of each block. There is no need to use a padding mechanism in GCM mode. In GCM mode, the initialization vector (IV) should be a unique value for each encryption request. The corresponding IVs of each unique value should be kept track of in order to decrypt this internal data. + +{% if is_version == "7.0.0" %} + +The keysize supported is AES-128. + +{% else %} + +The supported key sizes are AES-128, AES-192, and AES-256. + +{% endif %} + +## Internal crypto provider + +The `org.wso2.carbon.crypto.provider.SymmetricKeyInternalCryptoProvider` provider is used as the internal crypto provider. When configuring the `SymmetricKeyInternalCryptoProvider`, the secret key value needs to be provided in the configuration as well. + +The following configuration is enabled by default in the `/repository/resources/conf/default.json` file to use the above-mentioned internal crypto provider. + +```json +"encryption.internal_crypto_provider": "org.wso2.carbon.crypto.provider.SymmetricKeyInternalCryptoProvider" +``` + +## Encrypting symmetric encryption key with cipher tool + +It is advised to encrypt the symmetric encryption key with a cipher tool as mentioned [here]({{base_path}}/deploy/security/encrypt-passwords-with-cipher-tool). From 2648b848d5b18686a2d61e2da4a7d7d350438c5e Mon Sep 17 00:00:00 2001 From: himeshsiriwardana Date: Mon, 4 Nov 2024 14:46:40 +0530 Subject: [PATCH 2/3] Added suggestions for aes 256 encryption --- .../blue-green-data-encryption-keyrotation.md | 251 +----------------- .../security/symmetric-encryption/index.md | 2 +- .../use-symmetric-encryption.md | 1 - en/identity-server/7.0.0/mkdocs.yml | 1 - .../blue-green-data-encryption-keyrotation.md | 251 +----------------- .../security/symmetric-encryption/index.md | 2 +- .../use-symmetric-encryption.md | 1 - en/identity-server/next/mkdocs.yml | 1 - .../blue-green-data-encryption-keyrotation.md | 250 +++++++++++++++++ .../{use-symmetric-encryption.md => index.md} | 44 ++- .../guides/encryption/symmetric-encryption.md | 16 -- 11 files changed, 286 insertions(+), 534 deletions(-) delete mode 100644 en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md delete mode 100644 en/identity-server/next/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md create mode 100644 en/includes/guides/encryption/blue-green-data-encryption-keyrotation.md rename en/includes/guides/encryption/{use-symmetric-encryption.md => index.md} (58%) delete mode 100644 en/includes/guides/encryption/symmetric-encryption.md diff --git a/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation.md b/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation.md index 3bbdfe34c3..5ca7d50187 100644 --- a/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation.md +++ b/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation.md @@ -1,250 +1 @@ -# Blue-Green Data Encryption Key Rotation - -This section contains the complete process you need to follow in order to perform symmetric data encryption key rotation in WSO2 Identity Sever(WSO2 IS version 5.11.0 and above). - -Key rotation can be defined as retiring an encryption key and replacing it with a new key. Data is encrypted using a key known as a Data Encryption Key(DEK) and the DEK is then encrypted with another key called Key Encryption Key(KEK). This is known as envelope encryption. Frequent rotations of these encryption keys are considered as an industry best practice by PCI DSS and NIST standards. - -## Why should you rotate encryption keys? - -!!! info - Originator Usage Period (OUP) is the time period during which encryption is applied to data. - -- A cryptoperiod is the time span during which a specific key is authorized for use. [NIST SP 800-57](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57pt1r5.pdf){:target="_blank"} recommends different cryptoperiods for different encryption key types. - - - Symmetric Data Encryption Keys - - - OUP recommended for large volumes of data is about a day or a week. - - OUP recommended for smaller volumes of data is about 2 years. - - - Symmetric Key, Wrapping Keys - - - OUP recommended for a key that wraps a large number of keys is about a day or a week. - - OUP recommended for a key that wraps a smaller number of keys is up to 2 years. - -- Security compliance requirements -- Security breach requirements - -!!! note - The above-mentioned cryptoperiods can vary based on other factors like the sensitivity of data and the amount of data we have. - -## Background - -WSO2 Identity Server has the following key usages for signing/encrypting data and each of these types will have different key rotation requirements. - -- TLS Connection -- Signing and encryption of data (JWT assertions, payloads) shared with external parties (SP, IdP). -- Encryption of sensitive runtime level configuration secrets/user data persisted in datastores and user stores. -- Encryption of sensitive deployment-level configuration data in configuration files. - -From WSO2 IS 5.11.0 onwards, symmetric encryption is used to encrypt the internal sensitive runtime data above. The DEK used to encrypt these data is configured in the `deployment.toml` file and it is protected by a KEK. The secure vault is utilized as of now to protect this DEK. Here, only the rotation of the Data Encryption Key configured in the `deployment.toml` file is considered. - -## DEK rotation frequency - -In the case of a security compliance requirement, we can see that symmetric DEK rotation can be done in 2 years or less based on the volume of data present. - -In a security breach scenario, we must rotate the DEK immediately and re-encrypt all the data to the new DEK. - -## Key Rotation Approach - -WSO2 IS has introduced an external tool that re-encrypts internal data after rotation of the configured symmetric data encryption key. Here, the re-encryption of the identity and registry databases and some configuration files is considered. Apart from that, the tool syncs end-user data that gets generated in the live system to the new setup. - -The external Java client that performs the above tasks can be created by following the steps [here](#how-to-create-the-key-rotation-tool). - -## Tables that support re-encryption - -At the moment, the tables given below are supported for re-encryption. - -| **Table** | **Fields** | -|-----------|---------------| -| IDN_IDENTITY_USER_DATA | TOTP secretKey and verifiedSecretKey claims | -| IDN_OAUTH2_AUTHORIZATION_CODE | OAuth2 authorization codes | -| IDN_OAUTH2_ACCESS_TOKEN | OAuth2 access and refresh tokens | -| IDN_OAUTH_CONSUMER_APPS | Consumer secrets -| WF_BPS_PROFILE | BPS profile password | -| WF_REQUEST | WF request credentials | -| REG_PROPERTY | Keystore passwords, Keystore privatekeyPass, and Entitlement subscriberPasswords | - -## Configuration files that support re-encryption - -At the moment, the configuration files given below are supported for re-encryption. - -| **Configuration file** | **Path** | **Property** | -|---------------------------|-----------|--------------| -| Event publishers | `/repository/deployment/server/eventpublishers` files | Password | -| Super tenant secondary user stores | `/repository/deployment/server/userstores/` files | Password | -| Tenant secondary userstores | `/repository/tenants//userstores/` files | Password | - -## Tables that support syncing - -At the moment, the tables given below can be synced during key rotation from the old setup to the new setup. Any other data will not be persisted in the new setup. - -| **Table** | **Purpose** | **Recommendation** | -|-----------|---------------|-----------------------| -| IDN_IDENTITY_USER_DATA | Identity claims when the identity data store is enabled | Usually recommended to sync if identity management features are enabled in the system | -| IDN_OAUTH2_ACCESS_TOKEN | OAuth 2.0 tokens | Need to sync if the tokens created during the key rotation period need to be valid after key rotation | -| IDN_OAUTH2_ACCESS_TOKEN_SCOPE | OAuth 2.0 scopes | If the IDN_OAUTH2_ACCESS_TOKEN is synced, this table also needs to be synced | -| IDN_OAUTH2_AUTHORIZATION_CODE | OAuth 2.0 authorization codes | Need to sync if the authorization codes created during the key rotation period need to be valid after key rotation | - -## How To Create The Key Rotation Tool - -!!! note - In this section, `` is the directory where the current Identity Server resides, and `` is the directory where the copy of the current Identity Server resides. `` refers to the location [here](https://github.com/wso2/identity-tools/components/org.wso2.carbon.identity.keyrotation){:target="_blank"} and the `` refers to the location of the external tool. - -1. Clone the repository, [identity-tools](https://github.com/wso2/identity-tools){:target="_blank"}. - -2. Build it using maven by running the command `mvn clean install`. - -3. Go to the `/target` folder and copy the `keyrotation-tool--SNAPSHOT.jar` file and the `/target/lib` folder to ``. Get the `properties.yaml` file, `keyrotation.sh` file, and the `triggers` folder from `/src/main/resources` and copy them to the same `` location. - -## Performing blue-green key rotation - -1. Block all privileged user flows and allow only end-user flows. - - !!! note - For the privileged user flows, block all admin services from the load balancer and the management console as well. For end user flows, the above [tables]({{base_path}}/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation/#tables-that-support-re-encryption) will be synced to the ``, so only these end user data flows should be allowed to generate in ``. - -2. Execute the `old.sql` script in the `` identity database to create temp tables and triggers. The triggers can be found inside the `/triggers` folder. - -3. Create a copy of the ``(This copied directory will be referred to as the `NEW_IS_HOME`) and dump `` identity and registry databases and create the new databases. - -4. Drop the temp tables and triggers in the `` identity database using the `new.sql` script. The triggers can be found inside the `/triggers` folder. - -5. Open the `properties.yaml` file in `` and edit the configurations accordingly. - - - oldSecretKey - The symmetric encryption key used in the ``. - - !!! note - If the key is encrypted using cipher tool, decrypt it back as shown [here](https://shagihan.medium.com/decrypt-encrypted-text-with-the-wso2-cipher-tool-15b67624620a){:target="_blank"}. - - - newSecretKey - The new symmetric encryption key. - - !!! tip - Generate using a tool like openssl using the command, `openssl rand -hex 16`. - - - newISHome - The absolute path of the ``. - - oldIdnDBUrl - `` identity database URL. - - oldIdnUsername - `` identity database username. - - oldIdnPassword - `` identity database password (Encoded in [base64](https://www.base64encode.org/){:target="_blank"}). - - newIdnDBUrl - `` identity database URL. - - newIdnUsername - `` identity database username. - - newIdnPassword - `` identity database password (Encoded in [base64](https://www.base64encode.org/){:target="_blank"}). - - newRegDBUrl - `` registry database URL. - - newRegUsername - `` registry database username. - - newRegPassword - `` registry database password (Encoded in [base64](https://www.base64encode.org/){:target="_blank"}). - - enableDBMigrator - Enable/disable re-encryption for the identity and registry databases. - - !!! note - Keep this always **true** to avoid unnecessary issues. - - - enableConfigMigrator - Enable/disable re-encryption for the configuration files. - - !!! note - Keep this always **true** to avoid unnecessary issues. - - - enableSyncMigrator - Enable/disable syncing mechanism. - - !!! note - You only need to set this to **true**, if you have opted in for blue-green key rotation with zero downtime for the end user flows. - - - chunkSize - Size of the record chunks being retrieved from the database tables for syncing. - - ??? tip "Sample configuration written for the properties.yaml file" - - ``` - oldSecretKey: AFA27B44D43B02A9FEA41D13CEDC2E40 - newSecretKey: 1fc0bc7a3805b42afa5f5af07a595f56 - newISHome: /home/IS/wso2is-5.12.0 - oldIdnDBUrl: jdbc:mysql://localhost:3306/regdb?useSSL=false - oldIdnUsername: root - oldIdnPassword: cm9vdA== - newIdnDBUrl: jdbc:mysql://localhost:3306/regdb1?useSSL=false - newIdnUsername: root - newIdnPassword: cm9vdA== - newRegDBUrl: jdbc:mysql://localhost:3306/regdb1?useSSL=false - newRegUsername: root - newRegPassword: cm9vdA== - enableDBMigrator: true - enableConfigMigrator: true - enableSyncMigrator: true - chunkSize: 2 - ``` - - ??? tip "Sample configurations written for DB type URL" - **H2 DB** - ``` - jdbc:h2:~/Desktop/IS/copy/wso2is-5.11.0-beta5-SNAPSHOT/repository/database/WSO2IDENTITY_DB - ``` - **MySQL** - ``` - jdbc:mysql://localhost:3306/idndb?useSSL=false - ``` - **DB2** - ``` - jdbc:db2://localhost:50000/idndb - ``` - **PostgreSQL** - ``` - jdbc:postgresql://localhost:5432/idndb - ``` - **MSSQL** - ``` - jdbc:sqlserver://localhost:1433;databaseName=idndb - ``` - **Oracle DB** - ``` - jdbc:oracle:thin:@localhost:1521/ORCLCDB.LOCALDOMAIN - ``` - -6. Run the tool using the `./keyrotation.sh keyrotation-tool--SNAPSHOT.jar` command from ``. - -7. Edit the `` `deployment.toml` file having the new configured databases and the new key. - -8. Start `` once the re-encryption for the existing DB and config file is done. - -9. When no new entries are being synced in the logs, route traffic to `` and enable all load balancer API endpoints(privileged and end-user flows). - -!!! note "Important" - Do not stop the tool at once, let it sync any remaining data in the temp tables after routing the traffic. - -## Verifying the key rotation - -- Check the log files to verify if re-encryption happened successfully for the 7 identity and registry database tables. Check the logs given below for the successful/failed re-encryption counts of OAuth2 access and refresh tokens. - - ??? tip "DB log sample" - ``` - Successfully updated OAuth2 access and refresh tokens data records in IDN_OAUTH2_ACCESS_TOKEN: 897 - Failed OAuth2 access and refresh tokens data records in IDN_OAUTH2_ACCESS_TOKEN: 0 - ``` - - !!! note - If the key rotation task is successful, the failed logs count should be `0` for all the tables. - -- Check the log files to verify if re-encryption happened successfully for the 3 configuration files. Check the logs given below for the successful/failed re-encryption counts of event publisher configuration files. - - ??? tip "Config file log sample" - ``` - Updated event publisher configuration files: 8 - Failed event publisher configuration files: 0 - ``` - - !!! note - If the key rotation task is successful, the failed logs count should be `0` for all the configuration files. - -- Check the log files to verify if the transformation of the synced data happened successfully for the 4 tables. Check the logs given below for the successful/failed transformation counts of `IDN_IDENTITY_USER_DATA` table. - - ??? tip "Synced log sample" - ``` - Successfully transformed totp data records in IDN_IDENTITY_USER_DATA_TEMP: 2 - Transformation failed totp data records in IDN_IDENTITY_USER_DATA_TEMP: 0 - ``` - - !!! note - If the synced task is successful, the failed logs count should be `0` for all the synced tables. - -- Check for any errors in the log files and carefully analyze the logs if the error can be ignored and other steps can be proceeded with. Otherwise, check what has caused the error. - -## Recovering from any failure - -If the key rotation task stops midway, follow the blue green key rotation user guide steps again. - -If there are errors logged in the log files, carefully go through the errors and find what has caused the error. +{% include "../../../../../../includes/guides/encryption/blue-green-data-encryption-keyrotation.md" %} \ No newline at end of file diff --git a/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/index.md b/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/index.md index d72560d24d..0c124b4c79 100644 --- a/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/index.md +++ b/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/index.md @@ -1 +1 @@ -{% include "../../../../../../includes/guides/encryption/symmetric-encryption.md" %} +{% include "../../../../../../includes/guides/encryption/index.md" %} diff --git a/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md b/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md deleted file mode 100644 index 96b2a259f6..0000000000 --- a/en/identity-server/7.0.0/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md +++ /dev/null @@ -1 +0,0 @@ -{% include "../../../../../../includes/guides/encryption/use-symmetric-encryption.md" %} diff --git a/en/identity-server/7.0.0/mkdocs.yml b/en/identity-server/7.0.0/mkdocs.yml index 7b51aba0e9..d351af8231 100644 --- a/en/identity-server/7.0.0/mkdocs.yml +++ b/en/identity-server/7.0.0/mkdocs.yml @@ -671,7 +671,6 @@ nav: - Encryption: - Symmetric encryption: - Symmetric encryption: deploy/security/symmetric-encryption/index.md - - Configure symmetric key encryption: deploy/security/symmetric-encryption/use-symmetric-encryption.md - Symmetric data encryption key rotation: deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation.md - Asymmetric encryption: - Asymmetric encryption: deploy/security/asymmetric-encryption/index.md diff --git a/en/identity-server/next/docs/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation.md b/en/identity-server/next/docs/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation.md index 3bbdfe34c3..5ca7d50187 100644 --- a/en/identity-server/next/docs/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation.md +++ b/en/identity-server/next/docs/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation.md @@ -1,250 +1 @@ -# Blue-Green Data Encryption Key Rotation - -This section contains the complete process you need to follow in order to perform symmetric data encryption key rotation in WSO2 Identity Sever(WSO2 IS version 5.11.0 and above). - -Key rotation can be defined as retiring an encryption key and replacing it with a new key. Data is encrypted using a key known as a Data Encryption Key(DEK) and the DEK is then encrypted with another key called Key Encryption Key(KEK). This is known as envelope encryption. Frequent rotations of these encryption keys are considered as an industry best practice by PCI DSS and NIST standards. - -## Why should you rotate encryption keys? - -!!! info - Originator Usage Period (OUP) is the time period during which encryption is applied to data. - -- A cryptoperiod is the time span during which a specific key is authorized for use. [NIST SP 800-57](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57pt1r5.pdf){:target="_blank"} recommends different cryptoperiods for different encryption key types. - - - Symmetric Data Encryption Keys - - - OUP recommended for large volumes of data is about a day or a week. - - OUP recommended for smaller volumes of data is about 2 years. - - - Symmetric Key, Wrapping Keys - - - OUP recommended for a key that wraps a large number of keys is about a day or a week. - - OUP recommended for a key that wraps a smaller number of keys is up to 2 years. - -- Security compliance requirements -- Security breach requirements - -!!! note - The above-mentioned cryptoperiods can vary based on other factors like the sensitivity of data and the amount of data we have. - -## Background - -WSO2 Identity Server has the following key usages for signing/encrypting data and each of these types will have different key rotation requirements. - -- TLS Connection -- Signing and encryption of data (JWT assertions, payloads) shared with external parties (SP, IdP). -- Encryption of sensitive runtime level configuration secrets/user data persisted in datastores and user stores. -- Encryption of sensitive deployment-level configuration data in configuration files. - -From WSO2 IS 5.11.0 onwards, symmetric encryption is used to encrypt the internal sensitive runtime data above. The DEK used to encrypt these data is configured in the `deployment.toml` file and it is protected by a KEK. The secure vault is utilized as of now to protect this DEK. Here, only the rotation of the Data Encryption Key configured in the `deployment.toml` file is considered. - -## DEK rotation frequency - -In the case of a security compliance requirement, we can see that symmetric DEK rotation can be done in 2 years or less based on the volume of data present. - -In a security breach scenario, we must rotate the DEK immediately and re-encrypt all the data to the new DEK. - -## Key Rotation Approach - -WSO2 IS has introduced an external tool that re-encrypts internal data after rotation of the configured symmetric data encryption key. Here, the re-encryption of the identity and registry databases and some configuration files is considered. Apart from that, the tool syncs end-user data that gets generated in the live system to the new setup. - -The external Java client that performs the above tasks can be created by following the steps [here](#how-to-create-the-key-rotation-tool). - -## Tables that support re-encryption - -At the moment, the tables given below are supported for re-encryption. - -| **Table** | **Fields** | -|-----------|---------------| -| IDN_IDENTITY_USER_DATA | TOTP secretKey and verifiedSecretKey claims | -| IDN_OAUTH2_AUTHORIZATION_CODE | OAuth2 authorization codes | -| IDN_OAUTH2_ACCESS_TOKEN | OAuth2 access and refresh tokens | -| IDN_OAUTH_CONSUMER_APPS | Consumer secrets -| WF_BPS_PROFILE | BPS profile password | -| WF_REQUEST | WF request credentials | -| REG_PROPERTY | Keystore passwords, Keystore privatekeyPass, and Entitlement subscriberPasswords | - -## Configuration files that support re-encryption - -At the moment, the configuration files given below are supported for re-encryption. - -| **Configuration file** | **Path** | **Property** | -|---------------------------|-----------|--------------| -| Event publishers | `/repository/deployment/server/eventpublishers` files | Password | -| Super tenant secondary user stores | `/repository/deployment/server/userstores/` files | Password | -| Tenant secondary userstores | `/repository/tenants//userstores/` files | Password | - -## Tables that support syncing - -At the moment, the tables given below can be synced during key rotation from the old setup to the new setup. Any other data will not be persisted in the new setup. - -| **Table** | **Purpose** | **Recommendation** | -|-----------|---------------|-----------------------| -| IDN_IDENTITY_USER_DATA | Identity claims when the identity data store is enabled | Usually recommended to sync if identity management features are enabled in the system | -| IDN_OAUTH2_ACCESS_TOKEN | OAuth 2.0 tokens | Need to sync if the tokens created during the key rotation period need to be valid after key rotation | -| IDN_OAUTH2_ACCESS_TOKEN_SCOPE | OAuth 2.0 scopes | If the IDN_OAUTH2_ACCESS_TOKEN is synced, this table also needs to be synced | -| IDN_OAUTH2_AUTHORIZATION_CODE | OAuth 2.0 authorization codes | Need to sync if the authorization codes created during the key rotation period need to be valid after key rotation | - -## How To Create The Key Rotation Tool - -!!! note - In this section, `` is the directory where the current Identity Server resides, and `` is the directory where the copy of the current Identity Server resides. `` refers to the location [here](https://github.com/wso2/identity-tools/components/org.wso2.carbon.identity.keyrotation){:target="_blank"} and the `` refers to the location of the external tool. - -1. Clone the repository, [identity-tools](https://github.com/wso2/identity-tools){:target="_blank"}. - -2. Build it using maven by running the command `mvn clean install`. - -3. Go to the `/target` folder and copy the `keyrotation-tool--SNAPSHOT.jar` file and the `/target/lib` folder to ``. Get the `properties.yaml` file, `keyrotation.sh` file, and the `triggers` folder from `/src/main/resources` and copy them to the same `` location. - -## Performing blue-green key rotation - -1. Block all privileged user flows and allow only end-user flows. - - !!! note - For the privileged user flows, block all admin services from the load balancer and the management console as well. For end user flows, the above [tables]({{base_path}}/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation/#tables-that-support-re-encryption) will be synced to the ``, so only these end user data flows should be allowed to generate in ``. - -2. Execute the `old.sql` script in the `` identity database to create temp tables and triggers. The triggers can be found inside the `/triggers` folder. - -3. Create a copy of the ``(This copied directory will be referred to as the `NEW_IS_HOME`) and dump `` identity and registry databases and create the new databases. - -4. Drop the temp tables and triggers in the `` identity database using the `new.sql` script. The triggers can be found inside the `/triggers` folder. - -5. Open the `properties.yaml` file in `` and edit the configurations accordingly. - - - oldSecretKey - The symmetric encryption key used in the ``. - - !!! note - If the key is encrypted using cipher tool, decrypt it back as shown [here](https://shagihan.medium.com/decrypt-encrypted-text-with-the-wso2-cipher-tool-15b67624620a){:target="_blank"}. - - - newSecretKey - The new symmetric encryption key. - - !!! tip - Generate using a tool like openssl using the command, `openssl rand -hex 16`. - - - newISHome - The absolute path of the ``. - - oldIdnDBUrl - `` identity database URL. - - oldIdnUsername - `` identity database username. - - oldIdnPassword - `` identity database password (Encoded in [base64](https://www.base64encode.org/){:target="_blank"}). - - newIdnDBUrl - `` identity database URL. - - newIdnUsername - `` identity database username. - - newIdnPassword - `` identity database password (Encoded in [base64](https://www.base64encode.org/){:target="_blank"}). - - newRegDBUrl - `` registry database URL. - - newRegUsername - `` registry database username. - - newRegPassword - `` registry database password (Encoded in [base64](https://www.base64encode.org/){:target="_blank"}). - - enableDBMigrator - Enable/disable re-encryption for the identity and registry databases. - - !!! note - Keep this always **true** to avoid unnecessary issues. - - - enableConfigMigrator - Enable/disable re-encryption for the configuration files. - - !!! note - Keep this always **true** to avoid unnecessary issues. - - - enableSyncMigrator - Enable/disable syncing mechanism. - - !!! note - You only need to set this to **true**, if you have opted in for blue-green key rotation with zero downtime for the end user flows. - - - chunkSize - Size of the record chunks being retrieved from the database tables for syncing. - - ??? tip "Sample configuration written for the properties.yaml file" - - ``` - oldSecretKey: AFA27B44D43B02A9FEA41D13CEDC2E40 - newSecretKey: 1fc0bc7a3805b42afa5f5af07a595f56 - newISHome: /home/IS/wso2is-5.12.0 - oldIdnDBUrl: jdbc:mysql://localhost:3306/regdb?useSSL=false - oldIdnUsername: root - oldIdnPassword: cm9vdA== - newIdnDBUrl: jdbc:mysql://localhost:3306/regdb1?useSSL=false - newIdnUsername: root - newIdnPassword: cm9vdA== - newRegDBUrl: jdbc:mysql://localhost:3306/regdb1?useSSL=false - newRegUsername: root - newRegPassword: cm9vdA== - enableDBMigrator: true - enableConfigMigrator: true - enableSyncMigrator: true - chunkSize: 2 - ``` - - ??? tip "Sample configurations written for DB type URL" - **H2 DB** - ``` - jdbc:h2:~/Desktop/IS/copy/wso2is-5.11.0-beta5-SNAPSHOT/repository/database/WSO2IDENTITY_DB - ``` - **MySQL** - ``` - jdbc:mysql://localhost:3306/idndb?useSSL=false - ``` - **DB2** - ``` - jdbc:db2://localhost:50000/idndb - ``` - **PostgreSQL** - ``` - jdbc:postgresql://localhost:5432/idndb - ``` - **MSSQL** - ``` - jdbc:sqlserver://localhost:1433;databaseName=idndb - ``` - **Oracle DB** - ``` - jdbc:oracle:thin:@localhost:1521/ORCLCDB.LOCALDOMAIN - ``` - -6. Run the tool using the `./keyrotation.sh keyrotation-tool--SNAPSHOT.jar` command from ``. - -7. Edit the `` `deployment.toml` file having the new configured databases and the new key. - -8. Start `` once the re-encryption for the existing DB and config file is done. - -9. When no new entries are being synced in the logs, route traffic to `` and enable all load balancer API endpoints(privileged and end-user flows). - -!!! note "Important" - Do not stop the tool at once, let it sync any remaining data in the temp tables after routing the traffic. - -## Verifying the key rotation - -- Check the log files to verify if re-encryption happened successfully for the 7 identity and registry database tables. Check the logs given below for the successful/failed re-encryption counts of OAuth2 access and refresh tokens. - - ??? tip "DB log sample" - ``` - Successfully updated OAuth2 access and refresh tokens data records in IDN_OAUTH2_ACCESS_TOKEN: 897 - Failed OAuth2 access and refresh tokens data records in IDN_OAUTH2_ACCESS_TOKEN: 0 - ``` - - !!! note - If the key rotation task is successful, the failed logs count should be `0` for all the tables. - -- Check the log files to verify if re-encryption happened successfully for the 3 configuration files. Check the logs given below for the successful/failed re-encryption counts of event publisher configuration files. - - ??? tip "Config file log sample" - ``` - Updated event publisher configuration files: 8 - Failed event publisher configuration files: 0 - ``` - - !!! note - If the key rotation task is successful, the failed logs count should be `0` for all the configuration files. - -- Check the log files to verify if the transformation of the synced data happened successfully for the 4 tables. Check the logs given below for the successful/failed transformation counts of `IDN_IDENTITY_USER_DATA` table. - - ??? tip "Synced log sample" - ``` - Successfully transformed totp data records in IDN_IDENTITY_USER_DATA_TEMP: 2 - Transformation failed totp data records in IDN_IDENTITY_USER_DATA_TEMP: 0 - ``` - - !!! note - If the synced task is successful, the failed logs count should be `0` for all the synced tables. - -- Check for any errors in the log files and carefully analyze the logs if the error can be ignored and other steps can be proceeded with. Otherwise, check what has caused the error. - -## Recovering from any failure - -If the key rotation task stops midway, follow the blue green key rotation user guide steps again. - -If there are errors logged in the log files, carefully go through the errors and find what has caused the error. +{% include "../../../../../../includes/guides/encryption/blue-green-data-encryption-keyrotation.md" %} \ No newline at end of file diff --git a/en/identity-server/next/docs/deploy/security/symmetric-encryption/index.md b/en/identity-server/next/docs/deploy/security/symmetric-encryption/index.md index d72560d24d..14367ded0a 100644 --- a/en/identity-server/next/docs/deploy/security/symmetric-encryption/index.md +++ b/en/identity-server/next/docs/deploy/security/symmetric-encryption/index.md @@ -1 +1 @@ -{% include "../../../../../../includes/guides/encryption/symmetric-encryption.md" %} +{% include "../../../../../../includes/guides/encryption/index.md" %} \ No newline at end of file diff --git a/en/identity-server/next/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md b/en/identity-server/next/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md deleted file mode 100644 index 96b2a259f6..0000000000 --- a/en/identity-server/next/docs/deploy/security/symmetric-encryption/use-symmetric-encryption.md +++ /dev/null @@ -1 +0,0 @@ -{% include "../../../../../../includes/guides/encryption/use-symmetric-encryption.md" %} diff --git a/en/identity-server/next/mkdocs.yml b/en/identity-server/next/mkdocs.yml index c2fd5be424..1009dcb1fd 100644 --- a/en/identity-server/next/mkdocs.yml +++ b/en/identity-server/next/mkdocs.yml @@ -680,7 +680,6 @@ nav: - Encryption: - Symmetric encryption: - Symmetric encryption: deploy/security/symmetric-encryption/index.md - - Configure symmetric key encryption: deploy/security/symmetric-encryption/use-symmetric-encryption.md - Symmetric data encryption key rotation: deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation.md - Asymmetric encryption: - Asymmetric encryption: deploy/security/asymmetric-encryption/index.md diff --git a/en/includes/guides/encryption/blue-green-data-encryption-keyrotation.md b/en/includes/guides/encryption/blue-green-data-encryption-keyrotation.md new file mode 100644 index 0000000000..3bbdfe34c3 --- /dev/null +++ b/en/includes/guides/encryption/blue-green-data-encryption-keyrotation.md @@ -0,0 +1,250 @@ +# Blue-Green Data Encryption Key Rotation + +This section contains the complete process you need to follow in order to perform symmetric data encryption key rotation in WSO2 Identity Sever(WSO2 IS version 5.11.0 and above). + +Key rotation can be defined as retiring an encryption key and replacing it with a new key. Data is encrypted using a key known as a Data Encryption Key(DEK) and the DEK is then encrypted with another key called Key Encryption Key(KEK). This is known as envelope encryption. Frequent rotations of these encryption keys are considered as an industry best practice by PCI DSS and NIST standards. + +## Why should you rotate encryption keys? + +!!! info + Originator Usage Period (OUP) is the time period during which encryption is applied to data. + +- A cryptoperiod is the time span during which a specific key is authorized for use. [NIST SP 800-57](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57pt1r5.pdf){:target="_blank"} recommends different cryptoperiods for different encryption key types. + + - Symmetric Data Encryption Keys + + - OUP recommended for large volumes of data is about a day or a week. + - OUP recommended for smaller volumes of data is about 2 years. + + - Symmetric Key, Wrapping Keys + + - OUP recommended for a key that wraps a large number of keys is about a day or a week. + - OUP recommended for a key that wraps a smaller number of keys is up to 2 years. + +- Security compliance requirements +- Security breach requirements + +!!! note + The above-mentioned cryptoperiods can vary based on other factors like the sensitivity of data and the amount of data we have. + +## Background + +WSO2 Identity Server has the following key usages for signing/encrypting data and each of these types will have different key rotation requirements. + +- TLS Connection +- Signing and encryption of data (JWT assertions, payloads) shared with external parties (SP, IdP). +- Encryption of sensitive runtime level configuration secrets/user data persisted in datastores and user stores. +- Encryption of sensitive deployment-level configuration data in configuration files. + +From WSO2 IS 5.11.0 onwards, symmetric encryption is used to encrypt the internal sensitive runtime data above. The DEK used to encrypt these data is configured in the `deployment.toml` file and it is protected by a KEK. The secure vault is utilized as of now to protect this DEK. Here, only the rotation of the Data Encryption Key configured in the `deployment.toml` file is considered. + +## DEK rotation frequency + +In the case of a security compliance requirement, we can see that symmetric DEK rotation can be done in 2 years or less based on the volume of data present. + +In a security breach scenario, we must rotate the DEK immediately and re-encrypt all the data to the new DEK. + +## Key Rotation Approach + +WSO2 IS has introduced an external tool that re-encrypts internal data after rotation of the configured symmetric data encryption key. Here, the re-encryption of the identity and registry databases and some configuration files is considered. Apart from that, the tool syncs end-user data that gets generated in the live system to the new setup. + +The external Java client that performs the above tasks can be created by following the steps [here](#how-to-create-the-key-rotation-tool). + +## Tables that support re-encryption + +At the moment, the tables given below are supported for re-encryption. + +| **Table** | **Fields** | +|-----------|---------------| +| IDN_IDENTITY_USER_DATA | TOTP secretKey and verifiedSecretKey claims | +| IDN_OAUTH2_AUTHORIZATION_CODE | OAuth2 authorization codes | +| IDN_OAUTH2_ACCESS_TOKEN | OAuth2 access and refresh tokens | +| IDN_OAUTH_CONSUMER_APPS | Consumer secrets +| WF_BPS_PROFILE | BPS profile password | +| WF_REQUEST | WF request credentials | +| REG_PROPERTY | Keystore passwords, Keystore privatekeyPass, and Entitlement subscriberPasswords | + +## Configuration files that support re-encryption + +At the moment, the configuration files given below are supported for re-encryption. + +| **Configuration file** | **Path** | **Property** | +|---------------------------|-----------|--------------| +| Event publishers | `/repository/deployment/server/eventpublishers` files | Password | +| Super tenant secondary user stores | `/repository/deployment/server/userstores/` files | Password | +| Tenant secondary userstores | `/repository/tenants//userstores/` files | Password | + +## Tables that support syncing + +At the moment, the tables given below can be synced during key rotation from the old setup to the new setup. Any other data will not be persisted in the new setup. + +| **Table** | **Purpose** | **Recommendation** | +|-----------|---------------|-----------------------| +| IDN_IDENTITY_USER_DATA | Identity claims when the identity data store is enabled | Usually recommended to sync if identity management features are enabled in the system | +| IDN_OAUTH2_ACCESS_TOKEN | OAuth 2.0 tokens | Need to sync if the tokens created during the key rotation period need to be valid after key rotation | +| IDN_OAUTH2_ACCESS_TOKEN_SCOPE | OAuth 2.0 scopes | If the IDN_OAUTH2_ACCESS_TOKEN is synced, this table also needs to be synced | +| IDN_OAUTH2_AUTHORIZATION_CODE | OAuth 2.0 authorization codes | Need to sync if the authorization codes created during the key rotation period need to be valid after key rotation | + +## How To Create The Key Rotation Tool + +!!! note + In this section, `` is the directory where the current Identity Server resides, and `` is the directory where the copy of the current Identity Server resides. `` refers to the location [here](https://github.com/wso2/identity-tools/components/org.wso2.carbon.identity.keyrotation){:target="_blank"} and the `` refers to the location of the external tool. + +1. Clone the repository, [identity-tools](https://github.com/wso2/identity-tools){:target="_blank"}. + +2. Build it using maven by running the command `mvn clean install`. + +3. Go to the `/target` folder and copy the `keyrotation-tool--SNAPSHOT.jar` file and the `/target/lib` folder to ``. Get the `properties.yaml` file, `keyrotation.sh` file, and the `triggers` folder from `/src/main/resources` and copy them to the same `` location. + +## Performing blue-green key rotation + +1. Block all privileged user flows and allow only end-user flows. + + !!! note + For the privileged user flows, block all admin services from the load balancer and the management console as well. For end user flows, the above [tables]({{base_path}}/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation/#tables-that-support-re-encryption) will be synced to the ``, so only these end user data flows should be allowed to generate in ``. + +2. Execute the `old.sql` script in the `` identity database to create temp tables and triggers. The triggers can be found inside the `/triggers` folder. + +3. Create a copy of the ``(This copied directory will be referred to as the `NEW_IS_HOME`) and dump `` identity and registry databases and create the new databases. + +4. Drop the temp tables and triggers in the `` identity database using the `new.sql` script. The triggers can be found inside the `/triggers` folder. + +5. Open the `properties.yaml` file in `` and edit the configurations accordingly. + + - oldSecretKey - The symmetric encryption key used in the ``. + + !!! note + If the key is encrypted using cipher tool, decrypt it back as shown [here](https://shagihan.medium.com/decrypt-encrypted-text-with-the-wso2-cipher-tool-15b67624620a){:target="_blank"}. + + - newSecretKey - The new symmetric encryption key. + + !!! tip + Generate using a tool like openssl using the command, `openssl rand -hex 16`. + + - newISHome - The absolute path of the ``. + - oldIdnDBUrl - `` identity database URL. + - oldIdnUsername - `` identity database username. + - oldIdnPassword - `` identity database password (Encoded in [base64](https://www.base64encode.org/){:target="_blank"}). + - newIdnDBUrl - `` identity database URL. + - newIdnUsername - `` identity database username. + - newIdnPassword - `` identity database password (Encoded in [base64](https://www.base64encode.org/){:target="_blank"}). + - newRegDBUrl - `` registry database URL. + - newRegUsername - `` registry database username. + - newRegPassword - `` registry database password (Encoded in [base64](https://www.base64encode.org/){:target="_blank"}). + - enableDBMigrator - Enable/disable re-encryption for the identity and registry databases. + + !!! note + Keep this always **true** to avoid unnecessary issues. + + - enableConfigMigrator - Enable/disable re-encryption for the configuration files. + + !!! note + Keep this always **true** to avoid unnecessary issues. + + - enableSyncMigrator - Enable/disable syncing mechanism. + + !!! note + You only need to set this to **true**, if you have opted in for blue-green key rotation with zero downtime for the end user flows. + + - chunkSize - Size of the record chunks being retrieved from the database tables for syncing. + + ??? tip "Sample configuration written for the properties.yaml file" + + ``` + oldSecretKey: AFA27B44D43B02A9FEA41D13CEDC2E40 + newSecretKey: 1fc0bc7a3805b42afa5f5af07a595f56 + newISHome: /home/IS/wso2is-5.12.0 + oldIdnDBUrl: jdbc:mysql://localhost:3306/regdb?useSSL=false + oldIdnUsername: root + oldIdnPassword: cm9vdA== + newIdnDBUrl: jdbc:mysql://localhost:3306/regdb1?useSSL=false + newIdnUsername: root + newIdnPassword: cm9vdA== + newRegDBUrl: jdbc:mysql://localhost:3306/regdb1?useSSL=false + newRegUsername: root + newRegPassword: cm9vdA== + enableDBMigrator: true + enableConfigMigrator: true + enableSyncMigrator: true + chunkSize: 2 + ``` + + ??? tip "Sample configurations written for DB type URL" + **H2 DB** + ``` + jdbc:h2:~/Desktop/IS/copy/wso2is-5.11.0-beta5-SNAPSHOT/repository/database/WSO2IDENTITY_DB + ``` + **MySQL** + ``` + jdbc:mysql://localhost:3306/idndb?useSSL=false + ``` + **DB2** + ``` + jdbc:db2://localhost:50000/idndb + ``` + **PostgreSQL** + ``` + jdbc:postgresql://localhost:5432/idndb + ``` + **MSSQL** + ``` + jdbc:sqlserver://localhost:1433;databaseName=idndb + ``` + **Oracle DB** + ``` + jdbc:oracle:thin:@localhost:1521/ORCLCDB.LOCALDOMAIN + ``` + +6. Run the tool using the `./keyrotation.sh keyrotation-tool--SNAPSHOT.jar` command from ``. + +7. Edit the `` `deployment.toml` file having the new configured databases and the new key. + +8. Start `` once the re-encryption for the existing DB and config file is done. + +9. When no new entries are being synced in the logs, route traffic to `` and enable all load balancer API endpoints(privileged and end-user flows). + +!!! note "Important" + Do not stop the tool at once, let it sync any remaining data in the temp tables after routing the traffic. + +## Verifying the key rotation + +- Check the log files to verify if re-encryption happened successfully for the 7 identity and registry database tables. Check the logs given below for the successful/failed re-encryption counts of OAuth2 access and refresh tokens. + + ??? tip "DB log sample" + ``` + Successfully updated OAuth2 access and refresh tokens data records in IDN_OAUTH2_ACCESS_TOKEN: 897 + Failed OAuth2 access and refresh tokens data records in IDN_OAUTH2_ACCESS_TOKEN: 0 + ``` + + !!! note + If the key rotation task is successful, the failed logs count should be `0` for all the tables. + +- Check the log files to verify if re-encryption happened successfully for the 3 configuration files. Check the logs given below for the successful/failed re-encryption counts of event publisher configuration files. + + ??? tip "Config file log sample" + ``` + Updated event publisher configuration files: 8 + Failed event publisher configuration files: 0 + ``` + + !!! note + If the key rotation task is successful, the failed logs count should be `0` for all the configuration files. + +- Check the log files to verify if the transformation of the synced data happened successfully for the 4 tables. Check the logs given below for the successful/failed transformation counts of `IDN_IDENTITY_USER_DATA` table. + + ??? tip "Synced log sample" + ``` + Successfully transformed totp data records in IDN_IDENTITY_USER_DATA_TEMP: 2 + Transformation failed totp data records in IDN_IDENTITY_USER_DATA_TEMP: 0 + ``` + + !!! note + If the synced task is successful, the failed logs count should be `0` for all the synced tables. + +- Check for any errors in the log files and carefully analyze the logs if the error can be ignored and other steps can be proceeded with. Otherwise, check what has caused the error. + +## Recovering from any failure + +If the key rotation task stops midway, follow the blue green key rotation user guide steps again. + +If there are errors logged in the log files, carefully go through the errors and find what has caused the error. diff --git a/en/includes/guides/encryption/use-symmetric-encryption.md b/en/includes/guides/encryption/index.md similarity index 58% rename from en/includes/guides/encryption/use-symmetric-encryption.md rename to en/includes/guides/encryption/index.md index 0c927e6b4f..551d84e3c1 100644 --- a/en/includes/guides/encryption/use-symmetric-encryption.md +++ b/en/includes/guides/encryption/index.md @@ -1,23 +1,42 @@ -# Configure symmetric key encryption +# Symmetric Encryption -This section explains the configurations related to [symmetric key encryption]({{base_path}}/deploy/security/symmetric-encryption). +Symmetric encryption uses a single key to encrypt and decrypt information. In {{product_name}} version 7.0.0, symmetric encryption is used by default. -WSO2 Identity Server uses symmetric encryption by default for encrypting the following data: +!!! note + If required, you may switch to [asymmetric key encryption]({{base_path}}/deploy/security/asymmetric-encryption/). -- Event publisher passwords -- Secondary user store properties -- TOTP `secretKey` and `verifiedSecretKey` claims -- OAuth 2.0 authorization codes, access tokens, refresh tokens, and consumer secrets (only when encryption enabled) +## Why symmetric key encryption? + +In all versions of WSO2 Identity Server prior to 5.11.0, asymmetric key encryption was used for signing purposes and for encrypting internal data. However, from version 7.0.0 onwards, symmetric key encryption is used as the default encryption mechanism due to the following reasons: + +- **Ability to easily change key stores** - In earlier versions, internal data was encrypted using asymmetric key encryption. This means that whenever the certificates expire, or when the keystore is changed, all encrypted data should be migrated. With the shift to symmetric encryption, this overhead is now removed. The secret key involved in symmetric key encryption is encrypted using asymmetric key encryption. Therefore, the secret key needs to be re-encrypted only when the keystore changes. + +- **Industry-wide usage** - Symmetric key encryption is used as an accepted industry-wide mechanism for encrypting internal sensitive data. This includes both on-premise and cloud platforms. + +- **Post-Quantum Security** - Quantum computers have the potential to break widely-used asymmetric encryption algorithms such as RSA and ECC by efficiently solving the underlying mathematical problems. Symmetric key encryption, on the other hand, is more resistant to quantum attacks. + +!!! info + For more information on symmetric key encryption properties, see [Configure Symmetric Key Encryption]({{base_path}}/deploy/security/symmetric-encryption/use-symmetric-encryption). + +## How is it used? + +{{product_name}} uses [symmetric key encryption]({{base_path}}/deploy/security/symmetric-encryption) to encrypt the following data. + +- Event publisher passwords. +- Secondary user store properties. +- `secretKey` and `verifiedSecretKey` claims of TOTP authentication. +- OAuth 2.0 authorization codes, access tokens, refresh tokens, and consumer secrets (when encryption is enabled). !!! note To enable encryption of OAuth 2.0 authorization codes, access tokens, refresh tokens, and consumer secrets, add the following configuration to the `deployment.toml` found in the `/repository/conf/` directory. + ```toml [oauth.extensions] token_persistence_processor = "org.wso2.carbon.identity.oauth.tokenprocessor.EncryptionDecryptionPersistenceProcessor" ``` -- Secondary keystore passwords, and private-key passwords +- Secondary keystore passwords and private-key passwords - BPS profile passwords - Workflow request credentials @@ -27,7 +46,7 @@ For other types of encryption, [asymmetric encryption]({{base_path}}/deploy/secu !!! warning All configuration changes should be applied before starting Identity Server for the first time. Otherwise, a [key rotation]({{base_path}}/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation) will be required. -## Configure a secret key +## Generate a secret key For enhanced security, it is recommended to generate your own secret key for symmetric key encryption in {{product_name}}. To do so, @@ -65,15 +84,15 @@ For enhanced security, it is recommended to generate your own secret key for sym If a custom encryption key is not provided, the value of `encryption.key` in this configuration file will be used as the default key. -## Algorithm used +## Algorithm -`AES/GCM/NoPadding` is used as the symmetric key encryption algorithm. +{{product_name}} uses the `AES/GCM/NoPadding` algorithm for symmetric key encryption. GCM is a stream cipher. Hence, there is a performance advantage of using it due to the parallel encryption of each block. There is no need to use a padding mechanism in GCM mode. In GCM mode, the initialization vector (IV) should be a unique value for each encryption request. The corresponding IVs of each unique value should be kept track of in order to decrypt this internal data. {% if is_version == "7.0.0" %} -The keysize supported is AES-128. +The key size supported is AES-128. {% else %} @@ -94,3 +113,4 @@ The following configuration is enabled by default in the `/repository/r ## Encrypting symmetric encryption key with cipher tool It is advised to encrypt the symmetric encryption key with a cipher tool as mentioned [here]({{base_path}}/deploy/security/encrypt-passwords-with-cipher-tool). + diff --git a/en/includes/guides/encryption/symmetric-encryption.md b/en/includes/guides/encryption/symmetric-encryption.md deleted file mode 100644 index 6d76a86b4d..0000000000 --- a/en/includes/guides/encryption/symmetric-encryption.md +++ /dev/null @@ -1,16 +0,0 @@ -# Symmetric Encryption - -In symmetric encryption, a single key is used for the encryption and decryption of information. In WSO2 Identity Server version 7.0.0, symmetric encryption is used by default. If required, you may switch to [asymmetric key encryption]({{base_path}}/deploy/security/asymmetric-encryption/). - -## Why symmetric key encryption? - -In all versions of WSO2 Identity Server prior to 5.11.0, asymmetric key encryption was used for signing purposes and for encrypting internal data. However, from version 7.0.0 onwards, symmetric key encryption is used as the default encryption mechanism due to the following reasons: - -- **Ability to easily change key stores** - In earlier versions, internal data was encrypted using asymmetric key encryption. This means that whenever the certificates expire, or when the keystore is changed, all encrypted data should be migrated. With the shift to symmetric encryption, this overhead is now removed. The secret key involved in symmetric key encryption is encrypted using asymmetric key encryption. Therefore, the secret key needs to be re-encrypted only when the keystore changes. - -- **Industry-wide usage** - Symmetric key encryption is used as an accepted industry-wide mechanism for encrypting internal sensitive data. This includes both on-premise and cloud platforms. - -- **Post-Quantum Security** - Quantum computers have the potential to break widely-used asymmetric encryption algorithms such as RSA and ECC by efficiently solving the underlying mathematical problems. Symmetric key encryption, on the other hand, is more resistant to quantum attacks. - -!!! info - For more information on symmetric key encryption properties, see [Configure Symmetric Key Encryption]({{base_path}}/deploy/security/symmetric-encryption/use-symmetric-encryption). From 9e4ff36b3d6a997aa3266bd48c0412f90dfd5be0 Mon Sep 17 00:00:00 2001 From: himeshsiriwardana Date: Mon, 4 Nov 2024 16:41:09 +0530 Subject: [PATCH 3/3] improved index file --- en/includes/guides/encryption/index.md | 58 +++++++++++--------------- 1 file changed, 24 insertions(+), 34 deletions(-) diff --git a/en/includes/guides/encryption/index.md b/en/includes/guides/encryption/index.md index 551d84e3c1..bedab209e3 100644 --- a/en/includes/guides/encryption/index.md +++ b/en/includes/guides/encryption/index.md @@ -1,13 +1,13 @@ # Symmetric Encryption -Symmetric encryption uses a single key to encrypt and decrypt information. In {{product_name}} version 7.0.0, symmetric encryption is used by default. +Symmetric encryption uses a single key to encrypt and decrypt information. {{product_name}} uses symmetric encryption by default. !!! note If required, you may switch to [asymmetric key encryption]({{base_path}}/deploy/security/asymmetric-encryption/). ## Why symmetric key encryption? -In all versions of WSO2 Identity Server prior to 5.11.0, asymmetric key encryption was used for signing purposes and for encrypting internal data. However, from version 7.0.0 onwards, symmetric key encryption is used as the default encryption mechanism due to the following reasons: +From {{product_name}} version 7.0.0 onwards, symmetric key encryption is used as the default encryption mechanism due to the following reasons: - **Ability to easily change key stores** - In earlier versions, internal data was encrypted using asymmetric key encryption. This means that whenever the certificates expire, or when the keystore is changed, all encrypted data should be migrated. With the shift to symmetric encryption, this overhead is now removed. The secret key involved in symmetric key encryption is encrypted using asymmetric key encryption. Therefore, the secret key needs to be re-encrypted only when the keystore changes. @@ -20,6 +20,18 @@ In all versions of WSO2 Identity Server prior to 5.11.0, asymmetric key encrypti ## How is it used? +{{product_name}} uses the `AES/GCM/NoPadding` algorithm for symmetric key encryption. GCM is a stream cipher and therefore, enables simultaneous encryption of multiple blocks, resulting in faster data encryption. + +{% if is_version == "7.0.0" %} + +The supported key size is AES-128. + +{% else %} + +The supported key sizes are AES-128, AES-192, and AES-256. + +{% endif %} + {{product_name}} uses [symmetric key encryption]({{base_path}}/deploy/security/symmetric-encryption) to encrypt the following data. - Event publisher passwords. @@ -42,13 +54,14 @@ In all versions of WSO2 Identity Server prior to 5.11.0, asymmetric key encrypti For other types of encryption, [asymmetric encryption]({{base_path}}/deploy/security/asymmetric-encryption) is used by default. +## Generate a secret key -!!! warning - All configuration changes should be applied before starting Identity Server for the first time. Otherwise, a [key rotation]({{base_path}}/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation) will be required. +For enhanced security, it is recommended to generate your own secret key for symmetric key encryption in {{product_name}}. -## Generate a secret key +!!! warning + All configuration changes should be applied before starting {{product_name}} for the first time. Otherwise, a [key rotation]({{base_path}}/deploy/security/symmetric-encryption/blue-green-data-encryption-keyrotation) will be required. -For enhanced security, it is recommended to generate your own secret key for symmetric key encryption in {{product_name}}. To do so, +To do so, {% if is_version == "7.0.0" %} @@ -65,6 +78,9 @@ For enhanced security, it is recommended to generate your own secret key for sym key = "9a131db7d3fce3adb0850b486bfc6528" ``` + !!! note + + It is advised to encrypt the symmetric encryption key with a cipher tool as mentioned [here]({{base_path}}/deploy/security/encrypt-passwords-with-cipher-tool). {% else %} 1. Generate a unique 256-bit secret key. If you use OpenSSL, the command will be as follows: @@ -84,33 +100,7 @@ For enhanced security, it is recommended to generate your own secret key for sym If a custom encryption key is not provided, the value of `encryption.key` in this configuration file will be used as the default key. -## Algorithm - -{{product_name}} uses the `AES/GCM/NoPadding` algorithm for symmetric key encryption. - -GCM is a stream cipher. Hence, there is a performance advantage of using it due to the parallel encryption of each block. There is no need to use a padding mechanism in GCM mode. In GCM mode, the initialization vector (IV) should be a unique value for each encryption request. The corresponding IVs of each unique value should be kept track of in order to decrypt this internal data. - -{% if is_version == "7.0.0" %} - -The key size supported is AES-128. - -{% else %} - -The supported key sizes are AES-128, AES-192, and AES-256. - -{% endif %} - -## Internal crypto provider - -The `org.wso2.carbon.crypto.provider.SymmetricKeyInternalCryptoProvider` provider is used as the internal crypto provider. When configuring the `SymmetricKeyInternalCryptoProvider`, the secret key value needs to be provided in the configuration as well. - -The following configuration is enabled by default in the `/repository/resources/conf/default.json` file to use the above-mentioned internal crypto provider. - -```json -"encryption.internal_crypto_provider": "org.wso2.carbon.crypto.provider.SymmetricKeyInternalCryptoProvider" -``` - -## Encrypting symmetric encryption key with cipher tool +!!! note "Important" -It is advised to encrypt the symmetric encryption key with a cipher tool as mentioned [here]({{base_path}}/deploy/security/encrypt-passwords-with-cipher-tool). + It is highly recommended to encrypt the secret key using the [cipher tool]({{base_path}}/deploy/security/encrypt-passwords-with-cipher-tool/).