[Ws Wiki] Update of "FrontPage/WsFx/wssec" by WernerDittmann

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Ws Wiki" for change notification.

The following page has been changed by WernerDittmann:
http://wiki.apache.org/ws/FrontPage/WsFx/wssec

New page:
= General remarks and caveats =

First of all some hints and caveats if you plan to use WSS4J together 
with a SOAP implementation:

''Before you use WSS together with SOAP become familiar with the SOAP implementation you use.''

Most people use Axis together with WSS4J because WSS4J provides Axis handlers to simplify the setup and deployment of Web Service security. In this case it is necessary to understand the basic concepts of Axis.

The concept of handlers:
 * What is an Axis handler? 
 * What is the concept behind the handlers and handler chains? 
 * What is meant with a pivot?

Deployment and deployment files:
 * What are deployment files and their contents? 
 * Where to put deployment files? 
 * Why/when do you need deployment files for clients? 
 * Where to place these files?

Static versus dynamic calls:
 * What is the difference between dynamic and static calls? 
 * What are stubs and proxies? 
 * How to setup an Axis client with/without deplyment files?
 * How do you setup handler chains if you use dynamic calls?

If you are familiar with these concepts then you may go on and use and deploy additional software that rely on these Axis concepts. Well, you don't need to understand every detail of the concepts, but a solid know-how is always a good strating point.

== Overall Structure of WSS4J for Signature and Encryption ==

The following text describes the WS Security part of WSS4J, not the part of secure conversation and reliable messaging.

=== The two parts of WSS4J WS-Security ===

In general WSS4J (WS Security) falls into two parts
 * one part that is independent of Axis or any other SOAP implementation. This part handles all the necessary signing, encryption, certificate stuff. This part makes heavy use of the Apache XML security lib (xmlsec), also quite some DOM is involved because WSS4J needs to re-create the SOAP message that was created by the SOAP implementation firsthand.
 * the second part consists of Axis handlers that plugin into the message path both on the client and the server side. The Axis handler in turn call functions of the independent part of WSS4J. Another handler is also available that is compliant to JAX-RPC and thus is not bound to Axis directly.

=== The message flow of a request ===

Thus the message flow is as follows (client part):
{{{
Application
   |
   |-> Axis kernel
           |
           |-> WSS4J handler (Axis/JAX-RPC)
                    |
	            |<-> WSS4J sign/encrypt methods
           |<------ |	      
           |
           v
         wire
}}}
Between the Axis kernel and the WSS4J Axis handler there may be some other handlers.

However, the security handler is
 * usually last one in the request flow and first one in the response flow on client side 
 * usually the first one in the request flow and the last one in the  response flow on the server side

Signed parts of the SOAP request message _must_ not be altered if during the follwing request processing. In addition it is somewhat difficult to modify the message after it was encrypted.

== Step to enhance your webservice with Security ==
 
To develop a procduct that use WS Security I would perform several steps:

 1.#0 Step 0: get a good understanding of you SOAP implementation (see remarks above)
 1. Then develop and set-up the Webservice (client and Server) __without__ any security. Then test them to have a stable basis. In particular error cases.
 1. define an installation procedure, e.g. using Ant or scripts, to reliably install the product. This includes to copy all libraries, classes, jars, etc to their right places. 1. Then re-check the classpathes used by your client and server. Many problems just pop up because of a wrong classpath.
 
After this works flawlessly then you can introduce security on top. WSS4J was designed that you can introduce security to an existing Webservice environment without changing existing source code. 

For Axis this means that you need to modify your deployment files on the  server, create and/or modify the client's deployment files.
 
Before you set-up your required security, you need to think about which type of security your webservice needs:

 * Signature only?
 * Signature with encryption?
 * Username/Password, clear text or digested?
 * etc.

If your security requirements are such that you need to sign and/or encrypt your SOAP requests, then you should ask the following questions:
 
 * Do we require ''officially'' signed certificates?
 * Which Certificate Authorization (CA) do you select? 
 * What about your certificate Infrastructure at all?

After this step you can create the required security environment

 * If you need signature and/or encryption you usually need to generate or get certificates, both for client and server, set up the certificate store.

 * Also a customized password callback class is usually necessary. 

 * Put the required libraries (WSS4J lib, xmlsec, Bouncy Castle, etc.) in their right places, if necessary adapt the classpath, make sure all resources can be found. This includes the deployment files, certificate store both for client and server
 
After all this was done do some regression without enabling security in the deployment files:
 * Does the webservice it still work? 
 * Do the added libraries, certificate store, modified classpath, or other resources interfere with the webservice?
 
Now you can enable security. Do do so, insert the required statements in the deployment files (both client and server side). Do one step after another, e.g. first perform Signature only, then, if you need it, switch on Encryption. 

'''Please''' refer to the Javadoc for a more detailed description of the deployment parameters that control the WSS4J Axis security handlers. The Axis directory of WSS4J where the Axis specific handlers are located also contains some introduction.
 
If the security set-up works it comes to the most boring part:
testing. You need to think about test cases for your webservice. You need to have test cases that generate errors, use wrong certificates, etc. to make sure the security enviroment is stable.
 
Well, the rest is as usual for a normal product: make it simple to
install, operate, and have success in selling it :-) .