Geneos ["Geneos"]
You are currently viewing an older version of the documentation. End of life for version 5.x.x is scheduled for 30 September 2025.
If you are currently using version 5.x.x, we advise you to upgrade to the latest version before the EOL date. You can find the latest documentation here.
["Geneos > Gateway"]["Technical Reference"]

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 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>

      Caution: This option has been deprecated.

  • External password provider (extPwd)

    Specify passwords by requesting them from secured external sources. You can configure the source from Operating environment using the Gateway Setup Editor.

  • Plain text (plain-text)

    Specify a password without any encryption. This is not advised and is only provided for testing purposes.

    Caution: This option has been deprecated.

  • Variable (Var)

    Specify a password with a variable. Variables can be defined in managed entities, managed entity groups, types, environments and operating environment. You can provide any of the above password types using a variable. For more information, see User Variables and Environments.

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.

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).

  1. 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.

  2. 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

Securing your Gateway with an external password provider

You can configure a Gateway to retrieve passwords from an external provider. This allows passwords to be encrypted and stored by another application.

Gateway supports the following external providers:

  • CyberArk Central CP
  • CyberArk Local CP

Note: Only one external provider can be used at a time.

Configure the operating environment

To use an external password provider, you must configure the connection to the provider server in the Gateway Operating environment. The provider must be accessible to the Gateway over the network and you must provide valid credentials to access the password store.

To configure an external provider:

  1. Open the Gateway Setup Editor.
  2. Navigate to Operating environment.
  3. Open the Advanced tab.
  4. Click External passwords, this creates a new section.
  5. Specify the Provider.
  6. Specify the Provider information.
  7. Specify a Validation timeout. This determines how long Gateway should wait after setup validation for responses to outstanding password requests.
  8. Click Validate current document.
  9. Click Save current document.

CyberArk Central Credential Provider

The CyberArk Central Credential Provider allows you to fetch passwords from a central password vault using an API.

To use the CyberArk Central Credential Provider as your password provider you must provide the following information.

Field Description
Server name

URL of the CyberArk server. This should take the form https://<server_name>:<port>.

If no port is specified the default port 443 will be used.

Application id

Name used to identify the CyberArk permissions for the Gateway. This determines which passwords can be requested and must be configured in the CyberArk web interface.

Client certificate Path to the <your-cyberark-cert>.pem file containing the certificates needed to connect to CyberArk securely.
Client key (Optional) Path to the file containing the client key. This is not required if the client key has been provided as part of the <your-cyberark-cert>.pem file.
Client key passphase (Optional) Passphrase used to decrypt an encrypted client key.

When you request a password, Gateway sends an HTTPS request to the CyberArk REST API containing a query for the required password. The correct queries will be provided by your CyberArk administrator.

A valid request will receive a JSON file in response. Gateway will parse the JSON file and extract the password. Passwords received by a Gateway are stored securely in memory using AES-256 encryption.

Note: If a CyberArk query includes a Query= prefix this should be omitted when specifying the query in the Gateway Setup Editor.

Test CyberArk connectivity

You can test whether your environment can connect to the CyberArk Central Credential Provider by manually performing a query using curl:

curl -k --cert client.pem 'https://<server>:<port>/AIMWebService/api/Accounts?AppID=<application_id>&Query=<query>

CyberArk Local Credential Provider

The CyberArk Local Credential Provider allows you to maintain a secure, actively refreshed password cache locally. This uses a local agent to access your central password vault.

To use CyberArk Local Credential Provider as your password provider you must provide the following information.

Field Description
Application id

Name used to identify the CyberArk permissions for the Gateway. This determines which passwords can be requested and must be configured in the CyberArk web interface.

Default: ITRS-Geneos

SDK path

Path to the Application Password SDK installed on the Gateway host. The path must be fully specified and cannot embed any references to environment variables.

If no path is specified, the default CyberArk installation directory /opt/CARKaim/sdk/clipasswordsdk will be used.

Note: Configuring the CyberArk Local Credential Provider in the operating environment allows only the Gateway to use external passwords. To enable Netprobes to use external passwords, you must both configure the operating environment settings and additionally install the local agent on each Netprobe host, and then configure external passwords on each Netprobe. For more information, see Probes.

In addition, the CyberArk Local Credential Provider is available on all platforms supported by the respective plugins, except Linux on IBM POWER8. For more information, see Plug-in support in 5.x Compatibility Matrix.

Use external passwords

To use a password from an external provider:

  1. Select extPwd from the Password drop-down list.
  2. Specify the query associated with the required password.
  3. Click Validate current document.
  4. Click Save current document.