Using certificates from an external Certificate Authority

In this tutorial, you learn how to use certificates that were generated by an external Certificate Authority (CA) with your IBM® Blockchain Platform network. After you gather the required certificates for a peer or ordering node, you build a Membership Service Provider (MSP) definition that is used by your blockchain components.

While it is always possible to use a CA that you create with the console to generate identities, you can also use certificates that were generated by a CA external to your network, one that is not hosted by IBM, and then build the required organization Membership Service Provider (MSP) definition that is used by your blockchain components.

Objectives

Gather certificates.
Build MSP definition.
Import MSP into the console.
Create and import the organization admin identity to the wallet.
Deploy a blockchain node.

Before you begin

Install the IBM® Blockchain Platform.
This tutorial requires use of the IBM Blockchain Platform console. Therefore, after you deploy the platform, ensure that you can successfully log in to the console.

Gather certificates

You need to request the following set of certificates from the external CA in X.509 format. When you request the certificates from your provider, the core requirement for the certificates is that they are ECDSA with Curve P256 and that the private key uses the PKCS #8 standard. Also when you request the certificates, you need to specify a Node Organizational Unit (OU) attribute for some certificates as indicated in the Node OU column in the following tables. Certificates can be in the format of a .pem file or a base64 encoded string.

When you create a peer or ordering node, you need to provide the following four certificates in PEM format. When you request these certificates from the third-party CA, you need to request a specific Node Organizational Unit (OU) attribute for some certificates as indicated in the Node OU column.

Table 1. Node certificates
Node certificates	Description	Node OU	Format
1. Peer or ordering node identity certificate	The public certificate of the node’s identity.	"peer" or "orderer" depending on the node type	PEM
2. Peer or ordering node identity private key	The private key corresponding to the public signing certificate. Make sure to keep this certificate safe, as it can be used to impersonate the node.		PEM
3. Peer or ordering service TLS CA certificate	The public signing certificate created by your external TLS CA that is used by the peer or ordering node. The certificate needs to contain the x.509 Subject alternative name (SAN) for the peer or ordering nodes. If you are using the Fabric CA client to enroll the identity, you specify the SAN by passing the `--csr.hosts` parameter on the `enroll` command. If the hostname is not yet known, you can specify a wildcard with the domain name, for example: `--csr.hosts '*.ibpv2-cluster.us-south.containers.appdomain.cloud,127.0.0.1'`.		PEM
4.Peer or ordering service TLS CA private key	The private key corresponding to the signed certificate from your TLS CA that is used by the peer or ordering node for secure communications with other members on the network.		PEM

Table 2. MSP certificates
MSP certificates	Description	Node OU	Format
1. CA root certificate	The root certificate of your external CA. You can also provide an intermediate CA root certificate or both.		base64
2. TLS CA root certificate	The root certificate of your external TLS CA. You must provide either a TLS CA root certificate or an intermediate TLS CA certificate, you can also provide both.		base64
3. Intermediate CA root certificate: (Optional)	The root certificate of your intermediate CA. You must provide either a CA root certificate or an intermediate CA root certificate, you can also provide both.		base64
4. Intermediate CA TLS certificate: (Optional)	The TLS certificate if your TLS certificate is issued by an intermediate TLS CA. Upload the intermediate TLS CA certificate. You must provide either a TLS CA root certificate or an intermediate TLS CA certificate, you may also provide both.		base64
5. Peer or ordering organization admin identity certificate	The signing certificate from your external CA that the admin identity of this peer or ordering service uses.	"admin"	base64
6. Peer or ordering organization admin identity private key	The private key corresponding to the signed certificate from your external CA that the admin identity of this peer or ordering service uses.		base64

Consideration when using an external CA to generate certificates

If a generated private key is in PKCS #1 format, before it can be used by the console, it needs to be converted to PKCS #8 format by running the following openssl command:

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in identity.1.pem -out identity.8.pem

Replace:

identity.1.pem with the name of the PKCS #1 private key .PEM file.
identity.8.pem with the name that you want to give your PKCS #8 private key .PEM file.

Build MSP definition

An MSP definition is the mechanism that allows other members of the blockchain consortium to verify the identity of your nodes and applications. Because MSPs define an organization, they are required when you create channels, create nodes (to identify which organization the node belongs to), and validate signatures.

The MSP definition requires that all certificates are encoded in base64 format. If needed, you can convert the contents of a certificate file, <cert.pem> from PEM format into a base64 string by running the following command on your local machine:

export FLAG=$(if [ "$(uname -s)" == "Linux" ]; then echo "-w 0"; else echo "-b 0"; fi)
cat <cert.pem> | base64 $FLAG

