From 0c6a49bde6f5978f9e94a67fe89a4bc311126dad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marcus=20Sch=C3=A4fer?= <marcus.schaefer@gmail.com>
Date: Sat, 7 Sep 2024 22:17:12 +0200
Subject: [PATCH] Add documentation

---
 doc/source/building_images.rst               |   1 +
 doc/source/building_images/build_enclave.rst | 101 +++++++++++++++++++
 doc/source/conf.py                           |   2 +
 tox.ini                                      |   1 +
 4 files changed, 105 insertions(+)
 create mode 100644 doc/source/building_images/build_enclave.rst

diff --git a/doc/source/building_images.rst b/doc/source/building_images.rst
index d8451e208eb..22324dbc9b2 100644
--- a/doc/source/building_images.rst
+++ b/doc/source/building_images.rst
@@ -17,3 +17,4 @@ Building Images for Supported Types
    building_images/build_container_image
    building_images/build_wsl_container
    building_images/build_kis
+   building_images/build_enclave
diff --git a/doc/source/building_images/build_enclave.rst b/doc/source/building_images/build_enclave.rst
new file mode 100644
index 00000000000..8b176e44a01
--- /dev/null
+++ b/doc/source/building_images/build_enclave.rst
@@ -0,0 +1,101 @@
+Build an AWS Nitro Enclave
+==============================
+
+.. sidebar:: Abstract
+
+   This page explains how to build AWS Nitro Enclaves. It covers the following topics:
+
+   * how to build an AWS Nitro Enclave
+   * how to test the enclave via QEMU
+
+AWS Nitro Enclaves enables customers to create isolated compute environments
+to further protect and securely process highly sensitive data such as personally
+identifiable information (PII), healthcare, financial, and intellectual property
+data within their Amazon EC2 instances. Nitro Enclaves uses the same Nitro
+Hypervisor technology that provides CPU and memory isolation for EC2 instances.
+For further details please visit https://aws.amazon.com/ec2/nitro/nitro-enclaves
+
+To add an enclave build to your appliance, create a `type` element with
+`image` set to `enclave` in the :file:`config.xml` file as shown below:
+
+.. code:: xml
+
+   <image schemaversion="{schema_version}" name="Tumbleweed_enclave">
+     <!-- snip -->
+     <profiles>
+       <profile name="default" description="CPIO: default profile" import="true"/>
+       <profile name="std" description="KERNEL: default kernel" import="true"/>
+     </profiles>
+     <preferences>
+       <type image="enclave" enclave_format="aws-nitro" kernelcmdline="reboot=k panic=30 pci=off console=ttyS0 i8042.noaux i8042.nomux i8042.nopnp i8042.dumbkbd random.trust_cpu=on rdinit=/sbin/init"/>
+       <!-- additional preferences -->
+     </preferences>
+     <packages type="image" profiles="std">
+        <package name="kernel-default"/>
+     </packages>
+     <!-- more packages -->
+     <!-- snip -->
+   </image>
+
+The following attributes of the `type` element are relevant:
+
+- `enclave_format`: Specifies the enclave target
+
+  As of today only the `aws-nitro` enclave target is supported
+
+
+- `kernelcmdline`: Specifies the kernel commandline suitable for the enclave
+
+  An enclave is a system that runs completely in RAM loaded from
+  an enclave binary format which includes the kernel, initrd and
+  the kernel commandline suitable for the target system.
+
+With the appropriate settings specified in :file:`config.xml`, you can build an
+image using {kiwi}:
+
+.. code:: bash
+
+   $ sudo kiwi-ng system build \
+         --description kiwi/build-tests/{exc_description_enclave} \
+         --set-repo {exc_repo_tumbleweed} \
+         --target-dir /tmp/myimage
+
+The resulting image is saved in :file:`/tmp/myimage`, and the image can
+be tested with QEMU:
+
+.. code:: bash
+
+   $ sudo qemu-system-x86_64 \
+         -M nitro-enclave,vsock=c \
+         -m 4G \
+         -nographic \
+         -chardev socket,id=c,path=/tmp/vhost4.socket \
+         -kernel {exc_image_base_name_enclave}.eif
+
+The image is now complete and ready to use. Access to the system is
+possible via ssh through a vsock connection into the guest. To establish
+a vsock connection it's required to forward the connection through the
+guest AF_VSOCK socket. This can be done via a ProxyCommand setup of the
+host ssh as follows:
+
+.. code:: bash
+
+   $ vi ~/bin/vsock-ssh.sh
+
+   #!/bin/bash
+   CID=$(echo "$1" | cut -d . -f 1)
+   socat - VSOCK-CONNECT:$CID:22
+
+.. code:: bash
+
+   $ vi ~/.ssh/config
+
+   host *.vsock
+     ProxyCommand ~/bin/vsock-ssh.sh %h
+
+After the ssh proxy setup login to the enclave with a custom vsock port
+as follows:
+
+.. code:: bash
+
+   $ ssh root@21.vsock
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 50ab4e5dfca..65ed220ee46 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -70,6 +70,7 @@ def setup(app):
     '{exc_image_base_name_disk_simple}': 'kiwi-test-image-disk-simple',
     '{exc_image_base_name_live}': 'kiwi-test-image-live',
     '{exc_image_base_name_docker}': 'kiwi-test-image-docker',
+    '{exc_image_base_name_enclave}': 'kiwi-test-image-nitro-enclave',
     '{exc_netboot}': 'netboot/suse-tumbleweed',
     '{exc_description_pxe}': 'x86/tumbleweed/test-image-pxe',
     '{exc_description_vagrant}': 'x86/leap/test-image-vagrant',
@@ -78,6 +79,7 @@ def setup(app):
     '{exc_description_live}': 'x86/leap/test-image-live',
     '{exc_description_wsl}': 'x86/tumbleweed/test-image-wsl',
     '{exc_description_docker}': 'x86/leap/test-image-docker',
+    '{exc_description_enclave}': 'x86/tumbleweed/test-image-nitro-enclave',
     '{exc_os_version}': '15.5',
     '{exc_image_version}': '1.15.3',
     '{exc_repo_leap}': 'obs://openSUSE:Leap:15.5/standard',
diff --git a/tox.ini b/tox.ini
index 369f8fbf99d..fe791d19dae 100644
--- a/tox.ini
+++ b/tox.ini
@@ -49,6 +49,7 @@ basepython =
     check: python3
     devel: python3
     packagedoc: python3
+    doc: python3
 passenv =
     *
 usedevelop = True