Chapter 5. Using and Configuring the Token Management System: TPS, TKS, and Enterprise Security Client

5.1. Configuring TPS Smart Card Operation Policies
5.1.1. Configuring Format Policies
5.1.2. Configuring TPS Enrollment Policies
5.1.3. Configuring TPS Renewal Operations
5.1.4. Configuring the PIN Reset Policies
5.1.5. Configuring the Applet Update Policies
5.1.6. Editing TPS Policies in the TPS UI
5.2. Mapping Token Types and Policies to Specified Smart Cards
5.2.1. Default Token Types
5.2.2. Mapping Token Types to Smart Card Operation Policies
5.2.3. Mapping Token Types and TPS Policies in the TPS UI
5.2.4. Example: Token Mapping with Two Different Token Types
5.3. Creating Custom User Token Profiles
5.4. Allowing Token Renewal
5.5. Changing the Token Policy
5.6. Setting Token Status Transitions
5.7. Automating Encryption Key Recovery
5.7.1. Configuring Enrollment for Replacement Tokens
5.7.2. Configuring Key Generation for Temporary Tokens
5.8. Managing Shared Keys
5.8.1. Generating Master Keys
5.8.2. Generating and Transporting Wrapped Master Keys
5.8.3. Using HSM for Generating Keys
5.8.4. Updating Master Key Versions and Associating the Master Key with Its Version
5.8.5. Configuring Symmetric Key Changeover
5.8.6. Troubleshooting Master Key and HSM Problems
5.9. Configuring the TPS
5.9.1. Configuring the TPS Administrative UI
5.9.2. Enabling SSL for TPS-Enterprise Security Client Connections
5.9.3. Configuring the Channels between the TPS and Tokens
5.9.4. Configuring or Disabling LDAP Authentication
5.9.5. Configuring the Token Database
5.9.6. Configuring Server-Side Key Generation and Archival of Encryption Keys
5.9.7. Setting TPS Server Password Lengths
5.9.8. Setting TPS Server Search Configuration
5.9.9. Configuring IPv6 Support
5.10. Configuring Connections to Other Subsystems
5.10.1. Editing Subsystem Connections in the TPS UI
5.10.2. Scaling the TPS and Its Support Subsystems
5.10.3. Configuring Multiple Support Subsystem Instances for Different Functions
5.11. Potential Token Operation Errors
This chapter gives an overview of using hardware security modules, also called HSMs or tokens, to generate and store Certificate System instance certificates and keys. This chapter includes installation and usage considerations for supported HSMs, describes different tasks for managing tokens, and contains other information for using hardware tokens with Certificate System.

5.1. Configuring TPS Smart Card Operation Policies

The way that the TPS is configured effects how smart card operations are handled, both coming in from the Enterprise Security Client and going between the CA and TPS, depending on the nature of the operation.
There are three operations that are performed through the TPS:
  • Formatting the smart card, which can include upgrading the applet version on the smart card
  • Enrolling the smart card, which includes requesting and installing certificates on the card, renewing certificates on the card, and, optionally, upgrading the applet version on the smart card
  • Changing the password (PIN) on the smart card
Each of these operations is configured in the TPS instance's CS.cfg file, similar to a CA enrollment profile.

5.1.1. Configuring Format Policies

When the TPS is contacted by a smart card for a format operation, there are several different operations the TPS can perform, depending on the status of the smart card.
  • Whether an empty token should be rejected or have the required applet (card format) uploaded, so it is made usable.
  • Whether a smart card with an outdated applet should be upgraded and, if so, which version of applet to upload.
  • Whether a smart card with outdated keys should be updated with new symmetric keys. Keys can become outdated if the TKS had a master key changeover.
  • Whether to revoke the certificates associated with the token.
For example, to configure the TPS to reject a smart card without an applet, to update a smart card with new symmetric keys, and to revoke certificates associated with the smart card, the following parameters are set:
op.format.tokenKey.update.applet.emptyToken.enable=true
op.format.tokenKey.update.symmetricKeys.enable=true
op.format.tokenKey.revokeCert=true
The different format operations can be configured to happen automatically by setting the appropriate parameters in the CS.cfg file. The TPS can also be configured with other options, such as requiring LDAP authentication and setting which subsystem instances will process the formatting operations. The parameters are listed in Table 5.1, “Format Operation Parameters”.

