Security

Running a different version of IBM Blockchain Platform? Switch to version 2.1.3, 2.5, 2.5.1, 2.5.2, 2.5.3.

Important: You are not looking at the latest product documentation. It is strongly suggested that you upgrade to the latest version of the product as soon as possible. Upgrading ensures that you are using the latest product features and fixes, such as improved product stability, automated certificate renewal, and current security patches. Security patches are not applied to older versions of the product that are no longer supported. The supported environments described in documentation for earlier releases, such as a previously supported Kubernetes version, are not updated and may no longer be accurate—do not rely upon support for any versions listed in earlier releases of the product.

IBM® Blockchain Platform provides a scalable, highly reliable platform that helps customers deploy applications and data quickly and securely. This document provides information about securing your IBM Blockchain Platform service instance, where the blockchain console runs, and best practices for securing the Kubernetes cluster where the blockchain nodes are deployed.

Security on the IBM Blockchain Platform console

Audience: Tasks in this section are typically performed by blockchain network operators.

Configuration of an IBM Blockchain Platform network includes deploying the blockchain console that can then be used to create blockchain nodes that reside in the customer Kubernetes cluster.

Considerations include:

• IAM (Identity and Access Management)
• Ports
• Key management
• Membership service providers (MSPs)
• Access control lists (ACLs)
• API authentication

IAM (Identity and Access Management)

Identity and access management allows the owner of a console to control which users can access to the console and their privileges within it. IAM is built into the blockchain console and includes local console authentication and role management. When the console is initially provisioned you need to specify the email address of the user who is designated as the console administrator, also known as the Manager. This administrator can then add and grant other users access to the console by using the Users tab. It is also possible to change the console administrator. Every user that accesses the console must be assigned an access policy with a user role defined. The policy determines what actions the user can perform within the console. Other users can be assigned with Manager, Writer, or Reader roles when a console manager adds them to the console. The definition of each role is provided in the Role to permissions mapping table. For the steps required to add new users, see Managing users from the console.

Note that users can also be managed with APIs.

Ports

If you are using a client application to send requests to the console, either via the blockchain APIs or the Fabric SDKs, the standard HTTPS (443) port needs to be exposed in your firewall.

Key management

The IBM Blockchain Platform network is based on trusted identities. Customers use the Certificate Authorities (CAs) in the console to generate the identities and associated certificates that are required by all members to transact on the network. The generated public and private keys are ECDSA with Curve P256. These keys are stored in the browser when they are added to the member's blockchain wallet so that the console can use them to manage blockchain components. However, it is recommended that customers export these keys and import them into their own key management system in case they clear their browser cache or switch browsers. Customers are responsible for the storage, backup, and disaster recovery of all keys that they export.

Because these public and private key pairs are essential to how the IBM Blockchain Platform functions, key management is a critical aspect of security. If a private key is compromised or lost, hostile actors might be able to access your data and functionality. Although you use the IBM Blockchain Platform console to generate the certificates and private keys, they are not permanently stored by the browser or the cloud database. Public and private keys are temporarily stored in the browser and added to the member's wallet so that the console can use the private key to digitally sign transactions. Customers are ultimately responsible for exporting the keys and managing their storage, backup, and disaster recovery.

If a private key is lost and cannot be recovered, you will need to generate a new private key by registering and enrolling a new identity with your Certificate Authority. You should also then remove and replace your signCert in any components or organizations where you had used the lost or corrupted identity. See Updating an organization MSP definition for detailed steps.

