vSEC:TOOL

Getting Started With vSEC:TOOL K3.1

With vSEC:TOOL K3.1 (previously vSEC:CMS K3.0) it is possible to perform a number of administrative operations on user authentication credentials, such as physical smart cards.
Examples of such operations are changing or unblocking a smart card PIN.

In this document vSEC:TOOL K3.1 is called the Application or just Application. 

The Application is a software tool that is intended to be used for testing and learning about credentials.
When a time comes to implement and integrate credentials into a live environment, the Application no longer has a role and instead the Credential Management System vSEC:CMS should be used: https://versasec.com/products/vsec-cms

The Application is tab-based, where each tab is focused on a specific type of credential operation.
Each tab is described in more detail later in this document.

In order to use the Application, it is required that the credential that is being used is supported.
The updated list of supported credentials can be found at versasec.com (https://versasec.com/products/supported-credentials/). The Application displays which credential drivers have been detected on the local system.

Tab: Home

From the Home tab you can see the End-User License Agreement and the Installed Credential Drivers.

End-User License Agreement

Here you can see and scroll through the End-User Licence Agreement for the Application.

Installed Credential Drivers

The Installed Credential Drivers that are on the system are listed here.

Tab: Online Unblock

How To Unlock A PIN While Online

From this tab it is possible to unblock a credential. In order to perform an unblock you will need to know the Admin key of the credential or have the person who does know the Admin key of the credential able to generate the unblock code.

Firstly select the Credential you want to unblock from the drop-down list beneath Credential selection.

From the second drop-down field, it is possible to select the PIN that is required to be unblocked. This feature will only be available for credentials that support multiple PINs. If the credential does not support this feature, then the default Primary smart card PIN option will be selected.

The Serial number field is automatically populated with the serial number of the attached credential that is to be unblocked.

Depending on the different possible flows, a challenge will need to be generated and clicking the Get button will generate a challenge. The challenge needs to be provided to the person who knows the Admin Key of the credential. They can then generate a response (Cryptogram) code and provide back. Alternatively, if you know the Admin key you can skip this part and just enter a PIN and confirm in the fields provided and click the Unblock button. In that case you will be prompted to enter the Admin key to complete the unblock.

It is important that the credential is not removed and that the tab remains open during this process as there is a one to one relationship between the challenge and the cryptogram in the protocol.

When the challenge and the response have been supplied and input, enter the new PIN and confirm the new value. If all the PIN rules are satisfied a tick icon will be displayed beside the rule and the Unblock button will become enabled. 

Click the Unblock button to complete the operation and unblock the credential.

Tab: Offline Unblock

From the Offline Unblock tab an unblock code (response cryptogram) can be calculated. This can then be used to perform an online unblock. To calculate the offline unblock code you need to run an application that will generate a challenge code on the credential which is to be unblocked. For example, you could open a separate instance of the Application and from the Online Unblock tab and with the credential attached click the Get button. The challenge code should then be entered into the User credential challenge field.

On clicking the Cryptogram button you will need to enter the Admin key value in order to generate the cryptogram. Enter the Admin key value and click the Calculate Cryptogram to generate the cryptogram.

Tab: PIN Policies

PIN Policy Management

A PIN (Personal Identification Number) is a private code. It is a sequential combination of numeric and/or alphanumeric characters and is used as a type of password.

PIN policies are established in multiple ways so it is important that it is planned out what is wanted according to a company’s security policy and making sure this matches up with the unchangeable built in PIN policy of the credential itself. For example, some credentials allow a user PIN to be a minimum of 4 characters, and other credentials allow a minimum of 6 characters. Please consult the credential vendor documentation for more information.

The Application recognizes two types of PINs that may be on a credential 

• User PIN
• Administration PIN

The User PIN management is described in this section. For the Administration PIN management see the section Tab:Admin Key. 

As a user, the user PIN must be verified before you can perform security tasks with the credential, such as logging on to a workstation, or creating a digital signature.

The user PIN of a credential may be the original PIN value set at the time of manufacture or it may be a PIN value assigned when the credential is managed by a Credential Management System (CMS). The user PIN should be unique to the user’s credential token and known only by the user. 

The PIN Policies dialog allows you to set configurable PIN policies, if the token supports this, regarding:

• set PIN policy to a specific PIN type (see note below);
• make changes to the PIN policy;
• add a PIN policy;
• remove a PIN policy

With the Application PIN Policy settings you can set the PIN policy for a particular end user credential. The parameters to be set for a PIN policy include, for example, specifications for minimum and maximum PIN lengths, characters allowed or not allowed and the use or not of repeated patterns for PINs.

When you have set all the parameters for a policy, the policy template is updated and saved to a database file.

Depending on the credential type, the Microsoft (MS) minidriver specification version supported on the credential and the configuration set for credential access from the Credential Configuration tab the view presented in the Policies tab can vary. 

From the Policy template drop-down field select the available policy and click the Apply on credential button to update and set this policy to the attached credential. This will replace the current PIN policy of the credential with the new PIN policy as specified in the template.

In order to manage and configure the PIN policy templates available click the Manage button.

Tab: PIN

Changing PIN

Select the credential reader from the drop-down list for which the credential PIN is to be changed or blocked. Select the PIN type from the drop-down field for which the credential PIN is to be changed. This feature will only be available for credentials that support multiple PINs. If the credential does not support this feature then the default Primary smart card PIN option will be selected and the field will be disabled.

Enter the current PIN, followed by the new PIN and confirm the new PIN and click the Change PIN button if the operation is to change the credential PIN. 

If it is required to block the credential simply click the Block button to block the credential.

Tab: Admin Key

Changing Admin Key

The Admin key is required to unblock the user credential when it becomes blocked. A user can block its credential when it enters their PIN incorrectly in excess of the allowed number of PIN entry tries. When the credential is blocked it becomes unusable. In order to maintain high security levels it is important to change the Admin key value when the credential is received from the credential vendor as the credential is shipped with a well-known Admin key value. For example, the Thales IDPrime MD tokens have a factory Admin key value of “000000000000000000000000000000000000000000000000” (48 zeros).

Select the credential from the drop-down list for which the credential Admin key is to be changed.

Enter the current Admin key value into the field provided and enter the new Admin key value followed by confirmation of this new value. If it is required to hide the Admin key characters check the enable the Hide characters checkbox. It is possible to use a random key generator by clicking the Random button, which automatically generates a new Admin key value. Click the Copy button to save the new Admin key value to the host system clipboard. It is important to copy this value to a secure location for future use. Click the Change key button to complete the operation. 

It is possible to set an ASCII value for the Admin key by disabling the Hexadecimal checkbox.

Tab: Certificates and Keys

Managing Certificates

From the Certificates tab it is possible to: 

• View the certificates on the device (if any exist)
• Set the certificate on the device as default if more than one certificate exists on the card. The Certificate icon will indicate the default certificate in the container if more than one certificate exists
• Import certificate onto the end user’s credential. The certificate format needs to be either PKCS#12 format (*.p12 or *.pfx) or a binary certificate format (*.cer or *.der). PKCS#12 format can have one or more certificates and may contain the certificate’s key pair value. These types of files are usually protected with a password. Binary certificate format contains one certificate and have no keys
• Delete certificate on the end user’s credential
• Clear (remove) all the certificates and keys. Knowledge of the credential administration key is required to perform this task.

The Issued To column displays the name of the person that the certificate is issued to.

The Issued By column displays the name of the organization that the certificate is issued by.

The Expiration date column displays the date on which the certificate will expire.

The Type column indicates what the key is valid for. If the type is Kex then the key is valid for key exchange and if the value is Sig then the key is valid for signature.

The PIN column displays information about the type of PIN that the container is set to.

The Container column is the corresponding private key identifier of the certificate.

Select a certificate entry and click the View button to view the full details about the certificate.

Select a certificate entry and click the Default button to set the certificate as the default certificate on the credential. The certificate needs to have a corresponding private key in order to set it as the default certificate.

Click the Import button to browse to a certificate file in the file system to import to the credential.

If a key container is selected, the new certificate will be imported into the selected container, otherwise a new container will be created.

Select a certificate and click the Delete button to remove the certificate from the credential.

Click the Clear all button to remove all certificates from the credential. This will require authentication to the credential, therefore knowledge of the credential Admin key is required.

Tab: Information

Viewing Credential Information

Specific information about the credential present, including FIDO2 information if the credential has one, can be viewed from this tab. Depending on the configuration set for the particular credential in the Credential Configurations tab, different information about the attached credential will be presented. Consult the credential vendor documentation for further details about the credential.

Tab: Credential Configurations

Viewing Credential Configuration

If a credential is attached to the host when viewing this tab, the Application will automatically filter for the attached credential and display the configuration for the credential. Otherwise all known credential configurations will be shown.

Adding Credential Configuration

If a credential is attached to the host when viewing this tab, and no entry is found for the credential you can try to add the credential configuration to see if it is supported. With the credential attached click the Add button and then click the Add button again and the Get button. The Application will then check to see if it knows about the attached credential and retrieve the details on the credential. If it does find details click the Ok button and click Save. You can then try to manage the credential with the Application.

Tab: About

All About vSEC:TOOL

From this tab you can see general information about the Application. This includes versioning, how to upgrade to the full Credential Management System - vSEC:CMS and some ways to keep in touch with Versasec such as through LinkedIN, Twitter and Facebook.

Technical Specifications

Operating Systems

The Application is supported on the following operating systems:

• MS Windows 10, 11
• MS Windows 2016 / 19, 22 Servers

Hardware

The following hardware needs to be available on the host running vSEC:TOOL:

• USB port (1.1 or higher)
• PC/SC compliant Smart Card Reader

Credentials

The full list of supported credentials can be found here:
https://versasec.com/products/supported-credentials/