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.

The pure Java client or server acting as a client (that is, by making an outgoing connection to another server) gets some of the information it needs from the object's IOR from the server. Additional information is obtained from the client properties file.

For a pure Java client (one that executes in a separate process from the server), the properties file used is the one specified on the com.ibm.CORBA.ConfigURL property on the Java command line. This is usually the sas.client.props file.

For a server acting as a client, the property file used is the sas.server.props file on the server system. Some of the information in the sas.server.props file can only be changed by using the administrative console. Other parts of the sas.server.props file can be changed using a text editor.

Most of the SSL and login configuration is done by using the Security Center in the administrative console and written into the WebSphere Application Server repository. After the administrative server restarts, the configuration information is migrated from the repository to the sas.server.props.future file. It is then merged into the sas.server.props file, which is used when the adminstrative server restarts.

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

You can verify the URL syntax 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 through the Security Center. It contains the realm and user ID of the target server. The realm typically describes the name of the authentication server. The format of the value varies with the authentication mechanism:
    • For Local OS:
      DOMAIN/server_id

      The DOMAIN attribute can be either a Machine Name or Domain Name depending upon whether the WebSphere server is configured on a domain (if your operating system supports the domain concept).

    • For Lightweight Third-Party Authentication (LTPA):
      LDAP HOST AND PORT/server_id

      The server_id must be a valid user in the LDAP registry. The LDAP administrative ID is not supported for use as the WebSphere Server Security ID. If you want to specify a user called "cn=root", you can add a valid LDAP user record where the UID has cn=root specified to make it searchable.

  • 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:
    • high: 128-bit encryption and digital signing
    • medium: 40-bit encryption and digital signing
    • low: No encryption or 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:
    • high: 128-bit encryption and digital signing
    • medium: 40-bit encryption and digital signing
    • low: No encryption or 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. Pure Java clients must call the JDK API System.exit(0) at the end of the program in order to properly end the Java process. This is because the JDK starts a backward AWT thread that is not killed when the login prompt disappears. If you choose not to use a System.exit(0) call, pressing Ctrl-C ends the process.
      • stdin: The user is prompted for user ID and password by using a non-graphical console prompt. Currently only supported by a pure Java client.
      • 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 log in (for instance, com.ibm.CORBA.loginSource=properties), you must specify the realm where you are trying to log in to. There are two ways to do this:

        • Set the com.ibm.CORBA.principalName property in that file to realm/loginUserid, where the loginUserid is the same as the value of 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. For example:
          com.ibm.CORBA.loginUserid=userid
          com.ibm.CORBA.principalName=REALM/userid
        • Specify the realm on the same line as loginUserid. For 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
      • localos
      • ltpa
      The only supported value for a pure Java client is basicauth. A server actingas a client performs a login by properties. This creates basicauth credentials, which are then authenticated by the target server. On the server side, localos and ltpa can be specified; the value you select determines the type of registry against which basicauth credentials are verified.
  • Client SSL Configuration Properties: See 5.7.3: ORB SSL Configuration

This information is used by SAS to construct the SSL connection to the server. During this process, the client uses the public key in the key store file to secure messages.

WebSphere Application Server provides several dummy keyring files for use in test and development environments. These keyring files 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 value, the messages are encrypted with 128-bit algorithms and digitally signed.
  • If the coalesced QOP is the medium value, the messages are encyrpted with 40-bit algorithms and digitally signed.
  • If the coalesced QOP is the low value, only digital signing occurs.

In cases where client authentication is required but the login information is not specified, the message is sent over an insecure TCP/IP connection. Ensure that methods are protected using authorization if you do not want unauthorized users to access them. 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