Installing Cloudera Navigator Encrypt

Learn about installing Navigator Encrypt, setting up TLS certificates on a Navigator Encrypt client, entropy requirements , and uninstalling and reinstalling NavEncrypt.

See Data at Rest Encryption Requirements for more information about encryption and Navigator Encrypt requirements.

Setting Up an Internal Repository

You must create an internal repository to install or upgrade Navigator Encrypt. For instructions on creating internal repositories (including Cloudera Manager, CDH, and Cloudera Navigator encryption components), see Configuring a Local Package Repository.

Installing Navigator Encrypt (RHEL-Compatible)

Learn how to install RHEL compatible Navigator Encrypt. The steps below show an example of how to install NavEncrypt on a cluster running Red Hat Linux.

  1. Install the EPEL Repository.

    Dependent packages are available through the Extra Packages for Enterprise Linux (EPEL) repository. To install the EPEL repository, install the epel-release package. The EPEL repository for each release of RHEL is different ,so confirm the host is set up correctly.

  2. Install the NavEncrypt Repository.
    1. mkdir -p /root/navencrypt-repo
    2. Fetch the NavEncrypt repository from the Cloudera download site, for example: wget https://archive.cloudera.com/p/navencrypt7/7.1.9.1000/rhel8/navigator-encrypt-7.1.9.1000-el8.tar.gz
    3. tar -zxvf navigator-encrypt-7.1.9.1000-el8.tar.gz --directory /root/navencrypt-repo
  3. Create and edit file /etc/yum.repos.d/navencrypt-repo:
    [navencrypt-repo] name=Cloudera NavEncrypt enabled=1 autorefresh=0 gpgcheck=1 baseurl=file:///root/navencrypt-repo gpgkey=file:///root/navencrypt-repo/nepub.asc
  4. Install Kernel Libraries.

    For Navigator Encrypt to run as a kernel module, you must download and install the kernel development headers. Each kernel module is compiled specifically for the underlying kernel version. Running as a kernel module allows Navigator Encrypt to provide high performance and complete transparency to user-space applications.

    To determine your current kernel version, run uname -r.

    To install the development headers for your current kernel version, run:
    sudo yum install kernel-headers-$(uname -r) kernel-devel-$(uname -r)
  5. (RHEL or CentOS Only) Manually Install dkms.
    With some versions of RHEL7 and CentOS 7, because of a broken dependency, you must manually install the dkms package. To do this ,you must locate a repo that has a version of dkms that is compatible with the version of RHEL the host is running.
    sudo yum install https://download-ib01.fedoraproject.org/pub/epel/7/aarch64/Packages/d/dkms-2.7.1-1.el7.noarch.rpm
  6. yum install libkeytrustee
  7. yum install navencrypt-kernel-module
  8. Install Navigator Encrypt.
    Install the Navigator Encrypt client using the yum package manager:
    sudo yum install navencrypt
    If you attempt to install navencrypt-kernel-module with incorrect or missing kernel headers, you see a message like the following:
    Building navencryptfs 3.8.0 DKMS kernel module...
    
    #################### BUILDING ERROR ####################
    
    
    
    Creating symlink /var/lib/dkms/navencryptfs/3.8.0/source ->
                     /usr/src/navencryptfs-3.8.0
    
    DKMS: add completed.
    Error! echo
    Your kernel headers for kernel 3.10.0-229.4.2.el7.x86_64 cannot be found at
    /lib/modules/3.10.0-229.4.2.el7.x86_64/build or /lib/modules/3.10.0-229.4.2.el7.x86_64/source.
    
    #################### BUILDING ERROR ####################
    
    Failed installation of navencryptfs 3.8.0 DKMS kernel module !

    To recover, see Navigator Encrypt Kernel Module Setup.

  9. Confirm NavEncrypt is installed.
    yum list installed | egrep "naven|keytrust"

Installing Navigator Encrypt (SLES-12)

