Understanding Message Security in the Enterprise Server

The Enterprise Server offers integrated support for the WS-Security standard
in its web services client and server-side containers. This functionality
is integrated such that web services security is enforced by the containers
of the Enterprise Server on behalf of applications, and such that it can be applied
to protect any web service application without requiring changes to the implementation
of the application. The Enterprise Server achieves this effect by providing facilities
to bind SOAP layer message security providers and message protection policies
to containers and to applications deployed in containers.

Assigning Message Security Responsibilities

In the Enterprise Server, the System Administrator and Application Deployer roles are expected to take
primary responsibility for configuring message security. In some situations,
the Application Developer may also contribute,
although in the typical case either of the other roles may secure an existing
application without changing its implementation without involving the developer.
The responsibilities of the various roles are defined in the following sections:

System Administrator

Configuring a Java Cryptography Extension (JCE) provider if
using encryption and running a version of the Java SDK prior to version 1.5.0.

Installing the samples server. This is only done if the xms sample application will be used to demonstrate the use of message
layer web services security.

A system administrator uses the Admin Console to manage server security
settings and uses a command line tool to manage certificate databases. In
Platform Edition, certificates and private keys are stored in key stores and
are managed with keytool. Standard Edition and Enterprise
Edition store certificates and private keys in an NSS database, where they
are managed using certutil. This document is intended primarily
for system administrators. For an overview of message security tasks, see Configuring the Enterprise Server for Message Security.

Application Deployer

The application deployer is responsible for:

Specifying (at application assembly) any required application-specific
message protection policies if such policies have not already been specified
by upstream roles (the developer or assembler).

Application Developer

The application developer can turn on message security, but is not responsible
for doing so. Message security can be set up by the System Administrator so
that all web services are secured, or by the Application Deployer when the
provider or protection policy bound to the application must be different from
that bound to the container.

The application developer or assembler is responsible for the following:

Determining if an application-specific message protection
policy is required by the application. If so, ensuring that the required policy
is specified at application assembly which may be accomplished by communicating
with the Application Deployer.

About Security Tokens and Security Mechanisms

The WS-Security specification provides an extensible mechanism for using
security tokens to authenticate and encrypt SOAP web services messages. The
SOAP layer message security providers installed with the Enterprise Server may
be used to employ username/password and X.509 certificate security tokens
to authenticate and encrypt SOAP web services messages. Additional providers
that employ other security tokens including SAML assertions will be installed
with subsequent releases of the Enterprise Server.

About Username Tokens

The Enterprise Server uses Username tokens in SOAP
messages to establish the authentication identity of the message sender. The recipient of a message containing a Username token (within
embedded password) validates that the message sender is authorized to act
as the user (identified in the token) by confirming that the sender knows
the secret (the password) of the user.

When using a Username token, a valid user database must be configured
on the Enterprise Server

About Digital Signatures

The Enterprise Server uses XML Digital signatures to bind an authentication
identity to message content. Clients use digital signatures
to establish their caller identity, analogous to the way basic authentication
or SSL client certificate authentication have been used to do the same thing
when transport layer security is being used. Digital signatures are verified
by the message receiver to authenticate the source of the message content
(which may be different from the sender of the message.)

When using digital signatures, valid keystore and truststore files must
be configured on the Enterprise Server. For more information on this topic, read About Certificate Files.

About Encryption

The purpose of encryption is to modify the data such that it can only
be understood by its intended audience. This is accomplished by substituting
an encrypted element for the original content. When predicated on public key
cryptography, encryption can be used to establish the identity of the parties
that can read a message.

When using Encryption, you must have an installed JCE provider that
supports encryption. For more information on this topic, read Configuring a JCE Provider.

About Message Protection Policies

Message protection policies are defined for request message processing
and response message processing and are expressed in terms of requirements
for source and/or recipient authentication. A source authentication policy
represents a requirement that the identity of the entity that sent a message
or that defined the content of a message be established in the message such
that it can be authenticated by the message receiver. A recipient authentication
policy represents a requirement that the message be sent such that the identity
of the entities that can receive the message can be established by the message
sender. The providers apply specific message security mechanisms to cause
the message protection policies to be realized in the context of SOAP web
services messages.

Request and response message protection policies are defined
when a provider is configured into a container. Application-specific message
protection policies (at the granularity of the web service port or operation)
may also be configured within the Sun-specific deployment descriptors of the
application or application client. In any case, where message protection policies
are defined, the request and response message protection policies of the client
must match (be equivalent to) the request and response message protection
policies of the server. For more information on defining application-specific
message protection policies, refer to the Securing Applications chapter
of the Developers Guide.

Glossary of Message Security Terminology

The authentication
layer is the message layer on which authentication processing must
be performed. The Enterprise Server enforces web services message security at
the SOAP layer.

Authentication Provider

In this release of the Enterprise Server,
the Enterprise Server invokes authenticationproviders to process SOAP message layer security.

A client-side provider establishes (by
signature or username/password) the source identity of request messages and/or
protects (by encryption) request messages such that they can only be viewed
by their intended recipients. A client-side provider also establishes its
container as an authorized recipient of a received response (by successfully
decrypting it) and validates passwords or signatures in the response to authenticate
the source identity associated with the response. Client-side providers configured
in the Enterprise Server can be used to protect the request messages sent and
the response messages received by server-side components (servlets and EJB
components) acting as clients of other services.

A server-side provider establishes its
container as an authorized recipient of a received request (by successfully
decrypting it) and validates passwords or signatures in the request to authenticate
the source identity associated with the request. A server-side provider also
establishes (by signature or username/password) the source identity of response
messages and/or protects (by encryption) response messages such that they
can only be viewed by their intended recipients. Server-side providers are
only invoked by server-side containers.

Default Server Provider

The default
server provider is used to identify the server provider to be invoked
for any application for which a specific server provider has not been bound.
The default server provider is sometimes referred to
as the default provider.

Default Client Provider

The default
client provider is used to identify the client provider to be invoked
for any application for which a specific client provider has not been bound.

Request Policy

The request policy defines
the authentication policy requirements associated with request processing
performed by the authentication provider. Policies are expressed in message
sender order such that a requirement that encryption occur after content would
mean that the message receiver would expect to decrypt the message before
validating the signature.

Response Policy

The response policy defines
the authentication policy requirements associated with response processing
performed by the authentication provider. Policies are expressed in message
sender order such that a requirement that encryption occur after content would
mean that the message receiver would expect to decrypt the message before
validating the signature.