InfoCenter Home >
5: Securing applications -- special topics >
5.7: The Secure Association Service (SAS) >
5.7.1: SAS on the client side
When an enterprise-bean client, for example, a Java client, a servlet,
or another enterprise bean, invokes a remote method, SAS interceptors are
called to do the following work on the client side:
- Establish an SSL connection
- Establish a secure association between the client and the server
- Send the request to the server
The following sections describe these steps in detail.
Establishing an SSL connection
Establishing an SSL connection requires
information from both the client and the server prior. The client
obtains some of this information from the client-side property file,
sas.client.props. Some of the information must come from the server,
which stores the information with the naming service. To contact a
server, the client retrieves information about the server from the
naming service. The returned information includes an interoperable
object reference (IOR), which the client uses to determine the type of
connection expected by the server. If global security is enabled
within WebSphere Application Server, servers insert a structure of
security information, called a security tag into their IORs
before registering the IORs with the naming service. The
information from the security tag in the IOR and from the
sas.client.props file is sufficient for creating an SSL connection.
If the necessary information for an SSL connection is not present, a
TCP/IP connection is created instead. For example, if the client does
not find a security tag in a server's IOR, an SSL connection cannot be
created. If the target method is secured, the request must come in on
a secure connection. Requests coming in on a TCP/IP connection always
fail for a lack of permission provided the method being invoked is
protected; no credentials are created for a TCP/IP connection. A
typical error message that indicates this condition is:
authorization failed for / while invoking method A
If global security is enabled, RMI/IIOP connections are typically
made using SSL. There are a few exceptions, for which TCP/IP connections
are automatically made. These exceptions include name-server lookups,
is_a queries, and a few other special methods. SSL connections
are always the default for business methods.
SAS gets some of the information it needs from the server's IOR. Additional
information is obtained from property files, one on the client side
and two on the server side (sas.server.props and server-cfg.xml). The configuration file server-cfg.xml is created from changes made in the Administrator's Console. A Java client, for example, uses the client-side
configuration file, but a server acting as a client uses the server-side
files. WebSphere Application Server provides two pre-configured properties
files, sas.client.props and sas.server.props, which can be modified.
Applications can also use other files. The property file for an application
is specified as a Java property on the command line when the application
is started. The property, com.ibm.CORBA.ConfigURL , requires a
valid URL as a value. For example, the URL for the sas.client.props file,
assuming a default installation, is specified as follows:
- For Windows NT systems:
com.ibm.CORBA.ConfigURL=file:/c:/WebSphere/AppServer/properties/sas.client.props
- For UNIX systems:
com.ibm.CORBA.ConfigURL=file:///usr/WebSphere/AppServer/properties/sas.client.props
Note:
The sas.client.props file affects administrative clients like the GUI-based administrative console and the XMLConfig
tool when WebSphere Application Server security is enabled. The WSCP tool uses its own properties file as specified in
its documentation.
When authenticating by values configured in the file, it may also be necessary to configure the following parameter
where the <realm name> is found in the destination server's sas.server.props file:
com.ibm.CORBA.principalName=<realm name>/<user_ID>
You can verify the URL by following the URL with a browser on the system
where the file resides. If the browser can read the file, the URL is valid. The com.ibm.CORBA.ConfigURL property
is typically specified on the java command line of the client program by using the -D option in front of the property.
The information required before SAS can make a secure connection is
shown below.
Information obtained from the server's IOR
This section describes the information retrieved on the client side
from the server's IOR and lists possible server-side sources for that
information. For example, some of the information in the IOR comes
from server-side properties.
- Server TCP/IP address: This is determined by the TCP/IP
configuration.
- Server TCP/IP port: This is usually assigned dynamically, but
it can be explicitly set by using the server-side property in the sas.server.props file
com.ibm.CORBA.ListenerPort .
- Server SSL port: This is usually assigned dynamically, but it
can be explicitly set by using the server-side property in the sas.server.props file
com.ibm.CORBA.SSLPort .
- Server security name: This is configured using the Administrator's Console when enabling security. It can
also be set manually in the $(WAS_ROOT)/config/server-cfg.xml file under the "security" tag.
- Server SSL key file and password: These values are
set from the Administrator's Console on the server.
See 5.7.3: ORB SSL Configuration.
The SSL key file contains the keys used by the server to identify the
server and to encrypt and decrypt messages. The strength of
the encryption algorithm used is determined when the
connection is established. The password protects the
contents of the SSL key file.
- Quality of protection (QOP) required: This is set
by using the server-side property
com.ibm.CORBA.standardClaimQOPModels .
The value of this property determines the quality of the SSL
connection required by the server. If a client attempts to connect at a value lower, it will automatically be
bumped up to this value. However, if the client tries to make a connection at a higher quality of protection, the connection should be opened at the higher value.
Valid values are:
confidentiality (high) : 128-bit encryption and digital signing
integrity (medium) : 40-bit encryption and digital signing
authenticity (low) : no encryption and digital signing
Information obtained from the client's properties
This section describes the information retrieved on the client side
from the client's properties files.
- Quality of protection (QOP) offered: This is set
by using the client-side property
com.ibm.CORBA.standardPerformQOPModels . The value
indicates what the client expects to do in creating an SSL
connection; however, the server's quality-of-protection value
can require the client to exceed its expected level.
Valid values are:
confidentiality (high) : 128-bit encryption and digital signing
integrity (medium) : 40-bit encryption and digital signing
authenticity (low) : no encryption and digital signing
- Login information: This is information needed to
authenticate the user. It is set by using the following
client-side properties:
com.ibm.CORBA.loginSource : This determines
the source of the authentication information. Valid values
include:
prompt : A graphical panel is presented
for the user for collecting the user ID and password.
stdin : The user is prompted for user ID and
password by using a non-graphical console prompt. Currently only supported in the client properties file.
properties : The user ID and password are
retrieved from the following two properties:
com.ibm.CORBA.loginUserid
com.ibm.CORBA.loginPassword
If you are using a client-side property file to login (i.e., com.ibm.CORBA.loginSource=properties),
you must specify the <realm> which you are trying to login to. There are two ways
to do this. One is to set the com.ibm.CORBA.principalName in that file to
<realm>/<loginUserid> , where the <loginUserid>
is the same as the value in the com.ibm.CORBA.loginUserid property and the
<realm> matches the realm specified for the server localos machine name or
domain name depending on the type of registry used. Note that the realm name is case sensitive.
Example:
com.ibm.CORBA.loginUserid=userid
com.ibm.CORBA.principalName=REALM/userid
The other way to handle this is to specify the <realm> on the same line as <loginUserid>.
Example:
com.ibm.CORBA.loginUserid=REALM/userid
key file : The user ID specified by
using the property com.ibm.CORBA.loginUserid
and the realm name retrieved from the IOR are
used to extract a user ID and password for
authentication from a key file. The name of the key file to use is specified by
setting the com.ibm.CORBA.keyFileName property.
com.ibm.CORBA.authenticationTarget : This value
determines the authentication method used to establish
credentials. The valid values are:
The only supported value for a pure client is basicauth . The authentication target for the
server is always localos for WebSphere AE Single-Server.
Server associations allowed by this client: This
determines the type of association the client can establish
with the server. This value is determined by setting one
of the following properties to true . The properties are:
com.ibm.CORBA.SSLTypeIServerAssociationEnabled :
Type I is an SSL connection in which only server authentication
is performed at the SSL transport layer. (Note: Client
authentication takes place at the security-context layer
with basicauth (user ID/password) credentials.)
If this property is set to false, a TCP/IP connection is
created, regardless of any other SSL properties specified.
Client keyring file and password: These are specified using
the client-side properties com.ibm.CORBA.SSLClientKeyRing
and com.ibm.CORBA.SSLClientKeyRingPassword . The
The keyring-file value specifies the keyring file that contains
the server's public key. This key is used to encrypt outgoing
messages and to decrypt incoming messages. The password protects
the contents of keyring file.
This information, with the exception of the client-side keyring
file and password, is used by SAS to construct the SSL connection
to the server. During this process, the client uses the public
key in the keyring file to secure messages.
WebSphere Application Server provides a keyring file, DummyKeyring,
for use in test and development environments. This keyring file
should not be used in a production environment where message
protection is desired. The certificate in this keyring file
can be used to do valid encryption, but the private key needed
for decrypting the messages is readily available.
During the SSL handshake between the client and server, the
quality-of-protection level for the connection is determined by
evaluating the client and server settings; the result is called the
coalesced QOP. If the server setting is higher than the client
setting, the server setting is used for both. The server setting is
the minimum acceptable level for the connection. If the client setting
is higher but the server supports the higher level, then the client
setting is used. If the server does not support the higher
level offered by the client, the client uses the server setting.
The coalesced QOP value is used to determine the cipher suite to use
when creating the SSL connection. The value determines the characteristics
of the SSL connection as follows:
- If the coalesced QOP is the high-security
confidentiality
value, the messages will be encrypted with 128-bit algorithms and digitally signed;
- If the coalesced QOP is the medium-security
integrity value,
the messages will be encyrpted with 40-bit algorithms and digitally signed.
- If the coalesced QOP is low-security
authenticity value,
only digital signing will occur.
In cases where client authentication is required but the login information
is not specified, the message is sent over an insecure TCP/IP connection.
When a TCP/IP connection is used to access a protected method, an
authorization failure occurs.
Establishing a secure association between the client and server
Once a connection is created at the server, SAS requires that a secure
association between the client and server be established. This entails
authenticating the client on the server side and establishing a SAS security
session on both the client and server sides. Most problems that occur with
authentication will happen during this process. This is where the server
authenticates the client and returns success or failure. In many cases where
a failure occurs, you can expect to receive a NO_PERMISSION exception. To get
more information from the exception, use the getMessage() method to get a text
description about the failure.
Sending the request to the server
After the SSL connection is created and a secure association is
established, the client's request is sent to the server.
Receiving a response from the server
Once the server processes the request it sends a response back to the client. The SAS client processes the response
to determine if it was successful or not. If not successful, it will throw an exception to the business client to handle.
Some of the exceptions you can expect to see are:
The exception is usually one of the following:
- org.omg.CORBA.NO_PERMISSION
Typically received because the userid and password entered on the client failed to authenticate. This could be due to an incorrect
userid/password or an internal reason such as the user registry being unavailable.
- org.omg.CORBA.COMM_FAILURE
Typically received when a server is not listening on the host and port specified in the IOR of the business object. For
example, if an application server has been stopped which was sharing a particular resource, access to that resource will
return a COMM_FAILURE.
- org.omg.CORBA.INTERNAL
Typically received when the SAS code reaches a path that was unexpected or a message is out of sequence. This can happen
unexpectedly and SAS tracing
may be required.
|
|