Oracle Cloud Infrastructure Documentation

Using In-transit TLS Encryption

In-transit encryption using oci-fss-utils or stunnel provides a way to secure your data between instances and mounted file systems using TLS v.1.3 (Transport Layer Security) encryption. Together with other methods of security such as Oracle Cloud Infrastructure Vault and File Storage's encryption-at-rest, in-transit encryption provides for end-to-end security.

Tip

If you use Kerberos for authentication, the KRB5P security option provides authentication over NFS, data integrity (unauthorized modification of data in-transit), and data privacy as an alternative in-transit encryption option.

In-transit encryption using oci-fss-utils or stunnel doesn't require any updates to your file system's mount target or export configuration, but the steps differ for Linux users and Windows users.

Prerequisites

Add the required rules to the security list for the mount target subnet. Alternatively, you can add the following rules to a Network Security Group (NSG) and then add the mount target to the NSG. For more information and instructions about adding security list rules for File Storage, see Configuring VCN Security Rules for File Storage, in particular Scenario C: Mount target and instance use TLS in-transit encryption.

Important

Only the rules for TCP port 2051 are required for encrypted access.

In-transit Encryption for Linux Users

To enable in-transit encryption, you install a package called oci-fss-utils on the instance. The oci-fss-utils tool is available for the following instance types:

  • Oracle Linux, CentOS 7 x86
  • Oracle Linux, CentOS 8 x86
  • Oracle Linux, CentOS 9 x86
  • Oracle Linux, CentOS 7 Arm*
  • Oracle Linux, CentOS 8 Arm*
  • Oracle Linux, CentOS 9 Arm*

*Oracle offers an Arm-based compute platform based on the Ampere Altra processor. See Arm-Based Compute for more information.

How In-transit Encryption is Enabled

The oci-fss-utils package creates a network namespace and virtual network interface on your instance and provides a local NFS endpoint. The oci-fss-utils package also runs a forwarder process in the background called oci-fss-forwarder.

The network namespace isolates the forwarder process from the instance's networking environment. The virtual network interface provides the forwarder process a unique IP address. The local NFS endpoint provides NFS connection capability.

The file system is mounted using a special command that initiates encryption. After the file system is mounted, the oci-fss-forwarder process connects the local NFS client to the NFS endpoint. The process then receives requests from the NFS client, encrypts them and sends them to the mount target using a TLS tunnel.

Here are the general steps for setting up In-transit encryption:

  1. Ensure that you meet the prerequisites before setting up in-transit encryption.

  2. Install the oci-fss-utils package.

    1. If you're using Oracle Linux, see 1. Install the OCI-FSS-UTILS package.
    2. If you're using CentOS, see Manual and offline installation.
  3. Use the in-transit encryption command to mount the file system. For instructions, see 2. Mount the file system with the encryption command.

Limitations and Considerations

  • The in-transit encryption installation package is distributed as an RPM for Oracle Linux and CentOS. Oracle Linux users can install the package using yum. It can also be downloaded from the Oracle Linux yum Repository.
  • You must install the oci-fss-utils package on every instance that requires encrypted access to a mount target.
  • The number of encrypted NFS/TLS connections for a single mount target is limited to 4096.
  • DNS hostnames aren't supported for mounting encrypted file systems with oci-fss-forwarder. Use the mount target IP address to mount encrypted file systems.
Important

If you're not using the latest version of the oci-fss-utils package, you might experience SSL connection failures. SSL connection failures can cause NFSv3 operations to fail.

We recommend that you always upgrade to the latest version of the oci-fss-utils package as soon as it's available. See File Storage Release Notes for information about new RPM version releases.

Setting up In-transit Encryption for Linux

1. Install the OCI-FSS-UTILS package

Oracle Linux users can directly install the TLS utility from the Oracle Linux yum repository.

  1. Open a terminal window on the destination instance.

  2. Ensure that the Oracle developer yum repository is enabled for the version of Oracle Linux using the following command:

    sudo yum-config-manager --enable ol<oracle_linux_major_version>_developer

    Install the package using the following command: 

    sudo yum install oci-fss-utils

The package creates a namespace called ns1 in your instance, which contains a default network interface for ethernet traffic. A network interface pair is created for each mount target.

After the package has finished installing, proceed to 2. Mount the file system with the encryption command.

Manual and offline installation

Internet access is required to download the RPM installation package. If the destination instance doesn't have internet access, you can download the RPM to a staging instance on your network and then use the scp command to securely copy the RPM from the staging instance to the destination instance.

