Build environment to enclave applications in 5 min 🚀🚀 🚀
#intelsgx # confidentialcompute
Join the discussion »
Example
·
Report Bug
·
Request Feature
- About the project
- Getting started
- Usage blueprint
- Roadmap
- Contributing
- Support
- Licence
- Contact
- Acknowledgments
Gramine (formerly called Graphene) is a lightweight library OS, designed to run a single application with minimal host requirements. Gramine can run applications in an isolated environment with benefits comparable to running a complete OS in a virtual machine -- including guest customization, ease of porting to different OSes, and process migration.
Application enclavation is a fragile and delicate task. Specifically the design of the enclave manifest is an iterative and time-consuming process. Common pitfuls are the wrong linking of (dynamic) libraries, folders and files. To speed of the process the gramineSDK advocates a blueprint of how to strucutre and enclave applications. In addition, the SDK comes with a bunch of command line tools to speed the debugging and enclavation.
The aim of this project is a standardized build environment to ease the development of SGX-ready applications along tools and scripts. Note, the SDK aims to help with building and testing the manifest.template as well as debugging the enclave. Once the manifest is in place, you may want a self-contained container of your application.
docker-compose up -d
docker-compose exec gramine-sdk bash
This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.
An enclave-ready computing platform. You can check for Intel Security Guard Extension (SGX) presence by running the following
grep sgx /proc/cpuinfo
or have a thorough look at Intel's processor list. (We remark that macbooks with CPUs transitioned to Intel are unlikely supported. If you find a configuration, please contact us know.)
Note that in addition to SGX the hardware module must support FSGSBASE. FSGSBASE is an architecture extension that allows applications to directly write to the FS and GS segment registers. This allows fast switching to different threads in user applications, as well as providing an additional address register for application use. If your kernel version is 5.9 or higher, then the FSGSBASE feature is already supported and you can skip this step.
There are several options to proceed
-
Case: No SGX-ready hardware
Azure Confidential Compute cloud offers VMs with SGX support. Prices are fair and have been recently reduced to support the developer community. First-time users get $200 USD free credit. Other cloud provider like OVH or Alibaba cloud have similar offerings. -
Case: Virtualization
Ubuntu 21.04 (Kernel 5.11) provides the driver off-the-shelf. Read the release. -
Case: Ubuntu (Kernel 5.9 or higher)
Install the DCAP drivers from the Intel SGX reposudo apt update sudo apt -y install dkms wget https://download.01.org/intel-sgx/sgx-linux/2.13.3/linux/distro/ubuntu20.04-server/sgx_linux_x64_driver_1.41.bin -O sgx_linux_x64_driver.bin chmod +x sgx_linux_x64_driver.bin sudo ./sgx_linux_x64_driver.bin sudo apt -y install clang-10 libssl-dev gdb libsgx-enclave-common libsgx-quote-ex libprotobuf17 libsgx-dcap-ql libsgx-dcap-ql-dev az-dcap-client open-enclave
-
Case: Other
Upgrade to Kernel 5.11 or higher. Follow the instructions here.
Install the docker engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
sudo usermod -aG docker $USER # manage docker as non-root user (obsolete as of docker 19.3) Use docker run hello-world to check if you can run docker (without sudo).
Add your favorite tools to packages.txt list
libprotobuf-c1 # mandatory
build-essential # mandatory
curl # mandatory
nano vim # editors
net-tools nmap # network debugging
gdb strace ltrace # trace debugging
errno # error codes
Build image
docker build \
-t enclaive/gramine-sdk \
-f ubuntu20.04-gramine-sdk.dockerfile .
To see if the hosting OS provisioned the Intel SGX driver /dev/sgx_enclave, run
docker run -it \
--device=/dev/sgx_enclave \
-v /var/run/aesmd/aesm.socket:/var/run/aesmd/aesm.socket \
--entrypoint is-sgx-available \
enclaive/gramine-sdk
and check flags SGX1, SGX driver loaded and AESMD installed are true.
Run the container
docker run -it \
--device=/dev/sgx_enclave \
-v $(pwd)/manifest:/manifest \
-v /var/run/aesmd/aesm.socket:/var/run/aesmd/aesm.socket \
--name gramine-sdk
enclaive/gramine-sdk
Sometimes it is handy to continue with the last container state (e.g. installed dependencies, applications, other tools). To this end, run the command
docker start -i gramine-sdk
Optional: Shared volume /manifestmay be tricky to use when host and container have varying permissions. Change permissions
chown -R 777 ./manifest
to access the files without sudo(e.g. from IDE)
Once you have build the container you have the following structure within the myGramineSDK container
-/
--/manifest # place the manifest here (shared volume)
--/entrypoint # place the build here
--/scripts # a bunch of helpful scripts, incl. sign, launch & relaunch
--/scripts/ssl # script to create self-signed SSL/TLS certicate (e.g. for server applications)
--/sgx-signer-key/enclaive.pem # key to sign the enclave ($SGX_SIGNER_KEY)
--/templates # copy manifest template to /manifest/myApp.manifest.template
The following commands are available to ease the enclavation of an application
sign <entrypoint> # generates signed manifest from /manifest/<entrypoint>.manifest.template
launch <entrypoint> # launches /entrypoint/<entrypoint> in an enclave
relaunch <entrypoint> # invocation of sign & launch
Remark: Gramine supports the enclavation of binaries only. <entrypoint> must be the name of the binary. Scripts (e.g. bash, python) are invoked by running the interpreter (e.g. /bin/bash) and passing myscript.sh as argument.
Build the project in folder /entrypoint
cd /gramine-sdk/sample
make
make check # expects output [Success]
cp helloworld /entrypoint
Create a manifest in folder /manifest
cp /gramine-sdk/templates/helloworld.manifest.template /manifest
cd /manifest
Configure and sign the enclave
# SDK
sign helloworld
# 'sign' calls
gramine-manifest \
helloworld.manifest.template helloworld.manifest
gramine-sgx-sign \
--key $SGX_SIGNER_KEY \
--manifest helloworld.manifest \
--output helloworld.manifest.sgx
gramine-sgx-get-token -s helloworld.sig -o helloworld.token // requires helloworld.manifest.sgx
Pre-load and execute helloworld in the enclave
# SDK
launch helloworld
# 'launch' calls
gramine-sgx /manifest/helloworld // requires helloworld.manifest.sgx helloworld.sig helloworld.token
- Add README
- Add more templates
- Add more examples
- Add tutorials
- Add debug section
- New features
- Secret key provisioning
- Remote attestation
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Don't forget to give the project a star! Spread the word on social media! Thanks again!
Distributed under the GNU Lesser General Public License v3.0 License. See LICENSE for more information.
Sebastian Gajek - @sebgaj - sebastianl@enclaive.io
Project Site - https://enclaive.io
This project greatly celebrates all contributions from the gramine team. Special shout out to Dmitrii Kuvaiskii from Intel for his support.