Configuration#

The configuration for each CCF node must be contained in a single JSON configuration file specified to the cchost executable via the --config /path/to/config/file argument.

Tip

JSON configuration samples:

A single configuration file can be verified using the cchost executable, but without launching the enclave application, using the --check option:

$ cchost --config /path/to/config/file --check

Configuration Options#

enclave#

Required. This section includes configuration for the enclave application launched by this node.

  • file: Path to enclave application. Required.

  • platform: Trusted Execution Environment platform. (values: "SGX", "SNP", "Virtual"). Default: "SGX".

  • type: Type of enclave application (only if platform is SGX). “Virtual” is deprecated (use platform instead). (values: "Release", "Debug", "Virtual"). Default: "Release".

network#

Required. This section includes configuration for the interfaces a node listens on (for both client and node-to-node communications).

node_to_node_interface#

Required. Address (host:port) to listen on for incoming node-to-node connections (e.g. internal consensus messages).

  • bind_address: Local address the node binds to and listens on. Required.

  • published_address: The published node address advertised to other nodes. Default: "Value of 'bind_address'".

rpc_interfaces#

Required. Interfaces to listen on for incoming client TLS connections, as a dictionary from unique interface name to RPC interface information.

  • bind_address: Local address the node binds to and listens on. Required.

  • published_address: The published RPC address advertised to clients. Default: "Value of 'bind_address'".

  • protocol: The RPC protocol used (udp | tcp). Default: "tcp".

  • app_protocol: The application protocol used by all sessions on this interface. (values: "HTTP1", "HTTP2"). Default: "HTTP1".

  • max_open_sessions_soft: The maximum number of active client sessions on that interface after which clients will receive an HTTP 503 error. Default: 1000.

  • max_open_sessions_hard: The maximum number of active client sessions on that interface after which clients sessions will be terminated, before the TLS handshake is complete. Note that its value must be greater than the value of max_open_sessions_soft. Default: 1010.

http_configuration#

  • max_body_size: Maximum size (size string) of a single HTTP request body. Submitting a request with a payload larger than this value will result in the client session being automatically closed. Default: "1MB".

  • max_header_size: Maximum size (size string) of a single HTTP request header (key or value). Submitting a request with a header larger than this value will result in the client session being automatically closed. Default: "16KB".

  • max_headers_count: Maximum number of headers in a single HTTP request. Submitting a request with more headers than this value will result in the session being automatically closed. Default: 256.

  • max_concurrent_streams_count: HTTP/2 only. Maximum number of concurrent streams allowed per session. Default: 100. Minimum: 1.

  • initial_window_size: HTTP/2 only. Initial size (size string) of flow-control window per stream. Default: "64KB".

  • max_frame_size: HTTP/2 only. Maximum allowed size (size string) of HTTP/2 frames (min: 16KB, max: 16MB). Default: "16KB".

endorsement#

  • authority: The type of endorsement for the TLS certificate used in client sessions. If the endorsement is not available, client sessions will be terminated, before the TLS handshake is complete. ‘Node’ means self-signed, ‘Service’ means service-endorsed, ‘ACME’ means an ACME-capable CA, ‘Unsecured’ means unencrypted traffic and no endorsement authority. (values: "Node", "Service", "ACME", "Unsecured"). Default: "Service". Required.

  • acme_configuration: Name of the ACME configuration defined in the network.acme.configurations section.

  • accepted_endpoints: An array of regular expressions that specify which URL paths are served on the interface. Optional; if not present, all paths are served.

  • forwarding_timeout_ms: Timeout for forwarded RPC calls (in milliseconds). Default: 3000.

acme#

Configuration for the ACME client(s) to obtain globally valid TLS certificates, e.g. from Let’s Encrypt.

configurations#

  • ca_certs: Root certificate(s) of the CA to connect to in PEM format (for TLS connections to the CA, e.g. Let’s Encrypt’s ISRG Root X1). Default: [].

  • directory_url: URL of the ACME server’s directory.

  • service_dns_name: DNS name of the service we represent.

  • alternative_names: Alternative names for the service we represent (X509 SANs). Default: [].

  • contact: Contact addresses (see RFC8555 7.3, e.g. mailto:john@example.com). Default: [].

  • terms_of_service_agreed: Indication that the user/operator is aware of the latest terms and conditions for the CA. Default: false.

  • challenge_type: Type of the ACME challenge (usually http-01; others are supported but require a custom challenge handler). Default: "http-01".

  • challenge_server_interface: Name of the interface for the http-01 challenge frontend to listen on.

command#

Required. This section includes configuration of how the node should start (either start, join or recover) and associated information.

  • type: Type of CCF node. (values: "Start", "Join", "Recover"). Required.

  • service_certificate_file: For Start and Recover nodes, path to which service certificate will be written to on startup. For Join nodes, path to the certificate of the existing service to join. Default: "service_cert.pem".

start#

Note: Only if type is "Start".

  • constitution_files: List of constitution files. These typically include actions.js, validate.js, resolve.js and apply.js. Required.

  • initial_service_certificate_validity_days: Initial validity period (days) for service certificate. Default: 1. Minimum: 1.

members#

Required. List of initial consortium members files, including identity certificates, public encryption keys and member data files.

  • certificate_file: Path to member x509 identity certificate (PEM).

  • encryption_public_key_file: Path to member encryption public key (PEM).

  • data_json_file: Path to member data file (JSON).

service_configuration#

  • recovery_threshold: Number of recovery members required to recover the service. Note that if the recovery threshold is set to 0, it is automatically set to the number of recovery members specified in ‘members’. Minimum: 0. Required.

  • maximum_node_certificate_validity_days: The maximum number of days allowed for node certificate validity period. Default: 365. Minimum: 1.

  • maximum_service_certificate_validity_days: The maximum number of days allowed for service certificate validity period. Default: 365. Minimum: 1.

  • reconfiguration_type: . (values: "OneTransaction", "TwoTransaction"). Default: "OneTransaction".

  • recent_cose_proposals_window_size: Size of the window of COSE proposals recently received by the service, kept for the purpose of replay protection. Default: 100. Minimum: 1.

join#

Note: Only if type is "Join".

  • target_rpc_address: Address (host:port) of a node of the existing service to join. Required.

  • retry_timeout: Interval (time string) at which the node sends join requests to the existing service. This should be less than the value of ‘consensus.election_timeout’ set on the primary node of the existing service to join. Default: "1000ms".

recover#

Note: Only if type is "Recover".

  • initial_service_certificate_validity_days: Initial validity period (days) for service certificate. Default: 1. Minimum: 1.

  • previous_service_identity_file: Path to the previous service certificate (PEM) file. Required.

node_certificate#

This section includes configuration for the node x509 identity certificate.

  • subject_name: Subject name to include in node certificate. Default: "CN=CCF Node".

  • subject_alt_names: List of iPAddress: or dNSName: strings to include as Subject Alternative Names (SAN) in node certificates. If none are set, the node certificate will automatically include the value of the main RPC interface ‘published_address’.

  • curve_id: Elliptic curve to use for node identity key. (values: "Secp384R1", "Secp256R1"). Default: "Secp384R1".

  • initial_validity_days: Initial validity period (days) for node certificate. Default: 1. Minimum: 1.

node_data_json_file#

Path to file (JSON) containing initial node data. It is intended to store correlation IDs describing the node’s deployment, such as a VM name or Pod identifier.

attestation#

This section includes configuration for the attestation for AMD SEV-SNP platform (ignored for SGX).

environment#

Environment variables required to provide best auditability and serviceability for Azure Container Instance deployments (SEV-SNP only).

  • report_endorsements: Name of environment variable (e.g. UVM_HOST_AMD_CERTIFICATE) containing base64-encoded attestation report endorsements as JSON object (Azure Container Instance SEV-SNP only). If this is set, specified snp_endorsements_servers are ignored.

  • security_policy: Name of environment variable (e.g. UVM_SECURITY_POLICY) containing base64-encoded security policy (Azure Container Instance SEV-SNP only).

  • uvm_endorsements: Name of environment variable (e.g. UVM_REFERENCE_INFO) containing base64-encoded UVM endorsements as COSE Sign1 document (Azure Container Instance SEV-SNP only).

snp_endorsements_servers#

List of servers used to retrieve attestation report endorsement certificates (SEV-SNP only). The first server in the list is always used and other servers are only specified as fallback. Ignored if environment.report_endorsements is set.

  • type: Type of server used to retrieve attestation report endorsement certificates (SEV-SNP only). (values: "Azure", "AMD"). Default: "Azure".

  • url: Server URLs used to retrieve attestation report endorsement certificates, e.g. “kdsintf.amd.com” (SEV-SNP only).

service_data_json_file#

Path to file (JSON) containing initial service data. It is used when the node starts in ‘Start’ or ‘Recover’ mode and is intended to store arbitrary information about the service.

ledger#

This section includes configuration for the ledger directories and files.

  • directory: Path to main ledger directory. Default: "ledger".

  • read_only_directories: Paths to read-only ledger directories. Note that only ‘.committed’ files will be read from these directories.

  • chunk_size: Minimum size (size string) of the current ledger file after which a new ledger file (chunk) is created. Default: "5MB".

snapshots#

