Using sensitive data in custom scripts

When using the Lenovo XClarity One portal web interface, sensitive data (such as passwords) is encrypted in the web browser before being transmitted to the portal and then stored on the hubs. The encryption details are stored in a secure object called a secret entity, which is also stored on the hubs. Only the selected hubs can decrypt the sensitive data.

When using custom scripts, you must manually encrypt the sensitive data and create the required secret entities before referencing them in your REST API scripts.

Important

At least one healthy hub must be available in the organization to create and store secret entities.

Follow these steps to create a secret entity using the REST APIs and encrypt sensitive data.

Invoke POST /apis/v1/storage/secretEntities to initialize a secret entity and return information about it.

You can optionally specify one or more healthy hubs to store the secret entity. If not specified, the portal will choose a healthy hub for you.

You can also choose the amount of time, in hours, that the secret entity is to remain active (or 0 if you want it to never expire).

The following example request creates a secret entity that never expires and stores it on a specific hub.

{
    "hubs": ["220D89DD5CD64F77931ADF5B38D9E486"],
    "ttl": 0
}

The secret entity ID and asymmetric public key are returned in the response.

{
    "id": 1234567890ABCDE1234567890
    "pubKeystring": "-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtWw2Xr6YlF7k3lG2YJqM
Z3H1l0XJQ7b7x8xk5vFq7K1uYp8R0bX5VQk0ZcX9X8V0Q9J1p7Qk2Yv8wXh2tQ9m
4uKkY9zZ9f3t3cYlKj1g0dP6x2zLk9m3a7sVt5x2m9q1Zb6cV8n3p5d7f9k2l4m6
n8p0q2r4s6t8u0v2w4x6y8z0A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0
U1V2W3X4Y5Z6a7b8c9d0e1f2g3h4i5j6k7l8m9n0o1p2q3r4s5t6u7v8w9x0y1z2
QIDAQAB
-----END PUBLIC KEY-----"
}

Encrypt the sensitive data using the AES-128-GCM algorithm with a 16-byte random key and a 12-byte random nonce (also known as IV).
The encryption process produces:
- Base64-encoded encrypted sensitive data
- 16 bytes authTag (used during decryption to verify that the data has not been tampered with)
Note
For security reason, use a new random key and nonce pair for each sensitive data that you want to encrypt.
Encrypt the encryption details (key, nonce and authTag).
1. Concatenate the nonce, key and authTag (in this order) obtained in step 2.
2. Encrypt the concatenated encryption details using the RSA-OAEP-SHA1 algorithm with the public key returned in step 1
3. Encode the resulting encrypted output in Base64.

Invoke PATCH /apis/v1/storage/secretEntities/:id to add the base64-encoded encryption details generated in step 3 to the secret entity, where :id is the secret entity ID returned in step 1.

The following example request adds the base64-encoded encryption details to the secret entity.

{
    "op":"add",
    "path":"encryptionDetails",
    "value":"base64_encoded_encryption_details" 
}

To use sensitive data in your REST API scripts, you must provide the secret entity ID (returned in step 1), the encrypted sensitive data (generated in step 2), and the data type (string).

Give documentation feedback