Update encryptable-properties docs for AES-256-GCM encryption

docs/administration/configuration/encryptable-properties.md

@@ -13,19 +13,18 @@ For instance you might want to encrypt the bind password to your LDAP server. Le
 
 ### Encrypting Property values
 
-Runbook Automation has a feature to allow you to generate encrypted passwords using the Jasypt encryption library. The following instructions show how to encrypt a password with this utility from the command line.
+Runbook Automation includes a built-in utility to generate encrypted property values using AES-256-GCM authenticated encryption. The following instructions show how to encrypt a password with this utility from the command line.
 
 cd into the directory where your rundeck.war is located
 run:
 
 ```shell
-java -jar rundeck.war --encryptpwd Jasypt
-
+java -jar rundeck.war --encryptpwd Encryptable-properties
 ```
 
 You will receive prompts for information that look like the following:
 
-```
+```text
 Required values are marked with: *
 Encrypter Config (The base property name used in RD_ENCRYPTION_ or rd.encryption. ('default' is the default value)):
 
@@ -38,11 +37,15 @@ binder123 (this won't be displayed)
 *Verify Value To Encrypt (Verify the text you want to encrypt):
 
 ==ENCRYPTED OUTPUT==
-encrypted: bbnJmDtx82/NOeUc9ahULGVAH+RdSLG5
+encrypted: AQD3f8k2...base64-encoded-value...
 ```
 
-You will take the `encrypted:` value from the ENCRYPTED OUTPUT section which will have a value that looks like: `bbnJmDtx82/NOeUc9ahULGVAH+RdSLG5` (note that it will not be this value) and use it in your rundeck-config.properties file like this:
-`rundeck.security.ldap.bindPassword=ENC(bbnJmDtx82/NOeUc9ahULGVAH+RdSLG5)`
+You will take the `encrypted:` value from the ENCRYPTED OUTPUT section and use it in your rundeck-config.properties file like this:
+`rundeck.security.ldap.bindPassword=ENC(AQD3f8k2...base64-encoded-value...)`
+
+:::tip Upgrade Note
+Starting with Rundeck 6.0, new encrypted values use AES-256-GCM. Existing `ENC()` values encrypted with previous versions are automatically detected and decrypted without any configuration changes.
+:::
 
 ### Decrypting rundeck-config.properties
 
@@ -56,40 +59,24 @@ RDECK_JVM_SETTINGS=-Drd.encryption.default.password=1PwdToBindThem$
 
 Then we would start our Runbook Automation installation. After the application has completed the bootstrap process and is responding to requests, the environment variable can be unset for security purposes.
 
-### Advanced Usage
-
-If you wish to customize the algorithm, provider, or keyObtentions the Jasypt encryptor will use to encrypt the password, you can do this by passing those
-values as system properties when you launch the encryption utility.
-
-For example, if you wish to use the `PBEWITHSHA256AND256BITAES-CBC-BC` algorithm to encrypt your password, you could do it like this:
-
-```shell
-> java -jar -Drd.encryption.STRONG.algorithm=PBEWITHSHA256AND256BITAES-CBC-BC rundeckpro-cluster-3.0.0-SNAPSHOT.war --encryptpwd Jasypt
-Required values are marked with: *
-Encrypter Config (The base property name used in RD_ENCRYPTION_ or rd.encryption. ('default' is the default value)):
-STRONG
-*Master Password (Master password used to encrypt the value):
-1PwdToBindThem$ (this won't be displayed)
-*Verify Master Password (Verify master password):
-
-*Value To Encrypt (The text you want to encrypt):
-binder123 (this won't be displayed)
-*Verify Value To Encrypt (Verify the text you want to encrypt):
+### Advanced Usage (Legacy Decryption)
 
-==ENCRYPTED OUTPUT==
-encrypted: i67e4g3jAUML0KCh+KwmnqX9lCflThMuu6CXm++VSqU=
-```
-
-Notice we are setting an rd.encryption config with the name STRONG. Then when prompted for the `Encrypter Config` by the tool we type in the value `STRONG`. This sets the encryptor to use the algorithm passed by `rd.encryption.STRONG.algorithm` instead of the default configuration which uses a different algorithm.
+If you have existing encrypted values that were generated with a custom algorithm, provider, or keyObtentions in a previous Rundeck version, you can configure those settings so the system can decrypt them correctly.
 
-To use your custom encrypted password when you start Rundeck, it is very important to ensure that the same system properties you used at encrypt time are set at launch time. Otherwise Rundeck will use the default decryptor settings which will not match your customized settings, and startup will fail.
+:::warning
+These settings only affect **decryption of legacy values**. All new encryptions use AES-256-GCM regardless of these settings.
+:::
 
-To start Rundeck with the settings in our example, the startup string would be something like:
+For example, if your existing encrypted values were generated with the `PBEWITHSHA256AND256BITAES-CBC-BC` algorithm, set the corresponding system properties when starting Rundeck:
 
 ```shell
-java -jar -Drd.encryption.STRONG.algorithm=PBEWITHSHA256AND256BITAES-CBC-BC -Drundeck.encrypter.config.name=STRONG rundeckpro-cluster-3.0.0-SNAPSHOT.war
+java -Drd.encryption.STRONG.algorithm=PBEWITHSHA256AND256BITAES-CBC-BC \
+     -Drundeck.encrypter.config.name=STRONG \
+     -jar rundeck.war
 ```
 
+The `Encrypter Config` name (`STRONG` in this example) links the algorithm system property to the encrypted values. When the application encounters an `ENC(...)` value, it uses the configured algorithm and provider to decrypt legacy data.
+
 If you would rather use environment variables to set the encryption settings you can use:
 `RUNDECK_PROP_DECRYPTER_CONFIG` to set the config to use
 and config settings can be supplied like:
@@ -98,3 +85,13 @@ and config settings can be supplied like:
 For the example above, these would be:
 `export RUNDECK_PROP_DECRYPTER_CONFIG=STRONG`
 `export RD_ENCRYPTION_STRONG_ALGORITHM=PBEWITHSHA256AND256BITAES-CBC-BC`
+
+### Re-encrypting Legacy Values
+
+To migrate existing legacy-encrypted values to AES-256-GCM, re-run the encryption utility with the same master password:
+
+```shell
+java -jar rundeck.war --encryptpwd Encryptable-properties
+```
+
+Enter the plaintext value you want to encrypt. The output will be in the new AES-256-GCM format. Replace the old `ENC(...)` value in your configuration file with the new one. Both old and new formats are supported simultaneously, so migration can be done incrementally.

docs/administration/configuration/plugins/bundled-plugins.md

@@ -98,24 +98,26 @@ Provides a Workflow Step:
 
 File: `rundeck-flow-control-plugin-{{$rundeckVersionFull}}.jar`
 
-## Jasypt Encryption Plugin
+## AES-GCM Encryption Plugin
 
 Provides an encryption [storage converter](/administration/configuration/storage-facility.md#storage-converters) for the Storage facility. Can be used to encrypt the contents of Key Storage,
 and Project Configuration stored in the DB or on disk.
 
-This plugin provides password based encryption for storage contents.
-It uses the [Jasypt][] encryption library. The built in Java JCE is used unless another provider is specified, [Bouncycastle][] can be used by specifying the 'BC' provider name.
+This plugin provides password-based authenticated encryption using AES-256-GCM with PBKDF2 key derivation via [Bouncycastle][]. It can also transparently decrypt data encrypted by the previous Jasypt-based plugin, enabling seamless upgrades.
 
-[jasypt]: http://www.jasypt.org/
 [bouncycastle]: https://www.bouncycastle.org/
 
-Password, algorithm, provider, etc can be specified directly, or via environment variables (the `*EnvVarName` properties), or Java System properties (the `*SysPropName` properties).
+Password can be specified directly, or via environment variables (the `*EnvVarName` properties), or Java System properties (the `*SysPropName` properties).
 
 To enable it, see [Configuring - Storage Converter Plugins](/administration/configuration/plugins/configuring.md#storage-converter-plugins).
 
 See also: [Key Storage](/manual/key-storage/index.md)
 
-Provider type: `jasypt-encryption`
+Provider type: `aes-gcm-encryption`
+
+:::tip Backward Compatibility
+The legacy provider name `jasypt-encryption` is still supported as an alias. Existing configurations do not need to be changed after upgrade.
+:::
 
 The following encryption properties marked with `*` can be set directly,
 using the property name shown,
@@ -126,54 +128,65 @@ or `SysPropName` to use the Java System Property.
 If a System Property is specified: it is read in once and used by the initialization of the converter plugin,
 then the Java System Property is set to null so it cannot be read again.
 
-Configuration properties:
+#### Configuration properties
 
-`encryptorType`
+`password*`
+: The encryption password. This is the only required property.
 
-: Jasypt Encryptor to use. Either `basic`, `strong`, or `custom`. Default: 'basic'.
+Example configuration for **new installations**:
 
-    * `basic` uses algorithm `PBEWithMD5AndDES`
-    * `strong` requires use of the JCE Unlimited Strength policy files. (Algorithm: `PBEWithMD5AndTripleDES`)
-    * `custom` is required to specify the algorithm.
+```properties
+rundeck.storage.converter.1.type=aes-gcm-encryption
+rundeck.storage.converter.1.path=keys
+rundeck.storage.converter.1.config.password=YOUR_ENCRYPTION_PASSWORD
+```
 
-`password*`
-: the password.
+```properties
+rundeck.config.storage.converter.1.type=aes-gcm-encryption
+rundeck.config.storage.converter.1.path=projects
+rundeck.config.storage.converter.1.config.password=YOUR_ENCRYPTION_PASSWORD
+```
+
+#### Legacy properties (only needed when upgrading from a previous version)
+
+The following properties are only needed if you are upgrading from a Rundeck version that used the old `jasypt-encryption` plugin and you have existing encrypted data in your database. They tell the plugin how to **decrypt** that old data. New encryptions always use AES-256-GCM regardless of these settings.
+
+:::info
+If you are upgrading from a standard Rundeck installation (default settings), just add `encryptorType=custom` and use the same password you had before. No other legacy properties are needed.
+:::
+
+`encryptorType`
+: Identifies the legacy encryptor format used on existing data. Either `basic` or `custom`. Default: 'custom'.
 
-`algorithm*`
-: the encryption algorithm.
+    * `custom` — decrypts using algorithm `PBEWITHSHA256AND128BITAES-CBC-BC` with BC provider (the Rundeck default since 2014)
+    * `basic` — decrypts using algorithm `PBEWithMD5AndDES`
 
-`provider*`
-: the provider name. 'BC' indicates Bouncycastle.
+`algorithm`
+: (optional) Only needed if you previously configured a non-default algorithm. Overrides the legacy algorithm for decrypting existing data.
 
-`providerClassName*`
-: Java class name of the provider.
+`provider`
+: (optional) Only needed if you previously used a non-default JCE provider. Default: 'BC' (Bouncycastle).
 
-`keyObtentionIterations*`
-: Number of hashes to use for the password when generating the key, default is 1000.
+`keyObtentionIterations`
+: (optional) Only needed if you previously changed this from the default. Default: 1000.
 
-Example configuration for the Key Storage facility:
+Example configuration for an **upgrade** from a standard Rundeck installation:
 
 ```properties
-rundeck.storage.converter.1.type=jasypt-encryption
+rundeck.storage.converter.1.type=aes-gcm-encryption
 rundeck.storage.converter.1.path=keys
+rundeck.storage.converter.1.config.password=YOUR_EXISTING_PASSWORD
 rundeck.storage.converter.1.config.encryptorType=custom
-rundeck.storage.converter.1.config.passwordEnvVarName=ENC_PASSWORD
-rundeck.storage.converter.1.config.algorithm=PBEWITHSHA256AND128BITAES-CBC-BC
-rundeck.storage.converter.1.config.provider=BC
 ```
 
-Example configuration for the Project Configuration storage facility:
-
 ```properties
-rundeck.config.storage.converter.1.type=jasypt-encryption
-rundeck.config.storage.converter.1.path=/
-rundeck.config.storage.converter.1.config.password=sekrit
+rundeck.config.storage.converter.1.type=aes-gcm-encryption
+rundeck.config.storage.converter.1.path=projects
+rundeck.config.storage.converter.1.config.password=YOUR_EXISTING_PASSWORD
 rundeck.config.storage.converter.1.config.encryptorType=custom
-rundeck.config.storage.converter.1.config.algorithm=PBEWITHSHA256AND128BITAES-CBC-BC
-rundeck.config.storage.converter.1.config.provider=BC
 ```
 
-File: `rundeck-jasypt-encryption-plugin-{{$rundeckVersionFull}}.jar`
+File: `rundeck-aes-gcm-encryption-plugin-{{$rundeckVersionFull}}.jar`
 
 :::tip
 Note: the specific PBE algorithms available for use with the `encryptorType=custom` come from installed JCE providers.  BouncyCastle is included but others are provided by the specific JDK you use.  Here is a sample list of PBE providers using BouncyCastle and OpenJDK 1.8: