Encrypt your credentials

In this guide, you set an encryption key on your probe, encrypt a device password, and add the encrypted password to a credential. ITVA stores the encrypted password and sends it to the probe. Only the probe can decrypt it.

You can encrypt passwords for Username / Password credentials. You can encrypt a password in two ways:

Before you begin

• A probe that is installed and passes Test Connection. See Add your first probe.
• Access to the probe host: sudo on Linux, administrator rights on Windows, or access to the Docker container.
• Access to the ITVA portal, with permission to manage credentials.

Set the encryption key on the probe

The probe reads the key from encryption_key in its config file, itva.yml. The config file that you download from the portal has only a placeholder for this key. You add the real key on your probe host, so ITVA never sees it.

Caution: Keep a copy of the key in a safe place, such as your password manager. If you lose the key, nobody can decrypt your encrypted passwords, including ITVA. You must then set a new key and encrypt each password again.

Caution: If more than one probe uses the same credential, set the same key on each probe. For example, set it on the primary probe and the secondary probe of a device.

1. Make a long, random key. For example, on Linux:

openssl rand -base64 32

2. Open the probe's config file in a text editor. For example, /etc/itva/itva.yml on Linux or C:\ProgramData\Itva\itva.yml on Windows. For Docker, edit the copy of the file on the host.
3. Set encryption_key to your key. Replace <YOUR_ENCRYPTION_KEY> with the key from step 1. Keep the quotes.

encryption_key: "<YOUR_ENCRYPTION_KEY>"

4. Save the file.
5. Restart the probe so that it reads the key. On Linux:

sudo systemctl restart itva

On Windows, run PowerShell as an administrator:

Restart-Service Itva

On Docker, copy the file into the container again, then restart the container. Replace <PATH_TO_ITVA_YML> with the path of the config file on the host:

docker cp <PATH_TO_ITVA_YML> itva_probe:/app/itva.yml
docker restart itva_probe

Encrypt a password on the probe (recommended)

The probe program has an --encrypt option. It reads the key from the config file, encrypts the text you give it, and prints the result. It does not connect to ITVA.

Caution: Do not type the password directly in the command. Your shell can save the command in its history. The commands below read the password first, so it does not go into the history.

1. On the probe host, run the command for your platform. Type the device password when the command waits for input, then press Enter. On Linux:

read -rs PASSWORD
sudo /usr/local/bin/itva --path /etc/itva/itva.yml --encrypt "$PASSWORD"
unset PASSWORD

On Windows, in PowerShell as an administrator. If your config file is in a different location, change the --path value:

$p = Read-Host "Password"
& "C:\Program Files\Itva\Probe\itva.exe" --path "C:\ProgramData\Itva\itva.yml" --encrypt $p
Remove-Variable p

On Docker:

read -rs PASSWORD
docker exec itva_probe ./probe --encrypt "$PASSWORD"
unset PASSWORD

2. Copy the line that the command prints. This is the encrypted password.
3. In the portal, go to Inventory > Credentials.
4. Select New Credential. To change an existing credential, open it and select Edit.
5. In the type list, select Username / Password, and enter the Username.
6. Under Password, select View Advanced Password Options. The Advanced Password Management dialog opens.
7. Select Generate on Probe.
8. In Encrypted Password, paste the encrypted password.
9. Select Save. The dialog closes, and the Password field shows Encrypted.
10. Select Save to save the credential.

Note: The Generate on Probe tab tells you to open a local web page on the probe host. The probe does not have this page. Use the --encrypt command in step 1 instead.

Encrypt a password with ITVA's server

If you cannot run commands on the probe host, the portal can encrypt the password for you. Your browser sends the password and the encryption key to ITVA. ITVA encrypts the password, returns the result to your browser, and discards both values.

ITVA does not store your password or your key, and we will never look at them. But they do pass through ITVA's servers. For a password that must never leave your network, encrypt it on the probe.

Caution: The key you enter must be the same as encryption_key on the probe. If the keys are different, the probe cannot decrypt the password.

1. In the portal, go to Inventory > Credentials, and open a new or existing Username / Password credential.
2. Under Password, select View Advanced Password Options.
3. Select Generate using Server.
4. In Password, enter the device password.
5. In Encryption Key, enter the key from the probe's config file.
6. Select Save. The Password field shows Encrypted.
7. Select Save to save the credential.

Check that it worked

1. Assign the credential to a device that uses this probe.
2. On the device's page, select Test Connection.

If the result is Successfully connected, the probe decrypted the password and signed in to the device.

How this keeps your password safe

When you encrypt a password on the probe, the password is encrypted before it leaves your network. ITVA only receives the encrypted password. The key that can decrypt it stays in itva.yml on your probe host.

ITVA never receives the key. You add it to the config file on your own host. The probe uses the key only to encrypt and decrypt passwords, and it never sends the key to ITVA.

Because ITVA never has the key, ITVA can never decrypt the password. This is not only a policy. It is how the encryption works. Nobody at ITVA can read the password. A person who gets a copy of ITVA's database cannot read it either.

The encryption in detail

• Key derivation. The probe turns your key into a 32-byte encryption key with PBKDF2-HMAC-SHA256 and 100,000 iterations. The iterations make each guess at your key slow, so an attacker cannot try many keys quickly.
• Random salt. Each encryption uses a new random 16-byte salt. If you encrypt the same password two times, you get two different results. An attacker cannot use precomputed tables, or compare results to find passwords that are the same.
• Encryption and tamper protection. The probe encrypts the password with Fernet. Fernet uses AES-128 in CBC mode with a random IV, and signs the result with HMAC-SHA256. If anyone changes the encrypted password, the probe detects the change and does not use it.
• Output. The encrypted password is the salt followed by the Fernet token, encoded as URL-safe base64. It does not contain the key.
• Storage. ITVA encrypts the encrypted password again with its own storage key before it writes it to the database. ITVA can remove this outer layer, but the result is still your probe-encrypted password, which ITVA cannot read.

What you must protect

• Use a strong key. The encryption is only as strong as your key. An attacker can guess a short or common key. Use a long random key, such as the output of openssl rand -base64 32.
• Protect the config file. A person who has the key and an encrypted password can decrypt the password. Limit who can read itva.yml, and do not commit it to source control.
• Protect the probe host. The probe decrypts the password in memory when it signs in to a device. The plain password exists only on the probe host, and only while the probe uses it.

If you encrypt with ITVA's server

ITVA's server uses the same algorithm, so the stored result has the same protection. The difference is how the password and key get there. Your browser sends both to ITVA in one request. ITVA uses them to encrypt the password, then discards them. ITVA does not store them, and we will never look at them.

This method depends on your trust in ITVA for that one request. The probe method does not. If a password must never leave your network, encrypt it on the probe.

Troubleshooting

• If the --encrypt command fails with "encryption key not found", encryption_key is empty in the config file that the command read. Set the key, and make sure --path points to the correct file.
• If the command shows "unable to locate a config file for the path", the --path value is wrong. Use the full path of itva.yml.
• If the probe logs show "failed to decrypt password, secret key is invalid", the probe's key is different from the key that encrypted the password. Make sure that:
  • You restarted the probe after you set the key.
  • Every probe that uses the credential has the same key, including the secondary probe.
  • Nobody changed the key after the password was encrypted. If the key changed, encrypt the password again with the current key.