Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

back

Migrating ProtectFile to CTE Agent

Configuration Elements used by ProtectFile

search

Please Note:

Configuration Elements used by ProtectFile

Production Policies

In this section we describe all of the configuration elements on CM used by ProtectFile and how they would be mapped to their equivalent configuration elements for CTE.

Policies

To migrate ProtectFile data, you will use two different policies:

  • Data Transform Policy

  • Production Policy

Keys

ProtectFile uses AES-256 keys only. The pfmigrate utility creates the required CTE keys as AES-256 with CBC encryption mode. 

The pfmigrate utility creates new keys and renames them with a CTE prefix.

Example:

  • ProtectFile Key name: ClassicKSPFKey1

  • CTE Key name: cte_ClassicKSPFKey1

Client Mapping

The CTE configuration elements consist of the client names and their properties. Navigating to the CTE section on CM presents the list of clients and their properties.Use the following table to map the properties of the ProtectFile clients to CTE clients:

ProtectFile ClientsCTE ClientsNote
Client nameClient name
IP or host nameN/ACTE uses only the client names
OS TypeOS TypePopulated during registration
N/AKernel VersionPopulated during registration
Client ProfileClient Profile
UpdatedN/ALast synchronize time with the client
N/AStatusHealth status

The CTE clients section in the CM shows the client entries as in the screenshot below:

Client Entries

Network Shares

ProtectFile configures network shares explicitly and allows their grouping in network share profiles. You can apply encryption rules at the share level. All participating clients are added to the same network share profile.

CTE defines encryption policies, on network share, from within the client. All participating clients are configured in client groups. The pfmigrate utility migrates all of the participating clients from a ProtectFile network share profile and creates a CTE client group for them.

Clusters

ProtectFile configures clusters explicitly in its own section on CM. Encryption policies can be applied at the cluster level.

To access the Cluster section:

  1. From the products page, click ProtectFile and Transparent Encryption Userspace.

  2. Click Clusters in the navigation panel.

Client Profiles

Client profiles are used to group common configuration values for multiple clients in both ProtectFile and CTE. However ProtectFile client profiles are different from CTE client profiles, and the pfmigrate utility does not migrate them. We do not describe their mapping here, however, for ProtectFile Linux clients, if their associated client profile has the enable su property set, enable the CTE su_root_no_auth authenticator in the client settings on the CTE client.

Access Policies and Groups

In this section, we discuss the mapping of ProtectFile access policies to CTE policies.

  • An access policy in ProtectFile consists of a user/group/process and the access allowed to it.

  • An access policy group in ProtectFile is composed of one or more access policies. An access policy group is migrated to a CTE Standard Policy using the pfmigrate utility.

  • A CTE standard policy consists of one or more security rules, key rules and data transformation rules (for offline policies).

  • A CTE security rule describes actions and effects for a specific resource set, user set, process set and time set, basically performing what-who-how-when security operations.

  • A resource in a resource set is a file, a file extension, or sub-folder relative to the GuardPoint.

  • A user in a user set can be defined as a user or a user group.

  • A key selection rule consists of a key and optionally a resource set on which the key operates.

  • The data transformation rules section is available only if the policy is for data transformation, which is defined by having a key_op action and an Apply Key and Permit effects in the first security rule.

  • The table below describes how the elements of a ProtectFile access policy group are migrated to CTE. The pfmigrate utility does this migration for you.

Access Policies Mapping

ProtectFile Access PoliciesCTENote
AccessSee the next table
Name Name
User nameUser Set
User group name User Set
Process nameProcess Set
FingerprintSignature SetThe signature set is not migrated by the pfmigrate utility. It must be created manually.

In CTE, the access rules are a combination Action and Effects. The following table shows the mapping from ProtectFile access to CTE as performed by the pfmigrate utility.

Access Rules

