2.5. Smart Card Token Management with Certificate System

A smart card is a hardware cryptographic device containing cryptographic certificates and keys. It can be employed by the user to participate in operations such as secure website access and secure mail. It can also serve as an authentication device to log in to various operating systems such as Red Hat Enterprise Linux. The management of these cards or tokens throughout their entire lifetime in service is accomplished by the Token Management System (TMS).

A TMS environment requires a Certificate Authority (CA), Token Key Service (TKS), and Token Processing System (TPS), with an optional Key Recovery Authority (KRA) for server-side key generation and key archival and recovery. Online Certificate Status Protocol (OCSP) can also be used to work with the CA to serve online certificate status requests. This chapter provides an overview of the TKS and TPS systems, which provide the smart card management functions of Red Hat Certificate System, as well as Enterprise Security Client (ESC), that works with TMS from the user end.

Figure 2.4. How the TMS Manages Smart Cards

2.5.1. Token Key Service (TKS)

The Token Key Service (TKS) is responsible for managing one or more master keys. It maintains the master keys and is the only entity within the TMS that has access to the key materials. In an operational environment, each valid smart card token contains a set of symmetric keys that are derived from both the master key and the ID that is unique to the card (CUID).

Initially, a default (unique only per manufacturer master key) set of symmetric keys is initialized on each smart card by the manufacturer. This default set should be changed at the deployment site by going through a Key Changeover operation to generate the new master key on TKS. As the sole owner to the master key, when given the CUID of a smart card, TKS is capable of deriving the set of symmetric keys residing on that particular smart card, which would then allow TKS to establish a session-based Secure Channel for secure communication between TMS and each individual smart card.

Note

Because of the sensitivity of the data that the TKS manages, the TKS should be set behind the firewall with restricted access.

2.5.1.1. Master Keys and Key Sets

The TKS supports multiple smart card key sets. Each smart card vendor creates different default (developer) static key sets for their smart card token stocks, and the TKS is equipped with the static key set (per manufacturer) to kickstart the format process of a blank token.

During the format process of a blank smart card token, a Java applet and the uniquely derived symmetric key set are injected into the token. Each master key (in some cases referred to as keySet) that the TKS supports is to have a set of entries in the TKS configuration file (CS.cfg). Each TPS profile contains a configuration to direct its enrollment to the proper TKS keySet for the matching key derivation process that would essentially be responsible for establishing the Secure Channel secured by a set of session-specific keys between TMS and the smart card token.

On TKS, master keys are defined by named keySets for references by TPS. On TPS, depending on the enrollment type (internal or external registration), The keySet is either specified in the TPS profile, or determined by the keySet Mapping Resolver.

2.5.1.2. Key Ceremony (Shared Key Transport)

A Key Ceremony is a process for transporting highly sensitive keys in a secure way from one location to another. In one scenario, in a highly secure deployment environment, the master key can be generated in a secure vault with no network to the outside. Alternatively, an organization might want to have TKS and TPS instances on different physical machines. In either case, under the assumption that no one single person is to be trusted with the key, Red Hat Certificate System TMS provides a utility called tkstool to manage the secure key transportation.

2.5.1.3. Key Update (Key Changeover)

When Global Platform-compliant smart cards are created at the factory, the manufacturer will burn a set of default symmetric keys onto the token. The TKS is initially configured to use these symmetric keys (one KeySet entry per vendor in the TKS configuration). However, since these symmetric keys are not unique to the smart cards from the same stock, and because these are well-known keys, it is strongly encouraged to replace these symmetric keys with a set that is unique per token, not shared by the manufacturer, to restrict the set of entities that can manipulate the token.

The changing over of the keys takes place with the assistance of the Token Key Service subsystem. One of the functions of the TKS is to oversee the Master Keys from which the previously discussed smart card token keys are derived. There can be more than one master key residing under the control of the TKS.

Important

When this key changeover process is done on a token, the token may become unusable in the future since it no longer has the default key set enabled. The key is essentially only as good as long as the TPS and TKS system that provisioned the token is valid. Because of this, it is essential to keep all the master keys, even if any of them are outdated.

You can disable the old master keys in TKS for better control, but do not delete them unless disabled tokens are part of your plan. There is support to revert the token keys back to the original key set, which is viable if the token is to be reused again in some sort of a testing scenario.

2.5.1.4. APDUs and Secure Channels

The Red Hat Certificate System Token Management System (TMS) supports the GlobalPlatform smart card specification, in which the Secure Channel implementation is done with the Token Key System (TKS) managing the master key and the Token Processing System (TPS) communicating with the smart card (tokens) with Application Protocol Data Units (APDUs).

