| <html> |
| <head> |
| <title>Manual</title> |
| <meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| </head> |
| |
| <body lang="en-US" dir="ltr"> |
| <h2>Preamble</h2> |
| |
| <p style="margin-bottom: 0in">This document is intended to be a reference |
| manual for <a href="http://ws.apache.org/rampart/c">Apache Rampart/C</a>.</p> |
| <p>For further details on Axis2/C please refer the <a href="http://ws.apache.org/axis2/c/docs/axis2c_manual.html">Apache Axis2/C manual</a></p> |
| |
| <h2>Simplified Architecture</h2> |
| |
| <p>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 <a |
| href="http://ws.apache.org/axis2/c/docs/om_tutorial.html">Apache AXIOM</a> and |
| Axis2-Util libraries. OpenSSL is used as the crypto library in |
| OMXMLSecurity.</p> |
| <img src="files/rampart_simple_archi.png"> |
| |
| <h2>Interface with Axis2/C</h2> |
| |
| <p>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. </p> |
| |
| <p>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.</p> |
| |
| <h2>Inside Rampart/C</h2> |
| Following is a detailed architecture diagram of Rampart/C |
| <p><img src="files/rampart_archi.png"></p> |
| |
| <h3>Rampart Engine</h3> |
| |
| <p>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.</p> |
| |
| <h3>Processors and Builders</h3> |
| |
| <p>Rampart/C processes incoming SOAP message using it's processors. There are |
| two processors in Rampart/C.</p> |
| <ol> |
| <li><strong>Security Header Processor</strong> : Processes security header |
| of the incoming message and make decisions upon security claims and the |
| security policies.</li> |
| <li><strong>Token Processor</strong> : Processes token claims such as |
| binary security token.</li> |
| </ol> |
| Similar to processes, Rampart/C uses two builders that builds outgoing |
| messages. |
| <ol> |
| <li><strong>Security Header Builder</strong> : Builds Security headers of an outgoing |
| message depending on security policies.</li> |
| <li><strong>Token Builder</strong> : Builds token claims such as binary security token.</li> |
| </ol> |
| 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. |
| |
| <h3>Policy</h3> |
| |
| <p>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. <br> |
| </p> |
| |
| <p>Rampart/C is configured using policy assertions defined in WS-Security |
| Policy specification (1.1 or 1.2). These policies are defined in policy.xml files. |
| The client side policies are defined in a seperate policy.xml file located in the client's repository. |
| The service's policies are defined in the services.xml file. |
| |
| <h3>Rampart utilities</h3> |
| |
| <p>Rampart utilities groups different entities that cater for different |
| purposes. Following is a brief description of major components inside |
| utilities</p> |
| <ul> |
| <li><strong>Rampart context:</strong> Keeps configurations for Rampart/C. |
| This includes certificates, keys, passwords, policies etc.</li> |
| <li><strong>UsernameToken: </strong>Provides functionalities to |
| build/process a UsernameToken.</li> |
| <li><strong>TimestampToken: </strong>Provides functionalities to |
| build/process a TimestampToken.</li> |
| <li><strong>Authentication provider: </strong>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.</li> |
| <li><strong>Credentials provider: </strong>An interface for a credentials |
| module to be plugged in. Users can provide custom user name/password |
| pairs to build user name tokens.</li> |
| <li><strong>Password callbacks: </strong>An interface for users to provide |
| password for a given user name.</li> |
| </ul> |
| |
| <h2>OMXMLSecurity</h2> |
| |
| <p>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.</p> |
| <ol> |
| <li><strong>XML-Encryption / Decryption:</strong> 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.</li> |
| <li><strong>XML-Signature / Verification:</strong> Allows one or more part |
| of an XML document to be signed using a private key. Also allows these |
| signed parts to be verified.</li> |
| <li><strong>Key management:</strong> 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.</li> |
| <li><strong>Canonicalization:</strong> Provide Canonicalization (C14N) |
| transform support.</li> |
| <li><strong>Creating/Processing tokens:</strong> There are number of XML |
| elements that are introduced by security specifications. The token base |
| in OMXMLSecurity provides functionalities to create/process such |
| elements.</li> |
| </ol> |
| <p>Following diagram shows the architecture of OMXMLSecurity</p> |
| <img src="files/oxs_archi.png"> |
| |
| |
| |
| <p style="margin-bottom: 0in">Please send your feedback to the Apache Axis2/C |
| developer mailing list (<a |
| href="mailto:rampart-c-dev@ws.apache.org">rampart-c-dev@ws.apache.org</a>). Subscription |
| details are available on the <a |
| href="http://ws.apache.org/rampart/c/lists_issues.html">Rampart site</a>.</p> |
| |
| |
| </body> |
| </html> |