Working with CT-VL GUI

Use the CT-VL administration GUI to:

• Create tokenization users and groups.

• Specify permissions for users and groups.

• Create token templates.

• Create token groups.

Logging into the CT-VL GUI

To log in to the CT-VL administration GUI:

1. Point your browser to the Tokenization Server:

   https://<CT-VL name or IP address>/

   Copy

2. Log in using the Admin user name and password you defined when you created the CT-VL cluster.

3. If you have implemented OAuth authentication, log in with those credentials.

The CT-VL GUI Home page is displayed.

Troubleshooting

The CipherTrust Vaultless Tokenization Server Administration GUI login failure is indicated by the following error message:

nginx 504 Gateway Time-out error

In this scenario, consider the following problem/solution option:

• Problem: The Tokenization Server is not connected to the LDAP server.

• Solution: Restart the CT-VL service. Open the CT-VL CLI, and run the following command:

  main> vts service --restart

  Copy

Creating and Managing Passwords

CT-VL uses a dynamic password policy control mechanism to ensure system security.

CT-VL leverages a password checker library. If you try to create a password that does not pass the proactive password checking provided by this library, you are prompted to try another string. The policy can change dynamically based on several factors.

The dynamic nature of the checking algorithm provides the most secure possible password policy options.

When creating a system password, use the following guidelines:

• Use at least 1 digit, 1 uppercase letter, 1 lowercase letter, 1 special character, and use at least 8 characters in total.

• Do not use your name, the company name, or other familiar names in the password string.

• Do not use your birthday or any other personally or professionally meaningful dates in the password string.

• Include a combination of the following character types in the password string:

  • Lowercase letters

  • Uppercase letters

  • Numbers

  • Special characters

Managing CT-VL User Groups

User groups enable you to assign the same permissions to multiple users.

Refer to CT-VL Roles and Understanding CT-VL User Groups and Permissions to familiarize yourself with user groups in CT-VL.

If you are using AD/LDAP users, create at least three user groups, to correspond to the CT-VL roles:

• Superuser

• Staff

• Active

User groups must be defined on the LDAP system. The user group names must be entered into the CT-VL GUI before importing users.

Creating User Groups

To create a user group:

1) Log in to the CT-VL GUI and select User Groups from the navigation bar. All User Groups list is displayed.

2) Select New User Group and enter a name on the resulting page. Click Create. The new group name appears in the All User Groups list, and is selectable from user pages and the Permissions page.

Assigning Masks

You can assign a mask to a group when initially creating the user group (at the New User Group dialog), or any time later to an existing user group, by clicking the user group and adding a mask assignment at the Update User Group dialog.

Adding Users to User Groups

To add a user to an existing user group:

1) From the CT-VL GUI, select User Groups.

2) Click on a group from the list.

3) Select users to add to the group, and click Update.

Deleting a User Group

To delete a user group:

1. Log in to the CT-VL GUI and select User Groups from the navigation bar.

2. Select the check box by a group.

3. Click Delete. A dialog box appears asking you to confirm your action.

Note

If you delete a user group to which users and/or permissions have been associated, the user group is removed from any user belonging to it, and will delete any permissions assigned to it.

Managing CT-VL Users

Refer to Understanding CT-VL Authentication and Authorization for details on CT-VL users and CT-VL authentication and authorization basics.

You can perform the following to manage CT-VL users:

• Create a user manually.

• Import users from an AD/LDAP server.

Creating a User Manually

Creating Basic User Information

1. Log in to the CT-VL GUI and select Users from the navigation bar. The list of All Users is displayed.

2. Select New User. In the New User dialog, fill in the required information and click Create.

Note

• The username must contain only English letters, numbers, or the following special characters: “@” (at-sign), “.” (period), “+” (plus-sign), “-” (hyphen), or “_” (underscore).

• Usernames and passwords are case sensitive. Application code that calls the CT-VL RESTful APIs must pass usernames and passwords in the same case that are defined in the CT-VL GUI.

Updating User Information

After you complete the steps described in Creating Basic User Information, you can add more attributes to the basic user, including changing the CT-VL role and assigning to a user group.

1. Log in to the CT-VL GUI, and select Users from the navigation bar.

2. Click on the username of interest.

3. Change CT-VL role, User Groups assignment, Mask, or Email, as needed.

4. Click Change password here to update the user’s password.

5. Click Update.

Deleting a User Manually

If you delete a user to which permissions have been associated, all permissions linked to the user are also deleted.

Note

It is generally recommended to uncheck the Active status for a user rather than completely delete the user.

