diff --git a/.github/workflows/build-solution.yml b/.github/workflows/build-solution.yml index 71e03f7..3954048 100644 --- a/.github/workflows/build-solution.yml +++ b/.github/workflows/build-solution.yml @@ -81,7 +81,7 @@ jobs: - name: Build Rust code run: | - ./build-solution.sh + ./build-converter.sh - name: Run Rust unit tests env: diff --git a/README.md b/README.md index 3479474..99ab448 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,93 @@ +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 +-------------- + +1. Install Rust: + Follow [this](https://www.rust-lang.org/tools/install) guide. + + +2. Install Docker: + Follow [this](https://docs.docker.com/engine/install/) guide. + + +3. Set up your Nitro-enabled AWS EC2 instance: + - Install docker on your EC2: + Follow step #2 + - Install nitro-cli on your EC2: + Follow [this](https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave-cli-install.html) guide. + + +4. 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 . + ``` + +5. Compile container converter: + ```bash + # Run from the root of the repository + cd salmiac + ./build-converter.sh + ``` + +6. Create a simple conversion request json file + ```javascript + { + "input_image": { + "name": "", + }, + "output_image": { + "name": "", + }, + "converter_options": { + "debug": true + }, + "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 + ```bash + # Run from the root of the repository + cd tools/container-converter/target/debug + ./container-converter --request-file + ``` + +8. Copy converted image into your EC2 instance and run the image + ```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 + ``` + # Contributing We gratefully accept bug reports and contributions from the community. diff --git a/build-solution.sh b/build-converter.sh similarity index 100% rename from build-solution.sh rename to build-converter.sh