2.4. Using Encrypted Property Placeholders

Overview

When securing a container it is undesirable to use plain text passwords in configuration files. They create easy to target security holes. One way to avoid this problem is to use encrypted property placeholders when ever possible. This feature is supported in Blueprint XML files.

How to use encrypted property placeholders

To use encrypted property placeholders in a Blueprint XML file, perform the following steps:
  1. Download and install Jasypt, to gain access to the Jasypt listAlgorithms.sh, encrypt.sh and decrypt.sh command-line tools.
    Note
    When installing the Jasypt command-line tools, don't forget to enable execute permissions on the script files, by running chmod u+x ScriptName.sh.
  2. Choose a master password and an encryption algorithm. To discover which algorithms are supported in your current Java environment, run the listAlgorithms.sh Jasypt command-line tool, as follows: 
    ./listAlgorithms.sh
DIGEST ALGORITHMS:   [MD2, MD5, SHA, SHA-256, SHA-384, SHA-512]

PBE ALGORITHMS:      [PBEWITHMD5ANDDES, PBEWITHMD5ANDTRIPLEDES, PBEWITHSHA1ANDDESEDE, PBEWITHSHA1ANDRC2_40]
    On Windows platforms, the script is listAlgorithms.bat. JBoss A-MQ uses PBEWithMD5AndDES by default.
  3. Use the Jasypt encrypt command-line tool to encrypt your sensitive configuration values (for example, passwords for use in configuration files). For example, the following command encrypts the PlaintextVal value, using the specified algorithm and master password MasterPass: 
    ./encrypt.sh input="PlaintextVal" algorithm=PBEWithMD5AndDES password=MasterPass
  4. Create a properties file with encrypted values. For example, suppose you wanted to store some LDAP credentials. You could create a file, etc/ldap.properties, with the following contents:

    Example 2.8. Property File with an Encrypted Property

    #ldap.properties
ldap.password=ENC(EncryptedPassword)
ldap.url=ldap://192.168.1.74:10389
    The encrypted property values (as generated in the previous step) are identified by wrapping in the ENC() function. For example, in the preceding property file example you would replace the EncryptedPassword value with the output of the encrypt.sh Jasypt utility.
  5. (Blueprint XML only) Add the requisite namespaces to your Blueprint XML file:
    • Aries extensions—http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0
    • Apache Karaf Jasypt—http://karaf.apache.org/xmlns/jasypt/v1.0.0
    Example 2.9, “Encrypted Property Namespaces” shows a Blueprint file with the requisite namespaces.

    Example 2.9. Encrypted Property Namespaces

    <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
 	xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"
 	xmlns:enc="http://karaf.apache.org/xmlns/jasypt/v1.0.0">
...
</blueprint>
  6. Configure the location of the properties file for the property placeholder and configure the Jasypt encryption algorithm.
    • Blueprint XML
      Example 2.10, “Jasypt Blueprint Configuration” shows how to configure the ext:property-placeholder element to read properties from the etc/ldap.properties file. The enc:property-placeholder element configures Jasypt to use the PBEWithMD5AndDES encryption algorithm and to read the master password from the JASYPT_ENCRYPTION_PASSWORD environment variable.

      Example 2.10. Jasypt Blueprint Configuration

      <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
 	xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"
 	xmlns:enc="http://karaf.apache.org/xmlns/jasypt/v1.0.0">

  <ext:property-placeholder>
    <location>file:etc/ldap.properties</location>
  </ext:property-placeholder>

  <enc:property-placeholder>
    <enc:encryptor class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor">
      <property name="config">
        <bean class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig">
          <property name="algorithm" value="PBEWithMD5AndDES" />
          <property name="password" value="JASYPT_ENCRYPTION_PASSWORD" />
        </bean>
      </property>
    </enc:encryptor>
  </enc:property-placeholder>
...
</blueprint>
  7. Use the placeholders in your configuration file. The placeholders you use for encrypted properties are the same as you use for regular properties. Use the syntax ${prop.name}.
  8. Before starting up the JBoss A-MQ container, make sure that you set the JASYPT_ENCRYPTION_PASSWORD environment variable to the value of the master password. For example, on a Linux or UNIX system with the bash shell, you would set the environment variable as follows: 
    export JASYPT_ENCRYPTION_PASSWORD=MasterPass
  9. Make sure that the jasypt-encryption feature is installed in the container. If necessary, install the jasypt-encryption feature with the following console command: 
    JBossFuse:karaf@root> features:install jasypt-encryption

Blueprint XML example

Example 2.11, “Jasypt Example in Blueprint XML” shows an example of an LDAP JAAS realm configured in Blueprint XML, using Jasypt encrypted property placeholders.

Example 2.11. Jasypt Example in Blueprint XML

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
 	xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"
 	xmlns:enc="http://karaf.apache.org/xmlns/jasypt/v1.0.0">

  <ext:property-placeholder>
    <location>file:etc/ldap.properties</location>
  </ext:property-placeholder>

  <enc:property-placeholder>
    <enc:encryptor class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor">
      <property name="config">
        <bean class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig">
          <property name="algorithm" value="PBEWithMD5AndDES" />
          <property name="password" value="JASYPT_ENCRYPTION_PASSWORD" />
        </bean>
      </property>
    </enc:encryptor>
  </enc:property-placeholder>

  <jaas:config name="karaf" rank="1">
    <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule" flags="required">
      initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
      debug=true
        connectionURL=${ldap.url}
        connectionUsername=cn=mqbroker,ou=Services,ou=system,dc=jbossfuse,dc=com
        connectionPassword=${ldap.password}
        connectionProtocol=
        authentication=simple
        userRoleName=cn
        userBase = ou=User,ou=ActiveMQ,ou=system,dc=jbossfuse,dc=com
        userSearchMatching=(uid={0})
        userSearchSubtree=true
        roleBase = ou=Group,ou=ActiveMQ,ou=system,dc=jbossfuse,dc=com
        roleName=cn
        roleSearchMatching= (member:=uid={1})
        roleSearchSubtree=true
    </jaas:module>
  </jaas:config>

</blueprint>
The ${ldap.password} placeholder is replaced with the decrypted value of the ldap.password property from the etc/ldap.properties properties file.