12/18

# 9 Configure Security in Oracle Database Mobile Server

The following sections detail how to manage security in Oracle Database Mobile Server:

- Section 9.1, "Security Enhancements"

- Section 9.2, "Which Password is Which?"

- Section 9.3, "Providing Security for the Mobile Client"

- Section 9.4, "Configuring for Secure Socket Layer (SSL) Communication"

- Section 9.5, "Providing Your Own Authentication Mechanism for Oracle Database Mobile Server"

- Section 9.6, "Using a Firewall Proxy or Reverse Proxy"

- Section 9.7, "Providing SSL Client Authentication with a Common Access Card"

- Section 9.8, "Security Warning for Demo Applications"

Note:

There is additional information about developing for security in Chapter 7, "Customizing Oracle Database Mobile Server Security" in the Oracle Database Mobile Server Developer's Guide.

## 9.1 Security Enhancements

A number of security enhancements have been made, as follows:

- It is possible to restrict the database privileges for the `MOBILEADMIN` user, once the application has been published.

- Passwords for all default accounts can be chosen at install time.

## 9.2 Which Password is Which?

In the Oracle Database Mobile Server product, there are several user name/password combinations that are used for different security reasons and for separate types of users or administrators. This section describes each of the user name/password combinations in order to eliminate confusion.

Figure 9-1 Components That Use Passwords

Description of "Figure 9-1 Components That Use Passwords"

As shown in Figure 9-1, the passwords for the mobile client environment are as follows:

1. When the mobile server accesses the mobile server repository, it uses the repository user name/password. This defaults to the user `MOBILEADMIN` and the password is set during install. When the user accesses the user data in the mobile server repository, the mobile server connects using the repository user name, where the mobile user name and password are authenticated before access is provided to the user data.

   Note:

   For details on how to modify the repository password, see Section 9.2.1, "Modifying Repository Password".

2. The Mobile Manager is a Web administration UI that provides administrators the ability to modify how the mobile server behaves. Only administrators can use this tool; thus, only mobile server administrators can log in with their passwords. The initial administration user name/password is created during installation. For adding or modifying, use the Mobile Manager to modify these on the mobile server.

3. Within the mobile server, there are two types of user name/password combinations—both of which are created using the Mobile Manager UI: administrator and mobile user.

4. The mobile user provides its user name/password when synchronizing, which mobile server uses to verify that this use can access the application data. The mobile user name are stored in the mobile server repository. The password is stored in the repository only if external authentication is not used.

   Note:

   See Section 4.3.1.2.1, "Define User Name and Password" for conventions for creating the user name or password.

   - Modify the password on the client using the mSync UI. Only modify the password if you are connected to the mobile server to ensure that the user password change is propagated to the repository.

   - Modify the mobile user password in the Mobile Manager in the User Properties page. If you simply want to invalidate the mobile user, then you only have to modify the password on this screen; however, if you want to reset the password on both the mobile server and the user, then also send a Reset Password command from the Device Management section in the Mobile Manager to the mobile client. However, a Reset Password command can only modify the password if the client database is not encrypted. If the client database is encrypted, you can only modify the password with the mSync UI.

### 9.2.1 Modifying Repository Password

As described in number 1 in Section 9.2, "Which Password is Which?", the repository has its own user name/password combination. By default, the mobile server schema is `MOBILEADMIN`. However, if, during installation, you chose another name, replace `MOBILEADMIN` by your own schema name in the steps described in this section.

If you want to modify the password for your repository schema, perform the following:

1. Connect to your Oracle database where the mobile server repository was installed.

2. Change the password on the database with the ALTER command. The following command modifies the repository password to TEST:

       alter user mobileadmin identified by TEST;

3. Backup the `mobile.ora` file on the mobile server:

       cp $OL/Mobile/Server/bin/mobile.ora $OL/Mobile/Server/bin/mobile.ora_backup

4. Set the `admin_user` and `admin_password` parameters in the `mobile.ora` file to NULL since the password changed, as follows:

       ADMIN_USER=
       ADMIN_PASSWORD=

   We need to set these two parameters to a NULL value as the password change.

5. Restart the mobile server.

6. Go to the following URL: `http://mobileserver_hostname:Port/mobile/console/startup`

7. Log into thte mobile server using the new repository password. For our example, this password is `TEST`.

8. Click SAVE to save the mobile server repository user name and password.

   Note:

   This enables the auto start feature of the mobile server.

