Built-in Maps

public:ccf.gov.

members.certs

X509 certificates of all members in the consortium.

Key Member ID: SHA-256 fingerprint of the member certificate, represented as a hex-encoded string.

Value Member certificate, represented as a PEM-encoded string.

members.encryption_public_keys

Public encryption keys submitted by members to the network. The recovery share for each member is encrypted by the key they have submitted.

Key Member ID: SHA-256 fingerprint of the member certificate, represented as a hex-encoded string.

Value Member public encryption key, represented as a PEM-encoded string.

members.info

Participation status and auxiliary information attached to a member.

Key Member ID: SHA-256 fingerprint of the member’s X509 certificate, represented as a hex-encoded string.

Value Represented as JSON.

struct MemberDetails

Subclassed by ccf::FullMemberDetails

Public Members

MemberStatus status = MemberStatus::ACCEPTED

Status of the member in the consortium.

nlohmann::json member_data = nullptr

Free-form member data, can be used to associate specific roles to members for example.

enum class ccf::MemberStatus

Values:

enumerator ACCEPTED

enumerator ACTIVE

members.acks

Member acknowledgements of the ledger state, each containing a signature over the Merkle root at a particular sequence number.

Key Member ID: SHA-256 fingerprint of the member certificate, represented as a hex-encoded string.

Value Represented as JSON.

struct MemberAck : public ccf::StateDigest

Public Members

std::optional<SignedReq> signed_req = std::nullopt

Signed request containing the last state digest.

std::optional<std::vector<uint8_t>> cose_sign1_req = std::nullopt

COSE Sign1 containing the last state digest.

struct StateDigest

Records a signed signature containing the last state digest and the next state digest to sign

Subclassed by ccf::MemberAck

Public Members

std::string state_digest

Next state digest the member is expected to sign.

struct SignedReq

Public Members

std::vector<uint8_t> sig = {}

Signature.

std::vector<uint8_t> req = {}

Signed content.

std::vector<uint8_t> request_body = {}

Request body.

crypto::MDType md = crypto::MDType::NONE

Hashing algorithm used to summarise content before signature.

std::string key_id = {}

Signer key id, if present in the request.

users.certs

X509 certificates of all network users.

Key User ID: SHA-256 fingerprint of the user certificate, represented as a hex-encoded string.

Value User certificate, represented as a PEM-encoded string.

users.info

Auxiliary information attached to a user.

Key User ID: SHA-256 fingerprint of the user certificate, represented as a hex-encoded string.

Value Represented as JSON.

struct UserDetails

Public Members

nlohmann::json user_data = nullptr

Free-form user data, useful to store role information about users for example.

nodes.info

Identity, status and attestations (endorsed quotes) of the nodes hosting the network.

Key Node ID: SHA-256 digest of the node public key, represented as a hex-encoded string.

Value Represented as JSON.

struct NodeInfo : public ccf::NodeInfoNetwork

Public Members

QuoteInfo quote_info

Node enclave quote.

crypto::Pem encryption_pub_key

Node encryption public key, used to distribute ledger re-keys.

NodeStatus status = NodeStatus::PENDING

Node status.

std::optional<kv::Version> ledger_secret_seqno = std::nullopt

Set to the seqno of the latest ledger secret at the time the node is trusted

std::optional<std::string> code_digest = std::nullopt

Code identity for the node.

std::optional<crypto::Pem> certificate_signing_request = std::nullopt

Node certificate signing request.

Fields below are added in 2.x

std::optional<crypto::Pem> public_key = std::nullopt

Public key.

nlohmann::json node_data = nullptr

Free-form user data, can be used to store operator correlation IDs/labels for the node for example

std::optional<crypto::Pem> cert = std::nullopt

Fields below are deprecated Deprecated as of 2.x. Node certificate. Only set for 1.x releases. Further releases record node identity in public_key field. Service-endorsed certificate is recorded in “public:ccf.nodes.endorsed_certificates” table

bool retired_committed = false

Commit state for Retired state