There are two types of APDUs:

Command APDUs, sent by the TPS to smart cards
Response APDUs, sent by smart cards to the TPS as response to command APDUs

The initiation of the APDU commands may be triggered when clients take action and connect to the Certificate System server for requests. A secure channel begins with an InitializeUpdate APDU sent from TPS to the smart card token, and is fully established with the ExternalAuthenticate APDU. Then, both the token and TMS would have established a set of shared secrets, called session keys, which are used to encrypt and authenticate the communication. This authenticated and encrypted communication channel is called Secure Channel.

Because TKS is the only entity that has access to the master key which is capable of deriving the set of unique symmetric on-token smart card keys, the Secure Channel provides the adequately safeguarded communication between TMS and each individual token. Any disconnection of the channel will require reestablishment of new session keys for a new channel.

2.5.2. Token Processing System (TPS)

The Token Processing System (TPS) is a registration authority for smart card certificate enrollment. It acts as a conduit between the user-centered Enterprise Security Client (ESC), which interacts with client side smart card tokens, and the Certificate System back end subsystems, such as the Certificate Authority (CA) and the Key Recovery Authority (KRA).

In TMS, the TPS is required in order to manage smart cards, as it is the only TMS entity that understands the APDU commands and responses. TPS sends commands to the smart cards to help them generate and store keys and certificates for a specific entity, such as a user or device. Smart card operations go through the TPS and are forwarded to the appropriate subsystem for action, such as the CA to generate certificates or the KRA to generate, archive, or recover keys.

2.5.2.1. Coolkey Applet

Red Hat Certificate System includes the Coolkey Java applet, written specifically to run on TMS-supported smart card tokens. The Coolkey applet connects to a PKCS#11 module that handles the certificate and key related operations. During a token format operation, this applet is injected onto the smart card token using the Secure Channel protocol, and can be updated per configuration.

2.5.2.2. Token Operations

The TPS in Red Hat Certificate System is available to provision smart cards on the behalf of end users of the smart cards. The Token Processing System provides support for the following major token operations:

Token Format - The format operation is responsible for installing the proper Coolkey applet onto the token. The applet provides a platform where subsequent cryptographic keys and certificates can be later placed.
Token Enrollment - The enrollment operation results in a smart card populated with required cryptographic keys and cryptographic certificates. This material allows the user of the smart card to participate in operations such as secure web site access and secure mail. Two types of enrollments are supported, which is configured globally:
- Internal Registration - Enrollment by TPS profiles determined by the profile Mapping Resolver.
- External Registration - Enrollment by TPS profiles determined by the entries in the user’s LDAP record.
Token PIN Reset - The token PIN reset operation allows the user of the token to specify a new PIN that is used to log into the token, making it available for performing cryptographic operations.

The following other operations can be considered supplementary or inherent operations to the main ones listed above. They can be triggered per relevant configuration or by the state of the token.

Key Generation - Each PKI certificate is comprised of a public/private key pair. In Red Hat Certificate System, the generation of the keys can be done in two ways, depending on the TPS profile configuration:
- Token Side Key Generation - The PKI key pairs are generated on the smart card token. Generating the key pairs on the token side does not allow for key archival.
- Server Side Key Generation - The PKI key pairs are generated on the TMS server side. The key pairs are then sent back to the token using Secure Channel. Generating the key pairs on the server side allows for key archival.
Certificate Renewal - This operation allows a previously enrolled token to have the certificates currently on the token reissued while reusing the same keys. This is useful in situations where the old certificates are due to expire and you want to create new ones but maintain the original key material.
Certificate Revocation - Certificate revocation can be triggered based on TPS profile configuration or based on token state.
Normally, only the CA which issued a certificate can revoke it, which could mean that retiring a CA would make it impossible to revoke certain certificates. However, it is possible to route revocation requests for tokens to the retired CA while still routing all other requests such as enrollment to a new, active CA. This mechanism is called Revocation Routing.
Token Key Changeover - The key changeover operation, triggered by a format operation, results in the ability to change the internal keys of the token from the default developer key set to a new key set controlled by the deployer of the Token Processing System. This is usually done in any real deployment scenario since the developer key set is better suited to testing situations.
Applet Update - During the course of a TMS deployment, the Coolkey smart card applet can be updated or downgraded if required.

2.5.2.3. TPS Profiles

The Certificate System Token Processing System subsystem facilitates the management of smart card tokens. Tokens are provisioned by the TPS such that they are taken from a blank state to either a Formatted or Enrolled condition. A Formatted token is one that contains the CoolKey applet supported by TPS, while an Enrolled token is personalized (a process called binding) to an individual with the requisite certificates and cryptographic keys. This fully provisioned token is ready to use for crytptographic operations.

