Intel® DAL Tutorial: Create a Trusted Application and Host Application

ID 673056
Updated 8/28/2018
Version Latest
Public

author-image

By

This tutorial takes you through the steps of creating an Intel® Dynamic Application Loader (Intel® DAL) trusted application (applet) and a host application which calls the trusted application. You will use the Intel DAL Project wizard.

The wizard creates simple templates for the applet and the host application. Once you have created these templates, you can adapt their code to provide the functionality that you need.

By working your way through this tutorial, you will learn how to:

  1. Create and package an Intel DAL trusted application.
  2. Create and package a C++ or .NET* C# host-based application that sends a message to the trusted application and receives a message from it in return.
  3. Execute the trusted application and the firmware emulators to see the messages generated by running the samples.

Before you begin, make sure that your development environment is set up. If you have not done so already, download the SDK for Intel DAL and follow the installation wizard. Once you have finished the setup, you are ready to begin.

Tip: Check the Get Started page to make sure that you have correctly installed all the components and set the environment variables.

If Microsoft Visual Studio* was just installed, it must be opened at least once before you create your host application.

This tutorial uses the Intel DAL Project wizard for Eclipse*, Microsoft Visual Studio* and the Intel DAL Emulauncher.

Creating a Trusted Application and Its Host Application

  1. Open Eclipse and select a workspace. The workspace is the root folder where projects will be saved.
  2. Once Eclipse loads, it’s time to create the project. Select File ► New ► Project… from the menu and choose DAL Projects ► DAL Applet Project. If you do not have this menu item, the Intel DAL Eclipse plugin has not been installed.create new DAL project
  3. Enter the following parameters for the new project:
  • Project name: Name of the trusted application as well of the whole project. The trusted application name can be changed later via the manifest. For this tutorial, use the project name MyFirstProject.
  • Package name: Namespace for the trusted application. This must follow the regular Java* programming language rules. The namespace cannot contain names which are reserved for Intel DAL APIs. For this tutorial, use the package name pkgMyFirstProject.
  • Main class name: Main class of the trusted application. For this tutorial, use MyFirstProject.
  • API level: The lowest API level on which the trusted application will run. For example, if you specify API level 7, the applets will run on API levels 7 and higher.

Create a new DAL trusted application

  1. Click Next. In the next window, check the box to indicate that you want to create a new host application while you are creating your Intel DAL project. If the following parameters on the host application are not filled in, enter them:
    • Project name: Name of the host application.
    • Programming language: There is the option to choose between .NET and C++. For this tutorial, select C++.Screenshot of DAL new project UI
  2. Click Next.

The creation of this project using the wizard will already include the jhi.h in accordance with the selected API level. It is a good idea to open the jhi.h file and see exactly which functions the Intel DAL Host Interface Service library supports.

  1. In the Run Configuration window, you specify what should happen when you press the Run or Debug button in Eclipse. You have the following choices:
    • The first choice in the window is Open Visual Studio with created host application, and run it. If you choose this option, pressing Run or Debug will launch the host application that you create with the wizard.
    • The second choice is Run Generic Host Application Tool. If you choose this option, pressing Run or Debug will launch the SDK’s Generic Host Application. You will then be able to run the Generic Host Application to communicate with the applet.
    • The third choice is Run the following executable. This is for the case where you created a host application of your own that communicates with the applet.

For this tutorial, choose the first option: Open Visual Studio with created host application, and run it.

Intel DAL project run configuration - Microsoft Visual Studio

  1. Click Next to display the Summary window, which shows your project settings;

project summary

  1. Click Finish to generate your applet and host application.

Compiling and Packaging

Note: This step is necessary only if you have made changes to the applet. If you generated the applet via the wizard and subsequently made no changes to it, continue with 'About Your Host Application'.

When you created the new project, Eclipse compiled the applet and built, or converted it, to the Intel DAL package format, dalp. If you make any changes to an existing applet, you need to build and package the applet again. To do this:

  1. In Eclipse, select the top level of your project tree.
  2. From the Intel DAL menu, select Build and Package. A message box opens.

    packaging applet window

  3. Do NOT select the For Debugger option. The For Debugger option determines whether or not the compilation will be done in a way that enables source level debugging.
  4. Click OK. The packager begins to run. The Eclipse console displays in-process messages for the packager operation.Intel DAL Eclipse console messages - packager

The generated executable in loadable form is ready for use. For each API level, a separate .pack file is generated. For API levels 1.1 and above, a .dalp file is created as well. The .dalp file wraps all the .pack files in one XML file. The pack or dalp file is in the bin directory in the workspace. This is the file you will upload to the firmware emulator. Your file is located in:

workspace\MyFirstProject\bin\MyFirstProject.dalp

About Your Host Application

The code of this tutorial exercises the main functions of the trusted application. When you clicked Finish in the Intel DAL wizard to create your project, a template C++ host application was created for you. This is a simple Windows* console application that:

  • Loads the trusted application you packaged into the virtual machine.
  • Communicates with the trusted application.