In order to secure private keys in a production environment, the IBM Blockchain Platform includes the option to configure a Hardware Security Module (HSM) to generate and store the private keys for a node. An HSM is an optional hardware appliance that performs cryptographic operations and ensures that the cryptographic keys never leave the HSM. You are responsible for configuring an HSM device that implements the PKCS #11 standard. PKCS #11 is a cryptographic standard for secure operations, generation, and storage of keys. You will also need to configure a PKCS #11 proxy to communicate with your HSM. The platform supports ECDSA Sign and Verify cryptographic controls and EC Key generation. When an HSM is implemented for a node, the private key for the node is not stored in the browser wallet. Rather, the private key is accessed from the HSM via the proxy. When you register other node admin or client application identities with a CA by using the console, their private keys are not stored inside the HSM because they need the private key to transact on the network. For instructions on how to use HSM with the IBM Blockchain Platform, see Configuring a node to use a Hardware Security Module (HSM).

You also have the option to bring your own certificates from your own non-IBM Blockchain Platform CA when you create a peer node or ordering service. If you use your own certificates, you will need to manually build the peer or ordering service MSP definition file that includes those certificates and import the file into the console Organizations tab. See Using certificates from an external CA with your peer or ordering node for the steps required.

Membership Service Providers (MSPs)

Whereas Certificate Authorities generate the certificates that represent identities, turning these identities into roles in the IBM Blockchain Platform is done through the creation of Membership Service Providers (MSPs) in the console. These MSPs, which structurally are comprised of folders containing certificates, are used to represent organizations on the network. Every organization will have one and only one MSP and will always contain at least one admincert that identifies an administrator of the organization. When an MSP is associated with a peer, for example, it denotes that the peer belongs to that organization. Later on in the flow for creating a peer (or any node), this same administrator identity can be used to serve as the administrator of the peer as well. In order to perform some actions on a node, an administrator role is required. For example, to be able to install a smart contract on a peer, your public key must exist in the admincerts folder of the peer's organization MSP, which therefore makes you an administrator of the peer organization.

MSPs also identify the root CA that generated the certificates for the organization and any other roles beyond administrator that are associated with the organization (for example, members of a sub-organizational group), as well as setting the basis for defining access privileges in the context of a network and channel (e.g., channel admins, readers, writers).

MSP folders for organization members are based on a Fabric defined structure and are used by Fabric components. For more information about Fabric MSPs and their structure, see the Membership and Membership Service Provider Structure topics in the Hyperledger Fabric documentation. The Fabric CA establishes this structure by creating the following folders inside the MSP definition:

Note that organization MSPs are stored in browser storage and must be exported to a local file system and secured by the customer.

Access control lists (ACLs)

Hyperledger Fabric allows for finer grained control over user access to specified resources through the use of access control lists (ACLs). ACLs allow access to a channel resource to be restricted to an organization and a role within that organization. The available set of ACLs are from the underlying Fabric architecture and are selected during channel creation or update. Note that access control lists are restrictive, rather than additive. If access to a resource is specified to an organization, it means that only that organization will have access to the resource. For example, if the default access to a particular resource is the Readers of all organizations, and that access is changed to the Admin of Org1, then only the Admin of Org1 will have access to the resource. Because access to certain resources is fundamental to the smooth operation of a channel, it is highly recommended to make access control decisions carefully. If you decide to limit access to a resource, make sure that the access to that resource is added, as needed, for each organization.

You can use the blockchain console to select which ACLs to apply to resources on a channel. See this information under Creating a channel for instructions on how to configure access control for a channel.

API authentication

In order to use the blockchain APIs to create and manage network components, your application needs to be able to authenticate and connect to your network. See this topic on how to Connect to your console using API keys for more details.

Best practices for security on the customer Kubernetes cluster

Audience: Tasks in this section are typically performed by Kubernetes infrastructure managers.

The IBM Blockchain Platform console allows you to deploy and manage nodes on a Kubernetes cluster that you operate. The previous section addressed the security of the console. The following sections detail the best practices you can use to secure your Kubernetes cluster and the nodes of your network:

• Kubernetes cluster security
• Network security
• Cluster and Operating System (OS)
• Keys and cluster access information
• Membership Service Providers (MSPs)
• Storage
• Data privacy
• GDPR

