In Authentication, authorization, and auditing application traffic
In Citrix ADC 13.0
In Citrix ADC
In All products
Product documentation
In Authentication, authorization, and auditing application traffic
In Citrix ADC 13.0
In Citrix ADC
In All products
Citrix ADC
Current Release 12.1 11.1
View PDF

OTP encryption tool

December 8, 2020
Contributed by: 
C

Starting from Citrix ADC release 13.0 build 41.20, the OTP secret data is stored in an encrypted format instead of plain text for enhanced security. Storing of OTP secret in encrypted format is automatic and does not require manual intervention.

Previously, the Citrix ADC appliance stored OTP secret as a plain text in the active directory. Storing OTP secret in a plain text format posed a security threat as a malicious attacker or an admin could exploit the data by viewing the shared secret of other users.

The OTP encryption tool provides the following advantages:

  • Does not result in any data loss even if you have old devices that are using old format (plain text).
  • The backward compatibility support with old Citrix Gateway versions, helps to integrate and work with the existing devices, along with the new device.
  • The OTP encryption tool helps admins migrate all the OTP secret data of all users at once.

Note:

OTP encryption tool does not encrypt or decrypt KBA registration or Email registration data.

Uses of OTP encryption tool

The OTP encryption tool can be used for the following:

  • Encryption. Store the OTP secret in encrypted format. The tool extracts the OTP data of the devices registered with Citrix ADC, and then converts the OTP data in plain text format to encrypted format.
  • Decryption. Revert the OTP secret to the plain text format.
  • Update certificates. Admins can update the certificate to a new certificate at any time. Admins can use the tool to enter the new certificate and update all the entries with the new certificate data. The certificate path must either be a absolute path or relative path.

Important

  • You must enable the encryption parameter in the Citrix ADC appliance to use the OTP encryption tool.
  • For devices registered with Citrix ADC prior to build 41.20, you must perform the following:
    • Upgrade the 13.0 Citrix ADC appliance to 13.0 build 41.20.
    • Enable the encryption parameter on the appliance.
    • Use the OTP Secret migration tool to migrate OTP secret data from plain text format to encrypted format.

OTP secret data in plain text format

Example:

#@devicename=<16 or more bytes>&tag=<64bytes>&,

As you can see, the starting pattern for old format is always “#@” and ending pattern is always “&”. All the data between “devicename=” and end pattern, constitutes user OTP data.

OTP secret data in encrypted format

The new encrypted format of OTP data is of the following format:

Example:

    {
         "otpdata”: {
         “devices”: {
                        “device1”: “value1”,
                        “device2”: “value2”, …
                    }
            }
    }

Where, value1 is base64 encoded value of kid + IV +cipher data

Cipher data is structured as following:

    {
      secret:<16-byte secret>,
      tag : <64-byte tag value>
      alg: <algorithm used> (not mandatory, default is sha1, specify the algorithm only if it is not default)
    }
  • In “devices”, you have value against each name. The value is base64encode(kid).base64encode(IV).base64encode(cipherdata).
  • In standard AES algorithms, IV is always sent as first 16 or 32 bytes of cipher data. You can follow the same model.
  • IV will differ for each device though key remains the same.

OTP encryption tool setup

The OTP encryption tool is located in the directory \var\netscaler\otptool. You must download the code from the Citrix ADC source and run the tool with the required AD credentials.

  • Prerequisites for using the OTP encryption tool:
    • Install python 3.5 or higher version in the environment where this tool is run.
    • Install pip3 or later versions.
  • Execute the following commands:
    • pip install requirements.txt. Automatically installs the requirements
    • python main.py. Invokes the OTP encryption tool. You must provide the required arguments as per your need for the migration of OTP secret data.
  • The tool can be located at \var\netscaler\otptool from shell prompt.
  • Run the tool with the required AD credentials.

OTP encryption tool interface

The following figure displays a sample OTP encryption tool interface. The interface contains all the arguments that must be defined for encryption/decryption/certificate upgrade. Also, a brief description of each argument is captured.

OPERATION argument

You must define the OPERATION argument to use the OTP encryption tool for encryption, decryption, or certificate upgrade.

The following table summarizes some of the scenarios in which you can use the OTP encryption tool and the corresponding OPERATION argument values.

