Usage Notes and Limitations for Configuring Exclusion Key Rules

Keep in mind the information in the following sections when configuring an exclusion key rule.

Adding an Exclusion Key Rule to an Existing Policy with Versioned Keys (Linux)

When adding an exclusion key rule to an existing policy, the exclusion rule only applies to newly created files. Existing files that match the exclusion key rule remain encrypted with the same versioned key(s) specified in the non-exclusion key rule in the policy and will be rekeyed to the key in the exclusion key rule when the versioned key(s) rotates.

To force an existing file that matches an exclusion key rule to be transformed to the key in the exclusion key rule (non-versioned in this example), use one of the following methods:

• Rotate the versioned key specified in the policy to initiate rekey operations on the GuardPoint.

• Copy the existing file within the GuardPoint. The new file will be associated with the resource set in the exclusion key rule and will be encrypted with the non-versioned key. You can then delete the original file.

To perform a similar conversion on Windows, see Changing a Folder or Files from Versioned to Non-Versioned Key (Windows).

Adding an Exclusion Key Rule for LDT over NFS

For an LDT over NFS GuardPoint with exclusion rules, all files, including excluded files, can only be read in clear when the GuardPoint is enabled. Excluded files on an LDT over NFS GuardPoint will not be readable when the GuardPoint is unguarded/disabled.

Adding an Exclusion Key Rule That is Part of an Active GuardPoint (Linux)

To edit and/or add an exclusion key rule to an LDT policy, all GuardPoints using the policy must first be disabled before the new key rule can be added.

Changing an Exclusion Key Rule That is Part of an Active GuardPoint (Windows)

Changes that you make to an exclusion key rule that is part of an existing policy in an active GuardPoint do not take effect until the GuardPoint that the exclusion key rule is part of is disabled and enabled again.

Conflicting Keys as the Result of Rename Operations

Do not attempt to move or rename a file encrypted with a versioned key to a name associated with an exclusion key rule with clear_key. If you attempt such a move or rename, the original file is unaffected but following error is output on Linux systems and a log entry is created:

<command name>: setting attribute ‘user.::secfs:xattr:’ for ‘user.::secfs:xattr:’: Invalid argument
<command name>: failed to close ‘<filename>’: Invalid argument

No error is displayed on Windows systems. The target moved or renamed file is corrupted and should be deleted. The target file is also flagged with the xattr_error flag on Linux and Rekey Status Excluded on Windows. This flag prevents subsequent read/write access to the file. You can check the LDT attributes for the presence of this flag. See About the Exclusion Attribute for Files Matching an Exclusion Key Rule.

Also, a log entry is sent to the CipherTrust Manager on Linux systems when this occurs. For example, if you moved the versioned file /gp/foo.txt into the GuardPoint /gp/subdir/foo.txt with an exclusion key rule that excludes matching files with the clear_key, the following log message would be created on the CipherTrust Manager:

[CGA] [WARN ] [29261] [CGS3268W] LDT-ALERT: encrypted data detected in filename [foo.txt] inode [35720037] in guard point [/gp] under clear exclusion key rule

Overlapping Exclusion Key Rules

Multiple exclusion key rules in the same policy may overlap each other. For example on Linux, if the non-versioned key Key_A is associated with resource /oxf-fs1/gp1/Folder_Enc_With_KEY_A and the non-versioned key Key_B is associated with resource *.txt, placement of the file /oxf-fs1/gp/Folder_Enc_With_KEY_A/foo.txt overlaps the two key rules. In such a case, the first rule in the policy is enforced on /oxf-fs1/gp/Folder_Enc_With_KEY_A/foo.txt when the file is created and in subsequent file access.

On Windows, if the non-versioned key Key_A is associated with resource c:\oxf-fs1\gp1\Folder_Enc_With_KEY_A and the non-versioned key Key_B is associated with resource *.txt, then they would overlap on the file c:\oxf-fs1\gp\Folder_Enc_With_KEY_A\foo.txt. In such a case, the first rule in the policy is enforced on c:\oxf-fs1\gp\Folder_Enc_With_KEY_A\foo.txt when the file is created and in subsequent file access.

Application of Exclusion Key Rules on GuardPoint over NFS

When protecting files using an Exclusion Key Rule with clear_key in local file systems, files can be accessed in clear even if the GuardPoint is not enabled. Clear access is possible because data is not encrypted in such files and the LDT metadata is managed as part of the secfs extended attribute for such files. Clear access is not possible for such files in a GuardPoint over NFS because LDT metadata is part of the secfs extended attribute that is stored in the first 4096 bytes of each file. CTE skips the embedded secfs header when reading or writing such files when a GuardPoint is enabled. With a GuardPoint disabled, access to files is not through CTE and reading or writing files in a GuardPoint will not skip the embedded secfs attribute.

