Rules

A rule determines which path (file or directory) of a client will be protected. Each rule can be linked to multiple clients using the rule identifier. An encryption key and an access policy group are needed during a client-rule association. The rule status and other parameters specific to a client-rule combination are present in the client-rule association.

Managing Rules

After a rule is created, it can be applied (linked) to a single or multiple clients. This linking is referred to as client-rule-association.

CTE UserSpace provides options to view existing rules, view and modify their details, and delete them. However, only the rules that are not linked to any client can be modified or deleted.

CTE UserSpace shows the progress of cryptographic operations being performed on a path under a rule. If a rule is applied on a directory path, the progress is shown in percent of the number of files completed. For example, a rule is deployed on a directory that contains 100 files. If a cryptographic operation is complete on 50 files, the operation progress is reported as 50%.

The progress reporting is applicable to rules in the In Progress state. Reason of failed rules is also displayed.

Creating a Rule

With CTE UserSpace, you can create rules for folders and files.

Creating Folder-based Rules

To create a folder-based rule:

1. Open the ProtectFile & Transparent Encryption UserSpace application.

2. In the left pane, click Rules. The Rules page shows the list of existing rules, if any.

3. Click New Rule. You might need to scroll down the page.

4. Specify a Rule Name. This field is optional. If not specified, the rule will be automatically named as Rule-XXXX, where XXXX is a random string of 27 characters.

5. Specify Path Type and Location:

   1. Select Folder.

   2. Specify the Path to Folder. Paths to encrypt or decrypt are referred to as encryption paths in this document.

6. Configure Options for Folder based paths:

   • Include sub-folders: Specify whether the rule will be applied recursively to the sub-folders and files.

     By default,the check box is selected. You can also specify the list of directories to be ignored (excluded) by the rule. Add such directories in the text box under the Include sub-folders check box. Refer to Ignoring Subdirectories for details.

     If you do not want to not apply the rule recursively, clear the Include sub-folders check box.

   • Encrypt Data: Specify that encryption will be performed on the specified path. By default, the check box is selected. Make sure this check box remains selected for CTE UserSpace.

     Note

     Do not clear the check box. CTE UserSpace does not support access control policies.

   • Skip Migration: Specify whether to skip existing encrypted files in a directory. When selected, the existing encrypted files are skipped during encryption, and no encryption rule is applied to them. After migration, new files created in or moved to the migrated directory are encrypted and protected with the applied access policy.

   • Optionally filter encryption for specific extensions, leaving both blank will encrypt all files in the specified path. The options are:

     • File Extensions to Include in Protection: Specify extensions of files to encrypt. This option is applicable if Encrypt Data is selected. You can add multiple extensions to the list.

     • File Extensions to Exclude from Protection: Not applicable to CTE UserSpace.

7. Click Submit.

The rule is created for the specified folder.

Creating File-based Rules

To create a file-based rule:

1. Open the ProtectFile & Transparent Encryption UserSpace application.

2. In the left pane, click Rules. The Rules page shows the list of existing rules, if any.

3. Click New Rule. You might need to scroll down the page.

4. Specify a Rule Name. This field is optional. If not specified, the rule will be automatically named as Rule-XXXX, where XXXX is a random string of 27 characters.

5. Specify Path Type and Location:

   1. Select File.

   2. Specify the Path to File. Paths to encrypt or decrypt are referred to as encryption paths in this document.

6. Make sure that the Encrypt Data check box is selected. Encryption will be performed on the specified path.

   Note

   Do not clear the check box. CTE UserSpace does not support access control policies.

7. Click Submit.

The rule is created for the specified file.

Viewing Rules

CTE UserSpace provides options to view existing rules and their details. Filter rules based on characters in name, path, rule type (all rules, encrypt only rules, or access enforcement only rules).

To view existing rules:

1. Open the ProtectFile & Transparent Encryption UserSpace application.

2. In the left pane, click Rules. The Rules page shows the list of existing rules. The page shows the following details:

   Column	Description
   Name	Name of the rule. If no name was specified at the rule creation, the rule is named as Rule-XXXX, where XXXX is a random string of 27 characters.
   Type	Whether the path is a directory or file.
   Path	Path of the directory or file to protect. Paths to encrypt or decrypt are referred to as encryption paths in this document.
   Encrypt	Whether the path is configured for encryption, Yes or No. CTE UserSpace does not support access control policies.
   Skip Migration	(Applicable to folder-based rules) Whether the existing encrypted files in a directory are skipped, Yes or No. Yes indicates that the existing encrypted files are skipped during encryption, and no encryption rule is applied to them. After migration, new files created in or moved to the migrated directory are encrypted and protected with the applied access policy.

