Asylo C++ build rules

asylo_tags

asylo_tags(backend_tag)

Returns appropriate tags for Asylo target.

Parameters

backend_tag optional. default is None

String that indicates the backend technology used. Can be one of * "asylo-sgx" * "asylo-sim" * None

cc_enclave_binary

cc_enclave_binary(name, application_enclave_config, enclave_build_config, application_library_linkstatic, kwargs)

Creates a cc_binary that runs an application inside an enclave.

Mostly compatible with the cc_binary interface. The following options are not supported:

  • linkshared
  • malloc
  • stamp

Usage of unsupported aspects of the cc_binary interface will result in build failures.

fork() inside Asylo is enabled by default in this rule.

Parameters

name required.

Name for the build target.

application_enclave_config optional. default is ""

A target that defines a function called ApplicationConfig() returning and EnclaveConfig. The returned config is passed to the application enclave. Optional.

enclave_build_config optional. default is ""

An sgx_enclave_configuration target to be passed to the enclave. Optional.

application_library_linkstatic optional. default is True

When building the application as a library, whether to allow that library to be statically linked. See the `linkstatic` option on `cc_library`. Optional.

kwargs optional.

cc_binary arguments.

cc_enclave_test

cc_enclave_test(name, srcs, enclave_config, tags, deps, test_in_initialize, kwargs)

Build target that runs a cc_test srcs inside of an enclave.

This macro creates two targets, one sgx_enclave target with the test source. And another test runner application to launch the test enclave.

Parameters

name required.

Target name for will be <name>_enclave.

srcs required.

Same as cc_test srcs.

enclave_config optional. default is ""

An sgx_enclave_configuration target to be passed to the enclave. Optional.

tags optional. default is []

Same as cc_test tags.

deps optional. default is []

Same as cc_test deps.

test_in_initialize optional. default is False

If True, tests run in Initialize, rather than Run. This allows us to ensure the initialization and post-initialization execution environments provide the same runtime behavior and semantics.

kwargs optional.

cc_test arguments.

cc_test

cc_test(name, enclave_test_name, enclave_test_config, srcs, deps, kwargs)

Build macro that creates a cc_test target and a cc_enclave_test target.

This macro generates a cc_test target, which will run a gtest test suite normally, and optionally a cc_enclave_test, which will run the test suite inside of an enclave.

Parameters

name required.

Same as native cc_test name.

enclave_test_name optional. default is ""

Name for the generated cc_enclave_test. Optional.

enclave_test_config optional. default is ""

An sgx_enclave_configuration target to be passed to the enclave. Optional.

srcs optional. default is []

Same as native cc_test srcs.

deps optional. default is []

Same as native cc_test deps.

kwargs optional.

cc_test arguments.

cc_test_and_cc_enclave_test

cc_test_and_cc_enclave_test(name, enclave_test_name, enclave_test_config, srcs, deps, kwargs)

An alias for cc_test with a default enclave_test_name.

This macro is identical to cc_test, except it passes in an enclave test name automatically. It is provided for convenience of overriding the default definition of cc_test without having to specify enclave test names. If this behavior is not desired, use cc_test instead, which will not create and enclave test unless given an enclave test name.

This is most useful if imported as load( _workspace_name + “/bazel:asylo.bzl”, cc_test = “cc_test_and_cc_enclave_test”, ) so any cc_test defined in the BUILD file will generate both native and enclave tests.

Parameters

name required.

See documentation for name in native cc_test rule.

enclave_test_name optional. default is ""

See documentation for enclave_test_name in cc_test above. If not provided and name ends with "_test", then defaults to name with "_test" replaced with "_enclave_test". If not provided and name does not end with "_test", then defaults to name appended with "_enclave".

enclave_test_config optional. default is ""

An sgx_enclave_configuration target to be passed to the enclave. Optional.

srcs optional. default is []

See documentation for srcs in native cc_test rule.

deps optional. default is []

See documentation for deps in native cc_test rule.

kwargs optional.

See documentation for **kwargs in native cc_test rule.

copy_from_host

copy_from_host(target, output, name)

Genrule that builds target with host CROSSTOOL.

Parameters

target required.
output required.
name optional. default is ""

embed_enclaves

embed_enclaves(name, elf_file, enclaves, kwargs)

Build rule for embedding one or more enclaves into an ELF file.

Each enclave is embedded in a new ELF section that does not get loaded into memory automatically when the elf file is run.

If the original binary already has a section with the same name as one of the given section names, objcopy (and the bazel invocation) will fail with an error message stating that the file is in the wrong format.

Parameters

name required.

The name of a new ELF file containing the contents of the original ELF file and the embedded enclaves.

