Toolkit User’s Guide

Determining Your ZDG Toolkit Version

If you’re using an older version of the ZDG Toolkit, it might not include features that are described in this documentation. So before contacting Support, we recommend that you determine the version of your ZDG Toolkit.

Procedure

				
					Run the Dellfer zdg_version.py utility.
zdg_version.py
The utility outputs version information for your ZDG Toolkit.
				
			

What is Transparent

The Transparent build environment is a drop-in set of tools that provides an easy (if not seamless) integration of Dellfer ZeroDayGuard into your existing build process. With the Transparent build environment enabled, compiler and linker calls are integrated into ZDG-based build processes to produce ZDG-enabled binaries.

Transparent Modes

Transparent has two modes of operation: Cross-Compile (the default) and Retarget. 

Cross-Compile mode is a native replacement that is equivalent to the SDK environment provided by BitBake. Instead of superseding the host’s binaries, it supersedes the target-specific binaries, such as arm-agl-linux-gnueabl-gcc and arm-agl-linux-gnueabi-ld.

Retarget mode supersedes the target-specific binaries (just as Cross-Compile mode does), and also supersedes the host’s binaries, such as gcc, clang, and ld. In this mode, you’ll consume makefiles that are intended for the HOST machine that you’re using, but Transparent silently retargets those build items for your TARGET platform.

Choosing the Transparent Mode

Although not an exhaustive list, here are some criteria to help you decide which Transparent mode is right for your build environment:
  • If you don’t have a build system in place for your sources, use Cross-Compile mode because it is more flexible.
  • If your existing build environment uses a variant of a sourced-in SDK build environment, use Cross-Compile mode.
  • If a search with the grep command over your existing makefiles finds any of the following, use Cross-Compile mode:
    • TARGET_PREFIX
    • CROSS_COMPILE
    • OECORE_NATIVE_SYSROOT
    • CONFIGURE_FLAGS
  • If the binaries ordinarily run on the build machine, use Retarget mode. This is the only situation in which you should use Retarget mode.

Activating Transparent

To activate Transparent, source the environment into place. Every time you open a new shell, repeat the environment sourcing. For automation, you can perform the sourcing as an initial makefile step.

To enable Cross-Compile mode, assign the SDK_INSTALL_ROOT and run the environment set up command.
				
					# This is the default install root, which you might have changed during installation.

SDK_INSTALL_ROOT=/opt/poky-agl/5.0.2
source $(SDK_INSTALL_ROOT)/sysroots/x86_64-aglsdk-linux/usr/bin/zdg-environment-setup-armv7vehf-neon-vfpv4-agl-linux-gnueabi
				
			
To enable Retarget mode, assign the SDK_INSTALL_ROOT and run the environment set up command.
				
					# This is the default install root, which you might have changed during installation.
SDK_INSTALL_ROOT=/opt/poky-agl/5.0.2
export ZDG_ENABLE_RETARGET_MODE=1   # This MUST be done prior to the source command that follows.
source $(SDK_INSTALL_ROOT)/sysroots/x86_64-aglsdk-linux/usr/bin/zdg-environment-setup-armv7vehf-neon-vfpv4-agl-linux-gnueabi
				
			

Dellferizing Your Application

After you source your chosen Transparent mode, you can invoke your existing build process without any changes. To avoid interfering with build processes that rely on specific output of gcc/ld, Transparent does not output anything to STDOUT or STDERR by default.

(Optional) Enable Build Tracing

Build tracing enables you to confirm that Transparent is “present” in a Dellferized build. To enable build tracing, set up your environment for tracing before you begin the build.

				
					export ZDG_BUILD_TRACE=1
				
			
This provides a trace of actions that Transparent intercepts from your build process. By default, all output from ZDG goes to STDERR. You can customize the output location by setting the ZDG_INFO_OUTPUT_LOCATION environment variable.
				
					export ZDG_INFO_OUTPUT_LOCATION=STDERR  # (Default) Output to STEDERR
