Chapter 13. Secure Parameters

Transformation graphs in CloverETL Server environment allow you to define secure graph parameters. Secure graph parameters are regular graph parameters, either internal or external (in a *.prm file), but the values of the graph parameters are not stored in plain text on the file system - encrypted values are persisted instead. This allows you to use graph parameters to handle sensitive information, typically credentials such as passwords to databases.

Secure parameters are only available in CloverETL Server environment, including working with CloverETL Server Projects in CloverETL Designer.

The encryption algorithm must be initialized with a master password. The master password has to be manually set after server installation in Configuration > Secure Parameters > Master password. Secure parameters cannot be used before the master password is set.

Master password initialization

Figure 13.1. Master password initialization


After setting the master password secure parameters are fully available in Graph parameter editor in CloverETL Designer. When setting value of a secure parameter, it will be automatically encrypted using the master password. Secure parameters are automatically decrypted by server in graph runtime. A parameter value can also be encrypted in the CloverETL Server Console in the Configuration > Secure Parameters page - use the Encrypt text section.

Graph parameters tab with initialized master password

Figure 13.2. Graph parameters tab with initialized master password


If you change the master password, the secure parameters encrypted using the old master password cannot be decrypted correctly anymore. In that case existing secure parameters need to be encrypted again with the new master password. That can be accomplished simply by setting their value (non-encrypted) again in the Graph parameter editor. Similar master password inconsistency issue can occur if you move a transformation graph with some secure parameters to another server with a different master password. So it is highly recommended to use the identical master password for all your CloverETL Server installations.

See documentation of secure parameters in CloverETL Designer manual for further details.

Secure parameters configuration

Encryption of secure parameters can be further customized via server configuration parameters.

Table 13.1. Secure parameters configuration parameters

Property nameDefault valueDescription
security.job_parameters.encryptor.algorithm PBEWithMD5AndDES

The algorithm to be used for encryption. This algorithm has to be supported by your JCE provider (if you specify a custom one, or the default JVM provider if you don't). The name of algorithm should start with PBE prefix.

The list of available algorithms depends on your JCE provider, e.g. for the default SunJCE provider you can find them on http://docs.oracle.com/javase/6/docs/technotes/guides/security/SunProviders.html#SunJCEProvider or for the Bouncy Castle provider on http://www.bouncycastle.org/specifications.html (section Algorithms/PBE)).

security.job_parameters.encryptor.master_password_encryption.password clover The password used to encrypt values persisted in the database table secure_param_passwd (the master password is persisted there).
security.job_parameters.encryptor.providerClassName Empty string. The default JVM provider is used (e.g. for Oracle Java the SunJCE provider is used) The name of the security provider to be asked for the encryption algorithm. It must implement java.security.Provider interface. For example set to org.bouncycastle.jce.provider.BouncyCastleProvider for the Bouncy Castle JCE provider, see below.

Installing Bouncy Castle JCE provider

Algorithms provided by JVM could be too weak to satisfy an adequate security. Therefore it is recommended to install a third-party JCE provider. Following example demonstrates installation of one concrete provider, Bouncy Castle JCE provider. Another provider would be installed similarly.

  1. Download Bouncy Castle provider jar (e.g. bcprov-jdk15on-150.jar) from http://bouncycastle.org/latest_releases.html

  2. Add the jar to the classpath of your application container running CloverETL Server, e.g. to directory WEB-INF/lib

  3. Set value of the security.job_parameters.encryptor.providerClassName attribute to org.bouncycastle.jce.provider.BouncyCastleProvider in the config.properties file.

  4. Set value of the security.job_parameters.encryptor.algorithm attribute to the desired algorithm (e.g. PBEWITHSHA256AND256BITAES-CBC-BC).

Example of configuration using Bouncy Castle:

		security.job_parameters.encryptor.algorithm=PBEWITHSHA256AND256BITAES-CBC-BC
		security.job_parameters.encryptor.providerClassName=org.bouncycastle.jce.provider.BouncyCastleProvider