Kubernetes cluster security

The best place to start is to learn about the security features of the underlying Kubernetes infrastructure. The open source documentation provides a review of recommended practices for securing a Kubernetes cluster.

For OpenShift Container Platform security considerations, you should review the Red Hat Container Security Guide Service. You will need to use security context constraints (SCCs) to define a set of conditions that a pod must run with in order to be accepted into the system. Details are included in the IBM Blockchain Platform deployment instructions.

If you are running on Azure Kubernetes Service, Amazon Elastic Kubernetes Service, or IBM Kubernetes Service, then you need to set up the NGINX Ingress controller and it needs to be running in SSL passthrough mode

Network security

The Kubernetes Container Platform provides the underlying network, including the networks and routers, over which the customer's VLAN resides. The customer needs to configure their servers and use gateways and firewalls to route traffic between servers to protect workloads from network threats. Protecting your cloud network by using firewalls and intrusion prevention system devices is imperative for protecting your cloud-based workloads.

Cluster and Operating System security

• Sensitive data: Cluster configuration data is stored in the etcd component of your Kubernetes master. Data in etcd is stored on the local disk of the Kubernetes master and is backed up to IBM Cloud Object Storage. Data is encrypted during transit to IBM Cloud Object Storage. If you are using OpenShift, you can choose to enable encryption for your etcd data on the local disk of your Kubernetes master by Encrypting Data at the datastore layer for your cluster.

• UBI Linux: The Fabric Docker images use Red Hat UBI images, which is a smaller, lighter, and more secure version of Linux.

Keys and cluster access information

Membership Service Providers (MSPs)

Organizations in a blockchain network are represented by MSP definitions. You can use the blockchain console to add a new organization to the network by creating a new MSP definition in the Organizations tab. If you are the admin of an ordering service, you can use the console to add that organization MSP to a consortium using the Ordering service tab. Finally, if you are an administrator of a channel, you can add that organization to an existing channel so the organization can transact on the network using the Channels tab (this task might require the signature of other organizations). See the topic on Join the consortium hosted by the ordering service for detailed steps.

Storage

When the blockchain console deploys a node, storage is dynamically provisioned from the default storageclass for that node from persistent storage. You have the option of encrypting the persistent volume but there may be some performance implications with encryption to consider.

Customers are responsible for encrypting their own storage and the encryption must occur before any blockchain components are deployed to the cluster.

• For more information on securing your persistent storage on OpenShift, see this topic on Volume Security.

Data privacy

When you have data privacy requirements, Private Data collections provide a way to further isolate specific data from the rest of the channel members. The combination of the use of channels and private data offer various solutions for achieving Data Residency.

GDPR

In order to be GDPR compliant, it is recommended that you store PII data off chain.

Hyperledger Fabric Security

Because IBM Blockchain Platform is based on Hyperledger Fabric, you can leverage the secure features included in a Fabric network.

• TLS v1.2 communications TLS is embedded in the trust model of Hyperledger Fabric. By default, server-side TLS is enabled for all communications using TLS certificates. TLS is used to encrypt the communication between your nodes and between your nodes and your applications. TLS prevents man-in-the-middle and session hijacking attacks. All IBM Blockchain Platform components use TLS to communicate with each other.

• Transaction integrity: Fabric uses the cryptographic ECDSA standard to guarantee transaction integrity. With ECDSA, the transaction originator, such as a client application, signs their message by using their private key, and the recipient, such as a peer, uses the originator’s public key to verify the authenticity of the message. If a transaction is tampered with on its way to the recipient, the signature verification fails.

• Channels: While Fabric channels are a powerful mechanism for partitioning and isolating data, they also provide the primary foundation for data privacy. Only members of the same channel can access the data of this channel. To ensure channel security, the channel configuration update policy is configured to define the number of channel operators who need to agree on the channel update request before a channel can be updated. Therefore, a clear process must exist for defining the organizations that are allowed to join and update channel.

