Author: kaushalye
Date: Tue Jun 19 00:20:46 2007
New Revision: 548625
URL: http://svn.apache.org/viewvc?view=rev&rev=548625
Log:
Adding a configuration guide for Rampart/C
Added:
webservices/rampart/trunk/c/xdocs/docs/configurations.html
Modified:
webservices/rampart/trunk/c/xdocs/docs/index.html
webservices/rampart/trunk/c/xdocs/navigation.xml
Added: webservices/rampart/trunk/c/xdocs/docs/configurations.html
URL:
http://svn.apache.org/viewvc/webservices/rampart/trunk/c/xdocs/docs/configurations.html?view=auto&rev=548625
==============================================================================
--- webservices/rampart/trunk/c/xdocs/docs/configurations.html (added)
+++ webservices/rampart/trunk/c/xdocs/docs/configurations.html Tue Jun 19
00:20:46 2007
@@ -0,0 +1,404 @@
+<html>
+<head>
+ <title>Rampart configurations</title>
+</head>
+
+<body lang="en-US" dir="ltr">
+<h1>Rampart configurations</h1>
+
+<h2>Engaging Rampart/C</h2>
+<p>
+Rampart/C is deployed in Axis2/C engine as an <a
href="http://ws.apache.org/axis2/c/docs/axis2c_manual.html#engaging_module";>axis2
module</a>. Just as any other module you have to "engage" the Rampart/C with
Axis2/C. All you have to do is to add following line to your descriptor
file.</p>
+
+<pre>
+ <module ref="rampart"/>
+</pre>
+<p>
+This allows Rampart/C to intercept messages exchanged via the engine and
add/verify security claims.
+You may find several examples comes with Rampart/C under samples/secpolicy/.
There are several identified scenarios that demonstrates Rampart/C features.
This includes</p>
+<ol>
+<li>Inclusion of Timestamps and verification
+<li>Inclusion of Username Tokens and authentication
+<li>SOAP message encryption/decryption
+<li>SOAP message signature/verification
+<li>Detecting replays of messages
+</ol>
+
+<h2>Security policy based configurations</h2>
+
+<p>Rampart/C configurations are based on WS Security Policy Language 1.0.
Thus, we need to specify these policies in the descriptor file. For the client
side we place them in a separate policy file, whilst in the server side we
place them within either the services.xml or the axis2.xml.</p>
+
+<h2>Client configurations</h2>
+
+<p>For client side configurations, you need to create a client repository.
This is the place where you keep axis2.xml, libraries and modules. When you
create your service client, to invoke web services, you can give the client
repository as follows.</p>
+<pre>
+svc_client = axis2_svc_client_create(env, "/my/path/to/client/repository");
+</pre>
+<p>In the axis2.xml, you need to engage Rampart/C as follows.</p>
+<pre>
+ <module ref="rampart"/>
+</pre>
+<p>Then you may place your client's policy file in the client repository.
Following is an example of a policy file.</p>
+<pre>
+<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <sp:AsymmetricBinding
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <wsp:Policy>
+ <sp:InitiatorToken>
+ <wsp:Policy>
+ <sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
+ <wsp:Policy>
+ <sp:WssX509V3Token10/>
+ </wsp:Policy>
+ </sp:X509Token>
+ </wsp:Policy>
+ </sp:InitiatorToken>
+ <sp:RecipientToken>
+ <wsp:Policy>
+ <sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
+ <wsp:Policy>
+ <sp:WssX509V3Token10/>
+ </wsp:Policy>
+ </sp:X509Token>
+ </wsp:Policy>
+ </sp:RecipientToken>
+ <sp:AlgorithmSuite>
+ <wsp:Policy>
+ <sp:Basic256Rsa15/>
+ </wsp:Policy>
+ </sp:AlgorithmSuite>
+ <sp:Layout>
+ <wsp:Policy>
+ <sp:Strict/>
+ </wsp:Policy>
+ </sp:Layout>
+ </wsp:Policy>
+ </sp:AsymmetricBinding>
+ <sp:Wss10
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <wsp:Policy>
+ <sp:MustSupportRefKeyIdentifier/>
+ <sp:MustSupportRefEmbeddedToken/>
+ <sp:MustSupportRefIssuerSerial/>
+ </wsp:Policy>
+ </sp:Wss10>
+ <sp:SignedParts
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <sp:Body/>
+ </sp:SignedParts>
+ <rampc:RampartConfig
xmlns:rampc="http://ws.apache.org/rampart/c/policy">
+ <rampc:User>Bob</rampc:User>
+ <rampc:EncryptionUser>b</rampc:EncryptionUser>
+ <rampc:PasswordType>Digest</rampc:PasswordType>
+
<rampc:PasswordCallbackClass>AXIS2C_HOME/bin/samples/rampart/callback/libpwcb.so</rampc:PasswordCallbackClass>
+
<rampc:ReceiverCertificate>AXIS2C_HOME/bin/samples/rampart/keys/ahome/bob_cert.cert</rampc:ReceiverCertificate>
+
<rampc:Certificate>AXIS2C_HOME/bin/samples/rampart/keys/ahome/alice_cert.cert</rampc:Certificate>
+
<rampc:PrivateKey>AXIS2C_HOME/bin/samples/rampart/keys/ahome/alice_key.pem</rampc:PrivateKey>
+ </rampc:RampartConfig>
+ </wsp:All>
+ </wsp:ExactlyOne>
+</wsp:Policy>
+</pre>
+
+<h2>Server configurations</h2>
+
+<p>In order to engage Rampart/C in the server side you need to add following
line to your descriptor file. This can be either services.xml (service level)
or axis2.xml (global level). </p>
+<pre>
+<module ref="rampart"/>
+</pre>
+<p>Then we place our policies within the descriptor file as follows. </p>
+<pre>
+<service name="sec_echo">
+ <parameter name="ServiceClass"
locked="xsd:false">sec_echo</parameter>
+
+ <description>
+ This is a testing service , to test the system is working or not
+ </description>
+ <module ref="rampart"/>
+ <operation name="echoString">
+ <parameter
name="wsamapping">http://example.com/ws/2004/09/policy/Test/EchoRequest</parameter>
+ </operation>
+
+ <wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
+ <!--Your policies are here-->
+ </wsp:Policy>
+</service>
+</pre>
+
+<h2>Explaining policies</h2>
+
+<p>Here we will explain how to explore the various security features available
in Rampart/C. We thoroughly recommend you to go through the samples available
in Rampart/C in order see how these configurations are combined together. </p>
+
+<h3>Using Timestamps </h3>
+
+<p>To add a Timestamp to the SOAP message, user has to specify it in the
policy by adding assertion</p>
+<pre>
+<sp:IncludeTimestamp/>
+</pre>
+<p>Beyond that user has to specify the duration of the validity of the
message. This can be done by adding following Rampart/C specific assertion.</p>
+<pre>
+<rampc:TimeToLive>360</rampc:TimeToLive>
+</pre>
+<p>Here the time duration is specified using seconds. This would add a
timestamp as follows to the security header. Note that the time difference is
360 seconds. If the message is not arrived within these limits, an error will
be thrown back.</p>
+<pre>
+<wsu:Timestamp
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
+ <wsu:Created>2007-06-18T05:10:01.448Z</wsu:Created>
+ <wsu:Expires>2007-06-18T05:16:01.448Z</wsu:Expires>
+ </wsu:Timestamp>
+</pre>
+
+<h3>Using Username tokens</h3>
+
+<p>To add a username token to the SOAP message, user has to specify three
things.</p>
+<ol>
+<li>The user
+<li>The password type
+<li>The password callback module
+</ol>
+<p>This can be done using following assertions in the policy file.</p>
+
+<pre>
+ <rampc:RampartConfig
xmlns:rampc="http://ws.apache.org/rampart/c/policy">
+ <rampc:User>Alice</rampc:User>
+ <rampc:PasswordType>Digest</rampc:PasswordType>
+
<rampc:PasswordCallbackClass>AXIS2C_HOME/bin/samples/rampart/callback/libpwcb.so</rampc:PasswordCallbackClass>
+</rampc:RampartConfig>
+</pre>
+
+<p>Also it's necessary to specify inclusion of username token in the policy as
follows.</p>
+<pre>
+<sp:UsernameToken
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Always"/>
+</pre>
+<p>Password callback modules: User passwords can be stored in different ways
for different users. Passwords can be in databases, flat files... etc.
Considering this Rampart/C provides an interface for users to write their own
password callback modules. User has to assign the password callback function as
follows.</p>
+<pre>
+rampart_callback_t* rcb = NULL;
+rcb = AXIS2_MALLOC(env->allocator, sizeof(rampart_callback_t));
+rcb->ops = AXIS2_MALLOC(env->allocator, sizeof(rampart_callback_ops_t));
+rcb->ops->callback_password = get_sample_password;/*Your password
callback function*/
+</pre>
+
+<p>The signature of the password callback function is</p>
+<pre>
+axis2_char_t* AXIS2_CALL
+get_sample_password(rampart_callback_t *rcb,
+ const axutil_env_t *env,
+ const axis2_char_t *username,
+ void param)
+</pre>
+<p>Please see the password callback sample available under
samples/callback/pwcb.c for more details.</p>
+
+<h3>SOAP message Encryption</h3>
+
+<p>Specifying encryption options are a bit complex procedure. Thus here we
wouldn't try to explain all WS Security Policy assertions. Following is a
sample policy file that is used to encrypt SOAP messages.</p>
+<pre>
+<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <sp:AsymmetricBinding
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <wsp:Policy>
+ <sp:InitiatorToken>
+ <wsp:Policy>
+ <sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
+ <wsp:Policy>
+ <sp:WssX509V3Token10/>
+ </wsp:Policy>
+ </sp:X509Token>
+ </wsp:Policy>
+ </sp:InitiatorToken>
+ <sp:RecipientToken>
+ <wsp:Policy>
+ <sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
+ <wsp:Policy>
+ <sp:WssX509V3Token10/>
+ </wsp:Policy>
+ </sp:X509Token>
+ </wsp:Policy>
+ </sp:RecipientToken>
+ <sp:AlgorithmSuite>
+ <wsp:Policy>
+ <sp:Basic256Rsa15/>
+ </wsp:Policy>
+ </sp:AlgorithmSuite>
+ <sp:Layout>
+ <wsp:Policy>
+ <sp:Strict/>
+ </wsp:Policy>
+ </sp:Layout>
+ </wsp:Policy>
+ </sp:AsymmetricBinding>
+ <sp:Wss10
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <wsp:Policy>
+ <sp:MustSupportRefEmbeddedToken/>
+ </wsp:Policy>
+ </sp:Wss10>
+ <sp:EncryptedParts
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <sp:Body/>
+ </sp:EncryptedParts>
+ <rampc:RampartConfig
xmlns:rampc="http://ws.apache.org/rampart/c/policy">
+ <rampc:User>Bob</rampc:User>
+ <rampc:EncryptionUser>b</rampc:EncryptionUser>
+
<rampc:PasswordCallbackClass>AXIS2C_HOME/bin/samples/rampart/callback/libpwcb.so</rampc:PasswordCallbackClass>
+
<rampc:ReceiverCertificate>AXIS2C_HOME/bin/samples/rampart/keys/ahome/bob_cert.cert</rampc:ReceiverCertificate>
+
<rampc:Certificate>AXIS2C_HOME/bin/samples/rampart/keys/ahome/alice_cert.cert</rampc:Certificate>
+
<rampc:PrivateKey>AXIS2C_HOME/bin/samples/rampart/keys/ahome/alice_key.pem</rampc:PrivateKey>
+ </rampc:RampartConfig>
+ </wsp:All>
+ </wsp:ExactlyOne>
+</wsp:Policy>
+</pre>
+
+<p>In the above sample file we have specified the algorithm suite to be used
for encryption. Here the algorithm suite is Basic256Rsa15. </p>
+<pre>
+ <sp:AlgorithmSuite>
+ <wsp:Policy>
+ <sp:Basic256Rsa15/>
+ </wsp:Policy>
+ </sp:AlgorithmSuite>
+</pre>
+<p>The parts to be encrypted are specified using following assertion. Here we
have specified to encrypt the whole body.</p>
+<pre>
+ <sp:EncryptedParts
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <sp:Body/>
+ </sp:EncryptedParts>
+</pre>
+<p>The receiver's certificate is specified as follows. Here you have to
specify the full path to the certificate. The public key of this certificate is
used to encrypt the content.</p>
+<pre>
+<rampc:ReceiverCertificate>AXIS2C_HOME/bin/samples/rampart/keys/ahome/bob_cert.cert</rampc:ReceiverCertificate>
+</pre>
+<p>To decrypt an incoming message you have to specify your own private as
follows. Here you have to specify the full path to the key. </p>
+<pre>
+<rampc:PrivateKey>AXIS2C_HOME/bin/samples/rampart/keys/ahome/alice_key.pem</rampc:PrivateKey>
+</pre>
+
+<h3>SOAP message Signature </h3>
+
+<p>Similar to the Encryption, to apply the signature we have to specify the
signing parts, certificates and keys. Following is a sample policy file that is
being used to sign a SOAP message. </p>
+<pre>
+<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <sp:AsymmetricBinding
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <wsp:Policy>
+ <sp:InitiatorToken>
+ <wsp:Policy>
+ <sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
+ <wsp:Policy>
+ <sp:WssX509V3Token10/>
+ </wsp:Policy>
+ </sp:X509Token>
+ </wsp:Policy>
+ </sp:InitiatorToken>
+ <sp:RecipientToken>
+ <wsp:Policy>
+ <sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
+ <wsp:Policy>
+ <sp:WssX509V3Token10/>
+ </wsp:Policy>
+ </sp:X509Token>
+ </wsp:Policy>
+ </sp:RecipientToken>
+ <sp:AlgorithmSuite>
+ <wsp:Policy>
+ <sp:Basic256Rsa15/>
+ </wsp:Policy>
+ </sp:AlgorithmSuite>
+ <sp:Layout>
+ <wsp:Policy>
+ <sp:Strict/>
+ </wsp:Policy>
+ </sp:Layout>
+ </wsp:Policy>
+ </sp:AsymmetricBinding>
+ <sp:Wss10
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <wsp:Policy>
+ <sp:MustSupportRefKeyIdentifier/>
+ <sp:MustSupportRefEmbeddedToken/>
+ <sp:MustSupportRefIssuerSerial/>
+ </wsp:Policy>
+ </sp:Wss10>
+ <sp:SignedParts
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <sp:Body/>
+ </sp:SignedParts>
+ <rampc:RampartConfig
xmlns:rampc="http://ws.apache.org/rampart/c/policy">
+ <rampc:User>Bob</rampc:User>
+ <rampc:EncryptionUser>b</rampc:EncryptionUser>
+ <rampc:PasswordType>Digest</rampc:PasswordType>
+
<rampc:PasswordCallbackClass>AXIS2C_HOME/bin/samples/rampart/callback/libpwcb.so</rampc:PasswordCallbackClass>
+
<rampc:ReceiverCertificate>AXIS2C_HOME/bin/samples/rampart/keys/ahome/bob_cert.cert</rampc:ReceiverCertificate>
+
<rampc:Certificate>AXIS2C_HOME/bin/samples/rampart/keys/ahome/alice_cert.cert</rampc:Certificate>
+
<rampc:PrivateKey>AXIS2C_HOME/bin/samples/rampart/keys/ahome/alice_key.pem</rampc:PrivateKey>
+ </rampc:RampartConfig>
+ </wsp:All>
+ </wsp:ExactlyOne>
+</wsp:Policy>
+</pre>
+<p>To specify which parts of the message to be signed use following assertion.
Here we have asked to sign the whole body.</p>
+<pre>
+ <sp:SignedParts
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <sp:Body/>
+ </sp:SignedParts>
+</pre>
+<p>Optionally if you need to sign a header you may use.</p>
+<pre>
+<sp:SignedParts
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <sp:Header Namespace="http://www.w3.org/2005/08/addressing"/>
+</sp:SignedParts>
+</pre>
+<p>The algorithm suite to be used for signature is specified as follows. Same
as encryption.</p>
+<pre>
+ <sp:AlgorithmSuite>
+ <wsp:Policy>
+ <sp:Basic192Rsa15/>
+ </wsp:Policy>
+ </sp:AlgorithmSuite>
+</pre>
+
+<h3>Replay detection </h3>
+
+<p>To detect replay attacks, Rampart/C has it's own Replay Detection module.
This module detects if the message is a replay of a previous. By default the
RD(Replay Detection) module is turned OFF. All you have to do turn it ON is to
add </p>
+<pre>
+<rampc:ReplayDetection><b>N</b></rampc:ReplayDetection>
+</pre>
+<p>policy assertion to your descriptor file. Here N is the number of records
that must be kept in memory. Greater the value of N is, greater the chance of
detecting a replays. Rampart/C keeps records of messages in a list and process
them on arrival of a new message. A record is the concatenation of message
id(wsa:msg-id) and the value of the timestamp.</p>
+<p>
+RECORD-ID = MSG-ID + TIMESTAMP
+</p>
+<p>The message ID is considered to be unique to a particular message. But for
this, user needs to have the addressing module engaged(which comes with
axis2/c). This is NOT a MUST but is the RECOMONDED approach. One can just
survive with only the timestamp. But shouldn't forget the chance of generating
two message at the same time, which definitely make them suspicious as a
replay.</p>
+
+<h2>Rampart/C samples</h2>
+
+<p>There are number of samples available under Rampart/C samples.
+Following is a brief description of Rampart/C samples</p>
+<p>
+<b><i>Service :</b> samples/services/sec_echo</i><br>
+The security enabled service. Depends on deployed security policy scenario.</p>
+<p>
+<b><i>Client:</b> samples/client/sec_echo</i><br>
+The client to send secured SOAP messages. Depends on deployed security policy
scenario.</p>
+<p>
+<b><i>Security policies:</b> samples/secpolicy/scenarioX</i><br>
+Provides several identified scenarios to demonstrate features of Rampart/C.
+Please read the README file under samples/secpolicy to learn more about
them.</p>
+<p>
+<b><i>Callbacks :</b> samples/callback</i><br>
+To retrieve passwords for a particular user, Rampart/C uses password callback
mechanism.
+Such callback modules can be plugged into Rampart/C by defining them in the
policy assertions.
+The sample shows how to write a simple password callback module.</p>
+<p>
+<b><i>Credential Provider:</b> samples/credential_provider</i><br>
+In the client side it's possible to give a username/password pair to the
client, using a credential_provider.
+Similar to Callbacks, these can too plugged into Rampart/C by defining them in
the policy assertions.
+The sample shows how to write a simple credentials provider.</p>
+<p>
+<b><i>Authentication Provider :</b> samples/authn_provider</i><br>
+In the server side, in order to validate a usernametoken in more application
specific way, an authentication module can be used.<br>
+The authentication module gets both the username and the password and returns
a status code back to Rampart/C.
+The sample shows how to write a simple authentication provider.</p>
+<p>
+<b><i>Keys :</b> samples/keys</i><br>
+All the certificates, private keys and key stores that are used by samples,
placed here.</p>
+<p>
+<b><i>Data :</b> samples/data</i><br>
+Data files that are used by samples, placed here.
+</p>
+</body>
+</html>
Modified: webservices/rampart/trunk/c/xdocs/docs/index.html
URL:
http://svn.apache.org/viewvc/webservices/rampart/trunk/c/xdocs/docs/index.html?view=diff&rev=548625&r1=548624&r2=548625
==============================================================================
--- webservices/rampart/trunk/c/xdocs/docs/index.html (original)
+++ webservices/rampart/trunk/c/xdocs/docs/index.html Tue Jun 19 00:20:46 2007
@@ -20,6 +20,10 @@
<li><a href="rampartc_manual.html">Rampart/C Manual</a></li>
</ul>
+<h2>Configurations</h2>
+<ul>
+ <li><a href="configurations.html">Configuration Guide</a></li>
+</ul>
<h2>Additional References</h2>
<ul>
<li><a href="http://ws.apache.org/axis2/c/index.html";>Apache Axis2/C</a></li>
Modified: webservices/rampart/trunk/c/xdocs/navigation.xml
URL:
http://svn.apache.org/viewvc/webservices/rampart/trunk/c/xdocs/navigation.xml?view=diff&rev=548625&r1=548624&r2=548625
==============================================================================
--- webservices/rampart/trunk/c/xdocs/navigation.xml (original)
+++ webservices/rampart/trunk/c/xdocs/navigation.xml Tue Jun 19 00:20:46 2007
@@ -9,6 +9,7 @@
<item name="Documentation" href="docs/index.html">
<item name="Installation Guide"
href="docs/installationguide.html"/>
<item name="Rampart/C manual" href="docs/rampartc_manual.html"/>
+ <item name="Configurations guide"
href="docs/configurations.html"/>
</item>
<item name="Get Involved" href="lists_issues.html">
<item name="Mailing Lists & Issue Tracking"
href="lists_issues.html"/>
