WebService Security A guide to set up highly secured client-server communications using WS-Security extensions to the SOAP protocol Jam Hamidi Senior Technical Analyst BCcampus, Victoria, British Columbia, Canada jhamidi@bccampus.ca Thursday, March 21, 2013 Abstract This documents describes the process of setting up a secure WebService communication channel using OASIS WS- Security extensions to the SOAP protocol. Detailed configuration examples and code snippets are provided in the JAVA programming environment for Apache tomcat servers. About this document This document is not intended as an introduction to the WebService architecture or even the WS- Security architecture of the WebService protocols, but rather as a practical solution to the configuration and deployment of a service, of the type provided by the BCcampus Connector System. However the concepts and examples should be applicable to any WebService application that requires a high level of security. If you re only interested in the example configurations, skip to section III. I. INTRODUCTION The BCcampus Connector system provides secure and reliable data exchange between British Columbia s postsecondary institutions enterprise systems to each other as well as to BCcampus. The information exchanged includes personal student as well as financial data, so it is paramount that the communications be carried out in a highly secure manner, in particular with respect to a man in the middle attack, whereby an attacker intercepts messages and then resubmits them, substituting his own data for the requested one. It is easy to see why this protection is needed in cases where student transcripts are exchanged. PLNet, the Provincial Learning Network, BCNET (Shared IT Services for Higher Education in British Columbia) both offer a reliable, robust and safe network infrastructure for BCcampus services, but even so, they also connect thousands of users on a daily basis and it is next to impossible to monitor all of their access points for security attacks. Fortunately the OASIS group provides an infrastructure for secure point-to-point WebService access in a (more or less) public network if you adhere to their Security specifications. These are the same specifications implemented by banks, governments and organizations throughout the world. The heart of the WebService WS-Security is the use of public/private key cryptography. In this model, a user has a pair of public and private keys. These are generated using a large prime number generator. The keys are related mathematically, but cannot be derived from each other. The user uses his private key to encrypt data, and at the other end the receiver can use the public key to decrypt the data. Another key point is the signing of the contents of a message. Signing means deriving a key from the content of the sent message and including this key with the message. The receiver then applies the key to the content and if the content was modified in any way the key will fail on it. This guarantees the authenticity of the message. II. HOW BCCAMPUS COMPLIES WITH WEBSERVICES SECURITY SPECIFICATIONS WebService messages are built on top of SOAP and OASIS specifies what needs to be included in the SOAP headers. The <wsse:security> header provides a mechanism for attaching security-related information in the form of a SOAP actor or role. The following attributes of <wsse:security> are used at BCcampus: mustunderstand EncryptedKey EncryptionMethod X509 Binary Security Token Signature Timestamp UsernameToken Password A Security Token conveys a set of claims. Sometimes these claims reside elsewhere and need to be accessed by the receiving application. The <wsse:securitytokenreference> element in the SOAP header provides an extensible mechanism for referencing security tokens. The following mechanisms are supported: Direct reference Key identifier Key name Embedded reference The signature algorithm used is RSA with SHA1. BCcampus allows the following SOAP elements to be signed:
The SOAP message body The identity token (used to assert identity) The encryption algorithm used is Key Transport (public key cryptography) RSA version 1.5. BCcampus allows the following SOAP element to be encrypted: The SOAP body The element provides a mechanism for expressing the creation and expiration times of the security semantics in a message. BCcampus tolerates the use of timestamps within the WebService security header on inbound and outbound messages. Finally, BCcampus generates SOAP security fault messages using the standard list of response codes listed in the specification. III. TOMCAT PACKAGING AND CONFIGURATION The target environment for running any of BCcampus WebService applications is tomcat. Applications are packaged as WAR packages and deployed to running tomcat containers. The BCcampus WAR package contains the following in its root directory: /WEB-INF/lib : Support libraries for applications, including WebServices, WS-Security and BCcampus support libraries. /WEB-INF/web.xml : Apache tomcat Servlet definition and mapping. /WEB-INF/cxf-servlet.xml : Apache CXF WebService configuration file where most of the server s WS-Security configuration is done. /WEB-INF/bccampusRequest.wsdl : The WSDL of the WebService application. This defines the WebService methods provided by the application and is outside the scope of this document. /WEB-INF/classes/*.class : The various java classes that form the application. /WEB-INF/classes/log4j.properties : The logging configuration of the application. /WEB-INF/classes/*.ks and *.ts : Keystores for the client and server : Explained below. /WEB-INF/classes/*.properties : Explained below. Four keystores are needed for a client/server application. These are storage facilities for cryptographic keys and certificates. webserviceclient.ks : Key store for the WebService client. webserviceclient.ts : Trust store for the WebService client (includes the public keys of the servers that the client trusts and accepts keys from). webserviceserver.ks : Key store for the WebService server. webserviceserver.ts : Trust store the for WebService server (includes the public keys of the clients that this server accepts connection from). There four property files dedicated to WS-Security and these are located in the /WEB-INF/classes location. clientencrypt.properties : defines configurable values for the encryption of outgoing messages from a client. clientsign.properties : defines configurable values for the signing of outgoing messages from a client. serversignverify.properties : defines configurable values for the verification of the client signature by the server. serverdecrypt.properties : defines configurable values for the decrypting of the message by the server. The WAR file, once assembled, is deployed to the tomcat s webapps directory in order to run the application. IV. ENCRYPTION KEY SETUP Before assembling the WAR, private/public key pairs have be generated and stored in their appropriate keystores. Most Windows and Linux operating systems provide the utility keytool to generate and manipulate cryptographic keys. It should be noted that BCcampus uses strong cryptography and as such additional security jars are typically added to the JAVA implementation. These are forbidden to export to some countries so please verify adherence criteria before installation. First a pair of keys are generated for the server (here the keys are self-signed and valid for 10 years): keytool -genkeypair -alias webserviceserver -keyalg RSA -validity 3650 -keystore webserviceserver.ks -storepass webserverpassword Then for the client: keytool -genkeypair -alias webserviceclient -keyalg RSA -validity 3650 -keystore webserviceclient.ks -storepass webclientpassword The public keys are extracted for the trust stores: keytool -alias webserviceserver export file server.cert -keystore webserviceserver.ks keytool -alias webserviceclient export file client.cert -keystore webserviceclient.ks And imported into the appropriate trust stores: keytool import trustcacerts -alias webserviceserver -keystore webserviceclient.ts -storepass webclientpassword keytool import trustcacerts -alias webserviceclient -keystore webserviceserver.ts -storepass webserverpassword At this point the four keystores are ready for inclusion in the WAR file.
V. THE WS-SECURITY PROPERTIES FILES Both client and server for the purpose of accessing their configuration during run time use the WS-Security properties files. They are used for signing, verification of signing, encryption and decryption. clientencrypt.properties webclientpassword webserviceserver webserviceclient.ts clientsign.properties webclientpassword webserviceclient webserviceclient.ks serverdecrypt.properties webserverpassword webserviceserver webserviceserver.ks serversignverify.properties webserverpassword webserviceclient webserviceserver.ts Please be aware that the contents of these files will be used by different components and sometimes the context of use will be perplexing to the user. For example, serversignverify.properties is used in the outgoing decryption module (instead of serverdecrypt as you d expect). Keep in mind that there are some inversion involved, ie. you decrypt what the client intended for you and not what you intended for the client. So it s important to follow to the letter these configurations. VI. SERVER CONFIGURATION Most of the WS-Security configurations of the server is accomplished in the cxf-servlet.xml file. The server itself is defined is the web.xml packages at the /WEB-INF level of the WAR file, which contains: <web-app> <servlet> <servlet-name>webserviceapplicationname</servlet-name> <display-name>generic Service Application</display-name> <servletclass>org.apache.cxf.transport.servlet.cxfservlet</servlet-class> <init-param> <param-name>config-location</param-name> <param-value>/web-inf/cxf-servlet.xml</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>webserviceapplication</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> </web-app> The WS-Security configuration is in cxf-servlet.xml defines a number of in and out interceptors that implement the security functionality. The incoming interceptors are defined as: <jaxws:ininterceptors> <bean class="org.apache.cxf.interceptor.loggingininterceptor"/> <bean class="org.apache.cxf.binding.soap.saaj.saajininterceptor"/> <bean class="org.apache.cxf.ws.security.wss4j.wss4jininterceptor"> <constructor-arg> <map> <!-- username/password section --> <entry key="action" value="usernametoken Timestamp Signature Encrypt"/> <entry key="passwordtype" value="passwordtext"/> <entry key="passwordcallbackclass" value="some.class.to.verify.passwords"/> <!-- decrypt section --> <entry key="decryptionpropfile" value="serverdecrypt.properties"/> <entry key="encryptionkeyidentifier" value="issuerserial"/> <!-- signature section --> <entry key="signaturepropfile" value="serversignverify.properties"/> <entry key="signaturekeyidentifier" value="directreference"/> </map> </constructor-arg> </bean> <bean id="cryptochecker" class="org.apache.cxf.ws.security.wss4j.defaultcryptocoveragecheck er"/> </jaxws:ininterceptors> Notice that there are 3 sections: username and password verification, decrypt section and signature section. First the username and passwords, supplied and encrypted in the SOAP
header, are verified using a class (here indicated as some.class.to.verify.passwords). Please note that this class not only needs to verify user passwords, but also the aliases supplied in the construction of the keystores along with the keystore passwords. A snippet of password verification code in JAVA might simply be: if (username.equals("webservicemethoduser")) { password = "WebServiceMethodPassword"; else if (username.equals("webserviceclient")) { password = "webclientpassword"; else if (username.equals("webserviceserver")) { password = "webservicepassword"; The cryptochecker line makes sure that incoming signature is correct and adheres to the timestamp validation nature. The server outgoing interceptors are configured as: <jaxws:outinterceptors> <bean class="org.apache.cxf.interceptor.loggingoutinterceptor"/> <bean class="org.apache.cxf.binding.soap.saaj.saajoutinterceptor"/> <bean class="org.apache.cxf.ws.security.wss4j.wss4joutinterceptor"> <constructor-arg> <map> <!-- username/password section --> <entry key="action" value="usernametoken Timestamp Signature Encrypt"/> <entry key="passwordtype" value="passwordtext"/> <entry key="passwordcallbackclass" value="some.class.to.verify.passwords "/> <entry key="user" value="webservicemethoduser"/> <!-- encrypt section --> <entry key="encryptionuser" value="webserviceclient"/> <entry key="encryptionpropfile" value="serversignverify.properties"/> <entry key="encryptionkeyidentifier" value="issuerserial"/> <entry key="encryptionparts" value="{element{http://docs.oasis- open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility- 1.0.xsdTimestamp;{Content{http://schemas.xmlsoap.org/soap/envelo pe/body"/> <!-- signature section --> <entry key="signatureuser" value="webserviceserver"/> <entry key="signaturepropfile" value="serverdecrypt.properties"/> <entry key="signaturekeyidentifier" value="directreference"/> <entry key="signatureparts" value="{element{http://docs.oasis- open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility- 1.0.xsdTimestamp;{Element{http://schemas.xmlsoap.org/soap/envelo pe/body"/> </map> </constructor-arg> </bean> </jaxws:outinterceptors> Please note the inversion of the properties for the encrypt and signature sections. Even though it doesn t look right, this is the correct WS-Security configuration. VII. CLIENT CODE The client code doesn t originate from a tomcat container. In JAVA, clients are typically generated initially from the WSDL file of the server by the java2wsdl command. Once the client skeleton is obtained from whatever method, the WS- Security code needs to be added before the client makes a WebService call. As an example, below, a WebContent/WEB- INF/wssec.xml file is created on the fly using Spring, but there are numerous other ways to achieve the same thing. // ws-security client outgoing SpringBusFactory bf = new SpringBusFactory(); Bus bus = bf.createbus("webcontent/web-inf/wssec.xml"); BusFactory.setDefaultBus(bus); The outgoing interceptor is then added: // outgoing username/password Map<String, Object> outprops = new HashMap<String, Object>(); outprops.put("action", "UsernameToken Timestamp Signature Encrypt"); outprops.put("passwordtype", "PasswordText"); outprops.put("passwordcallbackclass", "ca.bccampus.wsrequest.serverpasswordcallback"); outprops.put("user", " WebServiceMethodUser "); // outgoing encryption outprops.put("encryptionuser", "webserviceserver"); outprops.put("encryptionpropfile", "clientencrypt.properties"); outprops.put("encryptionkeyidentifier", "IssuerSerial"); outprops.put("encryptionparts", "{Element{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsdTimestamp;" + "{Content{http://schemas.xmlsoap.org/soap/envelope/Body"); // outgoing signature outprops.put("signatureuser", "webserviceclient"); outprops.put("signaturepropfile", "clientsign.properties"); outprops.put("signaturekeyidentifier", "DirectReference"); outprops.put("signatureparts", "{Element{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsdTimestamp;" + "{Element{http://schemas.xmlsoap.org/soap/envelope/Body;{{http://w ww.w3.org/2005/08/addressingreplyto;"); // set all outgoing interceptors bus.getoutinterceptors().add(new WSS4JOutInterceptor(outProps)); VIII. COPYRIGHT FORMS BCcampus uses open software products and accepts various licenses to use, distribute software and documentation from the Apache Software Foundation and Oracle Corporation. ACKNOWLEDGMENT The author thanks all BCcampus staff who helped assemble this document. REFERENCES [1] "Web Services Glossary". W3C. February 11, 2004. Retrieved 2011-04-22 [2] Bob Atkinson, et. al.: Web Services Security (WS-Security) [3] OASIS Web Services Security TC
[4] Web Services Security: SOAP Message Security Working Draft 13 [5] schemas.xmlsoap.org [6] 2013.