PKI 10.5 Secure Installation with CMC

From Dogtag
Revision as of 03:00, 13 February 2018 by Edewata (talk | contribs) (→‎Replacing Temporary LDAP Server Certificate)

Jump to: navigation, search

This page provides some tips for deployment sites that are interested in secure options during installation. Although some instruction procedures are given for RHCS (https://access.redhat.com/documentation/en-us/red_hat_certificate_system/) in the RHEL environment at this time, there should be comparable Dogtag 10.5 procedures. In this document, the terms "CS" and "pki" are used interchangeably.

Although non-CMC enrollment methods could take advantage of many of the secure options listed on this page, instructions and examples given here are mainly focused on CMC enrollment methods.

When applicable, relevant pkispawn example config parameters are provided at each section. They are to be used for knowledge-gaining purpose only, and no action is expected till instructed in the CS instance creation section. 

Note: unless otherwise noted, all OS commands on this page are to be run as the root user.

Note: pkispawn is the CLI used for creating Dogtag/RHCS instances.
For more information, type "man pkispawn" at command prompt.

OS Installation

  • Install RHEL 7.x (Red Hat subscription needed) or Fedora 10.5 per respective instruction.

Some references:

FIPS

Information on enabling FIPS mode for RHEL can be found here: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/chap-federal_standards_and_regulations

Here is a summary of the procedures:

HSM

See supported HSMs: https://access.redhat.com/documentation/en-us/red_hat_certificate_system/9/html/release_notes/chap-release-notes-rhcs-9-2#Release_Notes-Deployment_Notes-Optional_Server_Hardware-9-2

Follow your HSM vendor's procedure to set up your Hardware Security Module. For CS instance creation using pkispawn, you will need

  • token/partition name
  • token/partition password

Make sure you obtain those from your HSM administrator before you proceed with pkispawn.

Here is an example of the relevant pkispawn info for a Thales module: 

pki_hsm_enable=True
pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so
# lunasa would be /usr/safenet/lunaclient/lib/libCryptoki2_64.so 
pki_hsm_modulename=nfast
pki_token_name=NHSM6000
pki_token_password=MY.HSM.123

Later in the pkispawn section this option will be included in the example.

SELinux

By default, SELinux should be in enforcing mode. To verify:SELinux#Checking_SELinux_mode

If the result of the command getenforce is disabled or permissive then as a root user:

  • edit the file /etc/sysconfig/selinux and set SELINUX=Enforcing
  • reboot the system

Note: SELinux policies for CS are incorporated into the standard system SELinux policies. There is therefore no actions needed by default. However, if HSM is to be used, one needs to run the following command after HSM client is setup on the installing system and before pkispawn is executed (instruction for nCipher): 

$ /sbin/restorecon -R /opt/nfast
$ /opt/nfast/sbin/init.d-ncipher restart

OS groups and CS Roles

This section explains how to correspond the CS roles to OS groups, as well as how to strengthen the CS instance files with proper ownership/permissions.

Information on CS roles can be found here: https://access.redhat.com/documentation/en-us/red_hat_certificate_system/9/html-single/administration_guide/index#User_and_Group_Authorization

CS Instance Files Ownership and Permissions

On the file system, when a CS instance is created, by default, the user group pkiuser and user id pkiuser are set as the owner of the CS system files.

The following relevant pkispawn parameters are listed. The values presented here are the default values so in general you do not need to explicitly specify them. 

pki_group=pkiuser
pki_user=pkiuser

CS Roles and Privileges

In general, CS administrators, agents, as well as auditors can manage the CS instance remotely using client applications such as CLIs, the Java Console, and browsers. For the majority of CS management tasks, a CS role user does not need to log on to the host where the CS instance runs. For instance, a pki auditor is allowed to retrieve signed audit logs remotely for verification: PKI 10.4 Audit Review/Search_Design#Downloading_Audit_Log_Files.

In some cases,however, a CS administrator might need to log on to the host system to modify configuration files directly.

In addition, on the Operating System, the role "pki administrator" should be someone who is allowed to make changes to the configuration files and read various logs. For some environment, it is desirable to prohibit the administrators to access the audit logs.

Because of these, you want to consider the following:

  • Create a "pkiadmin" group on the OS
    • note: Users should be existing on the OS before being added to the pki groups that they belong.
    • Run "man useradd" on the command line to learn how to add a user.
  • Add pki administration users to the pkiadmin group:
    • Run "man usermod" on the command line to learn how to add a user to the right pki group.
  • On the OS, add proper "sudo" rules to allow the "pkiadmin" group to read and modify the desired CS configuration files, e.g.
    • CS.cfg
    • server.xml
    • profiles
  • Change the file owner and permission on the files listed above to pkiadmin.

RHCS/Dogtag and RHDS/389-ds Package Installation

Overview at PKI Install Guide PKI Data Storage Requirements

e.g. (for Fedora: yum dnf ...) yum install 389-ds pki-ca pki-kra pki-ocsp

Creating an LDAP Instance

Follow instruction here to install and create DS instance: Installing DS

Configuring LDAP over SSL

When installing a CA instance, if the internal LDAP server is on a different host than the ca's intended host, or if the installing environment is less secure, site administrators should consider employing SSL between the LDAP server and the CA during installation. A temporary self-signed DS server certificate could be used initially during CA instance creation before CA becomes functional. Here you will find steps on how to establish that at the "Generating Temporary DS Certificate" section: Enabling SSL Connection with Internal Database on New Instance#Generating_Temporary_DS_Certificate

And here you will find instruction on "Enabling Secure Connection in DS" Enabling SSL Connection with Internal Database on New Instance#Enabling_Secure_Connection_in_DS 

Note: Please stop at end of the above linked section.  You will be directed to continue with
http://pki.fedoraproject.org/wiki/Enabling_SSL_Connection_with_Internal_Database_on_New_Instance#Enabling_Secure_DS_Connection_in_PKI
when we get to the step on creating the pki instance with pkispawn.

Later, when installing a non-CA cs instance, no temporary DS SSL server certificate is needed, as the already-setup CA could issue a real server cert for the directory server.

For ease of reference, I'm copying the relevant example pkispawn parameters given at the above-mentioned instruction link here: 

pki_ds_secure_connection=True
pki_ds_hostname=server.example.com
pki_ds_ldaps_port=636
pki_ds_secure_connection_ca_nickname=DS Certificate
pki_ds_secure_connection_ca_pem_file=ds.crt

Where the pki_ds_secure_connection_ca_pem_file contains the PEM format of the temporary DS server certificate.

Creating CS Instance

First, for information about pkispawn, please run "man pkispawn" at command line. 

Note: Although the example below is given primarily for creating a root CA, as that's what most likely would be the first
CA instance one creates, the instructions are meant for all subsystems unless otherwise noted.

Pre-pkispawn Knowledge and Considerations

Before running pkispawn to create a CS instance, a few pre-pkispawn considerations to note:

  • Unique Nicknames: If a network (shared) HSM partition is used, understand that certificate nicknames must be unique. Unless a nickname is explicitly specified, by default, the following pkispawn parameters are used to generate a nickname:
    • pki_instance_name
    • pki_security_domain_name
    • pki_host (for server certificates)
  • Bootstrap Admin User: A "bootstrap" admin user is needed at time of pkispawn cs instance creation. This bootstrap user by default possesses all role privileges. This user will be the one that creates other role (administrator, agent, auditor) users. The pkispawn parameters relevant to such "bootstrap" admin user are the following. e.g.:
    • pki_admin_email=caadmin@example.com
    • pki_admin_name=pkica admin
    • pki_admin_nickname=caadmin
    • pki_admin_password=MY.password.123
    • pki_admin_uid=caadmin
  • Random Serial Numbers : It is possible to instruct the CA to generate random serial numbers to the certificates it issues Random Certificate Serial Numbers. The pkispawn parameter to enable random serial number is:
    • pki_random_serial_numbers_enable (default to false if unspecified)
  • ECC: Some sites might prefer having ECC instead of RSA certificates. By default, without explicitly specified, CS servers are installed with RSA. To install with ECC certificates, the relevant pkispawn configuration parameters are (example shown for CA):
    • pki_ca_signing_key_algorithm=SHA256withEC
    • pki_ca_signing_key_size=nistp256
    • pki_ca_signing_key_type=ecc
    • pki_ca_signing_signing_algorithm=SHA256withEC
    • pki_ocsp_signing_key_algorithm=SHA256withEC
    • pki_ocsp_signing_key_size=nistp256
    • pki_ocsp_signing_key_type=ecc
    • pki_ocsp_signing_signing_algorithm=SHA256withEC
    • pki_ssl_server_key_algorithm=SHA256withEC
    • pki_ssl_server_key_size=nistp256
    • pki_ssl_server_key_type=ecc
    • pki_subsystem_key_algorithm=SHA256withEC
    • pki_subsystem_key_size=nistp256
    • pki_subsystem_key_type=ecc

pkispawn

With all the knowledge from the previous sections, we are ready to create a pkispawn configuration file for the first CA instance. This example will be for a root CA, meaning that the CA signing cert will be a self-sign certificate.

For a secure setup, it is advised to use two-step pkispawn procedure to allow administrator opportunity to fine-tune the server configuration before it becomes operational. (see: Two-Step Installation)

Step One

pkispawn example that incorporates all possible secure options (assuming the file name is ca_inst.inf): 

[DEFAULT]
pki_instance_name=pki-root-ca-cfu-02082018
pki_user=pkiuser
pki_group=pkiuser
pki_audit_group=pkiaudit

pki_https_port=8443
pki_http_port=8080

#Token Password
pki_hsm_enable=True
pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so
pki_hsm_modulename=nfast
pki_token_name=NHSM6000
pki_token_password=MY.HSM.123

#Admin Password
pki_admin_password=MY.password.123

#Security Domain
pki_hostname=host.example.com
pki_security_domain_name=Example-root-ca
pki_security_domain_password=MY.password.123

#client Dir
pki_client_database_password=MY.password.123
pki_client_pkcs12_password=MY.password.123

pki_ds_ldap_port=389
pki_ds_bind_dn=cn=Directory Manager
pki_ds_password=MY.ds.123
pki_ds_secure_connection=True
pki_ds_ldaps_port=636
pki_ds_secure_connection_ca_pem_file=/tmp/ca_cert.pem
pki_ds_remove_data=True

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[CA]
pki_admin_nickname=PKI CA Administrator for pki-root-ca-cfu-02082018
pki_admin_name=caadmin
pki_admin_uid=caadmin
pki_admin_email=caadmin@example.com
pki_admin_key_type=rsa
pki_import_admin_cert=False
pki_ds_hostname=host.example.com
pki_ds_database=pki-ca-cfu
pki_random_serial_numbers_enable=True

Run step one install (note the "--skip-configuration" option): 

pkispawn -s CA -f ca_inst.inf -vv --skip-configuration

Mid-Installation Configuration (Between the two pkispawn steps)

One could tweak configurations at this point before CS is fully installed and goes live. See Two-Step Installation#Use_Cases

Below please find some of the options for the more security-oriented.

For CA's only:

  • For CMC Shared Token feature:
  • For higher level of security, you want to set cmc.popLinkWitnessRequired to true in the CS.cfg, e.g.
    • cmc.popLinkWitnessRequired=true
  • Disable enrollment profiles that you don't wish to offer at your site (e.g. non-CMC enrollment profiles)

For all subsystems:

For non-CA subsystems

Step Two

Run pkispawn again, this time with --skip-installation option instead: 

pkispawn -s CA -f ca_inst.inf -vv --skip-installation

Post-pkispawn Considerations and Operations

Here are some of the post-installation operations that one might consider.

Replacing Temporary LDAP Server Certificate

If you followed the earlier procedure to create a temporary LDAP server certificate, you can now enroll for a real LDAP server certificate from the newly created CA to replace by doing the following:

  • Generate a PKCS#10 request. There are different ways to do this
    • DS should have document on how to do this in their recommended way
    • The standard CS procedure is to use PKCS10Util. e.g.
      • PKCS10Client -d . -p MY.password.123 -a rsa -l 2048 -o ds.csr -n "CN=host.example.com"
  • Generate a CMC request and enroll for certificate:
  • Replace the DS server certificate; It can be done in various ways.
    • DS should have document on how to do this in their recommended way
    • shutdown ds and use certutil to delete the temporary cert and add the real cert

Setting up User Directory for CMC Shared Secret

For information on CMC Shared Token, see PKI 10.5 CMC Shared Token

To setup directory server for supporting CMC Shared Secret, see: PKI 10.5 CMC Shared Token#Directory_Configuration

Password Daemon (nuxwdog)

For information on the Password Daemon:

  • Nuxwdog
  • type "man nuxwdog" at command line.

Setup Procedures:

  • Adding Services in CS to be Prompted by Nuxwdog - The cms.passwordlist in the CS.cfg contains list of password prompts that are required at time of cs instance startup. So in the example where an external ldap server is setup for the CMC Shared Secret feature, it's entry would be required if nuxwdog is configured to run.
    • e.g. CS.cfg: cms.passwordlist=internaldb,replicationdb,CorporateDirectory
  • Enable nuxwdog - Follow instruction here to enable nuxwdog: Nuxwdog#Enabling_Nuwxdog

Signed Audit Log

To prevent unauthorized log manipulation, CS provides Signed Audit Log feature. Information can be found: 

Note: At time of this writing, only RSA signing certificates are supported as audit signing cert.

Setting up NSS database to run PKI CLIs

For information about CLI, see: PKI CLI.

Instruction on initializing for CLI:

  • Note: before you follow the following instruction, please note that there is a possibility that you already have an NSS database. e.g.:
    • <user home directory>/.thunderbird/<profile>/*.db
    • <user home directory>/.mozilla/firefox/<profile>/*.db
  • CLI initialization instruction: PKI CLI Initialization

Creating Role Users

Initially, right after a CS instance is freshly installed, recall that there is only one user existing -- the bootstrap administrator user.

This special user is to issue certificates for other role users before they take over. The process involves:

  • Asking these role users to enroll for their certificates if they have not done so already
    • Note: it should be just a certificate that can identify them.
  • Creating and adding the user entries into CS's authentication user database
  • Adding the user's certificate to his/her ldap record
  • Adding each user to his/her assigned group (role)
Note: Once the first administrator is added successfully, the bootstrap administrator user, pkiadmin, can be either removed from the authentication user database.

Setup Procedures:

Java Security Manager

This section is for information only. The default configuration should cover all that's needed.

All RHCS/Dogtag instances run as Tomcat instances with the Java Security Manager enabled by default.

This is controlled on an instance-by-instance basis by the SECURITY_MANAGER="true" parameter located in the "/var/lib/pki/<instance_name>/conf/tomcat.conf" file.

Other CS subsystems

Follow the instructions below to install non-root-CA subsystems (e.g. subordinate CA, OCSP, KRA, TKS, and TPS): http://pki.fedoraproject.org/wiki/PKI_10.5_Installation_with_CMC

References

Retrieved from "http://www.dogtagpki.org/index.php?title=PKI_10.5_Secure_Installation_with_CMC&oldid=30877"