1. Log in to the CT-VL GUI, and select Users from the navigation bar.

2. Select the check box by a user, click Delete, and confirm the deletion.

Importing Users from an AD/LDAP Server

Refer to CT-VL Roles and Understanding CT-VL User Groups and Permissions to familiarize yourself with user groups in CT-VL.

AD/LDAP User Import Prerequisites

Before you import users, complete the following tasks:

• Set up your AD/LDAP connection to CT-VL, and configure it using the CT-VL CLI. See Configuring an AD/LDAP Server for instructions.

• Create the appropriate user groups in the CT-VL GUI as described in Creating User Groups.

• Set up the AD/LDAP server to import and authenticate users and user groups.

To import CipherTrust Tokenization Server users from an AD/LDAP server:

1. Create three AD/LDAP server groups, one for REST API users (Tokenization/Crypto/Key Management) and the other two for CT-VL administrators who require GUI access.
   The group that has been designated as the “Superuser” group in the CLI will have read/write access in the GUI, whereas the group that has been designated as the “Staff” group in the CLI will have read-only access in the GUI.

2. Populate each group with the desired REST API (“active”) users and CT-VL administrators.

   

   Note

   • The name with permission to access the REST APIs must match the name specified with the active_user command under the auth category of the CT-VL CLI. See Configuring an AD/LDAP Server for further information.

   • The name of the CT-VL users with read-only access to the GUI must match what was specified in the staff_user command of the auth category of the CLI.

   • The name of the CT-VL administrators’ group must match the name of the group that was specified in the super_user command of the auth category of the CT-VL CLI.

   Example of AD\LDAP server group names:

   • ct-vlUsers - Users in this group can create and/or access data through the RESTful API.

   • ct-vlStaff - Users in this group can access the CT-VL GUI (read only).

   • ct-vlAdmin - Users in this group can access the CT-VL GUI (read/write)

   

   Note

   • staff_user is valid only if the user also has active_user permission.

   • super_user is valid only if the user has both active_user and staff_user permissions.

   • Use corporate policy to define whether or not staff_user and super_ users should actually be granted REST API permissions, and disallow by policy when necessary to maintain corporate standards or separation of duties.

3. Create three group permissions in the CT-VL GUI with the same names as the LDAP groups (example: ct-vlUsers , ct-vlStaff, ct-vlAdmin). Members of these AD/LDAP groups inherit these permissions.

   • An application program that uses Basic Auth (username/password) will try to authenticate to LDAP using these credentials.

   • An application program that uses a client certificate for authentication will use the Bind user’s username and password for looking up the client certificate’s common name (CN) in LDAP.

   • If the credentials are authorized, the LDAP user is imported into the user table of the CT-VL. Thus, there is no need to manually create the LDAP users in the GUI.

   • Once the user has been added to the CT-VL, permissions can be modified with another group permission or individually.

   

   Note

   User names and passwords are case sensitive. Application code that calls the REST APIs must pass usernames and passwords in the same case that are defined in the AD/LDAP server.

Unlocking User Accounts

As a security feature, users are locked out after six failed login attempts.

If a user fails to successfully login after six attempts, the account is locked for 15 minutes (to prevent brute force attacks). The maximum number of attempts and cool-off time duration can be modified in the CLI.

To unlock a user account:

1. Click Logs in the navigation menu.

2. Select the Locked Accounts tab. The locked accounts are displayed.

3. Click Unlock for the desired account(s).

Note

All successful and failed login attempts are displayed under the Access Logs tab in the Logs menu. Select Success or Failed from the pull-down menu to filter the list so that only the selected access type is shown.

Specifying CT-VL Keys

Refer to Understandng CT-VL Keys to understand the definition and usage of symmetric keys, asymmetric keys, and opaque objects.

Creating a Key Name

Use the CT-VL GUI to enter a key name that corresponds to a key that has been created in the CipherTrust Manager (CM), and is to be used for CT-VL functions.

After the name has been entered into the CT-VL local database, the key is available to associate with user and user group permissions. Symmetric keys are also be available to associate with tokenization groups.

Note

The very first symmetric key entered into CT-VL needs to be entered from the GUI of the first cluster node. Enter this key as soon as possible, it will be used to create large lookup tables for the “RANDOM” tokenization mode.

1. After Logging into the CT-VL GUI, select Keys from the navigation bar. The Keys List is displayed, with the Symmetric Keys, Asymmetric Keys, and Opaque Objects tabs in the top navigation.

