IBM Support

DAOS Notes Large Objects (NLO) Encryption

Technote (troubleshooting)


Problem

Errors result if you move NLO files from the originating server to another server and then attempt to read the data. NLO files are encrypted using the server.id file, and cannot be by read if they are moved from the original server.

Symptom

During attempts to access NLO data that was moved from the original server, the following error occurs: 0x171C "Specified private key does not exist"


Cause

The NLO data is encrypted with the server.id file of the originating server.

Resolving the problem

The following fixes are related to this issue:
PMAO9C6R9G - Adds validation capability for NLO files.
GFAL9AKKJZ - Builds on the code delivered in the preceding fix and adds encryption management.
PMAO9LM3E8 - Critical fix required for GFAL9AKKJZ. Do NOT use encryption management without applying this fix.


For PMAO9C6R9G:

1) To enable validation of NLO files, specify the value of the following notes.ini setting as indicated. After you change the value of the setting, a server restart is NOT required to put the change into effect.


    DAOS_RESYNC_VALIDATE_NLO_FILES
      Set the value to 1 to enable validation. The default is 0 (OFF).

2) After you enable the DAOS_RESYNC_VALIDATE_NLO_FILES setting, issue one of the following commands from the Domino console:
    • If the DAOS catalog is not already synchronized, use the command daosmgr resync
      For example, from the command line for your operating system, type daosmgr resync
      Or, from the Domino console, type tell daosmgr resync
    • If the DAOS catalog is already in a Synchronized state, use the command daosmgr resync force
      For example, from the command line for your operating system, type daosmgr resync force
      Or, from the Domino console, type tell daosmgr resync force

Messages are generated for any NLO that does not pass validation. The validation process attempts to read the NLO files and reports on any files that cannot be read. The process also checks for structural errors in the NLO file, and verifies that the NLO file either is unencrypted, or that it is encrypted and can be decrypted using the current server.id encryption key. The validation process is a read-only operation. No NLO data is modified during the process.

Messages are generated via xprintf to the console and via DAOS_LOGGING with the RESYNC keyword.
The best practice is to run the daosmgr resync command from the command line and redirect the messages from the standard output to a file.

When you enable DAOS_RESYNC_VALIDATE_NLO_FILES to validate NLO files, the performance of the resync operation becomes slower. To restore normal performance, remove this INI setting or change its value to 0 after you finish using it.

For GFAL9AKKJZ:

This fix adds support for the NLOENCRYPTION subcommand of the DAOS Manager command.

Syntax:

DAOSMGR NLOENCRYPTION [ENCRYPT | DECRYPT | VALIDATE] <path to single NLO file>|

You can specify the following actions for the NLOENCRYPTION subcommand:

    • VALIDATE- The VALIDATE option attempts to read the specified NLO files, and identifies any file that cannot be read. It checks for structural errors in the NLO file, and verifies that the NLO file is either unencrypted, or that it is encrypted and can be decrypted using the current server.id encryption key. The validation process is a read-only operation. No NLO data is modified during the process.
    • ENCRYPT - The ENCRYPT option attempts to encrypt the specified NLO files using the current server.id encryption key. Depending on the encryption status of the the NLO file, one of the following operations results:
      • If the NLO file is already encrypted with the current key, no action is taken.
      • If the NLO file is not encrypted, it is encrypted using the current key.
      • If the NLO file is encrypted with the alternate server.id key, it is re-encrypted using the current key.
    This operation modifies NLO files that are not encrypted in the way that you want.
    • DECRYPT - The DECRYPT option attempts to decrypt the specified NLO files using both the current server.id file key and the alternate server.id file key. If the NLO file is not encrypted, no action is taken. This operation writes the contents of the entire NLO header and data to a new file. It is not possible to perform an in-place update. This operation modifies NLO files that are not non-encrypted.

Usage:

1) Before you begin, verify that you have a current backup of all NLO data.