ProtectFile AccessCTE ActionCTE Effects
ReadWriteall_opsPermit, Apply Key
Writef_wrPermit, Apply Key
Readf_rdPermit, Apply Key
ReadWriteCipherall_opsPermit
ReadCipherf_rdPermit
NoAccessall_opsDeny

ProtectFile Encryption Rules

An Encryption rule in ProtectFile is a tuple consisting of a path, a key and an access policy group. Additional rule attributes are available (listed below) to fine tune the encryption rule.

The CTE equivalent is a GuardPoint. Each GuardPoint consists of a policy (as described in the previous section), a guard type, a guard path, and additional GuardPoint attributes.

For every ProtectFile encryption rule, two CTE GuardPoints are created:

  • One for data transformation

  • One for applying the production policy

Following are the properties of CTE GuardPoints:

  • CTE guard path must be a directory path.

  • CTE Guard Types can be one of the following:

    • Directory (Auto Guard)

    • Directory (Manual Guard)

    • Raw or Block Device (Auto Guard)

    • Raw or Block Device (Manual Guard)

    For migration, only use the Directory(Auto Guard) type.

  • A CTE GuardPoint must be associated with a policy as described above.

  • Regardless of the encryption approach used in the ProtectFile encryption rule, the CTE GuardPoint must be configured with offline data transformation.

The following table depicts how the ProtectFile encryption rule properties are mapped to CTE GuardPoints by the pfmigrate utility.

Encryption Rules Mapping

ProtectFile Encryption RulesCTE GuardPointsNote
Rule name (optional)N/A
FolderFolderThe guard type is directory(auto guard).

ProtectFile encryption rules can use attributes for fine tuning. The following sections describe how they would be mapped to CTE GuardPoint properties by the pfmigrate utility.

Only the specific rule being migrated goes offline while being migrated. All other rules are available.

File Level Rules

A ProtectFile encryption can be applied on an individual file. To achieve the same in CTE, create a resource set with the file name to be encrypted relative to the GuardPoint. This resource set is used n the security rule of the policy with the apply_key effect enabled. The following screenshot provides an example of the resource set:

File Level Rules

Non Recursive Rules

A ProtectFile encryption rule can be applied to a folder non recursively. To achieve the same in CTE, create a resource set with the ‘Include Subfolders’ property unchecked. This resource set is used in the security rule of the policy with the apply_key effect enabled. The following screenshot provides an example of the resource set:

Non-recursive Rules

Include File Extension

A ProtectFile encryption rule can be applied only to selected file extensions. To achieve the same in CTE, create a resource set with the *.ext in the File property, where ext is the extension. This resource set is used in the security rule of the policy with the apply_key effect enabled. The following screenshot provides an example:

File Extensions

Exclude File Extension

A ProtectFile encryption rule can exclude specific file extensions. To achieve the same in CTE, create a resource set with *.ext in the File property, where ext is the extension. This resource set is then applied to the Key Rules of the policy, with the key set to clear_key. The following screenshot provides an example of the resource set.

Exclude Extensions

Access Only

An encryption rule in ProtectFile can bypass encryption and only enforce access. To achieve this in CTE, the GuardPoint policy cannot have a key rule. Choose the following:

Action: all_ops

Effect: permit, audit

Resources Names Conversion During Migration of PF Configuration to CTE Configuration

PF ResourceCTE Resource typeMigrated resource naming convention
Access Policy Access policy becomes UserSet or ProcessSet depending upon the type of PF access policy:
  • User-based becomes UserSet
  • Process-based becomes ProcessSet
<pf_access_policy_name>
<pf_access_policy_name>
Access Policy Group

Access policy group becomes two CTE policies: one for initial data transformation and the other for production:

  • Data transformation policy starts with ‘transform_’
  • Production policy has the same name as the transform policy, except that it does not start with ‘transform_’

Data transformation policy is for the initial migration of PF encrypted data to CTE encryption format. Once data is migrated, Production policy must be applied.

