Open Enclave extension for Visual Studio Code

A Visual Studio Code extension supporting Open Enclave, including development, debugging, emulators, and deployment!

For more information on the technology, see here.

Getting started

Ensure that the requirements are met.

Install the Microsoft Open Enclave extension.

Create a new Open Enclave solution.

You can use the Microsoft Open Enclave: New Open Enclave Solution command (commands can be found using F1 or CTRL-Shift-P) to create a new Open Enclave solution.

You will be prompted to:

1. Select a folder for your solution.
2. On Linux, you will have the option to create a Standalone project or an Azure IoT Edge Module project. Otherwise, you will only have the option to create an Azure IoT Edge Module project.
3. If you choose an Azure IoT Edge Module project, you will be prompted to provide your container repository.
4. You will be prompted to provide a name for your host/enclave.

A new solution will be created in the folder you've selected. That solution will contain both the host and enclave as well as the required EDL file. If you've chosen to build an Azure IoT Edge Module, the host will include some code that implements the required Azure IoT Hub communication.

Note: On Windows, you can use the Windows Subsystem for Linux and the Visual Studio Code Remote-Development extension to utilize Standalone projects on a Windows desktop. In this case, you will need to install the requirements in the subsystem.

Standalone projects

Build your Open Enclave solution.

The underlying system used to build is CMake.

There will be configure and build tasks for each target: ARMv7-A, AArch64/ARMv8-A, and TrustBoxEdge(LS1012a). The configure task will invoke CMake to create the required build files. This is only required to be run once.
The build task will do the actual compiling and linking.

1. F1 or CTRL-Shift-P
2. Select Tasks: Run Task
3. Select Build for QEMU ARMv7-A | AArch64/ARMv8-A | TrustBoxEdge(LS1012a)

Debug your Open Enclave solution.

Debugging your standalone project's enclave is easy. Please ensure that all of the QEMU dependencies are installed in your development environment.

1. Set breakpoints in the files you wish to debug. Breakpoints in the enclave may only be added before the emulator (QEMU) starts or when the debugger is already broken inside the enclave.

2. Choose the architecture you are interested in debugging by navigating to the Visual Studio Debug view (CTRL-Shift-D) and selecting either (gdb) Launch QEMU (ARMv7-A), (gdb) Launch QEMU (AArch64/ARMv8-A), or (gdb) Launch QEMU (TrustBoxEdge(LS1012a)) from the debug configuration dropdown.

3. You can simply hit F5. This will run cmake configuration, run the build, start QEMU, and load the host and enclave symbols into an instance of the debugger.

4. Open the Terminal view

5. Log into QEMU using root (no password is required)

6. Start the host process by entering /mnt/host/bin/<solution-name>

    Note: The debugger has been configured to break at TA_InvokeCommandEntryPoint.  This will happen once when the enclave starts and once for each ECALL.
   

Azure IoT Edge projects

Build your Open Enclave solution.

Ubuntu containers are used to configure and build. The build task will invoke docker and leverage project dockerfiles. The build the Azure IoT Edge Module:

1. Right click on modules/<solution-name>/module.json
2. Select Build IoT Edge Module Image
3. Select trustboxedge-ls1012a, arm32v7-qemu or aarch64-qemu from the Platform picker

Deploy your Open Enclave solution.

Deploying your Azure IoT Edge Module project is fairly simple:

1. Right click on modules/<solution-name>/module.json
2. Select Build and Push IoT Edge Module Image
3. Select trustboxedge-ls1012a, arm32v7-qemu or aarch64-qemu from the Platform picker

Azure IoT Edge deployment template files have been provided. To create a new deployment configuration based on the current settings in module.json:

1. Select the desired platform:
   1. F1 or CTRL-Shift-P
   2. Select Azure IoT Edge: Set Default Target Platform for Edge Solution
   3. Choose from trustboxedge-ls1012a, arm32v7-qemu or aarch64-qemu
2. Right click on deployment.template.json (or deployment.debug.template.json)
3. Select Generate IoT Edge Deployment Manifest. This will generate or replace the apppropriate deployment json file in the config folder.

Once your deployment json has been created in the config folder, you can deploy to an Azure Edge device by:

1. Navigating to the config folder
2. Right clicking on deployment.*.json
3. Selecting Create Deployment for Single Device or Create Deployment at Scale.

To set up an actual device to receive a deployment, you can follow these instructions.

Check your system for Open Enclave requirements.

You can use the Microsoft Open Enclave: Check System Requirements command (commands can be found using F1 or CTRL-Shift-P) to validate your system.

The command will query whether the required tools and the required versions are present on your system. Any unmet requirements will be presented in a Visual Studio Code warning window.

Note: as long as unmet requirements are found, this requirements check will run whenever the extension is activated automatically.

Requirements

• Install Visual Studio Code

• Install git

  • On Windows, please make sure that long paths are enabled: git config --global core.longpaths true

