From DOC

Contents 1 Overview 1.1 Default Passwords And Credentials 1.2 Changing Passwords And Credentials 1.2.1 Backup plugins.xml File And Credentials Directory 1.2.1.1 Remove Credentials From <config-dir>/credentials 1.2.2 Edit plugins.xml File 1.2.3 Admin Password And KeyStore 1.2.4 JBoss Password And KeyStore 1.2.4.1 Externally Administered Database And LDAP 1.2.5 Tolven Password And KeyStore 1.2.6 mdbuser Password And KeyStore 1.2.7 LDAP Password And Key 1.2.7.1 Self-Administered LDAP 1.2.7.2 Externally Administered LDAP 1.2.7.3 LDAP Manager Password 1.2.8 Postgresql Password And Key 1.2.8.1 Self-Administered Database 1.2.8.2 Externally Administered Database 1.2.8.3 Database Manager Password 1.2.9 pgAdmin Key 1.2.10 WebServer KeyStore 1.2.11 TrustStores 1.2.12 Copying Credentials To Final Destination

Overview

The Tolven credentials fall into two main categories:

1. Something you know e.g. a password etc
2. Something you have e.g. private/public keys, keystores etc

By default, Tolven comes with a number of passwords and credentials to ease configuration for initial set up and development. It is recommended to change them. This article will cover what the credentials are, and how to change the passwords that protect them and their resources.

Note well, that if encryption keys have already been used to encrypt data, then you should back them up, since the data will be irretrievably lost without them. Another point to note is to ensure that when generating credentials that you choose suitable expiration dates.

Default Passwords And Credentials

The passwords are located in <config-dir>/credentials/admin-password.cfg. Each password is associated with a password Id. The password Ids can be seen by executing:

tpf -plugin org.tolven.assembler.admin -displayPasswordIds

A typical output for the default passwords Ids is something like:

Password Ids:

admin   required=true:stored=true:comment=ADMIN
jboss   required=true:stored=true:comment=APPSERVER_SSL
ldap    required=true:stored=true:comment=LDAP_SSL
ldap.root       required=true:stored=true:comment=LDAP_MANAGER
ldapClient      required=true:stored=true:comment=LDAPCLIENT_SSL
mdbuser required=true:stored=true:comment=MDBUSER
pgadmin required=true:stored=true:comment=DBCLIENT_SSL
postgresql      required=false:stored=true:comment=DB_SSL
postgresql.root required=true:stored=true:comment=DB_MANAGER
tolven  required=true:stored=true:comment=TOLVEN

The default passwords are:

Id	Default	Usage
admin	sysadmin	Executing TPF commands and authenticating against LDAP when accessing the application server
jboss	tolven	Protects <config-dir>/credentials/jboss/tolvendev-jboss.jks and <config-dir>/credentials/jboss/tolvendev-jboss-cacerts.jks, which are used for application server SSL
ldap	tolven	Protects <config-dir>/credentials/ldap/tolvendev-ldap-cert.key used by LDAP for SSL
ldap.root	secret	The password used by the application server to register and authenticate Tolven users in LDAP
ldapClient	tolven	Protects <config-dir>/credentials/ldapclient/tolvendev-ldapclient-key.pem, used by LDAP clients
mdbuser	tolven	Protects <config-dir>/credentials/mdbuser/tolvendev-mdbuser.p12, which is used by the application server to protect queued JMS messages
pgadmin	tolven	Protects <config-dir>/credentials/pgadmin/postgresql.key, used by postgresql clients (e.g. pgadmin)
postgresql	tolven	Protects <config-dir>/credentials/postgresql/server.key, used by PostgreSQL for SSL
postgresql.root	postgresql	The password used by the application server to access the database
tolven	tolven	Protects <config-dir>/credentials/tolven/tolvendev-tolven.jks, which itself protects <config-dir>/credentials/tolven passwordStore.properties, where the latter is a subset of passwords distributed to and used by the application server

Changing Passwords And Credentials

For a fresh installation, one can follow the steps below to change all of the passwords and their associated credentials, since none have been used or propagated. In the Configuration Guide, repositoryInit would have been executed in order to download the various plugins, but configPhase1 has not yet been executed.