• Ledger data: Implicit in the blockchain permissioned network is the notion that an agreed upon policy of multiple endorsers is required to sign (approve) a transaction before it can be committed to the ledger. Before any information can be added to the ledger, a clear and well-established process for defining the ledger information must exist. Data on the ledger is immutable.

• Smart contracts: All smart contracts should be reviewed by channel members before they are installed and executed on peers in their organization. Likewise, all updates to smart contract should be reviewed before the updates are applied to a peer. See this topic on Upgrading a smart contract for the steps that are required.

• HSM integration: After you have configured an HSM for your environment, you have the option of configuring your nodes to use the HSM to generate and store private keys. See Configuring a CA, peer, or ordering node to use the HSM for more information.

Enable network policy

Enable network policy will automatically install when the console is created. In the operator deployment specification, the operator needs to add an environment variable IBPOPERATOR_CONSOLE_APPLYNETWORKPOLICY and set its value to true.

kubectl edit deploy ibm-hlfsupport-operator -n <offering-namespace>

In the environment section under spec.containers, add the following:

- name: IBPOPERATOR_CONSOLE_APPLYNETWORKPOLICY
   value:"true"

When the above option is enabled, the operator will install 2 network policies during the console installation. These network policies are meant to give basic defensive security mechanism, and opens only the ports that the offering uses. This by no means is a policy that can replace a firewall. The policies applied provide ingress security, as blockchain network may require to call npm, gradle, maven servers to get chaincode modules as well as to communicate with the orderers/peers/applications running outside the cluster on internet we do not provide egress policies.

Following are the two policies that we apply:

1. Deny-all-ingress.

   This policy denies all ingress (ingress: []) network traffic to the pods (podSelector: {}) in the namespace it applies to. This ensure only the needed traffics go through.

   kind: NetworkPolicy
   apiVersion: networking.k8s.io/v1
   metadata:
     name: networkpolicy-denyall
     namespace: <>
     labels:
       type: "ibp-console"
       app.kubernetes.io/name: "ibp"
       app.kubernetes.io/instance: "ibp-console"
       app.kubernetes.io/managed-by: "ibp-operator"
       release: "operator"
       helm.sh/chart: "ibp"
   spec:
     podSelector: {}
     ingress: []
   

1. Ingress.

   This ingress network policy applies to network traffic coming from anywhere (from: []). It applies to all pods that labels app.kubernetes.io/name: "ibp" which are all the offering related pods. This policy only opens the ports that are required for the blockchain components and the available management console from outside for them to connect to each other.

   kind: NetworkPolicy
   apiVersion: networking.k8s.io/v1
   metadata:
     name: networkpolicy-ingress
     labels:
       type: "ibp-console"
       app.kubernetes.io/name: "ibp"
       app.kubernetes.io/instance: "ibp-console"
       app.kubernetes.io/managed-by: "ibp-operator"
       release: "operator"
       helm.sh/chart: "ibp"
   spec:
     ingress:
     - from: [] # everywhere
       ports:
       - port: 7051 # peer-api
         protocol: TCP
       - port: 9443 # peer-operations / ca-operations
         protocol: TCP
       - port: 7443 # peer-grpcweb / orderer-grpcweb
         protocol: TCP
       - port: 7052
         protocol: TCP # peer-chaincode
       - port: 3000 # optools
         protocol: TCP
       - port: 7050 # orderer-grpc
         protocol: TCP
       - port: 8443 # orderer-operations
         protocol: TCP
       - port: 22222 # fileserver #check install/invoke chaincode
         protocol: TCP
       - port: 11111 # grpc #check install/invoke chaincode
         protocol: TCP
       - port: 7054 # ca
         protocol: TCP
     podSelector:
       matchLabels:
         app.kubernetes.io/name: "ibp"
     policyTypes:
       - Ingress