Learn how to install SLES 12 compatible Navigator Encrypt . The steps below show an example of installing SLES 12 compatible NavEncrypt, assuming the user is root.

  1. Install the NavEncrypt Repository.
    1. mkdir -p /root/navencrypt-repo
    2. Fetch the NavEncrypt repository from the Cloudera download site, for example: wget https://archive.cloudera.com/p/navencrypt7/7.1.9.1000/sles15/navigator-encrypt-7.1.9.1000_sles15.4-0.tar.gz
    3. tar -zxvf navigator-encrypt-7.1.9.1000_sles15.4-0.tar.gz --directory /root/navencrypt-repo
  2. Create and edit file /etc/zypp/repos.d/navencrypt.repo:
    [navencrypt-repo] name=Cloudera NavEncrypt enabled=1 autorefresh=0 gpgcheck=1 baseurl=file:///root/navencrypt-repo gpgkey=file:///root/navencrypt-repo/nepub.asc
  3. Confirm zypper can access repo.
    zypper search -r navencrypt-repo
  4. zypper install libkeytrustee
  5. Install the Kernel Module Package and Navigator Encrypt Client.

    Install the kernel module package (KMP) and Navigator Encrypt client with zypper:

    sudo zypper install cloudera-navencryptfs-kmp-default
    sudo zypper install navencrypt
  6. Confirm NavEncrypt is installed
    zypper search -i | egrep "naven|keytrust"
  7. systemctl daemon-reload

Installing Navigator Encrypt (SLES-15)

Learn how to install SLES 15 compatible Navigator Encrypt. The following steps show an example of installing SLES 15 compatible Navigator Encrypt, assuming the user is root.

  1. Install the Navigator Encrypt repository.
    1. Execute the following command:
      mkdir -p /root/navencrypt-repo
    2. Fetch the Navigator Encrypt repository from the Cloudera download site.
      For example,
      wget https://archive.cloudera.com/p/navencrypt7/7.1.9.1000/sles15/navigator-encrypt-7.1.9.1000-49-sles15.tar.gz
    3. Execute the following command:
      tar -zxvf navigator-encrypt-7.1.9.1000-49-sles15.tar.gz --directory /root/navencrypt-repo
  2. Create and edit the /etc/zypp/repos.d/navencrypt.repo file:
    [navencrypt-repo] name=Cloudera NavEncrypt enabled=1 autorefresh=0 gpgcheck=1 baseurl=file:///root/navencrypt-repo gpgkey=file:///root/navencrypt-repo/nepub.asc
  3. Confirm that Zypper can access the repository.
    zypper se -v  navencrypt libkeytrustee
            S  | Name                              | Type       | Version                      | Arch   | Repository
            ---+-----------------------------------+------------+------------------------------+--------+--------------------
               | cloudera-navencryptfs             | srcpackage | 7.1.9-0.0                    | noarch | Cloudera NavEncrypt
                name: cloudera-navencryptfs
            i+ | cloudera-navencryptfs-kmp-default | package    | 7.1.9_k5.14.21_150400.22-0.0 | x86_64 | Cloudera NavEncrypt
                name: cloudera-navencryptfs-kmp-default
             v  | cloudera-navencryptfs-kmp-default | package    | 7.1.9_k5.14.21_150500.53-0.0 | x86_64 | Cloudera NavEncrypt
                name: cloudera-navencryptfs-kmp-default
            i+ | libkeytrustee                     | package    | 7.1.9.1000_sles15.4-49       | x86_64 | Cloudera NavEncrypt
                name: libkeytrustee
            v  | libkeytrustee                     | package    | 7.1.9.1000_sles15.5-49       | x86_64 | Cloudera NavEncrypt
                name: libkeytrustee
            i+ | navencrypt                        | package    | 7.1.9.1000_sles15.4-49       | x86_64 | Cloudera NavEncrypt
                name: navencrypt
            v  | navencrypt                        | package    | 7.1.9.1000_sles15.5-49       | x86_64 | Cloudera NavEncrypt
                name: navencrypt

    You can see that the repository contains packages for SLES15-SP4 and SLES15-SP5.

  4. If you are running SLES15-SP4, install:
    • zypper in libkeytrustee-7.1.9.1000_sles15.4-49
    • zypper in cloudera-navencryptfs-kmp-default-7.1.9_k5.14.21_150400.22-0.0
    • zypper in navencrypt-7.1.9.1000_sles15.4-49
  5. Confirm that Navigator Encrypt SLES15.4 is installed:
    zypper se -v -i navencrypt libkeytrustee
    S  | Name                              | Type    | Version                      | Arch   | Repository
    ---+-----------------------------------+---------+------------------------------+--------+--------------------
    i+ | cloudera-navencryptfs-kmp-default | package | 7.1.9_k5.14.21_150400.22-0.0 | x86_64 | Cloudera NavEncrypt
        name: cloudera-navencryptfs-kmp-default
    i+ | libkeytrustee                     | package | 7.1.9.1000_sles15.4-49       | x86_64 | Cloudera NavEncrypt
        name: libkeytrustee
    i+ | navencrypt                        | package | 7.1.9.1000_sles15.4-49       | x86_64 | Cloudera NavEncrypt
        name: navencrypt
  6. If you are running SLES15-SP5, install:
    • zypper in libkeytrustee-7.1.9.1000_sles15.5-49

    • zypper in cloudera-navencryptfs-kmp-default-7.1.9_k5.14.21_150500.53-0.0

    • zypper in navencrypt-7.1.9.1000_sles15.5-49

  7. Confirm that Navigator Encrypt SLES15.5 is installed:
    zypper se -v -i navencrypt libkeytrustee
    S  | Name                              | Type    | Version                      | Arch   | Repository
    ---+-----------------------------------+---------+------------------------------+--------+--------------------
    i+ | cloudera-navencryptfs-kmp-default | package | 7.1.9_k5.14.21_150500.53-0.0 | x86_64 | Cloudera NavEncrypt
        name: cloudera-navencryptfs-kmp-default
    i+ | libkeytrustee                     | package | 7.1.9.1000_sles15.5-49       | x86_64 | Cloudera NavEncrypt
        name: libkeytrustee
    i+ | navencrypt                        | package | 7.1.9.1000_sles15.5-49       | x86_64 | Cloudera NavEncrypt
        name: navencrypt
  8. Reload the systemd files:
    systemctl daemon-reload

