Use Cases for Petals BC SOAP 5.0.0+

Version 3 by Christophe DENEUX
on Jun 27, 2018 11:08.

<< Changes from 2 to 3

compared with

Version 4 by Christophe DENEUX
on Jun 27, 2018 13:08.

Changes from 4 to 5 >>

Key

This line was removed.

This word was removed. This word was added.

This line was added.

Changes (27)

View Page History

...

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. Securing a service running into Petals using 2-Way SSL and WS-Security

{tip}This use case runs with the Petals BC SOAP 5.0.0+{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">


<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>


<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"?>

<?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>

</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">

<ramp:user>ssl-wss-client-username</ramp:user>

<ramp:userCertAlias>wsseclt-sign</ramp:userCertAlias>

<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}

...

</jbi:services>
</jbi:jbi>

<jbi:jbi version="1.0"
xmlns:generatedNs="http://InformationDeProduction.cirtil.cer69.recouv/InformationDeProduction.wsdl"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:soap="http://petals.ow2.org/components/soap/version-4"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<jbi:services binding-component="true">
<jbi:consumes
interface-name="generatedNs:InformationDeProductionPortType"
service-name="generatedNs:InformationDeProductionService"
endpoint-name="InformationDeProductionPort">


<petalsCDK:timeout>30000</petalsCDK:timeout>
<petalsCDK:mep xsi:nil="true" />


<soap:service-name>InformationDeProductionServiceSSLandWSSE</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:service-parameters>
<![CDATA[
<parameter name="InflowSecurity">
<action>
<items>Signature Encrypt Timestamp UsernameToken</items>
<user>wsseclt-id</user>
<passwordCallbackClass>org.ow2.petals.test.PWCBHandler</passwordCallbackClass>
<userCertAlias>wsseclt-sign</userCertAlias>
<signaturePropFile>service.properties</signaturePropFile>
<decryptionPropFile>service.properties</decryptionPropFile>
</action>
</parameter>
]]>
</soap:service-parameters>
</jbi:consumes>
</jbi:services>
</jbi:jbi>

{code}

where '{{ws-policy.xml}}' is the WS-Policy previously defined.

Add the properties file 'service.properties' under the directory 'jbi' and containing:

Add the class 'PasswordCallback' as password callback:

{code:lang=java}

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=keystoresrv
org.apache.ws.security.crypto.merlin.file=../https/keystore-srv.jks
{code}

public class PasswordCallback implements CallbackHandler {

Add the class 'PWCBHandler' as password callback:

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

{code}

public class PWCBHandler implements CallbackHandler {

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

for (int i = 0; i < callbacks.length; i++) {

final WSPasswordCallback pwcb = (WSPasswordCallback) callbacks[i];
final String username = pwcb.getIdentifier();

WSPasswordCallback pwcb = (WSPasswordCallback)callbacks[i]; if (username.equals("ssl-wss-client-username")) {

// Retrieve the password associated to the username of the UsernameToken

String id = pwcb.getIdentifer(); pwcb.setPassword("ssl-wss-client-password");

} else if (id.equals("wsseclt-id")) (username.equals("wsseclt-crypt")) {

// Retrieve the password associated to the key used to encrypt

pwcb.setPassword("pwwsseid"); pwcb.setPassword("keystoresrv");

}

else if (id.equals("wsseclt-crypt")) {
pwcb.setPassword("keystoresrv");
}

}
}

...

h3. Running the use case

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

Install the Petals BC SOAP enabling SSL through the component parameters:
* https-enabled = true
* https-port = 8083
* https-keystore-type = JKS
* https-keystore-file = ../https/keystore-srv-ssl.jks
* https-keystore-password = keystoresrv
* https-key-password = pwsslsrv
* https-client-authentication-enabled = true

Deploy your SU.
Use SoapUI to invoke your secured service !

Launch the script '{{deploy.sh}}' available here after to have adjust the environment with '{{env.sh}}'.

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

h1. Complex Use Cases

...

Wiki

All versions of Petals ESB

Helpful links

Use Cases for Petals BC SOAP 5.0.0+

Changes (27)