Product Documentation
ADC
14.1-Current Release 13.1
View PDF

OTP encryption tool

September 11, 2025
Contributed by: 
C H S

Starting from NetScaler 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 an OTP secret in encrypted format is automatic and does not require manual intervention.

Previously, the NetScaler appliance stored an OTP secret as a plain text in the active directory. Storing an OTP secret in a plain text format posed a security threat as a malicious attacker or an admin can 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 an old format (plain text).
  • The backward compatibility support with an old NetScaler Gateway version, helps to integrate and support 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

The 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 NetScaler, 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. Administrators 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 an absolute path or a relative path.

Important

  • You must enable the encryption parameter in the NetScaler appliance to use the OTP encryption tool.
  • For devices registered with NetScaler before build 41.20, you must perform the following:
    • Upgrade the 13.0 NetScaler 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.
  • The OTP encryption tool supports only single-valued user attributes. It does not support multi-valued user attributes.

OTP secret data in plain text format

Example:

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

As you can see, the starting pattern for an old format is always “#@” and an 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”, …
                    }
            }
    }
<!--NeedCopy-->

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

Cipher data is structured as the 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)
    }
<!--NeedCopy-->
  • In “devices”, you have value against each name. The value is base64encode(KID).base64encode(IV).base64encode(cipherdata).
  • KID is the key ID value that is used to identify the certificate used for OTP secret data encryption. The key ID is useful especially when multiple certificates are used for the OTP secret data encryption.
  • In standard AES algorithms, IV is always sent as first 16 or 32 bytes of cipher data. You can follow the same model.
  • IV differs for each device though key remains the same.

Note:

The encrypted format of the OTP data is stored in a user attribute AD.

OTP encryption tool setup

Note

To run the OTP encryption tool, Citrix recommends you to use an alternative platform with Python environment instead of the NetScaler appliance.

The OTP encryption tool is located in the directory \var\netscaler\otptool. You must download the code from the NetScaler 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.
  • Run the following commands:
    • pip install -r 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 a 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 the 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 the 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 the 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 -operation 2 -cert_path aaatm_wild_all.cert –new_cert_path aaatm_wild_all_new.cert

CERT_PATH argument

The CERT_PATH argument is a file containing the certificate which is used in the NetScaler for encrypting the data. The user must provide this argument for all the three operations namely Encryption, Decryption, and Update certificates.

The CERT_PATH argument file must contain both the certificate and the associated private key in the PEM or CERT format (pfx is non supported).

For example, if the certificate.cert and certificate.key files correspond to the certificate file and its private key, in a Unix like system the following command creates the file certkey.merged that can be used as the value for the cert_path flag.

$ cat certificate.cert certificate.key > certkey.merged
$
<!--NeedCopy-->

Points to note about the certificate

  • The user must provide the same certificate which is bound globally in the NetScaler appliance for user data encryption.
  • The certificate must contain the Base64 encoded public certificate and its corresponding RSA private key in the same file.
  • The format of the certificate has to be either PEM or CERT. The certificate must adhere to X509 format.
  • Password protected certificate format and .pfx file are not accepted by this tool. The user must convert the PFX certificates to .cert before providing the certificates to the tool.

SEARCH_FILTER argument

The SEARCH_FILTER argument is used to filter the Active Directory domains or users.

Examples:

  • -search_filter "(sAMAccountName=OTP*)": Filters users whose samAccountNames (user logon names) start with “OTP”.
  • -search_filter "(objectCategory=person)": Filters the object category of type person.
  • -search_file "(objectclass=*)": Filters all the objects.

Enabling encryption option in the NetScaler appliance

To encrypt the plain text format, you must enable the encryption option in the NetScaler 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 NetScaler appliance version 13.0 build 41.20

When you register your new device with NetScaler 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 the NetScaler appliance before 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 the NetScaler appliance.
    • To enable the 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 more 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 have 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 an 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
<!--NeedCopy-->

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.

The log files can be found in the OTP_encryption_tool directory within the folder where the OTP encryption tool is placed in the end-user device.

OTP encryption tool
September 11, 2025
Contributed by: 
C H S
September 11, 2025
Contributed by: 
C H S

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.