//asylo/bazel:asylo.bzl

backend_debug_sign_enclave

backend_debug_sign_enclave(name, backend, unsigned, config, backend_label_struct, kwargs)

Defines the ‘signed’ version of an unsigned enclave target.

The signer is backend-specific.

Parameters

name required.

The rule name.

backend required.

An Asylo backend label.

unsigned required.

The label of the unsigned enclave target.

config optional. default is None

An enclave signer configuration label. Optional.

backend_label_struct optional. default is None

Optional backend label struct (details in enclave_info.bzl)

kwargs optional.

Generic rule arguments like tags and testonly.

cc_backend_unsigned_enclave

cc_backend_unsigned_enclave(name, backend, kwargs)

Defines a C++ unsigned enclave target in the provided backend.

Parameters

name required.

The rule name.

backend required.

An Asylo backend label.

kwargs optional.

Arguments to cc_binary.

cc_backend_unsigned_enclave_experimental

cc_backend_unsigned_enclave_experimental(name, backend, kwargs)

Defines a C++ unsigned enclave target in the provided backend.

Parameters

name required.

The rule name.

backend required.

An Asylo backend label.

kwargs optional.

Arguments to cc_binary.

cc_enclave_binary

cc_enclave_binary(name, application_enclave_config, enclave_build_config, application_library_linkstatic, backends, unsigned_name_by_backend, signed_name_by_backend, testonly, 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 ""

A backend-specific configuration target to be passed to the enclave signer. 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.

backends optional. default is {"@linux_sgx//:asylo_sgx_hw": struct(config_settings = ["@linux_sgx//:sgx_hw"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_hw", order = 2, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-hw", "manual"]), "@linux_sgx//:asylo_sgx_sim": struct(config_settings = ["@linux_sgx//:sgx_sim"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_sim", order = 1, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-sim", "manual"])}

The asylo backend labels the binary uses. Must specify at least one. Defaults to all supported backends. If more than one, then name is an alias to a select on backend value to backend-specialized targets. See enclave_info.bzl:all_backends documentation for details.

unsigned_name_by_backend optional. default is {}

An optional dictionary from backend label to backend- specific target label for the defined unsigned enclaves.

signed_name_by_backend optional. default is {}

An optional dictionary from backend label to backend- specific target label for the defined signed enclaves.

testonly optional. default is 0

True if the targets should only be used in tests.

kwargs optional.

cc_binary arguments.

cc_enclave_test

cc_enclave_test(name, srcs, enclave_config, remote_proxy, tags, deps, test_in_initialize, backends, unsigned_name_by_backend, signed_name_by_backend, test_name_by_backend, kwargs)

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

This macro creates two targets, one debug_sign_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 ""

A backend-specific configuration target to be passed to the signer for each backend. Optional.

remote_proxy optional. default is None

Host-side executable that is going to run remote enclave proxy server which will actually load the enclave(s). If empty, the enclave(s) are loaded locally.

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.

backends optional. default is {"@linux_sgx//:asylo_sgx_hw": struct(config_settings = ["@linux_sgx//:sgx_hw"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_hw", order = 2, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-hw", "manual"]), "@linux_sgx//:asylo_sgx_sim": struct(config_settings = ["@linux_sgx//:sgx_sim"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_sim", order = 1, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-sim", "manual"])}

The asylo backend labels the binary uses. Must specify at least one. Defaults to all supported backends. If more than one, then name is an alias to a select on backend value to backend-specialized targets. See enclave_info.bzl:all_backends documentation for details.

unsigned_name_by_backend optional. default is {}

An optional dictionary from backend label to backend- specific target label for the defined unsigned enclaves.

signed_name_by_backend optional. default is {}

An optional dictionary from backend label to backend- specific target label for the defined signed enclaves.

test_name_by_backend optional. default is {}

An optional dictionary from backend label to backend-specific name for the test target.

kwargs optional.

cc_test arguments.

cc_test

cc_test(name, enclave_test_name, enclave_test_unsigned_name_by_backend, enclave_test_signed_name_by_backend, enclave_test_config, srcs, deps, backends, 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_unsigned_name_by_backend optional. default is {}

Dictionary of backend label to test name for backend-specific unsigned enclave targets generated by cc_enclave_test. Optional.

enclave_test_signed_name_by_backend optional. default is {}

Dictionary of backend label to test name for backend-specific signed enclave targets generated by cc_enclave_test. Optional.

enclave_test_config optional. default is ""

A backend-specific configuration target to be passed to the enclave signer for each backend. Optional.

srcs optional. default is []

Same as native cc_test srcs.

deps optional. default is []

Same as native cc_test deps.

backends optional. default is {"@linux_sgx//:asylo_sgx_hw": struct(config_settings = ["@linux_sgx//:sgx_hw"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_hw", order = 2, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-hw", "manual"]), "@linux_sgx//:asylo_sgx_sim": struct(config_settings = ["@linux_sgx//:sgx_sim"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_sim", order = 1, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-sim", "manual"])}

The asylo backend labels the binary uses. Must specify at least one. Defaults to all supported backends. If more than one, then name is an alias to a select on backend value to backend-specialized targets. See enclave_info.bzl:all_backends documentation for details.

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, backends, 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( “//asylo/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 ""

A backend-specific configuration target to be passed to the signer. 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.

backends optional. default is {"@linux_sgx//:asylo_sgx_hw": struct(config_settings = ["@linux_sgx//:sgx_hw"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_hw", order = 2, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-hw", "manual"]), "@linux_sgx//:asylo_sgx_sim": struct(config_settings = ["@linux_sgx//:sgx_sim"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_sim", order = 1, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-sim", "manual"])}

The asylo backend labels the binary uses. Must specify at least one. Defaults to all supported backends. If more than one, then name is an alias to a select on backend value to backend-specialized targets. See enclave_info.bzl:all_backends documentation for details.

kwargs optional.

See documentation for **kwargs in native cc_test rule.

cc_unsigned_enclave

cc_unsigned_enclave(name, backends, name_by_backend, kwargs)

Creates a C++ unsigned enclave target in all or any backend.

Parameters

name required.

The rule name.

backends optional. default is {"@linux_sgx//:asylo_sgx_hw": struct(config_settings = ["@linux_sgx//:sgx_hw"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_hw", order = 2, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-hw", "manual"]), "@linux_sgx//:asylo_sgx_sim": struct(config_settings = ["@linux_sgx//:sgx_sim"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_sim", order = 1, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-sim", "manual"])}

The asylo backend labels the binary uses. Must specify at least one. Defaults to all supported backends. If more than one, then name is an alias to a select on backend value to backend-specialized targets. See enclave_info.bzl:all_backends documentation for details.

name_by_backend optional. default is {}

An optional dictionary from backend label to backend- specific target label.

kwargs optional.

Remainder arguments to the backend rule.

debug_sign_enclave

debug_sign_enclave(name, unsigned, backends, config, testonly, name_by_backend)

Signs an unsigned enclave according the the backend’s signing procedure.

Parameters

name required.

The signed enclave target name.

unsigned required.

The label to the unsigned enclave.

backends optional. default is {"@linux_sgx//:asylo_sgx_hw": struct(config_settings = ["@linux_sgx//:sgx_hw"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_hw", order = 2, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-hw", "manual"]), "@linux_sgx//:asylo_sgx_sim": struct(config_settings = ["@linux_sgx//:sgx_sim"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_sim", order = 1, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-sim", "manual"])}

The asylo backend labels the binary uses. Must specify at least one. Defaults to all supported backends. If more than one, then name is an alias to a select on backend value to backend-specialized targets. See enclave_info.bzl:all_backends documentation for details.

config optional. default is None

A label to a config target that the backend-specific signing tool uses.

testonly optional. default is 0

True if the target should only be used in tests.

name_by_backend optional. default is {}

An optional dictionary from backend label to backend- specific target label.

dlopen_enclave_loader

dlopen_enclave_loader(name, enclaves, embedded_enclaves, loader_args, remote_proxy, 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.

remote_proxy optional. default is None

Host-side executable that is going to run remote enclave proxy server which will actually load the enclave(s). If empty, the enclave(s) are loaded locally.

kwargs optional.

cc_binary arguments.

dlopen_enclave_test

dlopen_enclave_test(name, kwargs)

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

Parameters

name required.

enclave_test name

kwargs optional.

same as enclave_test kwargs

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_build_test

enclave_build_test(name, enclaves, tap, tags, name_by_backend, backends)

Tests that the given enclaves build in the specified backends.

Parameters

name required.

The rule name and base name for backend-specific name derivations.

enclaves optional. default is []

A list of enclave labels.

tap optional. default is False
tags optional. default is []

Tags to apply to the test targets.

name_by_backend optional. default is {}

An optional dictionary from backend label to backend- specific test name.

backends optional. default is {"@linux_sgx//:asylo_sgx_hw": struct(config_settings = ["@linux_sgx//:sgx_hw"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_hw", order = 2, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-hw", "manual"]), "@linux_sgx//:asylo_sgx_sim": struct(config_settings = ["@linux_sgx//:sgx_sim"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_sim", order = 1, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-sim", "manual"])}

A list of Asylo backend labels.

enclave_loader

enclave_loader(name, enclaves, embedded_enclaves, loader_args, remote_proxy, backends, loader_name_by_backend, name_by_backend, deprecation, 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.

The loader is subject to a backend transition by the specified backends.

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. Enclaves are built under a backend transition.

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.

remote_proxy optional. default is None

Host-side executable that is going to run remote enclave proxy server which will actually load the enclave(s). If empty, the enclave(s) are loaded locally.

backends optional. default is {"@linux_sgx//:asylo_sgx_hw": struct(config_settings = ["@linux_sgx//:sgx_hw"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_hw", order = 2, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-hw", "manual"]), "@linux_sgx//:asylo_sgx_sim": struct(config_settings = ["@linux_sgx//:sgx_sim"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_sim", order = 1, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-sim", "manual"])}

The asylo backend labels the binary uses. Must specify at least one. Defaults to all supported backends. If more than one, then name is an alias to a select on backend value to backend-specialized targets. See enclave_info.bzl:all_backends documentation for details.

loader_name_by_backend optional. default is {}

Dictionary of backend label to loader name for backend-specific enclave driver. Optional.

name_by_backend optional. default is {}

An optional dictionary from backend label to backend- specific loader script name.

deprecation optional. default is None

A string deprecation message for uses of this macro that have been marked deprecated. Optional.

kwargs optional.

cc_binary arguments.

enclave_test

enclave_test(name, enclaves, embedded_enclaves, test_args, remote_proxy, backend_dependent_data, tags, backends, loader_name_by_backend, test_name_by_backend, deprecation, 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.

remote_proxy optional. default is None

Host-side executable that is going to run remote enclave proxy server which will actually load the enclave(s). If empty, the enclave(s) are loaded locally.

backend_dependent_data optional. default is []
tags optional. default is []

Label attached to this test to allow for querying.

backends optional. default is {"@linux_sgx//:asylo_sgx_hw": struct(config_settings = ["@linux_sgx//:sgx_hw"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_hw", order = 2, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-hw", "manual"]), "@linux_sgx//:asylo_sgx_sim": struct(config_settings = ["@linux_sgx//:sgx_sim"], debug_default_config = "@linux_sgx//:enclave_debug_config", debug_private_key = "@linux_sgx//:enclave_test_private.pem", name_derivation = "_sgx_sim", order = 1, sign_tool = "@linux_sgx//:sgx_sign_tool", tags = ["asylo-sgx-sim", "manual"])}

The asylo backend labels the binary uses. Must specify at least one. Defaults to all supported backends. If more than one, then name is an alias to a select on backend value to backend-specialized targets. See enclave_info.bzl:all_backends documentation for details.

loader_name_by_backend optional. default is {}
test_name_by_backend optional. default is {}
deprecation optional. default is None

A string deprecation message for uses of this macro that have been marked deprecated. Optional.

kwargs optional.

cc_test arguments.

sgx_enclave_test

sgx_enclave_test(name, srcs, kwargs)

Build target for testing one or more instances of ‘debug_sign_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.