//
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you 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.
//

== Using Apache WSS4J&#8482;

This page describes how to use Apache WSS4J. For information about how to
configure WSS4J, see the link:config.html[configuration page]. WSS4J
can essentially be used in three different ways. For information about using
WSS4J with a SOAP stack, see the sections on Apache CXF and Apache Rampart/Axis.

 * Action based approach: WSS4J offers an "Action" based approach to
applying WS-Security to a SOAP request or response, in conjunction with a SOAP
stack.
 * WS-SecurityPolicy based approach: WSS4J can be configured for a SOAP
request/response via WS-SecurityPolicy, in conjunction with a SOAP Stack. 
This is the recommended approach.
 * Standalone approach: WSS4J offers a low-level (DOM) API to
construct/sign/encrypt/etc. tokens directly.

=== Action based approach

The WSHandler class in WSS4J is designed to configure WSS4J to secure an
outbound SOAP request, by parsing configuration that is supplied to it via
a subclass. Typically a web services stack that uses WSS4J for WS-Security
will subclass WSHandler. An example of a subclass is the
http://cxf.apache.org/docs/ws-security.html[WSS4JOutInterceptor]
in Apache CXF. The configuration tags are defined in the https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/ConfigurationConstants.java?view=markup[ConfigurationConstants] class (WSHandlerConstants in WSS4J 1.6.x). For a more detailed explanation
of the configuration tags, please refer to the link:config.html[configuration] page. The next few paragraphs will
describe the most fundamental configuration tags that are used in most
cases.

==== Common configuration tags

The "Action" based approach to using Apache WSS4J involves explicitly telling
WSS4J what WS-Security functionality to perform on a request, by configuring
the stack specific WSHandler implementation with the required properties. On
the receiving side, the "actions" that are configured are matched against what
was processed in the security header, and an error is thrown if they do not
match (in some order). Typical actions include "UsernameToken, "Signature",
"Encrypt", "Timestamp, "SAMLTokenSigned", etc. 

After specifying the action to perform on a request, the next task is typically
to specify the "user". The "user" can be either the username to insert into a
UsernameToken, or the keystore alias to use for either signature or encryption.
If you are configuring more than one of these actions, the "signatureUser" and
"encryptionUser" configuration tags override the more general "user" tag. The
next task is often to specify a CallbackHandler implementation to use to
retrieve passwords. On the sending side, this is used to retrieve a password
to insert into a UsernameToken and to decrypt a private key from a keystore
for Signature. On the receiving side, it is used to retrieve a password to
validate a received UsernameToken, and to decrypt a private key from a
keystore to use for decryption.  

The next task is to specify a Crypto implementation if you are using Signature
or Encryption. See the link:configuration.html[configuration] page for
more information on the Crypto interface. Typically, it is configured in a 
Crypto properties file, which specifies the Crypto implementation to use, as
well as the keystore location, default alias/password, etc. For signature, the
path of this properties file can be referred to by the tag "signaturePropFile"
and "encryptionPropFile" for outbound request, and
"signatureVerificationPropFile" and "decryptionPropFile" for inbound requests".
How signing keys/certificates are referenced from a Signature can be 
controlled via the "signatureKeyIdentifier" configuration tag. This defaults
to "IssuerSerial", but could be "DirectReference", "Thumbprint", etc. The
"encryptionKeyIdentifier" tag performs the same function for encryption.

Finally, the Elements to sign or encrypt can be specified by the
"signatureParts" and "encryptionParts" configuration tags. Both default to the
SOAP Body. The value of signatureParts/encryptionParts is a list of semi-colon
separated values that identify the elements to sign/encrypt. The value is of
the format of an encryption mode specifier, and a namespace URI, each inside a
pair of curly brackets, and then the local name of the Element. For example,
"{Content}{http://example.org/paymentv2}CreditCard;". The encryption modifier
can be either "Content" or "Element" and only applies to encryption.

Here are some sample configuration values for various actions, as taken from
some CXF system tests. The constructor of the
WSS4JOutInterceptor/WSS4JInIntereptor interceptors in CXF takes a map of 
String/Object pairs which correspond to the key/value pairs given in the tables
below. See the CXF configuration https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/resources/org/apache/cxf/systest/ws/action/client.xml[file] for more information.

