ESnetESnetESnet
» MyESnet
Services

Contact Us

Technical Assistance:

1 800-33-ESnet (Inside the US)
1 800-333-7638 (Inside the US)
1 510-486-7600 (Globally)
1 510-486-7607 (Globally)

Report Network Problems:

trouble@es.net

Provide Web Site Feedback:

info@es.net

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 Apache 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 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 a private key and X509 certificate to sign responses and the X509 certificates of the CAs (Certificate Authority) that issued users certificate in order to authenticate the message signature.

There is an additional complication presented by the interdomain architecture. The OSCARS and OSCARSNotify servers 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.       

The rampart configuration file 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 need to be edited to add the host and server certificates and user keys from your own site.

Configuration Files

  • axis2.xml Used by OSCARS client and services 
Includes rampConfig.xml by absolute pathname (edited for the site by ant setupServer).  This file is found by setting the -Daxis2.xml=<pathname> Java option, or programmatically by a System.setProperty("axis2.xml",<pathname> ). The pathname must be on the classpath. An absolute pathname does not seem to work.
  • oscars-services.xml and notify-services.xml Used by OSCARS and OSCARSNotify services. 
Has the ws-policy describing message security and includes rampConfig.xml by absolute path name (edited for the site by ant setupServer).  Has a list of each of the operations in the service, and what policy applies to them. Copied from conf/axis-tomcat to the oscars.aar and notify.aar files as META_INF/services.xml by the ant oscars-aar and notify-aar targets.
  • rampConfig.xml Used by the OSCARS client and services. Contains rampart specific ws-policy for message security. Contains the user alias, the keystore filename and password. (edited for the site by ant setupServer).

Keystore Files

  • $CATALINA_HOME/shared/classes/repo/OSCARS.jks Used by OSCARS server when signing response messages and when forwarding a request to another domain. Contains a keyEntry for the entity that is signing the message and trustedCertEntries for the entity's CA. Must also have a trustedCertEntry for the CA of the service that is being contacted in order to verify the signature of the response message. File is named in rampConfig.xml. Must be on the classpath. It is copied from conf/axis-tomcat to ${CATALINA_HOME}/shared/classes/repo by the setupServer ant task. The distributed file contains trustedCertEntries for all the currently recognized CAs. The site must add the KeyEntries for the local service.
  • examples/javaClients/repo/OSCARS.jks May be used by api client.
Contains the keyEntry for the client. Contains the trustedCertEtries for any trusted CAs, e.g. any CAs in the chain that signed the users certificate. Must be on the classpath. It is copied from conf/axis-tomcat to examples/javaClients/repo by examples/javaClients/build.xml. File is named in examples/javaClients/repo/rampConfig.xml which may either point to $CATALINA_HOME/shared/classes/repo/OSCARS.jks or to repo/OSCARS.jks. The site must add the KeyEntries for local api users.
  • ssl-keystore.jks- used by the OSCARS client when establishing an ssl connection to a Tomcat server. It needs to contain trustedCertEntries for the server and its issuer chain. e.g. oscars-dev.es.net or oscars.es.net, "ESnet SSL Server Certificates" and "ESnet Root CA 1". Location hard-coded into KeyManagement.java as System.setProperty("javax.net.ssl.trustStore",repo +"/ssl-keystore.jks"); where repo is an input string to setKeyStore(String repo). It is copied from conf/axis-tomcat to $CATALINA_HOME/shared/classes/repo by the setupServer ant task and to examples/javaClient/repo by examples/javaClients/build.xml.
  • /root/.keystore Used by the Tomcat server. 
The keystore used by the Tomcat server when accepting the ssl connection. The name is specified in $CATALINA_HOME/conf/server.xml as the keystoreFile. It must contain a keyEntry for the server with the alias Tomcat e.g. oscars-dev.es.net and trustedCertEntries for the issuers of that certificate. This file is created as part of the process of configuring Tomcat for SSL.