2. Select the tab for the type of key you want (for example, Symmetric Keys), and click the New Symmetric Key button.

   

   Note

   In CT-VL, the very first key generated cannot be renamed, edited, or destroyed. There is a warning when creating the key. Once this initial setup is complete, you can create subsequent keys with the normal New Symmetric Key UI, for application FPE.

3. Enter the key name that was used in the CM and click Create. The key name is displayed on the Keys List and will show as available in the Permissions matrix and Tokenization Group pages.

Deleting a Key Name

Deleting a key name from the CT-VL local database does not delete the key material (nor the key name) from the CM. Deleting a key name deletes all tokenization groups, tokenization templates, and permissions associated to it.

1. Select Keys from the navigation bar. The Keys List is displayed, with the Symmetric Key, Asymmetric Keys, and Opaque Objects tabs in the top navigation.

2. Select the tab for the type of key you want (for example, Symmetric Keys), click the check box by the desired key, and click Delete.

3. Confirm and click Delete again.

   

   Note

   The very first symmetric key entered into the CT-VL can serve as a regular key for all encryption, signing, and tokenization operations, but it is also used to build internal cryptographic tables and hence must not (and cannot) be deleted.

Tokenization Setup

Refer to Tokenization, Templates, and Masks for the concepts behind setting up tokenization in the CT-VL GUI.

Note

Before setting up tokenization, make sure you have specified the CM keys.

Creating Tokenization Groups

Have at least one symmetric key created in the CM and entered in the CT-VL GUI, as described in Specifying CT-VL Keys .

1. Select Tokenization > Tokenization Groups. The All Tokenization Groups list is displayed.

2. Click the New Tokenization Group button. The New Tokenization Group creation page is displayed.

3. Enter a Tokenization Group Name.

   

   Note

   Tokenization group names are case sensitive. Application code must pass tokenization group names in the same case that are defined in the CT-VL GUI.

4. Select a Symmetric Key from the drop-down list.

   

   Warning

   • Do not delete keys used for tokenization. If you delete a key, you will have to recreate the corresponding tokenization group to regain access to your tokens.

   • Do not use auto-key-rotation features with tokenization.

5. Click Create.

Deleting Tokenization Groups

Before deleting a tokenization group, make sure that tokens created with the symmetric key associated with this tokenization group are not stored anywhere within (or outside) of the organization.

Warning

Once the tokenization group used to create these tokens has been deleted, they can no longer be detokenized.

To delete a tokenization group:

1. Log in to the CT-VL administration interface.

2. Select Tokenization > Tokenzation Groups.

3. Select the group and click Delete.

Managing Character Sets

CT-VL now includes enhanced support for tokenizing international characters. In earlier versions, CT-VL supported three default character sets:

• All digits

• Alphanumeric

• All printable ASCII (not available for RANDOM Mode)

For FPE (FF3) and FF1 modes, you can also define a custom character set, which allows you to tokenize and detokenize UTF strings.

Creating Custom Character Sets

To define a custom character set, you need to know the Unicode character range for the language(s) you want to support. For example, the range for Arabic is 0600-06FF, while the range for Thai is 0E00 - 0E7F.

To create a custom character set:

1. Select Tokenization > Character sets.

2. Click New Character set.

3. Enter a Name and Range or set of ranges for your set. The maximum size of a custom UTF character set definition string is 1536. This implies either 100 ranges, or 200 individual characters, or some combination thereof—for instance, 50 ranges plus 100 individual characters.

4. Click Create. The new set appears in the All Character Sets list, and is available to apply to tokenization templates.

Editing Character Sets

To edit a character set, click on its name in the list. Predefined character sets cannot be edited and should not be deleted.

Applying Character Sets

The three predefined character sets always appear in the drop-down list of character sets when you create a tokenization template. Once a custom set has been defined, it appears in the tokenization template creation menu as well.

See Tokenization Template for information about CT-VL tokenization templates.

Deleting Character Sets

Before deleting a character set, make sure that tokens created with this character set are not stored anywhere within (or outside) of the organization.

Caution

After the character set used to create these tokens has been deleted, they can no longer be detokenized, unless the character set is recreated very precisely. Even the order of the characters in the character set matters.

To delete a character set:

1. Navigate to Tokenization > Character Sets.

2. Select the character set from the list, and click Delete.

Prototyping Tokenization

CT-VL supports UTF-8 inside the valuename field for "data" and "token".

Generate a file that has the JSON request in it containing this UTF-8 code, and then submit it via cURL.

A file can be submitted in cURL as shown here:

--data-binary @filename option.curl --tlsv1.2 -k -X POST -u
superuser:ssl12345 https://127.0.0.1/vts/rest/v2.0/tokenize --
data-binary @tokenizerequest.txt

