6.3. Configuring a Token Management System

As covered in Section 2.3, “Working with Smart Cards (TMS)”, there are two subsystems that are dedicated to managing smart cards and tokens: the Token Key Service and the Token Processing System. The TPS actually performs operations on smart cards; the TKS derives the keys used to TPS-smart card communication.
The order of installation is important when creating a token management system. Three subsystems are required — CA, TKS, and TPS — and they must be installed in that order. The TKS requires a CA for configuration, and the TPS requires a CA and TPS.
This walk-through simply shows, at a very high level, the major steps for setting up a functional token management system.
  1. Install a Red Hat Directory Server, as described in Section 5.3.3, “Installing Red Hat Directory Server”. This can be on a different machine from the Certificate System, which is the recommended scenario for most deployments.
  2. Create new, specific operating system groups for the Certificate System subsystems to run as. This is described in Section 5.3.7.1, “Creating Operating System Groups”.
  3. Assign users to the operating system groups to perform the subsystem administrative tasks. This is described in Section 5.3.7.2.3, “Associating Existing User Accounts with PKI Groups”.
  4. Download the Certificate System packages from the Red Hat Network channel.
  5. Install the packages.
  6. Run pkicreate to create the subsystem instances.
  7. Configure the Certificate System CA subsystem.
  8. Optionally, configure the DRM subsystem.
  9. Configure the TKS subsystem.
  10. Configure the TPS subsystem. The TPS requires having an existing TKS and DRM available when it is configured, so this is the last subsystem to set up.

6.3.1. Installing and Configuring a TKS

  1. A CA must be configured and running somewhere on the network. A TKS depends on the CA to issue their certificates and to create a security domain. If the security domain CA is not available, then the configuration process fails.
  2. Set up the required yum repositories.
    Create a .repo file with the repository information (this was likely configured in Section 6.2.1, “Installing and Configuring a CA”). For example: 
    [root@client ~]# touch /etc/yum.repos.d/rhcs.repo
[root@client ~]# vim /etc/yum.repos.d/rhcs.repo

[rhcs]
 name=rhcs
 baseurl=ftp://repo_ip_address/pub/rhcsrepo 
 enabled=1
 gpgcheck=0
  3. Run yum to install the TKS packages. Optionally, include the console packages. 
    [root@server ~]# yum install pki-tks pki-console
  4. Run the pkicreate command to create the TKS instance. For example: 
    pkicreate -pki_instance_root=/var/lib
          -pki_instance_name=pki-tks         
          -subsystem_type=tks                
          -agent_secure_port=13443           
          -ee_secure_port=13444              
          -admin_secure_port=13445           
          -unsecure_port=13180               
          -tomcat_server_port=13701
	  -audit_group=pkiaudit
	  -redirect logs=/var/log/pki-name/logs

PKI instance creation Utility ...

PKI instance creation completed ...

Starting instance_name:                                     [  OK  ]

instance_name (pid 17990) is running ...

    'instance_name' must still be CONFIGURED!
    (see /var/log/pki-name-install.log)

Before proceeding with the configuration, make sure
the firewall settings of this machine permit proper
access to this subsystem.

Please start the configuration by accessing:

http://server.example.com:13180/tks/admin/console/config/login?pin=kI7E1MByNIUcPJ6RKHmH

