{section}
{column}
This document contains all the use cases related to the Petals-BC-SOAP component.
Use cases are ordered by their complexity, from the most simple to the most complex ones.

h1. Simple Use Cases

h2. Proxy SOAP using SSL et WS-Security

{tip}This use case runs with the Petals BC SOAP 5.0.0+. Its source code is available [here|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap].{tip}

The goal of this use-case is to show you how to configure the service units of BS Soap on both sides:
* to import into Petals, an external service secured with SSL and WS-Security. This external service is implemented using SoapUI,
* to export to outside an internal Petals service, secured with SSL and WS-Security.

The WS-Security parts will be based on:
* a time-stamp to avoid request re-injection,
* and authentication based on username and password:
** for the external service provider: `user-soapui/petals`
** for Petals service consumer re-exposing the external service provider to outside: `user-petals/petals`

This sample using SSL requires the following key stores:
* a key store 'external': keystore-external.jks (password: keystoreext), containing the private and public key of the external service provider,
* a key store 'petals': keystore-petals.jks (password: keystorepetals), containing the private and public key of Petals service consumer re-exposing the external service provider to outside.

{column}
{column:width=35%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h3. About the service provider

A service provider 'ArticleServiceContinuation' is available as a SoapUI mock secured by SSL and WSS at [http://localhost:8088/mockArticleServiceContinuationSoap11Binding-SSL-WSS?wsdl]. Just import the [SoapUI project|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap/sa-SOAP-samples-Proxy-SSL-WSS/src/soapui/Petals-Samples---BC-SOAP---Proxy-SSL-WSS-soapui-project.xml].

Once the SoapUI project mocking the external service provider is imported:
# generate the key store 'external',
# configure your SoapUI to use SSL with mocked service 'ArticleServiceContinuationSoap11Binding-SSL-WSS MockService', and start it.

h3. Generate the key store 'external'

The key store 'external' containing the private/public key pair of the external service provider for SSL can be generated with the following command line:
{code}
keytool -genkey -alias soapui-external-service-provider -keyalg RSA -keypass petals \
-dname "CN=SSL External Service Provider, OU=Petals, O=Linagora, L=Grasse, ST=AM, C=FR" \
-storepass petals -keystore keystore-external.jks
{code}

h3. Configure SoapUI to use SSL with the mocked service provider

# In SoapUI, click *Preferences* on the main toolbar or select *File* > *Preferences* and switch to the *SSL Preferences* page.
# Enable SSL for Mock Services,
# Set the port 8089 for Mock Services secured by SSL,
# Set the key store file to used,
# Set the password of the key store, as well as the password for the key (even if you specified the same password when creating the keystore).

{tip}This use case runs with the Petals BC SOAP 5.0.0+. Its source code is available [here|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap].{tip}

The goal of this use-case is to show you that it is possible to mixed SSL and WS-Security to secure an internal endpoint as a webservice using several certificats:
* a transport certificate identifying the webservice client,
* a transport certificate to crypt the communication between the serveur and the client,
* a message certificate to sign the message sent by the client and to warranty its integrity,
* a message certificate to crypt the SOAP body content,
* a user name and a password to identify the user of the client,
* a time-stamp to avoid request re-injection.

So, it is needed to have the following key stores:
* a key store 'client': keystore-clt.jks (password: keystoreclt), containing:
** the private keys of the client,
** the public keys of the serveur
* a key store 'server': keystore-srv.jks (password: keystoresrv), containing:
** the private key used to crypt the SOAP body content,
** the public key of the client used to sign
* a specific key store 'ssl': keystore-srv-ssl.jks (password: keystoresrv), containing:
** the SSL private key of the server
** the SSL public key of the client

The private keys of the client (symetrically, public keys of the server) are:
* 'sslclt': the private key identifying the client at SSL level (2-way SSL), password: 'keystoreclt',
* 'wsseclt-sign': the private key to sign the message, password: 'keystoreclt'.

The private keys of the server (symetrically, public keys of the server) are:
* 'sslsrv': the private key to crypt the communication between the server and the client, password: 'pwsslsrv',
* 'wsseclt-crypt': the private key to crypt the message, password: 'keystoresrv'.

{tip}Although encrypted message is generated by the client, the private key is located on the server side.{tip}
{tip}To simplify the use-case, all keys are auto-signed.{tip}
{tip}The version of the SoapUI used as client needs to have keys with the same password than their keystore.{tip}

h3. About the service provider

A service provider 'Math' is available as a SoapUI mock at [http://localhost:8088/mockMathBinding?wsdl]. Just import the [SoapUI project|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap/sa-ssl-wss/src/main/resources/SOAP-with-SSL---WSS-soapui-project.xml] and start the mocked service 'mathBinding MockService'.

h3. Importing the service provider into Petals

Using the Petals Studio, create a service unit to deploy on the BC SOAP and provide the service 'Math'. You should have a service unit JBI descriptor as following:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:soap="http://petals.ow2.org/components/soap/version-4"

xmlns:math="http://petals.ow2.org/samples/bc/soap/math">

<jbi:services binding-component="true">
<jbi:provides
interface-name="math:math"
service-name="math:mathService"
endpoint-name="autogenerate">

<!-- CDK specific elements -->
<petalsCDK:timeout>3000</petalsCDK:timeout>
<petalsCDK:validate-wsdl>true</petalsCDK:validate-wsdl>
<petalsCDK:forward-security-subject>false</petalsCDK:forward-security-subject>
<petalsCDK:forward-message-properties>false</petalsCDK:forward-message-properties>
<petalsCDK:forward-attachments>true</petalsCDK:forward-attachments>
<petalsCDK:wsdl>math.wsdl</petalsCDK:wsdl>

<!-- Component specific elements -->
<soap:address>http://localhost:8088/mockMath</soap:address>
<soap:soap-version>1.1</soap:soap-version>
<soap:mode>SOAP</soap:mode>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}

h3. Exporting the service provider outside Petals

Before to write the service unit that consume the internal service associated to the service provider 'Math', we need:
* to generate SSL, encryption and signature keys,
* to write the right WS-Policy.

h4. Creation of keys and key stores

h5. Creation of private keys

Open a command shell and go into the directory $PETALS_HOME/https. $PETALS_HOME/https is not a directory provided by Petals, it is used by this tutorial, so don't forget to create it manually.

* Creation and auto-sign of the private key 'sslclt':
{code}
keytool -genkey -validity 731 -keystore keystore-clt.jks -storepass keystoreclt -storetype JKS -keyalg RSA -alias sslclt -keypass keystoreclt -dname "CN=SSL Client, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 731 -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias sslclt -keypass keystoreclt
{code}

* Creation and auto-sign of the private key 'wsseclt-sign':
{code}
keytool -genkey -validity 731 -keystore keystore-clt.jks -storepass keystoreclt -storetype JKS -keyalg RSA -alias wsseclt-sign -keypass keystoreclt -dname "CN=WSSE Signature, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 731 -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias wsseclt-sign -keypass keystoreclt
{code}

* Creation and auto-sign of the private key 'wsseclt-crypt':
{code}
keytool -genkey -validity 731 -keystore keystore-srv.jks -storepass keystoresrv -storetype JKS -keyalg RSA -alias wsseclt-crypt -keypass keystoresrv -dname "CN=WSSE Encryption-In, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 721 -keystore keystore-srv.jks -storetype JKS -storepass keystoresrv -alias wsseclt-crypt -keypass keystoresrv
{code}

* Creation and auto-sign of the private key 'sslsrv':
{code}
keytool -genkey -validity 731 -keystore keystore-srv-ssl.jks -storepass keystoresrv -storetype JKS -keyalg RSA -alias sslsrv -keypass pwsslsrv -dname "CN=SSL Server, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 721 -keystore keystore-srv-ssl.jks -storetype JKS -storepass keystoresrv -alias sslsrv -keypass pwsslsrv
{code}

h5. Generation and export/import of public keys

* Export/Import of public key 'sslclt':
{code}
keytool -export -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias sslclt -file sslclt.crt
keytool -import -keystore keystore-srv-ssl.jks -storetype JKS -storepass keystoresrv -alias sslclt -file sslclt.crt
{code}

* Export/Import of public key 'wsseclt-sign':
{code}
keytool -export -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias wsseclt-sign -file wsseclt-sign.crt
keytool -import -keystore keystore-srv.jks -storetype JKS -storepass keystoresrv -alias wsseclt-sign -file wsseclt-sign.crt
{code}

* Export/Import of public key 'wsseclt-crypt':
{code}
keytool -export -keystore keystore-srv.jks -storetype JKS -storepass keystoresrv -alias wsseclt-crypt -file wsseclt-crypt.crt
keytool -import -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias wsseclt-crypt -file wsseclt-crypt.crt
{code}

* Export/Import of public key 'sslsrv':
{code}
keytool -export -keystore keystore-srv-ssl.jks -storetype JKS -storepass keystoresrv -alias sslsrv -file sslsrv.crt
keytool -import -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias sslsrv -file sslsrv.crt
{code}

h4. Writing the WS-Policy

The following WS-Policy contains assertions about our requirement:
* 2-Way SSL,
* and WS-Security with:
** authentication based on a timestamped username token,
** encryption of the body part,
** and signature of the body part.

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?><wsp:Policy wsu:Id="SigEncr"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:ExactlyOne>
<wsp:All>
<sp:TransportBinding>
<wsp:Policy>
<sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken>
<wsp:Policy>
<sp:RequireClientCertificate />
</wsp:Policy>
</sp:HttpsToken>
</wsp:Policy>
</sp:TransportToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic256 />
</wsp:Policy>
</sp:AlgorithmSuite>
<!-- sp:Layout>
<wsp:Policy>
<sp:Strict />
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp /-->
</wsp:Policy>
</sp:TransportBinding>
<sp:SupportingTokens>
<wsp:Policy>
<sp:UsernameToken/>
</wsp:Policy>
</sp:SupportingTokens>
<sp:SymmetricBinding>
<wsp:Policy>
<sp:ProtectionToken>
<wsp:Policy>
<sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never" />
</wsp:Policy>
</sp:ProtectionToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic128 />
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Strict />
</wsp:Policy>
</sp:Layout>
<sp:EncryptBeforeSigning />
<sp:OnlySignEntireHeadersAndBody />
</wsp:Policy>
</sp:SymmetricBinding>
<sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body />
</sp:SignedParts>
<sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body />
</sp:EncryptedParts>

<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">
<!-- Username of UsernameToken to be used -->
<ramp:user>ssl-wss-client-username</ramp:user>
<!-- Key alias used to sign -->
<ramp:userCertAlias>wsseclt-sign</ramp:userCertAlias>
<!-- Key alias used to encrypt -->
<ramp:encryptionUser>wsseclt-crypt</ramp:encryptionUser>
<ramp:passwordCallbackClass>org.ow2.petals.samples.bc.soap.ssl_wss.PasswordCallback</ramp:passwordCallbackClass>

<ramp:signatureCrypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">keystore-srv.jks</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">keystoresrv</ramp:property>
</ramp:crypto>
</ramp:signatureCrypto>
<ramp:encryptionCypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">keystore-srv.jks</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">keystoresrv</ramp:property>
</ramp:crypto>
</ramp:encryptionCypto>
</ramp:RampartConfig>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
{code}

h4. Creation of the consumer service unit

Using the Petals Studio, create a service unit to deploy on the BC SOAP and consume the internal service 'Math'.
Next update its JBI descriptor to add the right configuration about SSL and WS-Security:
{code}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:soap="http://petals.ow2.org/components/soap/version-4"

xmlns:math="http://petals.ow2.org/samples/bc/soap/math">

<jbi:services binding-component="true">
<jbi:consumes
interface-name="math:math">

<!-- CDK specific elements -->
<petalsCDK:timeout>30000</petalsCDK:timeout>
<petalsCDK:mep xsi:nil="true" />

<!-- Component specific elements -->
<soap:service-name>MathServiceWithSSLAndWSS</soap:service-name>
<soap:mode>SOAP</soap:mode>
<soap:enable-http-transport>false</soap:enable-http-transport>
<soap:enable-https-transport>true</soap:enable-https-transport>
<soap:enable-jms-transport>false</soap:enable-jms-transport>
<soap:modules>rampart</soap:modules>
<soap:wss-policy>ws-policy.xml</soap:wss-policy>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}
where '{{ws-policy.xml}}' is the WS-Policy previously defined.

Add the class 'PasswordCallback' as password callback:
{code:lang=java}
public class PasswordCallback implements CallbackHandler {

public void handle(final Callback[] callbacks) throws IOException, UnsupportedCallbackException {

for (int i = 0; i < callbacks.length; i++) {
final WSPasswordCallback pwcb = (WSPasswordCallback) callbacks[i];
final String username = pwcb.getIdentifier();
if (username.equals("ssl-wss-client-username")) {
// Retrieve the password associated to the username of the UsernameToken
pwcb.setPassword("ssl-wss-client-password");
} else if (username.equals("wsseclt-crypt")) {
// Retrieve the password associated to the key used to encrypt
pwcb.setPassword("keystoresrv");
}
}
}
}
{code}

h3. Running the use case

Launch a freshly installed Petals ESB. Launch your SoapUI and start the mocked service.

Launch the script '{{deploy.sh}}' available [here|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap/sa-ssl-wss/src/main/scripts/deploy.sh] after to have adjusted the environment with '{{env.sh}}'.

Use SoapUI to invoke your secured service ! Sample requests are available into the SoapUI project.


h1. Complex Use Cases

These use cases involve several Petals components including the Petals-BC-SOAP component.

{contentbylabel:labels=uc-soap|showLabels=false|showSpace=false}