Modifying Rules

After a rule is created, you can change it from folder-based to file-based, change the path, and other settings based on the path type. However, only the rules that are not linked to any client can be modified. Refer to Unbinding a Network Share from a Client for details.

To edit a rule:

1. Open the ProtectFile & Transparent Encryption UserSpace application.

2. In the left pane, click Rules. The Rules page shows the list of existing rules.

3. Under Name, click the rule to be modified.

   Alternatively, click the overflow icon () corresponding to the rule you want to modify and click Edit.

4. Modify the rule, as appropriate. Refer to Creating a Rule for details.

5. Click Submit.

The rule details are modified.

Deleting Rules

CTE UserSpace provides an option to delete rules. However, only the rules that are not linked to any client can be modified or deleted. Refer to Unbinding a Network Share from a Client for details.

To delete a rule:

1. Open the ProtectFile & Transparent Encryption UserSpace application.

2. In the left pane, click Rules. The Rules page shows the list of existing rules.

3. Under Name, click the overflow icon () corresponding to the rule you want to delete.

4. Click Delete. A dialog box is displayed prompting you to confirm the action. Deletion of a rule is permanent and cannot be undone.

5. Click Delete.

The rule is deleted.

Migration Process

Migration is the initial act of encrypting a file or directory. Once a file is migrated, it is encrypted and decrypted when accessed by authorized users. Use the CTE UserSpace GUI on the CipherTrust Manager to apply encryption policies to directories and files.

When applying encryption policies on local directories, CTE UserSpace performs move-based migration. CTE UserSpace supports migration of entire disks or specific directories.

Migrating Specific Directories

To migrate a specific directory on a mount, CTE UserSpace:

1. Creates a temporary directory (using unique rule GUID) in the directory to be migrated. For example, if /MigrateThisDir/ is to be migrated, a temporary directory /MigrateThisDir/{unique rule GUID} is created.

   Note

   When migrating a file, a temporary directory (using unique rule GUID) is created in the directory containing the file. For example, if a file, EncryptThisFile, is stored in the /UserData/ directory, then a temporary directory /UserData/{unique rule GUID} is created.

2. For every file in the directory to be migrated, CTE UserSpace checks for the required disk space to move the file to the temporary directory.

   • If move (rename) fails due to any reason, CTE UserSpace tries to copy the file into the temporary directory and then deletes it from the source path.

   • If the required disk space is unavailable, CTE UserSpace stops the migration process and logs warning in the log file, /var/log/safenet/PF/feadeflog.txt. The encryption status on the CipherTrust Manager becomes completed with errors. Create required space, and redeploy the policy.

3. If enough space is available, CTE UserSpace moves all files to the temporary directory.

4. Performs migration on the empty path.

5. Moves back the files, one by one, from the temporary directory to the protected directory.

The migration of the directory is completed and the encryption status on the CipherTrust Manager becomes Encrypted.

Migrating Entire Volumes

To migrate a full volume, CTE UserSpace:

1. Creates a temporary directory (using unique rule GUID) at /{unique rule GUID} on the same volume.

2. For every file in the volume to be migrated, CTE UserSpace checks for the required disk space on the volume to move the file to the temporary directory.

   • If move (rename) fails due to any reason (generally, Invalid cross-device link), CTE UserSpace tries to copy the file into the temporary directory and then deletes it from the source path.

   • If the required disk space is unavailable, CTE UserSpace stops the migration process and logs warning in the log file, /var/log/safenet/PF/feadeflog.txt. The encryption status on the CipherTrust Manager becomes completed with errors. Create required space, and redeploy the policy.

3. If enough space is available, CTE UserSpace moves all files to the temporary directory.

4. Performs migration on the empty path.

5. Moves back the files, one by one, from the temporary directory to the protected directory.

The migration of the volume is completed and the encryption status on the CipherTrust Manager becomes Encrypted.

Rule Operations

This section provides an overview of cryptographic operations supported by CTE UserSpace: encryption, key rotation, and decryption.

Only one operation can be initiated on a given path at a time. While that operation is in progress, no other operations can be started on that path. Another operation can be performed only after the completion of the previous operation.

Cryptographic operations involve encryption keys. These operations are encryption, key rotation, and decryption.

Encryption

