EnclaveConstraint

public class EnclaveConstraint

This utility class provides a template against which remote attestations may be matched. It defines a little domain specific language intended for use in configuration files, command line flags etc.

A constraint is intended to match a single logical enclave. A logical enclave may be made up of multiple instances on different machines, and multiple versions of the enclave software. Constraints can be as tight or as loose as you like, however, it's better for security when you're more specific about what you want, and more flexible/convenient when you leave it vague. The correct tradeoff depends on your app and is up to you.

You don't have to use this class: you can check the components of a EnclaveInstanceInfo yourself. However these checks are normally just boilerplate and thus it's convenient to use an EnclaveConstraint.

Every criteria must be satisfied for the constraint to be satisfied. Hashes and public keys are combined such that satisfying any one of them is sufficient:

(hash OR hash OR key) AND minRevocationLevel AND productID AND minSecurityLevel

Constructors

EnclaveConstraint
Link copied to clipboard
EnclaveConstraint EnclaveConstraint()

Methods

check
Link copied to clipboard
void check(EnclaveInstanceInfo enclave)
equals
Link copied to clipboard
boolean equals(Object other)
getAcceptableCodeHashes
Link copied to clipboard
Set<SecureHashgetAcceptableCodeHashes()

The set of measurement hashes that will be accepted. A match against any hash satisfies this criteria and acceptableSigners.

At least one code hash or signer must be provided.

getAcceptableSigners
Link copied to clipboard
Set<SecureHashgetAcceptableSigners()

The set of code signers that will be accepted. A match against any signer satisfies this criteria and acceptableCodeHashes. A productID must also be specified since a single signing key can sign multiple unrelated enclaves.

At least one code hash or signer must be provided.

getMaxAttestationAge
Link copied to clipboard
Period getMaxAttestationAge()

How old the attestation is allowed to be. Defaults to null, representative of no maximum age. The Period class stores the duration in (months days weeks etc). It's important to remember that these quantities mean nothing until they are compared with a date because, for instance, the number of days in a month is variable.

getMinRevocationLevel
Link copied to clipboard
int getMinRevocationLevel()

EnclaveInfo.revocationLevel must be greater or equal to this. That corresponds to the SGX notion of an enclave security version level. Null means accept all revocation levels (i.e. there were no revocations yet). This value comes from the signed enclave metadata and cannot be forged by a hacked enclave: only if the enclave developer's signing key has been compromised. The remote enclave must have a revocation level (SVN) greater than this value, i.e. 1 means the enclave must have an SVN of 2 or above.

getMinSecurityLevel
Link copied to clipboard
EnclaveSecurityInfo.Summary getMinSecurityLevel()

Whether to accept debug/insecure enclaves, or enclaves running on hosts that have fallen behind on their security patches. By default stale machines (running old software/microcode) are accepted, to avoid outages in case of operator laxness, but you can tighten this if wanted.

getProductID
Link copied to clipboard
int getProductID()

The Product ID is a number between 0 and 65535 that differentiates products signed by the same signing key. Enclaves with different product IDs cannot access each other's sealed data. You need to specify this to prevent confusions between two products that speak the same protocol and which a malicious host has swapped. This must be specified if there is at least one acceptableSigners.

hashCode
Link copied to clipboard
int hashCode()
parse
Link copied to clipboard
static EnclaveConstraint parse(String descriptor)

Parses a Conclave specific textual constraint format designed to be compact and conveniently embeddable in config files, markup, source code etc.

It consists of space separated tokens. Each token is a key:value pair. The following keys are defined:

  • PROD: the value of productID.

  • C: an entry in the acceptableCodeHashes set.

  • S: an entry in the acceptableSigners set.

  • REVOKE: the value of minRevocationLevel, optional

  • SEC: whether to accept debug/stale enclave hosts or not, optional.

  • EXPIRE: expiry duration, check if the attestation is older than the specified duration, optional. The duration string uses the ISO-8601 duration format.

SEC is optional. It may take values of INSECURE, STALE or SECURE. See the documentation for EnclaveSecurityInfo.Summary for information on what these mean. The default is STALE, which optimises for uptime.

An example descriptor might look like this:

PROD:10 S:bb53e85cb86e7f1e2b7d97620e25d8d0a250c8fdbfe9b7cddf940bd08b646c88

which means, accept any enclave of product ID 10 signed by the key bb53...

Alternatively:

C:2797b9581b9377d41a8ffc45990335048e79c976a6bbb4e7692ecad699a55317 C:f96839b2159ecf8ea80cd3c1eb6be7160b05bc0d701b115b64b7e0725d15adee

says, accept if the code/measurement hash is either 2797... or f968....

static EnclaveConstraint parse(String descriptor, boolean checkValidity)

Parses a Conclave specific textual constraint format designed to be compact and conveniently embeddable in config files, markup, source code etc.

It consists of space separated tokens. Each token is a key:value pair. The following keys are defined:

  • PROD: the value of productID.

  • C: an entry in the acceptableCodeHashes set.

  • S: an entry in the acceptableSigners set.

  • REVOKE: the value of minRevocationLevel, optional

  • SEC: whether to accept debug/stale enclave hosts or not, optional.

  • EXPIRE: expiry duration, check if the attestation is older than the specified duration, optional. The duration string uses the ISO-8601 duration format.

SEC is optional. It may take values of INSECURE, STALE or SECURE. See the documentation for EnclaveSecurityInfo.Summary for information on what these mean. The default is STALE, which optimises for uptime.

An example descriptor might look like this:

PROD:10 S:bb53e85cb86e7f1e2b7d97620e25d8d0a250c8fdbfe9b7cddf940bd08b646c88

which means, accept any enclave of product ID 10 signed by the key bb53...

Alternatively:

C:2797b9581b9377d41a8ffc45990335048e79c976a6bbb4e7692ecad699a55317 C:f96839b2159ecf8ea80cd3c1eb6be7160b05bc0d701b115b64b7e0725d15adee

says, accept if the code/measurement hash is either 2797... or f968....

setAcceptableCodeHashes
Link copied to clipboard
void setAcceptableCodeHashes(Set<SecureHash> acceptableCodeHashes)

The set of measurement hashes that will be accepted. A match against any hash satisfies this criteria and acceptableSigners.

At least one code hash or signer must be provided.

setAcceptableSigners
Link copied to clipboard
void setAcceptableSigners(Set<SecureHash> acceptableSigners)

The set of code signers that will be accepted. A match against any signer satisfies this criteria and acceptableCodeHashes. A productID must also be specified since a single signing key can sign multiple unrelated enclaves.

At least one code hash or signer must be provided.

setMaxAttestationAge
Link copied to clipboard
void setMaxAttestationAge(Period maxAttestationAge)

How old the attestation is allowed to be. Defaults to null, representative of no maximum age. The Period class stores the duration in (months days weeks etc). It's important to remember that these quantities mean nothing until they are compared with a date because, for instance, the number of days in a month is variable.

setMinRevocationLevel
Link copied to clipboard
void setMinRevocationLevel(int minRevocationLevel)

EnclaveInfo.revocationLevel must be greater or equal to this. That corresponds to the SGX notion of an enclave security version level. Null means accept all revocation levels (i.e. there were no revocations yet). This value comes from the signed enclave metadata and cannot be forged by a hacked enclave: only if the enclave developer's signing key has been compromised. The remote enclave must have a revocation level (SVN) greater than this value, i.e. 1 means the enclave must have an SVN of 2 or above.

setMinSecurityLevel
Link copied to clipboard
void setMinSecurityLevel(EnclaveSecurityInfo.Summary minSecurityLevel)

Whether to accept debug/insecure enclaves, or enclaves running on hosts that have fallen behind on their security patches. By default stale machines (running old software/microcode) are accepted, to avoid outages in case of operator laxness, but you can tighten this if wanted.

setProductID
Link copied to clipboard
void setProductID(int productID)

The Product ID is a number between 0 and 65535 that differentiates products signed by the same signing key. Enclaves with different product IDs cannot access each other's sealed data. You need to specify this to prevent confusions between two products that speak the same protocol and which a malicious host has swapped. This must be specified if there is at least one acceptableSigners.

toString
Link copied to clipboard
String toString()

Properties

acceptableCodeHashes
Link copied to clipboard
private Set<SecureHashacceptableCodeHashes

The set of measurement hashes that will be accepted. A match against any hash satisfies this criteria and acceptableSigners.

At least one code hash or signer must be provided.

acceptableSigners
Link copied to clipboard
private Set<SecureHashacceptableSigners

The set of code signers that will be accepted. A match against any signer satisfies this criteria and acceptableCodeHashes. A productID must also be specified since a single signing key can sign multiple unrelated enclaves.

At least one code hash or signer must be provided.

maxAttestationAge
Link copied to clipboard
private Period maxAttestationAge

How old the attestation is allowed to be. Defaults to null, representative of no maximum age. The Period class stores the duration in (months days weeks etc). It's important to remember that these quantities mean nothing until they are compared with a date because, for instance, the number of days in a month is variable.

minRevocationLevel
Link copied to clipboard
private int minRevocationLevel

EnclaveInfo.revocationLevel must be greater or equal to this. That corresponds to the SGX notion of an enclave security version level. Null means accept all revocation levels (i.e. there were no revocations yet). This value comes from the signed enclave metadata and cannot be forged by a hacked enclave: only if the enclave developer's signing key has been compromised. The remote enclave must have a revocation level (SVN) greater than this value, i.e. 1 means the enclave must have an SVN of 2 or above.

minSecurityLevel
Link copied to clipboard
private EnclaveSecurityInfo.Summary minSecurityLevel

Whether to accept debug/insecure enclaves, or enclaves running on hosts that have fallen behind on their security patches. By default stale machines (running old software/microcode) are accepted, to avoid outages in case of operator laxness, but you can tighten this if wanted.

productID
Link copied to clipboard
private int productID

The Product ID is a number between 0 and 65535 that differentiates products signed by the same signing key. Enclaves with different product IDs cannot access each other's sealed data. You need to specify this to prevent confusions between two products that speak the same protocol and which a malicious host has swapped. This must be specified if there is at least one acceptableSigners.