export ZDG_INFO_OUTPUT_LOCATION=STDOUT  # Output to STDOUT
export ZDG_INFO_OUTPUT_LOCATION=<path>  # Output to a file/path (absolute path recommended)
				
			

When you specify the <path> form for ZDG_INFO_OUTPUT_LOCATION:

  • If you specify a relative file path, the path is relative to the current working directory (CWD) when gcc/ld is called. Because the CWD is likely to change multiple times during the build process, we highly recommend using absolute paths instead.
  • If you specify an existing directory, ZDG creates a zdg_build.log file in that directory.
  • If you specify an existing file, ZDG appends new trace data to the existing file.

(Optional) Select Security Level

By default, Transparent is configured to provide a balance between security strength and performance overhead during code signing. You can swing the pendulum toward strengthened security or faster performance by overriding the default configuration.

To reconfigure Transparent’s balance between security and performance, set the ZDG_SECURE_LEVEL environment variable to any of the following values before you begin the build:

  • FAST—Prefer performance over security.
  • BALANCED—(Default setting) Keep a reasonable mix of performance and security features
  • STRICT—In all cases, favor the most security, even though it may come with a performance cost.
				
					# Example setting for the secure level
export ZDG_SECURE_LEVEL=BALANCED
				
			
				
					ZDG_POLICY_REQUIRE_SIGNED_SO=0
				
			

Build Your Application

After you install the Dellfer ZeroDayGuard Toolkit, build your application just as you did before. No changes are required in your Makefile environment.

Confirm That Your App is Instrumented for Dellferization

Before you transfer the application to your IoT target device, you should confirm that it was successfully instrumented and is ready for the next step in the Dellferization process.

Procedure

  • Run the Dellfer zdgfile utility.
  • zdgfile <filename>
    • If the application is correctly instrumented, the command displays a message that includes the string Valid ZDG Binary; for example, Valid ZDG Binary (ZDG Tool Version 0.0.2-f97b1c5).
    • Any other output indicates that the application is not instrumented for Dellferization.

Code-sign an Application or Library

You can use an existing private key, use a private key from a PKCS#11 token, or generate a new key to code sign an application or library, regardless of whether it’s instrumented for Dellferization. Use the key with the Dellfer code signing utility, codesign, and then verify that the signing was successful.

The Dellfer ZeroDayGuard codesign utility supports code signing an application or library using a Privacy Enhanced Mail (PEM) formatted private key or a PKCS#11 Cryptographic Token, such as hardware security module (HSM) or security key.

Generate a Signing Key

If you don’t already have a private key to use for code signing, you can generate one by using common RSA key generation utilities, such as OpenSSL or PuTTY ssh-keygen.

The ZeroDayGuard code signing utility, codesign, supports the following digest (hash) algorithms, listed from weakest to strongest:

  • SHA224
  • SHA256
  • SHA384
  • SHA512

Stronger algorithms are less susceptible to collisions—two different messages that produce the same message digest.

The ZeroDayGuard code signing utility supports key sizes from 512 bits to 16,384 bits. Choosing an algorithm and key size is a tradeoff between security (stronger algorithms and larger keys) and performance (of the signing and verification functions).

  • We recommend key sizes larger than 2,048 bits because smaller keys are insufficiently secure.
  • Keys larger than 16,384 bits are impractical because they unacceptably increase the time to perform RSA crypto operations.

Related Topics

Example: Use OpenSSL to Generate a Signing Key

This example shows how to use OpenSSL to generate a private key from a PEM file named myprivatekey.pem.

				
					openssl genrsa -out myprivatekey.pem 2048
				
			

Example: Use PuTTY ssh-keygen to Generate a Signing Key

This example shows how to use PuTTY to generate a private key from a PEM file named myprivatekey.pem.

				
					ssh-keygen -b 2048 -t rsa -f myprivatekey.pem -P ""
				
			

