Using Encrypt Security Action

This section demonstrates the capability of WSStub and WSConsumer (4.0) to send/receive secured SOAP messages using Encrypt Web Service Security action.

Scenario

Expose a simple Web Service using WSStub. Using the Encrypt WS-Security mechanism, configure the WSStub component to encrypt messages from the sender (WebserviceConsumer 4.0) of SOAP requests. Similarly, using the Encrypt mechanism, configure the WebserviceConsumer component to decrypt messages from the sender (WSStub) of SOAP responses.

Encryption/Decryption in WS-Security is usually done using public and private keys. For a sender (WSConsumer in this case) to encrypt, the public key of the receiver is needed. For a receiver (WSStub) to decrypt, it should have its private key. Similarly, while sending the response, WSStub should have WSConsumer’s public key and WSConsumer should have its private key. These public and private keys can be stored in a keystore to use in the components. Generating private keys and self-signed certificates is explained in the following sections.

Components used

• WSStub
• WebServiceConsumer4.0
• Feeder
• Display

Basic Encryption settings

Create Password Callback Class

Password Callback Class is required for Encrypt security action to specify password for private keys in the keystore. Private keys will be used to sign and/or decrypt a message.  To specify a password, an implementation of javax.security.auth.callback.CallbackHandler is needed. A fully qualified class name for this implementation should be provided in the Configuration Property Sheet (CPS).

Refer Creating Password Callback Class handler to create a Password Callback Class.

Generating Keystore

Keystore used for encryption and signature can either have self-signed or Certificate Authority (CA) signed certificates.

To generate a private key and a self-signed certificate, JDK’s keytool may be used.

Command to generate a single entry keystore which acts both as a private key and also a corresponding self-signed certificate containing the public key is as below.

$ keytool -genkeypair -dname <domainName> -validity <no. of days> -alias <alias> -keystore <keystore name> -storepass <keystore password> -keypass <private key password> -keyalg <algorithm used to generate key pair> -sigalg <algo used to sign the certificate>

 $ keytool -genkeypair -dname "CN=TempName, OU=Engineering, O=Progress, ST=HYD, C=IN" -validity 365 -alias fiorano -keystore fiorano.keystore -storepass fioranostorepass -keypass fioranokeypass -keyalg RSA -sigalg SHA1withRSA

More information about this command can be found at http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html#genkeypairCmd.

Save this keystore file with the name 'fiorano'

Creating Encryption Properties file

Create a text file with the following content and save it with the name 'crypto':

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.file=fiorano.keystore
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=fioranostorepass
org.apache.ws.security.crypto.merlin.keystore.alias=fiorano

• org.apache.ws.security.crypto.provider - suggests the security provider class name using which encryption details are generated.
• org.apache.ws.security.crypto.merlin.file - suggests the file name of the corresponding keystore.
• org.apache.ws.security.crypto.merlin.keystore.type – type of keystore
• org.apache.ws.security.crypto.merlin.keystore.password – password for keystore
• org.apache.ws.security.crypto.merlin.keystore.alias – alias of keystore entry (private or public key depending on the action)

Using the attributes (created files) in Web Service components

The below component contents need to be used in the manner as explained further:

• Keystore (fiorano.keystore)
• Encryption Properties file (crypto.properties)

Ensure that Password Callback Class (PWCallback.jar) is already saved appropriately as mentioned in the Creating Password Callback Class handler section.

WSStub

Copy the files mentioned above to the following location:

%FIORANO_HOME%\esb\server\jetty\fps\webapps\bcwsgateway\WEB-INF\classes

After copying the files, restart the Peer server on which WSStub is running.

WSConsumer

Add the files as resource by editing WSConsumer properties in the ServiceDescriptor.xml section in eStudio.

Setting up the Example

Configuring WSStub component

When WSStub receives a message secured by Encryption, it will verify the username and password. To verify, Encrypt action must be enabled in the WSStub Configuration Property Sheet (CPS).

To configure WSStub component, perform the following action in eStudio:

1. Add a new Event Process with the name 'WSSecurity_Example'.
2. Drag the WSStub component from the WebService category in the Micro Service Palette to the Fiorano Orchestrator.
   
   

   

   
   Figure 2: Adding WSStub component to Fiorano Orchestrator
    
3. Double-click the WSStub component in the orchestrator to open Configuration Property Sheet (CPS).
4. In the Configuration screen, click WSDL Configuration button
   
   

   

   
   Figure 3: WSDL Configuration
    