Table 5.1. Format Operation Parameters

Parameter Description
op.format.tokenType.update.applet.emptyToken.enable Specifies whether TPS should upload an applet to the token when it does not have one. The valid values are true|false.
op.format.tokenType.update.applet.requiredVersion The version of the applet to use. It should be the file name of the applet without the .ijc extension.
op.format.tokenType.update.applet.directory The local (to the TPS) filesystem directory where the applets are located
op.format.tokenType.update.symmetricKeys.enable Specifies if the key changeover feature should be enabled. The valid values are true|false. When enabled, TPS checks to see the key version sent by the token matches symmetricKeys.requiredVersion.
op.format.tokenType.update.symmetricKeys.requiredVersion The required key version.
op.format.tokenType.revokeCert
Specifies if TPS should revoke the certificates associated with the token during this format operation.

NOTE

This parameter also specifies if the certificates should be revoked when performing an enrollment operation if RE_ENROLL is set to true in the enrollment policy, meaning that renewals are not allowed.
The default is true. The valid values are true|false.
op.format.tokenType.ca.conn The CA connection to use.
op.format.tokenType.loginRequest.enable Specifies if the login request should be sent to the client. This parameter enables authentication. The valid values are true|false.
op.format.tokenType.tks.conn The TKS connection to use.
op.format.tokenType.auth.id The LDAP authentication instance to use. The default value is ldap1.
op.format.tokenType.auth.enable Specifies whether to authenticate the user information. The valid values are true|false.
op.format.tokenType.issuerinfo.enable Specifies whether the Phone Home information for the Enterprise Security Client is written to the token. The valid values are true|false.
op.format.tokenType.issuerinfo.value Sets the Phone Home URL; this is the URL for the TPS which the Enterprise Security Client will contact for token operations; this value is set on the token when it is formatted. For example, https://tps.example.com:7888/cgi-bin/home/index.cgi.

5.1.2. Configuring TPS Enrollment Policies

Enrollment covers nearly every step of managing certificates on the token, from issuing them to recovering them if they are lost to revoking them.
Most enrollment parameters occur in pairs, one for signing certificates and one for encryption certificates. The processes for both can be slightly different, as in the case of recovery, even for the same certificate pair. For example:
op.enroll.userKey.keyGen.encryption.ca.profileId=caTokenUserEncryptionKeyEnrollment
op.enroll.userKey.keyGen.signing.ca.profileId=caTokenUserSigningKeyEnrollment
Each token type, such as soKey for security officers or userKey for regular users, has its own op.enroll profile definition.
Each enrollment profile definition has two parts for managing keys: how to generate new keys for the enrollment type and how to recover lost keys for the enrollment type. The profile also defines the CA to connection to, the CA profile to use, the LDAP instance to authenticate to, and whether to perform key archival. For example:
... LDAP authentication connection ...
 op.enroll.soKey.auth.enable=true
 op.enroll.soKey.auth.id=ldap2

... card issuer information ...
 op.enroll.soKey.cardmgr_instance=A0000000030000
 op.enroll.soKey.issuerinfo.enable=true
 op.enroll.soKey.issuerinfo.value=http://server.example.coml:7888/cgi-bin/so/index.cgi

... CA connection and profile ...
 op.enroll.soKey.keyGen.encryption.ca.conn=ca1
 op.enroll.soKey.keyGen.encryption.ca.profileId=caTokenUserEncryptionKeyEnrollment
 op.enroll.soKey.keyGen.encryption.certAttrId=c2
 op.enroll.soKey.keyGen.encryption.certId=C2

... key generation information ...
 op.enroll.soKey.keyGen.encryption.cuid_label=$cuid$
 op.enroll.soKey.keyGen.encryption.keySize=1024
 op.enroll.soKey.keyGen.encryption.keyUsage=0
 op.enroll.soKey.keyGen.encryption.keyUser=0
 op.enroll.soKey.keyGen.encryption.label=encryption key for $userid$
 op.enroll.soKey.keyGen.encryption.overwrite=true

