Gateway Security
Security and encryption model of the Keeper Gateway service
Last updated
Was this helpful?
KeeperPAM and Secrets Manager
Security and encryption model of the Keeper Gateway service
Last updated
Was this helpful?
The Keeper Gateway is a service that is installed on-premise in order to execute rotation, discovery and connection tasks. The Keeper Gateway communicates outbound to the Keeper Router using WebSockets and Keeper Secrets Manager .
The Keeper Gateway authenticates first to the Keeper Router using the One Time Access Token provided upon installation of the Gateway service on the target machine. After the first authentication, subsequent API calls to the Router authenticate using a Client Device Identifier (which is the HMAC_SHA512 hash of the One Time Access Token).
For accessing and decrypting vault records, the Keeper Gateway uses standard Keeper Secrets Manager APIs which perform client-side encryption and decryption of data. The ensures least privilege and zero knowledge by allocating only specific folders and records that can be decrypted by the service. API requests to the Keeper Cloud are sent with a Client Device Identifier and a request body that is signed with the Client Device Private Key. The server checks the ECDSA signature of the request for the given Client Device Identifier using the Client Public Key of the device.
Like any other Secrets Manager device, access can also be restricted based on IP address in addition to the encryption and signing process.
Rotations can be performed on-demand or on a schedule. When an on-demand rotation, connection or discovery job is triggered by a user in the Web Vault or Desktop App, the Keeper Router uses the active WebSocket connection to the appropriate Gateway to receive instructions. The messages do not contain any secret information or encrypted ciphertext. All messages sent through the WebSocket contain only the command type (e.g. "rotate") and the affected Record UID ("UID") which is not a secret value.
For scheduled rotations, the same mechanism is used. Rotation schedules are tracked in the Router, and at the appropriate intervals rotation instructions are pushed to the Gateway. When the Gateway receives a rotation task, it uses the local KSM configuration to fetch the secrets associated with the provided Record UIDs and decrypts the record information locally. These secrets are in turn used to perform the rotation, discovery or connection.
When the Gateway service is installed, the local KSM configuration is protected by permissions on the local file system. By default, the configuration will be stored in the home directory (.keeper folder) of the user that installed the Gateway.
The passes in the configuration through an environment variable in the Docker Compose file.
If Gateway is started as a user:
Config file: ~/.keeper/gateway-config.json
Logs folder: ~/.keeper/log
If Gateway is running as a service:
User: keeper-gateway-service
Config file: /etc/keeper-gateway/gateway-config.json
Logs folder: /var/log/keeper-gateway
If the Gateway is started via Command Line
Logs location: C:\Users\[USER NAME]\.keeper\logs\
Config File location: C:\Users\[USER NAME]\.keeper\gateway-config.json
If Gateway is started as a Windows Service
Logs location: C:\ProgramData\KeeperGateway\
Config File location: C:\ProgramData\KeeperGatewayPrivate\
Note: This folder can only be accessed by the user who installed the Gateway Service.
Access to the KSM configuration file allows a user to retrieve any associated secrets from Keeper. To prevent unauthorized access, this configuration file is only readable by the installing user and administrative accounts. On a Windows server, the Windows System account is used to run the service by default, and also has access to the KSM configuration.
Caching is used for discovery but not for rotation. Every time a secret is rotated, the Gateway retrieves associated records in real time using the Keeper Secrets Manager APIs.
The Gateway includes a virtual command shell. When the Gateway is run as a stand-alone application, the user is dropped into the shell. When the Gateway is run as a service, the shell is not accessible.
An SSH service is bundled with the Gateway to provide advanced debug access to the shell. The SSH service is not running by default, and there is no way to access the shell while it is disabled. When the Gateway service is started, an optional argument can be supplied to enable the SSH service component. When the SSH service is enabled, by default there are no accounts that can connect to it. A system administrator must create a key pair with an account to utilize SSH.
The Gateway shell does not provide commands to interact directly with secrets.
Keeper Commander can also be used to access the Gateway for troubleshooting. This leverages the connection between the Gateway and the Router, and the associated security mechanisms. For example, Commander can send a command to the Router to retrieve a list of running tasks on the Gateway. These commands can be used with any Gateway in the same enterprise as the Commander user.
Any secrets that are retrieved during rotation are automatically scrubbed from log messages produced by the Gateway. This includes accidental logging, such as stack traces.
Keeper Gateway supports the ability to execute admin-generated scripts in PowerShell and Bash for performing customized behaviors after a successful rotation has taken place. The script is provided to the Gateway through a file attachment in the corresponding Keeper record. Post-Rotation scripts are categorized differently from general file attachments, and only the record owner has the ability to attach post-rotation scripts on the corresponding record.
The script is decrypted by the Gateway and then executed on the Gateway. Connections to secondary devices, for the purpose of restarting services, etc., must be orchestrated within the post-rotation script.
Obviously, the script which is uploaded to the Keeper record and executed on the gateway must be protected from malicious abuse. Keeper Administrators need to ensure that least privilege is assigned to the Keeper record.
When Post-Rotation scripts are run, stdout and stderr output from the script are written to disk in logs. Secrets are also automatically scrubbed from this output. Record UIDs can be logged in this way for diagnostic purposes. The Post-Rotation script can be written with any arbitrary code, however the Keeper Gateway provides the script with minimal information required to perform standard use cases through the command-line parameters. This includes the following parameters:
PAM Rotation Record UID (contains environment settings)
Resource Record UID (contains target resource data)
Account Record UID (the record that was rotated)
Old Password (from Account Record)
New Password (from Account Record)
Username (from Account Record)
After the command is executed, Keeper Gateway clears the command line history on Linux and Windows instances.
In AWS environments, the configuration can be .
If a Post-Rotation script requires access to other secrets beyond those passed in automatically, users are strongly encouraged to use the or the tool.