Rampart/C is the security module of the Apache Axis2/C web services engine. The following tutorial by Kaushalye Kapuruge will guide you on how to configure Rampart/C in order to satisfy different security requirements in SOAP message exchanges.
Introduction
Sometimes Rampart/C is used to provide the confidentiality for the messages exchanged and sometimes for user authentication etc. Depending on these different requirements, different configurations are needed to be set up both in the client and the server. Here our discussion will be limited only for the essential details that are necessary to understand these configurations.
Table of Content
- Where to define configurations [0]
- How to enable timestamps [0]
- How to add a Username token [0]
- How to encrypt [0]
- How to sign [0]
- How to verify a Timestamp [0]
- How to verify a Usernametoken [0]
- How to decrypt [0]
- How to verify a signature [0]
- How to setup the protection order [0]
- How to enable replay detection [0]
- How to write a password callback module [0]
- How to write an authentication module [0]
This is a sample client policy file [0]
In the server side we define our policy assertions in the services.xml. The services.xml is in the same directory where you deposited the services module, in which you keep your business logic. This is a sample services.xml file [0]
These two configurations files are a MUST to enable WS-Security. Rampart/C behaves according to the assertions (configuration metadata) defined in those two. This behavior is two-folds. As per the assertions defined in these files,
- Rampart/C builds the message.
- Rampart/C processes/verifies the message.
In the following set of "How to" topics we will discuss above two behaviors in Rampart/C. But in order to understand WS-Security Policy we recommend you to refer the WS-Security Policy specification. [1] Note that some assertions discussed here are alien to the specification. Those are specific to the Rampart/C, and defined in the name-space of rampc="http://ws.apache.org/rampart/c/policy. These assertions are to provide Rampart/C configurations, that cannot be achieved only with the assertions defined in the WS-Security Policy specification. For example to define where to locate the private key, we use
<rampc:PrivateKey>/path/to/private/key/my_key.pem</rampc:PrivateKey>
Algorithm to be used [1] section under How to Encrypt [1] to see what values should be mentioned. All the algorithm suites that are supported right now, uses the RSA-SHA1 algorithm (http://www.w3.org/2000/09/xmldsig#rsa-sha1) for signing.
User's private key is used to sign the message is specified as follows.
<rampc:PrivateKey>/your/path/to/private/key/my_key.pem</rampc:PrivateKey>
Also it's important to send the information about the certificate, which will be needed for the verification process.
<rampc:Certificate>path/to/own/certificate/cert.cert</rampc:Certificate>
Which parts to be signed in the SOAP message is determined by the sp:SignedParts assertion. User may specify to sign the body of the message and/or SOAP headers.
<sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body/>
<sp:Header Namespace="http://www.w3.org/2005/08/addressing"/>
</sp:SignedParts>
In the above example the user needs to sign the message body and all the addressing headers.
Note that if timestamp is enabled, Rampart/C signs the Timestamp header element too.
Apache Rampart/C [2]
Author
Malinda Kaushalye Kapuruge is a Senior Software Engineer, WSO2 Inc. kaushalye at wso2 dot com