Encrypt with Apache Rampart/C

Message level security has become a hot topic for the past few years and plays a very crucial role in SOA. It provides confidentiality and integrity for messages exchanged, independent from the underlying transport protocol. Among WS-* specifications, WS-Security caters to the above purposes. As the security module for Apache Axis2/C, Apache Rampart/C has extended its capabilities to support WS-Security. The first phase of this is to implement SOAP message encryption. Following article by Kaushalye Kapuruge will describe how to use Apache Rampart/C module along with Apache Axis2/C engine to encrypt SOAP messages. Date: Thu, 25th Jan, 2007 Level: Reads: 10182 Discuss this article on Stack Overflow

Malinda Kaushalye Tech-lead WSO2 Inc.

To Whom is this Article For?

We assume the reader to have prior understanding on the behavior of Axis2/C engine. Moreover, a basic knowledge of cryptography and Web services would definitely help to absorb the content. We have also listed few other articles and Web resources that will help you to bag much needed background knowledge.

Rampart as a Module

Apache Rampart works as a module inside Apache Axis2/C engine. That means Rampart needs to be configured using the configuration mechanisms available in Axis2/C engine. Configuring a module is a very simple process. All you have to do is set a few parameters in a descriptor file. There are two kinds of descriptor files.

1. axis2.xml
2. services.xml

The first descriptor file (i.e. axis2.xml) is used to configure a particular module globally. In other words, the configurations are applied for all the services. If you need to encrypt all the messages that are exchanged by all the services in the same manner, this is the place to keep your configurations. But global configuration is a bit of an unlikely scenario. Most of the time you need to have different configurations for different services. For example you might need to encrypt messages of a particular services that exchanges confidential data whilst keeping another service simple. Or may be you need to encrypt a particular message exchange using Triple-DES and another using AES-256. For this kind of a scenario the file to place your configurations is in the services.xml.

In the following discussion we will limit configurations that are necessary only for the SOAP message encryption. If you need to learn how to configure UsernameToken and Timestamps we recommend you to read the article Introducing Rampart/C.

XML Encryption Library

OMXMLSecurity is the XML encryption library used by Rampart. OMXMLSecurity is specifically written for AXIOM (AXis Object Model), which is the XML object model used by Axis2. Although there were other C language implementations of XML Security, they are based on different object models such as DOM (Document Object Model). It was required to implement an XML Security library for AXIOM rather than converting XML data to AXIOM from another model, which is an inefficient process. The first phase of OMXMLSecurity is to support XML encryption as per W3C Recommendations . There is still no support for the XML signatures in Rampart. After completion of phase II we would be able to sign SOAP messages.

Right now OMXMLSecurity is packed as a sub module of Rampart. So you don't need to install it separately. Once you install Rampart, OMXMLSecurity is available for you. But OMXMLSecurity uses OpenSSL routines. Thus, in order to use Rampart in your system you need to have OpenSSL installed. OpenSSL is free. Please visit www.openssl.org to get it downloaded.

Encryption Process

WS-Security specification provides a wide variety of modes to encrypt SOAP messages. The most common way to encrypt a message is to encrypt a particular portion of the message with a one time (session) key and then deliver it, encrypted with the receiver's public key. This approach is a very secure and efficient way to encrypt SOAP messages for following reasons:

1. We do not use asymmetric key encryption to encrypt the data as it is an inefficient process if the data is lengthy. Instead we use symmetric key encryption.
2. We do not use the same symmetric key more than once, as it can be vulnerable for attacks.
3. The session key is encrypted using the receiver's public key. Therefore the session key can be decrypted only by the receiver's private key, which is known only to the receiving party.

The current version of Rampart encryption encrypts only the body of the message. Later we would be able to facilitate encryption of a desired portion in the message.

How to Configure Rampart/C to Encrypt Messages

First you need to engage the Rampart module. This means you enable the module to process SOAP messages. This can be done by simply adding the following line to your descriptor file,

<module ref="rampart"/>

This line will enable the Rampart handlers to invoke incoming and outgoing messages. Encryption happens in the OutFlow of messages whilst the decryption happens in the InFlow. Please add following to configure the outflow.

<parameter name="OutflowSecurity">
    <action>     </action>
</parameter>

Still Rampart does not encrypt messages. To enable this you have to place Encrypt under the items element as follows:

<parameter name="OutflowSecurity">
    <action>
    <items>Encrypt</items>
    </action>
</parameter>

Now Rampart knows that the outgoing messages should be encrypted. Still it doesn't know where to locate the receiver's certificate. Also you might need to change the default behavior's of Rampart. For example changing an algorithm. Following section will give you the semantics of parameters used by Rampart so that you will know how to perform the above mentioned tasks.

encryptionPropFile: The receiver's certificate. The full path to the file location has to be specified. This certificate should be in PEM format. PEM format is simply base64 encoded data surrounded by --BEGIN CERTIFICATE-- and --END CERTIFICATE-- header lines.

encryptionSymAlgorithm : Sets the algorithm used to encrypt data. This is a symmetric algorithm such as Triple-DES. You may use one of these values for this parameter.

