NAME

       Tss2_Tcti_Cmd_Init - Initialization function for the Cmd TCTI library.

SYNOPSIS

       #include <tss2/tss2_tcti_cmd.h>

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

       The  Tss2_Tcti_Cmd_Init()  function  initializes  a  TCTI  context  used to communicate with a subprocess
       specified in the conf string.  TCTI  send  and  receives  utilize  the  sub-process's  stdio  and  stdout
       respectively.

DESCRIPTION

       Tss2_Tcti_Cmd_Init()  attempts  to  initialize  a caller allocated tcti_context of size size using caller
       provided configuration string conf . Since the tcti_context must be a caller allocated buffer, the caller
       needs to know the buffer size required by the TCTI library. The minimum  size  of  this  context  can  be
       discovered  by  providing  NULL  for  the tcti_context and a non- NULL size parameter. The initialization
       function will then populate the size parameter with the minimum size  of  the  tcti_context  buffer.  The
       caller  must  then  allocate  a  buffer  of  this  size  (or larger) and call Tss2_Tcti_Cmd_Init () again
       providing the newly allocated tcti_context and the size of this  context  in  the  size  parameter.  This
       pattern  is  common to all TCTI initialization functions. We provide an example of this pattern using the
       Tss2_Tcti_Cmd_Init() function in the section titled EXAMPLE.

       The conf parameter is a C string used to configure the TCTI context. This  configuration  string  is  the
       command used for popen(3). The conf string cannot be NULL for this TCTI.

       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 a service that can excahnge  TPM2  command  and  response  buffers.  In
       nearly  all  cases  however,  the caller will initialize a context using this function before passing the
       context to a higher level API like the System API (SAPI), Enhanced System  API  (ESAPI)  or  Feature  API
       (FAPI) and then never touch it again.

       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_Cmd_Init() will return TSS2_RC_SUCCESS.  An unsuccessful call will produce
       a response code described in section ERRORS.

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.

EXAMPLE

       TCTI initialization fragment:

       #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 = "XXX TODO SAMPLE"

       rc = Tss2_Tcti_Cmd_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_Cmd_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);
       }

AUTHOR

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

SEE ALSO

       Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3),
       tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

COLOPHON

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

TPM2 Software Stack                                 MAY 2020                               Tss2_Tcti_Cmd_Init(3)