App Firewall Usage

The Blockchain Application Firewall (BAF) is configured via a policy stored in a configuration object attached to your blockchain node.

Configuration syntax

The full schema is described in the details of the POST to configurations in api.kaleido.io

Updating the configuration

When a new BAF configuration is attached to a node, or an existing configuration is changed, the node must be reset to pick up the change.

See api.kaleido.io for details of how to submit a reset.

The reset requires a restart of the Blockchain Node and App Firewall runtimes to pick up the new configuration.

Dynamic update for Application Credentials, Public keys and Tenants

A reset is not required to pick up the following changes, which propagate to the configuration automatically a short period after they are updated in the UI/API.

• Application Credentials - including regenerating secret keys (which retains the id of the key)
• Public keys for verification of JWT tokens - configured via OAuth resources
• Tenants used to dynamically generate a list of mappings - see Multi-tenant Nodes

Authentication

Two systems of authentication are supported by the Blockchain Application Firewall, and can be enabled/disabled independently:

• jwt: Authenticate using a JSON Web Token signed by a known public key, within its expiration period
  • See OAuth 2.0 / OpenID Connect more more information
• appcreds: Authenticate using strong generated credentials issued by Kaleido - passed as an API Key or in a Basic Authentication header
  • See Application Credentials more more information

When both forms of authentication are enabled, authentication is attempted using a JWT first.

Please note that if you remove/restrict access to Application Credentials with Basic Authentication credentials, then parts of the Kaleido console such as the + Connect panel and REST API explorer will be unable to connect to your nodes.

Authorization and Access Control

Once authenticated, a set of mappings are evaluated against the details establish about that connection during authentication (the claims), to establish whether the application is authorized, and with what level of access.

The mappings are evaluated in turn until one matches. If none match the request fails.

See Claim Mappings for more information

The connection is then assigned to a ruleset, which defines a set of permissions that are evaluated against every JSON/RPC call made via that connection.

HTTPS and WebSocket JSON/RPC connections are supported. For HTTPS connections the authentication is performed for each individual request. For Web Socket connections, authentication is performed once during the initial "upgrade" request, and then applied to all JSON/RPC commands performed over that connection.

The parameters of transaction related JSON/RPC methods are processed in detail. For example to extract the from and to address as well as the type of command being performed.

This includes externally signed eth_sendRawTransaction transactions, using EIP155 compliant signing with the correct Chain ID

As a result a granular set of permissions can be assigned to different connection types, such as the following examples:

• Only perform call (read--only) operations to smart contracts with a particular Ethereum address
• Send raw externally signed transactions from a particular set of addresses
• Send transactions for signing by a particular from address

The model of the blockchain application firewall is a whitelist approach, so any permissions not explicitly granted will be denied.

See Rulesets for more information

REST API Gateway Integration

The REST API Gateway is an embedded part of every Kaleido blockchain node, and it translates simple REST commands into a set of JSON/RPC requests.

The JSON/RPC requests might run synchronously against a node during the REST call, or to be queued for reliable ordered delivery to the node via a managed Apache Kafka transport.

In order to provide a single ruleset for determining the JSON/RPC permissions enabled for connections to a node, the REST API Gateway also acts as an enforcement point of the ruleset that is assigned to a connection. This is performed by creating an internally signed JWT token that is exchanged between the BAF and REST API Gateway runtime components (which remain separated runtimes for standard risk isolation purposes in a reverse proxy scenario). A JWT token is passed alongside the Kafka messages for asynchronous transactions, so the original security context of the application that submitted the asynchronous transaction is retained (even though the original JWT token or app credential is not persisted).

The generation and enforcement of this internal JWT is transparent to your application when performing REST operations.

Compatibility with native Ethereum node permissioning schemes

Both the Quroum and Hyperledger Besu communities are working on native permissioning systems for access to internal data, based on JWT authentication on the network interfaces of the node.

For example to restrict access to a private enclave of transaction data signed by a particular key in a private transaction manager (such as Quorum Tessera).

The blockchain application firewall architecture is designed to allow mapping to these permissioning schemes via efficient exchange of a front-end OAuth authentication JWT, with a back-end protocol permissioning JWT.

Please contact us if you have a project that requires configuration of the built-in permissioning infrastructure of the ethereum node itself.

Logging

The default logging level (level 1) of the blockchain application firewall is designed to provide an audit trail logging of the type of commands invoked against a node, and the timings of those requests.

You can increase the level of logging (to 2) as follows. This is helpful to debug why an application is not being authenticated, or a JSON/RPC request is being rejected as unauthorized:

{
    "logging": {
        "level": 2
    }
    // ... additional configuration
}