Internal ESAPI Types
Enhanced System API » Internals of Enhanced System API

## Data Structures

struct | RSRC_NODE_T
struct | ESYS_CONTEXT
struct | IESYS_SESSION
union | IESYS_RSRC_UNION
struct | IESYS_RESOURCE
struct | IESYS_METADATA
struct | IESYS_CONTEXT_DATA

## Macros

#define | _ESYS_MAX_SUBMISSIONS 5
#define | _ESYS_ASSERT_NON_NULL(x)
#define | IESYSC_KEY_RSRC 1
#define | IESYSC_NV_RSRC 2
#define | IESYSC_SESSION_RSRC 3
#define | IESYSC_WITHOUT_MISC_RSRC 0
#define | ENCRYPT 1
#define | NO_ENCRYPT 0
#define | DECRYPT 1
#define | NO_DECRYPT 0
#define | POLICY_PASSWORD 2
#define | POLICY_AUTH 1
#define | NO_POLICY_AUTH 0

## Typedefs

typedef struct RSRC_NODE_T | RSRC_NODE_T
typedef UINT32 | IESYSC_RESOURCE_TYPE_CONSTANT
typedef UINT32 | IESYSC_PARAM_ENCRYPT
typedef UINT32 | IESYSC_PARAM_DECRYPT
typedef UINT32 | IESYSC_TYPE_POLICY_AUTH
typedef UINT32 | IESYSC_RESOURCE_TYPE

## Detailed Description

The ESAPI implementation requires a set of internal type definitions.

## Data Structure Documentation

## RSRC_NODE_T

struct RSRC_NODE_T

Linked list type for object meta data.

This structure represents a linked list to store meta data information of type IESYS_RESOURCE.

### Data Fields

ESYS_TR | esys_handle
TPM2B_AUTH | auth
IESYS_RESOURCE | rsrc
size_t | reference_count
struct RSRC_NODE_T * | next

#### Field Documentation

## auth

TPM2B_AUTH auth

The authValue for this resource object.

## esys_handle

ESYS_TR esys_handle

The ESYS_TR handle used by the application to reference this entry.

## next

struct RSRC_NODE_T* next

The next object in the linked list.

## reference_count

size_t reference_count

Reference Count for Esys_TR_FromTPMPublic

## rsrc

IESYS_RESOURCE rsrc

The meta data for this resource object.

## ESYS_CONTEXT

struct ESYS_CONTEXT

The data structure holding internal state information.

Each ESYS_CONTEXT respresents a logically independent connection to the TPM. It stores meta data information about object in order to calculate session auths and similar things.

### Data Fields

enum _ESYS_STATE | state
TSS2_SYS_CONTEXT * | sys
ESYS_TR | esys_handle_cnt
RSRC_NODE_T * | rsrc_list
int32_t | timeout
ESYS_TR | session_type [3]
RSRC_NODE_T * | session_tab [3]
int | encryptNonceIdx
TPM2B_NONCE * | encryptNonce
int | authsCount
int | submissionCount
TPM2B_DATA | salt
IESYS_CMD_IN_PARAM | in
ESYS_TR | esys_handle
TSS2_TCTI_CONTEXT * | tcti_app_param
void * | dlhandle
IESYS_SESSION * | enc_session
ESYS_TR | sav_session1
ESYS_TR | sav_session2
ESYS_TR | sav_session3
ESYS_CRYPTO_CALLBACKS | crypto_backend

#### Field Documentation

## authsCount

int authsCount

The number of session provided during the command.

## crypto_backend

ESYS_CRYPTO_CALLBACKS crypto_backend

The backend function pointers to use for crypto operations

## dlhandle

void* dlhandle

The handle of dlopen if the tcti was automatically loaded.

## enc_session

IESYS_SESSION* enc_session

Ptr to the enc param session. Used to restore session attributes

## encryptNonce

TPM2B_NONCE* encryptNonce

The nonce of the encrypt session, or NULL if no encrypt session exists.

## encryptNonceIdx

int encryptNonceIdx

The index of the encrypt session.

## esys_handle

ESYS_TR esys_handle

Temporary storage for the object's TPM handle during Esys_TR_FromTPMPublic.

## esys_handle_cnt

ESYS_TR esys_handle_cnt

The next free ESYS_TR number.

## in

IESYS_CMD_IN_PARAM in

Temporary storage for Input parameters needed in corresponding _Finish function

