Misc documentation fixes (#6590)

microsoft · Oct 25, 2024 · 6e08bca · 6e08bca
1 parent 1bf76dd
commit 6e08bca
Show file tree

Hide file tree

Showing 6 changed files with 19 additions and 64 deletions.
diff --git 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
@@ -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
diff --git 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
@@ -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 <https://github.com/openenclave/openenclave/blob/master/docs/GettingStartedDocs/buildandsign.md#signing-an-sgx-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. ``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 <https://github.com/openenclave/openenclave/blob/master/docs/GettingStartedDocs/buildandsign.md#signing-an-sgx-enclave>`_. 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"``.
+    :end-before: SNIPPET_END: JS generic application
diff --git 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
@@ -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.
    */