Package org.apache.ws.security.message

The package provides classes to create messages that are compliant to the OASIS Web Service Security specifications.

See:
Description

Class Summary

EnvelopeIdResolver	XML-Security resolver that is used for resolving same-document URIs like URI="#id".
WSAddSignatureConfirmation	Builds a WS SignatureConfirmation and inserts it into the SOAP Envelope.
WSAddTimestamp	Builds a WS Timestamp and inserts it into the SOAP Envelope.
WSBaseMessage	This is the base class for WS Security messages.
WSEncryptBody	Encrypts a SOAP body inside a SOAP envelope according to WS Specification, X509 profile, and adds the encryption data.
WSSAddSAMLToken	Builds a WS SAML Assertion and inserts it into the SOAP Envelope.
WSSAddUsernameToken	Builds a WS UsernameToken and inserts it into the SOAP Envelope.
WSSecBase	This is the base class for WS Security messages.
WSSecDerivedKeyBase	Base class for DerivedKey encryption and signature
WSSecDKEncrypt	Encrypts and signs parts of a message with derived keys derived from a symmetric key.
WSSecDKSign	Builder to sign with derived keys
WSSecEncrypt	Encrypts a parts of a message according to WS Specification, X509 profile, and adds the encryption data.
WSSecEncryptedKey	Builder class to build an EncryptedKey.
WSSecHeader	This class implements WS Security header.
WSSecSAMLToken	Builds a WS SAML Assertion and inserts it into the SOAP Envelope.
WSSecSecurityContextToken	Builder class to add a wsc:SecurityContextToken into the wsse:Security
WSSecSignature	Creates a Signature according to WS Specification, X509 profile.
WSSecSignatureConfirmation	Builds a WS SignatureConfirmation and inserts it into the SOAP Envelope.
WSSecTimestamp	Builds a WS Timestamp and inserts it into the SOAP Envelope.
WSSecUsernameToken	Builds a WS UsernameToken.
WSSignEnvelope	Signs a SOAP envelope according to WS Specification, X509 profile, and adds the signature data.

Package org.apache.ws.security.message Description

The package provides classes to create messages that are compliant to the OASIS Web Service Security specifications.

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. Here are the WSS specifications.

Currently this package contains two sets of classes that provide the same or similar functionality.

• The old classes, named WSAdd*, WSEncryptBody, WSSignEnvelope, WSBaseMessage. The usage of these classes is depreciated.
• The new, refactored classes. Their names start with the prefix WSSec.

How to use the WSSec* classes

The new refactored classes follow the same usage pattern.

1. Create an object for the required security element, for example a WSSecSignature.
2. Set the required fields using setter methods, for example user name, signature algorithm, etc.
3. After the fields are set call prepare(...). This initializes the internal structures, gets the required data like X509 tokens, etc.
4. 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 WSSecHeader at this time (adding to the security header can be done at any time after prepare(...)). See the documentation of the various classes what is available.

In contrast to the old classes the handling of the security header is not longer implicitly performed. To provide better flexibilty the class WSSecHeader deals with the security header.

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.

This code snippet shows how to setup a Signature element:

        /*
         * 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();

Each new class also contains a build() method that is similar to the build() method in the old classes. Thus, if the flexibilty is not required you may use this method for convenience.

Each top level security element has wsu:Id or plain Id attribute

The prepare() 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 EncryptedKey and Signature elements have a plain Id according to the W3C specifications, elements defined by the OASIS WS Security specifications contain a wsu:Id.

Each WSSec* class has a getId() that returns the id strig regardless if its qualified or not.

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