9. Check that the `admin_user` and `admin_password` parameters in the `mobile.ora` file have new values, as follows:

       ADMIN_USER=ySTIx5WLKLRb+cuRojIuWg==
       ADMIN_PASSWORD=tLuQlClPTlJ2powDoW7S9w==

## 9.3 Providing Security for the Mobile Client

Security for the mobile client involves securing access to the device through authentication and securing the data stored within the mobile client database. For full details on both issues, see Section 3.8, "Providing Security for the Mobile Client" in the Oracle Database Mobile Server Mobile Client Guide.

## 9.4 Configuring for Secure Socket Layer (SSL) Communication

Oracle Database Mobile Server supports Secure Socket Layer (SSL) communication between the mobile server and mobile clients. This chapter assumes that you understand the concepts behind SSL and provides only the steps for using keys and certificates for SSL communication for the mobile server.

- Section 9.4.1, "Creating an SSL Certificate"

- Section 9.4.2, "Configuring Mobile Server for SSL"

- Section 9.4.3, "Using Packaging Wizard For SSL-Enabled Mobile Server"

- Section 9.4.4, "Troubleshooting Error Messages for an SSL-Enabled Mobile Server"

- Section 9.4.5, "Support for Non-SSL Mobile Clients"

Note:

These are server-level steps which are typically executed prior to deployment of an application that requires SSL communication.

### 9.4.1 Creating an SSL Certificate

SSL communicates by validating an SSL certificate between the client and the server. This section describes how to ceate the SSL certificate. However, often when you are first starting with new functionality, you may want to use a temporary certificate just to see how the SSL functionality works.

Oracle Database Mobile Server ships a sample keystore file with a self-signed sample certificate. The password for this sample keystore file is `oracle`. Use this keystore only for development or testing purposes. Obtain a signature from a recognized certificate authority for all production systems. The test keystore is located in the following directory:

    ORACLE_HOME\Mobile\Server\Bin\samplekeystore

To create a keystore file, perform the following steps:

1. Use the Oracle Java `keytool` utility to generate a private key, public key, and an unsigned certificate. Place this information into either a new or existing keystore.

   Note:

   A keystore is a `java.security.KeyStore` instance that you create and manipulate using the `keytool` utility, which is provided with the Oracle JDK. See `http://download.oracle.com/javase/6/docs/technotes/tools/index.html#security` for more information on the `keytool` utility.

2. Obtain a signature for the certificate, using either of the following approaches:

   - Generate your own signature by using `keytool` to self-sign the certificate. This is appropriate only if your clients trust you as your own certificate authority.

   - Obtain a signature from a recognized certificate authority through the following steps:

   1. Using the certificate from Step 1, use `keytool` to generate a certificate request, which requests a certificate authority to sign the certificate.

   2. Submit the certificate request to a certificate authority.

   3. Receive the signature from the certificate authority and import it into the keystore using `keytool`. In the keystore, the signature is matched with the associated certificate.

If you install the mobile client using `setup.exe` after you create the self-signed certificate, a message pops up asking if you want to continue. If you click Yes, a parameter is added to the `devmgr.ini` that tells Oracle Database Mobile Server to not validate the certificate. However, if you install the mobile client using any other method, you need to either set the SSL disable parameter yourself or add the certificate in the trusted certificate list. These options are listed below:

- To disable the SSL check, set the SSL disable parameter: Set the `DISABLE_SSL_CHECK` parameter to true in the `devmgr.ini` file to 1 after the `[NETWORK]` section, as follows:

      [NETWORK]
       DISABLE_SSL_CHECK=true

- To allow this certificate to be validated, add or install the new certificate in the trusted certificate list. After completion, the certificate will be trusted.

  1. Open your browser and point it at the following site:

         https://<server>/mobile/setup

     Security alert displays.

  2. Click View Certificate.

  3. Click Install Certificate.

  4. Click Next-> Next-> Finish.

  When you next perform the synchronization, the synchronization is successful. This adds the Oracle Database Mobile Server in the trusted root certification authority.

  Note:

  If this is for testing only, then remove this certificate after testing is completed.

Each certificate authority has its own process for requesting and receiving signatures. Since this is outside the scope and control of Oracle Database Mobile Server, it is not covered in Oracle Database Mobile Server documentation. For more information, go to the Web site of any certificate authority. Each browser lists trusted certificate authorities. Here are the Web addresses for VeriSign, Inc. and Thawte, for example:

    http://www.verisign.com/
    http://www.thawte.com/

### 9.4.2 Configuring Mobile Server for SSL

Once you have a certificate, you must configure SSL on both the application server and the mobile server, as follows:

1. Configure SSL in the application server as documented in your application server documentation.

