Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

Ce contenu n'est pas disponible dans la langue sélectionnée.

Chapter 6. Using and configuring the Token Management System: TPS and TKS

This chapter provides procedures for using hardware security modules, also called HSMs or tokens, to generate and store Certificate System instance certificates and keys.

This chapter only contains administration procedures. For general information on the concepts behind the Token Management System, see the Red Hat Certificate System Planning, Installation and Deployment Guide.

6.1. TPS profiles

Note

See the TPS Profiles section of the Red Hat Certificate System Planning, Installation and Deployment Guide for general information.

Unlike CA enrollment profiles, which are defined and stored in individual files or in LDAP, TPS profiles (also known as token types) are defined in the TPS configuration file, CS.cfg.

TPS profile (token type) configuration parameters are set in the following format: 

op.<explicit op>.<profile id>.<implicit op>.<key type>.*

In the above, <explicit op> and <implicit op> are one of the explicit and implicit operations discussed in the TPS Operations section below, and <key type> is the name given for each certificate type.

An example configuration parameter may look like the following example: 

op.enroll.userKey.keyGen.encryption.*

6.2. TPS operations

Explicit operations

An explicit operation is an operation called by a user. Explicit operations include enroll (op.enroll.*), format (op.format.*), and pinReset (op.pinReset.*).

Implicit operations

An implicit operation is an operation that takes place due to the policy or status of a token at a time when an explicit operation is being processed. Implicit operations include keyGen (op.enroll.userKey.keyGen.*), renewal (op.enroll.userKey.renewal.*), update.applet (op.enroll.userKey.update.applet.*), and key update (op.enroll.userKey.update.symmetricKeys.*).

Some implicit operations are controlled per key type. These include recovery, serverKeygen, and revocation.

The following example of a TPS profile specifies user keys to be generated on the server side: 

op.enroll.userKey.keyGen.encryption.serverKeygen.archive=true
op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=kra1
op.enroll.userKey.keyGen.encryption.serverKeygen.enable=true

Additionally, the following example tells TPS that a token whose keys are compromised should revoke the certification with revocation reason 1 during the state transition: 

op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert=true
op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert.reason=1

According to RFC 5280, possible revocation reasons and their codes are defined as follows:

Table 6.1. Revocation reasons and codes
ReasonCode

unspecified

0

keyCompromise

1

CACompromise

2

affiliationChanged

3

superseded

4

cessationOfOperation

5

certificateHold

6

removeFromCRL

8

privilegeWithdrawn

9

AACompromise

10

6.3. Token policies

This section provides a list of token policies that can be applied on a per token basis using the TPS UI. Ech section will show how each policy is reflected in the configuration.

Note

See the Token Policies section of the Red Hat Certificate System Planning, Installation and Deployment Guide for general information.