This section includes configuration for the snapshot directories and files.

  • directory: Path to snapshots directory. Default: "snapshots".

  • tx_count: Number of transactions after which a snapshot is automatically generated. Default: 10000. Minimum: 1.

  • read_only_directory: Path to read-only snapshots directory.

logging#

This section includes configuration for the logging of the node process.

  • host_level: Logging level for the untrusted host. Note: while it is possible to set the host log level at startup, it is deliberately not possible to change the log level of the enclave without rebuilding it and changing its code identity. (values: "Trace", "Debug", "Info", "Fail", "Fatal"). Default: "Info".

  • format: If ‘json’, node logs will be formatted as JSON. (values: "Text", "Json"). Default: "Text".

consensus#

This section includes configuration for the consensus protocol (note: should be the same for all other nodes in the service).

  • type: Type of consensus protocol. Only CFT (Crash-Fault Tolerant) is currently supported. (values: "CFT"). Default: "CFT".

  • message_timeout: Maximum interval (time string) at which the primary node sends messages to backup nodes to maintain its primary-ship. This should be set to a significantly lower value than ‘election_timeout’. Default: "100ms".

  • election_timeout: Maximum timeout (time string) after which backup nodes that have not received any message from the primary node (or voted for a candidate) will trigger a new election. This timeout is also used by candidates to restart unsuccessful elections. This should be set to a significantly greater value than ‘message_timeout’ plus the expected network delay. Default: "5000ms".

ledger_signatures#

This section includes configuration for the ledger signatures emitted by this node (note: should be the same for all other nodes in the service). Transaction commit latency in a CCF network is primarily a function of signature frequency. A network emitting signatures more frequently will be able to commit transactions faster, but will spend a larger proportion of its execution resources creating and verifying signatures. Setting signature frequency is a trade-off between transaction latency and throughput.

  • tx_count: Number of transactions after which a signature transaction is automatically generated. Default: 5000. Minimum: 1.

  • delay: Maximum duration after which a signature transaction is automatically generated. Default: "1000ms".

jwt#

This section includes configuration for JWT issuers automatic refresh.

  • key_refresh_interval: Interval at which JWT keys for issuers registered with auto-refresh are automatically refreshed. Default: "30min".

output_files#

This section includes configuration for additional files output by the node.

  • node_certificate_file: Path to self-signed node certificate output by node on startup. Default: "nodecert.pem".

  • pid_file: Path to file in which ‘cchost’ process identifier (PID) will be written to on startup. Default: "cchost.pid".

  • node_to_node_address_file: Path to file in which node address (hostname and port) will be written to on startup. This option is particularly useful when binding to port 0 and getting auto-assigned a port by the OS. No file is created if this entry is not specified.

  • rpc_addresses_file: Path to file in which all RPC addresses (hostnames and ports) will be written to on startup. This option is particularly useful when binding to port 0 and getting auto-assigned a port by the OS. No file is created if this entry is not specified.

tick_interval#

Interval at which the enclave time will be updated by the host (modify with care!). Default: "10ms".

slow_io_logging_threshold#

Maximum duration of I/O operations (ledger and snapshots) after which slow operations will be logged to node log. Default: "10000us".

node_client_interface#

Address to bind to for node-to-node client connections. If unspecified, this is automatically assigned by the OS. This option is particularly useful for testing purposes (e.g. establishing network partitions between nodes).

client_connection_timeout#

Maximum duration after which unestablished client connections will be marked as timed out and either re-established or discarded. Default: "2000ms".

worker_threads#

Experimental. Number of additional threads processing incoming client requests in the enclave (modify with care!). Default: 0. Minimum: 0.

memory#

This section includes configuration for the host-enclave ring-buffer memory (modify with care!).

  • circuit_size: Size (size string) of the internal host-enclave ringbuffers (must be a power of 2). Default: "4MB".

  • max_msg_size: Maximum size (size string) for a message sent over the ringbuffer. Messages may be split into multiple fragments, but this limits the total size of the sum of those fragments. Default: "16MB".

  • max_fragment_size: Maximum size (size string) of individual ringbuffer message fragments. Messages larger than this will be split into multiple fragments. Default: "64KB".

ignore_first_sigterm#

Ignore the first SIGTERM received by the process, but set “stop_notice” in /node/state. Default: false.

node_to_node_message_limit#

Cap at which node-to-node message channels will be closed, and a new channel will be created. Can be used to limit use of single cryptographic key. Minimum: 0.

Note

  • Size strings are expressed as the value suffixed with the size in bytes (B, KB, MB, GB, TB, as factors of 1024), e.g. "20MB", "100KB" or "2048" (bytes).

  • Time strings are expressed as the value suffixed with the duration (us, ms, s, min, h), e.g. "1000ms", "10s" or "30min".