Splinter’s security-related features start with support for cryptographic signing with public/private keys, then continue with additional levels of security and customizable permissions. This topic summarizes how Splinter uses key-based signing, provides Biome to map user credentials to keys, and supports organization-based smart permissions with the Pike smart contract. It also describes Splinter’s port requirements and security recommendations for REST API connections.
Cryptographic Signing with Public/Private Keys
Scabbard, the default distributed ledger service included in Splinter, uses public/private keys to sign all transactions that affect shared state. Each user and transaction-submitting entity has a public key and a private key for signing transactions. This includes smart contract operations (uploads, configuration, and changes), as well as transaction-related functions performed by the Splinter daemon and application-specific services.
Splinter also uses public/private keys to sign operations such as creating a circuit. For example, the admin service checks the signing key for each circuit payload and verifies that circuit proposals and votes are signed with the key of a circuit admin, as described in the next section.
Each Splinter node has one or more circuit admins who can propose new circuits and vote on circuit proposals. Usually, each node in the circuit has at least one circuit admin. The Splinter registry stores the public key of each node’s circuit admin (or admins) in the node entry.
NOTE: The admins must share their registry entries (either out-of-band or in
an external node registry file) before the circuit can be approved and created.
When creating a circuit, the circuit admin signs the proposal with their
private key (using the
--key option in the
splinter circuit propose
command). Each node verifies that this private key corresponds with the public
key that is defined in the registry.
Likewise, the circuit admin’s private key is required when voting on a circuit
proposal with the
--key option in the
splinter circuit vote command.
Smart Contract Administration with Scabbard
Each circuit has at least one contract admin who can manage smart contracts for that circuit
The contract admin (or admins) are defined in a circuit proposal (with
splinter circuit propose). The circuit admin includes one or more
admin_keys service arguments in the format
The contract admin can upload new smart contracts, configure new contracts (create a contract registry, namespace, and namespace permissions), and update or delete existing contracts. The contract admin also defines owners for the contract registry and namespace.
A contract registry owner can update contract versions. When creating a contract registry, the contract admin uses
scabbard cr create --ownersto specify at least one contract registry owner. To add an owner for an existing contract registry, the contract admin uses
scabbard cr update --owners.
A namespace owner can change the namespace permissions for the contract. When creating the contract namespace, the contract admin uses
scabbard ns create --ownersto specify at least one contract registry owner. To add an owner for an existing contract namespace, the contract admin uses
scabbard cr update --owners.
For more information, see Uploading a Smart Contract, the Grid README, and the man pages splinter-circuit-propose(1), scabbard-contract-upload(1), scabbard-cr(1), scabbard-ns(1), and scabbard-perm(1).
User and Credential Management with Biome
Biome is the Splinter component that manages the relationship between user-based data and Splinter’s key-based user information. Put simply, Biome maps user IDs and passwords (or other authentication credentials) to the public/private keys that the rest of Splinter uses to sign transactions.
Biome isolates all user-based data from the rest of Splinter, using a Biome-specific database to store the mapping between user data and keys. All other Splinter functions use only key-based signing to identify actors and verify that they have permission for the requested operation.
It’s important to note that the private keys stored in Biome are encrypted on the client side; Splinter does not re-encrypt private keys within the REST API. The client application is responsible for encryption before submitting a private key. For an example of client-encrypted keys, see the login functionality in the Gameroom application (as described in Gameroom Walkthrough: Behind scene 1.
NOTE: Currently, Biome doesn’t support integration with an organization’s identity provider (such as Active Directory). As a result, the current version of Biome is not appropriate for production deployment. This support is planned for the future. In the meantime, an application could implement a component that integrates user authentication from the organization’s identity provider with Biome-style approach for mapping users to keys.
For more information, see Biome User Management.
Smart Permissions for Organizations and Agents with Pike
Pike is a smart contract in Hyperledger Grid that handles organization and identity permissions with Sawtooth Sabre. Pike provides organization-specific business logic for agents (actors within the organization) and roles (sets of permissions).
The predefined admin role in Pike identifies the user or process who can create and change agents and roles for that organization. Other roles can be defined by organization admins or smart contracts as necessary.
Pike runs as WebAssembly (WASM) code, like other smart contracts. Smart permission data is stored in a portion of the Sabre namespace that other smart contracts and applications can access, if necessary.
For an example of a smart contract that uses Pike smart permissions, see the “intkey-multiply” smart contract in Sawtooth Sabre.
Ports and REST API Connections
By default, Splinter uses ports 8044 and 8080 for communication. Other nodes must be able to connect on port 8044. Applications and CLIs used to manage Splinter will connect to the Splinter REST API on port 8080.
Splinter supports several connection protocols for node-to-node communication:
Transport Layer Security (TLS), using X.509 certificates and associated keys for the certificate authority on each Splinter node
WebSocket secure (WSS) when the application protocol is HTTPS
Raw TCP (intended for development and testing only)
splinterd REST API does not have built-in authentication or
authorization (except for the Biome endpoints). Anyone with access to a
Splinter node on port 8080 will have unrestricted access to the REST API.
Endpoint authentication/authorization is planned for the future. In the
meantime, protecting port 8080 is recommended, either by blocking external
access or allowing selective access with a mechanism such as a reverse proxy
server or webserver.
For more information, see Planning a Splinter Deployment.