2.5. Smart Card Token Management with Certificate System

Figure 2.4. How the TMS Manages Smart Cards
2.5.1. Token Key Service (TKS)
Note
2.5.1.1. Master Keys and Key Sets
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.
2.5.1.3. Key Update (Key Changeover)
Important
2.5.1.4. APDUs and Secure Channels
- Command APDUs, sent by the TPS to smart cards
- Response APDUs, sent by smart cards to the TPS as response to command APDUs
2.5.2. Token Processing System (TPS)
2.5.2.1. Coolkey Applet
2.5.2.2. 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.
- 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 steps taken to Format or Enroll a token.
- The attributes contained within the finished token after the operation has been successfully completed.
- 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?
- 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.
2.5.2.4. Token Database
2.5.2.4.1. Token States and Transitions
2.5.2.4.1.1. 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 |
Note
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
FORMATTED
to ACTIVE
or DAMAGED
, but it can never transition from FORMATTED
to UNFORMATTED
.
tokendb.allowedTransitions
property, and the tps.operations.allowedTransitions
property controls allowed transitions triggered by token operations.
/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
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
<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
.
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. |
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
tokendb.allowedTransitions
property:
tps.operations.allowedTransitions=0:0,0:4,4:4,4:0,7:0
<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
.
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
/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
/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 interfacetps.operations.allowedTransitions
to customize the list of allowed transitions using token operations
/usr/share/pki/tps/conf/CS.cfg
.
2.5.2.4.1.6. Customizing Token State and Transition Labels
/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.
token-states.properties
file from your instance folder.
2.5.2.4.1.7. Token Activity Log
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
RE_ENROLL=YES;RENEW=NO;FORCE_FORMAT=NO;PIN_RESET=NO;RESET_PIN_RESET_TO_NO=NO;RENEW_KEEP_OLD_ENC_CERTS=YES
2.5.2.5. Mapping Resolver
Note
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.
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
ortokenType
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. ThekeySetMappingResolver
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
- 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