Trustmanager authentication and certificate handling library

Description

TrustManager is an implementation of the java TrustManager interface with implementation of cert path checking, grid namespace restrictions and dynamic loading of CA certs, credentials, CRLs and namespace restrictions. Also provided is integration into tomcat, axis and axis2. There are many utility classes and methods for certificate and proxy creation and handling in trustmanager. It can be used both in the server side for the server ssl handler and on the client side for the opening of ssl connections.

Restructuring

In version 3.0.3 the tomcat integration classes were moved from trustmanager to trustmanager-tomcat. Thus the trustmanager becomes the main library that has most of the code and functionality. The trustmanager-tomcat has the classes needed to integrate the trustmanager to tomcat. Also in the trustmanager 3.0.3 version the axis related code was moved to trustmanager-axis component. This way the basic code resides in trustmanager, tomcat integration in trustmanager-tomcat and axis integration code in trustmanager-axis. There is also the trustmanager-test that has a test servlet and web application, which are used also for trustmanger certification. There is trustmanager-axis2 component that has classes to integrate trustmanager with axis2. Trustmanager-test-certs is a component that has test certificate generation scripts, that are used for example to test and certify trustmanager.

Supported platforms

The Trustmanager (at version 3.1.3) is supported on Scientific Linux 5 and 6. Packages are available also on Debian and code works, but installation system isn't available at the moment. Trustmanager can be used with Tomcat with the trustmanager-tomcat plugin, with Axis (e.g. 1.4) with trustmanager-axis plugin and with axis2 with trustmanager-axis2 plugin. Trustmanager has also been used with Jetty (See Argus for example).

Manual usage with Tomcat

This is just for testing purposes, in real systems the Trustmanager is configured using yaim, espacially the yaim-core method configure-secure-tomcat.

First of all make sure you have the host credentials! (hostcert.pem and hostkey.pem in /etc/grid-security). Also make sure you have all the necessary CA certificates, CRLs and possibly namespace definitions in /etc/grid-security/certificates.

Get and install tomcat. Get and install the trustmanager and trustmanager-tomcat rpms from one emi repository, these depend on bouncycastle and log4j, so you need them too.

Run:

export CATALINA_HOME=<path to tomcat home directory>

Edit the /var/lib/glite-security-trustmanager/config.properties and run:

/opt/glite/etc/glite-security-trustmanager/configure.sh

And if everything is ok, run:

Service tomcat5 start

To check that the tomcat starts up nicely you can check the logs:

less /opt/glite/externals/tomcat-5.0.28/logs/catalina.out

less /opt/glite/externals/tomcat-5.0.28/logs/glite-security-trustmanager.log

If the installation was successful the trustmanager log should be an empty file, but it should exist.

Client Integration

In the program

The axis web service integration:

On the service you'll need to include bcprov, log4j, (axis,) security.trustmanager and security.util-java jars to your webapp and call org.glite.security.util.axis.InitSecurityContext.init() in your code to set up the org.glite.security.SecurityContext. After that you can use the org.glite.security.SecurityInfoContainer to get a class that implements SecurityInfo interface and there you can find the cert chain and user DN. the security.util-java rpm contains javadocs for the securitycontext/info stuff.

On the startup

You'll have to add the BoncyCastle (bcprov), log4j, trustmanger and util-java jars to the classpath.

After that you will have to set socket factory the Axis uses to create sockets by command line option -Daxis.socketSecureFactory=org.glite.security.trustmanager.axis.AXISSocketFactory

You also have to set up the credentials with the following options: either using user proxy: -DgridProxyFile=/tmp/x509up_u500

or user's real credentials: -DsslCertFile=/the/path/to/usercert.pem -DsslKey=/the/path/to/userkey.pem -DsslKeyPasswd=password

These are the minimum settings.

Useful is also the setting: -DtrustStoreDir=/etc/grid-security/certificates

Which defines where to get the trustanchors, their crls and namespace definitions.

Notes

Important setting is the crlUpdateInterval. It defines the interval at which the CRL files are polled for changes. Setting it to 0 will prevent the updater thread being started. It is important on clients that use several user credentials for connecting to services to prevent the crl updater from being started as it will lead to memory leaks and unnecessary threads being run. On the client side there is relly no need to start the updater thread.

Note on intervals: format: n {s,m,h,d} where n is number and (s=seconds, m=minutes, h=hours, d=days). Only first letter is considered, so for clarity's sake full word is recommended. (for example "2 hours")

Properties

This is the list of configuration variables the trustmanager takes during the ssl context creation. They can be given through properties when generating the contextwrapper, in the thread local properties or through system properties (thus also through the -D switch during the java command execution).

trustStoreDir

- the directory containing all the CA certificates, CRLs and namespace definitions.If neither this sslCAStore nor sslCAFiles are defined, /etc/grid-security/certificates is assumed as the value for this variable. The directory contains the CA files named as the hex of 4 least significant bytes of the MD5 hash of the CA subject name in binary ASN1 format and the suffix of a number e.g. 1dab23fe.1. The CRLs have the same filename except the suffix is prepended by a 'r' e.g. 1dab23fe.r1 corresponds to the previous CA. The namespace files are named with the same filename but with a suffix .namespace or .signin_policy depending on whether the namespace is defined using International Grid Trust Federation format in the first case or using globus format in the latter case. The IGTF format is used if both are present.

sslCertFile

- the file containing the local certificate.

sslKey

- The file containing the local private key.

sslKeyPasswd

- The password to access the private key if it is encrypted.

gridProxyFile

- Defines the file that contains the gridproxy to use for authentication. Also used for kerberos credentials where the user cert and key are in the same file in pem format.

credentialsUpdateInterval

- The time interval used to reload the local credentials from filesystem into memory. (default 0 (=never))

sslCertStore

- The keystore that holds the local credentials.

sslCertStoreType

- The keystore type "JKS" and "PKCS12" are supported (default "JKS")

sslCertStorePasswd

- The password to use when accessing the keystore

sslCAFiles (deprecated)

- The files containing the CA certificates

sslCAStore

- The keystore that holds the CA certificates

sslCAStoreType

- The keystore type of the CA keystore "JKS" and "PKCS12" are supported (default "JKS")

sslCAStorePasswd

- The password to use to access the CA keystore

crlFiles (deprecated)

- the CRL files to use (default /etc/grid-security/certificates/*.r0)

crlEnabled (deprecated, assumed true)

- defines whether the system tries to use CRLs (default true)

crlRequired

- defines what happens when CRL is not fournd for a CA (default true) - if true, all certificates from a CA that doesn't have a valid CRL are rejected - if false, all certificates from a CA that doesn't have a valid CRL are accepted

crlUpdateInterval

- the interval to poll updated of the CRL, CA or namespace files from the filesystem and reaload them into the memory cache in case of changes. If the interval is set to 0 the update thread is not started. (default "0 hours")

log4jConfFile

- The file to use to configure the log4j logging facility.

logFile

- The file to log to. To be used instead log4jConfFile if defaults are fine, but log file needs to be configured.

sslProtocol

- The ssl protocol to use (default "TLSv1") (SSLv3, SSLv2, SSLv2HELLO also supported)

sslConfigFile

- Given just this option, the actual configuration options are read from this file.

sslTimeout

- defines the read timeout in milliseconds

sslConnectTimeout

- defines the connect timeout in milliseconds

internalOverrideExpirationCheck

- only for testing, overrides the expiration check when loading credentials.

Changes

see TrustManagerChanges

Testing

CA testing

• put empty CA file (any . number file, eg. 9182374918.0) /etc/grid-security/certificates. Tomcat should start, and java clients work, warning in log file.
• renamve one crl file into CA .number file in /etc/grid-security/certificates. Tomcat should start, and java clients work, warning in log file.
• put expired CA file into /etc/grid-security/certificates. Tomcat should start, and java clients work, warning in log file.

CRL testing

• CA without CRL. The certs from the CA are rejected.
• CA with expired CRL. The certs from the CA are rejected.
• CA with invalid CRL. The certs from the CA are rejected.
• CA without CRL at the start of tomcat. After adding a valid CRL and waiting the update period (default 2h), the certs from the CA start to work.
• CA with expired CRL at the start of tomcat. After adding a valid CRL and waiting the update period (default 2h), the certs from the CA start to work.
• CA with invalid CRL at the start of tomcat. After adding a valid CRL and waiting the update period (default 2h), the certs from the CA start to work.
• CA with valid CRL. the certs from the CA are accepted.

Certificate testing

• v1 x509 certs are accepted.
• v3 x509 certs are accepted.
• not yet valid certificate is rejected.
• expired certificate is rejected.

Namespace testing

• CA with only .namespaces file. Certs following the namespace are accepted, certs outside the namespace are rejected.
• CA with only .signing_policy file. Certs following the policy are accepted, certs outside the policy are rejected.
• CA with both .namespaces and .signing_policy files. Certs following the namespace are accepted, certs outside the namespace are rejected, .signing_policy file ahs no effect.
• CA without .namespaces and .signing_policy file. All valid certificates irrespective of the DN are accepted.

Proxy testing

• Valid legacy proxies are accepted.
• Valid draft proxies are accepted.
• Valid rfc proxies are accepted.
• Valid proxies of depth of 15 are accepted.
• Proxy with invalid DN (not starting with the DN of the issuer and adding a CN component) are rejected.
• Proxy with invalid signature (for example signed by a private key of unrelated cert) are rejected.
• Proxy with invalid DN/singature in the middle of the chain is rejected.
• not yet valid proxy is rejected.
• expired proxy is rejected.

Log file testing

• Not yet valid certificate error message is correct.
• Expired certificate error message is correct.
• Error messages from all the above rejected certificates are correct.
• Timestamps are correct.
• Every valid cert produces a line in the logs with DN of the user.

see TrustmanagerTestplan. see TrustManagerTestReports. see tests in cvs.

Tomcat classloader change

see EGEETomcatTrustmanager.

Funding acknowledgement

Trustmanager has been developed with funding from Helsinki Institute of Physics and the following EU Projects:

• European Data Grid (EDG): initial development
• Enabling Grids in EuropE I, II and III (EGEE): further development and support
• European Middleware Initiative (EMI): Support and porting