## rsrc_list

RSRC_NODE_T* rsrc_list

The linked list of all ESYS_TR objects.

## salt

TPM2B_DATA salt

The salt used during a StartAuthSession.

## sav_session1

ESYS_TR sav_session1

Used to store session for cases where call with ESYS_TR_NONE is needed to determine object name

## session_tab

RSRC_NODE_T* session_tab[3]

The list of TPM session meta data in the current command execution.

## session_type

ESYS_TR session_type[3]

The list of TPM session handles in the current command execution.

## state

enum _ESYS_STATE state

The current state of the ESAPI context.

## submissionCount

int submissionCount

The current number of submissions of this command to the TPM.

## sys

TSS2_SYS_CONTEXT* sys

The SYS context used internally to talk to the TPM.

## tcti_app_param

TSS2_TCTI_CONTEXT* tcti_app_param

The TCTI context provided by the application during Esys_Initialize() to be returned from Esys_GetTcti().

## timeout

int32_t timeout

The timeout to be used during Tss2_Sys_ExecuteFinish.

## IESYS_SESSION

struct IESYS_SESSION

Type for representing TPM-Session

### Data Fields

TPM2B_NAME | bound_entity
TPM2B_ENCRYPTED_SECRET | encryptedSalt
TPM2B_DATA | salt
TPMT_SYM_DEF | symmetric
TPMI_ALG_HASH | authHash
TPM2B_DIGEST | sessionKey
TPM2_SE | sessionType
TPMA_SESSION | sessionAttributes
TPMA_SESSION | origSessionAttributes
TPM2B_NONCE | nonceCaller
TPM2B_NONCE | nonceTPM
IESYSC_PARAM_ENCRYPT | encrypt
IESYSC_PARAM_DECRYPT | decrypt
IESYSC_TYPE_POLICY_AUTH | type_policy_session
UINT16 | sizeSessionValue
BYTE | sessionValue [2 *sizeof(TPMU_HA)]
UINT16 | sizeHmacValue

#### Field Documentation

## authHash

TPMI_ALG_HASH authHash

Hashalg used for authorization

## bound_entity

TPM2B_NAME bound_entity

Entity to which the session is bound

## decrypt

IESYSC_PARAM_DECRYPT decrypt

Indicate parameter decryption by the TPM

## encrypt

IESYSC_PARAM_ENCRYPT encrypt

Indicate parameter encryption by the TPM

## encryptedSalt

TPM2B_ENCRYPTED_SECRET encryptedSalt

Encrypted salt which can be provided by application

## nonceCaller

TPM2B_NONCE nonceCaller

Nonce computed by the ESAPI for every session call

## nonceTPM

TPM2B_NONCE nonceTPM

Nonce which is returned by the TPM for every session call

## origSessionAttributes

TPMA_SESSION origSessionAttributes

Copy of flags which define the session behaviour

## salt

TPM2B_DATA salt

Salt computed if no encrypted salt is provided

## sessionAttributes

TPMA_SESSION sessionAttributes

Flags which define the session behaviour

## sessionKey

TPM2B_DIGEST sessionKey

sessionKey used for KDFa to compute symKey

## sessionType

TPM2_SE sessionType

Type of the session (HMAC, Policy)

## sessionValue

BYTE sessionValue[2 *sizeof(TPMU_HA)]

sessionKey || AuthValue

## sizeHmacValue

UINT16 sizeHmacValue

Size of sessionKey plus optionally authValue

## sizeSessionValue

UINT16 sizeSessionValue

Size of sessionKey plus optionally authValue

## symmetric

TPMT_SYM_DEF symmetric

Algorithm selection for parameter encryption

## type_policy_session

IESYSC_TYPE_POLICY_AUTH type_policy_session

Field to store markers for policy sessions

## IESYS_RSRC_UNION

union IESYS_RSRC_UNION

Type for representing public info of a TPM-Resource

### Data Fields

TPM2B_PUBLIC | rsrc_key_pub
TPM2B_NV_PUBLIC | rsrc_nv_pub
IESYS_SESSION | rsrc_session
TPMS_EMPTY | rsrc_empty

#### Field Documentation

## rsrc_empty

TPMS_EMPTY rsrc_empty

no specialized date for resource

## rsrc_key_pub

TPM2B_PUBLIC rsrc_key_pub

Public info for key objects

## rsrc_nv_pub