Class Files

  • net/es/oscars/client/security/PWCallback.java Called by org.apache.rampart.handler.WSDoAllSender.processMessage. 
Contains the password for the keys in sec-client.jks. Must be on classpath.
  • net/es/oscars/client/security/KeyManagement.java  setKeyStore called by Client.setup and Forwarder.setup 
Sets the name and the password for the client-side ssl-keystore.jks file.

Keystore Management Tools

  • keytool: available as part of the Java security package
    This is a general purpose keystore management program. use keytool -h for a complete list of functions. It can be used to create a new self-signed keyEntry, or to export a certificate signing request for the new entries certificate to be sent to a CA for signing, and then import the signed certificate back to the keyEntry. It can also import a CA certificate to a trustedCertEntry,  change the keystore password and list the contents of a keystore. 
  • tools/utils commands. These commands are wrappers to keytool that operate on either of ${CATALINA_HOME}/shared/classes/repo/{OSCARS.jks,ssl-keystore}. They take no arguments and prompt for the keystore, the alias you want to see or modify and find the keystore password from the  rampConfig.xml file.
  • idc-addcert: creates a new keyEntry, either with a signed or unsigned certificate, or imports a trusted CA certificate.
  • idc-certdel: deletes a trustedCertEntry or keyEntry from a keystore
  • idc-export: exports a pem format X.509 certificate from either a trustedCertEntry or keyEntry.
  • idc-signreq: exports a certificate signing request for a keyEntry that currently contains a self-signed certificate.
  • idc-certview: views the certificate associated with either a keyEntry or a TrustedCert entry.
  • idc-kspasswd: Changes the OSCARS.jks keystore password.
  • tools/utils/copyKey: Used to copy a keyEntry from one keystore to another. May be useful when upgrading to a new release or when importing a keyEntry from an externally obtained pkcs12 file.

copyKey.sh -a <alias of keyEntry>

[-inpkcs12 <filename of input keyStore>  | -injks <filename of input keyStore> ]

-out <filename of output keystore>

It will prompt for the password of the input keystore, the password of the keyEntry in the input keystore and the password for the output key store. Normally the password of a keyEntry is the same the keystore. If this is the case just reply with a CR. If the -inpkcs12 option is used the entry will be imported from a pkcs12 file. If -injks is used it will be imported from another jks keystore.

Server Side

Services.xml comes from conf/axis-tomcat/oscars-services.xml, notify-services.xml and is installed in the META-INF directory of the respective aar. It inlcudes rampConfig.xml which defines the rampart specific ws-policy including the name of the keystore file, user and password. RampConfig.xml and the keystore file (OSCARS.jks) are installed at ${catalina_home}/shared/classes/repo and are domain specific. The ones for ESnet are checked into https://oscars.es.net/esnet/domain/server. The ant target "setupServer" will copy them from [conf/axis-tomcat|$DOMAIN_HOME/server] into ${catalina_home}/shared/classes/repo. Examples of these files can be found in conf/axis2-tomcat. OSCARS.jks needs trustedCertEntries for all the authorized users' certificate issuers to validate request messages and a keyEntry for the service to sign response messages.

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.

Client Side

Needs axis2.xml, rampConfig.xml and OSCARS.jks files to generate signed messages.

The OSCARS[Notify] wsdl now specifies most of the message security properties. That information is included in the OSCARS[Notify]Stub.java by wsdl2java. rampConfig.xml specifies the Rampart specific message security properties, e.g. the location of the keystore to use, the user alias and password. axis2.xml imports rampConfig.xml

OSCARS.jks has the keyEntry for the user who will be signing messages and the trustedCertEntries for the issuers who signed the client cert and the certs of the OSCARS service that he is contacting. Keytool can be used to create a keyEntry and to enter trustedCertEntries. tools/utils/copyKey.sh can be used to copy a keyEntry from an existing

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 will need to edit rampConfig.xml to chose a a user to sign the message and may want to add additional keyEntries to OSCARS.jks.

See keytool.html for instructions on how to do this.