Encryption is the process of encrypting data using an encryption key stored on the CipherTrust Manager. The encrypted data is decrypted when an authorized entity having appropriate access permission accesses the encrypted path.

Before Proceeding with Encryption

Coordinate with the CTE UserSpace client administrator to ensure the following before performing migration:

• Data to be encrypted is backed up.

• All database services are stopped before deploying an encryption rule on databases.

• All open instances of a file are closed before file-level migration.

• SELinux policies are applied before deploying encryption rules.

• No files, folders, or volumes in the targeted path are in use. To verify, check the output of the lsof or fuser command.

Encryption Rules

• Files in use are skipped by the migration process. CTE UserSpace attempts to access a file three times during the process. If the file is in use each time, the migration fails for that file. Migration of such files can be retried later when they are not in use.

• While encrypting a path containing multiple files, migration can fail. After failure in the first attempt, CTE UserSpace retries to deploy the rule two more times. If the issues are resolved before the third attempt, the rule is deployed successfully. As there is no rollback functionality, if the rule could not be deployed in maximum attempts, it is recommended to resolve the issues, and redeploy the rule.

• Open instances of the folder to be migrated must be refreshed after migration. Refreshing the instance is as simple as changing the folder.

• Protected files and folders must not be renamed or deleted.

  Note

  It is strongly recommended to not rename an encrypted path (including higher level folders). As the renamed path will be different from the path where the rule is applied on the CipherTrust Manager, all files in the renamed path will remain encrypted and cannot be decrypted.

• CTE UserSpace scans each file and determines whether it is already encrypted or not. If a file is already encrypted by CTE UserSpace, then CTE UserSpace skips the file to avoid double encryption.

• Individual files are migrated by moving them to a temporary directory and then copying them back to the encrypted directory (Refer to Migration Process for details.) Do not make any changes inside the temporary directory.

• Creating new files in a directory undergoing migration fails. New files can be created after the migration is complete. The directory's encryption rule applies to the new file.

Lazy Migration

CTE UserSpace prevents reencryption (double encryption) of encrypted files in a directory. Depending on the key used for encryption of files, the cases could be:

• The directory contains files encrypted with a key and plaintext files. If you encrypt the directory using the same key, CTE UserSpace ignores the encrypted files and encrypts the remaining files. The status becomes Encrypted on the CipherTrust Manager GUI.

• The directory contains files encrypted with some keys and plaintext files. If you encrypt the directory using a different key, CTE UserSpace ignores the encrypted files and encrypts the plaintext files. However, the status becomes Completed with Errors on the CipherTrust Manager GUI.

Directories Ignored by CTE UserSpace

CTE UserSpace does not encrypt the following directories:

This is because these directories contain files needed to start Linux OS and CTE UserSpace.

These directories (and their subdirectories) will not be encrypted, even if they are included in an encryption policy. The only exception is that subdirectories under the / path can be encrypted (but the actual / path cannot be encrypted).

Likewise, files in these directories will not be encrypted, even when specifically listed in an encryption policy. (For example, the kernel and boot loader files in /boot cannot be encrypted. Files in / cannot be encrypted.)

Key Rotation

Key rotation is the act of decrypting a file using the encryption key and then re-encrypting the file with a new encryption key. CTE UserSpace supports the following types of key rotation:

• Deep Key Rotation: The entire file (with content and header) is first decrypted with the old key and then re-encrypted with a new key. As a result, deep key rotation consumes time that is directly proportional to the file size.

• Shallow Key Rotation: Only the file header is first decrypted with the old key and then re-encrypted with a different key created on the CipherTrust Manager. As only the file header is re-encrypted, shallow key rotation is extremely fast and independent of the file size.

  Note

  CTE UserSpace supports versioned keys. Refer to Key Version Rotation for details.

An encrypted file that is restored from an archive cannot be decrypted in its original directory if the keys for that directory were rotated after the file was archived. The file must be moved into a directory with an encryption rule that uses the same key that was originally used to encrypt the file.

Before Proceeding with Key Rotation

Coordinate with the CTE UserSpace client administrator to ensure the following before performing key rotation:

• All database services are stopped before performing key rotation on databases.

• All open instances of a file are closed before file-level key rotation.

• No files, folders, or volumes in the targeted path are in use. To verify, check the output of the lsof or fuser command.

Encryption Rules

• A file undergoing key rotation cannot be accessed. It is recommended to not access files until their status becomes Encrypted on the CipherTrust Manager. Any attempt to access the file undergoing key rotation results in a permission denied error.

