OSCARS Message
Security
- OSCARS
Message
Security
-
- Overview
- Configuration Files
- Keystore files
- Class Files
- Keystore Management Tools
- Server side
- Client
side
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 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 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 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/server to the oscars.aar file
in
META-INF/services.xml by the ant aar target. Also
copied from conf/notify-server to the oscars-notify.aar by the ant notifyaar
target.
- 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/examples |
$DOMAIN_HOME]/server/OSCARS.jks to ${CATALINA_HOME}/shared/classes/repo
by the setupServer
ant
task. File is named in
${CATALINA_HOME}/shared/classes/repo/rampConf.xml. The distributed file
contains trustedCertEntries for all the currently recognized CAs. The site must add the KeyEntries for
the local service.
- examples/javaClients/reop/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. Also contains a keyEntry for the server which is used to
sign the response messages. Must
be on the classpath. It is copied from
[conf/examples|$DOMAIN_HOME]/server/ to examples/javaClients.repo
by examples/javaClients/build.xml. File is named in
examples/javaClients/repo/rampConf.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/examples/client/ to
$CATALINA_HOME/shared/classes/repo by the setupServer ant
task and to examples/javaClient/repo by example/javaClient/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. Useful
when upgrading from DCN release 0.3 to 0.4 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/server/services.xml
and is installed in the META-INF directory of the 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. The ant target "setupServer" will
copy
them from [conf/examples/server|$DOMAIN_HOME/conf/server]
into
${catalina_home}/shared/classes/repo.
Examples of
these files can be found in examples/conf/server
. The
server
keystore needs trustedCertEntries
for all the authorized user's certificate issuers to validate request
messages and 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
key store. tool/utils/importKeyEntry.sh can be used to import a
keyEntry from a privateKey file in DER format and a cerificate chain in
DER format.
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.