Communication between the host and trusted applications running in the virtual machine is done via a mechanism called Intel DAL Host Interface Service. This mechanism supports installing and uninstalling a trusted application, and sending and receiving of messages between a hosted application and a trusted application. The Intel DAL Host Interface Service has an API and a library implementing that API.

The code of this tutorial uses the main functions of the trusted application. The program sends command ID 1 which causes the trusted application to display the debug string "Hello World!"

This application performs this flow:

  1. Initialize a connection with the Intel DAL Host Interface Service.
  2. Install the trusted application.
  3. Open session to the trusted application.
  4. Use the trusted application's SendAndRecv function to send data.
  5. Close session.
  6. Uninstall the trusted application.
  7. End the connection with Intel DAL Host Interface Service.

The following sections describe the code of both host applications: C++ and C#.

C++ Host Application Code

Let's have a look at the C++ code:

Main.cpp

How does the application perform this flow?

When you created your project, the following project properties were defined for you by the wizard:

  • Under Configuration Properties ► Linker ► Input tab - in the Additional Dependencies field, the wizard added  $(DALsdk)\Platforms\JHI\jhi.lib  at the end of the project dependencies list.
  • In the General Property page - under Configuration Properties ► C/C++, the following string was added Additional Include Directories: $(DALsdk)\Platforms\JHI. The header files in this directory are JHI.h and typedefs.h.

These cause your application to recognize the Intel DAL Host Interface Service functions defined in the JHI.h file, and enable running the project.

It's recommended to open the jhi.h file to see exactly which functions the Intel DAL Host Interface Service library supports.

The template has a security implementation which ensures that it is loading the correct JHI.dll at run time and not some malicious dll. To accomplish the maximum security level, the template uses delay load of the JHI.dll. Under Configuration Properties->Linker, the Delay Loaded Dll field is set to contain JHI.dll.

The first time one of the JHI.dll functions is called, when JHI_RET ret = JHI_Initialize(&handle, NULL, 0); a line in Main.cpp is called and the DLL is loaded. The function delayHook will be called and will perform the load from a trusted path with signature verification.

DelayLoader.cpp

The DelayHook() function is called when a .dll is delay loaded with the dliNotePreLoadLibrary argument. With any other case we simply ignore the call and return control to the Microsoft delay-load helper function.

The function first checks that the .dll is JHI.dll:

LPCSTR delayedDllName=pdli->szDll;
if(strcmp(delayedDllName,"JHI.dll")!=0)
      return 0;

Next the JHI.dll path is extracted from the registry. It is a secure practice to load a .dll from an explicit path:

01    //read the registry path to find where the JHI.dll of the current platform\emulation is located
02    if(ReadRegistryString(REGISTRY_BASE,
03                    REGISTRY_DAL_PATH,
04                    REGISTRY_PATH_FILES_VALUE,
05                    wtRegValue,
06                    ®ValSize) == 0)
07    {
08        regValSize = DEFAULT_LEN;
09        wcsncat_s(wtRegValue, DEFAULT_LEN, dllName, _TRUNCATE);
10        //wtRegValue now contains the path to JHI.dll
11    }

Then the signature of the dll is verified, both that it is a signed dll and that the signer is Intel Corporation:

if(!VerifyFileSignature(path) || !VerifyCertificateName(path))//JHI dll is not signed by Intel
                               {
                                      delete[] wtRegValue;
                                      throw std::exception("JHI.dll signature could not be verified.");
                               }

SignatureVerifier.cpp

The two functions VerifyFileSignature and VerifyCertificateName are in the file SignatureVerifier.cpp inside your solution.

If the signature is OK, the dll is loaded dynamically by calling the LoadLibrary function:

1    //Load the dll dynamically at run time
2    cout << "Verification was successful. Loading JHI.dll." << endl;
3    HMODULE lib = LoadLibraryW(wtRegValue);

About your .NET* host application

Let's have a look at the .NET code for a host application:

Program.cs

How does the application perform this flow?

When you created your project, the following project properties were defined for you by the wizard:

  • Under References, the wizard added JhiSharp.dll from $(DALsdk)\Platforms\JHI\JhiSharp.dll.

These cause your application to recognize the Intel DAL Host Interface Service functions defined in the JhiSharp.dll and enable running the project.

In the code, an instance of Jhi and JhiSession were declared.

The first time one of the JHI.dll functions is called is when jhi.Install(appletID, appletPath); a line in Program.cs is called.

This is the first step in the flow.

The basic flow continues in the code.

For more Intel DAL Host Interface Service functionality, see Intel DAL Host Interface Service.

Running Your Host Application

Your host application and trusted application are ready to run on your emulated environment via Intel DAL Emulauncher. The Amulet configuration, added by the Microsoft Visual Studio plugin, launches the emulator and specifies the API level.

  • In Microsoft Visual Studio, under the solution’s configuration, select Amulet  and start debugging.

  • Intel DAL Emulauncher launches with the matching emulation and the host application runs.

You can see the output of the trusted application in the Microsoft Visual Studio output window. Select Amulet in the drop-down list. If the output pane is closed, open it by selecting View ->Output.

That's it! You now have both a trusted application to use with Intel DAL and a host application to load and communicate with it. You can proceed with adapting the code in these applications to add your required functionality.