The scp command requires an SSH key pair to authenticate a remote user. If your instances are UNIX-style systems, you probably already have the ssh-keygen utility installed. To check if it's installed, open a shell or terminal and type ssh-keygen on the command line. If it's not installed, you can obtain OpenSSH for UNIX from http://www.openssh.com/portable.html.

  1. (Optional) Create a directory for the RPM installation package on the destination instance. For example: 

    sudo mkdir -p /<rpm_directory_name>

  2. Download the latest oci-fss-utils package from the Oracle Linux yum Repository to the directory on the destination instance or to a staging instance on your network.

    1. From the Oracle Linux yum Repository page, under Browse the Repositories, select an Oracle Linux version.
    2. Under Packages for Test and Development, find Developer Packages and then select the Linux architecture type, such as x86_64 or aarch64.

    3. Find and select the latest version of the oci-fss-utils package. For more information about the latest version, see File Storage Release Notes.

  3. If you downloaded the package to a staging instance, open a terminal window on the staging instance, and use the scp command to securely copy the RPM from the staging instance to the destination instance. For example:

    scp -i <private_key> <downloaded_file_name> <username>@<destination_public_ip_address>:/<rpm_directory_name>

    Skip this step if you downloaded the package directly to the destination instance.

  4. If the file name of the downloaded package doesn't include the package version and architecture, use the following command to identify the RPM file to be installed: 

    rpm -qp <downloaded_file_name>

    After the package is identified, rename the file using the RPM returned by the query. For example:

    mv <downloaded_file_name> $(rpm -qp <downloaded_file_name>).rpm

  5. Install the package using the following command:

    sudo yum localinstall oci-fss-utils-<version>.rpm

The package creates a namespace called ns1 in the instance, which contains a default network interface for ethernet traffic. A network interface pair is created for each mount target.

After the package has finished installing, proceed to 2. Mount the file system with the encryption command.

2. Mount the file system with the encryption command
  1. Open a terminal window in the instance.

  2. Create a mount point by typing the following, replacing yourmountpoint with the local directory from which you want to access the file system. 

    sudo mkdir -p /mnt/yourmountpoint

  3. Mount the file system using the following command: 

    sudo mount -t oci-fss 10.x.x.x:/fs-export-path /mnt/yourmountpoint

    Replace 10.x.x.x: with the local subnet IP address assigned to the mount target, fs-export-path with the export path you specified when associating the file system with the mount target, and yourmountpoint with the path to the local mount point. The export path is the path to the file system (relative to the mount target IP address).

    If you have installed oci-fss-utils version 2.0-1 or later, you can mount the file system in FIPS approved mode by including -o fips in the mount command. For example:
    sudo mount -t oci-fss -o fips 10.x.x.x:/fs-export-path /mnt/yourmountpoint
    Important

    DNS hostnames aren't supported for mounting file systems with the mount -t oci-fss command. You must use the mount target IP address.

    Each time you mount a file system using this command, systemd-managed service creates a new oci-fss-forwarder service with a name such as oci-fss-0<number>.service.

    Tip

    By default, the tool's NFS client uses reserved ports during mounting. Use the mount option noresvport if you need to use non-privileged ports.

Managing In-transit Encryption for Linux

Auto-mount a file system

Auto-mount ensures that a file system is automatically re-mounted on an instance if it is rebooted.

  1. Open a terminal window on the instance. Mount the file system as described in 2. Mount the file system with the encryption command.

  2. Open the /etc/fstab file for editing: 

    cd /etc
    vi fstab

  3. Add the following line to the fstab file: 

    10.x.x.x:/fs-export-path /mnt/yourmountpoint oci-fss x-systemd.requires=oci-fss-init.service,defaults,nofail 0 0

    Replace 10.x.x.x: with the local subnet IP address assigned to your mount target, fs-export-path with the export path you specified when associating the file system with the mount target, and yourmountpoint with the path to the local mount point.

    If you have installed oci-fss-utils version 2.0-1 or above, you can mount the file system in FIPS approved mode by including -o fips in the mount command. For example:
    10.x.x.x:/fs-export-path /mnt/yourmountpoint oci-fss x-systemd.requires=oci-fss-init.service,defaults,nofail,fips 0 0
    Important

    DNS hostnames aren't currently supported for mounting file systems with the mount -t oci-fss command. You must use the mount target IP address.
    Tip

    You can use the resvport option to restrict the client to using a specific reserved port. For example:

    10.x.x.x:/fs-export-path /mnt/yourmountpoint oci-fss x-systemd.requires=oci-fss-init.service,defaults,nofail,resvport=900 0 0
