SecretManager
- Last UpdatedFeb 19, 2025
- 4 minute read
The SecretManager node enables you to protect and unprotect any string using Windows DPAPI for Windows and for NX (IOS and Android) using Secure Storage.
(Only for Windows and WinNX) The strings protected by this node can be unencrypted only at two conditions:
-
The entropy used to encrypt is known.
-
The application that runs the engine is running under the same Windows user that protected it.
The string, from a cybersecurity standpoint, once encrypted can be considered as secure as the Windows user account is. An additional extra layer of security is granted by the unique entropy string used to encrypt.
Platform support
This node is fully supported on all platforms except XR Portable Wasm.
|
XR-WIN |
XR-P-WIN |
XR-P-IOS |
XR-P-AND |
XR-P-WASM |
|---|---|---|---|---|
|
Full support |
Full support |
Full support |
Full support |
No support |
|
|
|
|
|
|
DPAPI Protection (For Windows and WinNX)
When a SecretManager node is created, it is possible to use its sfunction fields to protect and unprotect secrets.
Example: <SecretManager name="secretNode" />
SecretManager on Windows uses Windows DPAPI. The DataProtectionScope is fixed and is set to CurrentUser [0]. Therefore, only threads running under the same Windows user can decrypt (unprotect) a protected secret.
Refer to the official documentation about DataProtectionScope at https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.dataprotectionscope?view=netframework-4.8
Secure Storage Protection (For NX)
Security Storage Protection uses the underlying OS Secure Storage solutions (for example: on iOS the Apple Keychain) to securely store simple key/value pairs that are accessible from within the scope of the application.
Please note that for this reason, on Android and iOS, any app running on the platform can read only entries in the Secure Storage added by the app itself. This can complicate deliveries to mobile devices.
Entropy value (For Windows and WinNX)
Protection process also requires an additional Entropy value, which can grant an additional layer of security to the encrypted secret.
It is strongly recommended to use unique entropy values for each secret, and consider the entropy as a secret too.
-
Valid unique entropy values can be generated to provide strings to the node's dedicated field getContextualEntropy.
-
Providing unique strings as a parameter would result in receiving back unique entropy values.
-
Passing an empty string as entropy would result in disabling this extra layer of protection.
Secret Manager fields
These are the fields for SecretManager node. Only the node-specific fields are indicated, not fields obtained by inheritance.
Field inheritance: NodeBase > Context > SecretManager
|
Fields |
Type |
Use |
Default value |
Description |
|---|---|---|---|---|
|
getContextualEntropy |
sfunction |
Optional |
Not set |
SSTRING getContextualEntropy(SSTRING) Returns a valid entropy string for the provided string parameter. The returned entropy string can be used to both protect and unprotect a secret. For example: getContextualEntropy ("xrstudio") |
|
protect |
sfunction |
Optional |
Not set |
(For Windows and WinNX) SSTRING protect(SSTRING entropy,SSTRING secret) This sfunction returns the encrypted string. Parameters are entropy and secret (comma separated). For example: protect(AB64DC222-4F,mySecret) (For NX) protect(SSTRING key,SSTRING value) This sfunction does not return any encrypted string, it just protects the value and store. and to get back the value, we need to call the unprotect sfunction with the key, and will return back the value Parameters are key and value(comma separated). For example: protect(AB64DC222-4F,mySecretValue) |
|
unprotect |
sfunction |
Optional |
Not set |
(For Windows and WinNX) SSTRING unprotect(SSTRING entropy,SSTRING encryptedString) This sfunction unencrypts the provided string using the provided entropy. Parameters are entropy and encryptedString (comma separated). The entropy passed must match the entropy used for protecting the original secret. For example: unprotect(AB64DC222-4F,myEncryptedSecret) unprotect(SSTRING key) This sfunction returns the value which is associated with the key provided as a parameter. Parameters is key, and it returns the value associated with the key For example: unprotect(AB64DC222-4F). |