Using encrypted keys (optional)

The utility stores these credentials as key, value pairs. You enter the key in the app.config file as ^<key>. When run, Resilient® Circuits gets the value for the key from the keyring. In the following example, resilient_secret is the key.

[resilient]
api_key_secret=^resilient_secret

Once you have created the keys in your app.config file, run res-keyring and you are prompted to create the secure values to store. In the following example, Free Desktop Secret Service is the keyring backend.

res-keyring 
Configuration file: /Users/kexample/.resilient/app.config
Secrets are stored with 'keyring.backends.SecretService'
[resilient] resilient_secret: <not set>
Enter new value (or <ENTER> to leave unchanged): 

Use the following procedure to use the Secret Service backend without an X11 server available.

1. Install the GNOME Keyring daemon:

   sudo yum install gnome-keyring

2. Start a D-Bus session:

   dbus-run-session -- sh
   sh-4.2$ gnome-keyring-daemon --unlock
   Passw0rd
   <CTRL-d>
   SSH_AUTH_SOCK=/run/user/1000/keyring/ssh

3. At the prompt, start the GNOME keyring daemon.

   sh-4.2$ gnome-keyring-daemon --unlock

4. Enter your password for ResilientKeyringPassword followed by the enter key then Ctrl-d.

   ResilientKeyringPassword
   <CTRL-d>
   SSH_AUTH_SOCK=/run/user/1000/keyring/ssh

   If gnome-keyring-daemon --unlock is run and there is no keyring, the GNOME keyring daemon creates a keyring with the provided password. The GNOME keyring information is stored in the following directory:

   ~/.local/share/keyrings/ 

5. List the keyring backends to verify that Secret Service is installed. For example:

   sh-4.2$ keyring --list-backends
   keyring.backends.SecretService.Keyring (priority: 5)
   keyring.backends.chainer.ChainerBackend (priority: 10)
   keyring.backends.fail.Keyring (priority: 0)
   

   In this example, the Secret Service backend is listed as the backend with highest priority after ChainerBackend which determines which backend to invoke.

6. Once the GNOME keyring is created, run the res-keyring utility to store the app.config credentials in the keystore, as described in Keyring utility.
7. When done, run Resilient Circuits on the command line in the D-bus session, which allows the integration server to access the credentials from the GNOME keyring.

   The GNOME keyring is unlocked while in the D-bus session, so you are not prompted for a keyring password when executing "resilient-circuits run" on the command line.

Once you have setup the GNOME keyring using res-keyring on the command line, you can run the integration server as a system service. However, you need to edit the service to make sure that the system can pass the keyring password to the systemd service for unlocking.

1. Edit service file /etc/systemd/system/resilient_circuits.service as follows to use the Secret Service backend:

   Description=Resilient-Circuits Service
   [Service]
   Type=simple
   User=integrations
   WorkingDirectory=/home/integrations/resilient-circuits-py3
   Environment=RES_KEYRING_PASSWORD=ResilientKeyringPassword
   ExecStart=/usr/bin/res-circuits.sh
   Restart=always
   TimeoutSec=10
   Environment=APP_CONFIG_FILE=/home/integrations/.resilient/app.config
   Environment=APP_LOCK_FILE=/home/integrations/.resilient/resilient_circuits.lock
   
   [Install]
   WantedBy=multi-user.target
   

   NOTE: The /etc/systemd/system/resilient_circuits.service file is owned by root. Only those users with privileges can view the password in the file.

2. Add the environment variable containing the GNOME keyring password:

   Environment=RES_KEYRING_PASSWORD=ResilientKeyringPassword

3. Look for the ExecStart line:

   ExecStart=/usr/local/bin/resilient-circuits run

4. Edit it to start Resilient Circuits from a shell script:

   ExecStart=/usr/bin/resilient-circuits.sh

The following resilient-circuits.sh script starts a dbus session and calls another script to unlock the keyring and start Resilient Circuits:

#!/bin/bash
dbus-run-session -- "/usr/bin/resilient-circuits-unlock-keyring.sh"

The /usr/bin/resilient-circuits-unlock-keyring.sh is as follows:

#!/bin/bash
echo $RES_KEYRING_PASSWORD | gnome-keyring-daemon --unlock
resilient-circuits run

Use the following procedure to use the keyrings.cryptfile backend:

1. Install the keyrings.cryptfile backend.

   pip3 install keyrings.cryptfile

2. List the keyring backends to verify that keyrings.cryptfile is installed. For example:

   keyring --list-backends
   keyrings.cryptfile.file.EncryptedKeyring (priority: 0.6)
   keyrings.cryptfile.cryptfile.CryptFileKeyring (priority: 2.5)
   keyring.backends.chainer.ChainerBackend (priority: 10)
   keyrings.cryptfile.file.PlaintextKeyring (priority: 0.5)
   keyring.backends.fail.Keyring (priority: 0)
   

3. Run the res-keyring utility to store the app.config credentials in the keystore, as described in Keyring utility.

The newly created cryptfile keyring is stored in the following location:

~/.local/share/python_keyring/cryptfile_pass.cfg

When you run resilient-circuits on the command line, you are prompted for the keyrings.cryptfile keyring password:

$ resilient-circuits run
Please enter password for encrypted keyring:

Once you have setup the keyring using res-keyring on the command line, you can run the integration server as a system service. However, you need to edit the service to make sure that the system can pass the keyring password to the systemd service for unlocking.

1. Edit service file /etc/systemd/system/resilient_circuits.service as follows to use the keyrings.cryptfile backend:

   Description=Resilient-Circuits Service
   [Service]
   Type=simple
   User=integrations
   WorkingDirectory=/home/integrations/resilient-circuits-py3
   Environment=RES_KEYRING_PASSWORD=ResilientKeyringPassword
   ExecStart=/usr/bin/res-circuits.sh
   Restart=always
   TimeoutSec=10
   Environment=APP_CONFIG_FILE=/home/integrations/.resilient/app.config
   Environment=APP_LOCK_FILE=/home/integrations/.resilient/resilient_circuits.lock
   
   [Install]
   WantedBy=multi-user.target
   

   NOTE: The /etc/systemd/system/resilient_circuits.service file is owned by root. Only those users with privileges can view the password in the file.

2. Add the environment variable containing the keyring password:

   Environment=RES_KEYRING_PASSWORD=ResilientKeyringPassword

3. Look for the ExecStart line:

   ExecStart=/usr/local/bin/resilient-circuits run

4. Edit it to start Resilient Circuits from a shell script:

   ExecStart=/usr/bin/res-circuits.sh

The /usr/bin/res-circuits.sh is as follows:

#!/bin/bash
echo $RES_KEYRING_PASSWORD | resilient-circuits run

For more information on the Windows Credential Locker, see:

https://docs.microsoft.com/en-us/windows/uwp/security/credential-locker

After installing Resilient Circuits, you can check that the Windows Credential Locker is in use:

keyring --list-backends
keyring.backends.chainer.ChainerBackend (priority: 0)
keyring.backends.Windows.WinVaultKeyring (priority: 5)
keyring.backends.fail.Keyring (priority: 0)

Then run res-keyring utility to store the app.config credentials in the Windows keystore:

res-keyring
Configuration file: C:\Users\integrations\.resilient\app.config
Secrets are stored with 'keyring.backends.Windows'
Please enter password for encrypted keyring: 
[resilient] password: ^res_password
  Enter new value (or <ENTER> to leave unchanged): Passw0rd
  Confirm new value: Passw0rd
Value set.
Done.