//
// 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.
//

== Securing message attachments

WSS4J 2.0.0 introduces support for signing and encrypting SOAP message
attachments, via the the SOAP with Attachments (SWA) Profile 1.1 specification.
There is no support in WSS4J 1.6.x for signing or encrypting message
attachments. Attachments can be signed and encrypted in WSS4J via either the
"action"-based approach or via WS-SecurityPolicy, as covered in the sections
below.

The message attachment streams must be supplied to WSS4J for
signature/encryption via a CallbackHandler approach. An
AttachmentRequestCallback Object is used to retrieve either a particular
Attachment (on the receiving side), or all attachments (on the sending side).
The user must implement a CallbackHandler that sets a list of Attachments
matching this request on the Callback. Correspondingly, there is also a
AttachmentResponseCallback, which represents the secured/processed Attachment.

The good news is that if you are using Apache CXF then all of this is taken
care of automatically by a CallbackHandler that retrieves and sets CXF message
attachments. Therefore if you are using CXF then you can sign/encrypt message
attachments just by setting the configuration detailed in the next couple of
sections.

=== Securing message attachments via the action approach

With the "action" approach to using WSS4J, the user specifies the parts to
sign or encrypt via the following configuration tags:

 * ConfigurationConstants.SIGNATURE_PARTS ("signatureParts")
 * ConfigurationConstants.ENCRYPTION_PARTS ("encryptionParts")

The value of these tags is a String in a special format that looks something
like "{Content}{http://example.org/paymentv2}CreditCard"
({modifier}{namespace}localname). In WSS4J 2.0.0, it is possible to
sign/encrypt all of the attachments by specifying the following as part of
signatureParts/encryptionParts: "{}cid:Attachments;". Note that this signs or
encrypts all of the attachments, it is not possible to only sign/encrypt
individual attachments.

=== Securing message attachments via WS-SecurityPolicy

An easier way to use WSS4J is in conjunction with a web services stack such as
Apache CXF and a WS-SecurityPolicy-based policy. It is possible to sign/encrypt
all attachments by adding a "sp:Attachments" policy as a child of either a
"sp:SignedParts" or "sp:EncryptedParts" policy. In addition, the
"sp:Attachments" policy for SignedParts only has two optional child policies
called "sp13:ContentSignatureTransform" and
"sp13:AttachmentCompleteSignatureTransform", which dictate whether the
attachment headers are included or not in the Signature.

