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.
Configuration Files
- axis2.xml Used by OSCARS client.
Names the security properties file (sec-client.properties); the user
who will sign the message; specifies that outflow messages are to be signed
and time stamped and that inflow messages are to be time stamped. This file is found by
setting the -Daxis2.xml=<pathname> Java option, or programatically by a
System.setProperty("axis2.xml",<pathname> ). The pathname must be on the classpath. An absolute
pathname does not seem to work.
- services.xml Used by OSCARS service.
Names the security.properties file to use on
the server side (sec-server.properties). Specifies that inflow messages are signed
and time stamped and outflow messages are time stamped. Found in the oscars.aar file
in META-INF/services.xml.
- sec-client.properties Used by OSCARS client.
Contains the name and password of the keystore that the client uses when signing a message.
Its name is specified in axis2.xml.
This file must be on the classpath of the client.
- sec-server.properties Used by OSCARS service.
Contains the name and password of the keystore that the server will use to verify signed messages.
Its name is specified in services.xml. This file must be on the services's classpath.
(it is put in the classes file of OSCARS.aar)
- repo/sec-client.properties Used by the OSCARS service when it is acting as
a client when forwarding a request to an adjacent domain.
Contains the name and password of the keystore
used when signing a forwarded message. The messages are signed by the server credential:
oscars-dev.es.net or oscars-test.es.net. The name of this file is specified in
$CATALINA_HOME/shared/classes/repo/axis2.xml). This file must be on the classpath of the server.
It is also used by the scheduler when contacting an adjacent domain to instantiate the routing request.
The ant setupServer task will put it in $CATALINA_HOME/shared/classes/repo.
Keystore files
- sec-client.jks Used by OSCARS client.
Contains a key entry for the client that is signing the message and
trusted cert entries for any trusted CAs, e.g. any CAs in the chain that signed the users
certificate. File is named in sec-client.properties. Must be on the classpath.
- sec-server.jks Used by OSCARS service.
Contains the trusted cert entries for any trusted CAs, e.g. any CAs in the chain that signed the users
certificate. File is named in sec-server.properties. Must be on the classpath.
- ssl-keystore.jks- used by the OSCARS client when establishing an ssl connection to a Tomcat
server.
It needs to contain trustedCert entries 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).
- /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 trustedCert entries for the issuers of that certificate.
Class Files
- net/es/oscars/client/security/PWCallback.javaCalled 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.javasetKeyStore Called by Client.setup and Forwarder.setup
Sets the name and the password for the client-side ssl-keystore.jks file.
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.
For the user this should be a file with just the trustedCertEntries to
which the user adds his key/cert. see exampleClients.html for instructions on
how to do this.
Needs ssl-keystore.jks to hold the trustedCert entries 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.
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. Any edited files should be copied to someplace safe
since the repo directory is purged and recreated each time ant is run.
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 the top level OSCARS.aar and are domain specific. The ones for esnet
are checked into https://oscars.es.net/esnet/domain. The ant target "prepare" will copy them from
$DOMAIN_HOME/server into build/WEB-INF where they will be input to the OSCARS.aar. Examples of these
files can be found in examples/server.
The server keystore only needs trustedCertEntires 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 oscars-dev keystoreFile element of the Connector for port 9090 is /root/.keystore. The keystore
contains a keyEntry for the oscars-dev cert/key with alias tomcat and the trustedcert entries for that key.
Server acting as client, e.g when forwarding request to next Domain
Needs trustedCertEnties and oscars-dev keyEntry, (not distributed outside
of LBL in domain/client/sec-client.jks). The ant task "setupServer" will create a repo directory
with the necessary axis2.xml, sec-client.properties, sec-client.jks
and ssl-keystore.jks in ${catalina.home}/shared/classes/repo
directory.