JBoss.orgCommunity Documentation

Chapter 13. Masking Passwords in XML Configuration

13.1. Password Masking Overview
13.2. Generate a key store and a masked password
13.3. Encrypt the key store password
13.4. Create password masks
13.5. Replace clear text passwords with their password masks
13.6. Changing the password masking defaults

Follow the instructions in this chapter to increase the security of your JBoss AS Installation by masking passwords that would otherwise be stored on the file system as clear text.

Passwords are secret authentication tokens that are used to limit access to resources to authorised parties only. In order for JBoss services to access password protected resources, the password must be made available to the JBoss service. This can be done by means of command line arguments passed to the JBoss Application Server on start up, however this is not practical in a production environment. In production environments, typically, passwords are made available to JBoss services by their inclusion in configuration files.

All JBoss configuration files should be stored on secure file systems, and should be readable by the JBoss Application Server process owner only. Additionally, you can mask the password in the configuration file for an added level of security. Follow the instructions in this chapter to replace a clear text password in a Microcontainer bean configuration with a password mask. Refer to Chapter 15, Encrypting Data Source Passwords for instructions on encrypting Data Source passwords; to Chapter 16, Encrypting the Keystore Password in a Tomcat Connector for instructions on encrypting the key store password in Tomcat; and to Chapter 17, Using LdapExtLoginModule with JaasSecurityDomain for instructions on encrypting the password for LdapExtLoginModule.

Note

There is no such thing as impenetrable security. All good security measures merely increase the cost involved in unauthorised access of a system. Masking passwords is no exception - it is not impenetrable, but does defeat casual inspection of configuration files, and increases the amount of effort that will be required to extract the password in clear text.

Generate a key store

Password masking uses a public/private key pair to encrypt passwords. You need to generate a key pair for use in password masking. By default JBoss Enterprise Application Platform 5 expects a key pair with the alias jboss in a key store at jboss-as/bin/password/password.keystore. The following procedures follow this default configuration. If you wish to change the key store location or key alias you will need to change the default configuration, and should refer to Section 13.6, “Changing the password masking defaults” for instructions.

For more on key stores and the keytool command, refer to Section 12.1, “SSL Encryption overview”.

With password masking, passwords needed by Jboss services are not stored in clear text in xml configuration files. Instead they are stored in a file that is encrypted using a key pair that you provide.

In order to decrypt this file and access the masked passwords at run time, JBoss Application Server needs to be able to use the key pair you created. You provide the key store password to JBoss Application Server by means of the JBoss Password Tool, password_tool. This tool will encrypt and store your key store password. Your key store password will then be available to the JBoss Password Tool for masking passwords, and to the JBoss Application Server for decrypting them at run time.

Procedure 13.3. Encrypt the key store password

  1. At the command line, change to the jboss-as/bin directory.

  2. Run the password tool, using the command ./password_tool.sh for Unix-based systems, or password_tool.bat for Windows-based systems.

    Result:

    The JBoss Password Tool will start, and will report 'Keystore is null. Please specify keystore below:'.

  3. Select '0: Encrypt Keystore Password' by pressing 0, then Enter.

    Result:

    The password tool responds with 'Enter keystore password'.

  4. Enter the key store password you specified in Generate a key pair and key store for password masking.

    Result:

    The password tool responds with 'Enter Salt (String should be at least 8 characters)'.

  5. Enter a random string of characters to aid with encryption strength.

    Result:

    The password tool responds with 'Enter Iterator Count (integer value)'.

  6. Enter a whole number to aid with encryption strength.

    Result:

    The password tool responds with: 'Keystore Password encrypted into password/jboss_keystore_pass.dat'.

  7. Select '5:Exit' to exit.

    Result:

    The password tool will exit with the message: 'Keystore is null. Cannot store.'. This is normal.

  8. Optional:

    Make the resulting file password/jboss_keystore_pass.dat readable by the JBoss Application Server process owner only.

    On Unix-based systems this is accomplished by using the chown command to change ownership to the JBoss Application Server process owner, and chmod 600 jboss-keystore_pass.dat to make the file readable only by the owner.

    This step is recommended to increase the security of your server. Be aware that if this encrypted key is compromised, the security offered by password masking is significantly reduced. This file should be stored on a secure file system.

    Note: the JBoss Application Server process owner should not have interactive console login access. In this case you will be performing these operations as another user. Creating masked passwords requires read access to the key store, so you may wish to complete configuration of masked passwords before restricting the key store file permissions.

