Build and Sign CCF Applications#

Note

Before building a CCF application, make sure that CCF is installed (see Install CCF).

Once an application is complete, it needs to be built into a shared object, and signed.

Using cmake, an application can be built and then signed using the functions provided by CCF’s cmake/ccf.cmake. For example, for the js_generic JavaScript application:

add_ccf_app(
  js_generic
  SRCS ${CCF_DIR}/src/apps/js_generic/js_generic.cpp
  LINK_LIBS_ENCLAVE js_generic_base.enclave js_openenclave.enclave
  LINK_LIBS_VIRTUAL js_generic_base.virtual js_openenclave.virtual INSTALL_LIBS
                    ON
)
sign_app_library(
  js_generic.enclave ${CCF_DIR}/src/apps/js_generic/oe_sign.conf
  ${CMAKE_CURRENT_BINARY_DIR}/signing_key.pem INSTALL_LIBS ON
)

The Open Enclave configuration file (oe_sign.conf) should be placed under the same directory as the source files for the application. For example:

# Enclave settings:
NumHeapPages=50000
NumStackPages=1024
NumTCS=8
ProductID=1
SecurityVersion=1
# The Debug setting is automatically inserted by sign_app_library in CMake, to build both debuggable and non-debuggable variants

Note

The Open Enclave documentation provides details about the enclave settings in the oe_sign.conf configuration file.

Standalone Signing#

It is also possible to sign an existing enclave application (e.g. libjs_generic.enclave.so) manually, using a signing key (specified by --key-file):

$ openssl genrsa -out signing_key.pem -3 3072
$ /opt/openenclave/bin/oesign sign --enclave-image libjs_generic.enclave.so --config-file CCF/src/apps/js_generic/oe_sign.conf --key-file signing_key.pem
Created libjs_generic.enclave.so.signed
$ ls *.so.signed
libjs_generic.enclave.so.signed

It is then possible to inspect the signed enclave library:

$ /opt/openenclave/bin/oesign dump --enclave-image libjs_generic.enclave.so.signed
=== Entry point:
name=_start
address=00000000008dee48

=== SGX Enclave Properties:
product_id=1
security_version=1
debug=1
xfrm=0
num_heap_pages=32768
num_stack_pages=1024
num_tcs=8
mrenclave=3175971c02d00c1a8f9dd23ca89e64955c5caa94e24f4a3a0579dcfb2e6aebf9
signature=...

For a given application, the signature field depends on the key used to sign the enclave. See Updating Code Version for instructions on how members can register new application versions (mrenclave field).

Note

The Open Enclave documentation. provides further details about how to sign enclave applications using oesign.

Debugging#

To connect a debugger to a CCF node, the configuration passed to oesign sign must have debugging enabled (Debug=1). This must be disabled for production enclaves, to ensure confidentiality is maintained. If using the sign_app_library function defined in ccf_app.cmake, two variants will be produced for each enclave. name.enclave.so.debuggable will have debugging enabled (meaning a debugger may be attached - the optimisation level is handled independently), while name.enclave.so.signed produces a final debugging-disabled enclave. The produced binaries are otherwise identical.

Additionally, the cchost binary must be told that the enclave type is debug, by setting the enclave.type configuration option to "debug".