Add TPM2 file backend support build/test documentation

These changes add TPM2 file backend support build and test
instructions to default documentation.

3 files changed, 70 insertions, 0 deletions

diff --git a/docs/reference/libsecret/libsecret-docs.sgml b/docs/reference/libsecret/libsecret-docs.sgml
index 0381c5a..210f21a 100644
--- a/docs/reference/libsecret/libsecret-docs.sgml
+++ b/docs/reference/libsecret/libsecret-docs.sgml
@@ -37,6 +37,8 @@
 
 	<xi:include href="libsecret-using.sgml"/>
 
+	<xi:include href="libsecret-tpm2.sgml"/>
+
 	<xi:include href="xml/migrating-libgnome-keyring.xml"/>
 
 	<xi:include href="xml/annotation-glossary.xml">
diff --git a/docs/reference/libsecret/libsecret-tpm2.sgml b/docs/reference/libsecret/libsecret-tpm2.sgml
new file mode 100644
index 0000000..184e26a
--- /dev/null
+++ b/docs/reference/libsecret/libsecret-tpm2.sgml
@@ -0,0 +1,67 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<part>
+<title>Extending file backend to use a TPM</title>
+
+<chapter>
+<title>Introduction</title>
+
+<para>The current implementation of file backend uses an encryption key derived from the user's login password. Security wise this not an ideal situation. Because, the entire security of the file backend relies on the user's login password (single point of failure). This situation can be improved if the keys are protected/generated by hardware. A Trusted Platform Module (TPM) is a such hardware security module found in modern computer systems.</para>
+
+<para>The new <application>EGG_TPM2 API</application> based on the <application>TSS Enhanced System API (ESAPI)</application></para>
+
+<informalexample><programlisting>
+EggTpm2Context *egg_tpm2_initialize               (GError **);
+void           egg_tpm2_finalize                  (EggTpm2Context *);
+GBytes         *egg_tpm2_generate_master_password (EggTpm2Context *,
+		                                   GError **);
+GBytes         *egg_tpm2_decrypt_master_password  (EggTpm2Context *,
+		                                   GBytes *,
+						   GError **);
+</programlisting></informalexample>
+</chapter>
+
+<chapter>
+<title>Build and test libsecret with TPM2 support</title>
+
+<para>In order to try out the <application>TPM2 support</application> use the <literal>-Dtpm2=true</literal> build option/flag during the <literal>meson _build</literal> process.</para>
+
+<para>You can alter the default build and install process as the following:</para>
+
+<informalexample><programlisting>
+$ meson _build -Dtpm2=true
+$ ninja -C _build
+$ ninja -C _build install
+</programlisting></informalexample>
+
+<para>For testing the TPM2 support you need a physical TPM or a TPM emulator. The following sections demonstrate how to setup <ulink url="https://github.com/stefanberger/swtpm">swtpm</ulink> emulator and testing out the TPM2 support. If you have access to a TPM you can ignore the emulator section.</para>
+
+<para>swtpm emulator setup:</para>
+
+<informalexample><programlisting>
+$ dnf install swtpm swtpm-tools tpm2-abrmd tpm2-tss-devel
+$ eval `dbus-launch --sh-syntax`
+$ export XDG_CONFIG_HOME=$HOME/.config/swtpm
+$ /usr/share/swtpm/swtpm-create-user-config-files --root
+$ mkdir -p ${XDG_CONFIG_HOME}/mytpm1
+$ swtpm_setup --tpm2 --tpmstate $XDG_CONFIG_HOME/mytpm1 --createek --allow-signing --decryption --create-ek-cert --create-platform-cert --lock-nvram --overwrite --display
+$ swtpm socket --tpm2 --tpmstate dir=$XDG_CONFIG_HOME/mytpm1 --flags startup-clear --ctrl type=tcp,port=2322 --server type=tcp,port=2321 --daemon
+$ tpm2-abrmd --logger=stdout --tcti=swtpm: --session --allow-root --flush-all &amp;
+$ export TCTI=tabrmd:bus_type=session
+</programlisting></informalexample>
+
+<para>Test TPM2 support:</para>
+
+<informalexample><programlisting>
+$ cd libsecret
+$ meson _build -Dtpm2=true
+$ ninja -C _build
+$ export SECRET_BACKEND=file
+$ export SECRET_FILE_TEST_PATH=$PWD/keyring
+$ ./_build/tool/secret-tool store --label=foo bar baz
+$ ls # keyring
+</programlisting></informalexample>
+</chapter>
+</part>
diff --git a/docs/reference/libsecret/meson.build b/docs/reference/libsecret/meson.build
index 76479ae..d342c58 100644
--- a/docs/reference/libsecret/meson.build
+++ b/docs/reference/libsecret/meson.build
@@ -1,6 +1,7 @@
 reference_content_files = [
   'libsecret-examples.sgml',
   'libsecret-using.sgml',
+  'libsecret-tpm2.sgml',
   'migrating-libgnome-keyring.xml',
 ]