Note:

You should only perform this key store password encryption procedure once. If you make a mistake entering the keystore password, or you change the key store at a later date, you should delete the jboss-keystore_pass.dat file and repeat the procedure. Be aware that if you change the key store any masked passwords that were previously generated will no longer function.

The JBoss Password Tool maintains an encrypted password file jboss-as/bin/password/jboss_password_enc.dat. This file is encrypted using a key pair you provide to the password tool, and it contains the passwords that will be masked in configuration files. Passwords are stored and retrieved from this file by 'domain', an arbitrary unique identifier that you specify to the Password Tool when storing the password, and that you specify as part of the annotation that replaces that clear text password in configuration files. This allows the JBoss Application Server to retrieve the correct password from the file at run time.

Note:

If you previously made the key store and encrypted key store password file readable only by the JBoss Application Server process owner, then you need to perform the following procedure as the JBoss Application Server process owner, or else make the keystore (jboss-as/bin/password/password.keystore) and encrypted key store password file (jboss-as/bin/password/jboss_keystore_pass.dat) readable by your user, and the encrypted passwords file jboss-as/bin/password/jboss_password_enc.dat (if it already exists) read and writeable, while you perform this operation.

Procedure 13.4. Create password masks

  1. At the command line, change to the jboss-as/bin directory.

  2. Run the password tool, using the command ./password_tool.sh for Unix-based systems, or password_tool.bat for Windows-based systems.

    Result:

    The JBoss Password Tool will start, and will report 'Keystore is null. Please specify keystore below:'.

  3. Select '1:Specify KeyStore' by pressing 1 then Enter.

    Result:

    The password tool responds with 'Enter Keystore location including the file name'.

  4. Enter the path to the key store you created in Generate a key pair and key store for password masking. You can specify an absolute path, or the path relative to jboss-as/bin. This should be password/password.keystore, unless you have performed an advanced installation and changed the defaults as per Section 13.6, “Changing the password masking defaults”.

    Result:

    The password tool responds with 'Enter Keystore alias'.

  5. Enter the key alias. This should be jboss, unless you have performed an advanced installation and changed the defaults as per Section 13.6, “Changing the password masking defaults”.

    Result:

    If the key store and key alias are accessible, the password tool will respond with some log4j WARNING messages, then the line 'Loading domains [', followed by any existing password masks, and the main menu.

  6. Select '2:Create Password' by pressing 2, then Enter

    Result:

    The password tool responds with: 'Enter security domain:'.

  7. Enter a name for the password mask. This is an arbitrary unique name that you will use to identify the password mask in configuration files.

    Result:

    The password tool responds with: 'Enter passwd:'.

  8. Enter the password that you wish to mask.

    Result:

    The password tool responds with: 'Password created for domain:mask name'

  9. Repeat the password mask creation process to create masks for all passwords you wish to mask.

  10. Exit the program by choosing '5:Exit'

Clear text passwords in xml configuration files can be replaced with password masks by changing the property assignment for an annotation. Generate password masks for any clear text password that you wish to mask in Microcontainer bean configuration files by following Create password masks. Then replace the configuration occurrence of each clear text password with an annotation referencing its mask.

The general form of the annotation is:


JBoss Enterprise Application Platform 5 ships with server profiles preconfigured for password masking. By default the server profiles are configured to use the keystore jboss-as/bin/password/password.keystore, and the key alias jboss. If you store the key pair used for password masking elsewhere, or under a different alias, you will need to update the server profiles with the new location or key alias.

The password masking key store location and key alias is specified in the file deploy/security/security-jboss-beans.xml under each of the included JBoss Application Server server profiles.