... recovering lost tokens ...
 op.enroll.soKey.keyGen.encryption.recovery.destroyed.revokeCert=false
 op.enroll.soKey.keyGen.encryption.recovery.destroyed.revokeCert.reason=0
 op.enroll.soKey.keyGen.encryption.recovery.destroyed.scheme=RecoverLast
 op.enroll.soKey.keyGen.encryption.recovery.keyCompromise.revokeCert=true
 op.enroll.soKey.keyGen.encryption.recovery.keyCompromise.revokeCert.reason=1
 op.enroll.soKey.keyGen.encryption.recovery.keyCompromise.scheme=GenerateNewKey
 op.enroll.soKey.keyGen.encryption.recovery.onHold.revokeCert=true
 op.enroll.soKey.keyGen.encryption.recovery.onHold.revokeCert.reason=6
 op.enroll.soKey.keyGen.encryption.recovery.onHold.scheme=GenerateNewKey
 op.enroll.soKey.keyGen.encryption.revokeCert=true

... key archival information ...
 op.enroll.soKey.keyGen.encryption.serverKeygen.archive=true
 op.enroll.soKey.keyGen.encryption.serverKeygen.drm.conn=drm1
 op.enroll.soKey.keyGen.encryption.serverKeygen.enable=true

... PKCS #11 parameters for keys ...
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.decrypt=true
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.derive=false
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.encrypt=false
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.private=true
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.sensitive=true
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.sign=false
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.signRecover=false
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.token=true
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.unwrap=true
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.verify=false
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.verifyRecover=false
op.enroll.soKey.keyGen.encryption.private.keyCapabilities.wrap=false
op.enroll.soKey.keyGen.encryption.privateKeyAttrId=k4
op.enroll.soKey.keyGen.encryption.privateKeyNumber=4

NOTE

There are a number of other parameters which are used by the TPS and are included in the configuration which are never to be altered from the default. For creating new enrollment operation profiles, simply copy these parameters from an existing profile. The list of verboten parameters is in Table 5.3, “Important Enrollment Parameters That Should Never Be Edited”.

Table 5.2. Enrollment Operation Parameters

