Platform Public Key

Fetch and cache the platform public key used to wrap document keys for enclave processing.

Before uploading an encrypted document, the client fetches Literal’s platform public key. The client uses this key to wrap the document encryption key for enclave processing. The application server stores the wrapped key but cannot unwrap it.

What The Platform Public Key Is

The Platform Master Key is a hardware-protected key used by the attested enclave path. The platform private key is available only through the attested enclave and key-management path and is not exposed to application code or server operators.

The private key can be used only after the enclave/key-management path passes attestation. The public key returned from this endpoint identifies the key version clients should use for wrapping.

The platform key is distinct from a document holder’s personal master key. The personal master key is derived from the user’s password and stays on the client device. See Key Hierarchy for the full key model.

Why The Client Fetches It

When uploading a document, the client wraps the document encryption key along multiple authorized paths:

With the document holder’s personal master key, so the document can be decrypted later.
With the platform public key, so the enclave can unwrap it during authorized processing (verification, seal generation, indexing).

The platform-wrapped copy is required for enclave processing. Without it, the document cannot complete processing.

Current Wrapping Key

The current platform public key response exposes the classical ECC public key used for platform wrapping. If hybrid platform wrapping is added later, the response schema and API Reference will identify the additional key material.

For broader cryptography context, see Key Hierarchy.

Fetch The Current Key

Endpoint: GET /v1/public-keys/server

The response includes a key identifier, key specification, public key material, and algorithm metadata. Use the API Reference for the exact response schema.

The endpoint is unauthenticated.

Use In Document Upload

The client uses the returned public key to derive a wrapping key, encrypt the document encryption key, and submit the result as the platform-wrapped document key during document creation.

This is Step 1 of Document Upload. Fetch the platform key before encrypting and wrapping the document key.

Caching And Rotation

Cache the platform public key by key_id. Do not hard-code the key or assume it never rotates.

Before wrapping a document key:

Use the cached key if it is still fresh.
Re-fetch if the cache is stale.
If document creation fails with a key-version mismatch, evict the cached key, fetch the current key, re-wrap the document key, and retry.

Always track which key_id was used to wrap a document key. Rotation requires re-wrapping with the current platform key.

Troubleshooting

If key fetch is rate-limited, back off and retry.
If key fetch fails during enclave or key-management startup, retry with backoff.
If document creation rejects the wrapped key, refresh the platform key and re-wrap before retrying.

See Error Handling and the API Reference for status-specific responses.

Document Upload — Step 1 of the upload flow uses this endpoint directly.
Key Hierarchy — how platform keys relate to personal, organization, and document keys.
Zero-Knowledge Model — the trust boundaries around enclave processing.
API Reference — exact platform key endpoint schema.

Last updated on

On this page