зеркало из https://github.com/microsoft/CCF.git
Improve documentation for SNP deployments (#5602)
This commit is contained in:
Julien Maffre
GitHub
Родитель
ff4402c981
Коммит
2fbf87840b
|
|
@ -7,7 +7,7 @@ Application Development using CCF Overview
|
|||
- :ref:`What is Confidential Consortium Framework (CCF) <overview/what_is_ccf:What is CCF?>`
|
||||
- Read the :doc:`CCF overview </overview/index>` and get familiar with :ref:`overview/what_is_ccf:Core Concepts` and `Azure confidential computing <https://learn.microsoft.com/en-us/azure/confidential-computing/>`__
|
||||
- :doc:`Build new CCF applications </build_apps/index>` in TypeScript/JavaScript or C++
|
||||
- CCF `JavaScript module API reference <https://microsoft.github.io/CCF/main/js/ccf-app/modules.html>`__
|
||||
- CCF `JavaScript module API reference <https://microsoft.github.io/CCF/main/js/ccf-app>`__
|
||||
- CCF application get started repos `CCF application template <https://github.com/microsoft/ccf-app-template>`__ and `CCF application samples <https://github.com/microsoft/ccf-app-samples>`__
|
||||
|
||||
Development environment
|
||||
|
|
|
|||
|
|
@ -68,8 +68,8 @@ This section describes how :term:`Operators` manage the different nodes constitu
|
|||
|
||||
---
|
||||
|
||||
:fa:`laptop-code` :doc:`platforms/index`
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
:fa:`microchip` :doc:`platforms/index`
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Platforms and trusted execution environments supported by CCF.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ The ledger and snapshot files written by CCF nodes to disk should be managed by
|
|||
Ledger
|
||||
------
|
||||
|
||||
The ledger is the persistent replicated append-only record of the transactions that have been executed by the CCF service. It is written by the primary node when a transaction is executed and replicated to all backups which maintain their own duplicated copy. Each node in a network creates and maintains its own local copy of the ledger. Committed entries are always byte identical between :ref:`a majority <architecture/consensus/index:CFT Consensus Protocol>` of nodes, but a node may be more or less up to date, and uncommitted entries may differ.
|
||||
The ledger is the persistent replicated append-only record of the transactions that have been executed by the CCF service. It is written by the primary node when a transaction is executed and replicated to all backups which maintain their own duplicated copy. Each node in a network creates and maintains its own local copy of the ledger. Committed entries are always byte identical between :ref:`a majority <architecture/consensus/index:Consensus Protocol>` of nodes, but a node may be more or less up to date, and uncommitted entries may differ.
|
||||
|
||||
On each node, the ledger is written to disk in a directory specified by the ``ledger.directory`` configuration entry.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,6 +10,6 @@ CCF can run on several hardware platforms/trusted execution environments, which
|
|||
snp
|
||||
virtual
|
||||
|
||||
Which platform code is run is determined partly by the compile time flag ``COMPILE_TARGET`` and partly by runtime detection of the hardware.
|
||||
CCF releases (Debian packages and Docker images) are available for each platform.
|
||||
|
||||
.. note:: CCF networks running a mix of node platforms are not currently supported.
|
||||
.. note:: Support for a single CCF service running a mix of node platforms is currently experimental.
|
||||
|
|
|
|||
|
|
@ -1,15 +1,17 @@
|
|||
Intel SGX
|
||||
===================
|
||||
=========
|
||||
|
||||
How to use the Intel SGX platform
|
||||
---------------------------------
|
||||
|
||||
CCF must run on an Intel CPU which supports SGX.
|
||||
|
||||
To use SGX, set the enclave type in the :doc:`node configuration <../configuration>` to ``Release`` or ``Debug``.
|
||||
To use SGX, in the :ref:`operations/configuration:``enclave``` configuration section, the enclave ``platform`` should be set to ``SGX``, and ``type`` to ``Release`` or ``Debug``, depending on the enclave build type.
|
||||
|
||||
Attestation
|
||||
-----------
|
||||
SGX attestations provide a measurement of the code loaded into the enclave, which CCF stores in the :ref:`audit/builtin_maps:``nodes.code_ids``` table. New nodes joining a network will provide their code id and the primary will perform an identity check against the table entries.
|
||||
|
||||
SGX attestations provide a measurement of the code loaded into the enclave, which CCF stores in the :ref:`audit/builtin_maps:``nodes.code_ids``` table. New nodes joining a network will provide their measurement and the primary will perform an identity check against the table entries.
|
||||
|
||||
The first node in a new network will add its code id to the table. Members can then manage which code ids are present in the table with the ``add_node_code`` and ``remove_node_code`` actions.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,26 +1,63 @@
|
|||
AMD SEV-SNP
|
||||
===================
|
||||
===========
|
||||
|
||||
How to use the AMD SEV-SNP platform
|
||||
-----------------------------------
|
||||
CCF must run on an AMD CPU which supports SEV-SNP.
|
||||
|
||||
To use SNP, set the enclave type in the :doc:`node configuration <../configuration>` to ``Virtual``.
|
||||
CCF must run on an AMD CPU which supports SEV-SNP (typically `Azure confidential containers <https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-containers>`_).
|
||||
|
||||
To use SNP, in the :ref:`operations/configuration:``enclave``` configuration section, the enclave ``platform`` should be set to ``SNP``.
|
||||
|
||||
Attestation
|
||||
-----------
|
||||
SNP attestation provide several fields needed to establish trust. This is specific to the SNP hardware as deployed in confidential Azure Container Instances, see `here <https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-containers>`_ for more information.
|
||||
|
||||
- Measurement
|
||||
SNP attestation provide several fields needed to establish trust. Several deployment scenarios are possible.
|
||||
|
||||
Measurement is a digest of the initial memory pages for the SEV-SNP VM, which CCF stores in the :ref:`audit/builtin_maps:``nodes.snp.measurements``` table. New nodes joining a network will provide their code id and the primary will perform an identity check against the table entries.
|
||||
Confidential Azure Container Instance (ACI)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The first node in a new network will add its code id to the table. Members can then manage which code ids are present in the table with the ``add_snp_measurement`` and ``remove_node_code`` actions.
|
||||
.. note:: See `here <https://learn.microsoft.com/en-us/azure/container-instances/container-instances-tutorial-deploy-confidential-containers-cce-arm>`_ for more information on the deployment of confidential containers in Azure.
|
||||
|
||||
- Security Policy
|
||||
Azure Confidential ACI provides a security context directory containing the following files. The content of these files are checked against the attestation report on node startup and join, and stored in the ledger for audit and improved serviceability.
|
||||
|
||||
On startup, the UVM checks code in the container against a security policy. A digest of the security policy is then provided in the attestation in the host_data field. CCF stores authorised host data in the :ref:`audit/builtin_maps:``nodes.snp.host_data``` table. New nodes joining a network will provide their policy digest and the primary will perform an identity check against the table entries.
|
||||
- ``host-amd-cert-base64``: The certificate chain corresponding to the key (VCEK) used to sign the attestation report, up to the well-known AMD root of trust certificate authority (Base64 encoded).
|
||||
- ``security-policy-base64``: The security policy [#security_policy]_ describing the state and transitions allowed for the container (Base64 encoded). The SHA256 hash of the decoded value should match the attestation report ``host_data``. This value is stored in the :ref:`audit/builtin_maps:``nodes.snp.host_data``` table.
|
||||
- ``reference-info-base64``: The COSE Sign1 document containing the measurement [#measurement]_ of the utility VM (UVM) used to launch the container (Base64 encoded). The measurement contained in the document payload should match the report ``measurement``. If set, the value is stored in the :ref:`audit/builtin_maps:``nodes.snp.uvm_endorsements``` table and new nodes must present measurement endorsements from the same issuer (`did:x509`) to be trusted.
|
||||
|
||||
The first node in a new network will add its policy digest to the table. Members can then manage which policy digests are present in the table with the ``add_snp_host_data`` and ``remove_snp_host_data`` actions.
|
||||
The location of the security context directory is passed to the container's startup command as the ``UVM_SECURITY_CONTEXT_DIR`` environment variable. The name of this environment variable should be specified as the value of the ``security_context_directory`` in the :ref:`operations/configuration:``environment``` configuration section.
|
||||
|
||||
.. note:: A node's security policy can be obtained by decoding the value of the ``SECURITY_POLICY`` environment variable from its base64 encoding to get a raw policy string. The digest is then a SHA256 hash of this raw string.
|
||||
.. tip:: See :ccf_repo:`samples/config/start_config_aci_sev_snp.json` for a sample node configuration for ACI deployments.
|
||||
|
||||
Non-ACI Deployment
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For non-ACI deployments, the certificate chain for VCEK will need to be retrieved from an endorsement server, as specified in the :ref:`operations/configuration:``snp_endorsements_servers``` configuration section. For example, for the `well-known AMD endorsement server <https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/57230.pdf>`_, the value should be set to:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
"attestation": {
|
||||
"snp_endorsements_servers": [
|
||||
{
|
||||
"type": "AMD",
|
||||
"url": "kdsintf.amd.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
.. tip:: See :ccf_repo:`samples/config/start_config_amd_sev_snp.json` for a sample node configuration for non-ACI deployments.
|
||||
|
||||
.. note:: The CCF node will fetch the endorsements from the server on startup, which may cause substantial deployment delays (up to tens of seconds) depending on network latency and endpoint throttling.
|
||||
|
||||
Governance Proposals
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The following governance proposals can be issued to add/remove these trusted values, e.g. when upgrading the service (see :doc:`/operations/code_upgrade`):
|
||||
|
||||
- ``add_snp_host_data``/``remove_snp_host_data``: To add/remove a trusted security policy, e.g. when adding a new trusted container image as part of the code upgrade procedure.
|
||||
- ``add_snp_uvm_endorsement``/``add_snp_uvm_endorsement``: To add remove a trusted UVM endorsement (ACI deployment only).
|
||||
- ``add_snp_measurement``/``remove_snp_measurement``: To add/remove a trusted measurement.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#security_policy] A `REGO <https://www.openpolicyagent.org/docs/latest/policy-language/>`_ policy checked by the utility VM (UVM) against the ACI container.
|
||||
.. [#measurement] Digest of the initial memory pages for the SEV-SNP VM.
|
||||
|
|
@ -1,12 +1,16 @@
|
|||
Insecure Virtual
|
||||
===================
|
||||
================
|
||||
|
||||
.. warning:: The Insecure Virtual mode does not provide any security guarantees and should be used for development purposes only.
|
||||
|
||||
How to use the Insecure Virtual Platform
|
||||
----------------------------------------
|
||||
|
||||
The insecure virtual platform can run on any hardware supported by CCF.
|
||||
|
||||
To use the insecure virtual platform, set the enclave type in the :doc:`node configuration <../configuration>` to ``Virtual``.
|
||||
To use virtual, in the :ref:`operations/configuration:``enclave``` configuration section, the enclave ``platform`` should be set to ``Virtual``, and ``type`` to ``Virtual``.
|
||||
|
||||
Attestation
|
||||
-----------
|
||||
No attestation is provided with virtual nodes, so nodes using this platform should not be trusted to the same degree as other nodes.
|
||||
|
||||
As no attestation is provided by virtual nodes, any CCF node (e.g. a malicious node that would leak the service secret key) is allowed to join an existing CCF service.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
Glossary
|
||||
========
|
||||
|
||||
.. glossary::
|
||||
|
||||
.. glossary::
|
||||
Azure Confidential Compute
|
||||
`Azure Confidential Compute <https://azure.microsoft.com/en-us/solutions/confidential-compute/>`_ protects the confidentiality and integrity of your data and code while it’s processed in the public cloud.
|
||||
`Azure Confidential Compute <https://azure.microsoft.com/en-us/solutions/confidential-compute/>`_ protects the confidentiality and integrity of your data and code while it's processed in the public cloud.
|
||||
|
||||
Azure DCAP
|
||||
Intel SGX Data Centre Attestation Primitives which allows SGX attestation to be used within Microsoft Azure.
|
||||
|
|
@ -17,7 +16,7 @@ Glossary
|
|||
|
||||
CFT
|
||||
Crash Fault Tolerance is a type of fault tolerance that allows the system to tolerate network and node failures up to
|
||||
a given limit. CFT however does not account for any nodes behaving maliciously. Read more on CFT :ref:`here <architecture/consensus/index:CFT Consensus Protocol>`.
|
||||
a given limit. CFT however does not account for any nodes behaving maliciously. Read more on CFT :ref:`here <architecture/consensus/index:Consensus Protocol>`.
|
||||
|
||||
Enclave
|
||||
`Trusted Execution Environments <https://en.wikipedia.org/wiki/Trusted_execution_environment>`_, allowing fully encrypted and auditable execution without direct access from the host machine.
|
||||
|
|
@ -59,8 +58,11 @@ Glossary
|
|||
RPC
|
||||
`Remote Procedure Call <https://en.wikipedia.org/wiki/Remote_procedure_call>`_ is a way to execute functions in remote machines. CCF uses :term:`REST` host services to allow clients to execute programs inside the :term:`enclave` via the :term:`ring buffer`.
|
||||
|
||||
SEV-SNP
|
||||
`AMD Secure Encrypted Virtualisation - Secure Nested Paging <https://www.amd.com/en/processors/amd-secure-encrypted-virtualization>`_ is a trusted execution environment platform. It is a technology used to isolate virtual machines from the hypervisor with strong memory integrity protection.
|
||||
|
||||
SGX
|
||||
`Intel Software Guard Extensions <https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/overview.html>`_ is a set of instructions that increases the security of application code and data, giving them more protection from disclosure or modification. Developers can partition sensitive information into enclaves, which are areas of execution in memory with more security protection.
|
||||
`Intel Software Guard Extensions <https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/overview.html>`_ is a trusted execution environment platform. It is a set of instructions that increases the security of application code and data, giving them more protection from disclosure or modification. Developers can partition sensitive information into enclaves, which are areas of execution in memory with more security protection.
|
||||
|
||||
TCP
|
||||
`Transmission Control Protocol <https://en.wikipedia.org/wiki/Transmission_Control_Protocol>`_ is a network protocol over IP that provides sessions and ordered streams, which we use to connect between nodes and external clients.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,41 @@
|
|||
{
|
||||
"enclave": {
|
||||
"file": "libjs_generic.snp.so",
|
||||
"platform": "SNP",
|
||||
"type": "Release"
|
||||
},
|
||||
"network": {
|
||||
"node_to_node_interface": {
|
||||
"bind_address": "127.0.0.1:8081"
|
||||
},
|
||||
"rpc_interfaces": {
|
||||
"interface_name": {
|
||||
"bind_address": "127.0.0.1:8080",
|
||||
"published_address": "ccf.dummy.com:12345"
|
||||
}
|
||||
}
|
||||
},
|
||||
"command": {
|
||||
"type": "Start",
|
||||
"service_certificate_file": "service_cert.pem",
|
||||
"start": {
|
||||
"constitution_files": [
|
||||
"validate.js",
|
||||
"apply.js",
|
||||
"resolve.js",
|
||||
"actions.js"
|
||||
],
|
||||
"members": [
|
||||
{
|
||||
"certificate_file": "member0_cert.pem",
|
||||
"encryption_public_key_file": "member0_enc_pubk.pem"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"attestation": {
|
||||
"environment": {
|
||||
"security_context_directory": "UVM_SECURITY_CONTEXT_DIR"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -462,6 +462,7 @@ def run_configuration_file_checks(args):
|
|||
*cmd, env={"ASAN_OPTIONS": "alloc_dealloc_mismatch=0"}
|
||||
).returncode
|
||||
assert rc == 0, f"Failed to check configuration: {rc}"
|
||||
LOG.success(f"Successfully check sample configuration file {config}")
|
||||
|
||||
|
||||
def run_preopen_readiness_check(args):
|
||||
|
|
|
|||
|
|
@ -0,0 +1,44 @@
|
|||
{
|
||||
"enclave": {
|
||||
"file": "libjs_generic.snp.so",
|
||||
"platform": "SNP",
|
||||
"type": "Release"
|
||||
},
|
||||
"network": {
|
||||
"node_to_node_interface": {
|
||||
"bind_address": "127.0.0.1:8081"
|
||||
},
|
||||
"rpc_interfaces": {
|
||||
"interface_name": {
|
||||
"bind_address": "127.0.0.1:8080",
|
||||
"published_address": "ccf.dummy.com:12345"
|
||||
}
|
||||
}
|
||||
},
|
||||
"command": {
|
||||
"type": "Start",
|
||||
"service_certificate_file": "service_cert.pem",
|
||||
"start": {
|
||||
"constitution_files": [
|
||||
"validate.js",
|
||||
"apply.js",
|
||||
"resolve.js",
|
||||
"actions.js"
|
||||
],
|
||||
"members": [
|
||||
{
|
||||
"certificate_file": "member0_cert.pem",
|
||||
"encryption_public_key_file": "member0_enc_pubk.pem"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"attestation": {
|
||||
"snp_endorsements_servers": [
|
||||
{
|
||||
"type": "AMD",
|
||||
"url": "kdsintf.amd.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
Загрузка…
Ссылка в новой задаче