[libsecret: 1/2] Add TPM2 file backend support build/test documentation

[Daiki Ueno <dueno src gnome org>]

commit 431bd637bc0a31420c89bd20bbd048639612c3ca
Author: Dhanuka Warusadura <csx tuta io>
Date:   Mon Aug 23 10:59:16 2021 +0530

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

 docs/reference/libsecret/libsecret-docs.sgml |  2 +
 docs/reference/libsecret/libsecret-tpm2.sgml | 67 ++++++++++++++++++++++++++++
 docs/reference/libsecret/meson.build         |  1 +
 3 files changed, 70 insertions(+)
---
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',
 ]