If configPhase1 has already been executed, then both an admin-password.cfg and admin-encryptedSecretKey would have been generated, and these are only usable with the tolvendev-admin.jks which originally generated them. So, if during this process, you create a new tolvendev-admin.jks, you need to remove both admin-password.cfg and admin-encryptedSecretKey so that new ones will be generated. And at that point, you will need to add all of the password Ids back to your password store, as described below.

All credentials should be backed up regardless including the default ones that come with the installation. Passwords which have propagated to the database server or LDAP server need to be changed as described by their documentation. The Tolven password store is simply a store of password Ids and their corresponding values, and changing a password there does not change the password of the actual underlying key, keystore etc or the server value. Changes to passwords for keys, keystores, truststores etc need to be done using utilities like Keytool in the Java JDK or referring to openssl documentation for formats like PEM. When the physical credential password is changed, then the password store value should be updated to match. At that point, it will be necessary to execute configPhase1 again, and also ensure that credentials are copied to the various servers as need be.

Backup plugins.xml File And Credentials Directory

Backup the <config-dir>/plugins.xml file and the <config-dir>/credentials directory.

Remove Credentials From <config-dir>/credentials

Only credentials files are located in the subdirectories of <config-dir>/credentials. Since they've been backed up in the first step above, you can now remove all of the ones you wish to change, but you can leave the empty directories, although they will be recreated again if the configuration is the same. For this article, we will assume that all of the credentials are removed.

Edit plugins.xml File

Default credentials are used during configuration, when relative paths are found for the following entries in the <config-dir>/plugins.xml file. During configPhase1, the files are copied from various plugins to a destination in the credentials directory, provided no file currently exists at that location.

When you new credentials of your own, you must change the following properties in your plugins.xml to be absolute paths, otherwise the default credentials found in the plugins will be used. You only need to place the credentials mentioned in this article at these locations, because the others will be created automatically, when required.

You can also change the filenames to whatever you wish, and for this article we will assume that none of the files initially exist, exist the admin keystore. Also note that the subdirectory of each credential matches what is called the groupId in the plugins.xml. The groupId is used as the password Id, so that the passwords are recognizable when displayed from the password store.

<property name="admin.keyStoreFile" value="c:/tolven-config/credentials/admin/tolvendev-admin.jks" />
<property name="admin.trustStoreFile" value="c:/tolven-config/credentials/admin/tolvendev-admin-cacerts.jks" />

<property name="ldapSSL.keyFile" value="c:/tolven-config/credentials/ldap/tolvendev-ldap-key.pem" />
<property name="ldapSSL.certFile" value="c:/tolven-config/credentials/ldap/tolvendev-ldap-cert.pem" />
<property name="ldapSSL.trustStoreFile" value="c:/tolven-config/credentials/ldap/tolvendev-ldap-cacerts.pem" />

<property name="databaseSSL.keyFile" value="c:/tolven-config/credentials/postgresql/server.key" />
<property name="databaseSSL.certFile" value="c:/tolven-config/credentials/postgresql/server.crt" />

<property name="databaseClientSSL.keyFile" value="c:/tolven-config/credentials/pgadmin/postgresql.key" />
<property name="databaseClientSSL.certFile" value="c:/tolven-config/credentials/pgadmin/postgresql.crt" />

<property name="appserverSSL.keyStoreFile" value="c:/tolven-config/credentials/jboss/tolvendev-jboss.jks" />
<property name="appserverSSL.trustStoreFile" value="c:/tolven-config/credentials/jboss/tolvendev-jboss-cacerts.jks" />

<property name="appserverPasswordStore.keyStoreFile" value="c:/tolven-config/credentials/tolven/tolvendev-tolven.jks" />

<property name="mdbuser.keyFile" value="c:/tolven-config/credentials/mdbuser/tolvendev-mdbuser-key.pem" />
<property name="mdbuser.certFile" value="c:/tolven-config/credentials/mdbuser/tolvendev-mdbuser-cert.pem" />
<property name="mdbuser.keyStoreFile" value="c:/tolven-config/credentials/mdbuser/tolvendev-mdbuser.p12" />

