2007/06/17
17 Jun, 2007

The Insider's Guide to Apache Rampart/C and OMXMLSecurity

  • Malinda Kaushalye
  • Tech-lead - WSO2

IntroductionRampartC

Rampart/C gives an Apache Axis2/C user a deployable module that can be used to secure SOAP messages. To get the maximum out of Rampart/C, it is vital to know how its components are designed. If required, you can extend the capabilities of Rampart/C, or customize Rampart/C according to the language platform. OMXMLSecurity is the XML Security library written on top of AXIOM used by Rampart/C. Let's take a look at the architecture of Rampart/C and OMXMLSecurity.

Background

Rampart/C and WS Security

The motivation behind the implementation of Rampart/C is to let Axis2/C users secure their SOAP messages as per the WS-Security Specification 1.0 [1]. With a little effort in the configuration setup, Axis2/C users can fulfill their SOAP message security requirements such as confidentiality, integrity, and authentication. The WS-Security specification provides a number of mechanisms to secure SOAP messages such as Encryption, Signature, UsernameToken, and Timestamps.

Rampart/C and WS Security Policy

Rampart configurations are based on security policy assertions as per the WS-Security Policy specification 1.1[2]. The specification allows users to define the requirements and constraints of their Web services. For example, if the message needs to be encrypted and signed etc., Rampart/C understands such policy assertions that are defined in configuration files. A violation of such a policy would result in a SOAP fault.

Rampart/C Features

  1. SOAP message encryption: Allows different parts of a SOAP message to be encrypted to maintain the confidentiality of the SOAP message.
  2. SOAP message signature: Allows different parts of a SOAP message to be signed to maintain the integrity of the SOAP message.
  3. UsernameToken support: Allows users to send Username tokens for authentication purposes as per the Web services security username token profile.
  4. Timestamps: Allows users to add timestamps to their SOAP messages in order to ensure the freshness.
  5. Security policy support: Allows users to express their security related requirements and constraints.

Simplified Architecture


In a very simple view, Rampart/C consists of a core module and packages related to WS-Security and WS-Security Policy. For XML-Encryption and Signature, Rampart/C uses OMXMLSecurity. Both Rampart/C and OMXMLSecurity use Apache AXIOM [5] and Axis2-Util libraries. OpenSSL is used as the crypto library in OMXMLSecurity.

Interface with Axis2/C

The interface between Rampart/C and the Apache Axis2/C engine is the Rampart module called mod_rampart. The module has two handlers, one for the inflow and the other for the outflow of the Axis2/C engine. Rampart/C directs messages to its other components for further security related processing using these handlers.

Handlers are a way of extending capabilities of the core engine. Once the Axis2/C engine calls the invoke() method of the handler, the module can do the necessary processing over the SOAP message. Rampart/C use this mechanism to build/process security related SOAP headers.

Inside Rampart/C

Rampart Engine

The Rampart engine is the heart of Rampart/C. It sets security policies that define the behavior of Rampart/C message processing. These policies are usually read from a selected policy.xml file depending on the message flow, which contains a set of policy assertions.

Processors and Builders

Rampart/C processes incoming SOAP messages using its processors. There are two processors in Rampart/C.

  1. Security Header Processor : Processes the security header of the incoming message and make decisions upon security claims and the security policies.
  2. Token Processor : Processes token claims such as the binary security token.

Similar to processors, Rampart/C uses two builders that build outgoing messages.

  1. Security Header Builder : Builds security headers of an outgoing message based on the security policies.
  2. Token Builder : Builds token claims such as the binary security token.
These builders and processors assemble the other components (such as encryption, signature, and UsernameToken) together. Decisions taken in these processors will result in further processing of the message or throwing of a SOAP fault.

Policy

The policy module of Rampart/C acts as the configuration module in Rampart/C. The policy module has a set of models that represents assertions. Also, there are a set of builders that builds these models.

Rampart/C is configured using policy assertions defined in the WS-Security Policy specification 1.1. These policies are defined in policy.xml files. There are two policy files for a single Rampart configuration.

  1. incoming-secpolicy.xml
  2. outgoing-secpolicy.xml
The former defines how an outgoing message is secured, whilst the latter defines how the incoming message should be secured. Apart from the assertions mentioned in the specification, Rampart/C uses its own assertions. (For example, to specify keys and certificates.) There are a number of such sample policy files under rampart/samples/secpolicy.

Rampart Utilities

Rampart Utilities groups different entities that cater for different purposes. The following is a brief description of the main components inside Utilities.

  • Rampart context: Keeps configurations for Rampart/C. This includes certificates, keys, passwords, policies, etc,.
  • UsernameToken: Provides the functionalities to build/process a UsernameToken.
  • TimestampToken: Provides the functionalities to build/process a TimestampToken.
  • Authentication provider: An interface for authentication modules to be plugged into Rampart/C. This allows users to define their own rules for processing user name/passwords.
  • Credentials provider: An interface for a credentials module to be plugged into Rampart/C. Users can provide custom user name/password pairs to build user name tokens.
  • Password callbacks: An interface for users to provide a password for a given user name.

OMXMLSecurity