elf_file required.

The ELF file to embed the enclaves in. This target is built with the host toolchain.

enclaves required.

A dictionary from new ELF section names to the enclave files that should be embedded in those sections. The section names may not start with ".", since section names starting with "." are reserved for the system.

kwargs optional.

genrule arguments.

enclave_loader

enclave_loader(name, enclaves, embedded_enclaves, loader_args, kwargs)

Wraps a cc_binary with a dependency on enclave availability at runtime.

Creates a loader for the given enclaves and containing the given embedded enclaves. Passes flags according to loader_args, which can contain references to targets from enclaves.

This macro creates three build targets: 1) name: shell script that runs name_host_loader. 2) name_loader: cc_binary used as loader in name. This is a normal native cc_binary. It cannot be directly run because there is an undeclared dependency on the enclaves. 3) name_host_loader: genrule that builds name_loader with the host crosstool.

Parameters

name required.

Name for build target.

enclaves optional. default is {}

Dictionary from enclave names to target dependencies. The dictionary must be injective. This dictionary is used to format each string in `loader_args` after each enclave target is interpreted as the path to its output binary.

embedded_enclaves optional. default is {}

Dictionary from ELF section names (that do not start with '.') to target dependencies. Each target in the dictionary is embedded in the loader binary under the corresponding ELF section.

loader_args optional. default is []

List of arguments to be passed to `loader`. Arguments may contain {enclave_name}-style references to keys from the `enclaves` dict, each of which will be replaced with the path to the named enclave.

kwargs optional.

cc_binary arguments.

enclave_test

enclave_test(name, enclaves, embedded_enclaves, test_args, tags, kwargs)

Build target for testing one or more enclaves.

Creates a cc_test for a given enclave. Passes flags according to test_args, which can contain references to targets from enclaves.

This macro creates three build targets: 1) name: sh_test that runs the enclave_test. 2) name_driver: cc_test used as test loader in name. This is a normal native cc_test. It cannot be directly run because there is an undeclared dependency on enclave. 3) name_host_driver: genrule that builds name_driver with host crosstool.

Parameters

name required.

Name for build target.

enclaves optional. default is {}

Dictionary from enclave names to target dependencies. The dictionary must be injective. This dictionary is used to format each string in `test_args` after each enclave target is interpreted as the path to its output binary.

embedded_enclaves optional. default is {}

Dictionary from ELF section names (that do not start with '.') to target dependencies. Each target in the dictionary is embedded in the test binary under the corresponding ELF section.

test_args optional. default is []

List of arguments to be passed to the test binary. Arguments may contain {enclave_name}-style references to keys from the `enclaves` dict, each of which will be replaced with the path to the named enclave. This replacement only occurs for non-embedded enclaves.

tags optional. default is []

Label attached to this test to allow for querying.

kwargs optional.

cc_test arguments.

sgx_enclave_test

sgx_enclave_test(name, srcs, kwargs)

Build target for testing one or more instances of ‘sgx_enclave’.

This macro invokes enclave_test with the “asylo-sgx” tag added.

Parameters

name required.

The target name.

srcs required.

Same as cc_test srcs.

kwargs optional.

enclave_test arguments.

sim_enclave

sim_enclave(name, kwargs)

Build rule for creating simulated enclave object files signed for testing.

The enclave simulation backend currently makes use of the SGX simulator. However, this is subject to change and users of this rule should not make assumptions about it being related to SGX.

Parameters

name required.

The name of the signed enclave object file.

kwargs optional.

cc_binary arguments.

sim_enclave_loader

sim_enclave_loader(name, enclaves, embedded_enclaves, loader_args, kwargs)

Thin wrapper around enclave loader, adds necessary linkopts and testonly=1

Parameters

name required.

Name for build target.

enclaves optional. default is {}

Dictionary from enclave names to target dependencies. The dictionary must be injective. This dictionary is used to format each string in `loader_args` after each enclave target is interpreted as the path to its output binary.

embedded_enclaves optional. default is {}

Dictionary from ELF section names (that do not start with '.') to target dependencies. Each target in the dictionary is embedded in the loader binary under the corresponding ELF section.

loader_args optional. default is []

List of arguments to be passed to `loader`. Arguments may contain {enclave_name}-style references to keys from the `enclaves` dict, each of which will be replaced with the path to the named enclave.

kwargs optional.

cc_binary arguments.

sim_enclave_test

sim_enclave_test(name, kwargs)

Thin wrapper around enclave test, adds ‘asylo-sim’ tag and necessary linkopts

Parameters

name required.

enclave_test name

kwargs optional.

same as enclave_test kwargs