Managing Tokenization Templates

Creating Tokenization Templates

1. In the CT-VL GUI, select Tokenization > Tokenization Templates.

2. Click New Tokenization Template.

3. Enter the values described in Managing Tokenization Templates field table.

Sample: Use a Tokenization Template in the REST API

After you specify a tokenization template, it can be used in the RESTful API application code. This is shown in the following example:

curl --tlsv1.2 -X POST -u EdYee:EdYee_password -d'{"tokengroup" :
"store1" , "data" : "9453677629008564", "tokentemplate" :
"ctsUsersTemplate" }' https://192.168.12.88/vts/rest/v2.0/tokenize

Deleting Tokenization Templates

Before deleting a tokenization template, make sure that tokens created with this tokenization template are not stored anywhere within (or outside) of the organization. Once the tokenization template used to create these tokens has been deleted, they can no longer be detokenized, unless the tokenization template is recreated very precisely.

Caution

After the character set used to create these tokens has been deleted, they can no longer be detokenized, unless the character set is recreated very precisely. Even the order of the characters in the character set matters.

To delete a tokenization template:

1. Navigate to Tokenization > Tokenization Templates.

2. Select the tokenization template from the list, and click Delete.

Managing Data Masks

Tokenization data masks hide specified parts of detokenized data. A mask is required for detokenization, even if the user is authorized to view the entire unencrypted string of data.

See Data Masks for more information on data masks used in CT-VL.

Creating a Data Mask

To create a data mask:

1. Select Tokenization > Masks. The All Masks list is displayed.

2. Click New Mask and enter the information on the New Mask dialog.

   Some examples of data masks you could create:

   • A mask called SHOW_LAST_4 that shows the last four digits of a tokenized credit card: XXXX-XXXX-XXXX-7897.

   • A mask called SHOW_FIRST_3 that shows only the first three digits of a social security number: 565-XX-XXXX.

   • A mask that shows everything (ALL_CLEAR): set Show Left and Show Right values to 999999.

3. Click Create.

Deleting a Data Mask

When a data mask is deleted, all user and user group permissions associated with that mask will be deleted.

Warning

This could result in production down time if a user is using the system and their permissions are deleted. They will be denied tokenization and detokenization rights. Be VERY sure these permissions are not in use before deleting the mask.

Applying Permissions to Users and User Groups

With CT-VL, users are authenticated, granted permissions (to tokenize, detokenize, encrypt, hash, etc.), and associated with particular keys, using a three-way permissions matrix.

Assigning Key-based Permissions

The CT-VL GUI Administrator assigns permissions based on user (or user group), action, and key, similar to the English sentence:

“User ctsuser1 may encrypt, decrypt, tokenize and detokenize with symmetric key key1."

Before permissions can be assigned, you must:

• Create user groups and users.

• Specify CT-VL Keys

Use the following steps to assign key-based permissions:

1. Log in to the CT-VL GUI and select Permissions. The User Permissions list is displayed. If necessary, click User Group to see the User Group Permissions list.
   You can click the tabs to see the Symmetric Keys, Asymmetric Keys, and Opaque Objects assigned to a user (or group).

2. Click a user or group name to see a user permissions summary page. You can review and change permissions there or from the list page. To continue from the list page:

3. Click the permission symbol for a particular user’s key. The user permission matrix is displayed.

4. Assign permissions as needed and click Apply.

Assigning Other Permissions

The permissions in the “Other Permissions” category are those that are not tied to specific keys. They are assigned only once per user group, and apply to all key groups. Actions that are not supported in the API are not displayed.

Creating and Importing Keys

To grant a user or user group permission to create keys on the CT-VL or to import keys to the CT-VL:

1. Log in to the CT-VL GUI and click Permissions. The User Permissions list is displayed. (If necessary, click User Groups to access the User Group Permissions list.)

2. Click the permission symbol for a user in the Other Permissions column. The Other Permissions assignment window is displayed.

3. Check Create and Import, as desired, and click Apply.

   

   Note

   • The Create permission is assigned only once per user and applies to all type of keys.

   • The Import permission is assigned only once per user and applies to symmetric keys and opaque objects.

Other Permissions: Tokenize/Detokenize

Select Tokenize/Detokenize to apply privileges at a global level, on all symmetric keys in the system.

If your system is upgraded from an earlier version, any users who had been granted tokenize/detokenize privileges have these boxes checked automatically.

Remember to de-select the global check boxes and reassign privileges on a per-key basis to take advantage of the more granular structure of CT-VL configuration options.