> ## Documentation Index > Fetch the complete documentation index at: https://docs.futurex.com/llms.txt > Use this file to discover all available pages before exploring further. # Configure Dogtag Certificate System > Step-by-step guide to install and configure Dogtag CA on Fedora Linux, integrating with CryptoHub for secure key storage. This section shows you how to install Dogtag Certificate System on Fedora Linux 28. The example demonstrates the installation of a CA subsystem by using a self-signed CA signing certificate, with the certificates and their corresponding keys securely stored in CryptoHub. ## Install the Dogtag packages Install the Dogtag packages by using the following command: ```shell expandable lines wrap title="Shell" theme={null} sudo dnf install pki-ca pki-kra 389-ds-base ``` ## Create the Directory Server instance The Dogtag CA and KRA subsystems use a 389 Directory Server as an internal database. Perform the following steps to create the Directory Server instance for the Dogtag Internal DB: Run the following command to log in as the root user: ```shell expandable lines wrap title="Shell" theme={null} sudo su ``` To set a FQDN (fully qualified domain name) as the hostname for your Fedora 28 system, edit the `/etc/hosts` file as follows: ```shell expandable lines wrap title="Shell" theme={null} 127.0.0.1 pki.example.com ::1 pki.example.com ``` You can set any valid FQDN, not just`pki.example.com`. You must also run the following command to update the hostname in the `/etc/hostname` file. ```shell expandable lines wrap title="Shell" theme={null} hostnamectl set-hostname pki.example.com ``` Create a directory for storing the 389 Directory Server configuration file: ```shell expandable lines wrap title="Shell" theme={null} mkdir -p /etc/389-ds ``` Create a configuration file named **setup.inf** in the `/etc/389-ds` directory with the **\[General]** and **\[slapd]** sections configured as follows: ```shell expandable lines wrap title="Shell" theme={null} [General] FullMachineName= pki.example.com SuiteSpotUserID= nobody SuiteSpotGroup= nobody [slapd] ServerPort= 389 ServerIdentifier= pki-tomcat Suffix= dc=example,dc=com RootDN= cn=Directory Manager RootDNPwd= Password ``` Run the directory server installation script, selecting the defaults or customizing as desired: ```shell expandable lines wrap title="Shell" theme={null} setup-ds.pl --silent --file=/etc/389-ds/setup.inf ``` ## Create a subsystem instance The next step in the process is to 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 may be run either interactively, as a batch process, or a combination of both (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. To spawn a subsystem that uses an HSM, Dogtag recommends creating an override configuration file that contains only the parameters necessary for using the CryptoHub as its token. Any parameter settings in this file override the parameter settings in the `default.cfg` file. You can spawn any of the various Dogtag PKI subsystems (CA, KRA, OCSP, TKS, TPS) to use the CryptoHub, but this integration guide focuses on the Certificate Authority (CA) for brevity. Perform the following tasks: 1. Prepare an override configuration file with the required HSM parameters. 2. Run the **pkispawn** utility. 3. View the keys and certificates that Dogtag created in the CryptoHub. 4. Import the CA administrator PKCS #12 file into the browser. 5. Access the new CA subsystem in the browser. ### Prepare a configuration file Perform the following steps to prepare an override configuration file with the required HSM parameters: Create the override configuration file for the CA subsystem. ```shell expandable lines wrap title="Shell" theme={null} sudo vim ca.cfg ``` The following is an example override file that can be used for spawning a CA subsystem with the CryptoHub : All values contained within angle brackets need to be set to a specific value by the user. All other values should be set exactly as shown. The `pkidspassword` value must match the password set for the directory manager when 389 Directory Server was installed. The `pkitokenpassword` value must be set to the CryptoHub identity password configured inside the `` tag in the `fxpkcs11.cfg` file. ```text expandable lines wrap title="Text" theme={null} [DEFAULT] ########################## # Provide HSM parameters # ########################## pki_hsm_enable=True pki_hsm_libfile= pki_hsm_modulename=FxPKCS11 pki_token_name=Futurex pki_token_password= ######################################## # Provide PKI-specific HSM token names # ######################################## pki_audit_signing_token=Futurex pki_ssl_server_token=Futurex pki_subsystem_token=Futurex ################################## # Provide PKI-specific passwords # ################################## pki_admin_password= pki_client_pkcs12_password= pki_ds_password= ##################################### # Provide non-CA-specific passwords # ##################################### pki_client_database_password= [CA] ####################################### # Provide CA-specific HSM token names # ####################################### pki_ca_signing_token=Futurex pki_ocsp_signing_token=Futurex ``` After you have finished editing, save the file. ### Run the pkispawn utility Perform the following steps to run the pkispawn utility: In a terminal, run the following command to deploy a CA subsystem using the CryptoHub. The full path to the `ca.cfg` file is required if you are not running the command from the directory where the `ca.cfg` file is saved. ```shell expandable lines wrap title="Shell" theme={null} sudo pkispawn -f ca.cfg -s CA -vvv ``` You will most likely see a warning message about manually adding a module while p11-kit is enabled. You can disregard this warning and press Enter to continue. If the deployment is successful, an installation summary similar to the following will be presented after the command completes: ```shell expandable lines wrap title="Shell" theme={null} ========================================================================== INSTALLATION SUMMARY ========================================================================== Administrator's username: caadmin Administrator's PKCS #12 file: /root/.dogtag/pki-tomcat/ca_admin_cert.p12 To check the status of the subsystem: systemctl status pki-tomcatd@pki-tomcat.service To restart the subsystem: systemctl restart pki-tomcatd@pki-tomcat.service The URL for the subsystem is: https://pki.example.com:8443/ca PKI instances will be enabled upon system boot ========================================================================== ``` If the pkispawn command fails, you need to run the following command to delete the subsystem instance that was only partially created before re-attempting to run pkispawn. ```shell expandable lines wrap title="Shell" theme={null} sudo pkidestroy -s CA -i pki-tomcat ``` ### View the keys and certificates To view the keys and certificates that Dogtag created on the CryptoHub , use the **PKCS11Manager** utility packaged with the Futurex PKCS #11 module. Perform the following steps: In a terminal, navigate to the directory where the FXPKCS11 module is installed (`/usr/local/bin/fxpkcs11`) and run **PKCS11Manager** by using the following command: ```shell expandable lines wrap title="Shell" theme={null} ./PKCS11Manager ``` This presents the following main menu: ```shell expandable lines wrap title="Shell" theme={null} 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 `1` to find all objects, and select the **Enter** key. Enter `2` to log in, and select the **Enter** key. Enter the password of the identity that is defined in the **FXPKCS11** configuration file, and select the **Enter** key. If successful, you receive confirmation that you are logged in. Enter `5` to find objects, and select the **Enter** key. Enter `1` to find all objects, and select the **Enter** key. Information prints for all keys and certificates that the connecting identity has access to. Dogtag PKI creates 15 objects in CryptoHub for a CA subsystem deployment. ### Import the PKCS #12 file The following steps use a Firefox web browser. The steps might vary when using a different browser, but the overall process is the same. Perform the following steps to import the CA administrator PKCS #12 file into the browser: In Firefox, go to **Preferences** > **Privacy & Security** > **Certificates** and select **\[ View Certificates ]**. Under the **Your Certificates** tab, select **\[ Import ]** to import the CA Administrator PKCS #12 file (for example, `ca_admin_cert.p12`). When it prompts for a password, enter the value that was configured for the `pki_client_pkcs12_password` define in the `ca.cfg` file. The location of the `caadmincert.p12` file is in the installation summary for the CA subsystem deployment. ### Access the CA subsystem Perform the following steps to access the new CA subsystem in the browser: Access the Dogtag Certificate System subsystem console by going to the following URL: ```none expandable lines wrap title="None" theme={null} https://:8443/pki/ui/ ``` When submitting Certificate Signing Requests (CSRs) in Dogtag Certificate System, you must use both the Common Name and UID fields. If you submit a request with only the Common Name field completed, the request fails, and you receive an error stating that the Subject Name does not match.