1. http://www.w3.org/2001/04/xmlenc#tripledes-cbc
2. http://www.w3.org/2001/04/xmlenc#aes128-cbc
3. http://www.w3.org/2001/04/xmlenc#aes256-cbc
4. http://www.w3.org/2001/04/xmlenc#aes192-cbc

encryptionKeyTransportAlgorithm : Sets the algorithm to encrypt the symmetric key, which is used to encrypt the data. This is an asymmetric key algorithm. Right now the only supported algorithm for this purpose is http://www.w3.org/2001/04/xmlenc#rsa-1_5.

encryptionKeyIdentifier: This will provide information on how to place key information in the out-going message. There are four ways to deliver the key information. Use one of these values.

1. Embedded
2. IssuerSerial
3. DirectReference
4. KeyIdentifier

Alright, now we have an understanding about the parameters that are required to be set. Following is a sample configuration,

    <parameter name="OutflowSecurity">
      <action>
        <items>Encrypt</items>
        <encryptionKeyTransportAlgorithm>http://www.w3.org/2001/04/xmlenc#rsa-1_5 </encryptionKeyTransportAlgorithm>
        <encryptionSymAlgorithm>http://www.w3.org/2001/04/xmlenc#aes128-cbc </encryptionSymAlgorithm>
        <encryptionPropFile>/home/guest/axis2/c/rampart/samples/keys/ahome/service.cert</encryptionPropFile>
        <encryptionKeyIdentifier>IssuerSerial</encryptionKeyIdentifier>
      </action>     
    </parameter>

If the above configurations are set, Rampart will encrypt the body of the message and place the security information inside the security header element. The outgoing message would be something like this.

In the message you can see that the contents of the body element are replaced by the EncryptedData element, which encapsulates the EncryptedAlgorithm and the CipherData elements. The EncryptedAlgorithm has the value set for the parameter encryptionSymAlgorithm or the default if you haven't. CipherData has another sub element called CipherValue, which carries the base64 encoded cipher text.

Also there are changes in the header as well. A new child element called EncryptedKey has been added to the wsse:Security header. There are four child elements in EncryptedKey.

1. EncryptionMethod
2. KeyInfo
3. CipherData
4. ReferenceList

EncryptionMethod in the header carries the asymmetric encryption algorithm used to encrypt the session key. This is the algorithm set using the parameter "encryptionKeyTransportAlgorithm". KeyInfo carries the information about the public key used to encrypt. CipherData brings the encrypted session key. The ReferenceList element tells what parts of the message are encrypted using the session key. In the above sample we encrypted the body. Thus the value of attribute URI specified in the DataReference refers to the EncryptedData element having the same value as the attribute ID. Note that there can be multiple DataReference elements if the same session key is used to encrypt multiple locations of the message.

How to Configure Rampart/C to Decrypt Messages?

Configuring Rampart to decrypt messages is a very easy approach. Similar to the OutFlowSecurity parameters, here we use InflowSecurity parameter. Inside the InflowSecurity we place following parameters.

items: Tells what is expected from incoming messages. Here we expect encrypted messages. Thus the value should be "Encrypt".

decryptionPropFile: This should be either a location to the private key in PEM format or to a pkcs12 key store. For the latter approach you might need to give a password using the password call back mechanism.

encryptionUser: If you have used a pkcs12 key store, you might need to give the correct password to extract the private key. To get the password, you need to give a user name to a password callback module. Use this parameter to specify the user name.

passwordCallBackClass: If you have used a pkcs12 key store as the decryptionPropFile, and specified an encryptionUser as described in the above section, use this parameter to locate the password callback module.

If we have configured as above, we are pretty much ready to decrypt messages. Deploy the sample service "sec_echo" available in rampart/samples/server/. Then use the sample client available in the rampart/samples/client/ to invoke the service. Please refer README files to know how to deploy the service and run the client example.

Conclusion

Apache Rampart/C is a the security module in Axis2/C engine and has extended it's support for SOAP message encryption. By simply configuring the module, Axis2/C users can encrypt SOAP messages. The next phase of Rampart is to enable support for signing and Web Services Security Policy Language.

References

1. Axis2/C Installation Guide - Building Rampart on Linux using Source Distribution
2. Axis2/C User's Guide : http://ws.apache.org/axis2/c/docs/userguide.html
3. Apache AXIOM : http://ws.apache.org/axis2/c/docs/om_tutorial.html
4. Introducing Rampart C : http://wso2.org/library/260
5. openssl : http://www.openssl.org
6. xml encryption : http://www.w3.org/TR/xmlenc-core/
7. WS-Security : http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf
8. WS-Security Policy : http://specs.xmlsoap.org/ws/2005/07/securitypolicy/ws-securitypolicy.pdf
9. Rampart/C SVN: https://svn.apache.org/repos/asf/webservices/axis2/trunk/c/rampart
10. Rampart/C Sample Code: https://svn.apache.org/repos/asf/webservices/axis2/trunk/c/rampart/samples

Author

Malinda Kaushalye Kapuruge, Software Engineer, WSO2 Inc. kaushalye at wso2 dot com