[Hold][WIP] Workflow Endpoint: how to encrypt secrets

[Paul-Cornell]

Work in progress. Still waiting for renamed "retrieve" endpoint, and certificate signing.

For now, see:

• Main secrets how-to page: https://unstructured-53-doc-4-secrets-api.mintlify.app/api-reference/workflow/secrets
• Updated Google Drive source connector API how-to page (scroll to bottom, look for yellow caution box especially): https://unstructured-53-doc-4-secrets-api.mintlify.app/api-reference/workflow/sources/google-drive

[awalker4]

Added some comments! I can add a commit to this branch to update the code samples once the new certificate flow is ready. Some other thoughts:

• I think the pattern of showing redacted on the encrypted text is a bit noisy. It's instructive to show the ---BEGIN PUBLIC KEY--- headers and such, but the other text will always be garbled nonsense, so there's nothing to "hide". Maybe just ellipses?

{
    "encrypted_aes_key": "x3+......9zD",
    "aes_iv": "k2N......g==",
    "encrypted_value": "gM1......A2m",
    "type": "rsa_aes"
}

[awalker4]

Suggested change

	Instead of programmatically sending a secret to Unstructured in plain text, which presents a security risk,
	There are inherent risks to sending plaintext secrets over a network. For stronger security, you may choose to use Unstructured's process for encrypting secrets locally as follows:

For now our stance is that this is more secure but it isn't backwards incompatible (except for GDrive). We'll also need to confirm that SecretReference is accepted by all connectors before pushing this approach too broadly.

[awalker4]

Suggested change

	1. Call Unstructured to get the Privacy Enhanced Mail (PEM) version of the public key for your Unstructured user account.
	1. Call Unstructured to get the RSA public key associated with your Unstructured user account.

The pem detail is probably too in the weeds. For the security minded folks who are doing this, the file format goes without saying. "RSA public key" is the right level of detail.

[awalker4]

Suggested change

	2. Use this PEM to encrypt your plain-text secret locally.
	2. Use this key to encrypt your plaintext secret locally.

[awalker4]

Suggested change

	Unstructured plans to add this requirement to other source and destination connectors in the future.
	Unstructured plans to support this workflow with other source and destination connectors in the future.

[awalker4]

Suggested change

	complete the step of encrypting the plain-text secret locally. Otherwise, both approaches are shown for the other steps.
	complete the step of encrypting the plaintext secret locally. Otherwise, both approaches are shown for the other steps.

[awalker4]

Suggested change

	While you can use a REST API client such as `curl` or Postman to complete most of the following steps, you can only use Python to
	While you can use a REST API client such as `curl` or Postman to complete most of the following steps, you can only use Python or another encryption language library to

[awalker4]

Suggested change

	## Step 1: Get the PEM version of the public key
	## Step 1: Get the RSA public key

[awalker4]

Suggested change

	## Step 4: Use the registered secret's ID and encryption type
	## Step 4: Use the registered secret's reference ID

[awalker4]

See this notebook for an updated flow once https://github.com/Unstructured-IO/platform-api/pull/544 is merged. The response from GET /users/secrets/encryption-certificate can be passed directly into the encrypt function that is now copied into the SDK. The result from this can likewise go straight to the store_secret function.