Code-sign an Application or Library

You can use the Dellfer ZeroDayGuard codesign utility to code-sign (with a hash and key) any application or shared library, and to generate the verification public key.

When an application or library starts, the Dellfer ZeroDayGuard validates the authenticity of the application or library—whether it is code signed—by validating the digitisal signatures. If the authenticity check of the application or shared library fails, Dellfer prevents the application from running.

ZeroDayGuard uses a single verification public key to validate the authenticity of the application or library. The signature verification key must be associated with a unique signing key. Therefore, the same signing key must be used to sign all applications or shared libraries that are subject to ZeroDayGuard enforcement.

Procedure

  • In your development environment, run the Dellfer ZeroDayGuard codesign utility.

Usage for the codesign utility is:

				
					Usage: codesign [options] <file>
Options:
  -h, --help                       print this message
  -v, --verbose                    verbose operational output
  -o, --output <output_file>       path to the signed executable ELF binary
  -d, --digest-alg <digest-alg>    digest algorithm: SHA224, SHA256, SHA384 or SHA512
                                   multiple algorithms can be specified
  -s, --sign_key <PEM file >       RSA private key, from 512 to 16,384 bits, in PEM format.
  -x, --password <password>        password of private key
  -X, --password-file  <file>      read password or PIN from a text file
  -p, --policy <policy-file>       policy content to be added to signature. When <policy-file> is -,
                                   standard input is read
  -i, --identifier <identifier>    string identifier of the ELF binary
  --verify                         verifies code signature and displays the signature section
                                   in the ELF binary
  --gen-verify-key                 extracts public key material from private key into a source file
                                   
  -m, --module <module-path>       path of the PKCS#11 module library
  -k, --key-id <identifier>        identifier of signing key of the PKCS#11 token
  <file>                           file name of the executable ELF binary
				
			

Example: Code-sign an Application Binary with a PEM-File Key

This example shows how to code sign an application binary, “myapp”, using a private key in a PEM file, mykey.id_rsa.pem. The signed data includes a SHA256 hash of selected areas of “myapp”.

				
					codesign --digest-alg SHA256 -s mykey.id_rsa.pem -i gauntlet myapp
				
			

Example: Code-sign an Application Binary with a PKCS#11 Cryptographic Token

This example shows how to code sign an application binary, “myapp”, using Yubikey, a security key from Yubico. The PKCS#11 module YKCS11 is installed at /usr/local/lib. Key identifier 01 which corresponds to PIV Authentication Key on the security key is used. The signed data includes a SHA256 hash of selected areas of “myapp”. The verbose operational output option of the code sign tool is also selected.

				
					codesign -v --module /usr/local/lib/libykcs11.so -k 01 -i test --digest-alg SHA256 myapp
