From 6e08bcab4def71ec7a0b802d89583c7cd7cec77d Mon Sep 17 00:00:00 2001 From: Amaury Chamayou Date: Fri, 25 Oct 2024 12:15:00 +0100 Subject: [PATCH] Misc documentation fixes (#6590) --- doc/audit/builtin_maps.rst | 6 +--- doc/build_apps/api.rst | 10 ++++++ doc/build_apps/auth/jwt.rst | 3 -- doc/build_apps/build_app.rst | 60 +++--------------------------------- doc/build_apps/run_app.rst | 2 +- include/ccf/crypto/cose.h | 2 ++ 6 files changed, 19 insertions(+), 64 deletions(-) diff --git a/doc/audit/builtin_maps.rst b/doc/audit/builtin_maps.rst index e6ceee47dc6b..fcd171b16796 100644 --- a/doc/audit/builtin_maps.rst +++ b/doc/audit/builtin_maps.rst @@ -359,10 +359,6 @@ JWT issuers. .. doxygenenum:: ccf::JwtIssuerKeyFilter :project: CCF -.. doxygenstruct:: ccf::JwtIssuerKeyPolicy - :project: CCF - :members: - ``jwt.public_signing_keys`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -472,7 +468,7 @@ Signatures emitted by the primary node at regular interval, over the root of the :members: ``cose_signatures`` -~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~ COSE signatures emitted by the primary node over the root of the Merkle Tree at that sequence number. diff --git a/doc/build_apps/api.rst b/doc/build_apps/api.rst index 0354d9f7cca4..808ec6394eca 100644 --- a/doc/build_apps/api.rst +++ b/doc/build_apps/api.rst @@ -162,5 +162,15 @@ HTTP Entity Tags Matching COSE ---- +.. doxygenstruct:: ccf::cose::edit::pos::InArray + :project: CCF + +.. doxygenstruct:: ccf::cose::edit::pos::AtKey + :project: CCF + :members: + +.. doxygentypedef:: ccf::cose::edit::pos::Type + :project: CCF + .. doxygenfunction:: ccf::cose::edit::set_unprotected_header :project: CCF \ No newline at end of file diff --git a/doc/build_apps/auth/jwt.rst b/doc/build_apps/auth/jwt.rst index 5ce24244b050..72c307832c9f 100644 --- a/doc/build_apps/auth/jwt.rst +++ b/doc/build_apps/auth/jwt.rst @@ -30,9 +30,6 @@ Before adding public token signing keys to a running CCF network, the IdP has to The ``issuer`` field is an arbitrary identifier and should be used during token validation to differentiate between multiple issuers. -Note that this action takes some additional optional args for more advanced scenarios. -See :ref:`build_apps/auth/jwt:Advanced issuer configuration` for details. - After this proposal is accepted, signing keys for an issuer can be updated with a ``set_jwt_public_signing_keys`` proposal: .. code-block:: bash diff --git a/doc/build_apps/build_app.rst b/doc/build_apps/build_app.rst index 700fc4a8543f..c630145c05e8 100644 --- a/doc/build_apps/build_app.rst +++ b/doc/build_apps/build_app.rst @@ -1,63 +1,13 @@ -Build and Sign CCF Applications -=============================== +Build CCF Applications +====================== .. note:: Before building a CCF application, make sure that CCF is installed (see :doc:`/build_apps/install_bin`). -Once an application is complete, it needs to be built into a shared object, and signed. +Once an application is complete, it needs to be built into a shared object. -Using ``cmake``, an application can be built and then signed using the functions provided by CCF's ``cmake/ccf_app.cmake``. For example, for the ``js_generic`` JavaScript application: +Using ``cmake``, an application can be built using the functions provided by CCF's ``cmake/ccf_app.cmake``. For example, for the ``js_generic`` JavaScript application: .. literalinclude:: ../../CMakeLists.txt :language: cmake :start-after: SNIPPET_START: JS generic application - :end-before: SNIPPET_END: JS generic application - -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:: ../../samples/apps/logging/oe_sign.conf - -.. 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``): - -.. code-block:: bash - - $ 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: - -.. code-block:: bash - - $ /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 :ref:`governance/common_member_operations: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"``. \ No newline at end of file + :end-before: SNIPPET_END: JS generic application \ No newline at end of file diff --git a/doc/build_apps/run_app.rst b/doc/build_apps/run_app.rst index 41b24a5feaa7..51a7b22a9074 100644 --- a/doc/build_apps/run_app.rst +++ b/doc/build_apps/run_app.rst @@ -1,7 +1,7 @@ Running CCF Applications ======================== -This document explains how to spin up a test CCF network and submit simple commands to it using `curl`_. We use curl here because it is a standard tool and broadly available - you should be able to get the same results with any HTTP client, provided you can configure the appropriate caller and CA identities. Once you have built your own app, you should be able to test it in the same way - simply pass the path to your app binary to ``sandbox.sh`` as ``-p/--package``, and call the endpoints defined by your app. +This document explains how to spin up a test CCF network and submit simple commands to it using ``curl``. We use curl here because it is a standard tool and broadly available - you should be able to get the same results with any HTTP client, provided you can configure the appropriate caller and CA identities. Once you have built your own app, you should be able to test it in the same way - simply pass the path to your app binary to ``sandbox.sh`` as ``-p/--package``, and call the endpoints defined by your app. Startup ------- diff --git a/include/ccf/crypto/cose.h b/include/ccf/crypto/cose.h index b75e5f9db5ee..3777130b2df7 100644 --- a/include/ccf/crypto/cose.h +++ b/include/ccf/crypto/cose.h @@ -16,6 +16,7 @@ namespace ccf::cose::edit struct AtKey { + /// @brief The key at which to insert the value. int64_t key; }; @@ -36,6 +37,7 @@ namespace ccf::cose::edit * @param key The key at which to insert either an array or a map. * @param position Either InArray or AtKey, to determine whether to insert an * array or a map. + * @param value The value to insert either in the array or the map. * * @return The COSE_Sign1 message with the new unprotected header. */