Version

    Chapter 18. Secure Configuration Properties

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

    Basic Utility Usage
    Advanced Usage - Custom Settings
    Configuring application server

    Basic Utility Usage

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

      The utility is available in the download section of your CloverDX account - at the same location as the download of CloverDX 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. The encrypted string has conf#encrypted_property format and 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 14, Configuration Sources).

      Example of a configuration property file with encrypted password:

      jdbc.driverClassName=org.postgresql.Driver
      jdbc.url=jdbc:postgresql://127.0.0.1/clover_db?charSet=UTF-8
      jdbc.username=yourUsername
      jdbc.password=conf#eCflGDlDtKSJjh9VyDlRh7IftAbI/vsH
      jdbc.dialect=org.hibernate.dialect.PostgreSQLDialect

    Alternatively, you can use the following command:

    java -jar secure-cfg-tool.jar
    [Important]Important

    Values encrypted by a Secure parameter form (Chapter 24, 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). If you need to customize the settings, use the following parameters of the secure-cfg-tool.jar utility.

    Table 18.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

    The 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

    The 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

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

    • Using command line arguments

      To change the algorithm, use the argument -a. The provider remains default (SunJCE in the case of Oracle Java):

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

      To use an external provider, you must specify the provider's class name (the --providerclass or -c arguments) and add jar(s) to the classpath (the --providerlocation or -l arguments). Provider location must point to a concrete jar file or directory containing the 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]

      See the following example of 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.providerLocation=C:\\User\\libs

      You must also set the path to the file using the -f argument:

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

      [Note]Note

      More jar locations can be set with the security.config_properties.encryptor.providerLocation property. The locations are delimited by semicolon.

    Configuring an application server

    CloverDX 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 to the application server. Property security.config_properties.encryptor.providerLocation will be ignored.