4.2. Phone Home

The Enterprise Security Client offers a feature called Phone Home that associates information within each smart card with information which points to distinct TPS servers and Enterprise Security Client UI pages. Whenever the Enterprise Security Client accesses a new smart card, it connects to the TPS server and retrieves the Phone Home information.

Phone Home quickly 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 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 find the proper 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:

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

Since the Enterprise Security Client is based on Mozilla XULRunner, each user has a profile similar to the user profiles used by Mozilla Firefox or 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.

The Phone Home information is put on the 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 formating small groups of tokens.

The following information is used by the Phone Home feature for each smart card:

The TPS server and port. For example:

"esc.key.40900062ff020000ba87.tps.url" =
 "http://tps.example.com:12443//nk_service"

The TPS enrollment interface URL. For example:

"esc.key.40900062ff020000ba87.tps.url" =
 "http://tps.example.com:12443/cgi_bin/esc.cgi?"

The issuing company name or ID. For example:

"esc.key.40900062ff020000ba87.issuer.name" = "Example Corp"

The Phone Home URL. For example:

"esc.key.40900062ff020000ba87.phone.home.url" =
 "http://tps.example.com:12443/phone_home/phone_home.cgi?"

Optionally, a default browser URL to access when an enrolled smart card is inserted.

"esc.key.40900062ff020000ba87.EnrolledTokenBrowserURL" =
"http://www.test.example.com"

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. Example 4.1, “TPS Phone Home Configuration File” shows an example XML file used by the TPS subsystem to configure the Phone Home feature.

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

Example 4.1. TPS Phone Home Configuration File

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.

If no Phone Home information is stored on the token, the the user is prompted for the Phone Home URL, 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

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 https://test.example.com:12443/cgi-bin/home/index.cgi. 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.

The Test button can be used to test of the entered URL. If the server is successfully contacted, a message box indicates success. If the test connection fails, an error dialog appears.