2. Configure SSL in the mobile server by adding `SSL=YES` in the `[MOBILE]` section of the `mobile.ora` file. In the Mobile Manager, migrate to the Administration tab and select Edit Config file. This is the `mobile.ora` file.

3. After all configuration is complete, restart the application server to initialize the changes.

Note:

If you have both SSL and non-SSL clients wanting to access the mobile server, you must configure it to be both SSL and non-SSL enabled.

### 9.4.3 Using Packaging Wizard For SSL-Enabled Mobile Server

If you enable the mobile server to be SSL-Enabled, then you have to change the configuration on the host where the Packaging Wizard is located in order for it to successfully communicate with the mobile server.

In order for Packaging Wizard to be SSL-Enabled, set the `SSL` parameter to `TRUE` in the `mobile.ora` file located on the host where the MDK is installed, as follows:

    [MOBILE]
    SSL=TRUE

### 9.4.4 Troubleshooting Error Messages for an SSL-Enabled Mobile Server

The following errors may occur when using SSL certificates on your mobile server:

No available certificate corresponds to the SSL cipher suites which are enabled
  Cause: Something is wrong with your certificate.
  Action: Examine your certificates and check that at least one of them supports the SSL cipher suite you are using.

IllegalArgumentException: Mixing secure and non-secure sites on the same ip + port
  Cause: You cannot configure SSL and non-SSL Web sites to listen on the same port and IP address.
  Action: Check to see that different ports are assigned.

### 9.4.5 Support for Non-SSL Mobile Clients

Y ou may have a non-SSL mobile client that you want to interact with your SSL enabled mobile server. For the case when you have both SSL and non-SSL mobile clients interacting with a mobile server, the mobile server must be configured in both SSL and non-SSL mode. See Section 9.4.2, "Configuring Mobile Server for SSL" for details.

## 9.5 Providing Your Own Authentication Mechanism for Oracle Database Mobile Server

You can provide an external authenticator for the mobile server to authenticate users with passwords as well as their access privileges to applications. For example, in an enterprise environment, you may have your user data, such as employee information, stored in a LDAP-based directory service. The mobile server can retrieve the user information from the LDAP directory—or from any custom User Management System—if configured with your own implementation of an external authenticator. The mobile server links the external user information to the mobile server repository.

For full details, see Section 7.1, "Providing Your Own Authentication Mechanism for Authenticating Users for the Mobile Server" in the Oracle Database Mobile Server Developer's Guide.

## 9.6 Using a Firewall Proxy or Reverse Proxy

Normally, the mobile client synchronizes data inside a firewall on the corporate intranet, where the mobile server also resides. However, what if the user wishes to synchronize the mobile client either from the internet, which is outside the firewall to a mobile server that exists inside the firewall? Or what if the mobile server exists on the public internet and the mobile client is inside the firewall on the corporate intranet? Either way, you have to modify your configuration to enable a mobile client and mobile server to communicate through a firewall.

One can think of many scenarios in which case mobile users want to connect to the corporate server, without being directly connected to the corporate intranet. The corporate firewall uses proxy support to allow the mobile user to connect to the server. The following sections describe how to configure the mobile server and mobile client to communicate through a firewall:

- Section 9.6.1, "Using a Reverse Proxy to Communicate from Internet to Intranet"

- Section 9.6.2, "Using HTTP Proxy to Communicate From Inside a Firewall"

### 9.6.1 Using a Reverse Proxy to Communicate from Internet to Intranet

If you are traveling to a customer site and you want to synchronize over the internet to the mobile server inside your corporate firewall, use a reverse proxy to communicate. A reverse proxy is used whenever a client outside a corporate network wants to connect to a resource available inside the corporate network, as shown in Figure 9-2. The corporate network is protected by a firewall, which stops the outside world from having direct access with the systems inside the corporate network. However, the reverse proxy enables designated traffic that originates outside the corporate network to reach servers inside the corporate intranet.

Figure 9-2 Mobile Client Communicating With Mobile Server Through Firewall Using Reverse Proxy

Description of "Figure 9-2 Mobile Client Communicating With Mobile Server Through Firewall Using Reverse Proxy"

When you configure the reverse proxy, then the mobile client communicates directly with the reverse proxy, which turns around and communicates with the mobile server.

Note:

Reverse proxy can be used with or without authentication. Using authentication is recommended for better security and access control to the inside of the firewall. The authentication is supported only if mobile client's user name and password are identical to those of the reverse proxy.

In order for this communication to occur seamlessly, do the following:

- Section 9.6.1.1, "Configure the Apache Web Server as a Reverse Proxy"

- Section 9.6.1.2, "Set Up Mobile Server for Mobile Client Download"

- Section 9.6.1.3, "Download Reverse Proxy Mobile Client"

- Section 9.6.1.4, "Enable SSL When Using a Reverse Proxy"

- Section 9.6.1.5, "Configure Device Management to Work With a Firewall"

#### 9.6.1.1 Configure the Apache Web Server as a Reverse Proxy

You need to set up the Apache Web Server software for the reverse proxy, as follows:

1. First, use Apache 2.0 or later for your proxy.

2. Configure the proxy server to point to the mobile server. See the Apache Web Server documentation for instructions on how to do so.

3. Set the following parameter in the `httpd.conf` configuration file:

       BrowserMatch MSIE AuthDigestEnableQueryStringHack=On

4. When you use reverse proxy authentication, you must upper-case the user name of the proxy digest.

5. If you are using authentication, then configure the Reverse Proxy with the user name/passwords for all mobile clients that will access this reverse proxy for synchronization.

   When the mSync is launched, the user name/password is sent automatically to the reverse proxy for authentication; thus, if the reverse proxy is not configured with the user name/password, then the connection is refused.

#### 9.6.1.2 Set Up Mobile Server for Mobile Client Download

If you know that the mobile client is going to be accessing the mobile server through a reverse proxy, you need to configure mobile server with the proxy server URL. This ensures that when the `setup.exe` is downloaded by the client, that the client is automatically configured with the reverse proxy URL, instead of the mobile server URL.

So, before you download `setup.exe` to the mobile client, perform the following on the mobile server:

1. If your server is a Windows XP machine, you must have the Service Pack 2 installed.

2. Configure the mobile server to accept communication from the reverse proxy.

   Configure the `reverse_proxy` parameter in the `mobile.ora` configuration file on the mobile server, as follows:

       [MOBILE]
       REVERSE_PROXY=http://<reverse_proxy_hostname>:<port_number>/mobile

#### 9.6.1.3 Download Reverse Proxy Mobile Client

After you have updated the mobile server with the proper reverse proxy configuration, perform the following on the client:

1. Configure the mobile client to communicate with the reverse proxy in one of the two following methods:

   - If you configured the mobile server as described in Section 9.6.1.2, "Set Up Mobile Server for Mobile Client Download", then you can download the mobile client software directly from the setup UI. The configuration automatically points to the reverse proxy when you perform the installation of the mobile client.

   - However, if you installed the mobile client software from within the corporate intranet or you have a client already installed on a machine, you must modify its configuration. Modify the `devmgr.ini` configuration file for your mobile client. Change or add the `SERVER_URL` parameter in the `NETWORK` section of the `devmgr.ini` configuration file to point to the host/port of the reverse proxy server, as follows:

         SERVER_URL=HTTP://<reverse_proxy_host>:<port>/mobile

     If you use the `msync.exe` to synchronize, then enter the hostname of the reverse proxy in the Server box.

     Note:

     If you are planning on using the mobile client both inside and outside of the corporate internet, you may want to have two `SERVER_URL` definitions—one for the internal corporate mobile server address and one for the reverse proxy address. Then, comment the one that you are not using and uncomment the one that you are using.

2. Perform post-installation steps for the mobile client:

   If the mobile client is a Windows client—such as Windows XP/2000 and WinCE devices—then Oracle Database Mobile Server uses the WININET API for SSL over HTTP.

   The following are known issues when using SSL over HTTP:

   - The HTTP connection may slow down if you have the `Auto Detect Proxy` enabled in the Internet Explorer. In addition, it may also slow down if you do not have a proxy server in your network. In this case, uncheck the `Automatically detect proxy` option in the Internet Explorer.

   - For Windows 2000 clients, mSync may hang if you do not have all of the Microsoft patches applied.

   - If your mobile server or reverse proxy does not have a valid SSL certificate, then the Oracle Database Mobile Server clients may stop working. This is critical if there are errors in certificate chaining. See Section 9.6.1.4, "Enable SSL When Using a Reverse Proxy" for details.

   You may get "Unsuccessful http response: HTTP/1.1 408 Request Time-out" error in bglog log0.xml. This is caused by an open bug for Apache Http server.

#### 9.6.1.4 Enable SSL When Using a Reverse Proxy

Normally, when you have a browser and you specify HTTPS for the connection between the browser and a reverse proxy, then the browser prompts for a user name/password for authentication. However, with msync, a browser is not displayed. Instead, msync sends on the user name/password for the user to the reverse proxy. Thus, you must have your environment configured correctly or the connection fails.

