6.3.2. Installing and Configuring a TPS

A CA must be configured and running somewhere on the network.
A TKS must be configured and running somewhere on the network.
If a DRM will be used to store keys, then it must be configured and running somewhere on the network.
On the TPS host machine, 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
```
Run yum to install the TPS packages.
```
[root@server ~]# yum install pki-tps
```

Run the pkicreate command to create the TPS instance. For example:

pkicreate -pki_instance_root=/var/lib
          -pki_instance_name=pki-tps         
          -subsystem_type=tps                
          -secure_port=7889                  
          -non_clientauth_secure_port=7890   
          -unsecure_port=7888 
	  -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:7888/tps/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.

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. This PIN is also contained in the install logs (/var/log/pki-name-install.log) and in the CS.cfg file for the instance.

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.
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.
If the CA, TKS, or DRM which will be used to work with the TPS is configured to prefer client authentication (sslClientAuth = want is set in the server.xml file), then this setting must be disabled before the TPS can be configured. Otherwise, the CA, TKS, or DRM will request client authentication when the TPS attempts to connect with it during configuration, which the TPS cannot perform.
The procedure for changing the client authentication settings is in the Administrator's Guide.

Open the configuration wizard using the URL returned by running pkicreate.

http://server.example.com:7888/tps/admin/console/config/login?pin=kI7E1MByNIUcPJ6RKHmH

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.
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.
Enter a name for the new instance.
Select the CA which will issue, renew, and revoke certificates for token operations requested through the TPS subsystem.
Supply information about the TKS which will manage the TPS keys. Select the TKS from the drop-down menu of TKS subsystems within the security domain.
There is an option for server-side key generation for tokens enrolled through the TPS. If server-side key generation is selected, supply information about the DRM which will generate keys and archive encryption keys. Key and certificate recovery is initiated automatically through the TPS, which is a DRM agent. Select the DRM from the drop-down menu of DRM subsystems within the security domain.
The hostname for the DRM can be the fully-qualified domain name or an IPv4 or IPv6 address.
Fill in the Directory Server authentication directory. This directory is used by the TPS to authenticate users which access the Enterprise Security Client and as an additional database for certificates and keys.
This Directory Server instance must not be the same Directory Server instance used as the TPS's internal database. This is a general user directory, which may be accessed by other applications or users, whereas the TPS's internal database is used exclusively by the TPS and is created on the fly as the TPS is configured.
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 of the LDAP server can be the fully-qualified domain name or an IPv4 or IPv6 address.
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.
Set the key size and type (RSA or ECC) to use for the subsystem instance keys.
By default, the settings for the signing key are applied to the keys for every certificate for the CA. To set different key types, sizes, or hashing algorithms for each certificate, click the [Advanced] link to expand the form so each key pair is listed.
The default RSA key size is 2048. The available algorithms are listed in Section A.1, “RSA Hashing Algorithms”. The default size for ECC is 256, and the only supported curve is nistp256.
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.
The next panels generate and show certificate requests, certificates, and key pairs.
Provide the information for the new subsystem administrator.
Click Next through the remaining panels to import the agent certificate into the browser and complete the configuration.
When the configuration is complete, restart the subsystem.
```
service pki-tps 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.
Stop the TPS.
```
service pki-tps stop
```
Use the tkstool script to import the shared key into the NSS software token.
```
tkstool -I -d /var/lib/pki-tps/alias -n sharedSecret
```
The script will prompts for the session key shares that were printed when the key was created in the TKS. Enter the information from the TKS.
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-tps/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. The TPS can be configured to set a different name for the shared key by changing the value of the conn.tks1.tksSharedSymKeyName value in the CS.cfg. This value must be the same as the nickname for the key imported into the token, or the TPS cannot locate the key.
Start the TPS instance.
```
service pki-tps start
```
Edit the TPS configuration file to use the appropriate profile name for the delegateISEtoken profile.
When a new TPS is installed using 8.1 packages, the delegateISEtoken profile is created with the wrong CA profile ID. The ID is incorrectly is set to caTokenUserAuthenticationKeyEnrollment.
Open the TPS configuration file:
```
[root@server ~]# vim /var/lib/pki-tps/conf/CS.cfg
```
Change the profile ID name to caTokenUserDelegateAuthKeyEnrollment:
```
op.enroll.delegateISEtoken.keyGen.encryption.ca.profileId=caTokenUserDelegateAuthKeyEnrollment
```