Password Encryption

As of version 8.2 the Management Console uses certificate based (public-, private-key) encryption when storing passwords. When you import from a previous version password will automatically be re-encrypted using the new certificate based algorithm.

The certificate and the matching private key is stored in a Java keystore, Management Console ships with a keystore that contains a default certificate and private key. Since all customers get the same keystore we recommend that you create your own keystore, otherwise anyone will be able to load your exports and potentially get your passwords.

Create your own keystore

If you have already started the Management Console you will need to upgrade the certificate.

The keystore must be in pkcs12 format, and can be created using the keytool application that comes with the Java SDK (which can be downloaded from Oracle.com, currently available here). The following command creates a new pkcs12 keystore with a certificate that is valid for 365 days.

keytool -genkey -alias mc -keyalg RSA -validity 3650 -keystore mc.p12 -storetype pkcs12

You will be prompted for password, and the information that will be stored in the X.509 private key. The command will create a file mc.p12 (the value from the -keystore argument) in the current directory. -validity 3650 means the certificate will be valid for 10 years.

We don't recommend that you use a certificate issued by a certificate authority (CA) since pkcs12 holds both the private key and the public certificate, and the password to the private key will be written in clear text as part of the application configuration.

To instruct Management Console to use the new certificate, change the Configuration.xml file. The file is located inside the ManagementConsole.war web archive, which must be unpacked, see Deploying into Tomcat for details. Inside Configuration.xml you will find the following entry:


         <bean id="keyStore" class="com.kapowtech.mc.config.KeyStoreConfig" >
               <property name="location" value="/WEB-INF/mc.p12"/>
               <property name="password" value="changeit"/>
               <property name="alias" value="mc"/>
         </bean>

Here you must specify the location, password and alias of the keystore. If you copy the keystore into ManagementConsole.war the location must be relative to the root of the application. If you want to refer to a keystore stored in the file system, the location must start with file://, and must be an absolute reference to the keystore location.

Upgrading the keystore

The first time Management Console starts, it creates a checksum using the private key from the keystore, this allows it to detect when the keystore has been replaced, and verify that passwords can in fact be decrypted with the provided certificate. If you have already started Management Console before installing your own keystore, you have will have to configure Management Console to perform a password conversion.

First copy the current keystore file into a new location, like your users home folder, then modify Configuration.xml to create a password converter with reference to the old keystore, like this:

     <bean id="oldKeyStore" class="com.kapowtech.mc.config.KeyStoreConfig" >
        <property name="location" value="file:///home/roboserver/mc.p12"/>
        <property name="password" value="changeit"/>
        <property name="alias" value="mc"/>
    </bean>

    <bean id="passwordConverter" class="com.kapowtech.scheduler.server.service.PasswordConverter">
        <constructor-arg ref="oldKeyStore"/>
    </bean>

This configures a password converter to use the previous certificate to decrypt any existing passwords and checksum (you will have to provide correct location, alias and password for the old keystore), and use the new private key (as configured above) to re-encrypt passwords and create a new checksum. The conversion will occur the next time the Management Console is started, the conversion occurs while the application is starting and may take some time if there are many schedules. You don't have to remove the oldKeyStore and passwordConverter beans from Configuration.xml, as the password conversion is only triggered when the checksum and keystore is out-of-sync, and after the conversion the checksum will match the new keystore).