The following describes several scenarios that you may have between the mobile client and the reverse proxy:

- Section 9.6.1.4.1, "Using SSL Authentication"

- Section 9.6.1.4.2, "Using SSL Between Mobile Client and Reverse Proxy"

- Section 9.6.1.4.3, "Using SSL Between Firewall and Mobile Server"

- Section 9.6.1.4.4, "Using Certificates That Are Not Signed By Trusted Authority"

##### 9.6.1.4.1 Using SSL Authentication

When you are using a reverse proxy firewall, SSL client authentication is not supported. You can only turn on server-side HTTPS authentication.

##### 9.6.1.4.2 Using SSL Between Mobile Client and Reverse Proxy

As Figure 9-3 demonstrates, you may want to encrypt your data and authenticate using SSL when using a reverse proxy.

Figure 9-3 Mobile Client Communicating Over SSL Through Firewall Using Reverse Proxy

Description of "Figure 9-3 Mobile Client Communicating Over SSL Through Firewall Using Reverse Proxy"

In this case, you must install the SSL certificate on the firewall for the SSL handshake between the mobile client and the firewall. If you are using a certificate that is not signed by a trusted authority or if you want to disable SSL authentication, see Section 9.6.1.4.4, "Using Certificates That Are Not Signed By Trusted Authority".

##### 9.6.1.4.3 Using SSL Between Firewall and Mobile Server

As Figure 9-4 demonstrates, you may want to encrypt your data and authenticate using SSL when using a reverse proxy for all communication between the mobile client and the mobile server. In this case, you would configure SSL between the mobile client and the firewall; as well as configure SSL between the firewall and the mobile server.

Figure 9-4 Mobile Client Communicating Over SSL Through Firewall Using Reverse Proxy

Description of "Figure 9-4 Mobile Client Communicating Over SSL Through Firewall Using Reverse Proxy"

In this case, you need to create a chained certificates with the following two certificates:

- A certificate for the connection between the mobile client and the reverse proxy firewall.

- A certificate for the connection between the reverse proxy firewall and the mobile server.

Perform the following:

1. Create a chained SSL certificate that contains both the certificates from the reverse proxy followed by the certificate for the mobile server.

2. Install this certificate on the reverse proxy firewall for the mobile client handshake.

In general, install the chained certificate on the firewall for the SSL handshake between the mobile client and the firewall.

##### 9.6.1.4.4 Using Certificates That Are Not Signed By Trusted Authority

You can use certificates that are not signed by a trusted authority, such as a self-signed certificate, on the mobile server. In this case, set the following parameter in the `NETWORK` section in the `devmgr.ini` (`devmgr.txt`) file on the client device:

    DISABLE_SSL_CHECK=YES

This parameter enables the client to use the self-signed certificate for SSL encryption, but not to perform SSL authentication.

#### 9.6.1.5 Configure Device Management to Work With a Firewall

We use device management to send commands to devices for updates, initiating synchronization, as well as other commands. Device management uses HTTP as its communication protocol. So, if a firewall is in between the device and the mobile server, you must perform some configuration to enable device management communication.

There are two types of device management requests:

- Device initiated: The Device Manager agent (dmagent), which is included on the mobile device, registers with the mobile server at device bootstrap. This is known as HTTP PULL, since the mobile device polls the mobile server for any outstanding commands. The dmagent periodically polls the mobile server for command requests on the mobile server listening port.

- Oracle Database Mobile Server initiated: This is known as HTTP PUSH, since the mobile server sends the commands directly to the mobile device. You can send commands to one or more devices through the Mobile Manager or Java APIs. However, this is unusual, since most communication/synchronization is initiated from the client. Thus, the proxy must be configured correctly to enable communication initiated from the mobile server.

The following describes how to configure your mobile server to enable device management requests to a mobile server that resides behind a firewall:

- Section 9.6.1.5.1, "Configure Mobile Device Listening Port"

- Section 9.6.1.5.2, "Firewall Configuration"

- Section 9.6.1.5.3, "Proxy Configuration for the Mobile Server"

##### 9.6.1.5.1 Configure Mobile Device Listening Port

In the mobile server initiated scenario, the mobile device has a listener with which the mobile server connects. Thus, the mobile server communicates with the dmagent listening port. The dmagent on the mobile device, by default, listens on port 8521, which is configured in the `PUSH_PORT` parameter.

For all future client installations, you may modify the `PUSH_PORT` for all the clients by using Mobile Manager in the Mobile Devices -> Administration -> Configuration Management page. This change affects only the client installations that are performed after the modification.

##### 9.6.1.5.2 Firewall Configuration

Your firewall should be configured so that HTTP traffic is enabled in the following manner:

- The dmagent on the mobile device should be able to access the `SERVER_PORT` on the firewall.

- The mobile server should be able to access the `PUSH_PORT` of all devices.

##### 9.6.1.5.3 Proxy Configuration for the Mobile Server

If the mobile server is behind the firewall, it can only access mobile devices through a proxy. To configure the proxy server information in the metadata of the HTTP provider, navigate to Mobile Devices -> Administration -> Network Management -> HTTP in the Mobile Manager.

The metadata is any user-defined string that is required by the Java class during initialization. The HTTP provider metadata is a sequence of name-value pairs, where the name and value are separated by and equals sign ('='). Each pair is separated by the ampersand ('&'). This setting is effective when you send commands from a standalone Java program using device management APIs.

The following example adds the `PROXY` name-value pair with the proxy URL into the metadata after the `TIMEOUT` name-value pair:

    TIMEOUT=30&PROXY=http://proxy.foo.com:8080

### 9.6.2 Using HTTP Proxy to Communicate From Inside a Firewall

Use the HTTP proxy for clients inside a corporate network that want to connect to a resource on the Internet. As shown in Figure 9-5, the corporate network is protected by a firewall, which blocks direct access from inside the corporate network to the outside world. However, you can configure a proxy server on the firewall to allow designated traffic travel through the firewall.

As demonstrated by Figure 9-5, A mobile user may wish to use a public Internet connection to connect to the corporate network, using one of the many available wireless 802.11 hotspots.

Figure 9-5 Client Accessing Mobile Server on Internet

Description of "Figure 9-5 Client Accessing Mobile Server on Internet"

If the mobile client is located in the corporate intranet and the mobile server is located somewhere in the public Internet—where both are separated by a firewall—then the firewall must be configured to let HTTP traffic travel through by means of a proxy server.

To enable communication from the mobile client to a mobile server outside the corporate firewall, perform one of the following:

Note:

You may be able to set up the proxy for communication originated from the client in this scenario; however, we do not support server-initiated device management requests in this scenario.

- Section 9.6.2.1, "Proxy Configuration for Mobile Clients"

- Section 9.6.2.2, "Proxy Configuration for the Device Manager Agent"

- Section 9.6.2.3, "Reverse Proxy Configuration for HTTP PUSH from Mobile Server Not Supported"

#### 9.6.2.1 Proxy Configuration for Mobile Clients

For all mobile clients, perform the following when you synchronize using the `msync.exe` tool:

1. Check the Use Proxy checkbox.

2. Enter the hostname and port number of the proxy server.

#### 9.6.2.2 Proxy Configuration for the Device Manager Agent

The mobile device is behind the firewall and can access the outside world (mobile server) only by using a proxy. At the time of client installation, the setup program prompts the user for the proxy information.

If you configured the proxy after the client installation, then you can configure dmagent to use the proxy server by adding `HTTP_PROXY` parameter under the `NETWORK` section including both the IP/hostname and port number to the `devmgr.ini` file, as follows:

    HTTP_PROXY=proxy.foo.com:8080

#### 9.6.2.3 Reverse Proxy Configuration for HTTP PUSH from Mobile Server Not Supported

In this scenario, the mobile server could only initiate communication with a mobile device behind a firewall through a reverse proxy. However, a reverse proxy would have to be configured for each mobile device behind the firewall. This is too intensive, so we do not support mobile server initiated communication, which includes the HTTP PUSH Device Management communication.

## 9.7 Providing SSL Client Authentication with a Common Access Card

Oracle Database Mobile Server supports client authentication for synchronization of data over SSL-based connections between a mobile client and the mobile server. The client authentication is based on X.509 certificates that can be stored in a Common Access Card (CAC).

Note:

Encryption of client data with a CAC for databases on either mobile client is not supported.

The following sections describe how to enable client authentication in Oracle Database Mobile Server for Common Access Cards:

- Section 9.7.1, "Introduction to SSL Client Authentication"

- Section 9.7.2, "Smartcard and Common Access Card Overview"

- Section 9.7.3, "Oracle Database Mobile Server Supports Common Access Cards"

- Section 9.7.4, "Supported Platforms for the Common Access Card"

- Section 9.7.5, "Prerequisites for Common Access Card"

- Section 9.7.6, "Configuration for Client Authentication Using the Common Access Card"

- Section 9.7.7, "Using the Common Access Card"

### 9.7.1 Introduction to SSL Client Authentication

Secure Sockets Layer (SSL) is a security protocol that enables secure and authenticated data transfer over a network between a server and a client. During the connection setup, the server is always authenticated using a public key certificate. The client connects to the server only after establishing its identity based on the certificate.

The server may also choose to authenticate the client by asking for a client certificate. With client authentication enabled, the server requests a certificate from the client to verify that the client is who it claims to be. The certificate that the client sends must be an X.509 certificate and signed by a Certifying Authority (CA) that is trusted by the server. The server allows the connection if the client's certificate can be trusted.

### 9.7.2 Smartcard and Common Access Card Overview

SSL Client authentication requires that all users have their own X.509 certificate. There are several methods for users to store and manage certificates. One method is to store the certificates on a Common Access Card.

A Smartcard is a pocket-sized card with embedded integrated circuits that store and process data. A Common Access Card (CAC) is a Smartcard with additional software that enables you to securely store and manage security certificates and keys on the card, which are used for authentication. The data on the CAC is secured by a password or pin number. When the user connects to a server or system that requires authentication, the user is prompted for the password. The certificates and keys residing on the card are used to authenticate the user.

The CAC is used to authenticate users for access to computers and facilities. The CAC also enables encrypting and cryptographically signing email, uses PKI authentication tools, and establishes identity credentials. The certificates are stored in X.509 format on the CAC, and can be accessed by software running on a host machine through a card reader.

For example, the following describes what happens if a user browses a Web site that requires the client side certificate:

1. Open a browser and navigate to the Web site. The browser prompts for the pin number of the CAC.

2. After the user provides the correct pin, a CAC session is created. This enables all applications running on the machine to access the card and read the necessary certificates and keys. In case there is more than one certificate on the card that the server will accept, then the user is prompted to select which certificate to use.

3. By default, the CAC session expires after a configurable amount of time, after which the user must provide the pin number again.

For Oracle Database Mobile Server, the CAC is used to authenticate the client to the mobile server when requested before synchronization or any other type of communication between the client and the mobile server.

### 9.7.3 Oracle Database Mobile Server Supports Common Access Cards

Oracle Database Mobile Server supports client authentication over SSL connections using client side certificates and keys residing on the CAC. Oracle Database Mobile Server supports the ActivIdentity card. When the user supplies the CAC, the user also enters a pin number to retrieve the certificate and corresponding private key from the CAC. If the pin number is correct, data on the card can be accessed for a configurable period of time, known as the idle timeout that is set in the CAC software.

Note:

To set the idle timeout for the authenticated sessions, use the User Console in the ActivIdentity software. The idle timeout defaults to 15 minutes.

When the pin number is verified, then access to the certificates and keys on the card is provided either to only the process that prompted the user to enter the pin number or to all of the user's processes running on the machine. For all components of the mobile client to work properly, the authentication must be shared among processes. See Section 9.7.6.2.1, "Sharing Authentication Acceptance Across Processes" for details.

### 9.7.4 Supported Platforms for the Common Access Card

The client authentication feature enabled for Oracle Database Mobile Server uses the CAC, which is supported only on the Win32 platform.

Note:

At this point, client authentication is not supported on Windows CE, Windows Mobile or any UNIX platforms.

The components that must use the CAC when client authentication is requested are those that communicate with the mobile server. These are as follows:

- Mobile client

- Device Manager Agent

- Automatic Sync agent

- Packaging Wizard on Windows platform

MDW is not supported. Since MDW does not support SSL/HTTPS, it cannot provide client authentication over SSL.

#### 9.7.4.1 Support for Mobile Clients That Are Not Enabled for Client Authentication

A mobile server that is configured for client authentication will only interact with mobile clients that are enabled for client authentication. Enabling client authentication on the mobile server is optional. Thus, if you do not turn it on, both clients with and without CAC can communicate with the mobile server without having to present a certificate.

### 9.7.5 Prerequisites for Common Access Card

You must install the software provided by the Common Access Card vendor to access the data on the card on each mobile client. This is required in order to access keys and certificates on the CAC. Refer to the vendor documentation on how to install this software.

### 9.7.6 Configuration for Client Authentication Using the Common Access Card

The following sections describe how to configure for client authentication:

- Section 9.7.6.1, "Configuration of the Mobile Server to Request Client Authentication"

- Section 9.7.6.2, "Configuration of the Mobile Client to Use a CAC"

- Section 9.7.6.3, "Configuration for Reverse Proxy and Load Balancer"