Scenario Operation argument value and other arguments
Convert plaintext OTP secret to encrypted format in the same attribute Enter the OPERATION argument value as 0 and provide the same value for source and target attribute. Example: python3 main.py -Host 192.0.2.1 –Port 636 -username ldapbind_user@aaa.local -search_base cn=users,dc=aaa,dc=local -source_attribute unixhomedirectory -target_attribute unixhomedirectory -operation 0 -cert_path aaatm_wild_all.cert
Convert plaintext OTP secret to encrypted format in a different attribute Enter the OPERATION argument value as 0 and provide the corresponding values for source and target attribute. Example: python3 main.py -Host 192.0.2.1 –Port 636 -username ldapbind_user@aaa.local -search_base cn=users,dc=aaa,dc=local -source_attribute unixhomedirectory -target_attribute userparameters -operation 0 -cert_path aaatm_wild_all.cert
Convert the encrypted entries back to plaintext Enter the OPERATION argument value as 1 and provide the corresponding values for source and target attribute. Example: python3 main.py -Host 192.0.2.1 –Port 636 -username ldapbind_user@aaa.local -search_base cn=users,dc=aaa,dc=local -source_attribute unixhomedirectory -target_attribute userparameters -operation 1 -cert_path aaatm_wild_all.cert
Update the certificate to a new certificate Enter the OPERATION argument value as 2 and provide all the previous certificate and the new certificate details in the corresponding arguments. Example: python3 main.py -Host 192.0.2.1 –Port 636 -username ldapbind_user@aaa.local -search_base cn=users,dc=aaa,dc=local -source_attribute unixhomedirectory -target_attribute userparameters -operation 2 -cert_path aaatm_wild_all.cert –new_cert_path aaatm_wild_all_new.cert

Note:

cert_path argument must contain the path of the file consisting of Base64 encoded public certificate and corresponding private keys.

Enabling encryption option in the Citrix ADC appliance

To encrypt the plain text format, you must enable the encryption option in the Citrix ADC appliance.

To enable OTP encryption data by using the CLI, at the command prompt, type:

set aaa otpparameter [-encryption ( ON | OFF )]

Example:

set aaa otpparameter -encryption ON

OTP encryption tool use cases

The OTP encryption tool can be used for the following use cases.

Register new devices with Citrix ADC appliance version 13.0 build 41.20

When you register your new device with Citrix ADC appliance version 13.0 build 41.x, and if the encryption option is enabled, then the OTP data is saved in an encrypted format. You can avoid manual intervention.

If the encryption option is not enabled, the OTP data is stored in the plain text format.

Migrate OTP data for the devices registered previous to 13.0 build 41.20

You must perform the following to encrypt the OTP secret data for the devices that are registered with Citrix ADC appliance prior to 13.0 build 41.20.

  • Use the conversion tool to migrate OTP data from plain text format to encrypted format.
  • Enable the “Encryption” parameter on Citrix ADC appliance.
    • To enable encryption option by using the CLI:
      • set aaa otpparameter -encryption ON
    • To enable encryption options by using the GUI:
      • Navigate to Security > AAA – Application Traffic and click Change authentication AAA OTP Parameter under Authentication Settings section.
      • On the Configure AAA OTP Parameter page, select OTP Secret encryption, and click OK.
    • Log in with the valid AD credentials.
    • If it is required, register additional devices (optional).

Migrate encrypted data from old certificate to new certificate

If admins want to update the certificate to a new certificate, the tool provides an option to update the new certificate data entries.

To update the certificate to a new certificate by using the CLI

At the command prompt, type:

Example:

python3 main.py -Host 192.0.2.1 –Port 636 -username ldapbind_user@aaa.local -search_base cn=users,dc=aaa,dc=local -source_attribute unixhomedirectory -target_attribute userparameters -operation 2 -cert_path aaatm_wild_all.cert –new_cert_path aaatm_wild_all_new.cert

Note

  • The certificates must contain both private and public keys.
  • Currently, the functionality is provided only for OTP.

Re-encrypt or migrate to new certificate for devices registered after the appliance is upgraded to 13.0 build 41.20 with encryption

Admin can use the tool on the devices that are already encrypted with a certificate, and can update that certificate with a new certificate.

Convert encrypted data back to plain text format

Admin can decrypt the OTP secret and revert them to the original plain text format. The OTP encryption tool scans through all the users for OTP secret in encrypted format and converts them to decrypted format.

To update the certificate to a new certificate by using the CLI

At the command prompt, type:

Example:

python3 main.py -Host 192.0.2.1 –Port 636 -username  ldapbind_user@aaa.local -search_base cn=users,dc=aaa,dc=local -source_attribute unixhomedirectory -target_attribute userparameters -operation 1

Troubleshooting

The tool generates the following log files.

  • app.log. Logs all the major steps of execution and information about errors, warnings, and failures.
  • unmodified_users.txt. Contains a list of User DNs that was not upgraded from plain text to encrypted format. These logs are generated to an error in format or might be due to some other reason.
OTP encryption tool
December 8, 2020
Contributed by: 
C
December 8, 2020
Contributed by: 
C

In this article

Site feedback | Privacy and legal terms | Cookie preferences | Consent settings
© 1999- Citrix Systems, Inc. All rights reserved.