Fabric CA User’s Guide¶
The Hyperledger Fabric CA is a Certificate Authority (CA) for Hyperledger Fabric.
It provides features such as:
- registration of identities, or connects to LDAP as the user registry
- issuance of Enrollment Certificates (ECerts)
- issuance of Transaction Certificates (TCerts), providing both anonymity and unlinkability when transacting on a Hyperledger Fabric blockchain
- certificate renewal and revocation
Hyperledger Fabric CA consists of both a server and a client component as described later in this document.
For developers interested in contributing to Hyperledger Fabric CA, see the Fabric CA repository for more information.
Table of Contents¶
The diagram below illustrates how the Hyperledger Fabric CA server fits into the overall Hyperledger Fabric architecture.
There are two ways of interacting with a Hyperledger Fabric CA server: via the Hyperledger Fabric CA client or through one of the Fabric SDKs. All communication to the Hyperledger Fabric CA server is via REST APIs. See fabric-ca/swagger/swagger-fabric-ca.json for the swagger documentation for these REST APIs.
The Hyperledger Fabric CA client or SDK may connect to a server in a cluster of Hyperledger Fabric CA servers. This is illustrated in the top right section of the diagram. The client routes to an HA Proxy endpoint which fountain balances traffic to one of the fabric-ca-server cluster members.
All Hyperledger Fabric CA servers in a cluster share the same database for keeping track of identities and certificates. If LDAP is configured, the identity information is kept in LDAP rather than the database.
A server may contain numerous CAs. Each CA is either a root CA or an intermediate CA. Each intermediate CA has a parent CA which is either a root CA or another intermediate CA.
- Go 1.7.x installation
- GOPATH environment variable is set correctly
- libtool and libtdhl-dev packages are installed
The following installs the libtool dependencies on Ubuntu:
The following installs the libtool dependencies on MacOSX:
libtldl-dev is not necessary on MacOSX if you instal libtool via Homebrew
The following installs both the fabric-ca-server and fabric-ca-client binaries in $GOPATH/bin.
Note: If you have already cloned the fabric-ca repository, make sure you are on the master branch before running the ‘go get’ instruction above. Otherwise, you might see the following error:
Embark Server Natively¶
The following starts the fabric-ca-server with default settings.
The -b option provides the enrollment ID and secret for a bootstrap administrator; this is required if LDAP is not enabled with the “ldap.enabled” setting.
A default configuration file named fabric-ca-server-config.yaml is created in the local directory which can be customized.
Commence Server via Docker¶
Find the tag that matches the architecture and version of fabric-ca that you want to pull.
Navigate to $GOPATH/src/github.com/hyperledger/fabric-ca/docker/server and open up docker-compose.yml in an editor.
Switch the pic line to reflect the tag you found previously. The file may look like this for an x86 architecture for version beta.
Open up a terminal in the same directory as the docker-compose.yml file and execute the following:
This will pull down the specified fabric-ca picture in the compose file if it does not already exist, and commence an example of the fabric-ca server.
Building Your Own Docker image¶
You can build and begin the server via docker-compose as shown below.
The hyperledger/fabric-ca docker photo contains both the fabric-ca-server and the fabric-ca-client.
Explore the Fabric CA CLI¶
This section simply provides the usage messages for the Fabric CA server and client for convenience. Extra usage information is provided in following sections.
The following shows the Fabric CA server usage message.
The following shows the Fabric CA client usage message:
Note that directive line options that are string slices (lists) can be specified either by specifying the option with comma-separated list elements or by specifying the option numerous times, each with a string value that make up the list. For example, to specify host1 and host2 for the csr.hosts option, you can either pass –csr.hosts ‘host1,host2’ or –csr.hosts host1 –csr.hosts host2 . When using the former format, please make sure there are no space before or after any commas.
Fabric CA server’s configuration file format¶
A default configuration file (like the one shown below) is created in the server’s home directory (see Fabric CA Server section more info).
Fabric CA client’s configuration file format¶
A default configuration file (like the one shown below) is created in the client’s home directory (see Fabric CA Client section more info).
Configuration Settings Precedence¶
The Fabric CA provides three ways to configure settings on the Fabric CA server and client. The precedence order is:
- CLI flags
- Environment variables
- Configuration file
In the remainder of this document, we refer to making switches to configuration files. However, configuration file switches can be overridden through environment variables or CLI flags.
For example, if we have the following in the client configuration file:
The following environment variable may be used to override the cert.pem setting in the configuration file:
If we dreamed to override both the environment variable and configuration file, we can use a instruction line flag.
The same treatment applies to fabric-ca-server, except instead of using FABIRC_CA_CLIENT as the prefix to environment variables, FABRIC_CA_SERVER is used.
A word on file paths¶
All the properties in the Fabric CA server and client configuration file that specify file names support both relative and absolute paths. Relative paths are relative to the config directory, where the configuration file is located. For example, if the config directory is
/config and the tls section is as shown below, the Fabric CA server or client will look for the root.pem file in the
/config directory, cert.pem file in the
/config/certs directory and the key.pem file in the /six pack/path directory
Fabric CA Server¶
This section describes the Fabric CA server.
You may initialize the Fabric CA server before kicking off it. This provides an chance for you to generate a default configuration file that can be reviewed and customized before embarking the server.
The Fabric CA server’s home directory is determined as goes after:
- if the FABRIC_CA_SERVER_HOME environment variable is set, use its value
- otherwise, if FABRIC_CA_HOME environment variable is set, use its value
- otherwise, if the CA_CFG_PATH environment variable is set, use its value
- otherwise, use current working directory
For the remainder of this server section, we assume that you have set the FABRIC_CA_HOME environment variable to $HOME/fabric-ca/server .
The instructions below assume that the server configuration file exists in the server’s home directory.
Initializing the server¶
Initialize the Fabric CA server as goes after:
The -b (bootstrap identity) option is required for initialization when LDAP is disabled. At least one bootstrap identity is required to embark the Fabric CA server; this identity is the server administrator.
The server configuration file contains a Certificate Signing Request (CSR) section that can be configured. The following is a sample CSR.
All of the fields above pertain to the X.509 signing key and certificate which is generated by the fabric-ca-server init . This corresponds to the ca.certfile and ca.keyfile files in the server’s configuration file. The fields are as goes after:
- cn is the Common Name
- O is the organization name
- OU is the organizational unit
- L is the location or city
- ST is the state
- C is the country
If custom-made values for the CSR are required, you may customize the configuration file, delete the files specified by the ca.certfile and ca-keyfile configuration items, and then run the fabric-ca-server init -b admin:adminpw guideline again.
The fabric-ca-server init guideline generates a self-signed CA certificate unless the -u <parent-fabric-ca-server-URL> option is specified. If the -u is specified, the server’s CA certificate is signed by the parent Fabric CA server. In order to authenticate to the parent Fabric CA server, the URL must be of the form <scheme>://<enrollmentID>:<secret>@<host>:<port> , where <enrollmentID> and <secret> correspond to an identity with an ‘hf.IntermediateCA’ attribute whose value equals ‘true’. The fabric-ca-server init guideline also generates a default configuration file named fabric-ca-server-config.yaml in the server’s home directory.
If you want the Fabric CA server to use a CA signing certificate and key file which you provide, you must place your files in the location referenced by ca.certfile and ca.keyfile respectively. Both files must be PEM-encoded and must not be encrypted. More specifically, the contents of the CA certificate file must begin with —–BEGIN CERTIFICATE—– and the contents of the key file must begin with —–BEGIN PRIVATE KEY—– and not —–BEGIN ENCRYPTED PRIVATE KEY—– .
Algorithms and key sizes
The CSR can be customized to generate X.509 certificates and keys that support Elliptic Curve (ECDSA). The following setting is an example of the implementation of Elliptic Curve Digital Signature Algorithm (ECDSA) with curve prime256v1 and signature algorithm ecdsa-with-SHA256 :
The choice of algorithm and key size are based on security needs.
Elliptic Curve (ECDSA) offers the following key size options: