Package com.inductiveautomation.ignition.gateway.secrets

package com.inductiveautomation.ignition.gateway.secrets

Secrets Management

Management of secrets are broken down into two systems:
  1. Embedded Secrets
  2. Referenced Secrets

Embedded Secrets

Embedded secrets are secrets which various subsystems embed within their own configuration settings. They are managed by the relying subsystems themselves and are not centrally managed by the Platform. One of the main adopters of embedded secrets is the Platform's configuration system.

Encrypting Secrets

To embed secrets in your own subsystem, first grab the instance of SystemEncryptionService from the GatewayContext: 

     SystemEncryptionService systemEncryptionService = gatewayContext.getSystemEncryptionService();

Next, wrap your secret in a Plaintext instance and pass this plaintext secret value to the SystemEncryptionService's encryptToJson method to encrypt your plaintext secret into JSON-encoded ciphertext: 

     Plaintext plaintext = Plaintext.ofString("super secret password");
     JsonElement ciphertext = systemEncryptionService.encryptToJson(plaintext);

Finally, save the resulting JSON-encoded ciphertext in durable storage where you can later retrieve the secret when it is needed.

Decrypting Secrets

To decrypt secrets embedded in your own subsystem, grab the instance of SystemEncryptionService from the GatewayContext as mentioned above, then pass the JSON-encoded ciphertext to the SystemEncryptionService's decryptFromJson method: 

     Plaintext plaintext = systemEncryptionService.decryptFromJson(ciphertext);

Referenced Secrets

Referenced secrets are secrets stored in a SecretProvider. Relying subsystems reference these secrets using the pair of secret provider name and secret name.

To fetch a SecretProvider by name, first get the SecretProviderManager: 

     SecretProviderManager secretProviderManager = gatewayContext.getSecretProviderManager();

Next, fetch a SecretProvider by name: 

     Optional<SecretProvider> optSecretProvider = secretProviderManager.getProvider(name);

Once you have a SecretProvider, you can read the current value of secrets it manages using the secret name as the reference: 

     Plaintext plaintext = secretProvider.read(secretName);

You may also write a new value to the named secret in the target provider: 

     secretProvider.write(secretName, plaintext);

Implementing a new type of SecretProvider

SecretProviders are extension points. If you would like to implement your own SecretProvider:

  1. Implement the SecretProvider interface. Optionally implement Lifecycle if the SecretProvider has the standard startup and shutdown lifecycle and theSecretProviderManager should drive that lifecycle.
  2. Implement the SecretProviderType interface whose createProvider method returns a new instance of the SecretProvider implementation above
  3. Include your SecretProviderType in the List returned from your GatewayModuleHook's getExtentionPoints() method.