Back to Contents 

How to handle WS Security

Genero Web Services does not entirely manage WS-Security. We provide XML APIs to help the development of Web Services with security.

Topics

• Introduction
• Server side
• Client Side
• Reference

Introduction

This topic describes how to handle WS Security using the demo wssecuritymessage. It is a sample that you can adapt to your needs. The demo will be enhanced to illustrate new features that will be introduced to fully support WS-Security.

The demo involves three clients exchanging secured messages. Those clients post and retrieve messages on a secured server. Each client is identified by a certificate and sign their messages.

We assume that you are familiar with security concepts described in topic "Encryption and Authentication Concepts".

The demo assumes that all the clients have sent their public keys to the other clients and to the server. Those keys are kept in each host's (server or clients) keystore. The certificates included in this package are provided for demonstration purposes only. As they are distributed with this package, anybody using this product can decrypt the messages exchanged. Do NOT use them in production.

Back to the top 

Server side

We provide 3 handlers to handle WS Security:

• Method com.WebService.registerWsdlHandler() to modify the wsdl to add WS policy.
• Method com.WebService.registerInputRequestHandler() to handle WS Security in an incoming request
• Method com.WebService.registerOutputRequestHandler() to handle WS Security in an outgoing request

In this demo, a received message is processed:

1. Identify the sender and validate the sender (search in keystore)
2. Decrypt the symmetric key with the server private key
3. Decrypt the body
4. Check the signature with the sender public key
5. Store the message in the box (thanks to the "To" field, "subject" and "message")
6. Create the outgoing message
7. Sign the outgoing message
8. Encrypt the outgoing message with a generated symmetric key. This symmetric key is then encrypted with the client public key.

Back to the top 

Client side

The client consists in sending a message and retrieving messages clients sent to it.

Before that, create the client stub from the wsdl:

• fglwsdl -domHandler myservice.wsdl

The client stub reference handlers:

• SecureMessageBox_HandleRequest
• SecureMessageBox_HandleResponse
• SecureMessageBox_HandleResponseFault

For more details about client SOAP handlers see Client stub and handlers.

What to do when a message is sent:

• Sign and encrypt the request for the server (WS-Security)
  • sign with client private key
  • encrypt with server public key
• Send key information in the request
  • key to identify the sender/client
  • key to identify the recipient/server
  • key used to encrypt the data (usually a symmetric key encrypted by the recipient public key)
• If the message has to be encrypted for the final recipient (XML-Security)
  • sign the message
  • encrypt the message

What to do to retrieve messages:

• Identify the sender and validate the sender (search in keystore)
• Identify the recipient (should be the server itself)
• Decrypt the request
• Check the signature
• Retrieve messages for the recipient

Back to the top 

Reference

The policy documentation can be found here.

The demo policy is divided into sections (make sure that the naming are correct and that the structure is understandable):

• Security Binding
• SOAP message security options
• SignedParts
• EncryptedParts

WS Security section begins with:

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy ... />

It defines rules:

<wsp:ExactlyOne>

Only one assertion should be fulfilled.

<wsp:All>

All the assertions should be fulfilled.

Security Binding

There are 3 types of security binding:

• TransportBinding
• SymmetricBinding
• AsymmetricBinding

The current demo uses the Asymmetric binding.

Asymmetric Binding

This section is divided in sub sections:

• InitiatorToken
• RecipientToken
• AlgorithmSuite
• Layout
• Additional assertions

AsymmetricBinding is the root node for protection description.

<sp:AsymmetricBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">

InitiatorToken is the message sender (client)

Example

<sp:InitiatorToken>
  <wsp:Policy>
    <sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
      <wsp:Policy>
        <sp:RequireThumbprintReference /> 
        <sp:WssX509V1Token10 /> 
      </wsp:Policy>
    </sp:X509Token>
  </wsp:Policy>
</sp:InitiatorToken>

The token is used for the message signature from initiator to recipient and encryption from recipient to initiator.
The initiator key is a X509 certificate that is always sent to the recipient.
sp:IncludeToken attribute indicates if the token must be included.
IncludeToken/AlwayToRecipient means each requests sent to the recipient must include the initiator token. But the token should not be included in messages from recipient to initiator.
The token must send its Thumbprint Reference.
The token must be of type X509 version 1 as defined in "X509 token profile 1.0".

What should be done in 4GL is decribed in Client Side section.
To retrieve the thumbprint reference you can use the API function xml.CryptoX509.getThumbprintSHA1
To create the x509 certificate use an appropriate tool like openssl.

RecipientToken is the message receiver (server)

<sp:RecipientToken>
  <wsp:Policy>
    <sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
      <wsp:Policy>
        <sp:RequireThumbprintReference /> 
        <sp:WssX509V3Token10 /> 
      </wsp:Policy>
    </sp:X509Token>
  </wsp:Policy>
</sp:RecipientToken>

The token is used for encryption from initiator to recipient, and for the message signature from recipient to initiator.
The recipient key is a X509 certificate that is never sent to the initiator.
sp:IncludeToken attribute indicates if the token must be included.
IncludeToken/Never means the token should not be included in any requests between the initiator and the recipient.
Instead the recipient ThumbprintRefrence is sent.
The token must be of type X509 version 3 as defined in "X509 token profile 1.0"

What should be done in 4GL is decribed in Server Side section.
To retrieve the thumbprint reference you can use the API function xml.CryptoX509.getThumbprintSHA1
To create the appropriate certificate use an appropriate tool like openssl.

AlgorithmSuite tells which algorithm is used to encrypt the data.

<sp:AlgorithmSuite>
 <wsp:Policy>
  <sp:TripleDesRsa15 /> 
 </wsp:Policy>
</sp:AlgorithmSuite>

TripleDesRsa15 refers to key http://www.w3.org/2001/04/xmlenc#tripledes-cbc.

Layout describes the way information are added to the message header.

<sp:Layout>
 <wsp:Policy>
  <sp:Strict /> 
 </wsp:Policy>
</sp:Layout>

For example, with Strict layout, token that are included in the message must be declared before use. For more details on the rules to follow see the security policy specifications section 7.7.

PartsToSign

<sp:OnlySignEntireHeadersAndBody />

The assertion means if there is any signature on the header or the body it should be on the entire header and the entire body not on their child element.

SOAP message security options

<sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
  <sp:MustSupportRefKeyIdentifier />
  <sp:MustSupportRefIssuerSerial />

• MustSupportRefKeyIdentifier means that initiator and recipient are able to generate and process key identifier reference.
• MustSupportRefIssuerSerial means that initiator and recipient are able to generate and process issuer and token serial reference.

SignedParts

The SignedParts section tells which part of the message should be signed.

<sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
  <sp:Body />

• Only the body needs to be signed

EncryptedParts

The section EncryptedParts tells which part of the message should be encrypted.

<sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
  <sp:Body />

• sp:Body indicates the body message needs to be encrypted

Encrypt the body using the algorithm referenced in assertion AlgorithmSuite:

• create an encryption key using TripleDesRsa15 algorithm like example2 in crypto key chapter that uses AES256
• encrypt the body with the created key

To find the exact syntax of security message read the specifications "Web Services Security: SOAP Message Security 1.0".

Useful links

• Security Policy specifications v1.2
• SOAP Message Security 1.0
• X.509 Token Profile 1.1

Back to the top