After configuration, the server can be operated by the command:

    service instance_name start | stop | restart
    This example uses the recommended port separation configuration, specifies an auditor group, and uses a Java Security Manager. Other options could be specified to set user-defined log and configuration directories and a user-defined operating system user and group. For other pkicreate options, see Table 6.1, “pkicreate Parameters”.
    The command options here are on separate lines to make it clear what options are used. All options should be on a single line.
  5. Create a new Firefox browser profile to use for configuring and accessing subsystems. Because of the certificates that are loaded, it is simpler and cleaner to use a fresh profile.
  6. Download the CA certificate chain for the CA which will issue the CA certificate, and import the CA chain into the browser.
    1. Open the CA web services page. 
      https://server.example.com:9444/ca/ee/ca
    2. Click the Retrieval tab.
    3. Click the Import CA Certificate Chain link.
    4. Select the radio button to import the CA certificate into the browser.
    5. Click Submit.
  7. When the pkicreate command completes, it returns a URL to use to access the web-based configuration wizard and a PIN to use to authenticate. Open the configuration wizard using the URL returned from the package installation.
  8. Select the token which will store the Certificate System certificates and keys; a list of detected hardware tokens and databases is given.
    Any hardware tokens used with the instance must be configured before configuring the subsystem instance.
  9. Join an existing security domain by entering the CA information. This URL can be identified by running service pki-ca status on the CA's host; the security domain URL is returned with the other configuration settings. For example: 
    https://server.example.com:9445
    When the CA is successfully contacted, then supply the admin username and password for the CA so that it can be properly accessed.
  10. Enter a name for the new instance.
  11. Fill in the information for the LDAP server which will be used for the instance's internal database. This requires connection information for the Directory Server instance, such as the hostname, port number, bind DN (username), and password. This step also creates a database in the Directory Server and a corresponding base directory entry (base DN) to use for the subsystem's entries.
    To configure SSL client authentication, make sure that the SSL port is set and the SSL checkbox is selected. The Directory Server must be configured to run in SSL, as described in Chapter 7, Installing Red Hat Certificate System with SSL Connections to Red Hat Directory Server.
    The hostname can be the fully-qualified domain name or an IPv4 or IPv6 address.

    NOTE

    One thing that can derail subsystem configuration or function is having services that are unable to connect with each other. If servers that need to communicate with each other are on different servers or networks, when the firewalls and iptables must be configured to give the required access.
    If the Red Hat Directory Server instances is on a different server or network than the Certificate System subsystem, then make sure that the Certificate System host's firewall allows access to whatever LDAP port was set in the previous configuration panel.
    Installation will not complete if iptables is not configured properly. To configure iptables, see the Red Hat Enterprise Linux Deployment Guide, such as "Using iptables." It is also possible to simply turn iptables off.
  12. Set the key size and the algorithm (RSA) or curve (ECC) to use for the subsystem instance keys.
    To set different key types, sizes, or algorithms (RSA) or curves (ECC) for each certificate, click the [Advanced] link to expand the form so each key pair is listed.
    The default RSA key size is 2048 and for ECC, 256.

    IMPORTANT

    ECC can be used for any keys for the subsystem, with one exception: only RSA can be used for audit signing keys.
    Any ECC-enabled PKCS#11 module must be loaded before beginning to configure the CA.
  13. Optionally, change subject names to the listed certificates.

    NOTE

    Certificate nicknames must be unique, and changing the default nicknames is one way to ensure that.
    Having unique certificate nicknames is vital for using an HSM, since any nickname conflicts (even for subsystems on different servers) will cause configuration to fail.
  14. The next panels generate and show certificate requests, certificates, and key pairs.
  15. If the subsystem will ever be cloned, or as a protection if keys or certificates are ever lost, back up the keys and certificates when prompted. It is also possible to extract these keys later.
  16. Provide the information for the new subsystem administrator.
  17. Click Next through the remaining panels to import the agent certificate into the browser and complete the configuration.
  18. Before restarting the new TKS instance, create a shared secret key.
    The tkstool script prints information about the shared secret key as it creates the key. These session key shares are required to import the shared key onto the TPS, so record this information.

    NOTE

    Creating shared keys for the TKS and TPS is covered in the Administrator's Guide. 
    tkstool -T -d /var/lib/pki-tks/alias -n 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!

    NOTE

    If you are using a hardware token, the tkstool script could return an error requiring you to set environment variables before running the tool. Set the environment variables as directed, and then re-run the tool.
    List the keys to make sure the shared key was properly imported. 
    tkstool -d /var/lib/pki-tks/alias -L

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

Enter Password or Pin for "NSS Certificate DB": xxxxx
        <0> sharedSecret
    The shared key is sharedSecret, which is the default name.
  19. When the configuration is complete, restart the subsystem. 
    service pki-tks restart

    IMPORTANT

    The new instance is not active until it is restarted, and weird behaviors can occur if you try to use the instance without restarting it first.