Guides

Generating Obfuscated Entries

Suggest Edits

Example of an obfuscated string that is encrypted with a shared secret (Recommended)

Configuration data can also be provided as encrypted entries, which are obfuscated by using a shared secret or password. The shared secret is provided in the secrets section of the provider.yml and is used to decrypt all OBF: prefixed entries found within the configuration YAML.

The following example shows the data NSTlodCsvxqUNbOz being encrypted with the shared secret myISVAOPExampleSecret:

echo -n "NSTlodCsvxqUNbOz" | openssl enc -aes256 \
  -pbkdf2 -md sha512 -pass pass:"myISVAOPExampleSecret" \
  -base64

Note: OpenSSL 1.1.1 or newer is required for the previous command.

This command produces a base 64 string similar to U2FsdGVkX19D+jM/0YdnFWXZEmW8Mo3+4eTZ9UwqsUAeHNvVGW/12vMM83DoNE4N.

Note: Due to salting, you should expect that this command will produce a different encrypted representation of the input data each time it is executed.

Entire files can also be obfuscated with a similar command:

The resulting encrypted base 64 string can be provided to ISVAOP using the OBF: prefix:

Example configuration entry in provider.yml

version: "24.08"
secrets:
  obf_key: "myISVAOPExampleSecret"
...

Example configuration entry in client01.yml


client_id: client01                                                                       # Client identifier
client_secret: "OBF:U2FsdGVkX19D+jM/0YdnFWXZEmW8Mo3+4eTZ9UwqsUAeHNvVGW/12vMM83DoNE4N"                                                                            # Client secret that is used for client authentication and/or JWT signing/encryption. `OBF:` indicates obfuscated string.
client_name: Client One

Reversing an Obfuscated String

An obfuscated string can be reversed by using a technique similar to the one used to create it:

[demouser@demovm ~]$ echo "U2FsdGVkX19D+jM/0YdnFWXZEmW8Mo3+4eTZ9UwqsUAeHNvVGW/12vMM83DoNE4N" | openssl enc -d -aes256 \
  -pbkdf2 -md sha512 -pass pass:"myISVAOPExampleSecret" \
  -base64

Detailed description of the expected format for encrypted data

The requirements for an obfuscated entry are:

  • The data must be encrypted with the AES-256 cipher -aes256
  • The key used to encrypt the data must:
    • be derived from a passphrase, which can be supplied in the YAML -pass pass:<passphrase>
    • was derived by using the PBKDF2 algorithm -pbkdf2
    • use SHA-512 message digest -md sha152
    • perform 10,000 iterations -iter 10000 (Note: This setting is the current default for OpenSSL.)
  • The data must be base64 encoded -base64
  • When base64 decoded, the data must be in OpenSSL format:
    • Bytes 0-7 is Salted__
    • Bytes 8-15 is the salt that is used while the key is derived
    • Byte 16 onwards is the encrypted data

Example Encrypted (Encrypted with RSA) String

Configuration data can also be provided as RSA encrypted entries. The private key required to decrypt the entry is provided in the secrets section of the Provider YAML and is used to decrypt all ENC: prefixed entries found within the configuration YAML.

To use RSA encryption, generate a private certificate:

[demouser@demovm ~]$ openssl genrsa -out private.pem 2048

This private certificate will be used to decrypt the entries and must be provided in the configuration YAML. To create encrypted entries, generate a corresponding public key which will be used for the encryption operations:

[demouser@demovm ~]$ openssl rsa -pubout -in private.pem -out public.pem

The following example shows the data NSTlodCsvxqUNbOz being encrypted with the public key public.pem and base64 encoded:

[demouser@demovm ~]$ echo -n "NSTlodCsvxqUNbOz" | openssl rsautl -encrypt -inkey public.pem -pubin | base64

This command produces a base 64 encoded string. The encrypted base 64 encoded string can be provided to ISVAOP using the ENC: prefix:

Example configuration entry in provider.yml

version: "24.08"
secrets:
  enc_key: "@private.pem"
...

Example configuration entry in client01.yml


client_id: client01                                                                       # Client identifier
client_secret: "ENC:L54YvgvQBX4TG+S1MM88QCAo/aJSCXLRYuGS9+QUHbKUKap6Re9IgBouZn..."                                                                                         # Client secret that is used for client authentication and/or JWT signing/encryption. `ENC:` indicates encrypted string.
client_name: Client One

Note: Any number of values in the configuration YAML can be encrypted, however they must all require the same private key for decryption. Only a single RSA private key can be provided for an ISVAOP instance.

Reversing an Obfuscated String

An obfuscated string can be reversed by using a technique similar to the one used to create it:

[demouser@demovm ~]$ echo -n "L54YvgvQBX4TG+S1MM88QCAo/aJSCXLRYuGS9+QUHbKUKap6Re9..." \
| base64 -d | openssl rsautl -decrypt -inkey private.pem

Using the Encrypted and Obfuscated Types Together

The amount of data which can be encrypted using this technique is limited by the size of the RSA private key. To protect entries which are too large for RSA encryption, it is recommended that the following pattern using both encryption and obfuscation is adopted:

  1. Entries are obfuscated using the OBF:<value> technique
  2. The obfuscation key/shared secret is encrypted using the ENC:<value> technique

Example configuration entry in provider.yml

version: "24.08"
secrets:
  enc_key: "@private.pem"
  obf_key: "ENC:OsG1/Aw5iNpP/AutK9q0bVF5z1sO/psBvpY7zpRpd8V..."

Example configuration entry in client01.yml


client_id: client01                                                                       # Client identifier
client_secret: "OBF:U2FsdGVkX19D+jM/0YdnFWXZEmW8Mo3+4eTZ9UwqsUAeHNvVGW/"                                                                                         # Client secret that is used for client authentication and/or JWT signing/encryption. `ENC:` indicates encrypted string.
client_name: Client One

Updated 3 months ago