TPM2B_NV_PUBLIC rsrc_nv_pub

Public info for NV ram objects

## rsrc_session

IESYS_SESSION rsrc_session

Internal esapi session information

## IESYS_RESOURCE

struct IESYS_RESOURCE

Type for representing TPM-Resource

### Data Fields

TPM2_HANDLE | handle
TPM2B_NAME | name
IESYSC_RESOURCE_TYPE | rsrcType
IESYS_RSRC_UNION | misc

#### Field Documentation

## handle

TPM2_HANDLE handle

Handle used by TPM

## misc

IESYS_RSRC_UNION misc

Resource specific information

## name

TPM2B_NAME name

TPM name of the object

## rsrcType

IESYSC_RESOURCE_TYPE rsrcType

Selector for resource type

## IESYS_METADATA

struct IESYS_METADATA

Esys resource with size field

### Data Fields

UINT16 | size
IESYS_RESOURCE | data

#### Field Documentation

## data

IESYS_RESOURCE data

Esys resource data

## size

UINT16 size

size of the operand buffer

## IESYS_CONTEXT_DATA

struct IESYS_CONTEXT_DATA

Type for representing ESYS metadata

### Data Fields

UINT32 | reserved
TPM2B_CONTEXT_DATA | tpmContext
IESYS_METADATA | esysMetadata

#### Field Documentation

## esysMetadata

IESYS_METADATA esysMetadata

Meta data of the ESY_TR object

## reserved

UINT32 reserved

Must allways be zero

## tpmContext

TPM2B_CONTEXT_DATA tpmContext

Context information computed by tpm

## Macro Definition Documentation

## _ESYS_ASSERT_NON_NULL

#define _ESYS_ASSERT_NON_NULL | ( |  | x | ) |

Value:
if (x == NULL) { \
LOG_ERROR(str(x) " == NULL."); \
return TSS2_ESYS_RC_BAD_REFERENCE; \
}

Makro testing parameters against null.

## _ESYS_MAX_SUBMISSIONS

#define _ESYS_MAX_SUBMISSIONS 5

The number of authomatic resubmissions.

The number of resubmissions before a TPM's TPM2_RC_YIELDED is forwarded to the application.

## DECRYPT

#define DECRYPT 1

Parameter decryption by TPM

## ENCRYPT

#define ENCRYPT 1

Parameter encryption by TPM

## IESYSC_KEY_RSRC

#define IESYSC_KEY_RSRC 1

Tag for key resource

## IESYSC_NV_RSRC

#define IESYSC_NV_RSRC 2

Tag for NV Ram resource

## IESYSC_SESSION_RSRC

#define IESYSC_SESSION_RSRC 3

Tag for session resources

## IESYSC_WITHOUT_MISC_RSRC

#define IESYSC_WITHOUT_MISC_RSRC 0

Tag for other resources, e.g. PCR register, hierarchies

## NO_DECRYPT

#define NO_DECRYPT 0

No parameter decryption by TPM

## NO_ENCRYPT

#define NO_ENCRYPT 0

No parameter encryption by TPM

## NO_POLICY_AUTH

#define NO_POLICY_AUTH 0

no special handling

## POLICY_AUTH

#define POLICY_AUTH 1

Marker to include the auth value in the HMAC key

## POLICY_PASSWORD

#define POLICY_PASSWORD 2

Marker to include auth value of the authorized object

## Typedef Documentation

## IESYSC_PARAM_DECRYPT

typedef UINT32 IESYSC_PARAM_DECRYPT

Type to indicate parameter decryption (by TPM)

## IESYSC_PARAM_ENCRYPT

typedef UINT32 IESYSC_PARAM_ENCRYPT

Type to indicate parameter encryption (by TPM)

## IESYSC_RESOURCE_TYPE

typedef UINT32 IESYSC_RESOURCE_TYPE

Selector type for esys resources

## IESYSC_RESOURCE_TYPE_CONSTANT

typedef UINT32 IESYSC_RESOURCE_TYPE_CONSTANT

Type of resource

## IESYSC_TYPE_POLICY_AUTH

typedef UINT32 IESYSC_TYPE_POLICY_AUTH

Type of policy authorization

## RSRC_NODE_T

typedef struct RSRC_NODE_T RSRC_NODE_T

Linked list type for object meta data.

This structure represents a linked list to store meta data information of type IESYS_RESOURCE.