==== Sample Outbound UsernameToken configuration

 * *Key* - *Value*
 * action - UsernameToken
 * user - Alice
 * passwordCallbackClass - https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/java/org/apache/cxf/systest/ws/common/UTPasswordCallback.java[org.apache.cxf.systest.ws.common.UTPasswordCallback]

==== Sample Outbound Signature/Timestamp configuration

 * *Key* - *Value*
 * action - Signature Timestamp
 * signatureUser - alice
 * passwordCallbackClass - https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/java/org/apache/cxf/systest/ws/common/KeystorePasswordCallback.java[org.apache.cxf.systest.ws.common.KeystorePasswordCallback]
 * signaturePropFile - https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/resources/alice.properties[alice.properties]
 * signatureKeyIdentifier - DirectReference
 * signatureParts - {}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{}{http://schemas.xmlsoap.org/soap/envelope/}Body;

=== WS-SecurityPolicy based approach

The recommended way of applying WS-Security to your web services is to use
WS-SecurityPolicy. The WS-SecurityPolicy specification defines a set of
WS-Policy expressions that can be used to define the security requirements of
a web service. Typically one or more policies are attached to the WSDL of a
service, which conveys the security requirements of the service to the client.
A WS-SecurityPolicy aware stack such as Apache CXF or Apache Axis/Rampart can
parse the policies and configure WSS4J appropriately. This greatly simplifies
things for the user, who then only has to supply some basic information about
which users, CallbackHandlers, Crypto property files, etc. to use.

For more information on using WS-SecurityPolicy with WSS4J, please see CXF's
WS-SecurityPolicy page, or go to the SOAP stack sections below:
http://cxf.apache.org/docs/ws-securitypolicy.html[CXF WS-SecurityPolicy configuration]

=== Standalone approach

Apache WSS4J provides a set of APIs to implement WS-Security functionality on
a SOAP message. It is possible to use these APIs directly in a standalone
manner, although it is far more common to use either the "Action" or
WS-SecurityPolicy based approaches. This functionality is only available for
the DOM code. The best way of finding out how to do this is to take a look at
the test sources. For example: 

 * https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/UsernameTokenTest.java?view=markup[Username Token Test]
 * https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/EncryptionTest.java?view=markup[Encryption Test]
 * https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/SignatureTest.java?view=markup[Signature Test]
 * https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/TimestampTest.java?view=markup[Timestamp Test]
 * https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/saml/SamlTokenTest.java?view=markup[SAML Token Test]

=== SOAP Stacks

==== Apache CXF

http://cxf.apache.org[Apache CXF] is an open-source web services
stack. CXF uses WSS4J to perform the core WS-Security functionality, and
provides extended security functionality based around the WS-SecurityPolicy,
WS-SecureConversation and WS-Trust specifications. More information:

 * http://cxf.apache.org/docs/ws-security.html[CXF WS-Security configuration]
 * http://cxf.apache.org/docs/ws-secureconversation.html[CXF WS-SecureConversation configuration]
 * http://cxf.apache.org/docs/ws-securitypolicy.html[CXF WS-SecurityPolicy configuration]
 * http://cxf.apache.org/docs/ws-trust.html[CXF WS-Trust configuration]
 * http://cxf.apache.org/resources-and-articles.html[CXF Security articles]

==== Apache Rampart/Axis

http://axis.apache.org/axis2/java/rampart/[Apache Rampart] is the
security module for the Axis2 web services stack. Rampart uses WSS4J to
perform the core WS-Security functionality, and provides extended security
functionality based around the WS-SecurityPolicy, WS-SecureConversation and
WS-Trust specifications. Note that support for Apache Axis1 via the WSS4J
1.5.x series of releases is no longer supported. More information:

 * http://axis.apache.org/axis2/java/rampart/developer-guide.html[Rampart developer guide]
 * http://axis.apache.org/axis2/java/rampart/samples.html[Rampart samples]
 * http://axis.apache.org/axis2/java/rampart/rampartconfig-guide.html[Rampart configuration guide]
 * http://axis.apache.org/axis2/java/rampart/articles.html[Rampart articles]