Aliased Passwords in AppServer

Author: Kedar.Mhaswade@Sun.Com

Introduction

This document sets the expectations with respect to the capability of aliased passwords used at the client side and server side for Sun Java System Application Server 8.2 onwards. It reflects what’s in the implementation. The server means the Domain Admin Server (DAS) and client means the asadmin command line interface.

This document should eventually be incorporated into the admin guide at http://docs.sun.com.

Details

It all started with a requirement of not storing clear-text passwords on disk for AppServer administrators. As of AppServer 8.2, the passwords are needed at the client location (asadmin) and server location (where the DAS configuration is stored).

Readers should realize that asadmin commands come in two variants: local and remote. The local commands don't need the DAS to be running in order to do administrative tasks, whereas remote commands need an administrative username and password for the DAS.

It does not matter if the DAs is running on the same or different physical machine as that of asadmin. Approximately 95% of asadmin commands are remote, and the rest are local. Remote commands are oblivious to the location of the DAS process and the domain itself that they are operating upon. By comparison, local commands do depend on the location of the domain and must have access to the domain’s configuration for local processing.

The Admin Password and Master Password are the minimum passwords that an administrator needs. The Admin Password is used for every administrative operation on a domain to authenticate a particular user. The Master Password locks (encrypts, indirectly) the SSL keystore of the domain, whose filename is ????????.

Domain startup will fail if the SSL keystore cannot be unlocked (decrypted) in case an invalid Master Password is provided. The administrator must know these two passwords in order to start the domain. The Master Password can be stored on the disc if the --savemasterpassword option is used on create-domain command. It is important to note that --savemasterpassword is used only sparingly and that in the event it is used, the administrator takes the responsibility for securing the file called master-password as described below.

Examples of local commands:

create-domain
start-domain
create-node-agent
start-node-agent

Examples of remote commands:

deploy
create-jdbc-resource
create-instance.

It is important for us to understand the structure and contents of the domain folder that gets created when the administrator issues the command “asadmin create-domain”. Among other things, here is what is created:

domain-configuration-folder
  | ----- config [protected by 0600 on secure platforms |
     | ----- domain.xml  ----- domain-passwords [encrypted with MP of choice]
     | ----- key3.db/cert8.db/cacerts.jks/keystore.jks
     | ----- master-password [encrypted with fixed key, 0600]

Files relevant to this discussion are:

• domain-passwords - This is a “JKS” type store protected with master password. This is where all the passwords can be stored after having encrypted with the master password. Thus, not only that the store is encrypted, but also each password is encrypted. The key is master password. Each entry in this keystore corresponds to the alias for the password, while using the asadmin create-password-alias command.
  
• master-password - This is a “JKS” type store that is encrypted with a fixed key (fixed for all installations, or installation specific?). This file contains at the most one entry. It contains nothing if --savemasterpassword is not used. It contains exactly one entry (that pertaining to master password) if --savemasterpassword is used. This file must be protected by administrators. It is risky to compromise the platform security of this file assuming that anything encrypted is safe. Such encryption with a fixed key (on all appserver domains created anywhere) is not secure, but then it is a feature that lets you start the domains without human intervention and there is a risk associated with it. It is important that administrators realize this and keep this store safe at all times. That includes not copying it over the network, emailing it, etc.

Password Aliasing at the Server Side

The need for this arises for the passwords like database passwords. When a database connection pool is created, the database password needs to be specified as a property. Under normal circumstance, this password is specified as a <property> element with value in clear-text. This means that the password is visible in domain.xml in clear like:

<domain>
  <resources>
    <jdbc-connection-pool ...>
      <property name="user" value="scott"/>
      <property name="password" value="tiger"/>
    </jdbc-connection-pool> 
  </resources>
</domain>

Thus, the password is exposed in the domain.xml in clear. To avoid this (although the file itself is protected by 0600), the following scheme is designed:

domain-passwords contents     domain.xml references
 ___________________________
|alias1->encrypted password1| <property name="password" value="${ALIAS=alias1}"/>
|alias2->encrypted password2| <property name="password" value="${ALIAS=alias2}"/>
|alias3->encrypted password3| <property name="password" value="${ALIAS=alias3}"/>
|...                        |
|___________________________|
 

Thus, the administrator uses the aliases "alias1", "alias2" and "alias3" to refer to the actual passwords that are stored in a safe store that is encrypted with the master password. Note the following in this case:

• The command to do this is asadmin create-password-alias. This command is a Remote Command and needs domain to be running. It creates the aliases for any domain by communicating with a running DAs
• The actual syntax in domain.xml is ${ALIAS=alias-name}
• For an alias-name alias1, the command should be run as:
  asadmin create-password-alias [user/password/host/port] alias1.
  You'll be prompted for the real password. Note that the real password is NEVER stored in clear anywhere.

All the entities in a running server instance will get the real password by doing the unaliasing of the password appropriately. There are internal API's to do this. Thus, it is transparent to the user applications.

Password Aliasing at the Client Side

The asadmin client is also expected to use this feature. The only restriction being asadmin can use it only for the local commands like start-domain and start-node-agent. The use of this feature by asadmin needs to be understood in conjunction with the following existing features:

• The so-called password-file
• The access to a local store like domain-passwords.
• The master password itself.

A Word About Password-file

This feature is the only way to hide passwords from command lines while being able to execute the asadmin commands non-interactively. The idea is you store the passwords in clear in a particular syntax in a file and undertake the security of this file. The asadmin client can read the passwords from there in a defined manner and that way neither do you have to specify the passwords on command lines nor do you get prompted for the same.

Requirement of 6264937 -- Using Aliased Password in Password-file

Since we had all the underpinnings ready, here is what was decided:

• Use the domain-passwords store from domain's configuration to store the actual password encrypted and password-file as a store for the alias only.

Thus, in the case of server, domain.xml contains the alias and domain-passwords contains the real passwords (encrypted, of course) and in case of asadmin, the password-file contains the aliases in the same special syntax and domain-passwords contains the real passwords. Since the domain-passwords store contains the real passwords, both server and client sides must have access to this store. The server will always have this access, but the local commands also need to have access to this store. (This is not implicit, but needs to be an informed decision).

It is important to note that this works for asadmin start-domain and asadmin start-node-agent only:

• The --passwordfile option is a replacement for --password. This means all the commands where --password is/was applicable, --passwordfile is a preferred substitute. Remote commands don't know where domain configuration (and the domain-passwords store) is and hence, they can not make use of the aliasing facility (unlike the server). This facility however will work for unattended boots.

Current State (as of June 1, 2006) of this bug fix:

• Fix integrated into 8.1EE-patch 09 by Sharan.
• Fix integrated into 9.0 by PDE.
• Fix NOT integrated into 8.2EE (will soon happen).

Procedure for Unattended Boots

Domain

This is explained at: http://docs.sun.com/app/docs/doc/819-2641/6n4trr8s5?a=view for App server 8.1 and is correct. Note that here, you can specify the admin password as:

AS_ADMIN_PASSWORD=${ALIAS=admin-password}

and then create an alias admin-password in the domain. What is missing is mentioning that this is limited to the startup of the domain only.

Node Agent

For node-agent to have this working, it is important that the node-agent has synchronized with the Domain once after the aliased are created using asadmin create-alias command. This is because the domain-passwords store described above is available only at the the domain initially, until it gets synchronized at the node-agent location.