TDS Tutorial: Basic Tomcat and TDS Security

About server.xml

• XML file (well-formed syntax is important).
• Tomcat's main configuration file.
• Changes to server.xml do not take effect until Tomcat is restarted.
• Where we make changes to enhance TDS security.

Important elements in server.xml

1. Examine the Elements in server.xml.

Move into the Tomcat conf/ directory and examine the server.xml file:

$ cd $TOMCAT_HOME/conf
$ less server.xml

Reference the table below to see how the server.xml elements relate to configuring TDS (mouse-over the element for a description):

Tag Name	Instances	How it relates to the TDS
<Server>Description: The Server element represents the entire Catalina servlet container as a whole. It is the single outermost element in server.xml	1...1	Not modified unless you want to change the port number Tomcat listens for a SHUTDOWN command. (Enabled by default.)
<GlobalNamingResources>Description: The GlobalNamingResources element defines the global Java Naming and Directory Interface (JNDI) resources for the Server.	0...*	Needed to contain the UserDatabase that corresponds to the UserDatabaseRealm used to authenticate users. (Enabled by default.)
<Resource>Description: The Resource element represents a static resource from which classes will be loaded and static files will be served.	0...*	Editable user database (tomcat-users.xml) used by UserDatabaseRealm to authenticate users. (UserDatabaseRealm Resource Enabled by default.)
<Service>Description: The Service element represents the combination of one or more Connector components that share a single Engine component for processing incoming requests. The top Tomcat service is named Catalina (hence the log file name of catalina.out).	1...*	Not modified unless you wish to establish more than one service. (Catalina Service enabled by default.)
<Connector>Description: The Connector element forward requests to the Engine using a specific protocol and returns the results to the requesting client.	1...*	Used to establish HTTP and SSL connections. Also will communicate with an web server for proxying requests. (HTTP connector enabled by default on port 8080.)
<Engine>Description: The Engine element represents the entire request processing machinery associated with a particular Catalina Service.	1...1	Not modified unless you specify a Host other than localhost. (Enabled by default.)
<Realm>Description: The Realm element represents a "database" of usernames, passwords, and roles (groups) assigned to those users.	0...*	The UserDatabaseRealm uses the UserDatabase configured in the global JNDI Resource. (UserDatabaseRealm enabled by default.)
<Valve>Description: The Valve element represents a component that will be inserted into the request processing pipeline for the associated containing element.	0...*	The RemoteAddrValve is used to filter access to the TDS based on IP address. (NOT enabled by default. You will need to add this if you want to use IP Filtering.)
<Host>Description: The Host element represents a virtual host.	1...*	Not modified unless you specify a Host other than localhost. (localhost enabled by default.)
<Realm>Description: The Realm element represents a "database" of usernames, passwords, and roles (groups) assigned to those users.	0...*	We use the MemoryRealm to configuring Tomcat to use digested passwords. (NOT enabled by default. You will need to add this if you want to use digested passwords.)
<Valve>Description: The Valve element represents a component that will be inserted into the request processing pipeline for the associated containing element.	0...*	We modify the AccessLogValve to customize the access logs generated by Tomcat. (NOT enabled by default. You will need to add this if you want to enable access logging.)

About tomcat-users.xml

• XML file (well-formed syntax is important).
• Stores user names, passwords and roles.
• Changes to tomcat-users.xml do not take effect until Tomcat is restarted.
• What the TDS uses for user authentication and access control.

Important elements in tomcat-users.xml

1. Examine the Elements in tomcat-users.xml.

Open the $TOMCAT_HOME/conf/tomcat-users.xml file:

$ less $TOMCAT_HOME/conf/tomcat-users.xml

Reference the table below to see how the tomcat-users.xml elements relate to configuring TDS (mouse-over the element for a description):

Tag Name	Instances	How it relates to the TDS
<tomcat-users>Description: The tomcat-users element represents the single outermost element in tomcat-users.xml	1...1	Not modified. (The only tag you get by default.)
<role>Description: The role element defines one role or group a user can belong to.	1...*	You will have at least two of these: one for the Tomcat manager application and one for the TDS. (You will need to add if you want to enable role-based authentication.)
<user>Description: The user element represents one valid user.	1...*	You will need to create an entry for each user who needs access to the Tomcat manager application and/or the restricted areas of the TDS. (You will need to add if you want to enable user authentication.)

About the manager application

• "Free" web application that comes with Tomcat distribution.
• Lives in the $TOMCAT_HOME/webapps/manager directory.
• Allows Tomcat administrators to deploy, undeploy, or reload web applications such as the TDS without having to shut down and restart Tomcat.
• Provides server status statistics for the JVM and each connector you have configured in server.xml.

Accessing the Tomcat manager application

Attempt to access the Tomcat manager application in your browser: http://localhost:8080/manager/html/. You will be prompted to login via BASIC authentication, which will end in failure since we do not yet have permission to access the manager application:

Granting access to the manager application

1. Modify tomcat-users.xml to add role and user elements.

Using your favorite editor, open $TOMCAT_HOME/conf/tomcat-users.xml:

$ vi tomcat-users.xml

Between the <tomcat-users> tags, add a role element and specify the rolename attribute as manager:

<tomcat-users>
    <role rolename="manager"/>
</tomcat-users>

Now add a new user by adding a user element. Create a username and password for the new user and specify manager as one of the roles (in this example we are creating a user called 'admin' with a corresponding password of 'secret'):

<tomcat-users>
    <role rolename="manager"/>
    <user name="admin" password="secret" roles="manager"/>   
</tomcat-users>

2. Restart Tomcat and log into the manager application.

Keep in mind

Changes to tomcat-users.xml do not take effect until Tomcat is restarted.

Attempt to access the manager application again (http://localhost:8080/manager/html/), this time logging in using the name and password specified in tomcat-users.xml:



Thinking ahead

To gain access to restricted parts of the TDS, you will perform the same steps you used to grant yourself access to the manager application.

Voilà! You should have access to the manager application.

Deploying the TDS using the manager application

1. Use the manager application to undeploy the TDS.

Find the TDS in the list of web application on the Applications page. Stop and then Undeploy the TDS:



List the contents of $TOMCAT_HOME/webapps/ to verify that both thredds.war and the unpacked thredds/ directory have been removed:

$ cd $TOMCAT_HOME/webapps
$ ls -l
total 10284
drwxr-xr-x 11 thredds workshop     4096 2009-05-13 17:15 docs
drwxr-xr-x  5 thredds workshop     4096 2009-05-13 17:15 examples
drwxr-xr-x  5 thredds workshop     4096 2009-05-13 17:15 host-manager
drwxr-xr-x  5 thredds workshop     4096 2009-05-13 17:15 manager
drwxr-xr-x  3 thredds workshop     4096 2009-05-13 17:15 ROOT

2. Deploy the TDS using the manager application.

Upload the TDS WAR file using the Deploy section of the manager application:



Confirm the deployment went as planned by accessing the TDS using your browser: http://localhost:8080/thredds/

Caveat of the manager application

The dreaded java.lang.OutOfMemoryError: PermGen space failure error:

• The issue: The "PermGen" error happens when the JVM runs out of memory in the permanent generation.
• The cause: Objects in the permanent generation are never garbage collected. When redeploying your web application using the Tomcat manager application, your WAR file is unpacked and parts of the class file definition are loaded into PermGen space, like string constants.
• The symptom: The PermGen error will manifest itself in a sluggish Tomcat manager application that never completes a task, and the java.lang.OutOfMemoryError: PermGen space failure error being displayed in $TOMCAT_HOME/logs/catalina.out
• A temporary fix: You can add the -XX:MaxPermSize switch to $JAVA_OPTS to increase the amount of memory allocated for the permanent generation, However this is only postponed the inevitable, as even an increased memory in permanent generation will eventually fill up. When this happens, you will need to stop/start Tomcat at this point. For this reason, you may want to restart Tomcat whenever you redeploy TDS or another webapp.

The problem of passwords in clear text

• Passwords stored in clear text are a vulnerability if the host is compromised.
• Worse yet, these passwords are being sent from the client to the server (Tomcat) in clear text. Anyone eavesdropping on the electronic conversation has easy access to the passwords.
• Better to have the passwords encrypted using a cryptographic hash functions (SHA, MD2, or MD5) and then stored in tomcat-users.xml.
• Tomcat can be configured to support digested passwords (this is not the default setting).
• How it works: When a client makes a request Tomcat will tell the client that a digested password is required. Based on this dialog, the client will automatically digest the password entered by the user.

Configure Tomcat to use digested passwords

1. First we need to enable digest passwords support in Tomcat by modifying server.xml.

Open $TOMCAT_HOME/conf/server.xml with your favorite editor:

$ vi server.xml

Locate the UserDatabaseRealm (right above the Host element) and comment it out:

<!-- This Realm uses the UserDatabase configured in the global JNDI
     resources under the key "UserDatabase".  Any edits
     that are performed against this UserDatabase are immediately
     available for use by the Realm.  -->
<!-- 
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
       resourceName="UserDatabase"/>
-->
<!-- Define the default virtual host
     Note: XML Schema validation will not work with Xerces 2.2.
-->
<Host name="localhost"  appBase="webapps"
      unpackWARs="true" autoDeploy="true"
      xmlValidation="false" xmlNamespaceAware="false">

Now add the flowing MemoryRealm information inside the Host element:

<!-- This Realm uses the UserDatabase configured in the global JNDI
     resources under the key "UserDatabase".  Any edits
     that are performed against this UserDatabase are immediately
     available for use by the Realm.  -->
<!-- 
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
       resourceName="UserDatabase"/>
-->
<!-- Define the default virtual host
     Note: XML Schema validation will not work with Xerces 2.2.
-->
<Host name="localhost"  appBase="webapps"
      unpackWARs="true" autoDeploy="true"
      xmlValidation="false" xmlNamespaceAware="false">

<Realm className="org.apache.catalina.realm.MemoryRealm" 
       digest="SHA" />

2. Create a SHA encrypted version of your password.

Tomcat provides a script ($TOMCAT_HOME/bin/digest.sh) that will encrypt a password string according to the algorithm specified. Use this script as follows with the password you made for yourself previously:

$ /home/thredds/apache-tomcat-6.0.20/bin/digest.sh -a SHA secret
secret:e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4

3. Update tomcat-users.xml.

Replace your clear-text password in tomcat-users.xml with the encrypted version:

<tomcat-users>
    <role rolename="manager"/>
    <user name="admin" password="e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4" roles="manager"/>
</tomcat-users>

4. Verify digest passwords have been successfully enabled in Tomcat.

BASIC authentication

Since we are using BASIC authentication, you will need to clear any authenticated sessions in your browser to test whether digested passwords have been enabled.

Restart Tomcat and verify digest passwords have been successfully enabled by logging into the Tomcat manager application using your password in clear text: http://localhost:8080/manager/html/

Troubleshooting tips

• Check the XML syntax in tomcat-users.xml and server.xml to make sure it is well-formed and without error.
• Did you restart Tomcat after you made your changes to tomcat-users.xml and server.xml ?
• Any errors will be reported in $TOMCAT_HOME/logs/catalina.out.
• You do not need to type the encrypted version of your password into the browser (the browser auto-magically encrypts your password for you before it transmits it to the server).

About Secure Sockets Layer (SSL)

• Secure Sockets Layer (SSL) is a cryptographic protocol that provides security and data integrity for communications over TCP/IP networks.
• SSL allows applications to communicate across a network in a way designed to prevent eavesdropping, tampering, and message forgery.
• SSL uses a cryptographic system that uses two keys to encrypt data: a public key known to everyone and a private or secret key known only to the recipient of the message.
• By convention, URLs that require an SSL connection start with https instead of http.

SSL certificates

• A public key certificate is an electronic document which incorporates a digital signature to bind together a public key with identity information of the certificate user.
• The certificate can be used to verify that a public key belongs to an individual.
• The digital signature can be signed by a Certificate Authority (CA) or the certificate user (a self-signed certificate).
• Unidata recommends the use of a certificate signed by a Certificate Authority (CA).

Accessing the TDS remote management tool

Other than the compelling security reasons, you will want to enable SSL to take advantage of the TDS remote management tool which (out-of-the-box) requires SSL in order to access: http://localhost:8080/thredds/admin/debug

1. Create a self-signed certificate and store it in $TOMCAT_HOME/conf/keystore.

Run the $JAVA_HOME/bin/keytool command:

$ cd /home/thredds/jdk1.6.0_15/bin
$ ./keytool -genkey -alias tomcat -keyalg RSA -keystore /home/thredds/apache-tomcat-6.0.20/conf/keystore

Meaning of the keytool options:

Command	Purpose
$JAVA_HOME/bin/keytool	Java provides a tool, called keytool, that generates a self-signed certificate and puts in a keystore file.
-genkey	The -genkey option specifies that a key pair (private key and public key) needs to be created. This key pair will be enclosed in the self-signed certificate.
-alias tomcat	The -alias tomcat option creates an entry in the keystore file identified by the alias "tomcat" (which Tomcat will use to find your entry).
-keyalg RSA	The -keyalg RSA option specifies the algorithm (in this case is RSA) to be used for the creation the key pair.
-keystore $TOMCAT_HOME/conf/keystore	-keystore $TOMCAT_HOME/conf/keystore is location of where want to put our keystore. Otherwise, the default keystore is $user_home/.keystore.

Create the self-signed certificate identity. While you are filling out the identity fields for your certificate, keep in mind:

• Although it is not obvious, the first and last name, or CN, should be the host name
• The keystore password (the first password you are prompted to enter) is always changeit
• The last password (the key password) and keystore password need to be the same (changeit).

Enter keystore password: changeit
Re-enter new password: changeit
What is your first and last name?
  [Unknown]:  localhost
What is the name of your organizational unit?
  [Unknown]: THREDDS
What is the name of your organization?
  [Unknown]:  Unidata
What is the name of your City or Locality?
  [Unknown]:  Boulder
What is the name of your State or Province?
  [Unknown]:  Colorado
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=localhost, OU=THREDDS, O=Unidata, L=Boulder, ST=Colorado, C=US correct?
  [no]:  y

Enter key password for 
        (RETURN if same as keystore password): 

Verify the new keystore file has been generated in $TOMCAT_HOME/conf:

$ cd /home/thredds/apache-tomcat-6.0.20/conf
thredds@workshop03 conf]$ ls -l
total 100
drwxr-xr-x 3 thredds workshop  4096 2009-08-03 16:08 Catalina
-rw------- 1 thredds workshop  8690 2009-05-13 17:15 catalina.policy
-rw------- 1 thredds workshop  3665 2009-05-13 17:15 catalina.properties
-rw------- 1 thredds workshop  1396 2009-05-13 17:15 context.xml
-rw-r--r-- 1 thredds workshop  1360 2009-08-03 16:42 keystore
-rw------- 1 thredds workshop  3257 2009-05-13 17:15 logging.properties
-rw------- 1 thredds workshop  6576 2009-08-03 16:36 server.xml
-rw------- 1 thredds workshop  1231 2009-08-03 16:37 tomcat-users.xml
-rw------- 1 thredds workshop 50757 2009-05-13 17:15 web.xml