#### 9.7.6.1 Configuration of the Mobile Server to Request Client Authentication

To configure the mobile server to request client authentication, perform the following:

1. Configure for SSL on the mobile server as described in Section 9.4, "Configuring for Secure Socket Layer (SSL) Communication".

2. Enable client authentication and install the certificate on the application server.

3. For the SSL connection to be established, the mobile server must have the certificate of the signing authority (CA), which signed the certificates present in the CACs. Import the CA certificate in the same keystore that you have used for storing the server certificate, as described in Section 9.4, "Configuring for Secure Socket Layer (SSL) Communication".

   The following is an example of how to import the certificate using the `keytool` executable:

       keytool.exe –keystore <samplekeystore> -storepass <oracle>
        -import –alias clientCACert –file <CACert.crt>

4. Modify the `pkcs11.cfg` file on the mobile server before you install the client with the correct path to the CAC library on the client. The PKCS11 configuration file defaults with the following entry:

       library = C:\WINDOWS\system32\acpkcs11.dll

   Note:

   Verify that this entry refers to the correct PKCS11 library provided by the CAC vendor on the client.

5. Restart the mobile server to reinitialize with the new modifications.

#### 9.7.6.2 Configuration of the Mobile Client to Use a CAC

If you have configured mobile server to request client authentication, as described in Section 9.7.6.1, "Configuration of the Mobile Server to Request Client Authentication", then any `setup.exe` downloaded for a new mobile client automatically installs a mobile client enabled for handling certificates and keys from a CAC.

However, if the PKCS11 library location is different on the client than what is specified in the pkcs11.cfg file on the mobile server, as described in Section 9.7.6.1, "Configuration of the Mobile Server to Request Client Authentication", then modify the PKCS11 configuration file on the client to point to the correct directory.

The configuration file location is specified with the `PKCS11_CONFIG_FILE` parameter in the `%INSTALL_DIR%\bin\mobile.ora` file. The default configuration file is `%INSTALL_DIR%\bin\pkcs11.cfg`. Change the library property in the configuration file to refer to the correct library, as follows:

    library = <Full path to PKCS11 library>

##### 9.7.6.2.1 Sharing Authentication Acceptance Across Processes

Client authentication sessions can be shared across processes belonging to the same user. Thus, if one process prompts the user for the pin number to read data from the CAC, a second process can also access the CAC without providing the pin number again--as long as the sesson is not expired.

You can control whether authentication is provided for all processes for the user or not through the Pin Caching Service.

On the ActivIdentity card, perform the following:

1. Select the Pin Caching Service through the following pull-down: Tools -> Advanced -> Configuration -> PIN Caching Service.

2. Select NO in the "Allow per process PIN caching" field.

#### 9.7.6.3 Configuration for Reverse Proxy and Load Balancer

Configuration for the reverse proxy and load balancer are described in Section 9.6, "Using a Firewall Proxy or Reverse Proxy". However, you must configure the reverse proxy and load balancer to require and accept the client certificates and to be able to validate the client's certificates. In addition, the reverse proxy and load balancer must create an SSL connection to the mobile server using the client authentication.

The mobile server must be configured to accept the client authentication from the reverse proxy or load balancer.

### 9.7.7 Using the Common Access Card

If no CAC session is established yet, then--in most cases--the user is prompted for the CAC pin number to create a CAC session. The cases where the user may not be prompted are for the background processes: the Device Manager agent (dmagent) and the Sync Agent, which is the agent for automatic synchronization.

The Oracle Database Mobile Server dmagent acts both as an HTTP client when communicating with the mobile server and as an HTTP server when receiving DM commands over HTTP. The dmagent supports SSL over HTTP when acting as a client and supports client authenticated SSL connections.

If the background processes—the dmagent and the Sync Agent—start when the CAC session is already available, then the connection succeeds. However, once the CAC session expires, then the following may occur:

- If the CAC card is in the card reader, then the background processes prompt for the user pin.

- If the CAC card is not in the card reader, then the processes fail silently and a log error is written into `cac_log.txt` file.

Note:

The SSL certificate or keys should not be stored in the database or any other persistence location on the mobile client.

## 9.8 Security Warning for Demo Applications

If you have the demo applications installed in a production environment, they can be used to access areas of Oracle Database Mobile Server that you may want to be secure. The demo applications are provided for you to use when learning how to develop your own application. Thus, when you are finished developing your product, remove the demo applications from the repository. For directions, see Chapter 4, "Installation of Oracle Database Mobile Server" in the Oracle Database Mobile Server Installation Guide.