Secure Passwords

Overview

This document explains how to use secure passwords on the Gateway, as well as how to decrypt encoded environment variables.

Operation

Types of password offered by the Gateway and how to generate them

There are a number of places where it is possible to specify passwords in your setup. For example, to access external resources or to access secure commands.

The Gateway supports the following methods of specifying passwords:

One way
- Encoded passwords
  These are one way hashes used to specify the Netprobe passwords. This is essentially the Unix crypt format.
  The Gateway Setup Editor can configure and transmit this password to the Netprobe for you. Alternatively, the start Netprobe script can supply a password by setting the ENCODED_PASSWORD environment variable. This is documented in the template file. To encrypt the password using the Gateway, use:
```
gateway -pw <password>
```
Two way
When interfacing with external systems, it is necessary to securely encrypt the password within the setup but also to decrypt them when required to supply the password to an external API such as an interface to a database. The Gateway supplies the following ways of specifying passwords.
- AES 256 bit Encryption (stdAES)
  This is the most secure method currently offered by the Gateway. This uses 256 key to produce a hash of the password.
  The Gateway Setup Editor handles the encrypting for you but if you are generating your setup dynamically, or manually editing the XML for some reason, you can use the Gateway to generate your passwords using:
```
gateway -aes256-encrypt <password>
```
- Geneos Standard Encoding (std)
  This encodes (rather than encrypts) the password so that it is not immediately apparent what the password is. However, this does not offer the level of protection that encrypting the password would.
  The Gateway Setup Editor handles this encoding for you, however you can use the Gateway to generate these from the command line using:
```
gateway -en <password>
```
Plain text (plain-text)
Specify a password without any encryption. This is not advised and is only provided for testing purposes.

Securing your Gateway with a supplied key

It is recommended that you use the most secure method of storing your passwords possible within your configuration. The Gateway provides AES 256 implementation, this is the recommended method unless you are using an external password manager.

ref-guide171

Gateway uses a built-in key to encrypt your passwords by default. You can supply your own key to increase the security of your passwords. See below for how to do this.

Warning: If you supply your own key, any existing AES 256 encrypted passwords will no longer be valid.

How to generate your own AES-256 key

An AES 256 key actually has two parts:

A key.
An initialisation vector.

You can use openssl tool on the command line to generate your own key and initialisation vector:

Note: This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org).

Use the following command, replacing <encryption phrase> with any phrase or letters you want:
- ```
openssl enc -nosalt -aes-256-cbc -k "<encryption phrase>" -P -md sha1
```
  The command produces output in the following form:
```
key=92358925C00DE524B4F325A7F488DF1F29646313F6D258090818E8C9B69CF4D8
iv =B8B606E4700FE4D05E24E1A682F5963D
```
  The command produces a different result each time it is run.
Copy these lines into a file or redirect the output of this command into a file.

How to change the key file of your Gateway

To change the key file of your Gateway, you must start the Gateway with a -key-file <filename> parameter. This tells the Gateway to use the key within this file for all encryption / decryption of AES passwords. However, the Gateway stores an MD5 hash of the key file in its cache to prevent you from unintentionally starting the Gateway with a different key file from the one used previously. The Gateway refuses to start if this hash does not match the MD5 hash of the file specified on the Gateway command line.

If no key file is specified, the default hash is used and this is noted in the cache. The Gateway does not start if no key file is specified and there is already a hash that is not the default.

To start the Gateway with a key file that is not the same as the previous, you must start the Gateway with the -skip-cache parameter to avoid this check. The new MD5 hash is written to the cache for next time.

Therefore to change the key file of your Gateway, you must start the Gateway with both parameters. An example command is shown below:

gateway2.linux -key-file <key-file> -skip-cache

Warning: If you supply your own key, any existing AES 256 encrypted passwords will no longer be valid.

How to generate password with the new key

As you can start a Gateway with a different key, you also need a way to generate passwords on the command line using this key.

To do this, use the following command, replacing <password> with your desired password, and <key-file> with your key file:

gateway -aes256-encrypt <password> -key-file <key-file>

Caution: Do not edit the key file while the Gateway is running. The Gateway detects the change and generates an error at whatever reload interval is set.
Remember that all passwords in the setup will need to be re-entered if this file is changed.

This command generates a password that can be added to a Gateway XML setup:

Encoded text:
+encs+69B1E12815FA83702F0016B0E7FBD33B

An example of this command is below:

gateway2.linux -aes256-encrypt PassW0rd -key-file shh.aes

Decode encrypted environment variables

As detailed in Securing your Gateway with a supplied key, the Gateway can be given a key file that is used to encrypt secure password fields.

You are required to supply your own key file if you want to send your own encrypted environment variables to a Toolkit. The Gateway can use it's own key but we do not supply a means for a third party to decrypt these.

See How to generate your own AES-256 key for how to generate your own key, and How to generate password with the new key for how to use your new key to make passwords.

To decrypt your password you need to convert the hexadecimal back to base64 for use with openssl and provide the contents of your key file.

Below is a bash script demonstrating how to do this.

decode.sh

#!/bin/bash
hex=${1#*+encs+}
salt=$(grep salt key-file)
key=$(grep key key-file)
iv=$(grep iv key-file)
echo ${hex}| xxd -r -p | base64 | openssl enc -d -aes-256-cbc -S ${salt#*=} -K ${key#*=} -iv ${iv#*=} -a

Note: xxd is part of the vim-common package which you may have to install separately.

To use this script to convert an environment variable, replace the '1' in the second line with the name of the environment variable. All encrypted variables start with +encs+ so this removes the prefix prior to decoding. Example of usage:

./decode.sh +encs+69B1E12815FA83702F0016B0E7FBD33B