transform_<pf_rule_name>
_<pf_access_policy_group_name>
_cte<pf_key_name>
<pf_rule_name>
_<pf_access_policy_group_name>
_cte<pf_key_name>

Client

CTE Client

<pf_client_name>

Client ProfilesCTE has profiles similar to PFPFMigrate utility is not migrating profiles. You MUST create CTE profiles manually.
ClustersClientGroup<pf_cluster_name>
Encryption Rules

GuardPoints

Guard points are created corresponding to all PF encryption rules.

GuardPoints are associated with CTE clients. Verify these GuardPoints.

Resource Set

Resource sets are conditionally created only if PF encryption rules have additional qualifiers to identify files.

 

For example, include or exclude extensions or folders, non-recursive rules etc. In general, if rules do not have qualifiers, then only GuardPoints are created.

Resource set (if created)

For Local rule:

<pf_client_name>_<pf_rule_name>


For NAS share rule:

<pf_share_name>_<pf_rule_name>


For Cluster rule:

<pf_cluster_name>_<pf_rule_name>

KeyCTE Keycte_<pf_key_name>
NAS ShareClientGroup

Client

CTE Client

<pf_client_name>

Client ProfilesCTE has profiles similar to PFPFMigrate utility is not migrating profiles. You MUST create CTE profiles manually.
ClustersClientGroup<pf_cluster_name>
Encryption Rules

GuardPoints

Guard points are created corresponding to all PF encryption rules.

GuardPoints are associated with CTE clients. Verify these GuardPoints.

Resource Set

Resource sets are conditionally created only if PF encryption rules have additional qualifiers to identify files.

 

For example, include or exclude extensions or folders, non-recursive rules etc. In general, if rules do not have qualifiers, then only GuardPoints are created.

Resource set (if created)

For Local rule:

<pf_client_name>_<pf_rule_name>


For NAS share rule:

<pf_share_name>_<pf_rule_name>


For Cluster rule:

<pf_cluster_name>_<pf_rule_name>

KeyCTE Keycte_<pf_key_name>
NAS ShareClientGroup<pf_share_name>

Caveats for Naming

CM/PF name constraints are different from CM/CTE constraints. The pfmigrate utility takes proactive actions while creating corresponding names for the CM/CTE migration.

Client/Host Names

CM/CTE uses the same name as the PF names for all cases, except when the name contains special characters.

CTE Client/Host names can begin with an alphabetic or a numeric character. It can include a period or a colon. Additionally, use only lower case letters for client names.

Acceptable Characters

Numbers, period, underscore, colon. For example:

  • myserver_1.1.1.1

  • 1.1.1.1_myserver

  • pfserver

  • testserver_1

  • server_a.b.com

  • pfserver:north_wing

Unacceptable Characters

Names with spaces are not allowed.

PF NameCTE Migrated Name
my pfserverpf_modified_my_pfserver

User Set, Process Set, and Resource Set Names

Only alphanumeric and underscore allowed. All other characters are considered special characters, including a period.

PF NameCTE Migrated NameReason
User set namePF_Modified_User_set_namespaces
Process.setPF_Modified_process_setperiod
1ResourcesetPF_Modified_1resourcesetstarted with a number
Resource=setPF_Modified_resource_setspecial char
MyUser_1MyUser_1no change needed
ProcessSetProcessSetno change needed

Conflicting Converted Names

If CM contains conflicting converted names, then the pfmigrate utility appends the “_count” string.

PF NameCTE Migrated Name
resource=setPF_Modified_resource_set
resource@setPF_Modified_resource_set _1
resource#setPF_Modified_resource_set_2

All of the names are modified to PF_Modified_resource_set. They are appended with ’_n’ (where ‘_n’ is a sequential number) to differentiate them from a previous name.

Known Issues

Issue ID Issue Description Workaround
AGT-31680 Getting permission denied error on path after PF to CTE migration completed in same shell.
  1. Create a new session.
  2. Exiting or log in as root user.
  3. Open a new tab.

