Dynamic TCTI Loading Proposal

NOTE: This proposed change to the TCTI specification was included in the TCG spec and published in version 1.0 revision 12: https://trustedcomputinggroup.org/wp-content/uploads/TSS_TCTI_v1.0_r12_PUBLIC_REVIEW.pdf

TCTI context initialization in previous spec versions has been left as "implementation specific". This proposal aims to standardize the TCTI initialization mechanism providing for both static and dynamic linking as well as dynamic loading.

Definitions:

• static linking - libraries are linked at compile time and copied into the executable image
• dynamic linking - libraries are linked at runtime with operating system support / dynamic linker
• dynamic loading - libraries are loaded at runtime and symbols resolved manually

Static and Dynamic Linking

Static and dynamic linking to TCTI libraries is accomplished through a library specific initialization function. The authors of a TCTI module SHOULD minimize the possibility of name conflicts across TCTI modules by prefixing their initialization function name with a string unique to their library. While the name of this function is implementation specific, the type of the function SHOULD be, as defined in tss2_tcti.h as:

typedef tss2_rc (*TSS2_TCTI_INIT) (TSS2_TCTI_CONTEXT *context, size_t *size, const char *conf);

Initialization functions of this type MUST initialize the provided TCTI context context of size size according to the configuration string in conf. The format of the configuration string conf is implementation specific. When provided with a NULL context this function MUST return the minimum size of the caller supplied TCTI context structure in the size parameter. When provided with a NULL conf string the TCTI module MUST initialize the TCTI context with default values. These defaults are implementation specific. In the event that the caller provides a non-NULL context and a value in the size parameter that is inaccurate (a size field larger than the buffer referenced in the context field) then the behavior of the initialization function is undefined.

Response Codes:

• TSS2_TCTI_BAD_VALUE is returned if any parameters contain unexpected values.
• TSS2_TCTI_BAD_REFERENCE is returned if any parameters are NULL when they should not be.
• TSS2_TCTI_BAD_CONTEXT is returned if the size of the TCTI context provided is insufficient.

Dynamic Loading

The previous initialization method requires that the application program know which TCTI module it is being linked against when the application is compiled. To support the dynamic discovery of TCTI module and to allow application code to link against multiple TCTIs dynamically we describe two mechanisms. First we provide a well known symbol to expose information about the TCTI module. This is defined in tss2_tcti.h as:

typedef const TSS2_TCTI_INFO* (*TSS2_TCTI_INFO) (void);

Every TCTI module MUST implement a function of type TSS2_TCTI_INFO and it must be exposed through the symbol Tss2_Tcti_Info. The headers provide this string in tss2_tcti.h as:

#define TSS2_TCTI_INFO_SYMBOL "Tss2_Tcti_Info"

The TSS2_TCTI_INFO_SYMBOL constant is defined for use by application developers for discovering this function at runtime. To supoprt dynamic TCTI loading the name of this symbol MUST be consistent across all TCTIs. Applications SHOULD never link to this symbol, it should only be used for dynamic loading (dlopen or equivalent). Applications that must link either statically or dynamically SHOULD use the initialization symbol unique to the TCTI.

Functions of this type take no parameters and MUST always return a constant reference to a populated TSS2_TCTI_INFO structure. The pointer returned is a const reference and so should never be modified or deallocated by the caller. The TSS2_TCTI_INFO structure is defined in tss2_tcti.h as:

typedef TSS2_TCTI_VERSION TSS2_TCTI_CONTEXT_VERSION;

typdef struct {
    TSS2_TCTI_VERSION version;
    const char *name;
    const char *description;
    const char *config_help;
    TSS2_TCTI_INIT_FUNC init;
} TSS2_TCTI_INFO;

Each field in this structure provides information to the caller about the TCTI module and its initialization mechanism. Each is described in the following table:

field	purpose
version	version information for the TCTI module
name	the unique name of the TCTI module
description	a human readable string describing the TCTI module
config_help	a human readable string describing the format of the conf parameter TSS2_TCTI_INIT functions exposed by this module
init	a reference to an initialization function of type TSS2_TCTI_INIT

The version filed

This field is the same type as defined for the context structure. Its value MUST be the same as would be returned by the same library in an initialized context structure.

The name, description, and config_help fields

The next 3 fields are self explanatory and intended to provide application developers with useful information about the TCTI module. TCTI authors should expect these strings to be displayed in output to users.

The init field

The final field MUST provide the caller with a valid reference to an initialization function of type TSS2_TCTI_INIT. In most cases this SHOULD be a reference to the same function exposed by the TCTI module with a TCTI specific name for static and dynamic linking.

Example Static or Dynamic Linking

Example Dynamic Loading