Chapter 4. Additional Installation Options
Chapter 4. Additional Installation Options
The Certificate System default installation, and all subsequent instances created with pkicreate, make certain assumptions about the instances being installed, such as the default signing algorithm to use for
CA signing certificates and whether to allow IPv6 addresses for hosts.
This chapter describes additional configuration options that impact the installation and configuration for new instances, so many of these procedures occur before the instance is created.
4.1. Requesting Subsystem Certificates from an External CA
Most of the time, it is easier and simpler to have a CA within your PKI be the root CA, since this affords a lot of flexibility for defining the rules and settings of the PKI deployment. However, for public-facing networks, this can be a difficult thing to implement, because web administrators have to find some way to propagate and update CA certificate chains to their clients so that any site is trusted. For this reason, people often use public CAs, hosted by companies like VeriSign or Thawte, to issue CA signing certificates and make all of their CAs subordinate to the public CA. This is one of the planning considerations covered in the Certificate System Deployment Guide.
All subsystem certificates can be submitted to an external CA when the subsystem is configured. When the certificates are generated from a CA outside the Certificate System deployment (or from a Certificate
System CA in a different security domain), then the configuration process does not occur in one sitting.
The configuration process is on hold until the certificates can be retrieved. Aside from that delay, the process is more or less the same as in
Chapter 3, Installation and Configuration
.
1. Install the subsystem packages, and open the configuration URL.
2. Join a security domain. For a CA, it is also possible to create a new security domain.
3. Set the subsystem information, like its name.
4. For a CA, set the CA to be a subordinate CA. This is required in order to submit CA subsystem certificates to an external CA; making a root CA automatically generates self-signed certificates.
5. Set up the internal database.
6. Select the key store, and generate the key pairs.
7. Set the subsystem certificate names; you can set these to whatever you want, but make sure that they conform to any requirements that the external CA sets for the subject names of certificates.
At the bottom of the screen is the list of CAs which are available to accept the submitted certificate requests. Choose External CA from the drop-down menu.
8. In the Requests and Certificates panel, the CA signing certificate is listed, with an action
required label. Once that certificate is generated, the other certificates for the CA will be automatically generated.
For other subsystems, each subsystem certificate has an action required label and must be submitted to the external CA.
55
Red Hat Certificate System 8.0 Install Guide
9. Click the Step 1: Copy the certificate request link, and copy the certificate request to a file or the clipboard.
10. Submit the request to the external CA. Leave the browser with the configuration wizard open as you wait for the certificates to be generated, so that it is easier to pick up the process.
11. Click Step 2, and import the certificate chain for the issuing CA. This certificate chain must not contain the leaf certificate (the certificate being requested).
12. After retrieving the issued certificates, click the Step 3: Paste in the base 64-encoded
certificate link, and paste in the new certificate (this should be only the new certificate, not a certificate chain).
13. For the CA, this only has to be done for the signing certificate. For the other subsystems, repeat
56
Chapter 4. Additional Installation Options
steps 9 , 10 , and 12
for each certificate.
When all the certificates have been submitted, click Next to resume the configuration process.
14. Export the keys for the certificates, if the subsystem will be cloned.
15. Create the administrator user.
16. When the configuration is done, restart the subsystem.
service subsystem_name restart
4.2. Installing a CA with ECC Enabled
Elliptic curve cryptography (ECC) is much more secure than the more common RSA-style encryption, which allows it to use much shorter key lengths and makes it faster to generate certificates. CAs which are ECC-enabled can issue both RSA and ECC certificates, using their ECC signing certificate.
Certificate System does not include a module natively to enable ECC, but it is possible to load and use a third-party PKCS #11 module with ECC-enabled.
To use the ECC module, it must be loaded before the subsystem instance is configured.
IMPORTANT
Third-party ECC modules must have an SELinux policy configured for them, or SELinux needs to be changed from enforcing mode to permissive mode to allow the module to function.
Otherwise, any subsystem operations which require the ECC module will fail.
4.2.1. Loading a Third-Party ECC Module
1. Copy the third-party module to a common directory, like /usr/lib for 32-bit systems or
/usr/lib64 for 64-bit systems.
2. Create a new CA instance by running pkicreate, but do not go through the configuration wizard.
3. Stop the CA.
service pki-ca stop
4. The CA runs as the pkiuser user. As root, create a home directory for pkiuser.
/usr/sbin/usermod --home /usr/share/pki/pkiuser pkiuser cd /usr/share/pki mkdir pkiuser
HOME=/usr/share/pki/pkiuser export HOME
5. Install the third-party module in the CA's security databases so it is available for the configuration.
cd /var/lib/pki-ca/alias modutil -dbdir . -nocertdb -add THIRD_PARTY_MODULE -libfile
/usr/lib/libYourNewModule.so
This creates a directory called .THIRD_PARTY_MODULE in the new home directory created for
57
Red Hat Certificate System 8.0 Install Guide
root (the new pkiuser home directory). For example, if the module's name is EccForPki, then the directory is named .EccForPki/
6. Using modutil, set the password for the new ECC module token.
modutil -dbdir . -nocertdb -changepw "THIRD_PARTY_MODULE_TOKEN"
7. Change the ownership of the new home directory from root to pkiuser.
cd /usr/share/pki chown -R pkiuser:pkiuser pkiuser
8. Add the password for the ECC token to the CA's password file.
vim /etc/pki-ca/password.conf
hardware-THIRD_PARTY_MODULE_TOKEN=secret
The hardware- prefix is required.
9. Edit the CA configuration and add a line to require signature verification.
ca.requestVerify.token=THIRD_PARTY_MODULE_TOKEN
10. Start the CA.
service pki-ca start
11. Continue with the CA configuration, with two important configuration settings:
In the Key Store panel, the ECC module should be listed as an available token. Select that module for the key store.
In the Key Pairs panel, ECC should be listed as an option to use to generate the keys used for the CA's certificates. Select the ECC key type.
12. After completing the configuration for the CA, try to log into the CA console.
pkiconsole https://server.example.com:9445/ca
This fails, because the console is not yet configured to run with ECC enabled. However, this does create the security databases for the console, so the ECC module can be loaded.
13. Load the ECC module into the console security databases.
cd ~/.redhat-idm-console/ modutil -dbdir . -nocertdb -add THIRD_PARTY_MODULE -libfile
/usr/lib/libYourNewModule.so
Now, logging into the console succeeds.
4.2.2. Loading the Certicom ECC Module
Certicom's ECC module has a slightly different configuration process than the procedure for loading a general ECC module.
1. Copy the third-party libraries to a common directory, like /usr/lib for 32-bit systems or
/usr/lib64 for 64-bit systems.
58
Chapter 4. Additional Installation Options
There are two library files for the Certicom ECC modules, libsbcpgse.so and libsbgse2.so.
2. Cache the recent shared libraries.
ldconfig
3. Install the CA, but do not go through the configuration wizard.
4. Stop the CA.
service pki-ca stop
5. The CA runs as the pkiuser user. As root, create a home directory for pkiuser.
/usr/sbin/usermod --home /usr/share/pki/pkiuser pkiuser cd /usr/share/pki mkdir pkiuser
HOME=/usr/share/pki/pkiuser export HOME
6. Open the subsystem's alias directory. For example: cd /var/lib/pki-ca/alias
7. Install the third-party module in the CA's security databases so it is available for the configuration.
modutil -dbdir . -nocertdb -add certicom -libfile /usr/lib/libsbcpgse.so
This creates a .certicom directory in the new pkiuser home directory.
8. Certicom's ECC module includes an initpin file; copy this into the new pkiuser directory and give it execute permissions. For example: cp /tmp/initpin /usr/share/pki/pkiuser chmod +x initpin
9. Run Certicom's initpin file from the /usr/share/pki/pkiuser directory. This first prompts for the directory to use for the Certicom token databases; use the pkiuser home directory,
/usr/share/pki/pkiuser. This also prompts to set a password for the module, and then proceed with configuring the module.
59
Red Hat Certificate System 8.0 Install Guide
/usr/share/pki/pkiuser/initpin
Please enter the directory where the token databases exist or will
be created: /usr/share/pki/pkiuser
Enter PIN:
Confirm PIN:
Security Builder API for PKCS #11 Samples
CryptoAes() success
CryptoArc4() success
CryptoDes() success
CryptoDh() success
CryptoDsa() success
CryptoEcdh() success
CryptoEcdsa() success
CryptoEcmqv() success
CryptoPkcs1Enc() success
CryptoPkcs1Sig() success
CryptoRsaEnc() success
CryptoRsaSig() success
CryptoSha1() success
Token() samples starting
Slot info for Slot 0
Desc: FIPS Generic Crypto Services V1.0.1d
manufacturerID: Certicom Corp.
flags: 0x1
CKF_TOKEN_PRESENT hardwareVersion: 1.0
...
10. Edit the pkiuser's home directory so that every file is owned by pkiuser.
cd /usr/share/pki; chown -R pkiuser:pkiuser pkiuser
11. List the Certicom ECC module to make sure it has been properly loaded. The module is in security databases in the subsystem's alias directory. For example: modutil -dbdir /var/lib/pki-ca/alias -list certicom
12. Add the password for the ECC token to the subsystem's password file. Escape any spaces or special characters in the name. For example: vim /etc/pki-ca/password.conf
hardware-Certicom\ FIPS\ Cert/Key\ Services=secret
The hardware- prefix is required.
13. Edit the CA configuration and add a line to require signature verification. In this file, spaces and special characters do not need to be escaped. For example: ca.requestVerify.token=Certicom FIPS Cert/Key Services
14. Edit file dtomcat5-instance file for the subsystem in the /usr/bin directory, and add a line to use the ECC module.
60
Chapter 4. Additional Installation Options
umask 00002
NSS_USE_DECODED_CKA_EC_POINT=1
export NSS_USE_DECODED_CKA_EC_POINT
15. Start the CA.
service pki-ca start
16. Continue with the CA configuration, with two important configuration settings:
In the Key Store panel, the ECC module should be listed as an available token. Select that module for the key store.
In the Key Pairs panel, ECC should be listed as an option to use to generate the keys used for the CA's certificates. Select the ECC key type.
17. After completing the configuration, try to log into the subsystem console.
pkiconsole https://server.example.com:9445/ca
This fails, because the console is not yet configure to run in ECC. However, this does create the security databases for the console, so the ECC module can be loaded.
Load the ECC module into the console security databases.
cd ~/.redhat-idm-console/ modutil -dbdir . -nocertdb -add certicom -libfile /usr/lib/libsbcpgse.so
Now, logging into the console succeeds.
18. The web browser used to access administrative and agent services pages also needs to be configured to support ECC.
a. Create a user for the browser profile, such as agent-pki.
b. Launch Firefox and create a profile for this user; this automatically creates the required security databases and directory.
c. Set the root home directory to /home/agent-pki, and make sure the directory is owned by root.
chown -R root:root /home/agent-pki d. Copy the ECC module libraries and initpin file to the /home/agent-pki directory. All these files should be owned by root.
e. Load the ECC module.
modutil -dbdir /home/agent-pki/.mozilla/profile.default -nocertdb -add certicom -libfile /usr/lib/libsbcpgse.so
f. Run the initpin file. When prompted, enter the Certicom token database directory,
/usr/share/pki/pkiuser, and enter the PIN configured for those databases.
./initpin g. Change the ownership of the new user's home directory from root to the user. For example:
61
Red Hat Certificate System 8.0 Install Guide chown -R agent-pki:agent-pki /home/agent-pki h. In the terminal with the /home/agent-pki directory open, export the environment variable that allows ECC support.
export NSS_USE_DECODED_CKA_EC_POINT=1 i. Open Firefox again. The Certicom module should be available and you should be able to log into it successfully.
j. Then, import the agent certificate and root CA certificate or certificate chain into Firefox so that the user profile can access the agent services pages.
19. The NSS_USE_DECODED_CKA_EC_POINT environment variable also needs to be set to access the subsystem Java console with an ECC certificate. This can be set in the .bashrc file for the user who uses the console. For example:
vim /home/jsmith/.bashrc
# User specific aliases and functions
NSS_USE_DECODED_CKA_EC_POINT=1
export NSS_USE_DECODED_CKA_EC_POINT
4.3. Changing the Hashing Algorithm Used for Subsystem Keys
When a CA is installed, along with determining the key type and size, the hashing algorithm for the key pair is set. However, for other subsystems, the hashing algorithm is not configurable, so they use whatever the default is for the CA which issues their certificates.
Instead of using the CA's hashing algorithm, it is possible to edit the profiles used to generate the subsystem certificates; then, the configuration wizard will use whatever hashing algorithm is in the profile instead of the one used by the CA.
NOTE
This is true for subordinate CAs as well as other subsystems. While some of the certificates for a sub CA are generated locally — and therefore can take a user-defined hashing algorithm for their keys in the configuration wizard — other certificates for the sub CA (like its signing certificate) are generated by another CA and default to that CA's key hashing algorithm.
To assign the hashing algorithm to the certificate, add this line to the profile in the CA's profile directory, such as /var/lib/instance_name/profiles/ca: default.params.signingAlg=hashing_alg
TIP
Editing certificate profiles is covered in the Administrator's Guide.
Each of the subsystem certificate profiles can be edited:
62
Chapter 4. Additional Installation Options caInternalAuthOCSPCert.cfg
caInternalAuthTransportCert.cfg
caInternalAuthAuditSigningCert.cfg
caInternalAuthServerCert.cfg
caInternalAuthDRMstorageCert.cfg
caInternalAuthSubsystemCert.cfg
The hashing algorithms that are available depend on whether RSA or ECC is selected as the key type.
For RSA, the available algorithms are as follows:
SHA256withRSA (the default)
SHA1withRSA
SHA256withRSA
SHA512withRSA
MD5withRSA
MD2withRSA
For ECC:
SHA256withEC (the default)
SHA1withEC
SHA384withEC
SHA512withEC
4.4. Enabling IPv6 for a Subsystem
Certificate System automatically configures and manages connections between subsystems. Every subsystem must interact with a CA as members of a security domain and to perform their PKI operations.
For these connections, Certificate System subsystems can be recognized by their host's fully-qualified domain name or an IP address. By default, Certificate System resolves IPv4 addresses and hostnames automatically, but Certificate System can also use IPv6 for their connections. IPv6 is supported for all server connections: to other subsystems, to the administrative console (pkiconsole), or through command-line scripts such as tpsclient.
op=var_set name=ca_host value=IPv6 address
If a host has both an IPv4 address and an IPv6 name, then an environment variable can be set before the Certificate System packages are installed so that Certificate System setup scripts will recognize the
IPv6 name.
1. If the default (first) instances should use IPv6, set the environment variable to keep pkicreate from running.
export DONT_RUN_PKICREATE=1
2. Install the Red Hat Certificate System packages.
3. Set the IPv4 and IPv6 addresses in the /etc/hosts file. For example:
63
Red Hat Certificate System 8.0 Install Guide
vim /etc/hosts
192.0.0.0 server.example.com IPv4 address
3ffe:1234:2222:2000:202:55ff:fe67:f527 server6.example.com IPv6 address
4. Then, export the environment variable to use the IPv6 address for the server. For example: export PKI_HOSTNAME=server6.example.com
5. Unset the DONT_RUN_PKICREATE variable so that the new instances can be created.
export DONT_RUN_PKICREATE=0
6. Run pkicreate to create the new instance. The values for the server hostname in the CS.cfg file will be set to the IPv6 address.
4.5. Configuring Separate RA Instances
When an RA is installed or created, it is automatically added to a default Registration Managers Group on the CA. This means that all RA managers belong to the same group, by default.
However, a particular site might require more than one RA instance, each having its own set of RA agents. If the site policy disallows cross-management between the RA instances, then extra configuration is needed to create separate RA groups.
1. Install and configure the first RA instance.
2. Add the new RA group to the Certificate Manager.
a. Start the Console. For example: pkiconsole https://server.example.com:9445/ca b. Click Users and Groups, and then click Groups.
c. Click Add to open the Edit Group Information dialog box.
d. Enter the group name and description, such as Registration Manager2 Agents.
e. Click OK.
3. Add the new RA authentication instance to the CA: a. Open the CA configuration directory, and edit the CS.cfg file cd /etc/pki-ca vi CS.cfg
b. Search for the string raCertAuth.
c. Copy those lines for the first RA instance, paste them, and edit them for the second RA instance's information. For example:
auths.instance.raCertAuth.agentGroup=Registration Manager Agents
auths.instance.raCertAuth.plug-inName=AgentCertAuth
auths.instance.ra2CertAuth.agentGroup=Registration Manager2 Agents
auths.instance.ra2CertAuth.plug-inName=AgentCertAuth
64
Chapter 4. Additional Installation Options
4. Add the new RA user enrollment profile to the Certificate Manager's certificate profiles list to utilize the new RA authentication instance.
a. Open the CA profiles directory.
cd /var/lib/pki-ca/profiles/ca b. Copy the current RA profile to create the new profile. For example: cp caDualRAuserCert.cfg caDualRA2userCert.cfg
c. Edit the new file to contain the second RA instance's information. Change raCertAuth to
ra2CertAuth.
5. Open the CA configuration directory, and edit the CS.cfg file.
cd /var/lib/pki-ca/conf vi CS.cfg
a. Add caDualRA2userCert to the profiles list. For example: profile.list=...[snip]...caRAserverCert,caRA2userCert
Make sure to use a comma to separate the entries.
b. Search for the lines for the caDualRAuserCert profile configuration, copy them, and edit them for the second RA instance's information.
profile.caDualRAuserCert.class_id=caEnrollImpl
profile.caDualRAuserCert.config=/var/lib/pkica/profiles/ca/caDualRAuserCert.cfg
profile.caDualRA2userCert.class_id=caEnrollImpl
profile.caDualRA2userCert.config=/var/lib/pki- ca/profiles/ca/caDualRA2userCert.cfg
6. Add a new URI mapping to allow the new RA agent to be registered in the new RA group.
a. Open the CA web applications directory, and edit the web.xml file: cd /var/lib/pki-ca/webapps/ca/WEB-INF vi web.xml
b. At about line 288 in the web.xml file is the servlet setting for the first RA's user. Copy the entire entry, including the opening and closing <servlet> tags, and edit the information to match the second RA's user. For example:
65
Red Hat Certificate System 8.0 Install Guide
<servlet>
<servlet-name> caRegisterRa2User </servlet-name>
<servlet-class> com.netscape.cms.servlet.csadmin.RegisterUser
</servlet-class>
<init-param><param-name> GetClientCert </param-name>
<param-value> false </param-value> </initparam>
<init-param><param-name> authority </param-name>
<param-value> ca </param-value> </initparam>
<init-param><param-name> ID </param-name>
<param-value> caRegisterRaUser </param-value>
</init-param>
<init-param><param-name> AuthMgr </param-name>
<param-value> TokenAuth </param-value> </init-param>
<init-param><param-name> GroupName </param-name>
<param-value> Registration Manager2 Agents </paramvalue> </init-param>
<init-param><param-name> AuthzMgr </param-name>
<param-value> BasicAclAuthz </param-value> </initparam>
<init-param><param-name> resourceID </param-name>
<param-value> certServer.ca.registerUser </paramvalue> </init-param>
</servlet> c. At about line 2510 in the web.xml file is the servlet-mapping setting for the first RA's user mapping. Copy the entire entry, including the opening and closing <servlet-
m apping> tags, and edit the information to match the second RA's user. For example:
<servlet-mapping>
<servlet-name> caRegisterRa2User </servlet-name>
<url-pattern> /admin/ca/registerRa2User </url-pattern>
</servlet-mapping>
7. Restart the CA. For example: service pki-ca restart
8. Create the new RA instance using the pkicreate.
pkicreate -pki_instance_root=/var/lib -subsystem_type=ra pki_instance_name=pki-ra2 -secure_port=12899 -unsecure_port=12898 -verbose user=pkiuser -group=pkiuser
9. Open the configuration file for the new RA instance, and edit its parameters to reflect the second
RA instance information.
cd /var/lib/pki-ra2/conf/ vi CS.cfg
10. Change the registerRaUser setting to registerRa2User.
conn.ca1.servlet.addagent=/ca/admin/ca/registerRa2User
66
Chapter 4. Additional Installation Options
11. Change the caDualRAuserCert setting to caDualRA2userCert.
request.renewal.approve_request.0.profileId=caDualRAuser2Cert
...
request.user.approve_request.0.profileId=caDualRA2userCert
12. Restart the new RA instance. For example:
# service pki-ra2 restart
13. A URL was generated at the end of the pkicreate command; go to that URL to configure the second RA. For example: http://server.example.com:12898/ra/admin/console/config/login?
pin=bFyAk9nWPfgLZXffRBT9
14. When the new RA is completely configured, restart the instance.
# service pki-ra2 restart
67
