Merge branch '1.x'
Conflicts:
.gitignore
Makefile.am
diff --git a/.gitignore b/.gitignore
index 1be86e1..44e2058 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,6 +32,7 @@
ltmain.sh
m4/libtool*
m4/lt*.m4
+man/man[0-9]/*
Makefile
Makefile.in
missing
diff --git a/Makefile.am b/Makefile.am
index d69ef41..798000c 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -61,7 +61,10 @@
test/integration/start-auth-session
TESTS = $(check_PROGRAMS)
-CLEANFILES = $(nodist_pkgconfig_DATA)
+CLEANFILES = \
+ $(nodist_pkgconfig_DATA) \
+ $(man3_MANS) \
+ $(man7_MANS)
AM_TESTS_ENVIRONMENT = \
export TPM20TEST_TCTI_NAME="socket"; \
@@ -77,6 +80,14 @@
# pkg-config files
pkgconfigdir = $(libdir)/pkgconfig
nodist_pkgconfig_DATA = lib/sapi.pc lib/tcti-device.pc lib/tcti-socket.pc
+# man pages / documentation
+man3_MANS = man/man3/InitDeviceTcti.3 man/man3/InitSocketTcti.3
+man7_MANS = man/man7/tcti-device.7 man/man7/tcti-socket.7
+
+EXTRA_DIST = \
+ man/InitDeviceTcti.3.in \
+ man/tcti-device.7.in \
+ man/tcti-socket.7.in
if UNIT
test_unit_tcti_device_CFLAGS = $(CMOCKA_CFLAGS) $(AM_CFLAGS)
@@ -168,10 +179,16 @@
TESTS_LDADD = $(noinst_LTLIBRARIES) $(lib_LTLIBRARIES)
%.pc : %.pc.in
- if [ ! -d $(dir $@) ]; then mkdir -p $(dir $@); fi
+ $(call make_parent_dir,$@)
sed -e "s,[@]VERSION[@],$(PACKAGE_VERSION),g; \
s,[@]includedir[@],$(includedir),g;" $^ > $@
+man/man3/%.3 : man/%.3.in $(srcdir)/man/man-postlude.troff
+ $(call make_man,$@,$<,$(srcdir)/man/man-postlude.troff)
+
+man/man7/%.7 : man/%.7.in $(srcdir)/man/man-postlude.troff
+ $(call make_man,$@,$<,$(srcdir)/man/man-postlude.troff)
+
# simulator build / run scripts
CLEANFILES += test/simulator-build.sh test/simulator-run.sh test/simulator.inc
.PHONY = simulator-build simulator-start simulator-stop clean-local-ibmtpm
@@ -200,3 +217,16 @@
libtcti_socket = tcti/libtcti-socket.la
libmarshal = marshal/libmarshal.la
tpmclient = test/tpmclient/tpmclient
+
+define make_parent_dir
+ if [ ! -d $(dir $1) ]; then mkdir -p $(dir $1); fi
+endef
+# function to transform man .in files to man pages
+# $1: target
+# $2: .in file
+# $3: man postlude file
+define make_man
+ $(call make_parent_dir,$1)
+ cat $2 $3 > $1
+ sed -i -e "s,[@]VERSION[@],$(PACKAGE_VERSION),g;" $1
+endef
diff --git a/configure.ac b/configure.ac
index 1135060..792ffd6 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,8 +1,5 @@
-m4_define([tpm20_major_version], [1])
-m4_define([tpm20_minor_version], [0])
-m4_define([tpm20_version_string], [tpm20_major_version.tpm20_minor_version])
-
-AC_INIT([tpm2.0-tss], [tpm20_version_string])
+AC_INIT([tpm2.0-tss],
+ [m4_esyscmd_s([git describe --tags --always --dirty])])
AC_CONFIG_MACRO_DIR([m4])
AC_PROG_CC
LT_INIT()
diff --git a/man/InitDeviceTcti.3.in b/man/InitDeviceTcti.3.in
new file mode 100644
index 0000000..6474b2f
--- /dev/null
+++ b/man/InitDeviceTcti.3.in
@@ -0,0 +1,164 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.TH InitDeviceTcti 3 "JUNE 2017" Intel "TPM2 Software Stack"
+.SH NAME
+InitDeviceTcti \- Initialization function for the device TCTI library.
+.SH SYNOPSIS
+.B #include <tcti/tcti_device.h>
+.sp
+.BI "typedef int (*TCTI_LOG_CALLBACK)( void " "*data" ", printf_type" "type" ", const char " "*format" ", "..." ");"
+.sp
+.nf
+typedef struct {
+ const char *device_path;
+ TCTI_LOG_CALLBACK logCallback;
+ void *logData;
+} TCTI_DEVICE_CONF;
+.fi
+.sp
+.BI "TSS2_RC InitDeviceTcti (TSS2_TCTI_CONTEXT " "*tctiContext" ", size_t " "*contextSize" ", const TCTI_DEVICE_CONF " "*config" ");"
+.sp
+The
+.BR InitDeviceTcti ()
+function initializes a TCTI context used to communicate with the TPM device
+driver.
+.SH DESCRIPTION
+.BR InitDeviceTcti ()
+attempts to initialize a caller allocated
+.I tcti_context
+of size
+.I size
+\&. Since the
+.I tcti_context
+must be a caller allocated buffer, the caller needs to know the size required
+by the TCTI library. The minimum size of this context can be discovered by
+providing
+.BR NULL
+for the
+.I tcti_context
+and a non-
+.BR NULL
+.I size
+parameter. The initialization function will then populate the
+.I size
+parameter with the minimum size of the
+.I tcti_context
+buffer. The caller must then allocate a buffer of this size (or larger) and
+call
+.B InitDeviceTcti ()
+again providing the newly allocated
+.I tcti_context
+and the size of this context in the
+.I size
+parameter. This patterm is common to all TCTI initialization functions. We
+provide an example of this pattern using the
+.BR InitDeviceTcti ()
+function in the section titled
+.B EXAMPLE.
+.sp
+The
+.I config
+parameter is a reference to an instance of the
+.B TCTI_DEVICE_CONF
+structure. The
+.I device_path
+member of this structure is a C string that contains the path to the device
+node exposed by the TPM device driver.
+.sp
+The
+.I logCallback
+parameter is a pointer to a callback function that will be called by the
+device TCTI. This is expected to be a
+.I printf
+like function.
+.sp
+The
+.I logData
+member is a void pointer to user data that will be supplied to the
+.I logCallback
+function on each invocation.
+.sp
+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
+respons buffers with the TPM device driver. In nearly all cases however, the
+caller will initialize a context using this funnction before passing the
+context to a higher level API like the System API (SAPI), and then never touch
+it again.
+.sp
+For a more thorough discussion of the TCTI API see the \*(lqTSS System Level
+API and TPM Command Transmission Interface Specification\*(rq as published by
+the TCG:
+\%https://trustedcomputinggroup.org/tss-system-level-api-tpm-command-transmission-interface-specification/
+.SH RETURN VALUE
+A successful call to
+.BR InitDeviceTcti ()
+will return
+.B TSS2_RC_SUCCESS.
+An unsuccessful call will produce a response code described in section
+.B ERRORS.
+.SH ERRORS
+.B TSS2_TCTI_RC_BAD_VALUE
+is returned if both the
+.I tcti_context
+and the
+.I size
+parameters are NULL, or if the
+.I config
+parameter is NULL.
+.SH EXAMPLE
+Logging function:
+.sp
+.nf
+int DebugPrintfCallback( void *data, printf_type type, const char *format, ...)
+{
+ va_list args;
+ int rval = 0;
+
+ va_start( args, format );
+ rval = vprintf( format, args );
+ va_end (args);
+
+ return rval;
+}
+.fi
+.sp
+TCTI initialization fragment:
+.sp
+.nf
+#include <inttypes.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <tcti/tcti_device.h>
+
+TSS2_RC rc;
+TSS2_TCTI_CONTEXT *tcti_context;
+size_t size;
+TCTI_DEVICE_CONF conf = {
+ .device_path = "/dev/tpm0",
+ .logCallback = DebugPrintfCallback,
+ .logData = NULL,
+};
+
+rc = InitDeviceTcti (NULL, &size, NULL);
+if (rc != TSS2_RC_SUCCESS) {
+ fprintf (stderr, "Failed to get allocation size for tabrmd TCTI "
+ " context: 0x%" PRIx32 "\n", rc);
+ exit (EXIT_FAILURE);
+}
+tcti_context = calloc (1, size);
+if (tcti_context == NULL) {
+ fprintf (stderr, "Allocation for TCTI context failed: %s\n",
+ strerror (errno));
+ exit (EXIT_FAILURE);
+}
+rc = InitDeviceTcti (&tcti_context, &size, &conf);
+if (rc != TSS2_RC_SUCCESS) {
+ fprintf (stderr, "Failed to initialize tabrmd TCTI context: "
+ "0x%" PRIx32 "\n", rc);
+ free (tcti_context);
+ exit (EXIT_FAILURE);
+}
+exit (EXIT_SUCCESS);
+.fi
diff --git a/man/InitSocketTcti.3.in b/man/InitSocketTcti.3.in
new file mode 100644
index 0000000..9176e8a
--- /dev/null
+++ b/man/InitSocketTcti.3.in
@@ -0,0 +1,198 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.TH InitSocketTcti 3 "JUNE 2017" Intel "TPM2 Software Stack"
+.SH NAME
+InitSocketTcti \- Initialization function for the Microsoft TPM simulator TCTI library.
+.SH SYNOPSIS
+.B #include <tcti/tcti_socket.h>
+.sp
+.BI "typedef int (*TCTI_LOG_CALLBACK)( void " "*data" ", printf_type" "type" ", const char " "*format" ", "..." ");"
+.sp
+.nf
+typedef struct {
+ const char *hostname;
+ uint16_t port;
+ TCTI_LOG_CALLBACK logCallback;
+ TCTI_LOG_BUFFER_CALLBACK logBufferCallback;
+ void *logData;
+} TCTI_SOCKET_CONF;
+.fi
+.sp
+.BI "TSS2_RC InitSocketTcti (TSS2_TCTI_CONTEXT " "*tctiContext" ", size_t " "*contextSize" ", const TCTI_SOCKET_CONF " "*config" ", const uint8_t " "serverSockets" ");"
+
+.sp
+The
+.BR InitSocketTcti ()
+function initializes a TCTI context used to communicate with the Microsoft TPM
+simulator.
+.SH DESCRIPTION
+.BR InitSocketTcti ()
+attempts to initialize a caller allocated
+.I tcti_context
+of size
+.I size
+using caller provided configuration information from
+.I config
+\&. Since the
+.I tcti_context
+must be a caller allocated buffer, the caller needs to know the size required
+by the TCTI library. The minimum size of this context can be discovered by
+providing
+.BR NULL
+for the
+.I tcti_context
+and a non-
+.BR NULL
+.I size
+parameter. The initialization function will then populate the
+.I size
+parameter with the minimum size of the
+.I tcti_context
+buffer. The caller must then allocate a buffer of this size (or larger) and
+call
+.B InitSocketTcti ()
+again providing the newly allocated
+.I tcti_context
+and the size of this context in the
+.I size
+parameter. This patterm is common to all TCTI initialization functions. We
+provide an example of this pattern using the
+.BR InitSocketTcti ()
+function in the section titled
+.B EXAMPLE.
+.sp
+The
+.I config
+parameter is a reference to an instance of the
+.B TCTI_SOCKET_CONF
+structure. The
+.I hostname
+member of this structure is a C string that contains the hostname or IPv4
+address of the Microsoft TPM simulator. The
+.I port
+member is an unsigned 16 bit integer containing the port number for the
+simulator command / response port. The simulator listens for \*(lqplatform
+commands\*(rq on
+.I port+1
+and so an additional connection will be made to this port. The
+.I logCallback
+member is a pointer to a callback function that will be called by the
+socket TCTI. This is expected to be a
+.I printf
+like function. The
+.I logBufferCallback
+mamber is a pointer to a call back function that will be invoked by the
+socket TCTI before a command buffer is transmitted or after a resposne buffer
+is received. This is expected to be a
+.I printf
+like function. The
+.I logData
+member is a void pointer that may be used to pass user data to the
+.I logCallback
+and
+.I logBufferCallback
+functions on each invocation.
+.sp
+The
+.I serverSockets
+parameter should always be 0 for client code.
+.sp
+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
+respons buffers with the Microsoft TPM simulator. In nearly all cases however,
+the caller will initialize a context using this funnction before passing the
+context to a higher level API like the System API (SAPI), and then never touch
+it again.
+.sp
+For a more thorough discussion of the TCTI API see the \*(lqTSS System Level
+API and TPM Command Transmission Interface Specification\*(rq as published by
+the TCG:
+\%https://trustedcomputinggroup.org/tss-system-level-api-tpm-command-transmission-interface-specification/
+.SH RETURN VALUE
+A successful call to
+.BR InitSocketTcti ()
+will return
+.B TSS2_RC_SUCCESS.
+An unsuccessful call will produce a response code described in section
+.B ERRORS.
+.SH ERRORS
+.B TSS2_TCTI_RC_BAD_VALUE
+is returned if both the
+.I tcti_context
+and the
+.I size
+parameters are NULL, or if the
+.I config
+parameter is NULL.
+.SH EXAMPLE
+Logging functions:
+.sp
+.nf
+int DebugPrintfCallback (void *data, printf_type type, const char *format, ...)
+{
+ va_list args;
+ int rval = 0;
+
+ va_start( args, format );
+ rval = vprintf( format, args );
+ va_end (args);
+
+ return rval;
+}
+void DebugPrintBuffer (printf_type type, UINT8 *buffer, UINT32 length)
+{
+ UINT32 i;
+
+ for( i = 0; i < length; i++ )
+ {
+ if( ( i % 16 ) == 0 ) {
+ printf ("\n");
+ }
+
+ printf ("%2.2x ", buffer[i] );
+ }
+ printf ("\n\n");
+}
+.fi
+.sp
+TCTI initialization fragment:
+.sp
+.nf
+#include <inttypes.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <tcti/tcti_socket.h>
+
+TSS2_RC rc;
+TSS2_TCTI_CONTEXT *tcti_context;
+size_t size;
+TCTI_SOCKET_CONF conf = {
+ .hostname = "127.0.0.1",
+ .port = 2321,
+ .logCallback = DebugPrintfCallback,
+ .logBufferCallback = DebugPrintBuffer,
+ .logData = NULL,
+};
+
+rc = InitSocketTcti (NULL, &size, NULL, 0);
+if (rc != TSS2_RC_SUCCESS) {
+ fprintf (stderr, "Failed to get allocation size for tabrmd TCTI "
+ " context: 0x%" PRIx32 "\n", rc);
+ exit (EXIT_FAILURE);
+}
+tcti_context = calloc (1, size);
+if (tcti_context == NULL) {
+ fprintf (stderr, "Allocation for TCTI context failed: %s\n",
+ strerror (errno));
+ exit (EXIT_FAILURE);
+}
+rc = InitSocketTcti (&tcti_context, &size, &conf, 0);
+if (rc != TSS2_RC_SUCCESS) {
+ fprintf (stderr, "Failed to initialize tabrmd TCTI context: "
+ "0x%" PRIx32 "\n", rc);
+ free (tcti_context);
+ exit (EXIT_FAILURE);
+}
+.fi
diff --git a/man/man-postlude.troff b/man/man-postlude.troff
new file mode 100644
index 0000000..9176dae
--- /dev/null
+++ b/man/man-postlude.troff
@@ -0,0 +1,14 @@
+.SH AUTHOR
+Philip Tricca <philip.b.tricca@intel.com>
+.SH "SEE ALSO"
+.BR InitDeviceTcti (3),
+.BR InitSocketTcti (3),
+.BR tcti-device (7),
+.BR tcti-socket (7),
+.BR tcti-tabrmd (7),
+.BR tpm2-abrmd (8)
+.SH COLOPHON
+This page is part of release @VERSION@ of Intel's 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/01org/tpm2.0-tss/.
diff --git a/man/tcti-device.7.in b/man/tcti-device.7.in
new file mode 100644
index 0000000..7551ad8
--- /dev/null
+++ b/man/tcti-device.7.in
@@ -0,0 +1,14 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.TH TCTI-DEVICE 7 "JUNE 2017" Intel "TPM2 Software Stack"
+.SH NAME
+tcti-device \- device driver TCTI library
+.SH SYNOPSIS
+A TPM Command Transmission Interface (TCTI) module for interaction with the
+TPM device driver.
+.SH DESCRIPTION
+tcti-device is a library that abstracts the details of direct communication
+with the device node exposed by the Linux kernel driver (typically /dev/tpm0).
+The interface exposed by this library is defined in the \*(lqTSS System Level
+API and TPM Command Transmission Interface Specification\*(rq specification.
diff --git a/man/tcti-socket.7.in b/man/tcti-socket.7.in
new file mode 100644
index 0000000..3d05856
--- /dev/null
+++ b/man/tcti-socket.7.in
@@ -0,0 +1,15 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.TH TCTI-SOCKET 7 "JUNE 2017" Intel "TPM2 Software Stack"
+.SH NAME
+tcti-socket \- TPM simulator TCTI library
+.SH SYNOPSIS
+A TPM Command Transmission Interface (TCTI) module for interaction with the
+Microsoft TPM2 simulator.
+.SH DESCRIPTION
+tcti-socket is a library that abstracts the details of direct communication
+with the interface and protocol exposed by the daemon hosting the TPM2
+reference implementation. The interface exposed by this library is defined
+in the \*(lqTSS System Level API and TPM Command Transmission Interface
+Specification\*(rq specification.