Metro is a high performance, extensible, easy-to-use
web services stack. It combines the JAX-WS reference implementation with Project Tango. Project Tango, also called
Web Services Interoperability Technology or WSIT, implements numerous WS-\* standards to enable interoperability with
other implementations and to provide Quality of Service (QOS) features such as security, reliability, and transaction
support. Metro is available in the open source, enterprise-ready
GlassFish v2 application server as well as in the
modular GlassFish v3
application server. Metro also runs in the
Tomcat web container.
In addition, it has been successfully used in
other application servers.
Metro 1.3 was recently released. With this release,
Metro now supports the OASIS specification version of all the major WS-\* specifications that it implements. Earlier
Metro releases supported the OASIS submission version of these specifications. As a result, Metro is now interoperable
with the Microsoft .NET Framework 3.5, which also supports the same version of the specifications. The earlier releases of
Metro were interoperable with the Microsoft .NET Framework 3.0 . Metro is tested for interoperability with .NET releases on
a continuous basis and is a primary release criteria. See the
Metro Specifications section in the
Metro User's Guide for a complete list of the specifications and their versions supported in Metro.
WS-SecurityPolicy v1.2 specification from OASIS now includes an assertion for integrity and confidentiality
protection of SwA (SOAP Messages with Attachments) attachments. This assertion is also a supported feature in Metro 1.3.
In this tip, you will learn how to secure an SwA attachment using Metro 1.3 and NetBeans IDE 6.5 (currently available as
a Beta release). The new features in the Metro 1.3 release are available in NetBeans IDE 6.5 through a web services plugin.
A sample application package accompanies the tip. The sample application demonstrates
a web service and client that securely exchange an SwA attachment using Metro 1.3.
An Example of SwA and Security
Securing attachments is described in the
Profile specification. It describes how to use the OASIS Web Services Security: SOAP Message Security specification with
SwA. More specifically, the WSS:SwA Profile specification describes how a web service consumer can secure SOAP attachments
using SOAP Message Security
for attachment integrity, confidentiality, and origin authentication, and how a receiver may process such a message.
SwA defines a multi-part MIME structure for packaging attachments with SOAP messages. The structure contains a primary
SOAP envelope in its root part and one or more attachments in additional MIME parts. Some of these attachments may have
a content type corresponding to XML, but do not contain the primary SOAP envelope to be processed. The WSS:SwA specification
considers all attachments as opaque, in other words, arbitrary binary data, whether they are XML or some other content type.
Here is a sample multi-part MIME SOAP message, where the attachment is integrity protected through signing (line numbers have
been added for reference):
When SOAP attachments are used in a SOAP message, the SOAP message is accompanied by a MIME header and possibly
multiple boundary parts.
This is known as a SOAP message package. The primary SOAP envelope is generally conveyed in the first MIME part.
The attachments are carried in other MIME parts and are referenced from the SOAP envelope. In the example message,
lines 1 - 41 show the SOAP message, and lines 42 - 47 show the MIME part containing an attachment, in this case a JPEG image.
The attachment is referenced from the SOAP body (lines 35 - 40) using a
cid:Content-ID reference (line 38). The
attachment can also be referenced from the Signature Reference element (line 20), indicating that the signature signs
Signing an SwA Attachment
As you can see from the example message, when an SwA attachment is signed, a
<ds:Reference> element (line 20)
pointing to it is placed inside the
<ds:Signature> element (line 16) in the
<wsse:Security> header (lines 13-33). The transform element in
<ds:Reference> (line 22)
specifies if the content only of the MIME package should be signed (
if both the content and the MIME headers should be signed (
Attachment-Complete-Signature-Transform). In Metro 1.3,
Attachment-Content-Signature-Transform option is supported, and it's enabled by default. This is because
the WS-SecurityPolicy 1.2 specification does not provide a way to specify which transform to use for attachments.
Encrypting an SwA Attachment
You can encrypt an SwA attachment for confidentiality protection, and in this way protect the MIME part content (the
attachment content) of a SOAP message. You do this using XML encryption elements. You place the resulting cipher
text in the updated attachment body, and place an
<xenc:EncrptedData> element in the
<wsse:Security> header. An
<xenc:CipherReference> element must link the
<xenc:EncryptedData> element with the cipher data.
Here's an example SwA message with an encrypted attachment (line numbers have been added for reference):
Line 32 shows an
<xenc:CipherReference> element inside the
element (Line 29). The
<xenc:CipherReference> element refers to the attachment Content-ID to be encrypted.
The MimeType attribute in the
<xenc:EncryptedData> element indicates the Content-Type of the MIME
attachment before encryption (in this case,
image/jpeg). After encrypting the attachment, the Content-Type is
The sample application demonstrates a web service and client that securely exchange an SwA attachment using Metro 1.3.
The application includes two projects: FileUpload and FileUploadClient. The FileUpload project provides a
FileUpload web service that stores binary files on the server. The FileUploadClient project includes
a servlet that acts as a client to the
FileUpload web service.
The servlet sends a binary file to the
FileUpload service in a secured manner, as mandated by the policy of the service. The binary
file is sent as an SwA attachment to the service's
uploadFile() method. The policy for the web service
mandates that the attachment must be integrity and confidentiality protected "on the wire", that is, as the
attachment is sent from the client to the service.
Running the Sample
To run the sample, perform the following steps:
java -jar metro-1_3.jar. This will
metrodirectory and fill it with the Metro 1.3 content.
metrodirectory by entering the command:
ant -Das.home=<AS_HOME> -f metro-on-glassfish.xml install
<AS_HOME> is where you installed GlassFish. It you set AS_HOME as an environment variable,
you don't need to specify -Das.home in the command. This command copies the two Metro JAR files into your
lib directory and makes the necessary classpath alterations in the domain
domain.xml. It also updates the classpath for the utility script files,
<AS_HOME>/domains/domain1/config/domain.xmlin a text editor.
sampledirectory of the sample application.Click the Open Project button.
<AS_HOME>/bin/asadmin start-domain domain1
FileUploadservice as follows:
As Figure 1 shows, the class is annotated with a
@WebService annotation to
identify it as a web service. Notice too that the service has one method,
uploadFile(), which is annotated
@WebMethod annotation that identifies it as a web method. The
uploadFile() method uploads
files to a server location identified by the
UPLOAD_LOC variable. Change the value of
to specify the location on the server where you would like to save the binary files.
Figure 1. The
FileUploadservice, as shown in Figure 2.
Figure 2. Service Policy For
Figure 3. Securing Message Parts
Figure 4. The WSDL for the Web Service
uploadClientclass in the FileUploadClient project, as follows:
As Figure 5 shows,
FileUploadClient is a servlet which accesses the
FileUpload web service. The code to access the service is in the
Figure 5. The
FileUploadservice, as shown in Figure 6.
Figure 6. Service Policy For
Figure 7. A Successful File Upload
java.jpg, in the target server location, that is, the location
UPLOAD_LOCvariable within the
FileUploadclass. Here is the graphic
About the Author
Ashutosh Shahi is a member of the Web Services Security group at Sun Microsystems. He currently works on implementation
of WS-\* technologies related to security in the Metro Web Services stack from Sun. Before joining Sun, Ashutosh worked
on the development of Apache Axis, an open source SOAP engine from Apache.