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

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:

Open the TPS web UI.
```
https://server.example.com:7889/tus/
```
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.
In the Administrator Operations tab, click the Profiles link.
Select the policy from the drop-down menu and click the Edit button.
Edit the policy as desired. The parameters for the different default operations are listed in Section 5.1.1, “Configuring Format Policies”, Section 5.1.2, “Configuring TPS Enrollment Policies”, and Section 5.1.4, “Configuring the PIN Reset Policies”.
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.
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.
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.