KY-26923

DFS replication not working after PF to CTE migration using pfmigrate utility.

Manually add additional GuardPoints for Replication endpoint, i.e. DfsPrivate folder.

Troubleshooting

Data Transformation

If the following events occur while dataxform is running, restart dataxform after restoring the data from the backup:

  1. The file server has rebooted.

  2. The file server is the active node of a cluster and there is a fail-over event.

  3. If the data is on a NAS and the NAS device becomes unreachable during the dataxform.

Before restoration, disable the offline policy and clear the dataxform state.Type:

dataxform –cleanup <_GuardPoint_>

Client Profiles

Client profiles are used to group common configuration values for multiple clients in both ProtectFile and CTE. However ProtectFile client profiles are quite different from CTE client profiles, and the pfmigrate utility does not migrate them.

If their associated client profile has the enable su property set, enable the CTE su_root_no_auth authenticator in the client settings on the CTE client.

Manually Migrating to CTE

For explicit details on how to complete tasks on ProtectFile, CM, CTE and Data Transformation, consult the product documentation for each product on Thales Docs Online.

Performing the migration manually may be unavoidable in some rare cases. In this approach, you need to decrypt all the data in the ProtectFile encrypted paths, and configure and apply CTE customized GuardPoints as appropriate.

Make sure that you perform all of the checks listed in the section Prerequisites for Migration. before performing the following steps:

  1. Install CTE on the file server and perform client registration. For NAS, CIFS, or cluster installations, this must be performed on all of the nodes. Make sure that in the Client section on CM, you select: Communication Enabled and Registration Allowed.

  2. In the manual approach, you can skip the step Migrating the configuration from classic KeySecure to CM.

  3. If the ProtectFile configuration is already migrated to CM, use the pfmigrate utility to migrate the CM configuration for ProtectFile to CTE. Then make changes as appropriate.

    Otherwise, create the CTE configuration elements manually. Refer to the section Production Policies for guidelines on mapping ProtectFile configuration elements to CTE configuration elements on CM.

  4. Navigate to the ProtectFile client on the CM (or KeySecure) and decrypt the first encryption rule.

  5. Wait for this operation to finish.

  6. After Data Transformation completes, it should automatically remove the encryption rule from the CM (or KeySecure) and the corresponding mount on the file server.

  7. Create and enable the CTE offline policy.

  8. Run the dataxformcommand on the GuardPoint.

  9. Create and enable the CTE production policy.

At this point, the migration for this encryption rule is complete. The data is converted to the CTE format and the access rules are enforced.

Linux File Server: After data migration, close existing login sessions/terminals and then verify the integrity of the data for each protected path.

Windows File Server: After data migration, reboot the file server. Once the file server is rebooted, verify the integrity of the data for each protected path.

  • Verify the integrity of the data. Consult the CTE product documentation for information on how to verify the data integrity.

  • The path is now ready for production use. Unless you need to migrate other encryption rules immediately, you can make the full cluster nodes and all of the NAS clients active.

  • Repeat the steps for all encryption rules for the ProtectFile client.

  • Delete the ProtectFile client entry from the CM.

  • Uninstall the ProtectFile software from the file server.

Sample Mapping File

When you convert a Linux client with NFS shares to CTE, you must create a mapping file which maps the names of all of the shares on the CM to their mount point on the file server. This file is provided as input for the pfmigrate utility. The mapping file uses the following options for the mapping:

  • pf_share_name: Share name designated for share

  • mount_point: Directory to which the share is mounted

Following is an example mapping file:

"mapping":  [
                {
                    "pf_share_name": "myshare1",
                    "mount_point": "/mnt/share1"
                }
                {
                    "pf_share_name": "myshare2",
                    "mount_point": "/mnt/share2"
                }
                {
                    "pf_share_name": "myshare3",
                    "mount_point": "/mnt/share3"
                }
            ]
}