Introduction

JS7 - Encryption and Decryption can be integrated with Secret Manager products in a number of ways. Basic requirements include:

  • The Secret Manager is the sole source holding a secret. Secrets can be updated/rotated at any point in time.
  • The Secret Manager stores encrypted secrets to JS7 - Job Resources.
  • Jobs read encrypted secrets from Job Resources and decrypt on-the-fly.

Integration

Use with Job Resources

Encrypting Secrets to Job Resources


Explanation:

  • The Secret Manager encrypts a secret using the target Agent's certificate and stores the encrypted result to a Job Resource variable.
  • The Job Resource variable is assigned an environment variable that will be made available to jobs using the Job Resource.
  • Examples:

    • For details see JS7 - How to update a Job Resource using Unix Shell.

      Example for Encryption using Unix Shell
      ./js7_set_job_resource.sh \
          --url=http://joc-2-0-primary:7446 \
          --controller-id=controller \
          --user=root \
          --password=root \
          --job-resource=/ProductDemo/Variables/pdDatabaseSecret \
          --key=databasePassword \
          --value='12345678' \
          --env-var='DATABASE_PASSWORD' \
          --encrypt-cert=foobar.crt
    • For details see JS7 - How to update a Job Resource using PowerShell.

      Example for Encryption using PowerShell
      Set-JS7JobResource `
          -Path /ProductDemo/Variables/pdDatabaseSecret `
          -Key 'databasePassword' `
          -Value '12345678' `
          -EnvVar 'DATABASE_PASSWORD' `
          -EncryptCertificatePath foobar.crt `
          -JavaLib /js7/js7.encryption/lib
    • Example how to use Bitwarden® CLI to retrieve a password and to store the encrypted password to a Job Resource:

      Example for Encryption using Bitwarden CLI and Unix Shell
      Get_Secret()
      {
          item="$1"
      
          if [ -f $HOME/.bw.session.lock ]
          then
          	BW_SESSION="$(bw unlock --passwordenv $BW_PASSWORD)"
          else
       	    BW_LOGIN=$(bw login -apikey && touch $HOME/.bw.session.lock)
          fi
      
          response_json=$(bw list items --search "${item}")
          item_count=$(printf "%s" "${response_json}" | jq ". | length")
      
          if [ "${item_count}" -eq 1 ]
          then
              printf "%s" "${response_json}" | jq -r ".[].login.password // empty"
          else
              if [ "${item_count}" -eq 0 ]
              then
                  >&2 echo "no matching item found in vault for: ${item}"
              else
                  >&2 echo "more than one matching item found in vault for: ${item}"
              fi
          fi
      }
      
      ./js7_set_job_resource.sh \
          --url=https://joc-2-0-primary:7443 \
          --controller-id=controller \
          --user=root \
          --password=root \
          --job-resource=/ProductDemo/Variables/pdDatabaseSecret \
          --key=databasePassword \
          --value=$(Get_Secret "database-login") \
          --env-var='DATABASE_PASSWORD' \
          --encrypt-cert=foobar.crt


      Explanation:

      • The script requires the jq utility to be available from the operating system.
        jq ships with the MIT license, see https://opensource.org/licenses/MIT.
      • Login to JOC Cockpit can be performed using username/password or using a Client Authentication Certificate, see JS7 - Certificate Identity Service.
      • Line 5-10: There are a number of ways how to login and to unlock the vault using Bitwarden CLI. Users should adjust this section.
      • Line 17: The JSON returned by Bitwarden CLI depends on the type of secret (1=login, 2=secure note etc.) and will require adjustments to select the desired property.

Decrypting Secrets from Jobs



Explanation:

  • The Job Resource is assigned the workflow to make environment variables available to all jobs or is assigned individual jobs. JS7 takes care to transfer the Job Resource to all Agents that operate workflows or jobs which are assigned the Job Resource. The environment variables specified with the Job Resource are automatically available for shell jobs. 

  • The job decrypts a secret using the assigned Agent's Private Key.
  • Examples:

    • For details see JS7 - How to encrypt and decrypt using Unix Shell

      Example for Decryption using Unix Shell
      # encrypted result is assumed being available from DATABASE_PASSWORD environment variable
      secret=$($JS7_AGENT_HOME/bin/js7_decrypt.sh \
          --key=$JS7_AGENT_CONFIG_DIR/private/foobar.key \
          --in="$DATABASE_PASSWORD")
      echo $secret
    • For details see JS7 - How to encrypt and decrypt using Windows Shell

      Example for Decryption using Windows Shell
      @rem encrypted result is assumed being available from DATABASE_PASSWORD Job Resource environment variable
      call "%JS7_AGENT_HOME%\bin\js7_decrypt.cmd" ^
          "--key=%JS7_AGENT_CONFIG_DIR%\foobar.key" ^
          "--in=%DATABASE_PASSWORD%"
      @echo %JS7_DECRYPT_VALUE%
    • For details see JS7 - How to encrypt and decrypt using PowerShell

      Example for Decryption using PowerShell
      # encrypted result is assumed being available from DATABASE_PASSWORD Job Resource environment variable
      $secret = Invoke-JS7Decrypt `
          -Value $env:DATABASE_PASSWORD `
          -KeyPath $env:JS7_AGENT_CONFIG_DIR/private/foobar.key `
          -JavaLib $env:JS7_AGENT_HOME/lib
      Write-Output $secret

Use with Secret Managers

  • Secret Manager products are used for lifecycle management of secrets, for example to create, to update, to rotate and to delete secrets.
  • Secret Manager products typically offer one or more of the following interfaces:
    • Command Line Interface: The Secret Manager CLI can be executed to retrieve a secret. The JS7 encryption scripts can be used to encrypt the secret for later use with JS7 products.
    • Event interface: The Secret Manager triggers events when a secret is changed. Typically Secret Managers offer hooks to forward changed secrets to applications such as JS7. This includes an automation scenario when passwords are rotated at regular basis. Hooks can include to execute a shell script, to implement a REST API call etc.
  • For CLI/Event integration the following JS7 interfaces can be used:
  • The recommended architecture includes that the Secret Manager forwards changed secrets to JS7.
    • It is not a perfect option that JS7 will access the Secret Manager in order to check if a secret changed.
    • One reason being that this approach will shift security risks as JS7 would have to authenticate with the Secret Manager at run-time. Availability and accessibility of the Secret Manager would be crucial which is a bad idea considering high availability of the job scheduling solution.
    • Another reason being that the Secret Manager knows the point in time when a secret is changed. It's a waste of resources to repeatedly access the Secret Manager if the secret did not change.

Key Distribution

Keys can be distributed in a number of ways. Frequent scenarios include:

  • Secret Manager products offering hooks to forward secrets to JS7 can encrypt secrets with the receiving Agent's Certificate or Public Key. If more than one Agent needs access to the same sensitive information,
    • the same secret can be encrypted a number of times using individual Certificates/Public Keys per Agent,
    • the secret can be encrypted once and the same Private Key can be shared by a number of Agents. This applies to use of secrets in an Agent Cluster if jobs on any Agent should access the same secret.
  • Certificates and Public Keys include no sensitive information. There is no harm in making an Agent's Certificate available from a PEM file known to the Secret Manager product.

Further Resources