• Files in use are skipped by the key rotation process. CTE UserSpace attempts to access a file three times during the process. If the file is in use each time, the key rotation fails for that file. Retry the key rotation when the files are not in use.

• Creating new files in a directory undergoing key rotation fails. The newly added files are migrated with the key used for rotation. However, the file on which key rotation is in progress cannot be accessed.

Key Version Rotation

If you create a new version of a key that is used to encrypt a path, the file header is first decrypted with the old version and then re-encrypted with the new version. This is called key version rotation. This is similar to shallow key rotation using key versions.

If multiple key versions are created simultaneously, key version rotation is first performed using the next version, followed by the latest version. For example, if the current version is Version 0, and five new versions (say Version 1 through Version 5) are created simultaneously, then the first rotation is performed using the next version (that is, Version 1), and finally using the latest version, Version 5.

Before creating a new version of an encryption key, it is recommended to read the instructions provided in Before Proceeding with Key Rotation.

To rotate a key version:

1. Log on to the CipherTrust Manager GUI.

2. In the left pane, click Keys.

3. Search for the key used to encrypt the path.

4. Under Key Name, click the key. The mini detail view of the key is displayed.

5. Click + next to the Version drop-down list.

Key version rotation (shallow key rotation) is automatically initiated on the encrypted path using the new key version. The status of the encryption path changes from Encrypted to In Progress. After the operation is successful, the status changes from In Progress to Encrypted.

The current key version that is used to perform version rotation can be viewed in the details view of the key on the CipherTrust Manager's Keys page.

Decryption

Decryption is the act of permanently removing a rule from an encrypted path. After the rule is removed, the file returns to plaintext and is no longer encrypted or decrypted by CTE UserSpace.

Before Proceeding with Decryption

Coordinate with the CTE UserSpace client administrator to ensure the following before decrypting a path:

• All database services are stopped before deploying an encryption rule on databases.

• All open instances of a file are closed before file-level migration.

• No files, folders, or volumes in the targeted path are in use. To verify, check the output of the lsof or fuser command.

• Enough disk space is available on the client. Refer to the "Space Requirements" section in the CTE UserSpace Clients User's Guide.

Decryption Rules

• Files in use are skipped by the decryption process. CTE UserSpace attempts to access a file three times during the process. If the file is in use each time, decryption fails for that file. Retry decryption of such files when they are not in use.

• While decrypting a path containing multiple files, decryption can fail. After failure in the first attempt, CTE UserSpace retries to deploy the encryption rule two more times. If the issues are resolved before the third attempt, the rule is deployed successfully. As there is no rollback functionality, if the rule could not be deployed in three attempts, it is recommended to resolve the issues, and redeploy the rule.

• A file being decrypted cannot be accessed. It is recommended to not access files until they are removed from the CipherTrust Manager. Any attempt to access the file being decrypted results in a permission denied error.

• When a folder level encryption rule is in progress, do not perform the create file and copy file operations on this directory. New files can be created after the decryption is complete.

Ignoring Subdirectories

CTE UserSpace can skip cryptographic operations (encryption or decryption) recursively on specific subdirectories. This is applicable for encryption, key rotation, decryption, and file operations.

When creating a rule for a path, specify the subdirectory to skip in the text box (called "exclude" here) under the "Include sub-folders" check box and click Add to the left of the entry displayed below. To skip multiple subdirectories, add multiple directories to the "exclude" text box. CTE UserSpace skips all the files recursively inside the specified directory.

For example, ExcludeThisDir is specified in the "exclude" text box, and the rule is deployed on a path containing this directory. CTE UserSpace does not encrypt files recursively inside the ExcludeThisDir directory. However, CTE UserSpace encrypts all other directories on the encryption path.

Rules and Recommendations

• The "exclude" text box to specify exclude subdirectories is case-sensitive; for example, excludethisdir is different than ExcludeThisDir.

• Wildcard characters are not supported. CTE UserSpace only skips directories that exactly match the value specified in the "exclude" text box. For example, if ExcludeThisDir is specified, then files under the directories such as ExcludeThis and ThisDir are not excluded. Only files under the ExcludeThisDir directory are excluded.

• Rename in the following scenarios is not permitted for directories under the protected paths:

  • From directory name matching the excluded subdirectory to any other name.

  • From any other name to the excluded subdirectory.

• Parent folder encryption is not supported.

• Directories on NFS mounts can be skipped. CIFS is not supported.