GettingStarted: Add secure boot

Change-Id: I906a7cb4f7687ddc6d7cc575c856e9145c05c8e3
Signed-off-by: Sona Sarmadi <sona.sarmadi@enea.com>

2 files changed, 189 insertions, 0 deletions

diff --git a/doc/book-enea-nfv-access-getting-started/doc/book.xml b/doc/book-enea-nfv-access-getting-started/doc/book.xml
index 1f51d01..534b7f9 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/book.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/book.xml
@@ -24,6 +24,9 @@
   <xi:include href="getting_started_nfv_access.xml"
                 xmlns:xi="http://www.w3.org/2001/XInclude" />
                           
+  <xi:include href="secure_boot.xml"
+              xmlns:xi="http://www.w3.org/2001/XInclude" />
+
   <xi:include href="getting_started_ucpe_manager.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />                               
                           
diff --git a/doc/book-enea-nfv-access-getting-started/doc/secure_boot.xml b/doc/book-enea-nfv-access-getting-started/doc/secure_boot.xml
new file mode 100644
index 0000000..cf2e935
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/secure_boot.xml
@@ -0,0 +1,186 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="secure_boot">
+  <title>UEFI Secure Boot</title>
+
+  <para>This chapter contains information needed in order to enable the Secure
+  Boot. Secure Boot is an optional feature in the Enea NFV Access Run Time
+  Platform. If you do not intend to use this feature, skip to the next
+  chapter.</para>
+
+  <section id="intro">
+    <title>Introduction</title>
+
+    <para>Secure Boot was designed to enhance security in the pre-boot
+    environment. It prevents malicious software and applications from being
+    loaded during the system start-up process.</para>
+
+    <para>The basic principle of UEFI Secure Boot is that it requires all
+    artifacts involved in the boot process (bootloaders, kernel, initramfs) to
+    be signed using a set of private keys. On a Secure Boot enabled uCPE device
+    these artifacts are checked against a set of public certificates which
+    correspond to these keys. If there are any mismatches the boot process
+    will fail at various stages.</para>
+
+    <para>For more information about Secure Boot please refer to <ulink
+    url="https://www.uefi.org/sites/default/files/resources/UEFI_Secure_Boot_in_Modern_Computer_Security_Solutions_2013.pdf">Secure
+    Boot in Modern Computer Security Solutions</ulink>.</para>
+  </section>
+
+  <section id="secure_boot_keys">
+    <title>Enabling UEFI Secure Boot</title>
+
+    <para>All Enea NFV Access image artifacts delivered with the release are
+    signed using the Enea UEFI Secure boot private keys. These artifacts can
+    be used on a uCPE device that doesn't have Secure Boot enabled. To use the
+    Secure Boot feature, however, the user must make the Enea UEFI Secure Boot
+    public certificates available on the uCPE device before enabling the feature
+    in BIOS. This process is called "Provisioning".</para>
+
+    <section id="manual_key_provisioning">
+      <title>Provisioning the Enea UEFI Secure Boot Certificates</title>
+
+      <para>The UEFI firmware is normally shipped with factory preloaded
+      certificates. If these do not already include Certificates from Enea,
+      they will need to be appended or replaced with the Enea
+      Certificates.</para>
+
+      <para><emphasis role="bold">UEFI Secure Boot certificates provided with
+      your release:</emphasis></para>
+
+      <itemizedlist>
+        <listitem>
+          <para><literal>Platform Key (PK)</literal>: the purpose of this key
+          is to protect the next key from uncontrolled modification. Once this
+          key is enrolled, Secure Boot enters into <literal>User
+          Mode</literal>. The drivers and loaders signed with the
+          <literal>platform key</literal> can then be loaded by the
+          firmware.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>Key Exchange key (KEK)</literal>: this key allows
+          other certificates which have a connection to the private portion of
+          the <literal>platform key</literal> to be used.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>Authorized Signature (DB)</literal>: contains the
+          <literal>trusted keys</literal> used for authenticating any drivers
+          or applications executed in the UEFI environment.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>The Enea UEFI Secure Boot certificates are installed together with
+      the Enea NFV Access Run Time Platform onto the hard drive. They can be
+      found on the EFI partition (usually the first partition of the drive)
+      under /uefi_sb_keys.</para>
+
+      <para><emphasis role="bold">How to manually enroll Enea
+      Certificates</emphasis></para>
+
+      <orderedlist>
+        <listitem>
+          <para>Reboot the uCPE device and press <literal>DEL</literal> to
+          enter into the BIOS.</para>
+        </listitem>
+
+        <listitem>
+          <para>Select "Secure Booot Mode" -&gt; "Custom".</para>
+        </listitem>
+
+        <listitem>
+          <para>Select <literal>Key Management</literal> from the
+          <literal>Security</literal> menu.</para>
+        </listitem>
+
+        <listitem>
+          <para>Enroll the <literal>Platform Key (PK)</literal>: <itemizedlist>
+              <listitem>
+                Select "Set New Key" -&gt; "File from a file system".
+              </listitem>
+
+              <listitem>
+                Specify the folder:
+
+                <literal>&lt;user-keys&gt;/&lt;uefi_sb_keys&gt;/PK.esl</literal>
+
+                .
+              </listitem>
+
+              <listitem>
+                Select "Public Key Certificate" and then "Ok".
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>Enroll the <literal>Key Exchange key (KEK)</literal>:
+          <itemizedlist>
+              <listitem>
+                Select "Set New Key" -&gt; "File from a file system".
+              </listitem>
+
+              <listitem>
+                Specify the folder:
+
+                <literal>&lt;user-keys&gt;/&lt;uefi_sb_keys&gt;/KEK.esl</literal>
+
+                .
+              </listitem>
+
+              <listitem>
+                Select "Public Key Certificate" and then "ok".
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+
+        <listitem>
+          <para>Enroll the <literal>Authorized Signature (DB)</literal>:
+          <itemizedlist>
+              <listitem>
+                Select "Set New Key" -&gt; "File from a file system".
+              </listitem>
+
+              <listitem>
+                Specify the folder:
+
+                <literal>&lt;user-keys&gt;/&lt;uefi_sb_keys&gt;/DB.esl</literal>
+
+                .
+              </listitem>
+
+              <listitem>
+                Select "Public Key Certificate" and then "ok".
+              </listitem>
+            </itemizedlist></para>
+        </listitem>
+      </orderedlist>
+
+      <note>
+        <para>Details on how to provision the certificates may vary with
+        different versions of UEFI firmware.</para>
+      </note>
+    </section>
+
+    <section id="enable_secure_boot">
+      <title>Turn on Secure Boot in BIOS</title>
+
+      <para>Finally, once the certificates are provisioned we can enable the
+      Secure Boot feature:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Select <literal>Security option</literal> from the top
+          menu.</para>
+        </listitem>
+
+        <listitem>
+          <para>Set the <literal>Boot Menu</literal> -&gt;
+          <literal>Enabled.</literal></para>
+        </listitem>
+      </orderedlist>
+    </section>
+  </section>
+</chapter>