Client cooperation

You can allow an nShield HSM to automatically access the remote file system (RFS) belonging to another nShield HSM and share the Security World and key data stored in the Key Management Data directory. Client hardware security modules that access data in this way are described as cooperating clients.

Configure client cooperation

To configure client cooperation for other clients or hardware security modules that are not nShield HSMs:

  1. Configure the RFS, or the RFS used by your nShield HSM, to accept access by cooperating clients:

    • For every authenticated client (with write access and KNETI authorization) that needs to be a client of this remote file system, run the command:

      rfs-setup --gang-client <client_IP_address> <EEEE-SSSS-NNNN> <keyhash>

      In this command:

      • <client_IP_address> is the IP address of the client. This can be an IPv4 or IPv6 address.

      • <EEEE-SSSS-NNNN> is the ESN of the nToken used by the client when using a nToken KNETI key to authenticate itself. When using software-based authentication, it must be empty (that, is "") or can be omitted altogether.

      • <keyhash> is the hash of the software or module KNETI key used by the client.

    • For every unauthenticated client (with write access but without KNETI authorization), run the command:

      Linux
      rfs-setup --gang-client --write-noauth <client_IP_address>
      Windows
      rfs-setup.exe --gang-client --write-noauth <client_IP_address>
      The --write-noauth option should be used only if you believe your network is secure. This option allows the client you are configuring to access the RFS without KNETI authorization.

      To limit a gang-client to read-only, use the --readonly flag.

  2. On each client that is to be a cooperating client, you must run the rfs-sync command-line utility with appropriate options:

    • for clients using a software KNETI key to authenticate themselves to the RFS, run the command with the default options:

      rfs-sync --setup <RFS_IP_ADDRESS>

    • for clients using a module KNETI key to authenticate themselves to the RFS, run the command:

      rfs-sync --setup --authenticate --module=<MODULE> <RFS_IP_ADDRESS>

      In this command:

      • <RFS_IP_ADDRESS> is the IP address of the RFS.

      • <MODULE> is the local module to use for authentication.

    • for clients to authenticate the RFS using software-based authentication, use the --rfs-hkneti=HKNETI option to specify the hash of the software KNETI key of the RFS.

    • for clients to authenticate the RFS using nToken authentication, use the --rfs-esn=ESN and --rfs-hkneti=HKNETI options to specify the ESN and hash of the KNETI key of the nToken installed in the RFS.

The rfs-sync utility uses lock files to ensure that updates are made in a consistent fashion. If an rfs-sync --commit operation (the operation that writes data to the remote file system) fails due to a crash or other problem, it is possible for a lock file to be left behind. This would cause all subsequent operations to fail with a lock time-out error.

The rfs-sync utility has options for querying the current state of the lock file, and for deleting the lock file; however, we recommend that you do not use these options unless they are necessary to resolve this problem. Clients without write access cannot delete the lock file.

For more information about the rfs-sync utility, see rfs-sync

Remove a cooperating client

To remove a cooperating client so the RFS no longer recognizes it, you must:

  • Know the IP address of the cooperating client that you want to remove

  • Manually update the remote_file_system section of the hardserver configuration file by removing the following entries for that particular client:

    Linux
    remote_ip=<client_IP_address>
remote_esn=keyhash=0000000000000000000000000000000000000000
native_path=/opt/nfast/kmdata/local
volume=kmdata-local
allow_read=yes
allow_write=yes
allow_list=yes
is_directory=yes
is_text=no

    and

    remote_ip=<client_IP_address>
remote_esn=keyhash=0000000000000000000000000000000000000000
native_path=/opt/nfast/kmdata/local/sync-store/
volume=kmdata-backup
allow_read=yes
allow_write=yes
allow_list=yes
is_directory=yes
is_text=no
    Windows
    remote_ip=client_IP_address
remote_esn=keyhash=0000000000000000000000000000000000000000
native_path=%NFAST_KMDATA%\local
volume=kmdata-local
allow_read=yes
allow_write=yes
allow_list=yes
is_directory=yes
is_text=no

    and

    remote_ip=client_IP_address
remote_esn=keyhash=0000000000000000000000000000000000000000
native_path=%NFAST_KMDATA%\local\sync-store
volume=kmdata-backup
allow_read=yes
allow_write=yes
allow_list=yes
is_directory=yes
is_text=no