home > Installing > Message Security

OSCARS Message Security

Overview

The OSCARS Web pages and Web Services are run within a Tomcat container which uses SSL connections to encrypt all messages. The OSCARS Web Service interface is run as an axis2 service within the Tomcat container that has message signing implemented by the Rampart software. The SSL connection assures the user that he is connecting to a legitimate OSCARS server, and encrypts all data that passes between the client and the server. The message signing assures the OSCARS service that the request came from an authenticated user that can be matched against its list of authorized users. Signed messages are required rather than SSL client authentication, because there may be more than one host machine between the client and the OSCARS service. Signed messages assure end-to-end authentication, where SSL does only point-to-point authentication.

The client needs to have access to a private key and its matching X509 certificate for message signing, and the the X509 certificate chain of the server that it is contacting. The Tomcat server needs access to a private key and X509 certificate to identify itself to the client and to encrypt the SSL connection. The OSCARS service needs the X509 certificate of the CA (Certificate Authority) that issued the user certificate in order to authenticate the message signature.

There is an additional complication presented by the interdomain architecture. The OSCARS server and OSCARS scheduler in each domain will also act as a client when information about a reservation needs to be forwarded to an adjacent domain. Thus on an OSCARS server host there will be both server and client configurations.

Since all of the code is in Java, the private keys and certificates are kept in Java keystore files, and the configuration information is kept in properties files.

Most of the configuration and keystore files contain information that is private to a domain or user. The source code available from our code repository includes samples of these files in the conf/examples directory. They will allow the user alice with a certificate from the OASIS Interop Test CA to contact the server.You will need to edit these files to add the host and server certificates and user keys from your own site.

Configuration Files

Keystore files

Class Files

Client side

Needs an axis2.xml file to generate signed messages.

Needs sec-client.properties to define the keystore file and password.

Needs sec-client.jks with the keyEntry for the user who will be signing messages and the trustedCertEntries for this issuers who signed his cert and signed the certs of the OSCARS service that he is contacting. Keytool can be used to create or enter a keyEntry and to enter trustedCertEntries.

Needs ssl-keystore.jks to hold the trustedCertEntries for the ssl connection to the Tomcat server. The name and the password for this file are hard-coded into net.es.oscars.client.security.KeyManagement. Use keytool to add a trustedCertEntry for this certificate.

The default ant task in examples/javaClients/build.xml will create and populate a repo directory with all these pieces. The user may want to edit the axis2.xml to chose a different user to sign the message and may want to add additional keyEntries to sec-client.jks.
See keytool.html for instructions on how to do this.

Server side

OSCARS needs the properties and keystore referenced in OSCARS.aar:META-INF/services.xml.
Services.xml comes from conf/server/services.xml. The properties and keystore files are installed at ${catalina_home}/shared/classes/server and are domain specific. The ones for ESnet are checked into https://oscars.es.net/esnet/domain. The ant target "setupServer" will copy them from examples|$DOMAIN_HOME/conf/server into ${catalina_home}/shared/classes/server. Examples of these files can be found in examples/conf/server. The server keystore only needs trustedCertEntries for all the authorized user's certificate issuers since response messages are not signed.

Tomcat needs the keystore referenced in ${catalina.home}/conf/server.xml to do server-side ssl.
If no keystoreFile entry is specified in the https connector element of server.xml, the file ~/.keystore is used. If no keystorePass entry is specified the password is "changeit".
On the oscars servers the keystoreFile element is specified as /root/.keystore. The keystore contains a keyEntry for the oscars/oscars.es.net cert/key with alias tomcat and the trustedCertEntries for the CAs in its certificate chain.

Server acting as client, e.g when forwarding request to next Domain

Needs a client keystore with trustedCertEnties and service keyEntry. The ant task "setupServer" will create the ${catalina.home}/shared/classes/repo directory. The files  axis2.xml, sec-client.properties, sec-client.jks and ssl-keystore.jks will  be either copied from examples/conf/client or $DOMAIN_HOME/conf/client by the setupServer ant task.