Skip to content

Python API (beta)

Jump to bottom
Shams Asari edited this page Jan 25, 2023 · 3 revisions

There is a beta enclave Python API, which mirrors some of the Java API and has been ported to the following global functions:

  • on_enclave_startup() - equivalent to onStartup
  • on_enclave_shutdown() - equivalent to onShutdown
  • receive_from_untrusted_host(bytes) - equivalent to receiveFromUntrustedHost. The Java byte array is converted to Python bytes. If there’s no return value then it is treated as null, otherwise the return value is expected to be bytes.
  • receive_enclave_mail(mail) - equivalent to receiveMail. The Java EnclaveMail object is converted to a simpler Python equivalent which is just a class holding the body, envelope and authenticated sender. The topic and sequence number are ignored for now. The authenticated sender is represented by its encoded binary form in bytes. The return value (if there is one) is treated as a response and is encrypted as Mail back to the sender. A single bytes value is treated as the reponse body, whilst a tuple of bytes is treated as the body and envelope.

These functions need to be defined in a single Python file and are all optional. Not defining them is equivalent to not overriding the equivalent method from Enclave. The Python script must exist in the enclave Gradle module under src/main/python. Only one Python script is supported at this time. Otherwise, everything else is the same as a Java or Kotlin project. The Python enclave module needs to be part of a Gradle multi-module project with the host module taking a dependency to the enclave module.

The Python script also has access to an enclave_sign(data) global function, which allows the given data bytes to be signed by the enclave's private signing key. This is equivalent to signer() in the Java API.

Have a look at the PyTorch sample to see how this API is used.

How it works

Under the hood, the Python support is implemented using an "adapter" enclave which extends Enclave and behaves like a normal Java/Kotlin Conclave enclave. The enclave API calls are delegated to the Python script using Jep. Using this avoids having to re-implement all the underlying enclave, Mail and attestation code. Jep integrates with the Python/C API via JNI and thus should provide good compatibility with existing Python libraries.

Limitations

The Python API is not feature complete. There are several missing componentes, Some of which are:

  • Mock mode support is limited. There's currently no way to inspect objects from the Python environment without using reflection.
  • All the necessary tools, such as Python, pip and Gramine, must be installed locally.
  • Most likely the enclave will only work on the same machine that it was built on.
  • Only a single Python file is supported.
  • There's no API yet to send responses to other than the requester.
Clone this wiki locally