Add clearer docs for how to build/sign application (microsoft#560)

CMakeLists.txt

@@ -33,7 +33,6 @@ target_link_libraries(logging_client PRIVATE
   ${CMAKE_THREAD_LIBS_INIT}
 )
 
-# SNIPPET: Logging application
 add_enclave_lib(loggingenc ${CMAKE_CURRENT_SOURCE_DIR}/src/apps/logging/oe_sign.conf ${CMAKE_CURRENT_SOURCE_DIR}/src/apps/sample_key.pem SRCS src/apps/logging/logging.cpp src/apps/logging/stub_for_code_signing.cpp)
 
 if(BUILD_TESTS)

cmake/common.cmake

@@ -571,7 +571,7 @@ set(CCF_NETWORK_TEST_ARGS
   ${PBFT_ARG}
 )
 
-# Lua generic app
+# SNIPPET: Lua generic application
 add_enclave_lib(luagenericenc ${CCF_DIR}/src/apps/luageneric/oe_sign.conf ${CCF_DIR}/src/apps/sample_key.pem SRCS ${CCF_DIR}/src/apps/luageneric/luageneric.cpp)
 
 # Samples

sphinx/source/developers/build_app.rst

@@ -0,0 +1,64 @@
+Build and Sign Application
+==========================
+
+Once an application is complete, it needs to be built into a shared object, and signed.
+
+Using `cmake`, an application can be built and automatically signed using the ``add_enclave_lib`` function, provided by CCF's ``CCF/cmake/common.cmake``. For example, for the ``luageneric`` application:
+
+.. literalinclude:: ../../../cmake/common.cmake
+    :language: cmake
+    :start-after: SNIPPET: Lua generic application
+    :lines: 1
+
+The :term:`Open Enclave` configuration file (``oe_sign.conf``) should be placed under the same directory as the source files for the application. For example:
+
+.. literalinclude:: ../../../src/apps/logging/oe_sign.conf
+
+.. note:: The `Open Enclave documentation <https://github.com/openenclave/openenclave/blob/master/docs/GettingStartedDocs/buildandsign.md#signing-the-enclave>`_ 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. ``libluagenericenc.so``) manually, using a personal signing key (specified by ``--key-file``):
+
+.. code-block:: bash
+
+    $ /opt/openenclave/bin/oesign sign --enclave-image libluagenericenc.so  --config-file CCF/src/apps/luageneric/oe_sign.conf --key-file CCF/src/apps/sample_key.pem
+    Created libluagenericenc.so.signed
+    $ ls *.so.signed
+    libluagenericenc.so.signed
+
+It is then possible to inspect the signed enclave library:
+
+.. code-block:: bash
+
+    $ /opt/openenclave/bin/oesign dump --enclave-image libluagenericenc.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 :ref:`Updating Code Version` for instructions on how members can register new application versions (``mrenclave`` field).
+
+.. note:: The `Open Enclave documentation <https://github.com/openenclave/openenclave/blob/master/docs/GettingStartedDocs/buildandsign.md#signing-the-enclave>`_. provides further details about how to sign enclave applications using ``oesign``.
+
+Running the Application
+-----------------------
+
+:ref:`Operators should start each CCF node <Starting the First Node>` with the signed enclave application as enclave file. For example, for the ``luageneric`` application:
+
+.. code-block:: bash
+
+    $ cchost --enclave-file libluagenericenc.signed.so [args]
+
+.. note:: When deploying the ``luageneric`` application, members should also :ref:`register the Lua application <Registering the Lua Application>` before the network is opened to users.

sphinx/source/developers/example.rst

@@ -1,5 +1,5 @@
-Example App
-===========
+Example Application
+===================
 
 Description
 -----------
@@ -74,6 +74,7 @@ The Logging application implements a trivial protocol, made up of four transacti
             }
         }
 
+
 Implementations
 ---------------
 

sphinx/source/developers/index.rst

@@ -3,7 +3,7 @@ Writing CCF Applications
 
 This section describes how CCF applications can be developed and deployed to a CCF network.
 
-Applications can be written in C++ or Lua (see :ref:`Example App`). An application consists of a collection of endpoints that can be triggered by :term:`users` using JSON-RPC. Each endpoint can define an :ref:`API Schema` to validate user requests.
+Applications can be written in C++ or Lua (see :ref:`Example Application`). An application consists of a collection of endpoints that can be triggered by :term:`users` using JSON-RPC. Each endpoint can define an :ref:`API Schema` to validate user requests.
 
 These endpoints mutate the state of a unique :ref:`Key-Value Store` that represents the internal state of the application. Applications define a set of ``Maps`` (see :ref:`Creating a Map`), mapping from a key to a value. When an application endpoint is triggered, the effects on the Store are committed atomically.
 
@@ -14,6 +14,7 @@ These endpoints mutate the state of a unique :ref:`Key-Value Store` that represe
   :caption: Contents:
 
   example