Introduced during 2.x (2.0.5), and so optional for backward compatibility.

enum class ccf::NodeStatus

Values:

enumerator PENDING

enumerator TRUSTED

enumerator RETIRED

struct NodeInfoNetwork : public ccf::NodeInfoNetwork_v2

Subclassed by ccf::NodeInfo

struct NodeInfoNetwork_v2

Node network information.

Subclassed by ccf::NodeInfoNetwork

Public Types

using RpcInterfaces = std::map<RpcInterfaceID, NetInterface>

RPC interface mapping.

Public Members

NetInterface node_to_node_interface

Node-to-node network interface.

RpcInterfaces rpc_interfaces

RPC interfaces.

std::optional<ACME> acme = std::nullopt

ACME configuration.

struct ACME

ACME configuration description.

Public Members

std::map<std::string, ccf::ACMEClientConfig> configurations

Mapping of ACME client configuration names to configurations.

struct NetInterface

Network interface description.

Public Members

std::optional<size_t> max_open_sessions_soft = std::nullopt

Maximum open sessions soft limit.

std::optional<size_t> max_open_sessions_hard = std::nullopt

Maximum open sessions hard limit.

std::optional<http::ParserConfiguration> http_configuration = std::nullopt

HTTP configuration.

std::optional<Endorsement> endorsement = std::nullopt

Interface endorsement.

std::optional<std::vector<std::string>> accepted_endpoints = std::nullopt

Regular expressions of endpoints that are accessible over this interface. std::nullopt means everything is accepted.

std::optional<size_t> forwarding_timeout_ms = std::nullopt

Timeout for forwarded RPC calls (in milliseconds)

struct Redirections

struct QuoteInfo

Describes a quote (attestation) from trusted hardware.

Public Members

QuoteFormat format = QuoteFormat::oe_sgx_v1

Quote format.

std::vector<uint8_t> quote

Enclave quote.

std::vector<uint8_t> endorsements

Quote endorsements.

std::optional<std::vector<uint8_t>> uvm_endorsements

UVM endorsements (SNP-only)

std::optional<std::string> endorsed_tcb = std::nullopt

Endorsed TCB (hex-encoded)

enum class ccf::QuoteFormat

Values:

enumerator oe_sgx_v1

enumerator insecure_virtual

enumerator amd_sev_snp_v1

nodes.endorsed_certificates

Key Node ID: SHA-256 digest of the node public key, represented as a hex-encoded string.

Value Node service-endorsed certificate, represented as a PEM-encoded string.

nodes.code_ids

Versions of the code allowed to join the current network on SGX.

Key MRENCLAVE, represented as a base64 hex-encoded string (length: 64).

Value Status represented as JSON.

Example

Code ID	Status
cae46d1...bb908b64e	ALLOWED_TO_JOIN

nodes.snp.host_data

Trusted attestation report host data field for new nodes allowed to join the network (SNP only).

Key Host data: The host data.

Value Metadata: The platform specific meaning of the host data.

nodes.snp.measurements

Trusted measurements for new nodes allowed to join the network (SNP only).

Note

For improved serviceability on confidential ACI deployments, see nodes.snp.uvm_endorsements map.

Key Measurement, represented as a base64 hex-encoded string (length: 96).

Value Status represented as JSON.

Example

Code ID	Status
ede8268...01b66ed1	ALLOWED_TO_JOIN

nodes.snp.uvm_endorsements

For Confidential Azure Container Instance (ACI) deployments, trusted endorsements of utility VM (UVM) for new nodes allowed to join the network (SNP only).