Parameter Description
op.enroll.tokenType.temporaryToken.tokenType The tokenType to use for temporary tokens. tokenType typically refers to the profile defining how many certificates should be generated, how keys should be recovered, and what format should be used.
op.enroll.tokenType.keyGen.recovery.destroyed.keyType.num Specifies number of keyTypes. The default value is 2.
op.enroll.tokenType.keyGen.recovery.destroyed.keyType.value.# Specifies keyType. The valid values are signing|encryption.
op.enroll.tokenType.keyGen.signing.recovery.destroyed.scheme Specifies the signing certificate recovery scheme for destroyed tokens. The default value is GenerateNewKey. The other possible values are RecoverLast and GenerateNewKeyAndRecoverLast (which generates a new signing key and recovers the last encryption key).
op.enroll.tokenType.keyGen.signing.recovery.destroyed.revokeCert Sets whether signing certificates should be revoked. The valid values are true|false. The default value is true.
op.enroll.tokenType.keyGen.signing.recovery.destroyed.revokeCert.reason
Sets what the signing certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.encryption.recovery.destroyed.scheme Specifies the encryption certificate recovery scheme for destroyed tokens. The default value is RecoverLast. The other possible values are GenerateNewKey and GenerateNewKeyAndRecoverLast (which generates a new signing key and recovers the last encryption key).
op.enroll.tokenType.keyGen.encryption.recovery.destroyed.revokeCert Specifies if the encryption certificate should be revoked. The valid values are true|false. The default value is true.
op.enroll.tokenType.keyGen.encryption.recovery.destroyed.revokeCert.reason  
op.enroll.tokenType.keyGen.encryption.recovery.destroyed.revokeCert.reason
Specifies what the encryption certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.recovery.keyCompromise.keyType.num The number of key types for recovery for the tokens whose keys are compromised.
op.enroll.tokenType.keyGen.recovery.keyCompromise.keyType.value.# Specifies keyType. The default values are signing|encryption.
op.enroll.tokenType.keyGen.signing.recovery.keyCompromise.scheme Specifies the signing certificate recovery scheme for tokens whose keys are compromised. The default value is GenerateNewKey. The other possible values are RecoverLast and GenerateNewKeyAndRecoverLast (which generates a new signing key and recovers the last encryption key).
op.enroll.tokenType.keyGen.signing.recovery.keyCompromise.revokeCert Specifies if the signing certificate should be revoked if the original token's key has been comprised. The valid values are true|false.
op.enroll.tokenType.keyGen.signing.recovery.keyCompromise.revokeCert.reason
Specifies what the signing certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.encryption.recovery.keyCompromise.scheme Specifies encryption certificate recovery scheme for tokens whose key is compromised. The valid values include GenerateNewKey, RecoverLast, and GenerateNewKeyAndRecoverLast (which generates a new signing key and recovers the last encryption key).
op.enroll.tokenType.keyGen.encryption.recovery.keyCompromise.revokeCert Specifies if the encryption certificate should be revoked if the token's key has been comprised. The valid values are true|false.
op.enroll.tokenType.keyGen.encryption.recovery.keyCompromise.revokeCert.reason
Specifies what the signing certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.recovery.onHold.keyType.num The number of key types for the tokens to put on hold for temporary loss reasons. The valid values are integers. The default is 2.
op.enroll.tokenType.keyGen.recovery.onHold.keyType.value.# Specifies keyType. The default values are signing|encryption.
op.enroll.tokenType.keyGen.signing.recovery.onHold.scheme The recovery scheme for signing certificates for tokens that are to be put on hold. The valid values are GenerateNewKey, RecoverLast, and GenerateNewKeyAndRecoverLast (which generates a new signing key and recovers the last encryption key).
op.enroll.tokenType.keyGen.signing.recovery.onHold.revokeCert
Specifies if the signing certificate should be revoked if the token's key has been comprised.
This setting is also checked after a signing certificate which was on hold is recovered. If this value is true, meaning that the certificate was revoked when the token went on hold, then the certificate is unrevoked. A new signing key is still generated.
The valid values are true|false.
op.enroll.tokenType.keyGen.signing.recovery.onHold.revokeCert.reason
Specifies what the signing certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.encryption.recovery.onHold.scheme The recovery scheme for encryption certificates for tokens that are to be put on hold. The valid values are GenerateNewKey, RecoverLast, and GenerateNewKeyAndRecoverLast (which generates a new signing key and recovers the last encryption key).
op.enroll.tokenType.keyGen.encryption.recovery.onHold.revokeCert
Specifies if the encryption certificate should be revoked if the token's key has been comprised.
This setting is also checked after an encryption certificate which was on hold is recovered. If this value is true, meaning that the certificate was revoked when the token went on hold, then the certificate is unrevoked.
The valid values are true|false.
op.enroll.tokenType.keyGen.encryption.recovery.onHold.revokeCert.reason
Specifies what the signing certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.tokenName The name of the token to use. The TPS can substitute some special strings. For example, if using cuid, the tokenName is substituted with the CUID of the token; if using uid, the tokenName is substituted with the UID of the authenticating user.
op.enroll.tokenType.keyGen.keyType.num The number of keys/certificates to be generated for the profile. The values are integers. The default is 2.
op.enroll.tokenType.keyGen.keyType.value.# Specifies keyType. The default values are signing|encryption.
op.enroll.tokenType.keyGen.signing.keySize Specifies the key size to use for key generation. The recommended setting is 2048.
op.enroll.tokenType.keyGen.signing.label The token label for the signing certificate. The valid values are $pretty_cuid$, $cuid$, $msn$, $userid$, and $profileId$. These variables are replaced by the user-supplied information when the certificate is generated.
op.enroll.tokenType.keyGen.signing.cuid_label The CUID to show in the certificate.
op.enroll.tokenType.keyGen.signing.overwrite Specifies if the TPS should overwrite the existing signing certificate. The valid values are true|false.
op.enroll.tokenType.keyGen.signing.ca.profileId The CA profile that should be used for creating the signing certificate. The default is caTokenUserSigningKeyEnrollment.
op.enroll.tokenType.keyGen.signing.ca.conn The CA connection to use. The default value is ca1.
op.enroll.tokenType.keyGen.encryption.keySize The key size for the encryption key. The recommended setting is 2048.
op.enroll.tokenType.keyGen.encryption.label The token label for the encryption certificate. The valid values are $pretty_cuid$, $cuid$, $msn$, $userid$, and $profileId$. These variables are replaced by the user-supplied information when the certificate is generated.
op.enroll.tokenType.keyGen.encryption.cuid_label The CUID to show in the certificate.
op.enroll.tokenType.keyGen.encryption.overwrite Specifies if the encryption certificate on the token should be overwritten. The valid values are true|false.
op.enroll.tokenType.keyGen.encryption.ca.profileId The CA profile to use for enrolling encryption certificates. The default value is caTokenUserEncryptionKeyEnrollment.
op.enroll.tokenType.keyGen.encryption.ca.conn The CA connection to use to generate encryption certs. The default value is ca1.
op.enroll.tokenType.update.applet.emptyToken.enable Specifies whether TPS should upload an applet to the token when it does not have one. The valid values are true|false.
op.enroll.tokenType.update.applet.enable Specifies if applet upgrade is turned on. The valid values are true|false.
op.enroll.tokenType.update.applet.requiredVersion The version of the applet to use. It should be the file name of the applet without the .ijc extension.
op.enroll.tokenType.update.applet.directory The local filesystem directory where the applets are located.
op.enroll.tokenType.update.symmetricKeys.enable Specifies if the key changeover feature should be enabled. The valid values are true|false. When enabled, TPS checks to see the key version sent by the token matches symmetricKeys.requiredVersion.
op.enroll.tokenType.update.symmetricKeys.requiredVersion The required key version.
op.enroll.tokenType.loginRequest.enable Specifies if the login request should be sent to the token. This parameter enables authentication. The valid values are true|false.
op.enroll.tokenType.pinReset.enable Specifies if the token's PIN should be reset. The default value is true. The valid values are true|false.
op.enroll.tokenType.pinReset.pin.minLen The minimum number of characters for the PIN.
op.enroll.tokenType.pinReset.pin.maxRetries The maximum number of times PIN authentication can be attempted on the token before the key is locked. This value is set on the token when the token is formatted.
op.enroll.tokenType.pinReset.pin.maxLen The maximum number of characters for the PIN.
op.enroll.tokenType.tks.conn The TKS connection to use.
op.enroll.tokenType.auth.id The LDAP authentication instance to use. The default value is ldap1.
op.enroll.tokenType.auth.enable Specifies whether to authenticate the user information. The valid values are true|false.

