Home | Table of ContentsSecure Configuration Properties CloverETL 4.7.0
Prev Configuration Next

Chapter 10. Secure Configuration Properties

Some configuration properties can be confidential (e.g. a password to database, mail client, etc.) and thus it's desirable to encrypt them. For this purpose, there is a command-line utility secure-cfg-tool.jar.

Basic Utility Usage
Advanced Usage - Custom Settings

Basic Utility Usage

  1. Get the utility archive file (secure-cfg-tool.zip) and unzip it.

    The utility is available in the download section of your CloverETL account - at the same location as the download of CloverETL Server.

  2. Execute the script given for your operating system, encrypt.bat for MS Windows, encrypt.sh for Linux. You will be asked for inserting a value of a configuration property intended to be encrypted.

    Example: 

    C:\secure-cfg-tool>encrypt.bat

**************************************************************
Secure config encryption (use --help or -h option to show help)
**************************************************************

****** Config settings ******
Provider: 	SunJCE
Algorithm: 	PBEWithMD5AndDES
*****************************

Enter text to encrypt: mypassword
Text to encrypt: "mypassword"
Encrypted text: conf#eCflGDlDtKSJjh9VyDlRh7IftAbI/vsH

C:\secure-cfg-tool>

    If you want to configure the way the values are encrypted, see Advanced Usage - Custom Settings

  3. Encrypted string has conf#encrypted_property format. The encrypted string can be used as a value of a configuration property in the properties file, clover.xml file or web.xml file (see details about configuration sources in Chapter 6, Configuration Sources and Their Priorities).

    Example (snippet of a configuration property file): 

    jdbc.driverClassName=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://example.com:3306/clover?useUnicode=true&characterEncoding=utf8
jdbc.username=example
jdbc.password=conf#eCflGDlDtKSJjh9VyDlRh7IftAbI/vsH
jdbc.dialect=org.hibernate.dialect.MySQLDialect

[Note]Note

Alternatively, java -jar secure-cfg-tool.jar command can be used.

[Important]Important

Values encrypted by a Secure parameter form (Chapter 13, Secure Parameters) cannot be used as a value of a configuration property.

Advanced Usage - Custom Settings

The way of encrypting configuration values described above uses default configuration settings (a default provider and algorithm). But if there is a need to change these default settings with the custom ones, the secure-cfg-tool.jar utility offers a set of parameters to achieve that.

Table 10.1. Parameters

ParameterDescriptionExample
--algorithm, -aalgorithm to encrypt--algorithm PBEWithMD5AndDES
--file, -fconfig file location-f C:\User\John\cloverServer.properties
--help, -hshow help--help
--providerclass, -ccustom provider class-c org.provider.ProviderClass
--providerlocation, -lpath to jar/folder containing a custom provider class (it will be added to the classpath)--providerlocation C:\User\John\lib\customprovider.jar, -l C:\User\John\lib\
--providers, -pprint available security providers and their algorithms--providers

[Note]Note

To demonstrate usage of an external provider the Bouncy Castle provider is used.

To find out a list of algorithms use -p or --providers

		C:\secure-cfg-tool>encrypt.bat -p

If you want to find out a list of algorithms of an external provider, you must pass the provider's class name and path to jar file(s)

		C:\secure-cfg-tool>encrypt.bat -p -c org.bouncycastle.jce.provider.BouncyCastleProvider -l C:\User\John\bcprov-jdk15on-152.jar

Result might look like this

		***** List of available providers and their algorithms *****
		Provider: SunJCE
		Provider class: com.sun.crypto.provider.SunJCE
			Algorithms:
				PBEWithMD5AndDES
				PBEWithSHA1AndDESede
				PBEWithSHA1AndRC2_40
		Provider: BC
		Provider class: org.bouncycastle.jce.provider.BouncyCastleProvider
			Algorithms:
				PBEWITHMD2ANDDES
				PBEWITHMD5AND128BITAES-CBC-OPENSSL
				PBEWITHMD5AND192BITAES-CBC-OPENSSL
				PBEWITHMD5AND256BITAES-CBC-OPENSSL

Provider class is displayed on the row starting with Provider class, algorithms are strings with PBE prefix. Both can be used to configure encryption.

Configuring the Encryption Process

Algorithm and provider can be passed to the utility in two ways.

  • Using command line arguments

    To change the algorithm use argument -a. Provider remains the default one (SunJCE in case of Oracle Java). 

    		C:\secure-cfg-tool>encrypt.bat -a PBEWithMD5AndDES

    Using of an external provider is a little more complex. Provider's class name must be specified (argument --providerclass or -c) and jar(s) must be added to the classpath (argument --providerlocation, -l). Provider location must point to concrete jar file or directory containing jar(s) and can be used several times for several paths. 

    		C:\secure-cfg-tool>encrypt.bat -a PBEWITHSHA256AND256BITAES-CBC-BC -c org.bouncycastle.jce.provider.BouncyCastleProvider -l C:\User\John\bcprov-jdk15on-152.jar

  • Using configuration file

    A configuration file is a common properties file (text file with key-value pairs):

    [property-key]=[property-value]

    It might look like this (example comes from secure.config.example.properties, distributed within secure-cfg-tool.zip): 

    		security.config_properties.encryptor.providerClassName=org.bouncycastle.jce.provider.BouncyCastleProvider
		security.config_properties.encryptor.algorithm=PBEWITHSHA256AND256BITAES-CBC-BC
		security.config_properties.encryptor.provider.location=C:\\User\\libs

    To let utility know about the configuration file use -f argument 

    		C:\secure-cfg-tool>encrypt.bat -f secure.config.example.properties

    [Note]Note

    More jar locations can be set in the security.config_properties.encryptor.providerLocation, locations are delimited by semicolon.

Configuring an application server

CloverETL Server application needs to know how the values have been encrypted, therefore the properties must be passed to the server (see details in Part III, “Configuration”). For example: 

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

[Important]Important

If a third-party provider is used, its classes must be accessible for the application server. Property security.config_properties.encryptor.providerLocation will be ignored.

Prev Up Next
List of Properties Home | Table of Contents Logging