2. Configure Tomcat to enable SSL and use the self-signed certificate.

Based on what we know about Tomcat configuration, which file in $TOMCAT_HOME/conf should we edit to to enable SSL?

Open $TOMCAT_HOME/conf/server.xml with your favorite editor:

$ vi server.xml

Locate the Java HTTP/1.1 Connector listening on port 8080 and verify it is redirecting SSL traffic to port 8443:

<Connector port="8080" protocol="HTTP/1.1"
              connectionTimeout="20000"
              redirectPort="8443" />

Find and uncomment the SSL HTTP/1.1 Connector listening on port 8443 to activate this connector:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
              maxThreads="150" scheme="https" secure="true"
              clientAuth="false" sslProtocol="TLS" />

Add a keystoreFile attribute to the SSL HTTP/1.1 Connector to tell Tomcat where to find the keystore:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
              maxThreads="150" scheme="https" secure="true"
              clientAuth="false" sslProtocol="TLS" keystoreFile="/home/thredds/apache-tomcat-6.0.20/conf/keystore" />

Finally, verify the AprLifecycleListener is uncommented (found near the top of the file):

<!--APR library loader. Documentation at /docs/apr.html -->
<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />

3. Verify SSL has been enabled.

Restart Tomcat:

$ $TOMCAT_HOME/bin/shutdown.sh
$ $TOMCAT_HOME/bin/startup.sh

Verify Tomcat is listening on port 8443 by running the netstat command:

$ netstat -an | grep tcp

man netstat

Run man netstat in your terminal window to learn more about this command.

netstat (short for network statistics) is available on Unix, Unix-like, and Windows NT-based operating systems. It is a command-line tool that displays:

• network connections (both incoming and outgoing)
• routing tables
• and a number of network interface statistics

Look for the following in the output:

tcp        0      0 127.0.0.1:8443               0.0.0.0:*                   LISTEN

Troubleshooting tips

• Check the XML syntax in server.xml to make sure it is well-formed and without error.
• When generating the self-signed certificate, the last password (the key password) and keystore password should be the same (changeit). If they differ, Tomcat cannot open the keystore and you will get this error: java.io.IOException: Cannot recover key.
• Did you restart Tomcat after you made your changes to server.xml?
• Did you specify the full path to the keystore file in server.xml?