Unmount a file system

When you unmount a file system, you must use another oci-fss-utils command to ensure that the associated local network namespace is removed:

  1. Open a terminal window on the instance.

  2. Use the following command to unmount the file system:

    sudo umount -t oci-fss /mnt/yourmountpoint

    Replace yourmountpoint with the path to the local mount point.

Upgrade the OCI-FSS-UTILS package

If you're using a deprecated version of the oci-fss-utils utility, such as oci-fss-utils-3.x, or you want to take advantage of new features, you can upgrade to a newer version. You can find version information in the File Storage Release Notes.

When upgrading oci-fss-utils to a new version, any new settings, such as a new IP address or TLS forwarder process name, won't be applied until the file system is remounted.

Note

Remounting is required if you're upgrading the oci-fss-utils utility so that the TLS client can use an IPv6 address. Applications using the mounted file system will experience downtime while you remount the file system.
  1. Open a terminal window on the destination instance.

  2. Upgrade the package.

    1. Oracle Linux users can upgrade oci-fss-utils from the Oracle Linux yum repository. Ensure that the Oracle developer yum repository is enabled for the version of Oracle Linux using the following command:

      sudo yum-config-manager --enable ol<oracle_linux_major_version>_developer

      Then, upgrade the package using the following command:

      sudo yum update -y oci-fss-utils

    2. If you don't use Oracle Linux, download the latest oci-fss-utils package from the Oracle Linux yum repository. For instructions, see Manual and offline installation. Then, upgrade the package using the following command:

      sudo yum localinstall -y oci-fss-utils-<version>.rpm

  3. After upgrading, verify the version of oci-fss-utils using the following command:

    sudo rpm -qa | grep oci-fss-utils
  4. Unmount the file system and remount the file system so that new settings can take effect.
To uninstall the OCI-FSS-UTILS package
  1. First, unmount all mounted file systems. For instructions, see Unmount a file system.
  2. Open a terminal window on the instance.

  3. Type the following command to uninstall the oci-fss package:

    sudo yum remove oci-fss-utils

In-transit Encryption for Windows Users

Windows clients can use stunnel to enable in-transit encryption to file systems.

Limitations and Considerations

  • The number of encrypted NFS/TLS connections for a single mount target is limited to 64. This limitation is caused by TLS memory requirements. Unlike NFS connections, TLS connections do not share memory buffers. So, once a TLS connection has been established, the allocated memory stays dedicated to it.
  • DNS hostnames are not supported for mounting encrypted file systems. Use the mount target IP address to mount encrypted file systems.

Setting up In-transit Encryption for Windows

These instructions describe how to install and set up stunnel to use in-transit encryption with your file systems. Ensure that you meet the prerequisites before setting up in-transit encryption.

Tip

You can automate this process by using a batch script that contains the following steps.

Setup Tasks

Task 1: Install the Windows NFS Client

  1. Open Windows PowerShell on your target instance and use the following command to install the Windows NFS Client:

    Install-WindowsFeature NFS-Client

    After the client is installed, proceed to Task 2: Download and Install stunnel.

Task 2: Download and Install stunnel

  1. Download and install stunnel from https://www.stunnel.org/downloads.html.

    Note

    The last installation step requests certificate information. Entering a value here is optional.

    By default, stunnel is installed to the following directory: C:\Program Files (x86)\stunnel

  2. Open the file C:\Program Files (x86)\stunnel\config\stunnel.cfg for editing and specify the following configuration:

    [mount]
    client=yes
    accept=127.0.0.1:2048
    connect=10.0.1.155:2051
 
[nfs]
    client=yes
    accept=127.0.0.1:2049
    connect=10.0.1.155:2051
 
[nlm]
    client=yes
    accept=127.0.0.1:2050
    connect=10.0.1.155:2051
 
[rpcbind]
    client=yes
    accept=127.0.0.1:111
    connect=10.0.1.155:2051

  3. Start stunnel using C:\Program Files (x86)\stunnel\bin\tstunnel.exe.

    Proceed to Task 3: Mount and Test Your Connection.

Task 3: Mount and Test Your Connection

Open a command prompt and type the following series of commands:

  1. Mount the file system:

    mount \\127.0.0.1\fss z:

  2. Test the connection to the file system by listing the contents of the directory:

    dir z:

  3. Unmount the file system:

    umount z: