Struct sgx_tservice::sgxcounter::SgxMonotonicCounter

pub struct SgxMonotonicCounter { /* fields omitted */ }

Monotonic counter ID

Methods

impl SgxMonotonicCounter

pub fn new(counter_value: &mut u32) -> SgxResult<Self>

creates a monotonic counter with default owner policy and default user attribute mask.

Description

Call new to create a monotonic counter with the default owner policy 0x1, which means enclaves with same signing key can access the monotonic counter and default owner_attribute_mask 0xFFFFFFFFFFFFFFCB.

The caller should call rsgx_create_pse_session to establish a session with the platform service enclave before calling this API.

Creating a monotonic counter (MC) involves writing to the non-volatile memory available in the platform. Repeated write operations could cause the memory to wear out during the normal lifecycle of the platform. Intel(R) SGX prevents this by limiting the rate at which MC operations can be performed. If you exceed the limit, the MC operation may return SGX_ERROR_BUSY for several minutes.

Intel(R) SGX limits the number of MCs an enclave can create. To avoid exhausting the available quota, an SGX application should record the MC UUID that rsgx_create_monotonic_counter returns and destroy a MC when it is not needed any more. If an enclave reaches its quota and previously created MC UUIDs have not been recorded, you may restore the MC service after uninstalling the SGX PSW and installing it again. This procedure deletes all MCs created by any enclave in that system.

Parameters

counter_value

A pointer to the buffer that receives the monotonic counter value.

Requirements

Header: sgx_tae_service.edl

Library: libsgx_tservice.a

Return value

Monotonic counter ID

Errors

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_MC_OVER_QUOTA

The enclave has reached the quota of Monotonic Counters it can maintain.

SGX_ERROR_MC_USED_UP

Monotonic counters are used out.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPC memory to load one of the Architecture Enclaves needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

pub fn new_ex(     owner_policy: u16,     owner_attribute_mask: &sgx_attributes_t,     counter_value: &mut u32 ) -> SgxResult<Self>

creates a monotonic counter.

Description

Call new_ex to create a monotonic counter with the given owner_policy and owner_attribute_mask.

The caller should call rsgx_create_pse_session to establish a session with the platform service enclave before calling this API.

Creating a monotonic counter (MC) involves writing to the non-volatile memory available in the platform. Repeated write operations could cause the memory to wear out during the normal lifecycle of the platform. Intel(R) SGX prevents this by limiting the rate at which MC operations can be performed. If you exceed the limit, the MC operation may return SGX_ERROR_BUSY for several minutes.

Intel(R) SGX limits the number of MCs an enclave can create. To avoid exhausting the available quota, an SGX application should record the MC UUID that rsgx_create_monotonic_counter_ex returns and destroy a MC when it is not needed any more. If an enclave reaches its quota and previously created MC UUIDs have not been recorded, you may restore the MC service after uninstalling the SGX PSW and installing it again. This procedure deletes all MCs created by any enclave in that system.

Parameters

owner_policy

The owner policy of the monotonic counter.

• 0x1 means enclave with same signing key can access the monotonic counter
• 0x2 means enclave with same measurement can access the monotonic counter
• 0x3 means enclave with same measurement as well as signing key can access the monotonic counter.
• Owner policy values of 0x0 or any bits set beyond bits 0 and 1 will cause SGX_ERROR_INVALID_PARAMETER

owner_attribute_mask

Mask of owner attribute, in the format of sgx_attributes_t.

counter_value

A pointer to the buffer that receives the monotonic counter value.

Requirements

Header: sgx_tae_service.edl

Library: libsgx_tservice.a

Return value

Monotonic counter ID

Errors

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_MC_OVER_QUOTA

The enclave has reached the quota of Monotonic Counters it can maintain.

SGX_ERROR_MC_USED_UP

Monotonic counters are used out.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPC memory to load one of the Architecture Enclaves needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

pub fn destory(&self) -> SgxError

destroys a monotonic counter created by new or new_ex.

Description

Calling destory after a monotonic counter is not needed anymore.

The caller should call rsgx_create_pse_session to establish a session with the platform service enclave before calling this API.

destory fails if the calling enclave does not match the owner policy and the attributes specified in the call that created the monotonic counter.

Destroying a Monotonic Counter (MC) involves writing to the non-volatile memory available in the platform. Repeated write operations could cause the memory to wear out during the normal lifecycle of the platform. Intel(R) SGX prevents this by limiting the rate at which MC operations can be performed. If you exceed the limit, the MC operation may return SGX_ERROR_BUSY for several minutes.

Requirements

Header: sgx_tae_service.edl

Library: libsgx_tservice.a

Errors

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_MC_NOT_FOUND

The Monotonic Counter does not exist or has been invalidated.

SGX_ERROR_MC_NO_ACCESS_RIGHT

The enclave doesn't have the access right to specified Monotonic Counter.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPC memory to load one of the Architecture Enclaves needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

pub fn increment(&self) -> SgxResult<u32>

increments a monotonic counter value by 1.

Description

Call increment to increase a monotonic counter value by 1.

The caller should call rsgx_create_pse_session to establish a session with the platform service enclave before calling this API.

increment fails if the calling enclave does not match the owner policy and the attributes specified in the call that created the monotonic counter.

Incrementing a monotonic counter (MC) involves writing to the non-volatile memory available in the platform. Repeated write operations could cause the memory to wear out during the normal lifecycle of the platform. Intel(R) SGX prevents this by limiting the rate at which MC operations can be performed. If you exceed the limit, the MC operation may return SGX_ERROR_BUSY for several minutes.

Requirements

Header: sgx_tae_service.edl

Library: libsgx_tservice.a

Errors

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_MC_NOT_FOUND

The Monotonic Counter does not exist or has been invalidated.

SGX_ERROR_MC_NO_ACCESS_RIGHT

The enclave doesn't have the access right to specified Monotonic Counter.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPC memory to load one of the Architecture Enclaves needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

pub fn read(&self) -> SgxResult<u32>

returns the value of a monotonic counter.

Description

Call read to read the value of a monotonic counter.

The caller should call rsgx_create_pse_session to establish a session with the platform service enclave before calling this API.

read fails if the calling enclave does not match the owner policy and the attributes specified in the call that created the monotonic counter.

Requirements

Header: sgx_tae_service.edl

Library: libsgx_tservice.a

Return value

Monotonic counter value

Errors

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_MC_NOT_FOUND

The Monotonic Counter does not exist or has been invalidated.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPC memory to load one of the Architecture Enclaves needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

Trait Implementations

impl Drop for SgxMonotonicCounter

fn drop(&mut self)

destroys a monotonic counter created by new or new_ex.