Key Trusted endorser DID (did:x509 only for now: https://github.com/microsoft/did-x509/blob/main/specification.md).

Value Map of issuer feed to Security Version Number (SVN) represented as JSON. See https://ietf-wg-scitt.github.io/draft-ietf-scitt-architecture/draft-ietf-scitt-architecture.html#name-issuer-identity.

service.info

Service identity and status.

Key Sentinel value 0, represented as a little-endian 64-bit unsigned integer.

Value Represented as JSON.

enum class ccf::ServiceStatus

Values:

enumerator OPENING

enumerator OPEN

enumerator WAITING_FOR_RECOVERY_SHARES

enumerator RECOVERING

struct ServiceInfo

Public Members

crypto::Pem cert

x.509 Service Certificate, as a PEM string

ServiceStatus status = ServiceStatus::OPENING

Status of the service.

std::optional<kv::Version> previous_service_identity_version = std::nullopt

Version (seqno) of previous service identity (before the last recovery)

std::optional<size_t> recovery_count = std::nullopt

Number of disaster recoveries performed on this service.

nlohmann::json service_data = nullptr

Free-form user data, can be used by members to store additional information about service

std::optional<ccf::TxID> current_service_create_txid = std::nullopt

TxID at which current service was created.

graph TB; Opening-- transition_service_to_open -->Open; Recovering-- "transition_service_to_open (recovery)"-->WaitingForRecoveryShares; WaitingForRecoveryShares -- member shares reassembly--> Open; Open-- "start in recovery"-->Recovering;

service.config

Service configuration.

Key Sentinel value 0, represented as a little-endian 64-bit unsigned integer.

Value Represented as JSON.

struct ServiceConfiguration

Public Members

std::optional<size_t> maximum_node_certificate_validity_days = std::nullopt

Fields below are added in 2.x

std::optional<size_t> recent_cose_proposals_window_size = std::nullopt

Size of recent_cose_proposals window.

Fields below are added in 3.x

service.previous_service_identity

PEM identity of previous service, which this service recovered from.

Key Sentinel value 0, represented as a little-endian 64-bit unsigned integer.

Value Previous Service Identity, represented as a PEM-encoded JSON string.

service.acme_certificates

Key Name of a network interface (string).

Value Endorsed TLS certificate for the interface, represented as a PEM-encoded string.

proposals

Governance proposals.

Key Proposal ID: SHA-256 digest of the proposal and store state observed during its creation, represented as a hex-encoded string.

Value Proposal as submitted (body of proposal request), as a raw buffer.

proposals_info

Status, proposer ID and ballots attached to a proposal.

Key Proposal ID: SHA-256 digest of the proposal and store state observed during its creation, represented as a hex-encoded string.

Value Represented as JSON.

struct ProposalInfo

Proposal metadata stored in the KV.

Public Members

ccf::MemberId proposer_id

ID of the member who originally created/submitted this proposal.

ccf::ProposalState state

Current state of this proposal (eg - open, accepted, withdrawn)

Ballots ballots = {}

Collection of ballots (scripts) submitted for this proposal. Each ballot is a javascript module exporting a single ‘vote’ function, re-executed to determine the member’s vote each proposal resolution. Keyed by each submitting member’s ID

std::optional<Votes> final_votes = std::nullopt

Collection of boolean results of the submitted ballots, keyed by submitting member’s ID, that caused a transition to a terminal state. Note that this is not present for open, withdrawn, or dropped proposals

std::optional<VoteFailures> vote_failures = std::nullopt

Collection of exception details describing which ballots failed to execute successfully, keyed by submitting member’s ID. Populated in the same circumstances as final_votes

std::optional<Failure> failure = std::nullopt

Exception details from execution of the proposal itself, either during resolution or application. Populated in the same circumstances as final_votes

enum class ccf::ProposalState

Members use proposals to propose changes to the public governance tables in the KV store. Active members can issue proposals. These proposals are stored in the KV, and passed to the JS constitution functions for validation and execution.

Values:

enumerator OPEN

enumerator ACCEPTED

enumerator WITHDRAWN

enumerator REJECTED

enumerator FAILED

enumerator DROPPED

modules

JavaScript modules, accessible by JavaScript endpoint functions.

Key Module name as a string.

Value Contents of the module as a string.

modules_quickjs_bytecode

JavaScript engine module cache, accessible by JavaScript endpoint functions.

Key Module name as a string.

Value Compiled bytecode as raw buffer.

modules_quickjs_version

JavaScript engine version of the module cache, accessible by JavaScript endpoint functions.

Key Sentinel value 0, represented as a little-endian 64-bit unsigned integer.

Value QuickJS version as a string.

js_runtime_options

QuickJS runtime options, used to configure runtimes created by CCF.

Key Sentinel value 0, represented as a little-endian 64-bit unsigned integer.

Value Represented as JSON.

struct JSRuntimeOptions

Public Members

size_t max_heap_bytes

heap size for QuickJS runtime

size_t max_stack_bytes

stack size for QuickJS runtime

uint64_t max_execution_time_ms

max execution time for QuickJS

bool log_exception_details = false

emit exception details to the log NOTE: this is a security risk as it may leak sensitive information to anyone with access to the application log, which is unprotected.

bool return_exception_details = false

return exception details in the response NOTE: this is a security risk as it may leak sensitive information, albeit to the caller only.

size_t max_cached_interpreters = 10

how many interpreters may be cached in-memory for future reuse

interpreter.flush

Used by transactions that set the JS application to signal to the interpreter cache system that existing instances need to be flushed.

Key Sentinel value 0, represented as a little-endian 64-bit unsigned integer.

Value Boolean, represented as JSON.

endpoints

JavaScript endpoint definitions.

Key Concatenation of HTTP method and endpoint dispatch key.

Examples

app.json fragment	Key
{ "endpoints": { "/jwt": { "get": { ... } } } }	GET /jwt
{ "endpoints": { "/jwt": { "post": { ... } } } }	POST /jwt
{ "endpoints": { "/log/private/{id}": { "post": { ... } } } }	POST /log/private/{id}

Value Represented as JSON.

struct EndpointProperties

Public Members

Mode mode = Mode::ReadWrite

Endpoint mode.

ForwardingRequired forwarding_required = ForwardingRequired::Always

Endpoint forwarding policy.

RedirectionStrategy redirection_strategy = RedirectionStrategy::ToPrimary

Endpoint redirection policy.

std::vector<nlohmann::json> authn_policies = {}

Authentication policies.

nlohmann::json openapi

OpenAPI schema for endpoint.

std::string js_module

JavaScript module.

std::string js_function

JavaScript function name.

std::optional<InterpreterReusePolicy> interpreter_reuse = std::nullopt

Determines how JS interpreters may be reused between multiple calls, sharing global state in potentially unsafe ways. The default empty value means no reuse is permitted.

enum class ccf::endpoints::Mode

Values:

enumerator ReadWrite

enumerator ReadOnly

enumerator Historical

enum class ccf::endpoints::ForwardingRequired

Values:

enumerator Sometimes

ForwardingRequired::Sometimes is the default value, and should be used for most read-only operations. If this request is made to a backup node, it may be forwarded to the primary node for execution to maintain session consistency. Specifically, if this request is sent as part of a session which was already forwarded, then it will also be forwarded.

enumerator Always

ForwardingRequired::Always should be used for operations which may produce writes. If this request is made to a backup node, it will be forwarded to the primary node for execution.

enumerator Never

ForwardingRequired::Never should be used for operations which want to read node-local state rather than the latest replicated state, such as historical queries or local consensus information. This call will never be forwarded, and is always executed on the receiving node, potentiall breaking session consistency. If this attempts to write on a backup, this will fail.

tls.ca_cert_bundles

CA cert bundle storage table, these bundles are used to authenticate connections to JWT issuers.

Key Bundle name, represented as a string.

Value Cert bundle, represented as a PEM-encoded string.

jwt.issuers

JWT issuers.

Key JWT issuer URL, represented as a string.

Value Represented as JSON.

struct JwtIssuerMetadata

Public Members

JwtIssuerKeyFilter key_filter

JWT issuer key filter.

std::optional<JwtIssuerKeyPolicy> key_policy

Optional Key Policy.

std::optional<std::string> ca_cert_bundle_name

Optional CA bundle name used for authentication when auto-refreshing.

bool auto_refresh = false

Whether to auto-refresh keys from the issuer.

enum class ccf::JwtIssuerKeyFilter

Values:

enumerator All

enumerator SGX

struct JwtIssuerKeyPolicy

Public Members

std::optional<std::map<std::string, std::string>> sgx_claims

OE claim name -> hex-encoded claim value See openenclave/attestation/verifier.h

jwt.public_signing_keys

JWT signing keys.

Key JWT Key ID, represented as a string.

Value JWT public key or certificate, represented as a DER-encoded string.

jwt.public_signing_key_issuer

JWT signing key to Issuer mapping.

Key JWT Key ID, represented as a string.

Value JWT issuer URL, represented as a string.

constitution

Service constitution: JavaScript module, exporting validate(), resolve() and apply().

Key Sentinel value 0, represented as a little-endian 64-bit unsigned integer.

Value JavaScript module, represented as a string.

history

Governance history of the service, captures signed governance requests submitted by members.

Key Member ID: SHA-256 fingerprint of the member certificate, represented as a hex-encoded string.

Value Represented as JSON.

See ccf::SignedReq

cose_history

Governance history of the service, captures all COSE Sign 1 governance requests submitted by members.

Key Member ID: SHA-256 fingerprint of the member certificate, represented as a hex-encoded string.

Value COSE Sign1

cose_recent_proposals

Window of recent COSE signed proposals, kept for the purpose of avoiding potential replay. Submitted proposals must be newer than the timestamp of the median, and not collide with any entry.

The window size is set to 100 by default, but can be overriden by setting recent_cose_proposals_window_size in public:ccf.gov.service.config.

Key ccf.gov.msg.created_at field from COSE protect header, as a string zero-padded to 10 characters, followed by SHA-256 digest of the COSE Sign1, represented as a hex-encoded string and separated by a ‘:’.

Value Proposal ID as a string.

public:ccf.internal.

historical_encrypted_ledger_secret

On each rekey, the old ledger secret is stored in this table , encrypted with the new secret.

While the contents themselves are encrypted, the table is public so as to be accessible by a node bootstrapping a recovery service.

encrypted_ledger_secrets

Used to broadcast ledger secrets between nodes during a recovery and ledger rekey.

While the contents themselves are encrypted, the table is public so as to be accessible by a node bootstrapping a recovery service.

tree

On every signature transaction, this contains the serialised Merkle Tree for the ledger, between the previous signature and this one.

This is used to generate receipts for historical transactions without having the recompute hashes.

signatures

Signatures emitted by the primary node at regular interval, over the root of the Merkle Tree at that sequence number.

Key Sentinel value 0, represented as a little-endian 64-bit unsigned integer.

Value

struct PrimarySignature : public ccf::NodeSignature

Public Members

ccf::SeqNo seqno = 0

Sequence number of the signature transaction.

ccf::View view = 0

View of the signature transaction.

crypto::Sha256Hash root

Root of the Merkle Tree as of seqno - 1.

crypto::Pem cert

Service-endorsed certificate of the node which produced the signature.

struct NodeSignature

Subclassed by ccf::PrimarySignature

Public Members

std::vector<uint8_t> sig

Signature.

NodeId node

Node ID.

Nonce hashed_nonce

Hashed nonce created by the node, only used for BFT.

recovery_shares

Members’ recovery_shares, encrypted by the keys recorded in members.encryption_public_keys.

While the contents themselves are encrypted, the table is public so as to be accessible by nodes bootstrapping a recovery service.

snapshot_evidence

Evidence inserted in the ledger by a primary producing a snapshot to establish provenance.

Key Sentinel value 0, represented as a little-endian 64-bit unsigned integer.

Value

struct SnapshotHash

Public Members

crypto::Sha256Hash hash

Snapshot digest.

kv::Version version

Sequence number to which the snapshot corresponds.

encrypted_submitted_shares

Used to persist submitted shares during a recovery.

While the contents themselves are encrypted, the table is public so as to be accessible by nodes bootstrapping a recovery service.