system.secrets.readSecretValue

New in 8.3.1

This function is used in Python Scripting.

Description

Reads the plaintext value of a secret given the name of the Secret Provider and the name of the secret. The PyPlaintext class contains a secret and performs much the same as the Java class Plaintext. To manage the lifecycle of the secret, returned as a PyPlaintext, either call the clear() method when finished or use a with...as statement to automatically clear the PyPlaintext.

Note that the system.secret.readSecretValue system function and PyPlaintext are not threadsafe.

Syntax

system.secrets.readSecretValue(providerName, secretName)

Parameters

Type	Parameter	Description
String	providerName	The name of the Secret Provider to read the secret from.
List	secretName	The name of the secret to read.

Returns

A PyPlaintext instance that contains the secret.

Scope

Gateway, Vision Client, Perspective Session

PyPlaintext Class

It is important to remember to clear the PyPlaintext instance after you are done accessing the secret. The preferred way to do so is use the Python with...as statement, as it is an efficient way to manage resource teardown. If the with...as statement is not appropriate for your use-case, you must clear the PyPlaintext instance manually using the clear() method.

• When using the getSecretAsString() methods, the returned string representing the secret is not cleaned up until garbage collection reclaims the memory.

• When using the getSecretAsBytes() method, the byte array returned is a direct reference to the bytes stored in the PyPlaintext instance. Therefore the array returned is cleared when the PyPlaintext is cleared. Refer to the Decode Returned Java Compatible Bytes code example below for options on what to do when the pyPlaintext instance is returned with getSecretAsBytes.

Code Examples

Code Snippet using a with...as Statement

with system.secrets.readSecretValue("InternalProvider1", "secret01") as plaintext:
   useSecret(plaintext.getSecretAsString()

Code Snippet using the clear() Method

pyPlaintext = system.secrets.readSecretValue(provName, secretName)

# The original secret is returned by calling methods on the returned PyPlaintext object. 
byteArray = pyPlaintext.getSecretAsBytes()
asString = pyPlaintext.getSecretAsString()

# When done using PyPlaintext, call the clear() method.
pyPlaintext.clear()

Decode Returned Java Compatible Bytes

# The following two examples show how to decode the Java compatible bytes 
# Returned from getSecretAsBytes().
byteArray = pyPlaintext.getSecretAsBytes()

# Option 1: Use Java String to decode to a string.
from java.lang import String
stringDecoded = str(String(byteArray, "UTF-8"))

# Options 2: Convert to python byteArray and decode to a string.
pyByte = byteArray(byteArraySecret)
stringDecoded = pyByte.decode("UTF-8")