<property name="https.keystoreFile" value="c:/tolven-config/credentials/webserver/tolvendev-webserver.p12" />

The following files must be used with the admin.keyStoreFile which generated them, as described later in this article.

<property name="admin.passwordStoreFile" value="c:/tolven-config/credentials/admin/admin-password.cfg" />
<property name="admin.secretKeyFile" value="c:/tolven-config/credentials/admin/admin-encryptedSecretKey" />

As a safety precaution, the existing secret key and password store files, will not be written unless the following values are set to true:

<property name="admin.secretKey.create" value="true" />
<property name="admin.passwordStore.create" value="true" />

Admin Password And KeyStore

1. Use Sun's Keytool to create a self-signed JKS tolvendev-admin.jks file, with your chosen password, and place it at the desired location e.g. c:/tolven-config/credentials/admin/tolvendev-admin.jks.
2. If you wish to use the password environment variable in <install-dir>/bin/tpfenv, then set the following entry with the new password:

set TOLVEN_PASSWORD=newsysadmin

Then execute the tpfenv command in the <install-dir>/bin for the environment variable to be set in the command window. If you already have an entry for admin LDAP, then you will need to change that before you execute configPhase3 later. Execute the following command, which will display the password Ids, and create new admin-password.cfg and admin-encryptedSecretKey files:

tpf -plugin org.tolven.assembler.admin -displayPasswordIds

At this point, only the admin password will be stored in the password store, and the admin keystore now exists.

JBoss Password And KeyStore

1. Use Sun's Keytool to create a self-signed JKS tolvendev-jboss.jks file, with your chosen password, and place it at the desired location e.g. c:/tolven-config/credentials/admin/tolvendev-jboss.jks.
2. Add the JBoss password to the admin password store by executing the following command, where you will be prompted for the new jboss password.

tpf -plugin org.tolven.assembler.admin -addPassword jboss

Externally Administered Database And LDAP

It may be necessary to provide the administrators of the database and LDAP, which intend to trust JBoss, with the JBoss public certificate. For LANs within the same company, a self-signed JBoss certificate may be enough, but it might in some circumstances be necessary to use commercial certificates. Export the JBoss certificate from JBoss and send it to the external administrators in the format they request.

Tolven Password And KeyStore

1. Use Sun's Keytool to create a self-signed JKS tolvendev-tolven.jks file, with your chosen password, and place it at the desired location e.g. c:/tolven-config/credentials/tolven/tolvendev-tolven.jks.
2. Add the Tolven password to the admin password store by executing the following command, where you will be prompted for the new tolven password.

tpf -plugin org.tolven.assembler.admin -addPassword tolven

mdbuser Password And KeyStore

If you already have an mdbuser in LDAP, and have existing accounts in the database, then you need to continue using that associated keystore. You can change the password of the keystore as described by Sun's keytool documentation, and you can use the -changePassword command of org.tolven.assembler.admin to change the password in the admin password store.

1. To generate a new mdbuser keystore, there are two options:
   1. Use openssl to create a self-signed PEM key/certificate pair tolvendev-mdbuser-key.pem and tolvendev-mdbuser-cert.pem, with your chosen password, and place them in c:/tolven-config/credentials/mdbuser. During configPhase1, these will be used to create a tolvendev-mdbuser.p12 in the same directory automatically
   2. Or use openssl to create a self-signed PKCS12 tolvendev-mdbuser.p12 file, with your chosen password, and place it at the desired location e.g. c:/tolven-config/credentials/mdbuser/tolvendev-mdbuser.p12
2. Add the mdbuser password to the admin password store by executing the following command, where you will be prompted for the new mdbuser password.

tpf -plugin org.tolven.assembler.admin -addPassword mdbuser

LDAP Password And Key

There are two LDAP passwords: One for the LDAP manager used to manage registered Tolven users, and one for the LDAP SSL keystore. In addition, LDAP may be administered by a different administration.

Self-Administered LDAP

1. Use openssl to create a self-signed PEM key/certificate pair tolvendev-ldap-key.pem and tolvendev-ldap-cert.pem, with your chosen password, and place them in the OpenLDAP server directory. The ldap password Id is for SSL key, and you'll need it in order to start the LDAP server.

