EnclaveHost

public class EnclaveHost implements AutoCloseable

Represents an enclave running on the local CPU. Instantiating this object loads and initialises the enclave, making it ready to receive connections.

You can get a EnclaveHost using one of the static factory methods.

An enclave won't actually be loaded and initialised immediately until the start method is explicitly called. This gives you time to configure the EnclaveHost before startup.

Multiple enclaves can be loaded at once, however, you may not mix simulation/debug/production enclaves together.

Although the enclave must currently run against Java 8, the host can use any version of Java that is supported.

Constructors

EnclaveHost
Link copied to clipboard
EnclaveHost EnclaveHost()

Methods

callEnclave
Link copied to clipboard
byte[] callEnclave(byte[] bytes)

Passes the given byte array to the enclave. The format of the byte arrays are up to you but will typically use some sort of serialization mechanism, alternatively, DataOutputStream is a convenient way to lay out pieces of data in a fixed order.

For this method to work the enclave class must override and implement receiveFromUntrustedHost The return value from that method (which can be null) is returned here. It will not be received via the provided callback.

The enclave does not have the option of using Enclave.callUntrustedHost for sending bytes back to the host. Use the overload which takes in a callback Function instead.

Any uncaught exceptions thrown by receiveFromUntrustedHost will propagate across the enclave-host boundary and will be rethrown here.

byte[] callEnclave(byte[] bytes, Function<byte[], byte[]> callback)

Passes the given byte array to the enclave. The format of the byte arrays are up to you but will typically use some sort of serialization mechanism, alternatively, DataOutputStream is a convenient way to lay out pieces of data in a fixed order.

For this method to work the enclave class must override and implement receiveFromUntrustedHost The return value from that method (which can be null) is returned here. It will not be received via the provided callback.

With the provided callback the enclave also has the option of using Enclave.callUntrustedHost and sending/receiving byte arrays in the opposite direction. By chaining callbacks together, a kind of virtual stack can be constructed allowing complex back-and-forth conversations between enclave and untrusted host.

Any uncaught exceptions thrown by receiveFromUntrustedHost will propagate across the enclave-host boundary and will be rethrown here.

close
Link copied to clipboard
void close()
deliverMail
Link copied to clipboard
void deliverMail(byte[] mail, String routingHint)

Delivers the given encrypted mail bytes to the enclave. The enclave is required to override and implement receiveMail to receive it. If the enclave throws an exception it will be rethrown. It's up to the caller to decide what to do with mails that don't seem to be handled properly: discarding it and logging an error is a simple option, or alternatively queuing it to disk in anticipation of a bug fix or upgrade is also workable.

It's possible the callback provided to start will receive a MailCommand.PostMail on the same thread, requesting mail to be sent back in response. However, it's also possible the enclave will hold the mail without requesting any action.

If the enclave is not unable to decrypt the mail bytes then a MailDecryptionException is thrown. This can happen if the mail is not encrypted to the enclave's key, which will most likely occur if the enclave was restarted and the client had used the enclave's old encryption key. In such a scenerio the client must be informed so that it re-send the mail using the enclave's new encryption key.

Note: The enclave does not have the option of using Enclave.callUntrustedHost for sending bytes back to the host. Use the overload which takes in a callback Function instead.

void deliverMail(byte[] mail, String routingHint, Function<byte[], byte[]> callback)

Delivers the given encrypted mail bytes to the enclave. The enclave is required to override and implement receiveMail to receive it. If the enclave throws an exception it will be rethrown. It's up to the caller to decide what to do with mails that don't seem to be handled properly: discarding it and logging an error is a simple option, or alternatively queuing it to disk in anticipation of a bug fix or upgrade is also workable.

It's possible the callback provided to start will receive a MailCommand.PostMail on the same thread, requesting mail to be sent back in response. However, it's also possible the enclave will hold the mail without requesting any action.

If the enclave is not unable to decrypt the mail bytes then a MailDecryptionException is thrown. This can happen if the mail is not encrypted to the enclave's key, which will most likely occur if the enclave was restarted and the client had used the enclave's old encryption key. In such a scenerio the client must be informed so that it re-send the mail using the enclave's new encryption key.

enableHardwareEnclaveSupport
Link copied to clipboard
static void enableHardwareEnclaveSupport()

Some platforms support software enablement of SGX, this method will attempt to do this. This may require elevated privileges and/or a reboot in order to work. The method is safe to call on machines where SGX is already enabled.

getEnclaveClassName
Link copied to clipboard
String getEnclaveClassName()

The name of the sub-class of Enclave that was loaded.

getEnclaveInstanceInfo
Link copied to clipboard
EnclaveInstanceInfo getEnclaveInstanceInfo()

Provides the info of this specific loaded instance. Note that the enclave instance info will remain valid across restarts of the host JVM/reloads of the enclave.

getEnclaveMode
Link copied to clipboard
EnclaveMode getEnclaveMode()

The mode the enclave is running in.

getMockEnclave
Link copied to clipboard
Object getMockEnclave()

For mock mode, the instance of the Enclave that is loaded by the host. This should be cast to the type of Enclave that has been loaded and can be used to examine the state of the enclave.

For anything other than mock mode attempting to access this property will result in an IllegalStateException being thrown.

getSupportedModes
Link copied to clipboard
static Set<EnclaveModegetSupportedModes()

Determine which enclave modes are supported on the current platform. Irrespective of the current project mode.

isHardwareEnclaveSupported
Link copied to clipboard
static boolean isHardwareEnclaveSupported()

Determine whether hardware enclaves are supported on the current platform. Irrespective of the current project mode. To support hardware enclaves, the platform needs to be Linux and the system needs a CPU which supports the intel SGX instruction set extensions.

isSimulatedEnclaveSupported
Link copied to clipboard
static boolean isSimulatedEnclaveSupported()

Determine whether simulated enclaves are supported on the current platform. Irrespective of the current project mode. To support simulated enclaves, the platform needs to be Linux.

load
Link copied to clipboard
static EnclaveHost load()

Scan the classpath and load the single signed enclave that is found.

static EnclaveHost load(MockConfiguration mockConfiguration)

Scan the classpath and load the single signed enclave that is found.

static EnclaveHost load(String enclaveClassName)

Load the signed enclave for the given enclave class name.

static EnclaveHost load(String enclaveClassName, MockConfiguration mockConfiguration)

Load the signed enclave for the given enclave class name.

start
Link copied to clipboard
void start(AttestationParameters attestationParameters, byte[] sealedState, Path enclaveFileSystemFile, Consumer<List<MailCommand>> commandsCallback)
void start(AttestationParameters attestationParameters, byte[] sealedState, Path enclaveFileSystemFile, KDSConfiguration kdsConfiguration, Consumer<List<MailCommand>> commandsCallback)

Causes the enclave to be loaded and the Enclave object constructed inside. This method must be called before sending is possible. Remember to call close to free the associated enclave resources when you're done with it.

updateAttestation
Link copied to clipboard
void updateAttestation()

Perform a fresh attestation with the attestation service. On successful completion the enclaveInstanceInfo property may be updated to a newer one. If so make sure to provide this to end clients.

Note that an attestation is already performed on startup. It's recommended to call this method if a long time has passed and clients may want a more fresh version.

Properties

enclaveClassName
Link copied to clipboard
private String enclaveClassName

The name of the sub-class of Enclave that was loaded.

enclaveInstanceInfo
Link copied to clipboard
private EnclaveInstanceInfo enclaveInstanceInfo

Provides the info of this specific loaded instance. Note that the enclave instance info will remain valid across restarts of the host JVM/reloads of the enclave.

enclaveMode
Link copied to clipboard
private EnclaveMode enclaveMode

The mode the enclave is running in.

mockEnclave
Link copied to clipboard
private Object mockEnclave

For mock mode, the instance of the Enclave that is loaded by the host. This should be cast to the type of Enclave that has been loaded and can be used to examine the state of the enclave.

For anything other than mock mode attempting to access this property will result in an IllegalStateException being thrown.