InfoCenter Home >
5: Securing applications -- special topics >
5.7: The Secure Association Service (SAS) >
5.7.1: SAS on the client side

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:

  1. Establish an SSL connection
  2. Establish a secure association between the client and the server
  3. 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:
      • basicauth
      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.

Go to previous article: Secure Association Service Go to next article: SAS on the server side

 

 
Go to previous article: Secure Association Service Go to next article: SAS on the server side