tpf -plugin org.tolven.assembler.admin -addPassword ldap

1. In general it is advisable to protect SSL keys with a password. But in some cases, you may need to have a bare key with no password on the filesystem, protected only by OS security. If that be the case, then you can remove protection from the key directly or ensure the following property is set to false, when you first generate the key.

<property name="ldapSSL.passwordProtected" value="false"/>

Externally Administered LDAP

1. Request a public key certificate from the LDAP admin, rename it to tolvendev-ldap-cert.pem and place it in c:/tolven-config/credentials/ldap. In this case, you will never be given a private key, and thus do not need a password.
2. In this case you will need to have the following property in your <config-dir>/plugins.xml set to false, since there is no key to protect. Thus the ldap password Id will not be required in the password store.

<property name="ldapSSL.passwordProtected" value="false"/>

LDAP Manager Password

Whether self or externally administered, the ldap.root password Id is for the LDAP manager, and needs to be requested from the LDAP administrator.

tpf -plugin org.tolven.assembler.admin -addPassword ldap.root

Postgresql Password And Key

There are two database passwords: One for the DB manager and one for the DB SSL keystore. In addition, the database may be administered by a different administration.

Self-Administered Database

1. Use openssl to create a self-signed PEM key/certificate pair server.key and server.crt, with your chosen password, and place them in the Postgresql's data directory. The postgresql password Id is for SSL key, and you'll need it in order to start the database server.

tpf -plugin org.tolven.assembler.admin -addPassword postgresql

An extra point to note: At the time of writing, PostgreSQL requires there to be no password on the SSL server.key, which must therefore be protected by OS security. You will see a passworedProtected property in the <config-dir>/plugins.xml directory which reflects this.

1. In general it is advisable to protect SSL keys with a password. But in some cases, you may need to have a bare key with no password on the filesystem, protected only by OS security. If that be the case, then you can remove protection from the key directly or ensure the following property is set to false, when you first generate the key.

<property name="databaseSSL.passwordProtected" value="false"/>

Externally Administered Database

1. Request a public key certificate from the database admin, rename it to server.crt and place it in c:/tolven-config/credentials/postgresql. In this case, you will never be given a private key, and thus do not need a password.
2. In this case you will need to have the following property in your <config-dir>/plugins.xml set to false, since there is no key to protect. Thus the database password Id will not be required in the password store.

<property name="databaseSSL.passwordProtected" value="false"/>

Database Manager Password

Whether self or externally administered, the postgresql.root password Id is for the database manager, and needs to be requested from the database administrator.

tpf -plugin org.tolven.assembler.admin -addPassword postgresql.root

pgAdmin Key

1. Use openssl to create a self-signed PEM key/certificate pair postgresql.key and postgresql.crt, with no password and place them in c:/tolven-config/credentials/pgadmin. pgAdminIII GUI hangs if the password is present. There is therefore no need to add any password to the admin password store.

WebServer KeyStore

1. Use openssl to create a self-signed PKCS12 tolvendev-webserver.p12 file, with your chosen password, and place it at the desired location e.g. c:/tolven-config/credentials/webserver/tolvendev-webserver.p12

The password for this keystore is not currently used in the admin keystore, primarily because the tomcat server.xml requires the password in plain text anyway. So, at this time the password is placed in the plugins.xml and used from there:

<property name="https.keystorePass" value="tolven" />

In a future version, the password may be added anyway with its group Id webserver.

TrustStores

At this point, all the keys and keystores are created and in place, and the only remaining step is for t hem to be added to the various TrustStores. This is automatically done during configPhase1, when all of the certificates and keys are located in the <config-dir>/credentials directory as described above.

For the case where LDAP and the database are managed by an external administrator, the truststores are still generated locally, but obviously the external administrators will already have their own truststores. They may require you to supply the JBoss public certificate (self-signed or signed by a CA) in order for their servers to trust JBoss.

Copying Credentials To Final Destination

Credentials need to be copied to their final destinations as described in the Credentials Configuration section of the Configuration Guide.