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.
The
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.
If would want to learn about other aspects of Metro security, see the March 2008 Tech Tip
Secure Conversations for Web Services With Metro and the March 2007 Tech Tip
Securing Web Services Using WSIT.
An Example of SwA and Security
Securing attachments is described in the
WSS:SwA
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
this attachment.
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 (Attachment-Content-Signature-Transform
) or
if both the content and the MIME headers should be signed (Attachment-Complete-Signature-Transform
). In Metro 1.3,
only the 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 <xenc:EncryptedData>
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
set to application/octet-stream
.
Sample Application
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 aFileUpload
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 theFileUpload
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:
<sample_install_dir>/sample
, where <sample_install_dir>
is theC:\\
onC:\\sample
.java -jar metro-1_3.jar
. This willmetro
directory and fill it with the Metro 1.3 content.metro
directory by entering the command: cd metro
ant -Das.home=<AS_HOME> -f metro-on-glassfish.xml install
where <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
GlassFish installation's lib
directory and makes the necessary classpath alterations in the domain
configuration file, domain.xml
. It also updates the classpath for the utility script files,wsimport
and wsgen
.
<AS_HOME>/domains/domain1/config/domain.xml
in a text editor.<jvm-options>
element:<jvm-options>-Dcom.sun.xml.ws.transport.http.HttpAdapter.dump=true</jvm-options>
sample
directory of the sample application.Click the Open Project button.<AS_HOME>/bin/asadmin start-domain domain1
FileUpload
service as follows:FileUpload.java
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
with a @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 UPLOAD_LOC
to specify the location on the server where you would like to save the binary files.
![]() |
Figure 1. The |
FileUpload
service, as shown in Figure 2.![]() |
Figure 2. Service Policy For |
![]() |
Figure 3. Securing Message Parts |
![]() |
Figure 4. The WSDL for the Web Service |
uploadClient
class in the FileUploadClient project, as follows: As Figure 5 shows, FileUploadClient
is a servlet which accesses theFileUpload web service
. The code to access the service is in the processRequest()
method.
![]() |
Figure 5. The |
FileUpload
service, 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 locationUPLOAD_LOC
variable within the FileUpload
class. Here is the graphic<AS_HOME>/domains/domain1/logs/server
Further Reading
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.
How can the client be run if one doesn't use NetBeans?
Hello,
There is a sample available for securing attachments using Metro at https://wsit.dev.java.net/source/browse/wsit/wsit/samples/ws-security/src/secure_attachments/ . This one is w/o Netbeans.
Ashutosh
Hello Ashutosh: I'm having a hard time finding decent documentation on Metro and Tomcat with WS-Security.
Most of what I've found references Glassfish and NetBeans and doesn't work when using Tomcat.
Could you please point me to some good docs on Tomcat, Metro and WS-Security?
Thank you.
Umk, perhaps my blog entry here might help you[1].
Ashutosh, do you know why WS-SecurityPolicy covers SwA but not MTOM? I would guess the latter would be the better choice--as it is more modern and supported by Microsoft.
[1] http://www.jroller.com/gmazza/entry/implementing_ws_security_with_pki
Hello Glen,
There's a policy assertion for MTOM <wsoma:OptimizedMimeSerialization xmlns:wsoma="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization"/> which XOPs the binary data of size above a specific threshold limit. If that binary data happens to be part of SignedPart or SignedElement (or EncryptedPart and EncryptedElement) e.g <sp:Body/>, it is signed in the SOAP messages. So, the whole process is transparent to the end user. And, thanks for the link.
Umk,
The steps on tomcat and glassfish should mostly be same except for few steps here and there. Please post queries on Metro forum if you have any issues.
Ashutosh
Thank you for the tutorial.
I think we need another one - on how to get SOAP attachments from web services on a client side.