There are some parameters in the CS.cfg file that are set to configure signing and encryption enrollment operations which should never be altered.

Table 5.3. Important Enrollment Parameters That Should Never Be Edited

Parameter Description
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.decrypt Specifies whether the key (public or private) is to be used to decrypt information. The valid values are true|false. For private encryption keys, this is true.
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.derive Specifies whether the key is used to derive a master key. The valid values are true|false. For both signing and encryption keys (public and private), this is false.
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.encrypt Specifies whether the key (public or private) is to be used to encrypt information. The valid values are true|false. For public encryption keys, this is true.
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.private Specifies whether the key is a private key. The valid values are true|false.
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.sensitive Specifies whether the key is sensitive (meaning, private) material. The valid values are true|false. For private keys, this is true.
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.sign Specifies whether this is a signing key. The valid values are true|false. For private signing keys, this is true.
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.signRecover
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.token Specifies whether the key will be used on a token. The valid values are true|false.
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.unwrap Specifies whether the key will be used to unwrap (decrypt) information. The valid values are true|false. For private encryption keys, this is true.
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.verify
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.verifyRecover
op.enroll.tokenType.keyGen.keyType.private|public.keyCapabilities.wrap Specifies whether the key will be used to wrap (encrypt) information. The valid values are true|false. For public encryption keys, this is true.
op.enroll.tokenType.keyGen.keyType.privateKeyAttrId
op.enroll.tokenType.keyGen.keyType.publicKeyAttrId
Gives a unique identifier for the public or the private key. There is a close relationship between the certAttrId value and the privateKeyAttrId and publicKeyAttrId. The first key is always 2 * C and the second key is always 2 * C + 1. For example, if the operation has a value of c1, then one key has a value of k2 and the next of k3.

WARNING

The public and private key values cannot collide. It is also critical that the mathematical relationship between the certificate and key AttrIds be maintained.
Do not alter the default values.
op.enroll.tokenType.keyGen.keyType.privateKeyNumber
op.enroll.tokenType.keyGen.keyType.publicKeyNumber
Gives the number of the key attribute, without the k prefix.
op.enroll.tokenType.pkcs11obj.compress.enable=true
op.enroll.tokenType.pkcs11obj.enable=true