Installing Navigator Encrypt (Ubuntu)

Learn how to install Ubuntu compatible Navigator Encrypt . The steps below show an example of installing Ubuntu compatible NavEncrypt, assuming the user is root.

  1. Install the NavEncrypt Repository.
    1. mkdir -p /root/navencrypt-repo
    2. Fetch the NavEncrypt repository from the Cloudera download site, for example: wget https://archive.cloudera.com/p/navencrypt7/7.1.9.1000/ubuntu/navigator-encrypt-7.1.9.1000-61-ubuntu20.tar.gz
    3. tar -zxvf navigator-encrypt-7.1.9.1000-61-ubuntu20.tar.gz --directory /root/navencrypt-repo
    4. apt-key add /root/navencrypt-repo/nepub.asc
  2. Install Kernel Headers.
    Determine your kernel version by running uname -r, and install the appropriate headers:
    sudo apt-get install linux-headers-$(uname -r)
  3. apt-get install libkeytrustee4
  4. apt-get install navencrypt-kernel-module
  5. Install the Navigator Encrypt Client.
    Install Navigator Encrypt:
    sudo apt-get install navencrypt
  6. Confirm if NavEncrypt is installed.
    apt-cache search . | egrep "naven|keytrust" 

Installing for Ranger KMS

If you are using Ranger KMS as your Key Management server you need to do the following:

  1. Generate a valid Kerberos ticket.
    There is a utility called navencrypt-gen-keytab that works with Cloudera Manager to create a valid Kerberos ticket.
  2. Start the navencrypt-krb5 service after the keytab file is generated.

Setting Up TLS for Navigator Encrypt Clients

Transport Layer Security (TLS) certificates are used to secure communication with Navigator Encrypt. Cloudera strongly recommends using certificates signed by a trusted Certificate Authority (CA).

If the TLS certificate is signed by an unrecognized CA, such as an internal CA, then you must add the root certificate to the host certificate truststore of each Navigator Encrypt client. Be aware that Navigator Encrypt uses the operating system's truststore, which is distinct from the JDK truststore used by Cloudera Manager.

