Registering and enrolling identities with a CA¶

Decide on the structure of your folders and certificates¶

Whether you are running in a test or production environment, it is critically important that you maintain a consistent and coherent structure for managing your folders and certificates. While it is not a strict Fabric necessity to use the same patterns everywhere (as long as your paths are correct whenever you reference them, for example when bootstrapping a node, Fabric can consume them), certificate pathing errors are among the most common errors faced by Fabric users. Forethought and consistency can dramatically reduce these issues.

Note that production deployments might include structures we won’t show here. For example, it might include a folder for gateways, allowing an admin to easily see which organizations and nodes and clients are associated with each network. Similarly, you might see a smart contracts folder containing the smart contracts associated with a network.

The method for organizing your folders and certificates we describe here is not mandatory, but you will find it helpful, as it is consistent with the rest of this topic as well as with the CA deployment guide. Most importantly, it organizes your structures around the organization that owns and manages them. While it might be natural to think of your deployments as being organized around physical structures like peers and ordering nodes, it is actually the organization that is the centralizing figure. Especially since not all network participants will necessarily own a node.

The structures and methods presented here also represent best practices, preventing cases where, for example, Fabric expects an MSP folder to be called msp and, if a different name is used, the name of the folder will have to be changed in the relevant YAML file.

NodeOUs¶

In previous versions of Fabric, identities only had two types: client and peer. The peer type was used for both peers and ordering nodes, while the client type was used for both clients (applications) and admins, with the placement of a client type in a special admincerts folder making the identity an admin within a particular context.

Now it is possible, and recommended, to encode not just peer or client, but also orderer or admin roles into the certificates generated by a CA using NodeOUs. This embeds the role an identity has within the certificate.

Note that an identity can only have one of these roles, and that to enable these roles you must copy the relevant stanzas into a file called config.yaml. This config.yaml file is used by Fabric in different ways. In a channel MSP, it is used to verify that the admin of an organization has a role of admin (this replaces the use of an admincerts folder which was used in older versions of Fabric). In the local MSP of a node, it is used to verify the admin role of the node admin and the peer or orderer role of the node itself.

Note that you can name this msp folder anything you want — msp is the default folder name used by the Fabric CA client. If you choose another name, for example, org1msp, then you will have to reference this folder using the --mspdir flag when enrolling the identity. Programmatically, you can use a command similar to this to copy config.yaml to the correct msp folder for the identity you’ve enrolled.

echo 'NodeOUs:
 Enable: true
 ClientOUIdentifier:
   Certificate: cacerts/localhost-7054-ca-org1.pem
   OrganizationalUnitIdentifier: client
 PeerOUIdentifier:
   Certificate: cacerts/localhost-7054-ca-org1.pem
   OrganizationalUnitIdentifier: peer
 AdminOUIdentifier:
   Certificate: cacerts/localhost-7054-ca-org1.pem
   OrganizationalUnitIdentifier: admin
 OrdererOUIdentifier:
   Certificate: cacerts/localhost-7054-ca-org1.pem
   OrganizationalUnitIdentifier: orderer' > path to msp>/msp/config.yaml

Or you can manually copy the Node OU material into the config.yaml file for the msp folder:

NodeOUs:
  Enable: true
  ClientOUIdentifier:
    Certificate: cacerts/<root CA cert for this org>.pem
    OrganizationalUnitIdentifier: client
  PeerOUIdentifier:
    Certificate: cacerts/<root CA cert for this org>.pem
    OrganizationalUnitIdentifier: peer
  AdminOUIdentifier:
    Certificate: cacerts/<root CA cert for this org>.pem
    OrganizationalUnitIdentifier: admin
  OrdererOUIdentifier:
    Certificate: cacerts/<root CA cert for this org>.pem
    OrganizationalUnitIdentifier: orderer

In a production scenario, it is assumed that users will be creating only one organization. However, it is a good practice to establish a separate folder structure for this organization and then create a structure underneath this organization for your msp (defining the organization) and your nodes (which will have a local MSP and TLS sections).

If you are creating an orderer, you obviously do not need to copy the PeerOUIdentifier into your config.yaml file (or vice versa), but for the sake of simplicity you might want to use the entire section — extra stanzas do no harm, and they allow the same config.yaml to be used for multiple types of nodes and identities associated with an organization.

Create the org MSP needed to add an org to a channel¶

The organizations in a Fabric network don’t exist in a physical sense the way nodes do. Rather, they exist as a structure of folders and certificates on the configuration of a channel. These certificates identify the relevant root CA, intermediate CA (if one was used), TLS CA, and at least one admin identity. As you recall from the membership topic and the registration and enrollment steps above, these folders and certificates are returned by the Fabric CA client when enrolling an admin identity, which is why the act of enrolling an admin and the act of “creating an organization” are closely related.

Here is a sample of the folder structure you need to create when you want to add an organization to a channel (the structure might vary slightly depending on the method you use to add an organization to a channel, but whatever the method, these are the files and folders you will need):

