TCTI loader library

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-tcti-ldr 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-tcti-ldr 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_Tcti_Ldr_Init (const char *name,
                    const char *conf,
                    TSS2_TCTI_CONTEXT **context);

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 the string "default" may be used to instantiate a default TCTI for the platform.
• conf: The configuration string passed to the TCTI initialization function.
• context: A TSS2_TCTI_CONTEXT** used to return a reference to the allocated and initialized TCTI context back to the caller.

Finalization

void Tss2_Tcti_Util_Finalize (TSS2_TCTI_CONTEXT *context);

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

• context: The TCTI context to finalize and deallocate.

List

TSS2_RC Tss2_Tcti_Ldr_List (char **names)

Return names of all TCTI modules known to tss2-tcti-ldr to the caller in the names parameter excluding the "default".

Parameters

• names: Implementations of the Tss2_Tcti_Ldr library using the dynamic TCTI loading protocol must return a newline '\n' separated string of values from the name field from the TSS2_TCTI_INFO structure of all available TCTI libraries. Implementations of the Tss2_Tcti_Ldr library that do not use the dynamic TCTI loading protocol may use an implementation specific mapping. The names string must be allocated by the List function and freed by the caller.