Tss2_Tcti_Mssim_Init(3)

📦
version 4.2.0 · 8 versions
, in arch rolling, nixos 26.05, nixpkgs unstable

💖 Tss2_Tcti_Mssim_Init(3) — Library Functions Manual 💖

okay bestie, sit down, hydrate, because we're about to talk about the iconic little function that gets you talking to the Microsoft TPM2 simulator. yes, that's a real thing. yes, it slays. let's go. ✨

🌸 NAME 🌸

Tss2_Tcti_Mssim_Init — the initialization function for the Microsoft TPM simulator TCTI library. she's the entry point, the girl who opens the door, the one who sets everything up before the real party starts. 💅

✨ SYNOPSIS ✨

#include <tcti/tcti_mssim.h>

TSS2_RC Tss2_Tcti_Mssim_Init (TSS2_TCTI_CONTEXT *tctiContext, size_t
*contextSize, const char *conf);

so like, the way that Tss2_Tcti_Mssim_Init() works is that it initializes a TCTI context, and that context is literally the thing you use to communicate with the Microsoft TPM2 simulator. no context, no talking. that's the vibe. 🦋

🎀 DESCRIPTION 🎀

Tss2_Tcti_Mssim_Init() attempts to initialize a caller allocated tcti_context of size size, using the caller provided configuration string conf. ngl, the whole "caller allocated" thing trips people up, so let's break it down.

since the tcti_context must be a caller allocated buffer, you (yes, you, the caller) need to know how big that buffer has to be. and here's the cute part: you can find out the minimum size by passing NULL for the tcti_context and a non-NULL size parameter. the init function will then fill in that size parameter with the minimum size of the tcti_context buffer. 💖

then you (the caller, the main character) allocate a buffer of that size — or bigger, she's flexible — and call Tss2_Tcti_Mssim_Init() again, this time handing over the freshly allocated tcti_context and its size in the size parameter. ✨

this two-step dance is literally the pattern for all TCTI initialization functions, not just this one. it's a whole genre.

there's a full example of this pattern using Tss2_Tcti_Mssim_Init() down in the section titled EXAMPLE, so if the words aren't wording, skip ahead. 🙈

so the conf parameter is a C string used to configure the TCTI context. it's a series of key / value pairs that specify the host and port used to connect to an instance of the Microsoft TPM2 simulator. the keys and values are separated by the '=' character, and each key / value pair is separated by the ',' character. that's it, that's the whole syntax, she's simple like that. 💅

the only keys supported in the conf string are host and port.

  • host may be an IPv4 address, an IPv6 address, or a host name. she contains multitudes.
  • port must be a valid uint16_t in string form. no vibes-based ports. it has to be a real number, bestie.

if a NULL conf string is provided by the caller, then the default of "host=localhost,port=2321" is used. and if either host or port are omitted, then their respective default value will be used. so you can half-ass the config string and she'll still show up for you. 🫶

once initialized, the TCTI context returned exposes the Trusted Computing Group (TCG) defined API for the lowest level communication with the TPM. using this API the caller can exchange (send / receive) TPM2 command and response buffers with the Microsoft TPM simulator.

but in nearly all cases? the caller will initialize a context using this function, then pass the context to a higher level API like the System API (SAPI), and then never touch it again. it's giving "raised you, sent you to college, now you're on your own." 😭 iconic honestly.

for a more thorough discussion of the TCTI API, see the "TSS System Level API and TPM Command Transmission Interface Specification" as published by the TCG:

https://trustedcomputinggroup.org/tss-system-level-api-tpm-command-transmission-interface-specification/

🌈 RETURN VALUE 🌈

a successful call to Tss2_Tcti_Mssim_Init() will return TSS2_RC_SUCCESS. periodt. 💅

an unsuccessful call will produce a response code described in the section ERRORS. (spoiler: it's one code. she's dramatic but she's consistent.)

💀 ERRORS 💀

  • TSS2_TCTI_RC_BAD_VALUE is returned if both the tcti_context and the size parameters are NULL, or if the config parameter is NULL.
yeah bestie, passing nothing and also nothing is not the move. she will not be able to work with that. 😭

🔥 EXAMPLE 🔥

TCTI initialization fragment, verbatim, because this is the part you're gonna copy-paste and we're not gonna mess with it:

#include <inttypes.h>
#include <stdlib.h>
#include <stdio.h>
#include <tcti/tcti_mssim.h>

TSS2_RC rc;
TSS2_TCTI_CONTEXT *tcti_context;
size_t size;
const char *conf = "host=localhost,port=2321"

rc = Tss2_Tcti_Mssim_Init (NULL, &size, NULL);
if (rc != TSS2_RC_SUCCESS) {
    fprintf (stderr, "Failed to get allocation size for mssim TCTI "
             " context: 0x%" PRIx32 "0, rc);
    exit (EXIT_FAILURE);
}
tcti_context = calloc (1, size);
if (tcti_context == NULL) {
    fprintf (stderr, "Allocation for TCTI context failed: %s0,
             strerror (errno));
    exit (EXIT_FAILURE);
}
rc = Tss2_Tcti_Mssim_Init (&tcti_context, &size, conf);
if (rc != TSS2_RC_SUCCESS) {
    fprintf (stderr, "Failed to initialize mssim TCTI context: "
             "0x%" PRIx32 "0, rc);
    free (tcti_context);
    exit (EXIT_FAILURE);
}

see how she calls it once with NULL to learn the size, callocs the buffer, and then calls it again with the real context? that's the pattern. that's the whole girl. 👑

🧚 AUTHOR 🧚

TPM2 Software Project — https://github.com/tpm2-software/tpm2-tss

💜 SEE ALSO 💜

👑 COLOPHON 👑

this page is part of release 4.2.0 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). a description of the project, info about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/. 🦋

⭐ LICENSE ⭐

this work is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). for more info visit https://creativecommons.org/licenses/by/4.0/. share the love, credit the girlies. 💖

and that's the whole page, bestie. TPM2 Software Stack, JUNE 2017 — Tss2_Tcti_Mssim_Init(3). go forth, allocate your buffers, and slay. 💅✨🎀

📦 where this page comes from