OTP encryption tool
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 an OTP secret in encrypted format is automatic and does not require manual intervention.
Previously, the Citrix ADC 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 Citrix 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 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. 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 Citrix ADC appliance to use the OTP encryption tool.
- For devices registered with Citrix ADC before 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 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).
- In standard AES algorithms, IV is always sent as a first 16 bytes or 32 bytes of cipher data. You can follow the same model.
- IV differs for each device though the key is the same.
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 Citrix ADC appliance.
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.
- Run 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\otptoolfrom 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 Citrix ADC 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 Citrix ADC 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 AD domains or users. The format of this search filter is the same as the LDAP search filter format used in the LDAP action command in the Citrix ADC appliance.
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 the Citrix ADC 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 Citrix ADC 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).
- To enable the encryption option by using the CLI:
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.