Caution About Applications That Create Temporary Files (Windows)

Some applications on Windows create a temporary file version of the original file when you open and modify a file. This behavior can affect how you implement exclusion key rules.

If you have an exclusion key rule that uses a file extension to exclude files that may be opened and modified by such an application, exclude the temporary file name extension also. If you don’t exclude the temporary file, the temporary file may be encrypted by another policy that matches the temporary file extension. Then the original file, which is copied from the temporary file, will be unreadable. Also keep in mind that other applications that may create temporary files with the same file extension and consider what policies should affect those temporary files.

This situation can happen with Microsoft Office files such as the .docx files used by Microsoft Word. When you open and modify a .docx file, Word creates a .tmp file version of that file. So for Microsoft Word you should add *.tmp to the exclusion key rule resource set if you add *.docx.

Rename Operations Crossing Key Rules (Linux)

On Linux, when a rename operation crosses key rules, the rename operation copies the source file to a new file using the new name and removes the original file. If the source file is flagged for exclusion key rule property, the target new file is disassociated with the exclusion key rule if the new name no longer matches the resource set associated with exclusion key rule. For more information, see About the Exclusion Attribute for Files Matching an Exclusion Key Rule.

Using Linked Files with Exclusion Key Rules (Linux)

On Linux, do not create multiple hard links to the same target file, such that the pathname of each hard link is associated with a resource set of an exclusion key, and the key rules have different keys. Accessing the file through the pathname of each hard link results in a different key being applied to the file, resulting in data corruption in the target file due to the application of multiple keys to the same data.

If you must create hard links, be sure the hard link pathnames and the target file are within the same resource set.

Changing a Folder or Files from Versioned to Non-Versioned Key (Windows)

Exclusion key rules provide a way to convert a subset of guarded files or the contents of a folder from being encrypted by a versioned key to being encrypted by a non-versioned key. After this conversion, the excluded files or directory contents will be encrypted at the last version of the versioned key but the encryption keys for those items will not rotate to a new version when the keys for other non-excluded files are rotated. In other words, the excluded files or folder contents will be encrypted by a non-versioned key.

Follow these steps to change selected files or folder contents to a non-versioned key:

1. In the CipherTrust Manager, clone the versioned key that is used in the policy that you plan to edit. Cloning a key creates a non-versioned copy of the existing version of the versioned key.

2. In the CipherTrust Manager, disable the GuardPoint. Disabling the GuardPoint is required before modifying a policy applied in that GuardPoint.

3. Configure one or more resource sets to match the files that you want to exclude. For example, the resource set star-dot-text could contain *.txt and the resource set sales-folder could contain \sales\*.

4. Add one or more exclusion key rules to convert matching files to a non-versioned key. In the following example, files matching *.txt and files in the sales folder (as defined in resource sets) will be converted from the current version of the versioned key AES256_versioned to AES256_clone, assuming AES256_clone is a clone of AES256_versioned.

   Order	Resource	Current Key	Transformation Key	Exclusion Rule
   1	star-dot-txt	AES256_clone	AES256_clone	Y
   2	sales-folder	AES256_clone	AES256_clone	Y
   3		clear_key	AES256_versioned	N

   Exclusion key rules must be ordered before other rules.

5. On the command line, run the following command to remove the LDT metadata from the files that you want to convert from versioned key to non-versioned key encryption:

   voradmin ldt attr delete <path_to_files>
   

   To recursively delete the LDT metadata from all files matching a pattern in all subfolders, use the following form, including * as a wildcard where needed:

   voradmin ldt attr delete <path_to_files> -filter <filename>.<extension>
   

   Note

   Be careful when deleting the LDT metadata from files. If you delete the metadata from a file that does not match an exclusion key rule policy, the file will be unreadable after the next rekey.

   Given the example exclusion key rule described in step 4, you would need to run this command on all files with the extension .txt (first example below) and on the files in \sales (second example below).

   voradmin ldt attr delete c:\gp1 -filter *.txt
   voradmin ldt attr delete c:\gp1\sales
   

   For more information about using voradmin on LDT metadata, run voradmin ldt attr /? on the command line.

6. In the CipherTrust Manager, re-enable the GuardPoint that includes the new exclusion key rule.

7. In the CipherTrust Manager, rotate the key for the policy that includes the new exclusion key rule.

Using the example exclusion key rule in step 4, after completing this procedure, files matching *.txt and files in the sales folder will have the exclusion attribute set and will be excluded from rekeying (see About the Exclusion Attribute for Files Matching an Exclusion Key Rule). Files not matching the exclusion key rule will be rekeyed to the next version of the AES256_versioned key.

To perform a similar conversion on Linux, see Adding an Exclusion Key Rule to an Existing Policy with Versioned Keys (Linux).