5.1.3. Configuring TPS Renewal Operations

Renewal operations regenerate the certificates on a token, using existing key pairs to recreate the certificates. This means that the renewal profile mirrors the enrollment configuration that relates directly to generating the certificate. Other aspects of the enrollment operations — such as recovering a lost token — are still managed through the enrollment configuration.
As with enrollment parameters, the renewal parameters occur in pairs, one for signing certificates and one for encryption certificates.
Each token type, such as soKey for security officers or userKey for regular users, has its own op.renewal profile definition.

Table 5.4. Renewal Operation Parameters

Parameter Description
op.renewal.tokenType.keyType.num The number of keys/certificates that are generated for the profile. The values are integers. The default is 2.
op.renewal.tokenType.keyType.value.# Specifies the key type. The default values are signing|encryption.
op.renewal.tokenType.signing.enable Sets whether the signing certificate renewal profile is enabled.
op.renewal.tokenType.signing.certAttrId Identifies which key on the token is used for the signing certificate.
op.renewal.tokenType.signing.certId Identifies which key on the token is used for the signing certificate.
op.renewal.tokenType.signing.ca.profileId The CA profile that should be used for renewing the signing certificate. The default is caTokenUserSigningKeyRenewal.
op.renewal.tokenType.signing.ca.conn The CA connection to use. The default value is ca1.
op.renewal.tokenType.encryption.enable Sets whether the encryption certificate renewal profile is enabled.
op.renewal.tokenType.encryption.certAttrId Identifies which key on the token is used for the encryption certificate.
op.renewal.tokenType.encryption.certId Identifies which key on the token is used for the encryption certificate.
op.renewal.tokenType.encryption.ca.profileId The CA profile to use for renewing encryption certificates. The default value is caTokenUserEncryptionKeyRenewal.
op.renewal.tokenType.encryption.ca.conn The CA connection to use to generate encryption certs. The default value is ca1.

5.1.4. Configuring the PIN Reset Policies

The PIN is the password which protects the certificates and keys on the smart card. The TPS can place two restrictions on the PIN: the maximum length and the minimum length. For example, to require PINs to be between 6 and 12 characters, the following parameters are set:
op.pinReset.userKey.pinReset.pin.maxLen=12
op.pinReset.userKey.pinReset.pin.minLen=6
Like the formatting operation, the TPS can be configured to update the symmetric key, require LDAP authentication, and set which subsystem instances will process the operation. The CS.cfg file parameters for resetting the PIN are listed in Table 5.5, “PIN Reset Operation Parameters”.
The parameters which should never be modified are listed in Table 5.6, “PIN Reset Operation Parameters That Should Never Be Edited”.

NOTE

PIN reset operations cannot logically follow an applet upgrade operation, because the upgrade process removes any previous settings, including the PIN. Therefore, the applet upgrade parameters for the PIN reset operation should be false. For example:
op.pinReset.userKey.update.applet.directory=/usr/share/pki/tps/applets
op.pinReset.userKey.update.applet.emptyToken.enable=false
op.pinReset.userKey.update.applet.enable=false
op.pinReset.userKey.update.applet.encryption=true
op.pinReset.userKey.update.applet.requiredVersion=1.4.499dc06c

Table 5.5. PIN Reset Operation Parameters

Parameter Description
op.pinReset.tokenType.update.symmetricKeys.enable Specifies if the key changeover feature should be enabled. The valid values are true|false. When enabled, TPS checks to see the key version sent by the token matches symmetricKeys.requiredVersion.
op.pinReset.tokenType.update.symmetricKeys.requiredVersion The required key version.
op.pinReset.tokenType.loginRequest.enable Specifies if the login request should be sent to the token. This parameter enables authentication. The valid values are true|false.
op.pinReset.tokenType.pinReset.pin.minLen The minimum number of characters for the PIN.
op.pinReset.tokenType.pinReset.pin.maxRetries The maximum number of times PIN authentication can be attempted on the token before the key is locked. This value is set on the token when the PIN is set or reset.
op.pinReset.tokenType.pinReset.pin.maxLen The maximum number of characters for the PIN.
op.pinReset.tokenType.tks.conn The TKS connection to use.
op.pinReset.tokenType.auth.id The LDAP authentication instance to use. The default value is ldap1.
op.pinReset.tokenType.auth.enable Specifies whether to authenticate the user information. The valid values are true|false.