For XML cryptographic purposes, Rampart/C uses OMXMLSecurity, which is a library written on top of Apache AXIOM. If a particular SOAP message has to be encrypted or signed, Rampart/C gets the work done through the OMXMLSecurity. The functionalities of OMXMLSecurity are as follows.

  1. XML-Encryption/Decryption: Includes symmetric and asymmetric encryptions. Usually data is encrypted using a symmetric key (or a session key) which is again encrypted using an asymmetric algorithm using a public key.
  2. XML-Signature/Verification: Allows one or more parts of an XML document to be signed using a private key. Also allows these signed parts to be verified.
  3. Key management: Provides an interface that facilitates a series of functions to load X509 certificates, private keys, etc,. Keys might be stored in PEM files, PKCS12 key stores or can be in string buffers.
  4. Canonicalization: Provides canonicalization (C14N) transform support.
  5. Creating/Processing tokens: There are number of XML elements that are introduced by security specifications. The token base in OMXMLSecurity provides the necessary functionalities to create/process such elements.

OMXMLSecurity Architecture

The above diagram shows the essential components that form the OMXMLSecurity library.

The Encryption Module

The encryption module has been implemented in two layers to separate the XML encryption from the data encryption. XML encryption does XML related processing such as serialization/de-serialization of XML elements, building necessary XML tokens, etc,. Also it renders special support for key encryption that's required by Rampart/C. The user has to create a context in which the necessary parameters for the encryption such as the algorithm is specified. Then a suitable function is called for either encryption or decryption.

The Signature Module

The main functionalities in the signature module are to sign a node and verify an XML digital signature. Apart from that, it helps the users to process signature nodes and their references. For signing, a user has to create a signature context. A signature context keeps information that is related to one signature step. One signature step can have multiple signature parts. (In XML signature, if you need to sign multiple parts of a message, you have to create digests of each part and group these digests into on node called<ds:SignedInfo>, which will be the actual node that is subjected to signing). These signature parts correspond to portions of the message that need to be signed. One signature part keeps the transformations required and the digest method.

In the verification process too, the user has to create a signature context and call the verify function. This time the signature context does not need to be populated, as it is done by scanning the node by the signature module itself.

Keys Manager

The Keys Manager module provides an easy to use interface for OMXMLSecurity users to load certificates and keys. The keys manager supports keys/certificates in the following formats.

  1. PKCS#12 key stores
  2. PEM files
  3. Base64 encoded DER key buffers

OpenSSL Wrappers

The OpenSSL library provides various routines that implement the basic cryptographic functions. The openSSL wrapper layer gives a comprehensive API, hiding the complex routines that can be used for cryptographic purposes of OMXMLSecurity. This includes,

  1. Encrypt/Decrypt data
  2. Sign/Verify data
  3. Create digests
  4. Load X509 certificates
  5. Load private keys
  6. Load PKCS#12 key stores

Transformations

Different transformations have to be applied to the XML signature before creating the digital signature. OMXMLSecurity allows users to set their own transformations for signature parts. A transform structure is defined for these purposes. These transformations store their input/output forms and the behavior. A transform factory is implemented for users to retrieve predefined transforms such as exclusive canonicalization. A signature part may contain more than one transformation and will be applied in the order they are set.

Tokens

In order to build/process XML elements that are required for XML-Encryption and XML-Signature, a token base is implemented. This token base covers all the AXIOM specific details in the process of creating tokens. For example if it's required to create the <ds:KeyInfo> element, simply call the

oxs_token_build_key_info_element(env, parent)

Here the parent is the node that takes KeyInfo as a child.

Utilities

The utility package contains a number of utility objects that are required for major functionalities of the library. This represents string buffers, keys, certificates, various contexts, and error representation.

The error representation in OMXMLSecurity, known as "oxs_error" defines the types of errors (e.g., Encryption failure, Signature failure, Unsupported Algorithm, etc.) that can occur. Once executed, it gives the error location, and type of error with the reason for the error.

A buffer represents a storage to keep data, and expands itself if the data size exceeds the maximum limit. This is quite useful to handle binary data.

Conclusion

Apache Rampart/C is the security module of the Apache Axis2/C engine. It uses OMXMLSecurity as the XML-Security library. Rampart/C's feature list includes support for UsernameTokens, Timestamps, Encryption, and Digital signature as per the WS-Security specification. Its configurations are based on the WS-Security policy. In the future, it is expected to support other security related specifications such as SAML, WS-Trust and WS-Secure conversation.


References

[1] WS-Security Specification 1.0- https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

[2] WS-Security Policy specification 1.1- https://specs.xmlsoap.org/ws/2005/07/securitypolicy/ws-securitypolicy.pdf

[3] Apache Rampart/C- https://wso2.org/projects/rampart/c

[4] Apache Axis2/C - http://ws.apache.org/axis2/c

[5] PEM - https://en.wikipedia.org/wiki/Base64#Privacy-Enhanced_Mail_.28PEM.29

[6] PKCS#12 - https://www.openssl.org/docs/apps/pkcs12.html

Author

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

 

About Author

  • Malinda Kaushalye
  • Tech-lead
  • WSO2 Inc.