The TPS can also manage Profiles. The notion of a token Profile is related to:

The steps taken to Format or Enroll a token.
The attributes contained within the finished token after the operation has been successfully completed.

The following list contains some of the quantities that make up a unique token profile:

How does the TPS connect to the user's authentication LDAP database?
Will user authentication be required for this token operation? If so, what authentication manager will be used?
How does the TPS connect to a Certificate System CA from which it will obtain certificates?
How are the private and public keys generated on this token? Are they generated on the token side or on the server side?
What key size (in bits) is to be used when generating private and public keys?
Which certificate enrollment profile (provisioned by the CA) is to be used to generate the certificates on this token?
Note
This setting will determine the final structure of the certificates to be written to the token. Different certificates can be created for different uses, based on extensions included in the certificate. For example, one certificate can specialize in data encryption, and another one can be used for signature operations.
What version of the Coolkey applet will be required on the token?
How many certificates will be placed on this token for an enrollment operation?

These above and many others can be configured for each token type or profile. A full list of available configuration options is available in the Red Hat Certificate System Administration Guide.

Another question to consider is how a given token being provisioned by a user will be mapped to an individual token profile. There are two types of registration:

Internal Registration - In this case, the TPS profile (tokenType) is determined by the profile Mapping Resolver. This filter-based resolver can be configured to take any of the data provided by the token into account and determine the target profile.
External Registration - When using external registration, the profile (in name only - actual profiles are still defined in the TPS in the same fashion as those used by the internal registration) is specified in each user's LDAP record, which is obtained during authentication. This allows the TPS to obtain key enrollment and recovery information from an external registration Directory Server where user information is stored. This gives you the control to override the enrollment, revocation, and recovery policies that are inherent to the TPS internal registration mechanism. The user LDAP record attribute names relevant to external registration are configurable.
External registration can be useful when the concept of a "group certificate" is required. In that case, all users within a group can have a special record configured in their LDAP profiles for downloading a shared certificate and keys.

The registration to be used is configured globally per TPS instance.

2.5.2.4. Token Database

The Token Processing System makes use of the LDAP token database store, which is used to keep a list of active tokens and their respective certificates, and to keep track of the current state of each token. A brand new token is considered Uninitialized, while a fully enrolled token is Enrolled. This data store is constantly updated and consulted by the TPS when processing tokens.

2.5.2.4.1. Token States and Transitions

The Token Processing System stores states in its internal database in order to determine the current token status as well as actions which can be performed on the token.

2.5.2.4.1.1. Token States

The following table lists all possible token states:

Table 2.9. Possible Token States

Name	Code	Label
FORMATTED	0	Formatted (uninitialized)
DAMAGED	1	Physically damaged
PERM_LOST	2	Permanently lost
SUSPENDED	3	Suspended (temporarily lost)
ACTIVE	4	Active
TERMINATED	6	Terminated
UNFORMATTED	7	Unformatted

The command line interface displays token states using the Name listed above. The graphical interface uses the Label instead.

Note

The above table contains no state with code 5, which previously belonged to a state that was removed.

2.5.2.4.1.2. Token State Transitions Done Using the Graphical or Command Line Interface

Each token state has a limited amount of next states it can transition into. For example, a token can change state from FORMATTED to ACTIVE or DAMAGED, but it can never transition from FORMATTED to UNFORMATTED.

Furthermore, the list of states a token can transition into is different depending on whether the transition is triggered manually using a command line or the graphical interface, or automatically using a token operation. The list of allowed manual transitions is stored in the tokendb.allowedTransitions property, and the tps.operations.allowedTransitions property controls allowed transitions triggered by token operations.

The default configurations for both manual and token operation-based transitions are stored in the /usr/share/pki/tps/conf/CS.cfg configuration file.

2.5.2.4.1.2.1. Token State Transitions Using the Command Line or Graphical Interface

All possible transitions allowed in the command line or graphical interface are described in the TPS configuration file using the tokendb.allowedTransitions property:

tokendb.allowedTransitions=0:1,0:2,0:3,0:6,3:2,3:6,4:1,4:2,4:3,4:6,6:7

The property contains a comma-separated list of transitions. Each transition is written in the format of <current code>:<new code>. The codes are described in Table 2.9, “Possible Token States”. The default configuration is preserved in /usr/share/pki/tps/conf/CS.cfg.

The following table describes each possible transition in more detail:

Table 2.10. Possible Manual Token State Transitions