To set up TLS certificates on a Navigator Encrypt client:

  1. If not already installed, install the CA-certificates:
    yum install ca-certificates
  2. Enable the dynamic CA configuration feature:
    update-ca-trust enable
  3. Copy the root certificate into the host certificate truststore:
    cp /path/to/root.pem /etc/pki/ca-trust/source/anchors/
  4. Update the host certificate truststore:
    update-ca-trust
Example:
[root@navencrypt-1 ~]# systemctl stop navencrypt-mount
Stopping navencrypt directories
 * Umounting /dev/nvtest/test1 ...                         [  OK  ]
 * Umounting /dev/nvtest/test2 ...                         [  OK  ]
 * Unloading module ...                                    [  OK  ]

[root@navencrypt-1 ~]# update-ca-trust enable
[root@navencrypt-1 ~]# cp dd-1.lab.usa.company.com.pem /etc/pki/ca-trust/source/anchors/
[root@navencrypt-1 ~]# update-ca-trust

[root@navencrypt-1 ~]# systemctl stop navencrypt-mount
Starting navencrypt directories
 * Mounting '/dev/nvtest/test1'                            [  OK  ]
 * Mounting '/dev/nvtest/test2'   

Entropy Requirements

Many cryptographic operations, such as those used with TLS or HDFS encryption, require a sufficient level of system entropy to ensure randomness; likewise, Navigator Encrypt needs a source of random numbers to ensure good performance.

Hence, you need to make sure that the hosts running Navigator Encrypt (as well as Key Trustee Server, Key Trustee KMS) and have sufficient entropy to perform cryptographic operations.

You can check the available entropy on a Linux system by running the following command:

cat /proc/sys/kernel/random/entropy_avail             

The output displays the entropy currently available. Check the entropy several times to determine the state of the entropy pool on the system. On hosts running a Linux kernel version less than 5.10.119, if the entropy is consistently low (500 or less), you must increase it by installing rng-tools version 4 or higher, and starting the rngd service. On hosts running a Linux kernel version of 5.10.119 or higher the entropy version will be stable at 256, unless there are special entropy requirements in place, no further action is required.

Install rng_tools Using Package Manager

Learn how to install rng_tools using Package Manager.

If version 4 or higher of the rng-tools package is available from the local package manager (yum), then install it directly from the package manager. If the appropriate version of rng-tools is unavailable, see Building rng-tools From Source.

For RHEL 7, run the following commands:

sudo yum install rng-tools
cp /usr/lib/systemd/system/rngd.service /etc/systemd/system/
systemctl daemon-reload
systemctl start rngd
systemctl enable rngd

Building rng-tools From Source

If you are unable to install rng-tools using package manager, you can build from source.

To install and start rngd and build from source:

  1. Download the source code:
    sudo wget http://downloads.sourceforge.net/project/gkernel/rng-tools/4/rng-tools-4.tar.gz
  2. Extract the source code:
    tar xvfz rng-tools-4.tar.gz
  3. Enter the rng-tools-4 directory:
    cd rng-tools-4
  4. Run ./configure
  5. Run make
  6. Run make install
After you have installed rng-tools, start the rngd daemon by running the following command as root:
sudo rngd --no-tpm=1 -o /dev/random

For improved performance, Cloudera recommends configuring Navigator Encrypt to read directly from /dev/random instead of /dev/urandom.

To configure Navigator Encrypt to use /dev/random as an entropy source, add --use-random to the navencrypt-prepare command when you are setting up Navigator Encrypt.

Uninstalling and Reinstalling Navigator Encrypt

Learn how to uninstall and reinstall Navigator Encrypt.

Uninstalling Navigator Encrypt

For RHEL-compatible OSes:
sudo yum remove navencrypt
sudo yum remove navencrypt-kernel-module

These commands remove the software itself. On RHEL-compatible OSes, the /etc/navencrypt directory is not removed as part of the uninstallation. Remove it manually if required.

Reinstalling Navigator Encrypt

After uninstalling Navigator Encrypt, repeat the preceding installation instructions for your distribution.

When Navigator Encrypt is uninstalled, the configuration files and directories located in /etc/navencrypt are not removed. Consequently, you do not need to use the navencrypt register command during reinstallation. If you no longer require the previous installation configuration information in the directory /etc/navencrypt, you can remove its contents.