<location of msp>/msp
├── config.yaml
├── cacerts
│   └── cacert.crt
├── intermediatecerts
|   └── cacert.crt
├── tlscacerts
│   └── tlsca.<org-domain>.pem
└── tlsintermediatecerts
    └── tlsca.<org-domain>.pem

Where the folders and certificates are:

• cacerts: the root certificate (ca-cert.pem) of the organization CA where the identity of the admin was registered and enrolled.
• intermediatecerts: the root certificate of an intermediate CA, if one was used.
• tlscacerts: the root certificate (ca-cert.pem) of the TLS CA that has issued certificates to the nodes associated with this organization.
• tlsintermediatecerts: the root certificate of the intermediate TLS CA, if one was used.

Note that while the certificates themselves can be named anything you want, you should not change the name of the folders themselves, as Fabric expects to consume folders with certain names.

See NodeOUs for instructions on how to generate the config.yaml file for this organization. In older versions of Fabric, the config.yaml file would not have been here and an additional folder, admincerts, would be needed, in which certificates identifying the admin of this organization would be placed. This is no longer necessary thanks to Node OUs. Any identity given a Node OU of admin by the CA listed in config.yaml can administer the organization.

Create the local MSP of a node¶

While the MSP of an organization serves as the representation of the organization on a channel configuration, the local MSP of a node is a logical collection of parameters that is used, along with other parameters, as part of the creation of a node.

As has been noted above, nodes must be bootstrapped both with enrollment certificates (the public/private key pair that identifies a node) and the TLS certificates that encrypt the communication layer between nodes. This “bootstrapping” happens by listing the location of these certificates in the relevant YAML configuration file that is referenced when creating the node. This means that the local MSP of a node must be created before the node itself can be created. Note that the enrollment certificates for the node are specified by listing the location of the MSP that contains them, while TLS certificates are identified through the absolute path to the location of each certificate.

For reference, here is a sample peer configuration file.

And here is a sample ordering node configuration file.

Note that these configuration files ask for the location of the relevant local MSP folder. For the peer, this is defined through the mspConfigPath. For the orderer, it is the LocalMSPDir. The folders found in this location will be used to define the local MSP of the node, including the private key the node will use when signing its actions as well as the public key of at least one admin of the node.

The TLS certificates, on the other hand, are defined individually, rather than pointing to a folder, and can be found in the TLS settings section of the YAML. This means that TLS certificates do not need to be kept in a strict folder structure like the local MSP (relevant in particular to users who will be using an external CA to generate TLS certificates — use the sample YAML files as a guide to what these certificates are used for). When you enroll a node with the TLS CA, the generated TLS public key can be found in the /signcerts folder and the TLS private key can be found in the /keystore folder. When you stand up a node that is enabled for TLS, you need to point to these files from the relevant fields in the YAML config file.

As with all of the configuration parameters in the YAML file of a node, you have the option to specify the msp folder and TLS certificate locations either in the YAML itself or through the use of environment variables.

If you are using a containerized solution for running your network (which for obvious reasons is a popular choice), it is a best practice to mount these folders (volumes) external to the container where the node itself is running. This will allow the certificates to be used to create a new node should the node container go down, become corrupted, or is restarted.

For a look at a sample local MSP, check out MSP structure. Note that you will not receive all of these certificates back simply by enrolling a peer identity. You will need, for example, to create the users subfolder and put the public certificate of the identity that will be administering the node in the folder prior to bootstrapping. You will also need an operations certificate (depending on the configuration of your network, this might come from a separate operations CA). For more information about the operations service, check out The Operations Service.

Here is a sample local MSP as it might look when the node has been enrolled and the additional fields have been added:

localmsp
  └── config.yaml
  └── cacerts
      └── <root CA public cert>.pem
  └── intermediatecerts
      └── <intermediate CA public cert>.pem
  └── keystore
      └── <node private cert>.pem
  └── signcerts
      └── <node public cert>.pem
  └── tlscacerts
      └── tlsca.<org-domain>.pem
  └── tlsintermediatecerts
      └── tlsca.<org-domain>.pem
  └── operationscerts
      └── operationcert.pem

Where the folders and certificates are:

• cacerts: the root cert of the organization CA where the identity of the admin was registered and enrolled.
• intermediatecerts: the root cert of an intermediate CA, if one was used.
• keystore: the private key of the node. This is the key the node uses to sign its communications.
• signcerts: the public key of the node. This certificate is presented to nodes making incoming communications, allowing the node initiating a communication to know that it is talking to the correct node.
• tlscacerts: the root cert of the TLS CA that has issued certificates to the CAs or nodes associated with this organization.
• tlsintermediatecerts: the root cert of the intermediate TLS CA, if one was used.
• operationscerts: the certificate needed for interaction with the operations service.

Note that while the certificates themselves can be named anything you want, you should not change the name of the folders themselves, as Fabric expects to consume folders with certain names.

Just as Node OUs make it no longer necessary to include a certificate of an admin in the organization MSP, it is not necessary to include the public certificate of a node admin to administer the node. Any identity given a Node OU of admin by the CA listed in config.yaml can administer any of the nodes owned by that organization without needing to place the public certificate of that admin in the organization MSP or the local MSP.