<!-- <!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" | |
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | |
--> | |
<html> | |
<head> | |
<title>Web Service Security classes for message creation</title> | |
<!-- | |
@(#)Web Service Security classes for message creation | |
/* | |
* Copyright 2003-2004 The Apache Software Foundation. | |
* | |
* Licensed under the Apache License, Version 2.0 (the "License"); | |
* you may not use this file except in compliance with the License. | |
* You may obtain a copy of the License at | |
* | |
* http://www.apache.org/licenses/LICENSE-2.0 | |
* | |
* Unless required by applicable law or agreed to in writing, software | |
* distributed under the License is distributed on an "AS IS" BASIS, | |
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
* See the License for the specific language governing permissions and | |
* limitations under the License. | |
* | |
*/ | |
--> | |
</head> | |
<body bgcolor="white"> | |
The package provides classes to create messages that are compliant to the | |
OASIS Web Service Security specifications. | |
<p/> | |
The OASIS WSS specifications define a number of features and it is possible | |
to combine them in several ways. The WSS4J classes already support | |
a large number of WSS features and their combinations. | |
<a href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss"> | |
Here</a> are the WSS specifications. | |
<p/> | |
Currently this package contains two sets of classes that provide the same | |
or similar functionality. | |
<ul> | |
<li>The old classes, named WSAdd*, WSEncryptBody, WSSignEnvelope, WSBaseMessage. | |
The usage of these classes is depreciated.</li> | |
<li>The new, refactored classes. Their names start with the prefix <e>WSSec</e>. | |
</ul> | |
<h3>How to use the WSSec* classes</h3> | |
The new refactored classes follow the same usage pattern. | |
<ol type="1"> | |
<li>Create an object for the required security element, for example a | |
<code>WSSecSignature</code>. | |
</li> | |
<li>Set the required fields using setter methods, for example user name, signature | |
algorithm, etc. | |
</li> | |
<li>After the fields are set call <code>prepare(...)</code>. This initializes the internal | |
structures, gets the required data like X509 tokens, etc. | |
</li> | |
<li>After preparation you may do security element specific functions, for example add | |
data refernces that should be included in the signature. You can also add the element to | |
the <code>WSSecHeader</code> at this time (adding to the security header can be done at any | |
time after <code>prepare(...)</code>). See the documentation of the various classes what is | |
available. | |
</li> | |
</ol> | |
In contrast to the old classes the handling of the security header is not longer | |
implicitly performed. To provide better flexibilty the class <code>WSSecHeader</code> | |
deals with the security header. | |
<p/> | |
The new structure of the classes provide a much more flxible handling of the actions | |
performed by the classes. This enhanced flexibility enables a precise control of | |
the placement of security elements in the security header and a much better control | |
which elements to sign or to encrypt. | |
<p/> | |
This code snippet shows how to setup a Signature element: | |
<pre> | |
/* | |
* Explicit security header handling. The WSSecHeader object | |
* remains the same for all elements that shall go into this | |
* security header. Thus you usually need to created one | |
* WSSecHeader object only. | |
*/ | |
WSSecHeader secHeader = new WSSecHeader(); | |
secHeader.insertSecurityHeader(doc); | |
WSSecSignature builder = new WSSecSignature(); | |
builder.setUserInfo("username", "password"); | |
builder.setKeyIdentifierType(WSConstants.ISSUER_SERIAL); | |
Document doc = getSOAPEnvelope(); | |
builder.prepare(doc, crypto, secHeader); | |
/* | |
* Set parts to sign | |
*/ | |
Vector parts = new Vector(); | |
WSEncryptionPart encP = new WSEncryptionPart(localName, namespace, "Content"); | |
parts.add(encP); | |
/* | |
* Add the references to include into Signature. This can be done multiple | |
* times. | |
*/ | |
builder.addReferencesToSign(parts, secHeader); | |
/* | |
* Add the Signature now to the security header | |
*/ | |
builder.prependToHeader(secHeader); | |
/* | |
* There maybe a BST to prepend it in front of the Signature according to | |
* strict layout rules. | |
*/ | |
builder.prependBSTElementToHeader(secHeader); | |
/* | |
* Before calling computeSignature make sure all elements to sign are | |
* available in the document (SOAP Envelope) | |
*/ | |
builder.computeSignature(); | |
</pre> | |
Each new class also contains a <code>build()</code> method that is similar to the | |
<code>build()</code> method in the old classes. Thus, if the flexibilty is not | |
required you may use this method for convenience. | |
<h3>Each top level security element has wsu:Id or plain Id attribute</h3> | |
The <code>prepare()</code> method autmatically generates an Id string for each new | |
element and sets the wsu:Id or plain Id attribute. Which type | |
of Id to use is determined by the security element. The <e>EncryptedKey</e> and <e>Signature</e> | |
elements have a plain Id according to the W3C specifications, elements defined by | |
the OASIS WS Security specifications contain a wsu:Id. | |
<p/> | |
Each <code>WSSec*</code> class has a <code>getId()</code> that returns the id strig | |
regardless if its qualified or not. | |
<p/> | |
The security processing uses these Id to identify each top level security element to | |
provide additional further processing of an element, for example to encrypt a Signature or | |
any other top level element. Also a Signature may include each top level element. Which | |
parts of a message to sign and/or encrypt is controlled by the Security Policy | |
@since WSS4J 2.0 | |
</body> | |
</html> |