Transition	Current State	Next State	Description
0:1	FORMATTED	DAMAGED	This token has been physically damaged.
0:2	FORMATTED	PERM_LOST	This token has been permanently lost.
0:3	FORMATTED	SUSPENDED	This token has been suspended (temporarily lost).
0:6	FORMATTED	TERMINATED	This token has been terminated.
3:2	SUSPENDED	PERM_LOST	This suspended token has been permanently lost.
3:6	SUSPENDED	TERMINATED	This suspended token has been terminated.
4:1	ACTIVE	DAMAGED	This token has been physically damaged.
4:2	ACTIVE	PERM_LOST	This token has been permanently lost.
4:3	ACTIVE	SUSPENDED	This token has been suspended (temporarily lost).
4:6	ACTIVE	TERMINATED	This token has been terminated.
6:7	TERMINATED	UNFORMATTED	Reuse this token.

The following transitions are generated automatically depending on the token's original state. If a token was originally FORMATTED and then became SUSPENDED, it can only return to the FORMATTED state. If a token was originally ACTIVE and then became SUSPENDED, it can only return to the ACTIVE state.

Table 2.11. Token State Transitions Triggered Automatically

Transition	Current State	Next State	Description
3:0	SUSPENDED	FORMATTED	This suspended (temporarily lost) token has been found.
3:4	SUSPENDED	ACTIVE	This suspended (temporarily lost) token has been found.

2.5.2.4.1.3. Token State Transitions using Token Operations

All possible transitions that can be done using token operations are described in the TPS configuration file using the tokendb.allowedTransitions property:

tps.operations.allowedTransitions=0:0,0:4,4:4,4:0,7:0

The following table describes each possible transition in more detail:

Table 2.12. Possible Token State Transitions using Token Operations

Transition	Current State	Next State	Description
0:0	FORMATTED	FORMATTED	This allows reformatting a token or upgrading applet/key in a token.
0:4	FORMATTED	ACTIVE	This allows enrolling a token.
4:4	ACTIVE	ACTIVE	This allows re-enrolling an active token. May be useful for external registration.
4:0	ACTIVE	FORMATTED	This allows formatting an active token.
7:0	UNFORMATTED	FORMATTED	This allows formatting a blank or previously used token.

2.5.2.4.1.4. Token State and Transition Labels

The default labels for token states and transitions are stored in the /usr/share/pki/tps/conf/token-states.properties configuration file. By default, the file has the following contents:

# Token states
UNFORMATTED         = Unformatted
FORMATTED           = Formatted (uninitialized)
ACTIVE              = Active
SUSPENDED           = Suspended (temporarily lost)
PERM_LOST           = Permanently lost
DAMAGED             = Physically damaged
TEMP_LOST_PERM_LOST = Temporarily lost then permanently lost
TERMINATED          = Terminated

# Token state transitions
FORMATTED.DAMAGED        = This token has been physically damaged.
FORMATTED.PERM_LOST      = This token has been permanently lost.
FORMATTED.SUSPENDED      = This token has been suspended (temporarily lost).
FORMATTED.TERMINATED     = This token has been terminated.
SUSPENDED.ACTIVE         = This suspended (temporarily lost) token has been found.
SUSPENDED.PERM_LOST      = This suspended (temporarily lost) token has become permanently lost.
SUSPENDED.TERMINATED     = This suspended (temporarily lost) token has been terminated.
SUSPENDED.FORMATTED      = This suspended (temporarily lost) token has been found.
ACTIVE.DAMAGED           = This token has been physically damaged.
ACTIVE.PERM_LOST         = This token has been permanently lost.
ACTIVE.SUSPENDED         = This token has been suspended (temporarily lost).
ACTIVE.TERMINATED        = This token has been terminated.
TERMINATED.UNFORMATTED   = Reuse this token.

2.5.2.4.1.5. Customizing Allowed Token State Transitions

To customize the list of token state transition, edit the following properties in /var/lib/pki/instance_name/tps/conf/CS.cfg:

tokendb.allowedTransitions to customize the list of allowed transitions performed using the command line or graphical interface
tps.operations.allowedTransitions to customize the list of allowed transitions using token operations

Transitions can be removed from the default list if necessary, but new transitions cannot be added unless they were in the default list. The defaults are stored in /usr/share/pki/tps/conf/CS.cfg.

2.5.2.4.1.6. Customizing Token State and Transition Labels

To customize token state and transition labels, copy the default /usr/share/pki/tps/conf/token-states.properties into your instance folder (/var/lib/pki/instance_name/tps/conf/CS.cfg), and change the labels listed inside as needed.

Changes will be effective immediately, the server does not need to be restarted. The TPS user interface may require a reload.

To revert to default state and label names, delete the edited token-states.properties file from your instance folder.