The policy is a collection of policies each separated by a semicolon (“;”"). Each policy can be turned on or off with the keywords YES or NO. Each policy in the list below will be introduced with its default value - the action taken by TPS if the setting did not exist at all in the policy string.

RE_ENROLL=YES

This policy controls whether or not a token allows a reenroll operation. This allows an already enrolled token (with certificates) to be reenrolled and given new ones. If set to NO, the server will return an error if a reenrollment is attempted.

This policy does not require special configuration. The enrollment will proceed with the standard enrollment profile, which likely enrolled the token originally.

RENEW=NO;RENEW_KEEP_OLD_ENC_CERTS=YES

Renewal allows a token to have their profile generated certificates to be renewed in place on the token. If RENEW is set to YES, a simple enrollment from the Enterprise Security Client (ESC) will result in a renewal instead of a reenrollment as discussed above.

The RENEW_KEEP_OLD_ENC_CERTS setting determines if a renewal operation will retain the previous version of the encryption certificate. Retaining the previous certificate allows users to access data encrypted with the old certificate. Setting this option to NO will mean that anything encrypted with the old certificate will no longer be recoverable.

Configuration: 

op.enroll.userKey.renewal.encryption.ca.conn=ca1
op.enroll.userKey.renewal.encryption.ca.profileId=caTokenUserEncryptionKeyRenewal
op.enroll.userKey.renewal.encryption.certAttrId=c2
op.enroll.userKey.renewal.encryption.certId=C2
op.enroll.userKey.renewal.encryption.enable=true
op.enroll.userKey.renewal.encryption.gracePeriod.after=30
op.enroll.userKey.renewal.encryption.gracePeriod.before=30
op.enroll.userKey.renewal.encryption.gracePeriod.enable=false
op.enroll.userKey.renewal.keyType.num=2
op.enroll.userKey.renewal.keyType.value.0=signing
op.enroll.userKey.renewal.keyType.value.1=encryption
op.enroll.userKey.renewal.signing.ca.conn=ca1
op.enroll.userKey.renewal.signing.ca.profileId=caTokenUserSigningKeyRenewal
op.enroll.userKey.renewal.signing.certAttrId=c1
op.enroll.userKey.renewal.signing.certId=C1
op.enroll.userKey.renewal.signing.enable=true
op.enroll.userKey.renewal.signing.gracePeriod.after=30
op.enroll.userKey.renewal.signing.gracePeriod.before=30
op.enroll.userKey.renewal.signing.gracePeriod.enable=false

This type of renewal configuration mirrors the basic userKey standard enrollment profile with a few added settings that are renewal specific. This parity is needed because we went to renew exactly the number and type of certs that were enrolled originally on to the token before renewal is to be put into play.

FORCE_FORMAT=NO

This policy causes every enrollment operation to prompt a format operation if enabled. This is a last-step option to allow tokens to be reset without a user having to return it to an administrator. If set to YES, every enrollment operation initiated by the user will cause a format to happen, esentially resetting the token to the formatted state.

No additional configuration is necessary. A simple format occurs given the same TPS profile used to perform a standard format operation.

PIN_RESET=NO

This policy determines if an already enrolled token can perform an explicit “pin reset” change using the ESC. This value must be set to YES or the attempted operation will be rejected with an error by the server.

Configuration: 

op.enroll.userKey.pinReset.enable=true
op.enroll.userKey.pinReset.pin.maxLen=10
op.enroll.userKey.pinReset.pin.maxRetries=127
op.enroll.userKey.pinReset.pin.minLen=4

In the above example, the settings for minLen and maxLen put constraints on the length of a chosen password, and the maxRetries setting sets the token to only allow a given number of retries before locking up.

TPS policies can be edited easily using the latest TPS user interface. Navigate to the token that needs a policy change and click Edit. This will bring up a dialog that will allow you to edit the field, which is a collection of semi colon separated policies strung together. Each supported policy must be set to <POLICYNAME>=YES or <POLICYNAME>=NO in order to be recognized by TPS.

6.4. Token operation and policy processing

This section discusses major operations (both explicit and implicit) that involve a token. The list below will discuss each feature and its configuration.

Note

See the Token Policies section in the Red Hat Certificate System Planning, Installation and Deployment Guide for general information.

Format

The Format operation (user-initiated) takes a token in a completely blank state as supplied by the manufacturer, and loads a Coolkey applet on it.

Configuration example: 

#specify that we want authentication for format. We almost always want this at true:
op.format.userKey.auth.enable=true
#specify the ldap authentication configuration, so TPS knows where to validate credentials:
op.format.userKey.auth.id=ldap1
#specify the connection the the CA
op.format.userKey.ca.conn=ca1
#specify id of the card manager applet on given token
op.format.userKey.cardmgr_instance=A0000000030000

#specify if we need to match the visa cuid to the nist sp800sp derivation algorithm KDD value. Mostly will be false:
op.format.userKey.cuidMustMatchKDD=false

#enable ability to restrict key changoever to a specific range of key set:
op.format.userKey.enableBoundedGPKeyVersion=true
#enable the phone home url to write to the token:
op.format.userKey.issuerinfo.enable=true
#actual home url to write to token:
op.format.userKey.issuerinfo.value=http://server.example.com:8080/tps/phoneHome
#specify whether to request a login from the client. Mostly true, external reg may want this to be false:
op.format.userKey.loginRequest.enable=true
#Actual range of desired keyset numbers:
op.format.userKey.maximumGPKeyVersion=FF
op.format.userKey.minimumGPKeyVersion=01
#Whether or not to revoke certs on the token after a format, and what the reason will be if so:
op.format.userKey.revokeCert=true
op.format.userKey.revokeCert.reason=0
#This will roll back the reflected keyyset version of the token in the tokendb. After a failed key changeover operation. This is to keep the value in sync with reality in the tokendb. Always false, since this version of TPS avoids this situation now:
op.format.userKey.rollbackKeyVersionOnPutKeyFailure=false

#specify connection to the TKS:
op.format.userKey.tks.conn=tks1
#where to get the actual applet file to write to the token:
op.format.userKey.update.applet.directory=/usr/share/pki/tps/applets
#Allows a completely blank token to be recognized by TPS. Mostly should be true:
op.format.userKey.update.applet.emptyToken.enable=true
#Always should be true, not supported:
op.format.userKey.update.applet.encryption=true
#Actual version of the applet file we want to upgrade to. This file will have a name something like: 1.4.54de7a99.ijc:
op.format.userKey.update.applet.requiredVersion=1.4.54de790f
#Symm key changeover:
op.format.userKey.update.symmetricKeys.enable=false
op.format.userKey.update.symmetricKeys.requiredVersion=1
#Make sure the token db is in sync with reality. Should always be true:
op.format.userKey.validateCardKeyInfoAgainstTokenDB=true
Enrollment

The basic enrollment operation takes a formatted token and places certs and keys onto the token in an effort to personalize the token. The following configuration example will explain how this can be controlled.

The example shows basic enrollment which does not deal with renewal and internal recovery. Settings not discussed here are either covered in the Format section, or not crucial. 

op.enroll.userKey.auth.enable=true
op.enroll.userKey.auth.id=ldap1
op.enroll.userKey.cardmgr_instance=A0000000030000
op.enroll.userKey.cuidMustMatchKDD=false

op.enroll.userKey.enableBoundedGPKeyVersion=true
op.enroll.userKey.issuerinfo.enable=true
op.enroll.userKey.issuerinfo.value=http://server.example.com:8080/tps/phoneHome

#configure the encryption cert and keys  we want on the token:

#connection the the CA, which issues the certs:
op.enroll.userKey.keyGen.encryption.ca.conn=ca1
#Profile id we want the CA to use to issue our encrytion cert:
op.enroll.userKey.keyGen.encryption.ca.profileId=caTokenUserEncryptionKeyEnrollment

#These two cover the indexes of the certs written to the token. Each cert needs a unique index or “slot”. In our sample the enc cert will occupy slot 2 and the signing cert, shown later, will occupy slot 1. Avoid overlap with these numbers:
op.enroll.userKey.keyGen.encryption.certAttrId=c2
op.enroll.userKey.keyGen.encryption.certId=C2

op.enroll.userKey.keyGen.encryption.cuid_label=$cuid$
#specify size of generated private key:
op.enroll.userKey.keyGen.encryption.keySize=1024
op.enroll.userKey.keyGen.encryption.keyUsage=0
op.enroll.userKey.keyGen.encryption.keyUser=0
#specify pattern for what the label of the cert will look like when the cert nickname is displayed in browsers and mail clients:
op.enroll.userKey.keyGen.encryption.label=encryption key for $userid$
#specify if we want to overwrite certs on a re-enrollment operation. This is almost always the case:
op.enroll.userKey.keyGen.encryption.overwrite=true

#The next several settings specify the capabilities that the private key on the final token will inherit. For instance this will determine if the cert can be used for encryption or digital signatures. There are settings for both the private and public key.

op.enroll.userKey.keyGen.encryption.private.keyCapabilities.decrypt=true
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.derive=false
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.encrypt=false
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.private=true
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.sensitive=true
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.sign=false
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.signRecover=false
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.token=true
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.unwrap=true
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.verify=false
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.verifyRecover=false
op.enroll.userKey.keyGen.encryption.private.keyCapabilities.wrap=false
op.enroll.userKey.keyGen.encryption.privateKeyAttrId=k4
op.enroll.userKey.keyGen.encryption.privateKeyNumber=4
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.decrypt=false
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.derive=false
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.encrypt=true
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.private=false
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.sensitive=false
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.sign=false
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.signRecover=false
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.token=true
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.unwrap=false
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.verify=false
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.verifyRecover=false
op.enroll.userKey.keyGen.encryption.public.keyCapabilities.wrap=true

#The following index numbers correspond to the index or slot that the private and public keys occupy. The common formula we use is that the public key index will be 2 * cert id + 1, and the private key index, shown above will be 2 * cert id. In this example the cert id is 2, so the key ids will be 4 and 5 respectively. When composing these, be careful not to create conflicts. This applies to the signing key section below.

op.enroll.userKey.keyGen.encryption.publicKeyAttrId=k5
op.enroll.userKey.keyGen.encryption.publicKeyNumber=5

#specify if, when a certificate is slated for revocation, based on other rules, we want to check to see if some other token is using this cert in a shared situation. If this is set to true, and this situation is found the cert will not be revoked until the last token wants to revoke this cert:
op.enroll.userKey.keyGen.encryption.recovery.destroyed.holdRevocationUntilLastCredential=false

#specify, if we want server side keygen, if we want to have that generated key archived to the drm. This is almost always the case, since we want the ability to later recover a cert and its encryption private key back to a new token:
op.enroll.userKey.keyGen.encryption.serverKeygen.archive=true
#connection to drm to generate the key for us:
op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=kra1
#specify server side keygen of the encryption private key. This most often will be desired:
op.enroll.userKey.keyGen.encryption.serverKeygen.enable=true

#This setting tells us how many certs we want to enroll for this TPS profile, in the case “userKey”. Here we want 2 total certs. The next values then go on to index into the config what two types of certs we want, signing and encryption:
op.enroll.userKey.keyGen.keyType.num=2
op.enroll.userKey.keyGen.keyType.value.0=signing
op.enroll.userKey.keyGen.keyType.value.1=encryption

#configure the signing cert and keys we want on the token the settings for these are similar to the encryption settings already discussed, except the capability flags presented below, since this is a signing key.

op.enroll.userKey.keyGen.signing.ca.conn=ca1
op.enroll.userKey.keyGen.signing.ca.profileId=caTokenUserSigningKeyEnrollment
op.enroll.userKey.keyGen.signing.certAttrId=c1
op.enroll.userKey.keyGen.signing.certId=C1
op.enroll.userKey.keyGen.signing.cuid_label=$cuid$
op.enroll.userKey.keyGen.signing.keySize=1024
op.enroll.userKey.keyGen.signing.keyUsage=0
op.enroll.userKey.keyGen.signing.keyUser=0
op.enroll.userKey.keyGen.signing.label=signing key for $userid$
op.enroll.userKey.keyGen.signing.overwrite=true
op.enroll.userKey.keyGen.signing.private.keyCapabilities.decrypt=false
op.enroll.userKey.keyGen.signing.private.keyCapabilities.derive=false
op.enroll.userKey.keyGen.signing.private.keyCapabilities.encrypt=false
op.enroll.userKey.keyGen.signing.private.keyCapabilities.private=true
op.enroll.userKey.keyGen.signing.private.keyCapabilities.sensitive=true
op.enroll.userKey.keyGen.signing.private.keyCapabilities.sign=true
op.enroll.userKey.keyGen.signing.private.keyCapabilities.signRecover=true
op.enroll.userKey.keyGen.signing.private.keyCapabilities.token=true
op.enroll.userKey.keyGen.signing.private.keyCapabilities.unwrap=false
op.enroll.userKey.keyGen.signing.private.keyCapabilities.verify=false
op.enroll.userKey.keyGen.signing.private.keyCapabilities.verifyRecover=false
op.enroll.userKey.keyGen.signing.private.keyCapabilities.wrap=false
op.enroll.userKey.keyGen.signing.privateKeyAttrId=k2
op.enroll.userKey.keyGen.signing.privateKeyNumber=2
op.enroll.userKey.keyGen.signing.public.keyCapabilities.decrypt=false
op.enroll.userKey.keyGen.signing.public.keyCapabilities.derive=false
op.enroll.userKey.keyGen.signing.public.keyCapabilities.encrypt=false
op.enroll.userKey.keyGen.signing.public.keyCapabilities.private=false
op.enroll.userKey.keyGen.signing.public.keyCapabilities.sensitive=false
op.enroll.userKey.keyGen.signing.public.keyCapabilities.sign=false
op.enroll.userKey.keyGen.signing.public.keyCapabilities.signRecover=false
op.enroll.userKey.keyGen.signing.public.keyCapabilities.token=true
op.enroll.userKey.keyGen.signing.public.keyCapabilities.unwrap=false
op.enroll.userKey.keyGen.signing.public.keyCapabilities.verify=true
op.enroll.userKey.keyGen.signing.public.keyCapabilities.verifyRecover=true
op.enroll.userKey.keyGen.signing.public.keyCapabilities.wrap=false
op.enroll.userKey.keyGen.signing.publicKeyAttrId=k3
op.enroll.userKey.keyGen.signing.publicKeyNumber=3
Pin Reset
The configuration for pin reset is discussed in Section 6.3, “Token policies”, because pin reset relies on a policy to determine if it is to be legally performed or not.
Renewal
The configuration for renewal is discussed in Section 6.3, “Token policies”, since renewal relies on a policy to determine if it is legal to perform or not upon an already enrolled token.
Recovery

Recovery is implicitly set into motion when the user of the TPS user interface marks a previously active token into an unfavorable state such as “lost” or “destroyed”. Once this happens, the next enrollment of a new token by the same user will adhere to the following configuration to recover the certificates from the user’s old token, to this new token.

The end result of this operation is that the user will have a new physical token that may contain the encryption certificates recovered from the old token, so that the user can continue to encrypt and decrypt data as needed. A new signing certificate is also usually placed on this token as shown in the sample config examples below.

The following is a list of supported states into which a token can be placed manually in the TPS user interface, as seen in the configuration:

  • tokendb._069=# - DAMAGED (1): Corresponds to destroyed in the recovery configuration. Used when a token has been physically damaged.
  • tokendb._070=# - PERM_LOST (2): Corresponds to `keyCompromise`in the recovery configuration. Used when a token has been lost permanently.
  • tokendb._071=# - SUSPENDED (3): Corresponds to onHold in the recovery configuration. Used when a token has been temporarily misplaced, but the user expects to find it again.
  • tokendb._072=# - TERMINATED (6): Corresponds to terminated in the recovery configuration. Used to take a token out of service forever for internal reasons.

Example recovery configuration:

#When a token is marked destroyed, don’t revoke the certs on the token unless all other tokens do not have the certs included:
op.enroll.userKey.keyGen.encryption.recovery.destroyed.holdRevocationUntilLastCredential=false
#specify if we even want to revoke certs a token is marked destroyed:
op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert=false
#if we want to revoke any certs here, specify the reason for revocation that will be sent to the CA:
op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert.reason=0
#speficy if we want to revoke expired certs when marking the token destroyed:
op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeExpiredCerts=false

Additional settings are used to specify what kind of supported static recovery should be used when performing a recovery operation to a new token (when the original token has been marked destroyed). The following schemes are supported:

  • Recover Last (RecoverLast): Recover the latest encryption certificate to be placed on the token.
  • Generate New Key and Recover Last (GenerateNewKeyAndRecoverLast): Same as Recover Last, but also generate a new encryption certificate and upload it to the token as well. The new token will then have two certificates.
  • Generate New Key (GenerateNewKey): Generate a new encryption certificate and place it on the token. Do not recover any old certificates.

For example: 

op.enroll.userKey.keyGen.encryption.recovery.destroyed.scheme=RecoverLast

The following configuration example determines how to recover tokens marked as permanently lost: 

op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.holdRevocationUntilLastCredential=false
op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert=true
op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert.reason=1
op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeExpiredCerts=false
op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.scheme=GenerateNewKey

# Section when a token is marked terminated.

op.enroll.userKey.keyGen.encryption.recovery.terminated.holdRevocationUntilLastCredential=false
op.enroll.userKey.keyGen.encryption.recovery.terminated.revokeCert=true
op.enroll.userKey.keyGen.encryption.recovery.terminated.revokeCert.reason=1
op.enroll.userKey.keyGen.encryption.recovery.terminated.revokeExpiredCerts=false
op.enroll.userKey.keyGen.encryption.recovery.terminated.scheme=GenerateNewKey

# This section details the recovery profile with respect to which certs and of what kind get recovered on the token.

op.enroll.userKey.keyGen.recovery.destroyed.keyType.num=2
op.enroll.userKey.keyGen.recovery.destroyed.keyType.value.0=signing
op.enroll.userKey.keyGen.recovery.destroyed.keyType.value.1=encryption

Finally, the following example determines what the system will do about the signing certificate that was on the old token. In most cases, the GenerateNewKey recovery scheme should be used in order to avoid potentially having multiple copies of a signing private key available (for example, one that is recovered on a new token, and one on an old token that was permanently lost but found by somebody else). 

op.enroll.userKey.keyGen.recovery.keyCompromise.keyType.value.0=signing
op.enroll.userKey.keyGen.recovery.keyCompromise.keyType.value.1=encryption
op.enroll.userKey.keyGen.recovery.onHold.keyType.num=2
op.enroll.userKey.keyGen.recovery.onHold.keyType.value.0=signing
op.enroll.userKey.keyGen.recovery.onHold.keyType.value.1=encryption

op.enroll.userKey.keyGen.signing.recovery.destroyed.holdRevocationUntilLastCredential=false
op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert=true
op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert.reason=0
op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeExpiredCerts=false
op.enroll.userKey.keyGen.signing.recovery.destroyed.scheme=GenerateNewKey
op.enroll.userKey.keyGen.signing.recovery.keyCompromise.holdRevocationUntilLastCredential=false
op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeCert=true
op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeCert.reason=1
op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeExpiredCerts=false
op.enroll.userKey.keyGen.signing.recovery.keyCompromise.scheme=GenerateNewKey
op.enroll.userKey.keyGen.signing.recovery.onHold.holdRevocationUntilLastCredential=false
op.enroll.userKey.keyGen.signing.recovery.onHold.revokeCert=true

op.enroll.userKey.keyGen.signing.recovery.onHold.revokeCert.reason=6
op.enroll.userKey.keyGen.signing.recovery.onHold.revokeExpiredCerts=false
op.enroll.userKey.keyGen.signing.recovery.onHold.scheme=GenerateNewKey
op.enroll.userKey.keyGen.signing.recovery.terminated.holdRevocationUntilLastCredential=false
op.enroll.userKey.keyGen.signing.recovery.terminated.revokeCert=true
op.enroll.userKey.keyGen.signing.recovery.terminated.revokeCert.reason=1
op.enroll.userKey.keyGen.signing.recovery.terminated.revokeExpiredCerts=false
op.enroll.userKey.keyGen.signing.recovery.terminated.scheme=GenerateNewKey

# Configuration for the case when we mark a token “onHold” or temporarily lost

op.enroll.userKeyTemporary.keyGen.encryption.recovery.onHold.revokeCert=true
op.enroll.userKeyTemporary.keyGen.encryption.recovery.onHold.revokeCert.reason=0
op.enroll.userKeyTemporary.keyGen.encryption.recovery.onHold.scheme=RecoverLast
op.enroll.userKeyTemporary.keyGen.recovery.onHold.keyType.num=2
op.enroll.userKeyTemporary.keyGen.recovery.onHold.keyType.value.0=signing
op.enroll.userKeyTemporary.keyGen.recovery.onHold.keyType.value.1=encryption
op.enroll.userKeyTemporary.keyGen.signing.recovery.onHold.revokeCert=true
op.enroll.userKeyTemporary.keyGen.signing.recovery.onHold.revokeCert.reason=0
op.enroll.userKeyTemporary.keyGen.signing.recovery.onHold.scheme=GenerateNewKey
Applet Update

The following example shows how to configure a Coolkey applet update operation. This operation can be performed during format, enrollment, and PIN reset operations: 

op.format.userKey.update.applet.directory=/usr/share/pki/tps/applets
op.format.userKey.update.applet.emptyToken.enable=true
op.format.userKey.update.applet.encryption=true
op.format.userKey.update.applet.requiredVersion=1.4.54de790f

Some of these options have already been demonstrated in the Format section. They provide information needed to determine if applet upgrade should be allowed, where to find the applet files, and the applet version to upgrade the token to. The version in the requiredVersion maps to a file name inside the directory.

Key Update
This operation, which can take place during format, enrollment, and PIN reset operations, allows the user to have their Global Platform key set version upgraded from the default supplied by the manufacturer.
TPS

The following options will instruct the TPS to upgrade the keyset from 1 to 2 during the next format operation requested on behalf of a given token. After this is done, the TKS must derive the three new keys that will be written to the token, Afterwards, the token must be used with the same TPS and TKS installation, otherwise it will become locked. 

op.format.userKey.update.symmetricKeys.enable=true
op.format.userKey.update.symmetricKeys.requiredVersion=2

You can also specify a version lower than current to downgrade the keyset instead.

TKS

As mentioned above, the TKS must be configured to generate the new keys to write to the token. First, the new master key identifier, 02, must be mapped to its PKCS #11 object nickname in the TKS CS.cfg, as shown in the following example: 

tks.mk_mappings.#02#01=internal:new_master
tks.defKeySet.mk_mappings.#02#01=internal:new_master

The above will map a key set number to an actual master key which exists in the TKS NSS database.

Master keys are identified by IDs such as 01. The TKS maps these IDs to PKCS #11 object nicknames specified in the masterKeyId part of the mapping. Therefore, the first number is updated as the master key version is updated, and the second number stays consistent.

When attempting to upgrade from version 1 to version 2, the mapping determines how to find the master key nickname which will be used to derive the 3 parts of the new key set.

The setting of internal in the above example references the name of the token where the master key resides. It could also be an external HSM module with a name such as nethsm. The strong new_master is an example of the master key nickname itself.

6.5. Internal registration

Note

See the TPS Profiles section of the Red Hat Certificate System Planning, Installation and Deployment Guide for general information.

In case of Internal Registration, the TPS profile (token type) is determined by the Mapping Resolver. In contrast with External Registration, authentication information is defined within the profile itself. For example: 

op.enroll.userKey.auth.enable=true
op.enroll.userKey.auth.id=ldap1

Another difference from External Registration is that the CA and KRA connector information is defined under each key type of each profile. For example: 

op.enroll.userKey.keyGen.encryption.ca.conn=ca1
op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=kra1

TKS connector information, however, is defined per profile: 

op.enroll.userKey.tks.conn=tks1
Note

Switching registration types between Internal and External Registration means you have to format all previously registered tokens before you can continue using them.

6.6. External registration

External Registration obtains the token type (TPS profile) from the authenticated user LDAP record. It also allows certificate/key recovery information to be specified in the same user record.

An External Registration TPS profile is similar to the Internal Registration profile discussed previously. It allows you to specify new certificate enrollments for both client-side and server-side key generation. Unlike Internal Registration, it allows you to choose specific certificate (and its matching keys) to be retrieved and loaded onto the token.

Note

Switching registration types between Internal and External Registration means you have to format all previously registered tokens before you can continue using them.

6.6.1. Enabling External Registration

External Registration can only be enabled globally for an entire TPS instance. The following example shows a set of global configuration parameters pertaining to External Registration: 

externalReg.allowRecoverInvalidCert.enable=true
externalReg.authId=ldap1
externalReg.default.tokenType=externalRegAddToToken
externalReg.delegation.enable=true
externalReg.enable=true
externalReg.recover.byKeyID=false
externalReg.format.loginRequest.enable=true
externalReg.mappingResolver=keySetMappingResolver

6.6.2. Customizing user LDAP record attribute names

Authentication parameters pertaining to External Registration are shown in the following example (with their default values): 

auths.instance.ldap1.externalReg.certs.recoverAttributeName=certsToAdd
auths.instance.ldap1.externalReg.cuidAttributeName=tokenCUID
auths.instance.ldap1.externalReg.tokenTypeAttributeName=tokenType

The LDAP record attribute names can be customized here. Make sure that the actual attributes in the user’s LDAP records match this configuration.

6.6.3. Configuring certsToAdd attributes

The certsToAdd attribute takes multiple values in the following form: 

<cert serial # in decimal>,<CA connector ID>,<key ID>,<kra connector ID>

For example: 

59,ca1,0,kra1
Important

By default, key recovery searches for the key by certificate, which makes the <key ID> value irrelevant. However, the TPS can optionally be configured to search for the key using this attribute, and therefore it is typically simpler to set the value to 0. That value is invalid, which avoids the possibility of retrieving an unmatched key.

Recovering by key ID is not recommended, because the KRA can not verify if the certificate matches with the key in this situation.

When specifying the certsToAdd attribute with only certificate and CA information, the TPS assumes that the certificate in question is already on the token, and that it should be preserved. This concept is called Key Retention.

The following examples show relevant attributes in the user LDAP record: 

tokenType: externalRegAddToToken
certstoadd: 59,ca1,0,kra1
certstoadd: 134,ca1,0,kra1
Certstoadd: 24,ca1

6.6.4. Token to user matching enforcement

Optionally, you can set the system up so that the token used for registration must match the token record card-unique ID (CUID) attribute in the user record. If this attribute (tokencuid) is missing from the record, CUID matching is not enforced. 

Tokencuid: a10192030405028001c0

Another attribute about External Registration is that the Token Policies on each token are bypassed.

Note

For the certificate and keys to be “recovered” in External Registration, connector information for CA and KRA is specified in the user LDAP record. Any CA and/or KRA connector information specified in the TPS profile pertaining to the certificate/keys to be “recovered” is to be ignored. 

certstoadd: 59,ca1,0,kra1

6.6.5. Delegation Support

Delegation support is useful where a user has delegates who can act on their behalf (for example, an executive at a company has one or more delegates) in terms of authentication (logins), data encryption and decryption, or signing (with limitations).

An example scenario could be that each delegate has their own token which they use to act on behalf of the executive. This token contains a combination of the following certificates and keys (determined by TPS profiles):

  • Authentication certificate/keys: The CN contains the name and unique ID of the delegate. The Subject Alternative Name (SAN) extension contains the Principal Name (UPN) of the executive.
  • Encryption certificate: An exact copy of the executive’s encryption certificate.
  • Signing certificate: The CN contains the delegate’s name and unique ID. The SAN contains the RFC822Name of the executive.

Use the following parameter to enable delegation support: 

externalReg.delegation.enable=true
Important

To work around a bug, manually set the op.enroll.delegateISEtoken.keyGen.encryption.ca.profileId parameter in the /var/lib/pki/ instance_name/tps/conf/CS.cfg file to caTokenUserDelegateAuthKeyEnrollment: 

op.enroll.delegateISEtoken.keyGen.encryption.ca.profileId=caTokenUserDelegateAuthKeyEnrollment

6.6.6. SAN and DN Patterns

The auths.instance.<authID>.ldapStringAttributes in the authentication instance configuration specifies which attributes will be retrieved during authentication. For example: 

auths.instance.ldap1.ldapStringAttributes=mail,cn,uid,edipi,pcc,firstname,lastname,exec-edipi,exec-pcc,exec-mail,certsToAdd,tokenCUID,tokenType

Once retrieved from the user’s LDAP record, the values of these attributes can be referenced and used to form the Subject Alternative Name (SAN) or Distinguished Name (DN) of the certificate in the format of $auth.<attribute name>$. For example: 

op.enroll.delegateIEtoken.keyGen.authentication.SANpattern=$auth.exec-edipi$.$auth.exec-pcc$@EXAMPLE.com
op.enroll.delegateIEtoken.keyGen.authentication.dnpattern=cn=$auth.firstname$.$auth.lastname$.$auth.edipi$,e=$auth.mail$,o=TMS Org

When patterns are used in TPS profiles for SAN and DN, it is important to ensure the CA enrollment profile specified in the TPS profile is set up correctly. For example:

On TPS, in profile delegateIEtoken
op.enroll.delegateIEtoken.keyGen.authentication.ca.profileId=caTokenUserDelegateAuthKeyEnrollment
On the CA, in enrollment profile caTokenUserDelegateAuthKeyEnrollment

The subjectDNInputImpl plug-in must be specified as one of the inputs in order to allow the DN to be specified by the TPS profile above: 

input.i2.class_id=subjectDNInputImpl
input.i2.name=subjectDNInputImpl

Similarly, to allow the SAN to be specified by the above TPS profile, the subjectAltNameExtInputImpl plug-in must be specified: 

input.i3.class_id=subjectAltNameExtInputImpl
input.i3.name=subjectAltNameExtInputImpl

The subjAltExtpattern must be specified as well: 

policyset.set1.p6.default.params.subjAltExtPattern_0=(UTF8String)1.3.6.1.4.1.311.20.2.3,$request.req_san_pattern_0$

In the above example, the OID 1.3.6.1.4.1.311.20.2.3 is the OID for the User Principal Name (UPN), and request.req_san_pattern_0 is the first SAN pattern specified in the delegateIEtoken SAN pattern.

You can specify multiple SANs at the same time. On the TPS side, specify multiple SANs in the SANpattern, delimited by a comma (“,”). On the CA side, a corresponding amount of subjAltExtPattern needs to be defined in the following format: 

policyset.<policy set id>.<policy id>.default.params.subjAltExtPattern_<ordered number>=

In the above, the <ordered number> starts with 0 and increases by one for each SAN pattern specified on the TPS side: 

policyset.set1.p6.default.params.subjAltExtPattern_0=
policyset.set1.p6.default.params.subjAltExtPattern_1=
...

The following is a complete example:

Example 6.1. SANpattern and DNpattern configuration

The LDAP record contains the following information: 

givenName: user1a
mail: user1a@example.org
firstname: user1a
edipi: 123456789
pcc: AA
exec-edipi: 999999999
exec-pcc: BB
exec-mail: user1b@EXAMPLE.com
tokenType: delegateISEtoken
certstoadd: 59,ca1,0,kra1

TPS External Registration profile delegateIEtoken contains:

  • SANpattern: 

    op.enroll.delegateISEtoken.keyGen.authentication.SANpattern=$auth.exec-edipi$.$auth.exec-pcc$@EXAMPLE.com

  • DNPattern: 

    op.enroll.delegateISEtoken.keyGen.authentication.dnpattern=cn=$auth.firstname$.$auth.lastname$.$auth.edipi$,e=$auth.mail$,o=TMS Org

CA caTokenUserDelegateAuthKeyEnrollment contains: 

input.i2.class_id=subjectDNInputImpl
input.i2.name=subjectDNInputImpl
input.i3.class_id=subjectAltNameExtInputImpl
input.i3.name=subjectAltNameExtInputImpl

policyset.set1.p6.constraint.class_id=noConstraintImpl
policyset.set1.p6.constraint.name=No Constraint
policyset.set1.p6.default.class_id=subjectAltNameExtDefaultImpl
policyset.set1.p6.default.name=Subject Alternative Name Extension Default
policyset.set1.p6.default.params.subjAltExtGNEnable_0=true
policyset.set1.p6.default.params.subjAltExtPattern_0=(UTF8String)1.3.6.1.4.1.311.20.2.3,$request.req_san_pattern_0$
policyset.set1.p6.default.params.subjAltExtType_0=OtherName
policyset.set1.p6.default.params.subjAltNameExtCritical=false
policyset.set1.p6.default.params.subjAltNameNumGNs=1

The resulting certificate then contains: 

Subject: CN=user1a..123456789,E=user1a@example.org,O=TMS Org
Identifier: Subject Alternative Name - 2.5.29.17
Critical: no
Value:
  OtherName: (UTF8String)1.3.6.1.4.1.311.20.2.3,999999999.BB@EXAMPLE.com

6.7. Mapping resolver configuration

The Token Processing System provides a single mapping resolver by default. The resolver is called FilterMappingResolver. This section will cover its configuration.

Note

See the Mapping Resolver section of the Red Hat Certificate System Planning, Installation, and Deployment Guide for general information about the Mapping Resolver.

6.7.1. Key set mapping resolver

During External Registration, the key set must be resolved using the resolver before a user can authenticate.

The key set mapping resolver name is defined as follows: 

externalReg.mappingResolver=<keySet mapping resolver name>

For example: 

externalReg.mappingResolver=keySetMappingResolver

The following configuration example shows a full instance configuration: 

mappingResolver.keySetMappingResolver.class_id=filterMappingResolverImpl
mappingResolver.keySetMappingResolver.mapping.0.filter.appletMajorVersion=0
mappingResolver.keySetMappingResolver.mapping.0.filter.appletMinorVersion=0
mappingResolver.keySetMappingResolver.mapping.0.filter.keySet=
mappingResolver.keySetMappingResolver.mapping.0.filter.tokenATR=
mappingResolver.keySetMappingResolver.mapping.0.filter.tokenCUID.end=a1000000000000000000
mappingResolver.keySetMappingResolver.mapping.0.filter.tokenCUID.start=a0000000000000000000
mappingResolver.keySetMappingResolver.mapping.0.target.keySet=defKeySet
mappingResolver.keySetMappingResolver.mapping.1.filter.appletMajorVersion=1
mappingResolver.keySetMappingResolver.mapping.1.filter.appletMinorVersion=1
mappingResolver.keySetMappingResolver.mapping.1.filter.keySet=
mappingResolver.keySetMappingResolver.mapping.1.filter.tokenATR=1234
mappingResolver.keySetMappingResolver.mapping.1.filter.tokenCUID.end=
mappingResolver.keySetMappingResolver.mapping.1.filter.tokenCUID.start=
mappingResolver.keySetMappingResolver.mapping.1.target.keySet=defKeySet
mappingResolver.keySetMappingResolver.mapping.2.filter.appletMajorVersion=
mappingResolver.keySetMappingResolver.mapping.2.filter.appletMinorVersion=
mappingResolver.keySetMappingResolver.mapping.2.filter.keySet=
mappingResolver.keySetMappingResolver.mapping.2.filter.tokenATR=
mappingResolver.keySetMappingResolver.mapping.2.filter.tokenCUID.end=
mappingResolver.keySetMappingResolver.mapping.2.filter.tokenCUID.start=
mappingResolver.keySetMappingResolver.mapping.2.target.keySet=jForte
mappingResolver.keySetMappingResolver.mapping.order=0,1,2

The above example defines three mappings named 0, 1, and 2. They are ordered in ascending order using the mappingResolver.keySetMappingResolver.mapping.order=0,1,2 line in the example. This order means the input parameters will be run against the mapping filter 0 first; only if they do not match that filter, the next one in the mapping order will be tried. For example, if a token with the following characteristics is evaluated: 

CUID=a0000000000000000011
appletMajorVersion=0
appletMinorVersion=0

Then it would pass mapping 0 and be assigned its target, which is configured to defKeySet, because the applet version matches and the CUID falls within the CUID start and end range for that mapping.

On the other hand, if a token has the following parameters: 

CUID=b0000000000000000000
ATR=2222
appletMajorVersion=1
appletMinorVersion=1

In this case this token fails mapping 0 because it is outside the specified CUID range. It also fails mapping 1 because while the applet versions match, the ATR does not. The above token will be assigned to mapping 2 and its target, jForte.

Note how mapping 2 has no assignments for any of its filters. This causes the mapping to match all tokens, effectively making it a "default" value. Mappings like this must be specified last in the mapping order, because any other mappings after it will never be evaluated.

6.7.2. Token Type (TPS) mapping resolver

There are three default tokenType mapping resolvers defined in the Token Processing System: formatProfileMappingResolver, enrollProfileMappingResolver, and pinResetProfileMappingResolver. Compared to the External Registration case discussed in the previous section, in the Internal Registration case token types are actually calculated from the defined mapping resolver.

The token type mapping resolver names are defined as follows: 

op.<op>.mappingResolver=<mapping resolver name>

For example: 

op.enroll.mappingResolver=enrollProfileMappingResolver

The following configuration example describes the enrollProfileMappingResolver: 

mappingResolver.enrollProfileMappingResolver.class_id=filterMappingResolverImpl
mappingResolver.enrollProfileMappingResolver.mapping.0.filter.appletMajorVersion=1
mappingResolver.enrollProfileMappingResolver.mapping.0.filter.appletMinorVersion=
mappingResolver.enrollProfileMappingResolver.mapping.0.filter.tokenATR=
mappingResolver.enrollProfileMappingResolver.mapping.0.filter.tokenCUID.end=b1000000000000000000
mappingResolver.enrollProfileMappingResolver.mapping.0.filter.tokenCUID.start=b0000000000000000000
mappingResolver.enrollProfileMappingResolver.mapping.0.filter.tokenType=userKey
mappingResolver.enrollProfileMappingResolver.mapping.0.target.tokenType=userKey
mappingResolver.enrollProfileMappingResolver.mapping.1.filter.appletMajorVersion=1
mappingResolver.enrollProfileMappingResolver.mapping.1.filter.appletMinorVersion=
mappingResolver.enrollProfileMappingResolver.mapping.1.filter.tokenATR=
mappingResolver.enrollProfileMappingResolver.mapping.1.filter.tokenCUID.end=a0000000000000001000
mappingResolver.enrollProfileMappingResolver.mapping.1.filter.tokenCUID.start=a0000000000000000000
mappingResolver.enrollProfileMappingResolver.mapping.1.filter.tokenType=soKey
mappingResolver.enrollProfileMappingResolver.mapping.1.target.tokenType=soKey
mappingResolver.enrollProfileMappingResolver.mapping.2.filter.appletMajorVersion=
mappingResolver.enrollProfileMappingResolver.mapping.2.filter.appletMinorVersion=
mappingResolver.enrollProfileMappingResolver.mapping.2.filter.tokenATR=
mappingResolver.enrollProfileMappingResolver.mapping.2.filter.tokenCUID.end=
mappingResolver.enrollProfileMappingResolver.mapping.2.filter.tokenCUID.start=
mappingResolver.enrollProfileMappingResolver.mapping.2.filter.tokenType=
mappingResolver.enrollProfileMappingResolver.mapping.2.target.tokenType=userKey
mappingResolver.enrollProfileMappingResolver.mapping.order=1,0,2

Three mappings are defined for the enrollProfileMappingResolver in the above example. The mappings are named 0, 1, and 2. The mappingResolver.enrollProfileMappingResolver.mapping.order=1,0,2 line defines the order in which the mappings will be processed. If a token matches a mapping, no further mappings in the order will be evaluated; if it does not match a mapping, the next one in the order will be tried.

In case of a token with the following parameters: 

CUID=a0000000000000000011
appletMajorVersion=1
appletMinorVersion=0
extension: tokenType=soKey

A token with this configuration will match the filters for mapping 1 because the applet version matches, the CUID fails within the specified start and end range, and the extension tokenType matches. Therefore, this token will be assigned the target for that mapping - soKey.

In another case, if the token has the following parameters: 

CUID=b0000000000000000010
appletMajorVersion=1
appletMinorVersion=1

In this case, the token will fail mapping 1 because the CUID is outside the specified range. Then it will also fail mapping 0, because the tokenType extension is missing. This token will then match mapping 2, because it has no specified filters in order to match all tokens which did not match any of the previous filters.

6.8. Authentication configuration

The Token Processing System supports directory-based authentication using a user ID and password (UidPwdDirAuthentication) by default. Authentication instances are defined in the CS.cfg file using the following pattern: 

auths.instance.<auths ID>.*

The <auths ID> is the authenticator name to be referenced by the TPS profiles for authentication preferences. For example: 

op.enroll.userKey.auth.id=ldap1

The following configuration example shows a full definition of an authentication instance: 

auths.impl.UidPwdDirAuth.class=com.netscape.cms.authentication.UidPwdDirAuthentication
auths.instance.ldap1.pluginName=UidPwdDirAuth
auths.instance.ldap1.authCredName=uid
auths.instance.ldap1.dnpattern=
auths.instance.ldap1.externalReg.certs.recoverAttributeName=certsToAdd
auths.instance.ldap1.externalReg.cuidAttributeName=tokenCUID
auths.instance.ldap1.externalReg.tokenTypeAttributeName=tokenType
auths.instance.ldap1.ldap.basedn=dc=sjc,dc=example,dc=com
auths.instance.ldap1.ldap.ldapauth.authtype=BasicAuth
auths.instance.ldap1.ldap.ldapauth.bindDN=
auths.instance.ldap1.ldap.ldapauth.bindPWPrompt=ldap1
auths.instance.ldap1.ldap.ldapauth.clientCertNickname=subsystemCert cert-pki-tomcat
auths.instance.ldap1.ldap.ldapconn.host=host1.EXAMPLE.com
auths.instance.ldap1.ldap.ldapconn.port=389
auths.instance.ldap1.ldap.ldapconn.secureConn=False
auths.instance.ldap1.ldap.ldapconn.version=3
auths.instance.ldap1.ldap.maxConns=15
auths.instance.ldap1.ldap.minConns=3
auths.instance.ldap1.ldapByteAttributes=
auths.instance.ldap1.ldapStringAttributes=mail,cn,uid,edipi,pcc,firstname,lastname,exec-edipi,exec-pcc,exec-mail,certsToAdd,tokenCUID,tokenType
auths.instance.ldap1.ldapStringAttributes._000=#################################
auths.instance.ldap1.ldapStringAttributes._001=# For isExternalReg
auths.instance.ldap1.ldapStringAttributes._002=#   attributes will be available as
auths.instance.ldap1.ldapStringAttributes._003=#       $<attribute>$
auths.instance.ldap1.ldapStringAttributes._004=#   attributes example:
auths.instance.ldap1.ldapStringAttributes._005=#mail,cn,uid,edipi,pcc,firstname,lastname,exec-edipi,exec-pcc,exec-mail,certsToAdd,tokenCUID,tokenType
auths.instance.ldap1.ldapStringAttributes._006=#################################
auths.instance.ldap1.pluginName=UidPwdDirAuth
auths.instance.ldap1.ui.description.en=This authenticates user against the LDAP directory.
auths.instance.ldap1.ui.id.PASSWORD.credMap.authCred=pwd
auths.instance.ldap1.ui.id.PASSWORD.credMap.msgCred.extlogin=PASSWORD
auths.instance.ldap1.ui.id.PASSWORD.credMap.msgCred.login=password
auths.instance.ldap1.ui.id.PASSWORD.description.en=LDAP Password
auths.instance.ldap1.ui.id.PASSWORD.name.en=LDAP Password
auths.instance.ldap1.ui.id.UID.credMap.authCred=uid
auths.instance.ldap1.ui.id.UID.credMap.msgCred.extlogin=UID
auths.instance.ldap1.ui.id.UID.credMap.msgCred.login=screen_name
auths.instance.ldap1.ui.id.UID.description.en=LDAP User ID
auths.instance.ldap1.ui.id.UID.name.en=LDAP User ID
auths.instance.ldap1.ui.retries=3
auths.instance.ldap1.ui.title.en=LDAP Authentication

TPS authentication instances are configured in a way similar to the CA’s UidPwdDirAuthentication authentication instance, since both are handled by the same plug-in. However, the TPS requires several extra parameters on top of the CA configuration.

In case of common operations (for both Internal and External registration), profiles that call for this authentication method allow TPS to project how the UID and password will be labeled on the client side. This is controlled by the auths.instance.ldap1.ui.id.UID.name.en=LDAP User ID and auths.instance.ldap1.ui.id.PASSWORD.name.en=LDAP Password parameters in the above example; this configuration tells clients to display the UID/password pair as "LDAP User ID" and "LDAP Password". Both parameters can be customized.

The credMap.authCred entries configure how the internal authentication plug-in accepts information presented to it, and the credMap.msgCred entries configure how this information is passed to the TPS. These fields allow you to use customized plug-in implementations, and should be left at their default values unless you are using a custom authentication plug-in.

Parameters related to External Registration are discussed in Section 6.6, “External registration”.

Similarly to CA authentication configuration, you can define multiple authentication instances for the same authentication implementation. This may be useful when the TPS serves multiple groups of users; you can direct each group to use its own TPS profile, each configured to use its own directory server authentication.

6.9. Connectors

Connectors define how the TPS communicates with other subsystems - namely CA, KRA, and TKS. In general, these parameters are set up during TPS installation. The following is an example of connector configuration: 

tps.connector.ca1.enable=true
tps.connector.ca1.host=host1.EXAMPLE.com
tps.connector.ca1.maxHttpConns=15
tps.connector.ca1.minHttpConns=1
tps.connector.ca1.nickName=subsystemCert cert-pki-tomcat
tps.connector.ca1.port=8443
tps.connector.ca1.timeout=30
tps.connector.ca1.uri.enrollment=/ca/ee/ca/profileSubmitSSLClient
tps.connector.ca1.uri.getcert=/ca/ee/ca/displayBySerial
tps.connector.ca1.uri.renewal=/ca/ee/ca/profileSubmitSSLClient
tps.connector.ca1.uri.revoke=/ca/ee/subsystem/ca/doRevoke
tps.connector.ca1.uri.unrevoke=/ca/ee/subsystem/ca/doUnrevoke
tps.connector.kra1.enable=true
tps.connector.kra1.host=host1.EXAMPLE.com
tps.connector.kra1.maxHttpConns=15
tps.connector.kra1.minHttpConns=1
tps.connector.kra1.nickName=subsystemCert cert-pki-tomcat
tps.connector.kra1.port=8443
tps.connector.kra1.timeout=30
tps.connector.kra1.uri.GenerateKeyPair=/kra/agent/kra/GenerateKeyPair
tps.connector.kra1.uri.TokenKeyRecovery=/kra/agent/kra/TokenKeyRecovery
tps.connector.tks1.enable=true
tps.connector.tks1.generateHostChallenge=true
tps.connector.tks1.host=host1.EXAMPLE.com
tps.connector.tks1.keySet=defKeySet
tps.connector.tks1.maxHttpConns=15
tps.connector.tks1.minHttpConns=1
tps.connector.tks1.nickName=subsystemCert cert-pki-tomcat
tps.connector.tks1.port=8443
tps.connector.tks1.serverKeygen=true
tps.connector.tks1.timeout=30
tps.connector.tks1.tksSharedSymKeyName=sharedSecret
tps.connector.tks1.uri.computeRandomData=/tks/agent/tks/computeRandomData
tps.connector.tks1.uri.computeSessionKey=/tks/agent/tks/computeSessionKey
tps.connector.tks1.uri.createKeySetData=/tks/agent/tks/createKeySetData
tps.connector.tks1.uri.encryptData=/tks/agent/tks/encryptData

TPS profiles refer to these connectors by their IDs. For example 

op.enroll.userKey.keyGen.signing.ca.conn=ca1

Multiple connector of the same kind (for example, multiple CA connectors) can be defined. This may be useful when one TPS instance serves multiple backend Certificate System servers for different groups of tokens.

Note

Automatic failover for connectors in TPS is currently not supported. A manual failover procedure must be performed to point the TPS to alternate CA, KRA, or TKS, as long as they are clones of the original systems.

6.10. Revocation routing configuration

To configure revocation routing, you must first define a list of relevant CA connectors and add them to the connector list in the following format: 

tps.connCAList=ca1,ca2

Additionally, you must add the CA signing certificate to the TPS nssdb and set up trust: 

#cd <TPS instance directory>/alias
#certutil -d . -A -n <CA signing cert nickname> -t “CT,C,C” -i <CA signing cert b64 file name>

Finally, the nickname of the CA signing certificate must be added to the connector using the following option: 

tps.connector.ca1.caNickname=caSigningCert cert-pki-tomcat CA
Note

During CA discovery, the TPS may automatically calculate the Authority Key Identifier of the CA and add it to the connector configuration. For example: 

tps.connector.ca1.caSKI=i9wOnN0QZLkzkndAB1MKMcjbRP8=

This behavior is expected.

6.10.1. Setting up Server-side Key Generation

Server-side key generation means that keys are generated by a Key Recovery Authority (KRA), an optional Certificate System subsystem. Generating keys by the KRA is necessary to allow recovery of keys on lost or damaged tokens, or key retrieval in the case of external registration. This section describes how to configure server-side key generation in TMS.

During TPS installation you are asked to specify whether you want to use key archival. If you confirm, setup will perform automatic basic configuration, specifically the following parameters:

TPS connector parameters for the KRA
tps.connector.kra1.enable=true
tps.connector.kra1.host=host1.EXAMPLE.com
tps.connector.kra1.maxHttpConns=15
tps.connector.kra1.minHttpConns=1
tps.connector.kra1.nickName=subsystemCert cert-pki-tomcat
tps.connector.kra1.port=8443
tps.connector.kra1.timeout=30
tps.connector.kra1.uri.GenerateKeyPair=/kra/agent/kra/GenerateKeyPair
tps.connector.kra1.uri.TokenKeyRecovery=/kra/agent/kra/TokenKeyRecovery
TPS profile-specific parameters for server-side key generation
op.enroll.userKey.keyGen.encryption.serverKeygen.archive=true
op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=kra1
op.enroll.userKey.keyGen.encryption.serverKeygen.enable=true

Set the serverKeygen.enable=true option for serverKeygen.archive to take effect.

Important

The LunaSA HSM does not support a smaller key size than 2048 bits for RSA encryption.

For example, to configure a key size of 2048 bits, set the following parameter in the /var/lib/pki/ instance_name/tps/conf/CS.cfg file: 

op.enroll.userKey.keyGen.encryption.keySize=2048
TKS configuration

The following configures the nickname of the transport certificate used for communication between the TKS and KRA (via TPS): 

tks.drm_transport_cert_nickname=transportCert cert-pki-tomcat KRA

The referenced transport certificate must also exist in the TKS instance security module. For example: 

transportCert cert-pki-tomcat KRA                            u,u,u
KRA configuration

Depending on the PKCS#11 token, parameters kra.keygen.temporaryPairs, kra.keygen.sensitivePairs, and kra.keygen.extractablePairs can be customized for key generation options. These parameters are all set to false by default.

The following values for these parameters have been tested with some of the security modules supported by Red Hat Certificate System:

NSS (when in FIPS mode)
kra.keygen.extractablePairs=true
nCipher nShield Connect 6000 (works by default without specifying)

  • For specifying RSA keys: 

    kra.keygen.temporaryPairs=true

    (Do not specify any other parameters.)

  • For generating ECC keys: 

    kra.keygen.temporaryPairs=true
kra.keygen.sensitivePairs=false
kra.keygen.extractablePairs=true
LunaSA CKE - Key Export Model (non-FIPS mode)
kra.keygen.temporaryPairs=true
kra.keygen.sensitivePairs=true
kra.keygen.extractablePairs=true
Note

Gemalto SafeNet LunaSA only supports PKI private key extraction in its CKE - Key Export model, and only in non-FIPS mode. The LunaSA Cloning model and the CKE model in FIPS mode do not support PKI private key extraction.

Note

When LunaSA CKE – Key Export Model is in FIPS mode, pki private keys cannot be extracted.

6.11. Setting up new key sets

This section describes setting up an alternative to the default key set in the Token Processing System (TPS) and in the Token Key Service (TKS).

TKS configuration

The default key set is configured in the TKS using the following options in the /var/lib/pki/ instance_name/tks/conf/CS.cfg file: 

tks.defKeySet._000=##
tks.defKeySet._001=## Axalto default key set:
tks.defKeySet._002=##
tks.defKeySet._003=## tks.defKeySet.mk_mappings.#02#01=<tokenname>:<nickname>
tks.defKeySet._004=##
tks.defKeySet.auth_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f
tks.defKeySet.kek_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f
tks.defKeySet.mac_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f
tks.defKeySet.nistSP800-108KdfOnKeyVersion=00
tks.defKeySet.nistSP800-108KdfUseCuidAsKdd=false

The above configuration defines settings specific to a certain type or class of tokens that can be used in the TMS. The most important part are the 3 developer or (out of the box) session keys, which are used to create a secure channel before symmetric key handover takes place. A different type of key may have different default values for these keys.

The settings describing the nistSP800 key diversification method control whether this method or the standard Visa method is used. Specifically, the value of the tks.defKeySet.nistSP800-108KdfOnKeyVersion option determines that the NIST version will be used. The nistSP800-108KdfUseCuidAsKdd option allows you to use the legacy key ID value of CUID during processing. The newer KDD value is most commonly used and therefore this option is disabled (false) by default. This allows you to configure a new key set to enable support for a new class of keys.

Example 6.2. Enabling support for the jForte class

To enable support for the jForte class, set: 

tks.jForte._000=##
tks.jForte._001=## SAFLink's jForte default key set:
tks.jForte._002=##
tks.jForte._003=## tks.jForte.mk_mappings.#02#01=<tokenname>:<nickname>
tks.jForte._004=##
tks.jForte.auth_key=#30#31#32#33#34#35#36#37#38#39#3a#3b#3c#3d#3e#3f
tks.jForte.kek_key=#50#51#52#53#54#55#56#57#58#59#5a#5b#5c#5d#5e#5f
tks.jForte.mac_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f
tks.jForte.nistSP800-108KdfOnKeyVersion=00
tks.jForte.nistSP800-108KdfUseCuidAsKdd=false

Note the difference in the 3 static session keys compared to the previous example.

Certificate System supports the Secure Channel Protocol 03 (SCP03) for Giesecke & Devrient (G&D) Smart Cafe 6 smart cards. To enable SCP03 support for these smart cards in a TKS, set in the /var/lib/pki/ instance_name/tks/conf/CS.cfg file: 

tks.defKeySet.prot3.divers=emv
tks.defKeySet.prot3.diversVer1Keys=emv
tks.defKeySet.prot3.devKeyType=DES3
tks.defKeySet.prot3.masterKeyType=DES3
TPS configuration

The TPS must be configured to recognize the new key set when a supported client attempts to perform an operation on a token. The default defKeySet is used most often.

The primary method to determine the keySet in the TPS involves Section 6.7, “Mapping resolver configuration”. See the linked section for a discussion of the exact settings needed to establish this resolver mechanism.

If the KeySet Mapping Resolver is not present, several fallback methods are available for the TPS to determine the correct keySet:

  • You can add the tps.connector.tks1.keySet=defKeySet to the CS.cfg configuration file of the TPS.
  • Certain clients can possibly be configured to explicitly pass the desired keySet value. However, the Enterprise Security Client does not have this ability at this point.
  • When the TPS calculates the proper keySet based on the desired method, all requests to the TKS to help create secure channels pass the keySet value as well. The TKS can then use its own keySet configuration (described above) to determine how to proceed.

6.12. Setting up a new master key

This section will describe the procedures and configuration required to set up a new master key in the Token Key Service (TKS). See the Red Hat Certificate System Planning, Installation, and Deployment Guide for background information.

Procedure: Creating a new master key

  1. Obtain internal the PIN required to access the TKS security databases: 

    # cat /var/lib/pki/pki-tomcat/tks/conf/password.conf
internal=649713464822
internaldb=secret12
replicationdb=-752230707

  2. Open the alias/ directory of the TKS instance: 

    # cd /var/lib/pki/pki-tomcat/alias

  3. Generate a new master key using the caTokenUserDelegateAuthKeyEnrollment utility. For example: 

    # tkstool -M -n new_master -d /var/lib/pki/pki-tomcat/alias -h <token_name>
Enter Password or Pin for "NSS Certificate DB":

Generating and storing the master key on the specified token . . .

Naming the master key "new_master" . . .

Computing and displaying KCV of the master key on the specified token . . .

new_master key KCV:  CA5E 1764

  4. Verify that the keys have been properly added to the database: 

    # tkstool -L -d .


 slot:  NSS User Private Key and Certificate Services
token:  NSS Certificate DB

Enter Password or Pin for "NSS Certificate DB":
        <0> new_master

6.12.1. Generating and transporting wrapped master keys (key ceremony)

If a master key is going to be used on an external token or in multiple locations, then it must be wrapped so that it can be safely transported to the hardware tokens. The caTokenUserDelegateAuthKeyEnrollment utility can be used to generate transport keys, which are then used to send the master key to the facility where the tokens are generated. The process of transferring wrapped master keys is commonly called a Key Ceremony.

Note

Transport keys can only be used with the master key they were generated with.

Procedure: Generating and transporting wrapped master keys

  1. Obtain the internal PIN required to access the Token Key Service security databases: 

    # cat /var/lib/pki/pki-tomcat/tks/conf/password.conf

internal=649713464822
internaldb=secret12
replicationdb=-752230707

  2. Open the TKS instance alias/ directory: 

    # cd /var/lib/pki/pki-tomcat/alias

  3. Create a transport key named transport: 

    # tkstool -T -d . -n transport
    Note

    The caTokenUserDelegateAuthKeyEnrollment utility prints out the key shares and KCV values for each of the three session keys generated. Save them to a file as they are necessary to regenerate the transport key in new databases later in this procedure, and to regenerate the key if lost.

  4. When prompted, fill in the database password. Then, follow on-screen instructions to generate a random seed. 

    A random seed must be generated that will be used in the
creation of your key.  One of the easiest ways to create a
random seed is to use the timing of keystrokes on a keyboard.

To begin, type keys on the keyboard until this progress meter
is full.  DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD!


Continue typing until the progress meter is full:

||

Finished.


Type the word "proceed" and press enter

  5. The next prompt will generate a series of session keys. Follow on-screen instructions until the final message: 

    Successfully generated, stored, and named the transport key!

  6. Use the transport key to generate and wrap a master key and store it in a file named file: 

    # tkstool -W -d . -n new_master -t transport -o file
Enter Password or Pin for "NSS Certificate DB":
Retrieving the transport key (for wrapping) from the specified token . . .
Generating and storing the master key on the specified token . . .
Naming the master key "new_master" . . .
Successfully generated, stored, and named the master key!
Using the transport key to wrap and store the master key . . .
Writing the wrapped data (and resident master key KCV) into the
 file called "file" . . .

       wrapped data:   47C0 06DB 7D3F D9ED
                       FE91 7E6F A7E5 91B9
       master key KCV: CED9 4A7B
       (computed KCV of the master key residing inside the wrapped data)
  7. Copy the wrapped master key over to the appropriate locations or facility.

  8. If necessary, generate new security databases on the HSM or at the facility: 

    # tkstool -N -d <directory>

    Alternatively, add the -I option to produce a key identical to the one generated originally in a the new database. Regenerating the transport key in this way requires that you input the session key share and KCV for each of the session keys generated earlier in this procedure. 

    # tkstool -I -d <directory> -n verify_transport

  9. Use the transport key to unwrap the master key stored in the file. Provide the security database PIN when prompted: 

    # tkstool -U -d directory -n new_master -t verify_transport -i file
Enter Password or Pin for "NSS Certificate DB":
Retrieving the transport key from the specified token (for
 unwrapping) . . .
Reading in the wrapped data (and resident master key KCV) from
 the file called "file" . . .

     wrapped data:   47C0 06DB 7D3F D9ED
                     FE91 7E6F A7E5 91B9
     master key KCV: CED9 4A7B
     (pre-computed KCV of the master key residing inside the wrapped data)

Using the transport key to temporarily unwrap the master key to
recompute its KCV value to check against its pre-computed KCV value . . .
     master key KCV: CED9 4A7B
     (computed KCV of the master key residing inside the wrapped data)
     master key KCV: CED9 4A7B
     (pre-computed KCV of the master key residing inside the wrapped data)

Using the transport key to unwrap and store the master key on the
 specified token . . .
Naming the master key "new_master" . . .
Successfully unwrapped, stored, and named the master key!

  10. Verify that the keys have been added to the database properly: 

    # tkstool -L -d
slot:  NSS User Private Key and Certificate Services
token:  NSS Certificate DB

Enter Password or Pin for "NSS Certificate DB":
			 <0> transport
			 <1> new_master

6.13. Setting up a TKS/TPS shared symmetric key

The shared symmetric key must be present in the NSS databases of both the TPS and TKS subsystems. This key is automatically generated when creating the a TPS subsystem. If both the TPS and TKS are installed within the same Tomcat instance, no additional setup is required as the TKS will automatically use the key created by TPS; however, if both subsystems are on separate instances, or even different physical hosts, you must follow the procedure described in this section to securely transport the key to the TKS.

Several possible methods are available to securely transport the shared key between the TPS and TKS:

  • The authomatic method: This method works in cases where the subsystem certificates for the TPS are kept in the software NSS database.
  • If the above method fails, a fallback manual method is available where the shared key is generated on the TPS using the caTokenUserDelegateAuthKeyEnrollment utility, which can wrap the key from the TPS, allowing for secure transport without exposing the key in transit, and unwrap it into the TKS NSS database.

The following describes the general configuration for both the TPS and TKS, regardless of the method which will be used to import the key. Note that the automatic method will generate these configurations automatically.

TKS
tks.useNewSharedSecretNames=true
tps.0.host=dhcp-16-206.sjc.example.com
tps.0.nickname=TPS-<tps host name>-8443 sharedSecret
tps.0.port=8443
tps.0.userid=,TPS-<tps host name>-8443
tps.list=0
Note

The above list can be extended when one TKS is connecting to multiple TPS instances.

TPS
conn.tks1.tksSharedSymKeyName=TPS-<tps host name>-8443 sharedSecret
Note

The host name must be the same as the one configured on the TKS side.

6.13.1. Manually generating and transporting a shared symmetric key

This section describes how to generate and transport a shared symmetric key manually. This method is useful in cases where automatic generation and transport fails, but should be avoided otherwise.

The manual method consists of two procedures. The first one is performed on the Token Key Service side, and the second one on the Token Processing System.

Procedure: Manual Shared Secret Key Method - TKS side

  1. Install the Token Key Service on the first system. See the Red Hat Certificate System Planning, Installation, and Deployment Guide for installation instructions.

  2. Stop the TKS service: 

    # pki-server stop pki-tomcat

  3. Change into the /var/lib/pki/pki-tomcat/alias directory, and use caTokenUserDelegateAuthKeyEnrollment to create the shared secret key on the TKS. Make sure to generate the shared key before you restart the new TKS instance.

    Important

    The caTokenUserDelegateAuthKeyEnrollment script will display information about the key during the key creation process. Make sure to note down this information, because it will be required later to import the key into the TPS. 

    #cd /var/lib/pki/pki-tomcat/alias
#tkstool -T -d /var/lib/pki/pki-tomcat/tks/alias -n TPS-<tps host name>-8443 sharedSecret
Generating the first session key share . . .
    first session key share:      792F AB89 8989 D902
                                  9429 6137 8632 7CC4
    first session key share KCV:  D1B6 14FD
Generating the second session key share . . .
    second session key share:      4CDF C8E0 B385 68EC
                                   380B 6D5E 1C19 3E5D
    second session key share KCV:  1EC7 8D4B
Generating the third session key share . . .
    third session key share:      CD32 3140 25B3 C789
                                  B54F 2C94 26C4 9752
    third session key share KCV:  73D6 8633
Generating first symmetric key . . .
Generating second symmetric key . . .
Generating third symmetric key . . .
Extracting transport key from operational token . . .
    transport key KCV:  A8D0 97A2
Storing transport key on final specified token . . .
Naming transport key "sharedSecret" . . .
Successfully generated, stored, and named the transport key!

  4. Configure the new key in the TKS: 

    tks.useNewSharedSecretNames=true
tps.0.host=dhcp-16-206.sjc.redhat.com
tps.0.nickname=TPS-<tps host name>-8443 sharedSecret
tps.0.port=8443
tps.0.userid=TPS-<tps host name>-8443 sharedSecret
tps.list=0

  5. Start the TKS: 

    #pki-server start pki-tomcat

Procedure: Manual shared secret key method - TPS side

  1. Install the Token Processing System on the second system. See the Red Hat Certificate System Planning, Installation, and Deployment Guide for installation instructions.

  2. Stop the TPS service: 

    # pki-server stop pki-tomcat

  3. Change into the /var/lib/pki/pki-tomcat/alias directory, and use caTokenUserDelegateAuthKeyEnrollment to import the shared key into the NSS software token: 

    # cd /var/lib/pki/pki-tomcat/alias
# tkstool -I -d . -n TPS-<tps host name>-8443 sharedSecret

    At this point, the script will prompt you for session key shares which were displayed to you when generating and wrapping the shared keys on the TKS side in the procedure above.

  4. Configure the shared secret in the TPS: 

    conn.tks1.tksSharedSymKeyName=TPS-<tps host name>-8443 sharedSecret

  5. Start the TPS service: 

    # pki-server start pki-tomcat

6.14. Using different applets for different SCP versions

In Certificate System, the following parameter in the /var/lib/ instance_name/tps/conf/CS.cfg file specifies which applet should be loaded for all Secure Channel Protocol (SCP) versions for each token operation: 

op.operation.token_type.update.applet.requiredVersion=version

However, you can also set individual applets for specific SCP versions, by adding the following parameter: 

op.operation.token_type.update.applet.requiredVersion.prot.protocol_version=version

Certificate System supports setting individual protocol versions for the following operations:

  • format
  • enroll
  • pinReset

Example 6.3. Setting protocol versions for enrollment operations

To configure a specific applet for SCP03 and a different applet for all other protocols when performing enrollment operations for the userKey token:

  1. Edit the /var/lib/ instance_name/tps/conf/CS.cfg file:

    • Set the op.enroll.userKey.update.applet.requiredVersion parameter to specify the applet used by default. For example: 

      op.enroll.userKey.update.applet.requiredVersion=1.4.58768072

    • Set the op.enroll.userKey.update.applet.requiredVersion.prot.3 parameter to configure the applet Certificate System uses for the SCP03 protocol. For example: 

      op.enroll.userKey.update.applet.requiredVersion.prot.3=1.5.558cdcff

  2. Restart Certificate System: 

    # pki-server restart instance_name

For details about enabling SCP03 for Giesecke & Devrient (G&D) Smart Cafe 6 smart cards in a TKS, see Section 6.11, “Setting up new key sets”.

Red Hat logoGithubRedditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez leBlog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

© 2024 Red Hat, Inc.