Slot{manufacturer: Yubico (www.yubico.com), description: Yubico Yubikey 4 OTP+U2F+CCID 00 00}
  Token{label: YubiKey PIV #13903398, manufacturer: Yubico (www.yubico.com), model: YubiKey YK5, serial: 13903398, login: required}
Enter PKCS#11 token PIN for YubiKey PIV #13903398: <redacted>
PKCS#11 login successful
  Public keys:
    Key{id:01, label:Public key for PIV Authentication}
    Key{id:02, label:Public key for Digital Signature}
    Key{id:19, label:Public key for PIV Attestation}
using public key: Public key for PIV Authentication
  Private keys:
    Key{id:01, label:Private key for PIV Authentication}
    Key{id:02, label:Private key for Digital Signature}
    Key{id:19, label:Private key for PIV Attestation}
using private key: Private key for PIV Authentication
processing ELF file 'myapp'
processing segment type: PT_LOAD index: 2 size 249094
processing segment type: PT_LOAD index: 3 size 2b568
Code signature content begin >>>>>
Identifier @240 size:4
    identifier[4]: 'test'
Directory Digest Entry Table @104 size:56
    Digest Entry Table entry count:2
      [segment ][2] digest-alg: SHA256 digest[32]: '1fe65aa1fd1151bb34d172ca4febfa7786abf668ddb463e650317edc9598e7c3'
      [segment ][3] digest-alg: SHA256 digest[32]: '13dc100e54fe78eae3b450d9973ef71e28151ce20aea0c6957dbda34de164bca'
MetaData Entry Table @96 size:8
    MetaData Entry Table entry count:0
Directory Digest @320 size:32
    digest-alg: SHA256 digest[32]: 'f110cf9ac7813d2c0a298b8b11f57eb2781c5a6de67e0d4521e26534a7ee78b2'
Signature @352 size:256
    signature[256]: '699f60cc28340f5a2a2eb0630dd2675d77698c3dfd6e2224ef86507b9b171c8c011b0ea35a4e...'
Signing Material  @608 size:282
    content[282]: '080001010b0103000e0100003082010a0282010100b52cbbb8fa3be83c56db1301fdb77fe4c4...'
<<<<< end of code signature content
Added code signature section {idx: 40}
Writing to file 'myapp' completed
				
			

Example: Code-sign an Application Binary to modify the ZDG Policy

This example shows how to code sign an application binary, “myapp”, using a private key in a PEM file, mykey.id_rsa.pem and a policy file, policy.txt. The policy file contains the following rules:

  • ZDG_POLICY_PERMIT_VM_EXEC=1 to disable the default ZDG LSM policy 
  • ZDG_POLICY_REQUIRE_SIGNED_SO=1 to enable shared library signature policy 
				
					codesign --digest-alg SHA256 -s mykey.id_rsa.pem -i gauntlet -p policy.txt myapp
				
			

Example: Validate a Code-signed Application’s Signature and Hash

This example validates the signature and SHA256 digest of the code signed “myapp.”

				
					codesign --verify myapp

processing section '.code.signature' {idx:27 size:748}
Code signature content begin >>>>>
Identifier @108 size:8
           identifier[8]: 'gauntlet'
Directory Digest Entry Table @56 size:16
          Digest Entry Table entry count:1
            [segment ][1] digest-alg: SHA256 digest[32]: '913f1bc6c7a1dd5fbea77a65fde17dfc760a9e2d8bf0499a0c9520784d57b2ac'
MetaData Entry Table @52 size:4
         MetaData Entry Table entry count:0
Directory Digest @152 size:32
          digest-alg: SHA256 digest[32]: '33cd5ef6d73cd02434a91d04ccf8a0c7eeed185cb4b2d83200c46826cf515978'
Signature @184 size:256
          signature[256]: '7bef91d00c51ec51b6129e7b9657840f92bdb61e85f175f2ecffc39e30d44a448fb917c1d7c6...'
Signing Material  @440 size:270
        content[270]: '3082010a0282010100c0b8b1c16cef2ea1329a637afe9c80363d8fe92f859720691c1fb75993...'
<<<<< end of code signature content
Signature Section verified successfully.
				
			

Verify Successful Code-signing

Procedure

  • In your development environment, run the Dellfer ZeroDayGuard codesign utility with the –verify option.
  • codesign verify <filename>
    • If the application or library is correctly signed, the command displays a message that includes the string Signature Section verified successfully.
    • If the success message is not displayed, the application or library is not correctly signed

Enter Your Information to Access This White Paper

  • This field is for validation purposes and should be left unchanged.

Enter Your Information to Access This White Paper

  • This field is for validation purposes and should be left unchanged.

Enter Your Information to Access This White Paper

  • This field is for validation purposes and should be left unchanged.

Enter Your Information to Access This Datasheet

  • This field is for validation purposes and should be left unchanged.

Enter Your Information to Access This White Paper

  • This field is for validation purposes and should be left unchanged.

Enter Your Information to Access This Datasheet

  • This field is for validation purposes and should be left unchanged.