Preamble
This document is intended to be a reference
manual for Apache Rampart/C.
For further details on Axis2/C please refer the Apache Axis2/C manual
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 uses Apache AXIOM and
Axis2-Util libraries. OpenSSL is used as the crypto library in
OMXMLSecurity.
Interface with Axis2/C
The interface between Rampart/C and Apache Axis2/C engine is the Rampart
module called mod_rampart. The module has two handlers, one for the inflow
and another for the outflow of the Axis2/C engine. Rampart/C directs messages
to it's 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
Following is a detailed architecture diagram of Rampart/C
Rampart Engine
Rampart engine is the heart of Rampart/C. It sets security policies that
defines 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 message using it's processors. There are
two processors in Rampart/C.
- Security Header Processor : Processes security header
of the incoming message and make decisions upon security claims and the
security policies.
- Token Processor : Processes token claims such as
binary security token.
Similar to processes, Rampart/C uses two builders that builds outgoing
messages.
- Security header builder : Builds Security headers of an outgoing
message depending on security policies.
- Token Builder : Builds token claims such as binary security token.
These builders and processes assemble other components such as encryption,
signature, UsernameToken together. Decisions are taken in these processes
would 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 set of builders that builds these models.
Rampart/C is configured using policy assertions defined in WS-Security
Policy specification 1.1. These policies are defined in policy.xml files.
There are two policy files for a single Rampart configuration.
- incoming-secpolicy.xml
- 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 it's own assertions. (e.g. To
specify keys and certificates). There are number of such sample policy files
under rampart/samples/secpolicy.
Rampart utilities
Rampart utilities groups different entities that cater for different
purposes. Following is a brief description of major components inside
utilities
- Rampart context: Keeps configurations for Rampart/C.
This includes certificates, keys, passwords, policies etc.
- UsernameToken: Provides functionalities to
build/process a UsernameToken.
- TimestampToken: Provides functionalities to
build/process a TimestampToken.
- Authentication provider: The interface for
authentication modules that can 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 in. Users can provide custom user name/password
pairs to build user name tokens.
- Password callbacks: An interface for users to provide
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 needs to
be encrypted or signed, Rampart/C get the work done through the
OMXMLSecurity. Following are the functionalities of OMXMLSecurity.
- XML-Encryption / Decryption: This 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.
- XML-Signature / Verification: Allows one or more part
of an XML document to be signed using a private key. Also allows these
signed parts to be verified.
- Key management: To load X509 certificates, Private
keys etc, the Key management interface provide a series of functions.
Keys might be stored in PEM files, PKCS12 key stores or can be in string
buffers.
- Canonicalization: Provide Canonicalization (C14N)
transform support.
- Creating/Processing tokens: There are number of XML
elements that are introduced by security specifications. The token base
in OMXMLSecurity provides functionalities to create/process such
elements.
Following diagram shows the architecture of OMXMLSecurity
Please send your feedback to the Apache Axis2/C
developer mailing list (rampart-c-dev@apache.org). Subscription
details are available on the Rampart site.