5. In the WSDL Configuration dialog box, select Auto_created_Operataion present in the left pane to enable input (request) and output (response).
   
   

   

   
   Figure 4: Selecting Auto_created_Operation
    
6. Under Input tab, perform the below actions:
   1. Click Add button to add Name 'PartName1'.
   2. Click the Ellipsis button to open Select Type/Element dialog box. Select the string option to configure the WSStub component to send a string message and then click OK.
      
      

      

      
      Figure 5: Adding Input attributes under Auto_created_Opretaion
       

7. Perform the same actions (as performed under the Input tab) under Output tab to add a part 'PartName1' and 'string' under Name and Type/Element respectively and click OK in the WSDL Configuration dialog box.
   

   

   Fiorano Mapper will be used to configure Route Transformation between Input and Output. This is explained in the Configuring Route Transformation section.

8. Click Next to navigate to Security Configuration screen. Under WS-Security Configuration section, click WS-Security button to configure WS-Security settings.
   
   

   

   
   Figure 6: Security Configuration
    

9. In the Request WS-Security tab, perform the following actions:
   1. Under Security Actions section, select Encrypt check box, and clear the UsernameToken check box if it is selected.
   2. In Encryption Properties File text field under Encrypt section, provide the name of the file (crypto.properties) where keystore properties are saved (refer the (13.0) Using Encrypt Security Action#Creating Encryption Properties file section).

   3. In Password Callback Class under Username Token section, provide the class name (PWCallback).
      

      

      If the class hav a package, then provide absolute class, that is, if the password Callback Class name is 'PWCallback' in the package com.wsSecurity package, then the absolute class name is 'com.wsSecurity.PWCallback'. This class will provide the necessary password which will then be added along with the User in the Security Header of the message.

      

      
      Figure 7: Security settings in Request WS-Security
      

      • Other actions such as the following can also be used:
        • UsernameToken as illustrated in the previous example Using UsernameToken Security Action.
        • A Timestamp value can be added to Request/Response to carry Created and Expires values indicating when a request or response is created and when it will expire. While adding a timestamp to the security header, the Created element will have the current time in GMT, and the Expires element will have the current time + time to live in GMT.
        • Signature configuration is similar to that of Encryption. Here, the client should have a keystore that has its own private key, and the server should have a keystore with the client’s public key in it.
      • When more than one action is chosen, the order of actions can be managed by selecting the action and using the scroll buttons on the right side.

       

10. In the Response WS-Security tab, select Encrypt check box (clear the UsernameToken checkbox if it is selected) under Security Actions section and provide the following values under Encrypt section:

    1. Encryption User: Value of org.apache.ws.security.crypto.merlin.keystore.alias (refer the (13.0) Using Encrypt Security Action#Creating Encryption Properties file section) which is the encryption user name.
    2. Encryption Properties File: Name of the file (crypto.properties) where keystore properties are saved.

    3. Encryption Key Identifier: Set to 'DirectReference' since any self-signed certificate will not likely be present at the server and setting this option will send the certificate containing public key along with the request.

       

       
       Figure 8: Security settings in Response WS-Security
       

       It is possible to encrypt certain elements in the request XML than the entire request. These elements can be configured using Encryption Parts property. Please refer to WSStub help for more information on this. For this example, leave it empty to encrypt the whole request.

        

11. Click OK to save WS-Security settings and click Finish to save WSStub component configuration.

12. In the three ports that get generated after WSStub configuration, connect the output port 'REQUEST' to the input port 'RESPONSE'.
    
    

    

    
    Figure 9: Connecting WSStub output port to input port

Configuring Route Transformation

To configure the transformation between the input and output port, perform the following actions in the Fiorano Orchestrator:

1. Right-click route1, point to Configure Transformation, and select Mapper Project to open the Fiorano Mapper editor.
   
   

   

   
   Figure 10: Opening Mapper Project editor
    
2. In the Output Structures panel in Mapper Project, click PartName1 element as it appears in Funclet View.
   
   

   

   
   Figure 11: Adding PartName1 to Funclet View
    
3. In the Funclet View panel, drag the function element Constant to the Funclet easel and double-click it to change the name to 'Secure_ACK' to give logical meaning to the scenario (acknowledgement message of secured/encrypted message received).
   
   

   

   
   Figure 12: Adding Constant and renaming it
    
4. Connect the Source node of the constant 'Secure_ACK' to the destination node of PartName1.
   
   

   

   
   Figure 13: Connecting the Constant with PartName1
    
5. Click Save icon (or File >Save) to save the transformation configuration and close the Mapper Project editor.

Launching Web Service

To launch the webservice, perform the following actions:

1. Click Check Resource and Connectivity icon (or press ALT+SHIFT+C) to check resource and connectivity.
2. Click Run Event Process icon (ALT+SHIFT+R).
3. Right-click WSStub component and click Copy WSDL URL to copy the URL to clipboard, which is used in the next section.
   
   

   

   
   Figure 14: Copying WSDL URL to clipboard

Configuring WebSeriveConsumer component

Setting up the Security Configurations in WebServiceConsumer component, corresponding to the WSStub security configurations, is essential to access the webservice. To configure the component, perform the following actions:

1. Drag the WebserviceConsumer component from the WebService category in the Micro Service Palette to the Fiorano Orchestrator.
   
   

   

   
   Figure 15: Adding WebServiceConsumer to Orchestrator
    
2. Double-click the WebserviceConsumer component in the orchestrator to open Configuration Property Sheet (CPS).
3. In the Managed Connection Factory, click WSDL Ellipsis button. In Wsdl dialog box, paste the copied WSDL URL in the URL text field and click OK.
   
   

   

   
   Figure 16: Pasting the copied WSDL URL
    
4. Click Next. In the Interaction Configurations page, click WebService Operation Ellipsis button and select the operation with the prefix 'Auto_created_Operation' from OperationName dialog box. Click OK to configure Web Service Security settings.
   
   

   

   
   Figure 17: Selecting Auto created operation
    
5. To verify the credentials, Encryption action must be enabled in WSConsumer too (as configured in WSStub). So, scroll down the screen and provide the following values under Security – Request section:
   1. Encryption User (fiorano)
   2. Encryption Properties filename (Request) (crypto.properties)

   3. Encryption Key Identifier (DirectReference)

      

      • Provide the same values as provided in the Response WSSecurity section in WSStub section.
      • Leave Encryption Parts property blank to encrypt the entire request.
      • Clear Is Password Required check box if it is selected.

      

      
      Figure 18: Security Request settings

       

6. Scroll down the screen and provide the following values under Security – Response section:

   1. Select Encrypt WS-Security (Response) check box.
   2. Encryption Properties filename (Response): Same value as provided in Encryption Properties filename (Request) above (crypto.properties).
      
      

      

      
      Figure 19: Security Response settings
       
7. Click Finish to save WebServiceConsumer component configuration.

Composing the Event Process and Configuring the Feeder component

Drag a Feeder component and Display component from Util category in the Micro Service Palette to the WSSecurity_Example Fiorano Orchestrator.

1. Connect the components in the below manner:
   1. Feeder output port to WebServiceConsumer input port.
   2. WebServiceConsumer output port to Display input port.
      
      

      

      
      Figure 20: Connecting Feeder and Display to WebServiceConsumer component
       
2. Double-click Feeder component and perform the following actions to configure it:
   1. In the Message Type Configuration page, retain Output Message Format option as 'XML' and click the Connected Port Schemas button.
   2. In the Connected ports dialog box, select IN_PORT to enable connection between the output port of Feeder and input port of WebServiceConsumer component. Click OK and then click Next.
      
      

      

      
      Figure 21: Enabling connection between input and output ports
       
   3. In the Message Details Configuration page, click the Generate Sample button to load sample input.
   4. Under No.of Repeatable elements to be generated section in the XSD Sample Generation Dialog window, replace max value '3' with '1' so that only one output is generated, and click OK.
      
      

      

      
      Figure 22: Reducing maximum number of output to '1'
       
3. Click Finish to save the Feeder configuration.
   
   

   

   
   Figure 23: Loading Sample Input

Running the Example

To run the example, perform the following actions in the WSSecurity_Example event process:

1. Click Synchronize Event Process icon to apply the modifications made to the event process that is already running. Two windows get opened for Feeder and Display components.
    
2. In the Feeder, click the Send button to send the message "PartName1".
   
   

   

   
   Figure 24: Sending message from Feeder
    
3. In the Display window, click the second tab at the lower-left part of the window.
   EncryptKey header indicates that Username Token security action is enabled on response in WSStub and that WebserviceConsumer authenticates using values provided under Security-Response. PartName1 'SecureACK' can also be found.
   
   

   

   
   Figure 25: Message received in Display with the UsernameToken header and PartName1

Reference

Please note that the component options used in this example are specific to WS-Security. To explore other options present in WSStub and WebServiceConsumer components, refer to the sections WSStub and WebServiceConsumer4.0 respectively.