2.5.2.4.1.7. Token Activity Log

Certain TPS activities are logged. Possible events in the log file are listed in the table below.

Table 2.13. TPS Activity Log Events

Activity	Description
add	A token was added.
format	A token was formatted.
enrollment	A token was enrolled.
recovery	A token was recovered.
renewal	A token was renewed.
pin_reset	A token PIN was reset.
token_status_change	A token status was changed using the command line or graphical interface.
token_modify	A token was modified.
delete	A token was deleted.
cert_revocation	A token certificate was revoked.
cert_unrevocation	A token certificate was unrevoked.

2.5.2.4.2. Token Policies

In case of internal registration, each token can be governed by a set of token policies. The default policies are:

RE_ENROLL=YES;RENEW=NO;FORCE_FORMAT=NO;PIN_RESET=NO;RESET_PIN_RESET_TO_NO=NO;RENEW_KEEP_OLD_ENC_CERTS=YES

All TPS operations under internal registration are subject to the policies specified in the token's record. If no policies are specified for a token, the TPS uses the default set of policies.

2.5.2.5. Mapping Resolver

The Mapping Resolver is an extensible mechanism used by the TPS to determine which token profile to assign to a specific token based on configurable criteria. Each mapping resolver instance can be uniquely defined in the configuration, and each operation can point to various defined mapping resolver instance.

Note

The mapping resolver framework provides a platform for writing custom plug-ins. However instructions on how to write a plug-in is outside the scope of this document.

FilterMappingResolver is the only mapping resolver implementation provided with the TPS by default. It allows you to define a set of mappings and a target result for each mapping. Each mapping contains a set of filters, where:

If the input filter parameters pass all filters within a mapping, the target value is assigned.
If the input parameters fail a filter, that mapping is skipped and the next one in order is tried.
If a filter has no specified value, it always passes.
If a filter does have a specified value, then the input parameters must match exactly.
The order in which mappings are defined is important. The first mapping which passes is considered resolved and is returned to the caller.

The input filter parameters are information received from the smart card token with or without extensions. They are run against the FilterMappingResolver according to the above rules. The following input filter parameters are supported by FilterMappingResolver:

appletMajorVersion - The major version of the Coolkey applet on the token.
appletMinorVersion - The minor version of the Coolkey applet on the token.
keySet or tokenType
- keySet - can be set as an extension in the client request. Must match the value in the filter if the extension is specified. The keySet mapping resolver is meant for determining keySet value when using external registration. The Key Set Mapping Resolver is necessary in the external registration environment when multiple key sets are supported (for example, different smart card token vendors). The keySet value is needed for identifying the master key on TKS, which is crucial for establishing Secure Channel. When a user's LDAP record is populated with a set tokenType (TPS profile), it does not know which card will end up doing the enrollment, and therefore keySet cannot be predetermined. The keySetMappingResolver helps solve the issue by allowing the keySet to be resolved before authentication.
- tokenType - okenType can be set as an extension in the client request. It must match the value in the filter if the extension is specified. tokenType (also referred to as TPS Profile) is determined at this time for the internal registration environment.
tokenATR - The token's Answer to Reset (ATR).
tokenCUID - "start" and "end" define the range the Card Unique IDs (CUID) of the token must fall in to pass this filter.

2.5.2.6. TPS Roles

The TPS supports the following roles by default:

TPS Administrator - this role is allowed to:
- Manage TPS tokens
- View TPS certificates and activities
- Manage TPS users and groups
- Change general TPS configuration
- Manage TPS authenticators and connectors
- Configure TPS profiles and profile mappings
- Configure TPS audit logging
TPS Agent - this role is allowed to:
- Configure TPS tokens
- View TPS certificates and activities
- Change the status of TPS profiles
TPS Operator - this role is allowed to:
- View TPS tokens, certificates, and activities

2.5.3. TKS/TPS Shared Secret

During TMS installation, a shared symmetric key is established between the Token Key Service and the Token Processing System. The purpose of this key is to wrap and unwrap session keys which are essential to Secure Channels.

Note

The shared secret key is currently only kept in a software cryptographical database. There are plans to support keeping the key on a Hardware Security Module (HSM) devices in a future release of Red Hat Certificate System. Once this functionality is implemented, you will be instructed to run a Key Ceremony using tkstool to transfer the key to the HSM.

2.5.4. Enterprise Security Client (ESC)

The Enterprise Security Client is an HTTP client application, similar to a web browser, that communicates with the TPS and handles smart card tokens from the client side. While an HTTPS connection is established between the ESC and the TPS, an underlying Secure Channel is also established between the token and the TMS within each TLS session.