API security
Ce contenu n’est pas encore disponible dans votre langue.
Subnoto’s API is served by a secure enclave. To protect your data and guarantee you are talking to a genuine Subnoto enclave, all application traffic uses remote attestation and a secure tunnel. That is why you cannot call the enclave with plain REST and API keys: you must use either an SDK (TypeScript or Python) or the API Proxy container.
Remote attestation
Section titled “Remote attestation”The enclave proves its identity and integrity to the client before any application data is exchanged. This is remote attestation: the enclave produces evidence that it is running on expected hardware, expected operating system, and expected (unmodified) Subnoto code. The client verifies this evidence using a public attester key that Subnoto publishes (see TypeScript SDK - Attestation). The SDK and the API Proxy container each perform attestation; they only continue the handshake if it succeeds, so you do not send sensitive data to an unverified endpoint.
Secure tunnel
Section titled “Secure tunnel”All application traffic to the enclave goes over an encrypted session (Oak-based), not plain JSON over HTTPS:
- Handshake - The client and enclave run a multi-step handshake (e.g.
POST /tunnel/sessionwith binary payloads). During this, attestation is verified and a shared session is established. - Encrypted traffic - After the handshake, every API request is encrypted by the client and decrypted inside the enclave; responses are encrypted by the enclave and decrypted by the client. The enclave does not accept unencrypted API payloads.
For API access from your backend you have two options:
- SDK (TypeScript or Python): The SDK uses an Oak client (native bindings) in your process. It performs the handshake and encrypts/decrypts each request. You get a typed API; the SDK handles attestation and the tunnel.
- API Proxy container: The API Proxy is a separate service that runs the same Oak-based tunnel and attestation. It
talks to the enclave over the secure tunnel and exposes local REST (e.g.
http://localhost:8080). You send plain REST requests to the proxy; the proxy encrypts them and forwards them to the enclave.
So from the outside, there is no “REST over HTTPS” to the enclave for your API calls - only tunnel-protected messages.
Why you cannot use the REST API without an SDK or the API Proxy
Section titled “Why you cannot use the REST API without an SDK or the API Proxy”The enclave API expects tunnel-encrypted messages and attestation. It does not accept plain REST requests with API keys. You must use one of:
- SDK (TypeScript or Python): Performs attestation and the tunnel handshake, encrypts your requests and decrypts responses, and exposes a normal API interface (e.g. typed methods). You write standard code; the SDK handles security.
- API Proxy container: A separate service that runs attestation and the tunnel. It talks to the enclave over the
secure tunnel and exposes local REST (e.g.
http://localhost:8080). You usecurlor any HTTP client against the proxy; the proxy handles the tunnel.
In both cases, the tunnel and attestation are mandatory. There is no supported way to call the enclave with raw REST and API keys only.
Full security details
Section titled “Full security details”For Subnoto’s full security model, attestation, and architecture, see the Subnoto whitepaper (PDF). It covers threat model, confidential computing, and design in depth.