2) Set the following notes.ini values as appropriate. After you change the values of any of these settings, a server restart is NOT required to put the changes into effect.
    DAOS_ENCRYPTION_ALTERNATE_SERVER_ID
      Optional -Set this value to the full path and file name of an alternate server.id file to use if the current server.id file is unable to decrypt the original NLO files during decryption or encryption. This setting applies to encrypt or decrypt operations only; it is NOT used during validation. During validation operations, only the current server.id file is used.

      Limitation: This version doesn't allow use of a server id with password protection. As a workaround, decrypt them on the originating server before copying the NLO files to the destination server.

    DAOS_ENCRYPTION_REENCRYPT_IN_PLACE
      Optional - If an encryption update is required, by default, the re-encryption operation writes the data to a new NLO file with the new encryption. After the new file is created, it is swapped in for the original file, which is removed. This minimizes problems created by unexpected interruptions. This process requires writing the entire NLO header and data content to the new file.

      If the NLO file is already encrypted, the re-encryption can be attempted in-place on the existing NLO file. Because re-encrypting the file in-place requires rewriting the header of the NLO file only, the process consumes significantly less I/O than rewriting all of the data content. However, if the process is interrupted unexpectedly, for example, as the result of a power outage or disk error, there is some risk that damage can occur, because the live file is being updated.
      Under the default setting of 0, re-encryption does not occur in place. Set this variable to 1 to attempt re-encryption of NLO files without requiring a full rewrite of the data content.

      This setting applies only when changing the encryption on NLO files from an alternate server.id file to the current server.id file. Conversions that add encryption to non-encrypted NLO files, or remove encryption from encrypted NLO files are not eligible for the in-place operation. In cases where in-place re-encryption of the existing NLO file is not possible, the operation reverts to the default process of creating a new NLO file.
      3) Use one of the following three methods to specify the NLO files to process:
      • Use the command with the path to an IND file to process all of the files listed in the IND file.

        For example, from the command line for your operating system, type:

        daosmgr nloencryption encrypt c:\listnlo1.ind 

        Output:
        [0E50:0002-0B8C] mm/dd/yyyy 08:17:04 PM  DAOSMGR: DAOS Manager started
        [0E50:0002-0B8C] Starting to process ind file c:\listnlo1.ind...
        [0E50:0002-0B8C] Processing nlo file C:\DAOS\0001\9D853220DFDA8CDE67011718C46AD0A84355EB9F00200000.nlo - No error(err=0).
        Processing nlo file C:\DAOS\0001\832A828C8D102861ACD64D38F07F436FC21726E100200000.nlo - No error(err=0).
        Processing nlo file C:\DAOS\0001\775CFC7CFEB2DDA41F92C9D2359B05E9AD06C68400200000.nlo - No error(err=0).
        End of processing ind file c:\listnlo1.ind, total = 3, successful = 3.
        [0E50:0002-0B8C] mm/dd/yyyy 08:17:04 PM  DAOSMGR: DAOS Manager shutdown complete

      • Use the command with no arguments to process all of the NLO files in the DAOS catalog (daoscat.nsf). When you use the command with no arguments, daoscat.nsf is locked for an extended period of time and server performance can be slowed. The best practice is to use this method only for stand-alone operation, when there is no other traffic on the system.

        For example, from the command line for your operating system, type:

        daosmgr nloencryption encrypt

      • Use the command with the path to an NLO file to process a single NLO file.

        For example, from the command line for your operating system, type:

        daosmgr nloencryption encrypt c:\daos\0001\73564238A14ACBE6F3D28713A3228071C931E1C4001A0EA8.nlo

      Note: On UNIX installations, there is a known issue, MQRO9RVCJG - "loading libnotes.so error when running daosmgr from OS terminal". You need to make a sym link for "<Domino install directory>/bin/daosmgr -> tools/startup" as a work around. Alternatively, run the following command:

      load DAOSMGR NLOENCRYPTION [ENCRYPT | DECRYPT | VALIDATE] <path to single NLO file>|

Messages are generated via xprintf to the console and via DAOS_LOGGING with the RESYNC keyword.
The best practice is to run the daosmgr nloencryptioncommand from the command line and redirect the messages from the standard output to a file.

All encryption and decryption operations should be coordinated with the setting of DAOS_ENCRYPT_NLO. For example, if NLO encryption is enabled, and the NLOENCRYPTION command is used to decrypt all the NLO files, any new NLO files created after that time will still be created with encryption.

Related information

A simplified Chinese translation is available

Document information

More support for: IBM Domino
DAOS

Software version: 8.5.3, 8.5.3.1, 8.5.3.2, 8.5.3.3, 8.5.3.4, 8.5.3.5, 8.5.3.6, 9.0, 9.0.1, 9.0.1.1

Operating system(s): AIX, IBM i, Linux, Solaris, Windows, z/OS

Reference #: 1673931

Modified date: 04 June 2015