4.3. Configuring Phone Home

The Phone Home feature in the Enterprise Security Client associates information within each smart card with information that points to distinct TPS servers and Enterprise Security Client UI pages. Whenever the Enterprise Security Client accesses a new smart card, it can connect to the TPS instance and retrieve the Phone Home information.

Phone Home retrieves and then caches this information; because the information is cached locally, the TPS subsystem does not have to be contacted each time a formatted smart card is inserted.

The information can be different for every key or token, which means that different TPS servers and enrollment URLs can be configured for different corporate or customer groups. Phone Home makes it possible to configure different TPS servers for different issuers or company units, without having to configure the Enterprise Security Client manually to locate the correct server and URL.

NOTE

In order for the TPS subsystem to utilize the Phone Home feature, Phone Home must be enabled in the TPS configuration file, as follows:

op.format.userKey.issuerinfo.enable=true
op.format.userKey.issuerinfo.value=http://server.example.com

4.3.1. About Phone Home Profiles

The Enterprise Security Client is based on Mozilla XULRunner. Consequently, each user has a profile similar to the user profiles used by Mozilla Firefox and Thunderbird. The Enterprise Security Client accesses the configuration preferences file. When the Enterprise Security Client caches information for each token, the information is stored in the user's configuration file. The next time the Enterprise Security Client is launched, it retrieves the information from the configuration file instead of contacting the server again.

4.3.2. Setting Global Phone Home Information

Phone Home is triggered automatically when a security token is inserted into a machine. The system immediately attempts to read the Phone Home URL from the token and to contact the TPS server. For new tokens or for previously formatted tokens, the Phone Home information may not be available to the card.

The Enterprise Security Client configuration file, esc-prefs.js, has a parameter which allows a global Phone Home URL default to be set. This parameter is esc.global.phone.home.url and is not in the file by default.

To define the global Phone Home URL:

Remove any existing Enterprise Security Client user profile directory. Profile directories are created automatically when a smart card is inserted. By default, the profile directory is ~/.redhat/esc.
Open the esc-prefs.js file.
On Red Hat Enterprise Linux 6.0, the profile directory is /usr/lib/esc-1.1.0/defaults/preferences. On 64-bit systems, this is /usr/lib64/esc-1.1.0/defaults/preferences.
Add the global Phone Home parameter line to the esc-prefs.js file. For example:
```
pref("esc.global.phone.home.url","http://server.example.com:7888/cgi-bin/home/index.cgi");
```
The URL can reference a machine name, a fully-qualified domain name, or an IPv4 or IPv6 address, depending on the DNS and network configuration.

When a smart card is inserted and Phone Home is launched, the Enterprise Security Client first checks the token for the Phone Home information. If no information is on the token, then the client checks the esc-prefs.js file for the esc.global.phone.home.url parameter.

If no Phone Home information is stored on the token and there is no global Phone Home parameter, the user is prompted for the Phone Home URL when a smart card is inserted, as shown in Figure 4.1, “Prompt for Phone Home Information”. The other information is supplied and stored when the token is formatted. In this case, the company supplies the specific Phone Home URL for the user. After the user submits the URL, the format process adds the rest of the information to the Phone Home profile. The format process is not any different for the user.

Figure 4.1. Prompt for Phone Home Information

4.3.3. Adding Phone Home Information to a Token Manually

The Phone Home information can be manually put on a token in one of two ways:

The preferred method is that the information is burned onto the token at the factory. When the tokens are ordered from the manufacturer, the company should also supply detailed information on how the tokens should be configured when shipped.
If tokens are blank, the company IT department can supply the information when formatting small groups of tokens.

The following information is used by the Phone Home feature for each smart card in the ~/.redhat/esc/alphanumeric_string.default/prefs.js file:

The TPS server and port. For example:

"esc.key.token_ID.tps.url" = "http://server.example.com:7888/nk_service"

The TPS enrollment interface URL. For example:

"esc.key.token_ID.tps.enrollment-ui.url" = "http://server.example.com:7888/cgi_bin/esc.cgi?"

The issuing company name or ID. For example:

"esc.key.token_ID.issuer.name" = "Example Corp"

The Phone Home URL. For example:

"esc.key.token_ID.phone.home.url" = "http://server.example.com:7888/cgi-bin/home/index.cgi?"

Optionally, a default browser URL to access when an enrolled smart card is inserted.
```
"esc.key.token_ID.EnrolledTokenBrowserURL" = "http://www.test.example.com"
```

More of the parameters used by the prefs.js file are listed in Table 4.3, “prefs.js Parameters”.

NOTE

The URLs for these parameters can reference a machine name, a fully-qualified domain name, or an IPv4 or IPv6 address, depending on the DNS and network configuration.

4.3.4. Configuring the TPS to Use Phone Home

The Phone Home feature and the different type of information used by it only work when the TPS has been properly configured to use Phone Home. If the TPS is not configured for Phone Home, then this feature is ignored. Phone Home is configured in the index.cgi in the /var/lib/pki-tps/cgi-bin/home directory; this prints the Phone Home information to XML.

Example 4.2, “TPS Phone Home Configuration File” shows an example XML file used by the TPS subsystem to configure the Phone Home feature.

Example 4.2. TPS Phone Home Configuration File

<ServiceInfo><IssuerName>Example Corp</IssuerName>
    <Services>
        <Operation>http://server.example.com:7888/nk_service ## TPS server URL
        </Operation>
        <UI>http://server.example.com:7888/cgi_bin/esc.cgi   ## Optional
Enrollment UI
        </UI>
        <EnrolledTokenBrowserURL>http://www.test.url.com   ## Optional
enrolled token url
        </EnrolledTokenBrowserURL>
    </Services>
</ServiceInfo>

The TPS configuration URI is the URL of the TPS server which returns the rest of the Phone Home information to the Enterprise Security Client. An example of this URL is http://server.example.com:7888/cgi-bin/home/index.cgi; the URL can reference the machine name, fully-qualified domain name, or an IPv4 or IPv6 address, as appropriate. When the TPS configuration URI is accessed, the TPS server is prompted to return all of the Phone Home information to the Enterprise Security Client.

To test the URL of the Smart Card server, enter the address in the TPS Config URI field, and click Test URL.

If the server is successfully contacted, a message box indicates success. If the test connection fails, an error dialog appears.