Skip to content

TCTI loader library

Jump to bottom
Philip Tricca edited this page Jul 17, 2019 · 12 revisions

This is a proposal to add to the core TCTI specification a new library to automate the TCTI lifecycle. This requires a very limited set of functionality:

  • A function to automate loading and initialization of available TCTI libraries from name / config strings
  • A function to automate unloading and finalizing TCTI contexts
  • A new library with header

This library will be referred to as tss2-tctildr for the remainder of this document. This is a "working name" and will probably change.

Design Constraints

The addition of this new library should have no impact on the existing TCTI header. No changes are to be made to the TCTI structure: current structure is v2, not v3 structure should be required. The tss2-tctildr library is intended to be a peer to the tss2-esys library and is intended for use by implementations of the Esys_Initialize function or users of this function who need to initialize a TCTI instance for use with the Esys_Initialize function. Implementations are constrained by the same functional requirements as tss2-esys.

Use-case

Applications using the full set of TCTI features must currently implement the following in order to instantiate a TCTI context:

  • discovery:
    • mapping a name (string) to a TCTI library
    • loading the library
    • obtaining the TCTI info structure and thus a reference to the init function
  • context allocation & initialization
    • invoking the initialization function to determine the size of the TCTI context
    • allocating memory for the TCTI context
    • invoking the initialization function a second time to initialize the TCTI context
  • deallocation & finalization
    • finalize the TCTI context
    • unload the TCTI library

This creates not only duplicate effort (we already have 2 implementations) and an undesirable burden on users but could also create incompatibility in TCTI library discovery algorithms. We expect this to be most hazardous for OS vendors that may want to configure their TSS2 plumbing in a way that we haven't anticipated.

Initialization

TSS2_RC
Tss2_Tctildr_Init (const char *name,
                   const char *conf,
                   TSS2_TCTI_CONTEXT **tctiContext);

By providing a single function that wraps all details of TCTI discovery, allocation and initialization we provide the most simple interface possible. This function takes the name of the TCTI library, a configuration string, and a reference to a reference to a TSS2_TCTI_CONTEXT structure.

Parameters

  • name: This string holds name of the TCTI library. For TCTIs that implement the dynamic loading protocol this value MUST be the same as exposed by the TCTI library through the 'name' field in the 'TSS2_TCTI_INFO' structure. Additionally a NULL string, or the string "default" may be used to instantiate a default TCTI for the platform.
  • conf: The configuration string passed to the TCTI initialization function. A NULL conf string will be passed through to the underlying TCTI.
  • context: A TSS2_TCTI_CONTEXT** used to return a reference to the allocated and initialized TCTI context back to the caller.

Finalization

void Tss2_Tctildr_Finalize (TSS2_TCTI_CONTEXT **tctiContext);

The Finalize function is the dual of the Initialize function above. Finalize is required as a mechanism to clean up whatever resources were reserved or allocated by the Init function. This function is separate from the finalize function from a specific TCTI though when invoked it MUST call the finalize function for the underlying TCTI before freeing the context.

Parameters

  • tctiContext: The TCTI context to finalize and deallocate. When the Finalize function deallocates the context it MUST set the TSS2_TCTI_CONTEXT* referenced by this context to NULL.

TaskList

Clone this wiki locally