Certificate Authority
Red Hat Certificate System (RH...
Install RHCS and deploy the subsystem
11 min
this section demonstrates how to deploy a ca subsystem in red hat certificate system (rhcs) using a deployment file and the pkispawn command as mentioned in the prerequisites section, it is assumed that you have already installed rhcs with a valid subscription per red hat's official documentation modify selinux file contexts if you want to deploy an rhcs subsystem by using an hsm with selinux running in enforcing mode, you must manually update certain selinux and firewalld settings before deploying the subsystem the following section describes the required actions run the following commands to reset the contexts of the main fxpkcs11 directory and the fxpkcs11 cfg file sudo semanage fcontext a t lib t '/usr/lib/fxpkcs11(/ )?' sudo restorecon rfv /usr/lib64/fxpkcs11 sudo semanage fcontext a t etc t '/etc/fxpkcs11 cfg' sudo restorecon v /etc/fxpkcs11 cfg run the following command to allow outbound connections to tcp port 9100 (the excrypt production tls port on the hsm) sudo semanage port m t http port t p tcp 9100 create and configure a subsystem instance run the pkispawn script to create and configure a subsystem instance the pkispawn command line tool installs and configures a new pki instance it eliminates the need for separate installation and configuration steps, and you can run it either interactively, as a hands off batch process, or as a batch process with prompts for passwords refer to the pkispawn man page for detailed information about all supported options by running man pkispawn the pkispawn command reads in its default installation and configuration values from a plain text configuration file ( /etc/pki/default cfg ) this file consists of name=value pairs divided into \[default] , \[tomcat] , \[ca] , \[kra] , \[ocsp] , \[tks] , and \[tps] sections we strongly recommend that you read the full documentation to understand the purpose of every parameter in the /etc/pki/default cfg file this enables you to customize your pki environment to your specific needs the red hat recommended procedure for spawning a subsystem that uses an hsm is to create an override configuration file that contains only the parameters necessary for using the hsm as its token any parameter settings in this file override the parameter settings in the default cfg file to use the hsm, you can spawn any of the rhcs subsystems (ca, kra, ocsp, tks, or tps), but this integration guide focuses solely on the certificate authority (ca) for brevity prepare an override configuration file perform the following steps to prepare an override configuration file with the required hsm parameters in a terminal, go to the directory where you installed the {{futurex}} pkcs #11 module on your system (such as /usr/lib64/fxpkcs11 ) run the following vim command as sudo sudo vim default futurex txt you can use the following example override file for spawning a ca subsystem with the hsm you must set all values contained within angle brackets to your specific value set all other values exactly as shown the pki ds password value must match the password set for the directory manager during the installation of the red hat directory server \[default] pki instance name=rhcs rootca pki http port=8080 pki https port=8443 \# admin & client credentials pki admin email=caadmin\@example com pki admin name=caadmin pki admin password=\<pki admin password> pki client database password=\<pki client database password> pki client pkcs12 password=\<pki client pkcs12 password> \# security domain (first ca or joining an existing one) pki security domain name=lab security domain pki security domain hostname=pki test local pki security domain https port=8443 pki security domain password=\<pki security domain password> \# 389 ds pki ds url=ldap\ //127 0 0 1 389 pki ds base dn=dc=pki,dc=test,dc=local pki ds database=userroot pki ds bind dn=cn=directory manager pki ds password=\<pki ds password> \# hsm (pkcs#11) pki hsm enable=true pki hsm libfile=/usr/lib64/fxpkcs11/libfxpkcs11 so pki hsm modulename=fxpkcs11 pki token name=futurex pki token password=\<hsm identity password> \# pki wide token assignments pki audit signing token=futurex pki ca signing token=futurex pki ocsp signing token=futurex \# do not store these on the hsm pki sslserver token=internal pki subsystem token=internal \[ca] \# ca specific hsm token assignments pki ca signing token=futurex pki ocsp signing token=futurex \# (optional but recommended) explicit subjects to avoid surprises pki ca signing subject dn=cn=lab root ca,o=lab pki ocsp signing subject dn=cn=lab ocsp signing certificate,o=lab pki subsystem subject dn=cn=subsystem certificate,o=lab pki audit signing subject dn=cn=audit signing certificate,o=lab pki sslserver subject dn=cn=pki test local,o=lab after you have finished editing, save the file two step ca subsystem install run the first pkispawn to create the ca db in a terminal, run the first pkispawn to create the ca db and generate the ca subsystem keys on the {{vectera}} hsm sudo pkispawn s ca f /root/rootca inst cfg this first pkispawn run should end with the following message installation failed command failed pki d /var/lib/pki/rhcs10 rootca/conf/alias f /var/lib/pki/rhcs10 rootca/conf/password conf token futurex client cert validate certusage statusresponder futurex\ ocspsigningcert cert rhcs10 rootca ca invalid certificate ( 8172) peer's certificate issuer has been marked as not trusted by the user this is expected, and we will fix the ca trust flags before running pkispawn again to complete the subsystem installation fix the ca certificate trust on the ca certificate run the certutil command below to set the correct trust flags on the casigningcert if you chose a different instance name than "rhcs rootca", modify the command accordingly db=/var/lib/pki/rhcs rootca/conf/alias ca nick plain="casigningcert cert rhcs rootca ca" certutil m d "$db" n "$ca nick plain" t "ct,ct,ct" the certutil command will prompt you to enter the password or pin for "nss certificate db" you can find it in the /var/lib/pki/rhcs rootca/conf/password conf file example \[root\@pki ]# cat /var/lib/pki/rhcs10 rootca/conf/password conf hardware futurex=safest internal=2zi2!fs,;osr internaldb=futurex123 replicationdb=zd67 c4rk 8g the "nss certificate db" password is the internal parameter value (e g , 2zi2!fs,;osr ) copy and paste the value into the certutil command that's prompting for it re run pkispawn to complete the ca subsystem deployment run the same pkispawn command you ran before, again sudo pkispawn s ca f /root/rootca inst cfg when pkispawn has finished running, you should see an "installation summary" that indicates the ca subsystem deployment was successful ========================================================================== installation summary \========================================================================== administrator's username caadmin administrator's pkcs #12 file /root/ dogtag/rhcs10 rootca/ca admin cert p12 to check the status of the subsystem systemctl status pki tomcatd\@rhcs10 rootca service to restart the subsystem systemctl restart pki tomcatd\@rhcs10 rootca service the url for the subsystem is https //pki test local 8443/ca pki instances will be enabled upon system boot \========================================================================== view the keys and certificates to view the keys and certificates that rhcs created on the hsm, use the pkcs11manager utility packaged with the {{futurex}} pkcs #11 module in a terminal, go to the directory where you installed the fxpkcs11 module and run pkcs11manager by using the following command /pkcs11manager this displays the following main menu main menu 1\ print library/token info 2\ login 3\ logout 4\ generate key 5\ find objects 6\ modify objects 7\ delete objects 8\ generate random data 9\ sign data 10\ verify data 11\ wrap key 12\ unwrap key 13\ import public key 0\ exit enter 2 to log in enter 1 to choose text as the password input mode enter the password of the identity defined in the fxpkcs11 configuration file if successful, you get a confirmation that you are logged in enter 5 to find objects enter 1 to find all objects information prints for all keys and certificates that the connecting identity may access red hat certificate system creates 9 objects on the hsm for a ca subsystem deployment import the ca administrator file perform the following steps to import the ca administrator pkcs #12 file into the browser the following steps assume you're using a firefox web browser there might be some differences in the actions taken when using a different browser, but the overall process is similar in firefox, go to settings > privacy & security > certificates and select \[ view certificates ] on the your certificates tab, select \[ import ] to import the ca administrator pkcs #12 file (such as ca admin cert p12 ) when it prompts for a password, enter the value you configured for pki client pkcs12 password in the /root/rootca inst cfg file access the new ca subsystem perform the following steps to access the new ca subsystem in the browser access the red hat certificate system subsystem console by going to the following url https //\<fully qualified domain name> 8443/ca when submitting certificate signing requests (csrs) in rhcs, the common name and uid fields are both required if you submit a request with only the common name field completed, the request fails, and you get an error stating that the subject name does not match