Table 5.6. PIN Reset Operation Parameters That Should Never Be Edited

op.pinReset.tokenType.update.applet.emptyToken.enable
op.pinReset.tokenType.update.applet.enable
op.pinReset.tokenType.update.applet.requiredVersion
op.pinReset.tokenType.update.applet.directory

5.1.5. Configuring the Applet Update Policies

The TPS communicates with an applet on the smart card. The smart cards can be manufactured with both a card manager applet and a vendor applet or with only the card manager applet. If the cards only have the card manager applet, the TPS can install the Certificate System applet onto the smart card. Similarly, an old applet can be replaced with a new applet. Any keys or certificates created or managed with the old applet are destroyed.

NOTE

The only supported card manager applet is the CoolKey applet which ships with Red Hat Enterprise Linux 5.6.
To upgrade the applet in the TPS, put the new applet in the applet directory, and set the update.applet.enable parameter in the CS.cfg file to true. For example, to update the applet when enrolling a smart card of the type userKey, the parameters would be the following:
op.enroll.userKey.update.applet.enable=true
op.enroll.userKey.update.applet.emptyToken.enable=false
op.enroll.userKey.update.applet.requiredVersion=1.3.44724DDE
op.enroll.userKey.update.applet.directory=/usr/share/pki/tps/applets
op.enroll.userKey.update.applet.encryption=true
If a smart card only has the card manager, then the card manager capability must be enabled by editing the following parameter:
op.operation.key_type.update.applet.emptyToken.enable=true

NOTE

If the filename set in the update.applet.requiredVersion parameter contains any alphabetic characters, then all of these alphabetic characters must always be uppercase letters; this applies to the actual name of the file, as well as the update.applet.requiredVersion parameter.
The TPS queries the applet version on the smart card before trying to execute any operations.
If the update feature is enabled and the applet version from the client is different from the one specified by the update.applet.requiredVersion parameter, the TPS updates the applet automatically.

NOTE

The TPS audit log shows whether the applet update worked successfully.
The parameters to enable upgrading the applets are set in the TPS operation configurations. The parameters for upgrading the applet during a formatting operation are in Table 5.1, “Format Operation Parameters”; the parameters for upgrading the applet when resetting the PIN are listed in Table 5.5, “PIN Reset Operation Parameters”; and the parameters for upgrading the applet during an enrollment operation are in Table 5.2, “Enrollment Operation Parameters”.

5.1.6. Editing TPS Policies in the TPS UI

The TPS policies are configured as operation-based profiles. While each policy is configured in the CS.cfg file, each operation policy can also be edited in the TPS administrative web UI. The configuration is exactly the same in the TPS UI and the CS.cfg file, but the UI shows the changelog before saving changes and provides a layer of validation before accepting changes.

TIP

Every configuration change performed through the TPS web UI is automatically recorded to the TPS audit logs. For change tracking, it is very useful to make configuration changes only in the TPS admin UI.
To edit a TPS operation policy:
  1. Open the TPS web UI.
    https://server.example.com:7889/tus/
  2. Have an agent disable the TPS operation policy. Like CA profiles, the TPS profile must be disabled by an agent before it can be edited.
    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.
  3. In the Administrator Operations tab, click the Profiles link.
  4. Select the policy from the drop-down menu and click the Edit button.
  5. Click the Submit for Approval button to send the edited profile back to the agent for approval. Submitting the profile for approval locks the configuration so that it cannot be changed until an agent either accepts or rejects it.
    To save a draft of the profile, click the Save button, which preserves the current changes. This updates the TPS CS.cfg; any other admin users who are editing the TPS configuration will have to edit the updated file, but they can still make changes.

    NOTE

    An agent can enable a profile even if it has not been sent for approval by an administrator.
  6. When the profile is submitted, a list of all of the changes comes up, showing both additions and deletions. If the changes are correct, click the Confirm Changes button.
  7. Have an agent approve and enable the edited profile.
    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.
A new policy can be added in the same way: give it a name, paste in the new configuration, validate the settings, and then have it approved by an agent.