To build the MSP definition, create a JSON by copying the following text and saving it to a file of type JSON:

{
   "name": "<organization_name>",
   "display_name": "<organization_name>",
   "msp_id": "<organization_id>",
   "type": "msp",
   "admins": [
       "<admins>"
   ],
   "root_certs": [
       "<root_certs>"
   ],
   "tls_root_certs": [
       "<tls_root_certs>"
   ],
   "fabric_node_ous": {
       "enable": true,
       "admin_ou_identifier": {
           "certificate": "<ou_root_cert>",
           "organizational_unit_identifier": "admin"
       },
       "client_ou_identifier": {
           "certificate": "<ou_root_cert>",
           "organizational_unit_identifier": "client"
       },
       "orderer_ou_identifier": {
           "certificate": "<ou_root_cert>",
           "organizational_unit_identifier": "orderer"
       },
       "peer_ou_identifier": {
           "certificate": "<ou_root_cert>",
           "organizational_unit_identifier": "peer"
       }
   },
   "host_url": "<url>",
}

Replace the following values:

organization_name: Specify any name to be used to identify this MSP definition in the console.
organization_id: Specify an ID that is used to represent this MSP internally in the console.
root_certs: Paste in an array that contains one or more root certificates from the external CA in base64 format. You must provide either a CA root certificate or an intermediate CA certificate. You can also provide both. This is certificates 1 and 3 in the MSP certificates table.
admins: Paste in the signing certificate of the organization admin identity in base64 format. This is certificate 5 in the MSP certificates table.
tls_root_certs: Paste in an array that contains one or more root certificates from the TLS CA in base64 format. You must provide either an external TLS CA root certificate or an external intermediate TLS CA certificate, you can also provide both. This is certificate 2 in the MSP certificates table.
ou_root_cert: Specify the trusted CA root certificate for each role. Typically this value would be the same as the root_certs. This is certificate 1 in the MSP certificates table.
host_url: Specify the URL of the blockchain console where this MSP collects signatures. This is the URL from your browser minus /nodes. For example, from the Nodes tab, the browser URL is similar to https://d0ddb7-optools.uss02.blockchain.cloud.ibm.com/nodes. Therefore the host_url would be https://d0ddb7-optools.uss02.blockchain.cloud.ibm.com.
fabric_node_OUs: Fabric-specific Organization Units (OUs) that enable identity classification. NodeOUs contain information for how to distinguish clients, peers, and orderers based on their OU. If the check is enforced, by setting Enabled to true, the MSP considers an identity valid only if it is an identity of type client, a peer, an admin, or an orderer. An identity should have only one of these special OUs, which are assigned to an identity when it is registered with the CA. See this topic for an example of how to specify the fabric_node_OU in an MSP in the Fabric Service Discovery documentation. Or learn more about using Node OUs in Fabric.

The following additional fields are also available in your MSP definition but are not required:

intermediate_certs: (if an intermediate CA was used) Paste in an array that contains one or more certificates from the external intermediate CA in base64 format. You must provide either a CA root certificate or an intermediate CA certificate, you can also provide both.
tls_intermediate_certs: (if an intermediate TLS CA was used) Paste in an array that contains one or more certificates from the intermediate TLS CA in base64 format. You must provide either an external TLS CA root certificate or an external intermediate TLS CA certificate, you can also provide both.
organizational_unit_identifiers: A list of Organizational Units (OU) that valid members of this MSP should include in their X.509 certificate. This is an optional configuration parameter that is used when multiple organizations leverage the same root of trust and intermediate CAs, and they have reserved an OU field for their members. An organization is often divided up into multiple organizational units (OUs), each of which has a certain set of responsibilities. For example, the ORG1 organization might have both ORG1-MANUFACTURING and ORG1-DISTRIBUTION OUs to reflect these separate lines of business. When a CA issues X.509 certificates, the OU field in the certificate specifies the line of business to which the identity belongs. See this topic in the Fabric documentation on Identity Classification for more information.
revocation_list: A list of certificates that are no longer valid. For X.509-based identities, these identifiers are pairs of strings that are known as Subject Key Identifier (SKI) and Authority Key Identifier (AKI), and are checked whenever the X.509 certificate is being used to make sure that the certificate has not been revoked. See this topic in the Fabric documentation for more information about Certificate Revocation Lists.

This is an example MSP JSON file:

{
   "name": "org1msp",
   "display_name": "org1msp",
   "msp_id": "org1msp",
   "type": "msp",
   "admins": [
       "LS0tLS1CRUd...LS0tLQo="
   ],
   "root_certs": [
       "LS0tLS1CRUd...LS0tLS0K"
   ],
   "intermediate_certs": [],
   "tls_root_certs": [
       "LS0tLS1CRUd...LS0y=g"
   ],
   "tls_intermediate_certs": [],
   "fabric_node_ous": {
       "admin_ou_identifier": {
           "certificate": "LS0tLS1CRUd...LS0tLS0K",
           "organizational_unit_identifier": "admin"
       },
       "client_ou_identifier": {
           "certificate": "LS0tLS1CRUd...LS0tLS0K",
           "organizational_unit_identifier": "client"
       },
       "enable": true,
       "orderer_ou_identifier": {
           "certificate": "LS0tLS1CRUd...LS0tLS0K",
           "organizational_unit_identifier": "orderer"
       },
       "peer_ou_identifier": {
           "certificate": "LS0tLS1CRUd...LS0tLS0K",
           "organizational_unit_identifier": "peer"
       }
   },
   "host_url": "https://ibpconsole-console.0defdaa0c51eab4bf04a1-0000.us-south.containers.appdomain.cloud:443",
}

Import MSP into the console

You have gathered your certificates and built your MSP. Before you can deploy a peer or ordering node, you need to import the MSP JSON file into your IBM Blockchain Platform console.

Navigate to the Organizations tab and click Import MSP.
Browse to the MSP JSON file and click Add file.
Click Import MSP.

Create and import the organization admin identity to the wallet

To be able to act as an administrator for an organization, import the identity that is listed in the MSP JSON "admins" section into your console wallet, including both the public and private key. When you subsequently deploy a peer or ordering node, you can designate this identity to be the node admin.

To import the identity, open the Wallet tab and click Add identity.
Give the identity a name.
Click Add certificate and browse to the .pem files for the organization admin identity certificate and private key.

Deploy a blockchain node

You've gathered all the certificates, created and imported the MSP, and imported the organization admin identity, you are now ready to deploy a peer or ordering node. The process to deploy a peer and ordering node is slightly different:

Deploy peer

From the Nodes tab, click Add peer > Create peer.
Provide a name for your peer.
Under Advanced deployment options, check Use your own CA certificate and private key and click Next.
In the Certificate field, click Add certificate and browse to the peer enrollment certificate .pem file. This is certificate 1 in the Node certificates table.
In the Private key field, click Add certificate and browse to the peer enrollment private key .pem file. This is certificate 2 in the Node certificates table.
In the MSP drop-down list, select the MSP that you imported into the console.
Select a Fabric version for your peer and click Next.
Provide the TLS certificate and key for the node. In the Certificate field, click Add certificate and browse to the peer TLS certificate .pem file. This is certificate 3 in the Node certificates table.
In the Private key field, click Add certificate and browse to the peer TLS private key .pem file. This is certificate 4 in the Node certificates table. Click Next.
From the Peer administrator identity drop-down list, select the organization admin identity that you imported into the wallet.
Review the details on the Summary panel and click Add peer.

Deploy ordering service

From the Nodes tab, click Add ordering service > Create ordering service.
Provide a name for your ordering service and select the number of ordering nodes that you want to deploy.
Under Advanced deployment options, check Use your own CA certificate and private key and click Next.
In the Certificate field, click Add certificate and browse to the peer enrollment certificate .pem file. This is certificate 1 in the Node certificates table.
In the Private key field, click Add certificate and browse to the peer enrollment private key .pem file. This is certificate 2 in the Node certificates table.
In the MSP drop-down list, select the MSP that you imported into the console.
Select a Fabric version for your peer and click Next.
Provide the TLS certificate and key for the node. In the Certificate field, click Add certificate and browse to the peer TLS certificate .pem file. This is certificate 3 in the Node certificates table.
In the Private key field, click Add certificate and browse to the peer TLS private key .pem file. This is certificate 4 in the Node certificates table. Click Next.
From the Orderer administrator identity drop-down list, select the organization admin identity that you imported into the wallet.
Review the details on the Summary panel and click Add ordering service.

Instead of creating an ordering service, if you prefer to contribute a single ordering node to an existing Raft ordering service, open the ordering service and click the Ordering nodes tab. Click Add ordering node, give it a name then and following the preceding steps.

It takes several minutes for peer and ordering node deployment to complete. When it is successful, you can see a green box on the node tile in the console. You might need to refresh your browser for the box to turn from gray to green.

Next steps

Your blockchain nodes are ready to be used on the network. In order for the peer to participate on the network, the peer organization needs to be part of a consortium on an ordering service so that the peer can join a channel.

Navigate to the Nodes tab.
Scroll down to the ordering service and click the tile to open it.
Under Consortium Members, click Add organization.
From the drop-down list, select the MSP that you imported into the console.
Click Add organization.

You can now install smart contracts on your peer and join it to an existing channel.