Merge branch 'master' into ns/SALM-564

Author: nshyrei

.github/workflows/build-solution.yml

@@ -87,7 +87,7 @@ jobs:
 
       - name: Build Rust code
         run: |
-          ./build-solution.sh
+          ./build-converter.sh
 
       - name: Run Rust unit tests
         env:

README.md

@@ -1,3 +1,115 @@
+Salmiac
+======
+
+
+A confidential VM running unmodified container images in AWS [Nitro Enclaves](https://aws.amazon.com/ec2/nitro/).
+Salmiac makes it possible to run an application in isolated compute environments to protect and securely process highly sensitive data.
+
+By default bare Nitro Enclaves doesn't provide any networking capability outside of the enclave environment as well
+as no persistent storage, meaning that all your data is lost when container image finishes its execution.
+
+Salmiac enhances Nitro Enclaves by enabling networking for external communication and providing encrypted persistent storage.
+
+Useful links
+------------
+
+* :wrench: [Nitro-cli](https://github.com/aws/aws-nitro-enclaves-cli) a tool Salmiac is built on.
+* :book: [The Security Design of the AWS Nitro System](https://docs.aws.amazon.com/whitepapers/latest/security-design-of-aws-nitro-system/security-design-of-aws-nitro-system.html), official Nitro Enclaves whitepaper.
+* :film_projector: [Presentation](https://archive.fosdem.org/2023/schedule/event/cc_aws/) of Salmiac internals.
+
+Quick Start Guide
+--------------
+This guide allows you to build salmiac from source and convert your docker application into a one that can run in a nitro enclave. 
+
+1. Set up your Ubuntu based build system:
+    - Install Rust:
+      Follow [this](https://www.rust-lang.org/tools/install) guide.
+    - Install Docker:
+      Follow [this](https://docs.docker.com/engine/install/) guide to install version 24.0.x
+      OR
+      ```bash
+      apt-get install docker-ce=5:24.0.1-1~ubuntu.20.04~focal docker-ce-cli=5:24.0.1-1~ubuntu.20.04~focal  containerd.io
+      ```
+    - Install tools needed to build the linux kernel:
+      Follow [this](https://kernelnewbies.org/KernelBuild) guide.
+    - Install additional dependencies:
+      ```bash
+      apt-get install pkg-config libclang-dev cmake libpcap-dev
+      ```
+
+2. Set up your Nitro-enabled AWS EC2 instance:
+    - Install docker on your EC2:
+      Follow [this](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-docker.html) guide.
+    - Install nitro-cli on your EC2:
+      Follow [this](https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave-cli-install.html) guide.
+
+
+3. Build requisite docker images needed to run container converter
+   ```bash
+   # Run from the root of the repository
+   # build enclave-base image
+   cd salmiac/docker/enclave-base
+   docker build -t enclave-base .
+         
+   # build parent-base image
+   cd ../parent-base
+   docker build -t parent-base .
+    ```
+
+4. Build the enclave kernel. This step takes a long time and needs to be done only once. The artifacts produced by this step need not be cleaned up unless the kernel config is updated.
+   ```bash
+   cd amzn-linux-nbd
+   ./build-enclave-kernel.sh build
+    ```
+
+5. Build the converter image. To produce a debug build of the converter, ensure the release flag is removed from the step below.
+    ```bash
+      # Run from the root of the repository
+      cd salmiac
+      # To produce a debug build of the converter, ensure the release flag is removed from the step below.
+      ./build-converter.sh --release
+
+      cd docker
+      # If a debug build of the converter was produced, use debug as an argument to the below script
+      ./build-conv-container.sh release
+    ```
+
+6. Create a simple conversion request json file (say /tmp/req.json)
+   More details about each field of the conversion request can be found in /salmiac/api-model/src/converter.rs
+   ```javascript
+    {
+      "input_image": {
+         "name": "hello-world", 
+      },
+      "output_image": {
+         "name": "hello-world-nitro",
+      },
+      "converter_options": {
+         "push_converted_image": false,
+         "enable_overlay_filesystem_persistence": false
+      },
+      "nitro_enclaves_options": {
+         "cpu_count": 2,
+         "mem_size": "4096M"
+      }
+   }
+   ```
+
+7. Make your application Nitro VM-capable by running container converter with the file from previous step.
+   The converter by default pulls the input image and pushes the output image to remote repositories. These images are then cleaned up from the local docker cache. In our example, the output image push is disabled in the request json and to preserve the images in the docker cache, 'PRESERVE_IMAGES' environment variable is specified.
+   ```bash
+      docker run --rm --name converter --user 0 --privileged -v /var/run/docker.sock:/var/run/docker.sock -e PRESERVE_IMAGES=input,result -v /tmp/req-files:/app converter --request-file /app/req.json
+    ```
+
+8. Copy converted image into your EC2 instance and run the image.
+   Note the use of the environment variable which disables the use of default certificates, which allows you to skip access to Fortanix CCM. Read more about environment variables used in salmiac here - /salmiac/ENV_VARS.md
+   ```bash
+      # Copy your converted image from step #7 into your EC2 isntance
+      # ...       
+      # Run copied image inside EC2
+      docker run -it --rm --privileged -v /run/nitro_enclaves:/run/nitro_enclaves -e ENCLAVEOS_DISABLE_DEFAULT_CERTIFICATE=true hello-world-nitro
+    ```
+
 # Contributing
 
 We gratefully accept bug reports and contributions from the community.
@@ -32,4 +144,4 @@ this project or the open source license(s) involved.
 
 # License
 
-This project is primarily distributed under the terms of the Mozilla Public License (MPL) 2.0, see [LICENSE](./LICENSE) for details.
+This project is primarily distributed under the terms of the Mozilla Public License (MPL) 2.0, see [LICENSE](./LICENSE) for details.

build-solution.sh renamed to build-converter.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+
+set -exo pipefail
+
+clonelinux() {
+
+  # Clone the amazon linux kernel repository and checkout
+  # the branch which is used for nitro enclaves
+  # You can find out the kernel version used by nitro-enclaves
+  # by running uname -a in a converted app. In this case, we
+  # use version 4.14.246
+  # For more details about supported nitro enclave kernel
+  # versions, refer to the aws-nitro-enclaves-cli github repository.
+
+  if [ -d "linux" ]; then
+    cd linux
+    git fetch
+  else
+    git clone https://github.com/amazonlinux/linux.git
+    cd linux
+  fi
+
+  git checkout microvm-kernel-4.14.246-198.474.amzn2
+
+}
+
+buildkernel() {
+
+  # Copy the enclave kernel config file into the kernel repository
+  # The original file is available here:
+  # https://github.com/aws/aws-nitro-enclaves-cli/blob/main/blobs/x86_64/bzImage.config
+  # The config file available in this directory has been updated to
+  # support salmiac features.
+  cp ../bzImage.config .config
+
+  # Build the enclave kernel
+  make prepare
+  make modules_prepare
+  make modules -j
+  make -j
+  make bzImage
+
+  # Once build is complete, we would need a copy of the bzImage file
+  cp ./arch/x86/boot/bzImage ../
+  cp .config ../bzImage.config
+
+  cd ../
+}
+
+cleankernel() {
+  if [ -d "linux" ]; then
+    rm -rf linux
+  fi
+}
+
+if [ $1 == "build" ]; then
+  clonelinux;
+  buildkernel;
+elif [ $1 == "clean" ]; then
+ cleankernel;
+else
+  echo "Provide input arguments - build or clean"
+fi
+