+  build_app
   demo
   kv/index.rst
   ledger

sphinx/source/developers/logging_cpp.rst

@@ -113,30 +113,6 @@ This produces validation error messages with a lower performance overhead, and e
 
 Both approaches register their RPC's params and result schema, allowing them to be retrieved at runtime with calls to the getSchema RPC.
 
-Build
------
-
-Once an application is complete, it needs to be built into a shared object, and signed:
-
-.. literalinclude:: ../../../CMakeLists.txt
-    :language: cmake
-    :start-after: SNIPPET: Logging application
-    :lines: 1
-
-For signing to work, a configuration is necessary. The configuration should be called `oe_sign.conf`, and
-be placed under the same directory as the source files for the application.
-
-.. literalinclude:: ../../../src/apps/logging/oe_sign.conf
-
-Running
--------
-
-This produces the enclave library ``libloggingenc.so.signed`` which can be loaded by the cchost application:
-
-.. code-block:: bash
-
-    $ cchost --enclave-file libloggingenc.so.signed [args]
-
 .. rubric:: Footnotes
 
 .. [#valijson] `Valijson is a header-only JSON Schema Validation library for C++11 <https://github.com/tristanpenman/valijson>`_.

sphinx/source/developers/logging_lua.rst

@@ -70,16 +70,3 @@ The tables passed to a Lua handler in ``tables`` and ``gov_tables`` can be acces
 
 * ``end_order()``: returns the "commit version" of the table. (Probably not useful for most applications.)
 
-
-Running
--------
-
-:ref:`Operators should start the first CCF node <Starting the First Node>` with `luageneric` as enclave file:
-
-.. code-block:: bash
-
-    cchost --enclave-file libluageneric.signed.so [args]
-
-Then, members should :ref:`register the Lua application <Registering the Lua Application>`.
-
-

sphinx/source/members/open_network.rst

@@ -30,7 +30,7 @@ The user is successfully added once a :term:`quorum` of members have accepted th
 Registering the Lua Application
 -------------------------------
 
-.. note:: This section only applies when deploying Lua applications (i.e. using the ``libluageneric.so.signed`` enclave library). For C++ applications, this step should be skipped.
+.. note:: This section only applies when deploying Lua applications (i.e. using the ``libluagenericenc.so.signed`` enclave library). For C++ applications, this step should be skipped.
 
 Before opening the CCF network to users, members should vote to register the Lua application defining the user-specific business logic (see for example :ref:`Logging (Lua)`):
 
@@ -71,4 +71,4 @@ Other members are then allowed to vote for the proposal, using the proposal id r
     $ memberclient --cert member3_cert --privk member3_privk --rpc-address rpc_ip:rpc_port --ca network_cert vote --proposal-id 2 --accept
     {"commit":19,"global_commit":18,"id":0,"jsonrpc":"2.0","result":true,"term":2}
 
-Once a quorum of members have approved the network opening (``"result":true``), the network is opened to users (see :ref:`Example App` for a simple business logic and :term:`JSON-RPC` transactions). It is only then that users are able to execute transactions on the business logic defined by the enclave file (``--enclave-file`` option to ``cchost``).
+Once a quorum of members have approved the network opening (``"result":true``), the network is opened to users (see :ref:`Example Application` for a simple business logic and :term:`JSON-RPC` transactions). It is only then that users are able to execute transactions on the business logic defined by the enclave file (``--enclave-file`` option to ``cchost``).

sphinx/source/quickstart/index.rst

@@ -23,7 +23,7 @@ Once this is done, you can quickly spin up a CCF network and start :ref:`issuing
 You should also get familiar with some of :ref:`CCF concepts`. You will then be able to:
 
 1. :ref:`Create a consortium and agree on the constitution <Member Governance>`
-2. :ref:`Develop a CCF application, based on the example logging application <Example App>`
+2. :ref:`Develop a CCF application, based on the example logging application <Example Application>`
 3. :ref:`Start a new CCF network to deploy the application <Starting a New Network>`
 4. :ref:`Let the consortium configure and open the network to users <Opening a Network>`
 5. :ref:`Have users issue business transactions to the application <Using CCF Applications>`

sphinx/source/users/issue_commands.rst

@@ -3,7 +3,7 @@ Issuing Commands
 
 Clients communicate with CCF using framed :term:`JSON-RPC` over :term:`TLS`. The ``method`` must be prefixed with the name of the target frontend (``"users"`` or ``"members"``), separated from the intended ``method`` with a single ``/``.
 
-Users can issue business transactions to CCF using the ``client`` command-line utility built with CCF. For example, to record a message at a specific id with the :ref:`Example App`:
+Users can issue business transactions to CCF using the ``client`` command-line utility built with CCF. For example, to record a message at a specific id with the :ref:`Example Application`:
 
 .. code-block:: bash