• On Linux

  • Make sure that the Native Debug extension is installed.

  • Install CMake 3.12 or higher

  • Install the required build components:

    sudo apt update && sudo apt install -y build-essential cmake gcc-arm-linux-gnueabihf gcc-aarch64-linux-gnu g++-arm-linux-gnueabihf g++-aarch64-linux-gnu gdb-multiarch python
    

  • Ensure that all QEMU dependencies are installed. On Ubuntu 18.04 run:

    sudo apt update && sudo apt install -y libpixman-1-0 zlib1g libc6 libfdt1 libglib2.0-0 libpcre3 libstdc++6
    

• Ensure that the requirements are met for the Azure IoT Edge extension:

  • Docker is installed and running: https://docs.docker.com/install/.

    • On Linux, for Edge projects, you will need to enable cross-building.

      • Enable docker cross-building on Ubuntu 19.04 and 18.10 by:

        sudo apt-get install -y qemu qemu-system-misc qemu-user-static qemu-user binfmt-support
        

      • Enable docker cross-building on Ubuntu 18.04 and 16.04 by:

        sudo apt-get install -y qemu qemu qemu-system-misc qemu-user-static qemu-user binfmt-support
        sudo mkdir -p /lib/binfmt.d
        sudo sh -c 'echo :qemu-arm:M::\\x7fELF\\x01\\x01\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x02\\x00\\x28\\x00:\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\xfe\\xff\\xff\\xff:/usr/bin/qemu-arm-static:F > /lib/binfmt.d/qemu-arm-static.conf'
        sudo sh -c 'echo :qemu-aarch64:M::\\x7fELF\\x02\\x01\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x02\\x00\\xb7\\x00:\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\xfe\\xff\\xff\\xff:/usr/bin/qemu-aarch64-static:F > /lib/binfmt.d/qemu-aarch64-static.conf'
        sudo systemctl restart systemd-binfmt.service
        

      • To validate that your system is configured for cross-building, you can try testing the docker containers that will be needed in the build:

        docker run arm32v7/ubuntu:xenial
        docker run aarch64/ubuntu:xenial
        docker run amd64/ubuntu:xenial
        

    • On Linux, if you are seeing permission issues related to connecting to the Docker daemon, add your Linux user to the docker group. This will allow your user to connect and issue commands to the Docker daemon:

      sudo usermod -a -G docker $USER
      

    • On Windows, be sure Docker is configured to use Linux containers. See docker help regarding Switch between Windows and Linux containers here.

  • The iotedgehubdev tool is installed

    pip install --upgrade iotedgehubdev
    

  • Create a container repository, like Azure Container Registry

    • To push Edge containers to the container registry, find the username and password for your container registry and use them to log into docker (the --pasword-stdin option will prevent your password from appearing in the command line history): docker login --password-stdin -u <username> <container-url>
    • Once you've logged into docker, you can log out (ane remove your credentials from the system) by: docker logout <container-url>

  • Make sure that the Azure Account extension is installed and utilized:

    1. F1 or CTRL-Shift-P
    2. Azure: Sign In

  • Make sure that the Azure IoT Hub Toolkit extension is installed and utilized:

    1. F1 or CTRL-Shift-P
    2. Azure IoT Hub: Select IoT Hub

Build and run extension from source code

For development of this extension, or running from source code directly

• Install node
• Install npm

To run the extension from this repository, following these instructions:

1. Clone this repository git clone --recursive https://github.com/microsoft/openenclave --branch feature.new_platforms.
2. Navigate to new_platforms\vscode-extension in the cloned folder.
3. Run npm to install the dependencies: npm install (see the requirements section for npm installation link).
4. Start VSCode: code ..
5. Start the extension using F5.

Data/Telemetry

This project collects usage data and sends it to Microsoft to help improve our products and services. Read our privacy statement to learn more. If you don't wish to send usage data to Microsoft, you can set the telemetry.enableTelemetry setting to false. Learn more in the Visual Studio Code FAQ.

Known Issues

• Building SGX enclaves is not currently supported.
• We've had reports that downloading the SDK from git can be slow from within the extension. To work around any issue, you can run these commands

  • Linux:

    rm -rf /home/$USER/.config/Code/User/globalStorage/ms-iot.msiot-vscode-openenclave/1.0.3/3rdparty/openenclave
    git clone --recursive --branch feature.new_platforms https://github.com/Microsoft/openenclave /home/$USER/.config/Code/User/globalStorage/ms-iot.msiot-vscode-openenclave/1.0.3/3rdparty/openenclave
    

  • Windows (from CMD prompt):

    rmdir /S /Q  %APPDATA%\Code\User\globalStorage\ms-iot.msiot-vscode-openenclave\1.0.3\3rdparty\openenclave
    git clone --recursive --branch feature.new_platforms https://github.com/Microsoft/openenclave %APPDATA%\Code\User\globalStorage\ms-iot.msiot-vscode-openenclave\1.0.3\3rdparty\openenclave
    

• The Visual Studio Code global data directory is used to download the Open Enclave SDK. You can specify where this directory exists for Visual Studio Code by using the --user-data-dir command line switch.

Release Notes

1.0.10

Public Preview

1.0.1

Prototyping and developing :)