9.3. Performing Agent Tasks

Agents perform two important management tasks for tokens: setting the token status and setting the token policies. They can also edit the token information, search certificates, and search activities.

IMPORTANT

A user can only see entries relating to the profile configured for it. This means that all results are filtered by the profiles that the user can view, including listing and searching for certificates, tokens, or activities.
Setting profiles for users is described in Section 9.4.2.3, “Setting Profiles for Users”.
Agent Tasks

Figure 9.6. Agent Tasks


9.3.1. Searching Tokens

To look for all tokens, a subset of tokens, or a specific token, click the List/Search Tokens link, and fill in the name of the user or the whole or partial token identification number (CUID). Asterisks (*) can be used in the search fields as wildcards.

NOTE

A user can only see entries relating to the profile configured for it, including both token operations and tokens themselves. For an agent to be able to see a certain token or group of tokens, then the agent user entry must be configured to view that token profile.
Setting profiles for users is described in Section 9.4.2.3, “Setting Profiles for Users”.
Searching for Tokens

Figure 9.7. Searching for Tokens


There is a maximum allowed number of search results configured for the TPS Directory Server database, so the number of entries returned is constrained by the search limit. Each results page shows 25 records.

9.3.2. Viewing Tokens

After searching for tokens, click the link of the token ID to view the token information.
The token information shows the current definition and state of the token:
  • Token, the token ID number entered in the TPS.
  • User ID, user of the token.
  • Status and Reason, the current state of the token.
    • uninitialized means the token has not been processed
    • initialized means that the smart card is formatted, but does not have any certificates enrolled on it
    • enrolled means that certificates have been installed on it
    • lost or onHold means it has been suspended, and any suspended or revoked token also has an attribute to show the reason why the token status was changed
  • Policy, which sets the user policies for the token, such as whether the token can be reused.
  • Token Type, which is the enrollment profile which is used to enroll the token.
The system information shows information about the token that is processed by the TPS:
  • Key Info, the types of keys and bit strength generated for the token
  • Applet ID, the applet loaded on the token
  • Creation Date and Modification Date, which shows the days that the token was first entered in the TPS and the most recent change to the token
Additionally, there are two other sets of information that can be viewed for the token.
  • Clicking the Show Certificates button lists the certificates which are stored on the token.
  • Clicking the Show Activities button lists the operations which have been performed on the token.
The agent can also edit the token, as described in Section 9.3.3, “Managing Tokens”.

9.3.3. Managing Tokens

When viewing a token, an agent can edit the token information, change the token status, and set policies for the token.

NOTE

A user can only see entries relating to the profile configured for it, including both token operations and tokens themselves. For an agent to be able to see a certain token or group of tokens, then the agent user entry must be configured to view that token profile.
Setting profiles for users is described in Section 9.4.2.3, “Setting Profiles for Users”.
Managing Tokens

Figure 9.8. Managing Tokens


9.3.3.1. Editing the Token Information

At the bottom of the token information screen, there is an Edit button. Two fields can be edited for the token: the user name of the user with whom the token is associated and the token policy.
Editing the Token Information

Figure 9.9. Editing the Token Information


9.3.3.2. Changing the Token Policy

The policy sets rules on what the user can do after the token is enrolled.
There are four supported token policies:
  • RE_ENROLL, which allows a user to re-enroll certificates with the same token
  • PIN_RESET, which allows the token user to initiate a PIN reset operation
  • RENEW, which allows a user to regenerate their existing certificates using the original key and an extended validity period
  • FORCE_FORMAT, which causes every enrollment operation to prompt a format operation. This is a last-step option to allow tokens to be reset without a user having to return it to an administrator.

    IMPORTANT

    If this policy is set, then this should be the only token policy configured. This takes precedence over any other policy.
The supported token policies accept values of either YES or NO. To set both policies, separate them with a semi-colon. For example:
RE_ENROLL=NO;PIN_RESET=YES
The default values is for the RE_ENROLL and PIN_RESET parameters to be set to YES.
If both RE_ENROLL and RENEW are set to YES, then the renewal setting takes precedence, the token certificates are renewed when they expire.

NOTE

If the PIN_RESET policy is not set, then user-initiated PIN resets are allowed by default. If the policy is present and is changed from NO to YES, then a PIN reset can be initiated by the user once; after the PIN is reset, the policy value automatically changes back to NO.
To edit the policy settings, search for the token, and click its ID link.
Editing the Token Policy

Figure 9.10. Editing the Token Policy


9.3.3.3. Changing Token Status

Agents can change the status of the token. Token status affects key recovery policies; the status of the token impacts whether a key should be recovered from the DRM or reissued, whether new tokens will be blocked because there are already active existing tokens, and whether to issue or revoke temporary tokens.
The status is changed through the token details page, which is shown by searching for tokens and then selecting a token from the returned list.
To change the status, select the menu item, and click Go.
Changing Status

Figure 9.11. Changing Status


There are six possible token statuses. A status is only active in the drop-down menu of the transition from the current status is allowed. For example, a token should not logically be allowed to move from a permanently lost status to a found status, so this option is grayed out in the menu.

NOTE

Moving from one status to another is a transition. Only certain transitions are allowed; for example, an administrator can block a token that is marked as permanently lost from ever being marked again as active. The allowed token transitions are set by an administrator in the TPS's CS.cfg file in the tokendb.allowedTransitions parameter. For information on setting status transitions for tokens, see the Administrator's Guide.

Table 9.1. Token Statuses

Status Meaning Action
The token is physically damaged. The TPS revokes the user certificates and marks the token lost. The original certificates are revoked, and new certificates for the user can be generated on a new token.
The token has been permanently lost. The TPS revokes the user certificates and marks the token lost. The original certificates are revoked, and new certificates for the user can be generated on a new token.
The token is temporarily lost or unavailable. The TPS puts the user certificates on hold and marks the token inactive. The original certificates are suspended and put on hold (meaning they cannot be used until the status changes). New, temporary certificates for the user can be generated on a new token.
The lost token has been found. The TPS takes the certificates off hold and marks the token active. The temporary certificates are revoked, and the original certificates are taken off hold.
The lost token cannot be found (permanently lost). The TPS revokes the certificates and marks the token lost. The temporary certificates and the original certificates are revoked, and new certificates for the user can be generated on a new token.
This token has been terminated. The TPS terminates the token. Terminating a token terminates the certificates and keys on the token and breaks the association between the token and the user in the token database. The physical token can still be formatted and reused afterward, but this change of status will mark a record of the termination event. The original certificates are revoked. The token itself can be reused and enrolled for new users or certificates.

Changing the status of the token to anything other than active has two possible actions. If the token is permanently taken offline (permanently lost, damaged, or terminated), then the certificates on the token are revoked and the token is inactivated. However, if the token is temporarily lost or inaccessible, then the token is essentially suspended, the certificates on it are inactivated, and a new token with temporary certificates is issued.

NOTE

If a token is terminated, the physical token can be reused with new certificates.
Temporary certificates, by default, are only valid for one week. Within that time, the status on the original token has to be finalized, in one of two ways:
  • The token could be found. If the user locates the original token, the TPS agent can reactivate the original token by changing the status to This temporarily lost token has been found. Changing the status of the original token to active also takes the certificates off hold; when this is done, the status of the temporary token is automatically updated and its certificates revoked.
  • If the user cannot locate the original token, the TPS agent must change the status of the original token to This temporarily lost token cannot be found. The certificates on the original token are revoked. The status of the temporary token is updated to inactive and its certificates revoked. The user is then permitted to enroll for a permanent token.

9.3.4. Searching Certificates

NOTE

It is possible to list the certificates for a single token by opening the token information page and then clicking the Show Certificates button.
Certificates are recorded as attributes of the token, so the search is for the token rather than the certificate alone.
To find all tokens, a subset of tokens, or a specific token, click the List/Search Certificates link in the Agent Operations tab, and fill in the name of the user or the whole or partial token identification number (CUID). The certificates search form, then, appears identical to the regular token search form. As with searching for tokens, asterisks (*) can be used in the search fields as wildcards and leaving a field blank returns all tokens.
There is a maximum allowed number of search results configured for the TPS Directory Server database, so the number of entries returned is constrained by the search limit. Each results page shows 25 records.
Results for Searching for Certificates

Figure 9.12. Results for Searching for Certificates


The results show all of the information about the certificate:
  • ID, the unique entry ID for the certificate
  • Serial number, the serial number of the certificate, which is assigned by the CA which issued it
  • Subject, the subject name of the certificate; this usually identifies the user of the certificate
  • Token ID, the ID of the token on which the certificate is enrolled
  • Key Type, the kind of key, which indicates the purpose or usage of the certificate
  • Last Status, which is the status of the certificate as of the last time the token was processed (meaning it may not reflect the most current status)
  • User ID, the user ID of the person who is associated with the token
  • Last Modified At, the timestamp of the last modification to the certificate

9.3.5. Searching Activities

Activities are essentially logs for the TPS subsystem, and for the actions taken on individual tokens.
Activities are logs of actions performed on a token, so searching for activities means searching for the token, and returning its specific log of activities.
To find all tokens, a subset of tokens, or a specific token, click the List/Search Activities link in the Agent Operations tab, and fill in the name of the user or the whole or partial token identification number (CUID). The certificates search form, then, appears identical to the regular token search form. As with searching for tokens, asterisks (*) can be used in the search fields as wildcards and leaving a field blank returns all tokens.

NOTE

It is possible to list the activities for a single token by opening the token information page and then clicking the Show Activities button.
There is a maximum allowed number of search results configured for the TPS Directory Server database, so the number of entries returned is constrained by the search limit. Each results page shows 25 records.
Results for Searching Activities

Figure 9.13. Results for Searching Activities


The activities entries are formatted with two lines of information. The first line has the following information:
  • Activity ID, the unique ID of the activity entry
  • Token, the ID of the token for which the activity was performed
  • IP, the IP address of the client which connected to the TPS and performed the operation
  • User ID, the ID of the person who performed the operation
  • Operation, the kind of action being taken
  • Result, the result returned for the operation
  • Created, the time that the activity was performed
The second line contains a detailed description of what operation was performed.

9.3.6. Enabling and Disabling Profiles

Similar to a CA profile, the TPS uses profiles to define the policies for its token operations. These policies are created and edited by TPS administrators, but they must be reviewed and enabled by TPS agents.

9.3.6.1. Enabling Profiles

  1. Click the Profiles link in the Agents Operations tab.
  2. Select the policy from the drop-down menu and click the Review button.
  3. Review the edited profile, and click the Approve and Enable button at the bottom of the screen.

9.3.6.2. Disabling Profiles

  1. Click the Profiles link in the Agents Operations tab.
  2. Select the policy from the drop-down menu and click the Review button.
  3. At the bottom of the policy page, click the Disable button.