diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 05a3c6f86..dd65a3838 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributions Welcome! This repository is part of the Fabric project. -Please consult [Fabric's CONTRIBUTING documentation](https://github.com/hyperledger/fabric/blob/master/CONTRIBUTING.md) for information on how to contribute to this repository. +Please consult [Fabric's CONTRIBUTING documentation](https://github.com/hyperledger/fabric/blob/main/CONTRIBUTING.md) for information on how to contribute to this repository. Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License. diff --git a/docs/source/conf.py b/docs/source/conf.py index 1f2682f1d..f264749b2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,7 +14,8 @@ import sphinx_rtd_theme placeholder_replacements = { - "{BRANCH}": "main" + "{BRANCH}": "main", + "{FABRIC_VERSION}": "release-2.5" } # -- Project information ----------------------------------------------------- @@ -41,7 +42,7 @@ # '.md': 'recommonmark.parser.CommonMarkParser', # } -# The file extensions of source files. Sphinx considers the files with this suffix as sources. +# The file extensions of source files. Sphinx considers the files with this suffix as sources. # The value can be a dictionary mapping file extensions to file types. For example: source_suffix = { '.rst': 'restructuredtext', @@ -108,4 +109,4 @@ def setup(app): # -- MyST-specific Options ------------------------------------------------- # https://myst-parser.readthedocs.io/en/latest/configuration.html#sphinx-config-options -myst_all_links_external = True \ No newline at end of file +myst_all_links_external = True diff --git a/docs/source/deployguide/ca-config.md b/docs/source/deployguide/ca-config.md index 91754f38e..8c414c9df 100644 --- a/docs/source/deployguide/ca-config.md +++ b/docs/source/deployguide/ca-config.md @@ -1,4 +1,4 @@ -# Checklist for a production CA server +# Checklist for a production CA server As you prepare to build a production Fabric CA server, you need to consider configuration of the following fields in the fabric-ca-server-config.yaml file. When you [initialize](../users-guide.html#initializing-the-server) the CA server, this file is generated for you so that you can customize it before actually starting the server. @@ -81,6 +81,7 @@ As mentioned in the topic on [Planning for a CA](ca-deploy-topology.html), the ` If this is not a desired configuration for your CA, you can leave the value of this parameter blank. ## intermediate CA + ``` intermediate: parentserver: @@ -101,7 +102,7 @@ intermediate: Intermediate CAs are not required, but to reduce the risk of your organization (root) CA becoming compromised, you may want to include one or more intermediate CAs in your network. -**Important:** Before setting up an intermediate CA, you need to verify the value of the `csr.ca.pathlength` parameter in the parent CA. When set to `0`, the organization CA can issue intermediate CA certificates, but these intermediate CAs may not in turn enroll other intermediate CAs. If you want your intermediate CA to be able to enroll other intermediate CAs, the root ca `csr.ca.pathlength` needs to be set to `1`. And if you want those intermediate CAs to enroll other intermediate CAs, the root ca `csr.ca.pathlength` would need to be set to `2`. +**Important:** Before setting up an intermediate CA, you need to verify the value of the `csr.ca.pathlength` parameter in the parent CA. When set to `0`, the organization CA can issue intermediate CA certificates, but these intermediate CAs may not in turn enroll other intermediate CAs. If you want your intermediate CA to be able to enroll other intermediate CAs, the root ca `csr.ca.pathlength` needs to be set to `1`. And if you want those intermediate CAs to enroll other intermediate CAs, the root ca `csr.ca.pathlength` would need to be set to `2`. - **`parentserver.url`**: Specify the parent server url in the format `https://:@:`. - **`parentserver.caname`**: Enter `ca.name` of the parent CA server. @@ -109,11 +110,13 @@ Intermediate CAs are not required, but to reduce the risk of your organization ( - **`tls.certfiles`**: Enter the location and name of the TLS CA signing cert, `ca-cert.pem` file. For example, `tls/ca-cert.pem`. This location is relative to where the server configuration .yaml file exists. In addition to editing this `intermediate` section, you also need to edit the following sections of the configuration .yaml file for this intermediate CA: + - `csr` - Ensure that the `csr.cn` field is blank. - `port` - Be sure to set a unique port for the intermediate CA. - `signing` - Verify that `isca` set to `true`, and `maxpathlen` is set to greater than `0` in the root CA only if the intermediate CA will serve as a parent CA to other intermediate CAs, otherwise it should be set to `0`. See the [signing](#signing) parameter. ## port + ``` port: ``` @@ -121,6 +124,7 @@ port: Each CA must be running on its own unique port and obviously must not conflict with any other service running on that port. You need to decide what ports you want to use for your CAs ahead of time and configure that port in the .yaml file. ## user registry + ``` registry: # Maximum number of times a password/secret can be reused for enrollment @@ -142,19 +146,21 @@ registry: hf.Registrar.Attributes: "*" hf.AffiliationMgr: true ``` + If you are not using an LDAP user registry, then this section along with the associated registry database `db:` section are required. This section can be used to register a list of users with the CA when the server is started. Note that it simply registers the users and does not generate enrollment certificates for them. You use the Fabric CA client to generate the associated enrollment certificates. -* `maxenrollments`: Used to restrict the number of times certificates can be generated for a user using the enroll ID and secret. The [reenroll](../users-guide.html#reenrolling-an-identity) command can be used to get certificates without any limitation. -* `identities`: This section defines the list of users and their associated attributes to be registered when the CA is started. After you run the `fabric-ca-server init` command, the `<<>>` and `<<>>` here are replaced with the CA server bootstrap identity user and password specified with the `-b` option on the command. -* `identities.type`: For Fabric, the list of valid types is `client`, `peer`, `admin`, `orderer`, and `member`. -* `affiliation`: Select the affiliation to be associated with the user specified by the associated `name:` parameter. The list of possible affiliations is defined in the `affiliations:` section. -* `attrs`: The list of roles included above would be for "admin" users, meaning they can register and enroll other users. If you are registering a non-admin user, you would not give them these permissions. The `hf` attributes associated with an identity affect that identity's ability to register other users. You should review the topic on [Registering a new identity](../users-guide.html#registering-a-new-identity) to understand the patterns that are required. +- `maxenrollments`: Used to restrict the number of times certificates can be generated for a user using the enroll ID and secret. The [reenroll](../users-guide.html#reenrolling-an-identity) command can be used to get certificates without any limitation. +- `identities`: This section defines the list of users and their associated attributes to be registered when the CA is started. After you run the `fabric-ca-server init` command, the `<<>>` and `<<>>` here are replaced with the CA server bootstrap identity user and password specified with the `-b` option on the command. +- `identities.type`: For Fabric, the list of valid types is `client`, `peer`, `admin`, `orderer`, and `member`. +- `affiliation`: Select the affiliation to be associated with the user specified by the associated `name:` parameter. The list of possible affiliations is defined in the `affiliations:` section. +- `attrs`: The list of roles included above would be for "admin" users, meaning they can register and enroll other users. If you are registering a non-admin user, you would not give them these permissions. The `hf` attributes associated with an identity affect that identity's ability to register other users. You should review the topic on [Registering a new identity](../users-guide.html#registering-a-new-identity) to understand the patterns that are required. When the user is subsequently "enrolled", the `type`, `affiliation`, and `attrs` are visible inside the user's signing certificate and are used by policies to enforce authorization. Recall that `enrollment` is a process whereby the Fabric CA issues a certificate key-pair, comprised of a signed cert and a private key that forms the identity. The private and public keys are first generated locally by the Fabric CA client, and the public key is then sent to the CA which returns an encoded certificate, the signing certificate. After a user has been registered, you can use the [`Identity`](../clientcli.html#identity-command) command to modify the properties of the user. ## registry database + ``` db: type: sqlite3 @@ -178,6 +184,7 @@ If you are running the database in a cluster, you must choose `postgres` or `mys If LDAP is being used as the user registry (designated by `ldap.enabled:true`), then this section is ignored. ## LDAP + ``` ldap: # Enables or disables the LDAP client (default: false) @@ -231,11 +238,12 @@ ldap: groups: - name: value: -``` +``` If an LDAP registry is configured, all settings in the [registry](#user-registry) section are ignored. ## affiliations + ``` affiliations: org1: @@ -243,11 +251,11 @@ affiliations: - department2 org2: - department1 -``` +``` -Affiliations are useful to designate sub-departments for organizations. They can then be referenced from a policy definition, for example when you might want to have transactions endorsed by a peer who is not simply a member of ORG1, but is a member of ORG1.MANUFACTURING. Note that the affiliation of the registrar must be equal to or a prefix of the affiliation of the identity being registered. If you are considering using affiliations you should review the topic on [Registering a new identity](../users-guide.html#registering-a-new-identity) for requirements. To learn more about how affiliations are used in an MSP, see the MSP Key concept topic on [Organizational Units (OUs) and MSPs](https://hyperledger-fabric.readthedocs.io/en/release-2.1/membership/membership.html#organizational-units-ous-and-msps). +Affiliations are useful to designate sub-departments for organizations. They can then be referenced from a policy definition, for example when you might want to have transactions endorsed by a peer who is not simply a member of ORG1, but is a member of ORG1.MANUFACTURING. Note that the affiliation of the registrar must be equal to or a prefix of the affiliation of the identity being registered. If you are considering using affiliations you should review the topic on [Registering a new identity](../users-guide.html#registering-a-new-identity) for requirements. To learn more about how affiliations are used in an MSP, see the MSP Key concept topic on [Organizational Units (OUs) and MSPs](https://hyperledger-fabric.readthedocs.io/en/{FABRIC_VERSION}/membership/membership.html#organizational-units-ous-and-msps). -The default affiliations listed above are added to the Fabric CA database the first time the server is started. If you prefer not to have these affiliations on your server, you need to edit this config file and remove or replace them _before_ you start the server for the first time. Otherwise, you must use the Fabric CA client [Affiliation command](../clientcli.html#affiliation-command) to modify the list of affiliations. By default, affiliations cannot be removed from the configuration, rather that feature has to be explicitly enabled. See the [cfg](#cfg) section for instructions on configuring the ability to allow removal of affiliations. +The default affiliations listed above are added to the Fabric CA database the first time the server is started. If you prefer not to have these affiliations on your server, you need to edit this config file and remove or replace them _before_ you start the server for the first time. Otherwise, you must use the Fabric CA client [Affiliation command](../clientcli.html#affiliation-command) to modify the list of affiliations. By default, affiliations cannot be removed from the configuration, rather that feature has to be explicitly enabled. See the [cfg](#cfg) section for instructions on configuring the ability to allow removal of affiliations. ## csr (certificate signing request) @@ -270,6 +278,7 @@ csr: expiry: 131400h pathlength: <<>> ``` + The CSR section controls the creation of the root CA certificate. Therefore, if you want to customize any values, it is recommended to configure this section before you start your server for the first time. The values you specify here will be included in the signing certificates that are generated. If you customize values for the CSR after you start the server, you need to delete the `ca.cert` file and `ca.key` files and then run the `fabric-ca-server start` command again. - **csr.cn**: This field must be set to the ID of the CA bootstrap identity and can be left blank. It defaults to the CA server bootstrap identity. @@ -307,7 +316,7 @@ signing: expiry: 8760h ``` -The defaults in this section are normally sufficient for a production server. However, you might want to modify the default expiration of the generated organization CA and TLS certificates. Note that this is different than the `expiry` specified in the `csr` section for the CA root certificate. +The defaults in this section are normally sufficient for a production server. However, you might want to modify the default expiration of the generated organization CA and TLS certificates. Note that this is different than the `expiry` specified in the `csr` section for the CA root certificate. If this is a TLS CA, it is recommended that you remove the `ca` section from `profiles:` since a TLS CA should only be issuing TLS certificates. @@ -328,7 +337,7 @@ bccsp: keystore: msp/keystore ``` -The information in this section controls where the private key for the CA is stored. The configuration above causes the private key to be stored on the file system of the CA server in the `msp/keystore` folder. If you plan to use a Hardware Security Module (HSM) the configuration is different. When you [configure HSM for a CA](https://hyperledger-fabric.readthedocs.io/en/release-2.1/hsm.html#using-an-hsm-with-a-fabric-ca), the CA private key is generated by and stored in the HSM instead of the `msp/keystore` folder. An example of the HSM configuration for softHSM would be similar to: +The information in this section controls where the private key for the CA is stored. The configuration above causes the private key to be stored on the file system of the CA server in the `msp/keystore` folder. If you plan to use a Hardware Security Module (HSM) the configuration is different. When you [configure HSM for a CA](https://hyperledger-fabric.readthedocs.io/en/{FABRIC_VERSION}/hsm.html#using-an-hsm-with-a-fabric-ca), the CA private key is generated by and stored in the HSM instead of the `msp/keystore` folder. An example of the HSM configuration for softHSM would be similar to: ``` bccsp: @@ -343,6 +352,7 @@ bccsp: ``` ## cors + ``` cors: enabled: false @@ -353,15 +363,16 @@ cors: Cross-Origin Resource Sharing (CORS) can be configured to use additional HTTP headers to tell browsers to give a web application running at one origin access to selected resources from a different origin. The `origins` parameter contains a list of domains that are allowed to access the resources. ## cfg + ``` cfg: affiliations: allowremove: false identities: - allowremove: false + allowremove: false ``` -These two parameters are not listed in the sample configuration file, but are important to understand. With the default configuration set to false, you will be unable to remove affiliations or identities without a server restart. If you anticipate the need to remove affiliations or identities from your production environment without a server restart, both of these fields should be set to `true` before starting your server. Note that after the server is started, affiliations and identities can only be modified by using the Fabric CA client CLI commands. +These two parameters are not listed in the sample configuration file, but are important to understand. With the default configuration set to false, you will be unable to remove affiliations or identities without a server restart. If you anticipate the need to remove affiliations or identities from your production environment without a server restart, both of these fields should be set to `true` before starting your server. Note that after the server is started, affiliations and identities can only be modified by using the Fabric CA client CLI commands. ## operations @@ -392,7 +403,7 @@ operations: ``` The operations service can be used for health monitoring of the CA and relies on mutual TLS for communication with the node. -Therefore, you need to set `operations.tls.clientAuthRequired` to `true`. When this is set to `true`, clients attempting to ascertain the health of the node are required to provide a valid certificate for authentication. If the client does not provide a certificate or the service cannot verify the client’s certificate, the request is rejected. This means that the clients will need to register with the TLS CA and provide their TLS signing certificate on the requests. +Therefore, you need to set `operations.tls.clientAuthRequired` to `true`. When this is set to `true`, clients attempting to ascertain the health of the node are required to provide a valid certificate for authentication. If the client does not provide a certificate or the service cannot verify the client’s certificate, the request is rejected. This means that the clients will need to register with the TLS CA and provide their TLS signing certificate on the requests. In the case where two CAs are running on the same machine, you need to modify the `listenAddress:` for the second CA to use a different port. Otherwise, when you start the second CA, it will fail to start, reporting that `the bind address is already in use`. @@ -427,6 +438,5 @@ If you want to monitor the metrics for the CA, choose your metrics provider: After deciding on your CA configuration, you are ready to deploy your CAs. Follow instructions in the next CA Deployment steps topic to start your CA. - diff --git a/docs/source/deployguide/ca-deploy-topology.md b/docs/source/deployguide/ca-deploy-topology.md index ae834b8ec..6a02e5609 100644 --- a/docs/source/deployguide/ca-deploy-topology.md +++ b/docs/source/deployguide/ca-deploy-topology.md @@ -2,17 +2,18 @@ **Audience**: Architects, network operators, users setting up a production Fabric network and are familiar with Transport Layer Security (TLS), Public Key Infrastructure (PKI) and Membership Service Providers (MSPs). -These deployment instructions provide guidance for how to deploy a CA for a Production network. If you need to quickly stand up a network for education or testing purposes, check out the [Fabric test network](https://hyperledger-fabric.readthedocs.io/en/release-2.0/test_network.html). While the Fabric CA server remains a preferred and tested certificate authority for Hyperledger Fabric, you can instead use certificates from a non-Fabric CA with your Fabric network; however, the scope of this deployment guide is focused on using a Fabric CA. It focuses on the most important configuration parameters you need to consider and provides best practices for configuring a CA. +These deployment instructions provide guidance for how to deploy a CA for a Production network. If you need to quickly stand up a network for education or testing purposes, check out the [Fabric test network](https://hyperledger-fabric.readthedocs.io/en/{FABRIC_VERSION}/test_network.html). While the Fabric CA server remains a preferred and tested certificate authority for Hyperledger Fabric, you can instead use certificates from a non-Fabric CA with your Fabric network; however, the scope of this deployment guide is focused on using a Fabric CA. It focuses on the most important configuration parameters you need to consider and provides best practices for configuring a CA. You may already be familiar with the Fabric CA [User's Guide](../users-guide.html) and the [Operations Guide](../operations_guide.html). This topic is intended to inform your decisions before deploying a CA and provide guidance on how to configure the CA parameters based on those decisions. You may still need to reference those topics when you make your decisions. Recall that a Fabric CA performs the following functions on a blockchain network: + - Registration of identities, or connect to a Lightweight Directory Access Protocol (LDAP) as the user registry. - Issuance of Enrollment Certificates (ECerts). Enrollment is a process whereby the Fabric CA issues a certificate key-pair, comprised of a signing certificate and a private key that forms the identity. The private and public keys are first generated locally by the Fabric CA client, and then the public key is sent to the CA which returns an encoded certificate, the signing certificate. - Certificate renewal and revocation. You have the opportunity to customize the behavior of these functions. The first time the CA is started, it looks for a [fabric-ca-server-config.yaml -file](https://hyperledger-fabric-ca.readthedocs.io/en/release-1.4/serverconfig.html) which contains the CA configuration parameters. If the file is not there, a default one is created for you. Before you deploy your CA, this topic provides guidance around the parameters in that file and the decisions you need to make in order to customize the CA according to your use case. +file](https://hyperledger-fabric-ca.readthedocs.io/en/latest/serverconfig.html) which contains the CA configuration parameters. If the file is not there, a default one is created for you. Before you deploy your CA, this topic provides guidance around the parameters in that file and the decisions you need to make in order to customize the CA according to your use case. ## What CA topology will you use on your network? @@ -32,7 +33,7 @@ It is also worth noting that from a functional perspective there is no differenc #### When would I want an intermediate CA? -Intermediate CAs are optional. For added security, organizations can deploy a chain of CAs known as intermediate CAs. An intermediate CA has their root certificate issued by a parent CA (root CA) or another intermediate authority (that becomes the parent CA), which establishes a “chain of trust” for any certificate that is issued by any CA in the chain. Therefore, having one or more intermediate CAs allows you to protect your root of trust. This ability to track back to the root CA not only allows the function of CAs to scale while still providing security — allowing organizations that consume certificates to use intermediate CAs with confidence — it limits the exposure of the root CA, which, if compromised, would endanger the entire chain of trust. If an intermediate CA is compromised, on the other hand, there will be a much smaller exposure. A key benefit is that after the intermediate CAs are up and running, the root CA can be effectively turned off, limiting its vulnerability even more. +Intermediate CAs are optional. For added security, organizations can deploy a chain of CAs known as intermediate CAs. An intermediate CA has their root certificate issued by a parent CA (root CA) or another intermediate authority (that becomes the parent CA), which establishes a “chain of trust” for any certificate that is issued by any CA in the chain. Therefore, having one or more intermediate CAs allows you to protect your root of trust. This ability to track back to the root CA not only allows the function of CAs to scale while still providing security — allowing organizations that consume certificates to use intermediate CAs with confidence — it limits the exposure of the root CA, which, if compromised, would endanger the entire chain of trust. If an intermediate CA is compromised, on the other hand, there will be a much smaller exposure. A key benefit is that after the intermediate CAs are up and running, the root CA can be effectively turned off, limiting its vulnerability even more. Another reason to include an intermediate CA would be when you have a very large organization with multiple departments and you don’t want a single CA to generate certificates for all of the departments. Intermediate CAs provide a mechanism for scoping the certificates that a CA manages to a smaller department or sub-group. Intermediate CAs are not required, but they mitigate risk and scope certificate management. This pattern incurs significant overheard if there will only be a small number of members in the organization. As an alternative to deploying multiple intermediate CAs, you can configure a CA with `affiliations` (similar to departments) instead. More on this later when we talk about `affiliations`. @@ -44,7 +45,7 @@ If a dual-headed CA is not configured with an organization CA and TLS CA, then t ## Deciding on a user registry -Because the Fabric CA controls the identities for an organization, you need to decide on your user registry before you configure your CA. The Fabric CA server can be configured to use a database as the user registry or it can be configured to read from an Lightweight Directory Access Protocol (LDAP) server. LDAP is an industry standard for server data storage and retrieval where information is represented as a hierarchical tree. The LDAP protocol is used to lookup data on the server, in this context the data is users and groups, and the server is therefore a user repository. When an LDAP server will be your user repository, you will need to provide the connection and configuration details. After LDAP is configured for the CA, it authenticates an identity against the LDAP user registry prior to generating the certificates for that user, a process known as `enrollment`. Additionally, user attributes retrieved from the LDAP registry are useful for making access control decisions in smart contracts. See [Configuring LDAP](../users-guide.html#configuring-ldap) if you want to learn more about LDAP considerations. +Because the Fabric CA controls the identities for an organization, you need to decide on your user registry before you configure your CA. The Fabric CA server can be configured to use a database as the user registry or it can be configured to read from an Lightweight Directory Access Protocol (LDAP) server. LDAP is an industry standard for server data storage and retrieval where information is represented as a hierarchical tree. The LDAP protocol is used to lookup data on the server, in this context the data is users and groups, and the server is therefore a user repository. When an LDAP server will be your user repository, you will need to provide the connection and configuration details. After LDAP is configured for the CA, it authenticates an identity against the LDAP user registry prior to generating the certificates for that user, a process known as `enrollment`. Additionally, user attributes retrieved from the LDAP registry are useful for making access control decisions in smart contracts. See [Configuring LDAP](../users-guide.html#configuring-ldap) if you want to learn more about LDAP considerations. This deployment guide demonstrates the process for configuring the user registry with a database. @@ -56,7 +57,7 @@ There are three ways to configure settings on the Fabric CA server and client. T 2. Use environment variables to override configuration file settings. 3. Modify the configuration file. -This order means that from a code perspective, any flags passed on a Fabric CA server CLI command will override an environment variable if it exists for the same setting, as well as the default value of the setting in the configuration file. Likewise, environment variables can be used to override settings in the configuration file. However, use of environment variables to modify configuration settings is discouraged because the changes are not persisted and can lead to problems later when they do not get set or are not set to what they should be. It's important to understand the parameters in the configuration file and their dependencies on other parameter settings in the file. Blindly overriding one setting using an environment variable could affect the functionality of another setting. Therefore, the recommendation is that before starting the server, you **make the modifications to the settings in the configuration file** to become familiar with the available settings and how they work. +This order means that from a code perspective, any flags passed on a Fabric CA server CLI command will override an environment variable if it exists for the same setting, as well as the default value of the setting in the configuration file. Likewise, environment variables can be used to override settings in the configuration file. However, use of environment variables to modify configuration settings is discouraged because the changes are not persisted and can lead to problems later when they do not get set or are not set to what they should be. It's important to understand the parameters in the configuration file and their dependencies on other parameter settings in the file. Blindly overriding one setting using an environment variable could affect the functionality of another setting. Therefore, the recommendation is that before starting the server, you **make the modifications to the settings in the configuration file** to become familiar with the available settings and how they work. Note that some configuration settings are stored in the CA database which means that after a CA is started, overriding the settings can no longer be performed by editing the configuration file or by setting environment variables. Affected parameters are noted throughout these instructions. In these cases, the modifications are required to be made by using the Fabric CA server CLI commands and have the added benefit of not requiring a server restart. diff --git a/docs/source/deployguide/cadeploy.md b/docs/source/deployguide/cadeploy.md index 939ade925..a97d25aba 100644 --- a/docs/source/deployguide/cadeploy.md +++ b/docs/source/deployguide/cadeploy.md @@ -10,13 +10,13 @@ In this topic, we use the server binaries to deploy three different types of CAs ### Client binary file -Likewise, we will copy the Fabric CA client binary to its own directory. Having the CA client in its own folder facilitates certificate management, especially when you need to interact with multiple CAs. When you issue a command from the CA client against a CA server, you can target a specific CA by modifying the CA server URL on the request. Therefore, only a single Fabric CA client binary is required and can be used to transact with multiple CAs. More on using the Fabric CA client below. +Likewise, we will copy the Fabric CA client binary to its own directory. Having the CA client in its own folder facilitates certificate management, especially when you need to interact with multiple CAs. When you issue a command from the CA client against a CA server, you can target a specific CA by modifying the CA server URL on the request. Therefore, only a single Fabric CA client binary is required and can be used to transact with multiple CAs. More on using the Fabric CA client below. ## Fabric CA client Before deploying a Fabric CA server, you need to understand the role of the Fabric CA client. While you can use the Fabric SDKs to interact with your CA, it is recommended that you **use the Fabric CA client to register and enroll node admin identities**. The instructions provided in this topic assume a single Fabric CA client is being used. Registering an identity, or user, is the process by which the enroll id and secret is added to the CA database "user registry". If you are using LDAP server for your user registry, then the register step is not required because the identities already exist in the LDAP database. After a user is registered you can use the Fabric CA client to "enroll" the identity which is the process that generates the certificates the identity needs to transact as part of the organization. When you submit an enrollment request, the private and public keys are first generated locally by the Fabric CA client, and then the public key is sent to the CA which returns an encoded "signed certificate". -Because you will use a single CA client to submit register and enrollment requests to multiple CAs, certificate management is critically important when using the CA client. A best practice therefore is to create sub-folders for each CA server that the CA client will interact with, to store the generated certificates. +Because you will use a single CA client to submit register and enrollment requests to multiple CAs, certificate management is critically important when using the CA client. A best practice therefore is to create sub-folders for each CA server that the CA client will interact with, to store the generated certificates. - Create a sub-folder in order to connect to each CA server, such as `/tls-ca` or `/org1-ca` or `/int-ca`. This folder can be under the Fabric CA client or anywhere that the CA client can access the path. For purposes of these instructions, these folders reside inside the `fabric-ca-client` directory. For example: @@ -25,27 +25,31 @@ Because you will use a single CA client to submit register and enrollment reques cd fabric-ca-client mkdir tls-ca org1-ca int-ca ``` + **Tip:** While you can run the Fabric CA client binary from any folder you prefer, for ease of following these instructions we will refer to it in its own directory named `fabric-ca-client`. + - Copy the Fabric CA client binary into the `fabric-ca-client` folder. -- Because TLS communications are enabled on a production network, the TLS CA for the organization is responsible for generating certificates that secure communications between all nodes in the organization. Therefore, every time the Fabric CA client transacts with a CA server in that organization, it needs to provide the TLS CA "root certificate" to secure the client-server communication. For example, when the Fabric CA client issues a register or enroll request to the CA server, the client request includes that root certificate to perform an SSL handshake. The TLS CA root certificate, named `ca-cert.pem`, is generated on the TLS CA after TLS is enabled in the server config .yaml file. To enable TLS communications for your CA client, you need a `tls-root-cert` sub-folder to store the root certificate. Later in this topic, we will copy the root certificate into this folder. +- Because TLS communications are enabled on a production network, the TLS CA for the organization is responsible for generating certificates that secure communications between all nodes in the organization. Therefore, every time the Fabric CA client transacts with a CA server in that organization, it needs to provide the TLS CA "root certificate" to secure the client-server communication. For example, when the Fabric CA client issues a register or enroll request to the CA server, the client request includes that root certificate to perform an SSL handshake. The TLS CA root certificate, named `ca-cert.pem`, is generated on the TLS CA after TLS is enabled in the server config .yaml file. To enable TLS communications for your CA client, you need a `tls-root-cert` sub-folder to store the root certificate. Later in this topic, we will copy the root certificate into this folder. ``` mkdir tls-root-cert ``` The resulting folder structure resembles: - ``` - fabric-ca-client - ├── int-ca - ├── org1-ca - ├── tls-ca - └── tls-root-cert - ``` + ``` + fabric-ca-client + ├── int-ca + ├── org1-ca + ├── tls-ca + └── tls-root-cert + + ``` **Important:** If your Fabric CA client will transact with CAs from multiple organizations that are secured by different TLS servers, then you would need to either create different `tls-root-cert` folders to hold the TLS CA root certificate for each organization or simply name them differently inside the folder to differentiate them. Since our Fabric CA client will only be transacting with CA servers in the same organization, all of which are secured by the same TLS CA, we will only have a single root certificate in this folder. You can use environment variables or flags on the CLI commands to specify the location of certificates and the Fabric CA client binary: + - `FABRIC_CA_CLIENT_HOME` - Specify the fully qualified path to where Fabric CA client binary resides. - `FABRIC_CA_CLIENT_TLS_CERTFILES` - Specify the location and name of the TLS CA root certificate. If the path of the environment variable `FABRIC_CA_CLIENT_TLS_CERTFILES` is not an absolute path, it will be parsed as relative to the Fabric CA client’s home directory as specified by `FABRIC_CA_CLIENT_HOME`. Throughout these instructions, we use the `--tls.certfiles` flag on the commands instead to specify the location of the TLS CA root certificate. - `FABRIC_CA_CLIENT_MSPDIR` - While you can use this environment variable to specify the name of the folder where the certificates are located, because the client communicates with multiple CAs, _a better option is to explicitly pass the `--mspdir` flag on the register and enroll commands to specify the location._ If not specified on the command, the location defaults to `$FABRIC_CA_CLIENT_HOME/msp` which will be problematic if the Fabric CA client transacts with multiple CA servers in the organization. @@ -67,17 +71,18 @@ We will use both of these CLI commands throughout this topic. ## What order should I deploy the CAs? Assuming you are not deploying a dual-headed CA that contains both a TLS CA and an organization CA together, you would deploy the CAs in the following order: -1. **Deploy the TLS CA** - Because TLS communication is required in a Production network, TLS must be enabled on each CA, peer, and ordering node. While the example configuration in the CA Operations Guide shares a single TLS CA across all organizations, the recommended configuration for production is to deploy a TLS CA for each organization. The TLS CA issues the TLS certificates that secure communications between all the nodes on the network. Therefore, it needs to be deployed first to generate the TLS certificates for the TLS handshake that occurs between the nodes. +1. **Deploy the TLS CA** + + Because TLS communication is required in a Production network, TLS must be enabled on each CA, peer, and ordering node. While the example configuration in the CA Operations Guide shares a single TLS CA across all organizations, the recommended configuration for production is to deploy a TLS CA for each organization. The TLS CA issues the TLS certificates that secure communications between all the nodes on the network. Therefore, it needs to be deployed first to generate the TLS certificates for the TLS handshake that occurs between the nodes. -2. **Deploy the organization CA** +2. **Deploy the organization CA** - This is the organization's identity enrollment CA and is used to register and enroll the identities that will participate in the network from this organization. + This is the organization's identity enrollment CA and is used to register and enroll the identities that will participate in the network from this organization. -3. **Deploy the intermediate CA (Optional)** +3. **Deploy the intermediate CA (Optional)** - If you decide to include an intermediate CA in your network, the intermediate CA's parent server (the associated root CA) must be deployed before any intermediate CAs. + If you decide to include an intermediate CA in your network, the intermediate CA's parent server (the associated root CA) must be deployed before any intermediate CAs. ## Deploy the TLS CA @@ -90,6 +95,7 @@ Regardless of whether you are setting up a TLS CA, an organization CA or an inte - [Step five: Enroll bootstrap user with TLS CA](#enroll-bootstrap-user-with-tls-ca) When you deploy any node, you have three options for your TLS configuration: + - No TLS. _Not recommended for a production network._ - Server-side TLS. - Mutual TLS. @@ -100,10 +106,11 @@ This process will configure a CA with server-side TLS enabled which is recommend You should have already downloaded and copied the Fabric CA server binary `fabric-ca-server` to a clean directory on your machine. For purposes of these instructions, we put the binary in its own folder named `fabric-ca-server-tls`. - ``` - mkdir fabric-ca-server-tls - ``` - Copy the `fabric-ca-server` binary into this folder. +``` +mkdir fabric-ca-server-tls +``` + +Copy the `fabric-ca-server` binary into this folder. ### Initialize the TLS CA server @@ -114,17 +121,20 @@ The first step to deploy a CA server is to "initialize" it. Run the following CA ``` For example: + ``` cd fabric-ca-server-tls ./fabric-ca-server init -b tls-admin:tls-adminpw ``` -The `-b` (bootstrap identity) flag bootstraps the admin username and password to the CA server which effectively "registers" the CA admin user with the server for you, so an explicit Fabric CA client CLI `register` command is not required for the bootstrapped user. All CA users need to be "registered" and then "enrolled" with the CA, except for this CA admin identity which is implicitly registered by using the `-b` flag. The registration process inserts the user into the CA database. The `-b` option is not required for initialization when LDAP will be configured. -**Note: This example is for illustration purposes only. Obviously, in a production environment you would never use `tls-admin` and `tls-adminpw` as the bootstrap username and password.** Be sure that you record the admin id and password that you specify. They are required later when you issue register and enroll commands against the CA. It can help to use a meaningful id to differentiate which server you are transacting with and follow secure password practices. +The `-b` (bootstrap identity) flag bootstraps the admin username and password to the CA server which effectively "registers" the CA admin user with the server for you, so an explicit Fabric CA client CLI `register` command is not required for the bootstrapped user. All CA users need to be "registered" and then "enrolled" with the CA, except for this CA admin identity which is implicitly registered by using the `-b` flag. The registration process inserts the user into the CA database. The `-b` option is not required for initialization when LDAP will be configured. + +**Note: This example is for illustration purposes only. Obviously, in a production environment you would never use `tls-admin` and `tls-adminpw` as the bootstrap username and password.** Be sure that you record the admin id and password that you specify. They are required later when you issue register and enroll commands against the CA. It can help to use a meaningful id to differentiate which server you are transacting with and follow secure password practices. #### What does the CA server `init` command do? The `init` command does not actually start the server but generates the required metadata if it does not already exist for the server: + - Sets the default the CA Home directory (referred to as `FABRIC_CA_HOME` in these instructions) to where the `fabric-ca-server init` command is run. - Generates the default configuration file `fabric-ca-server-config.yaml` that is used as a template for your server configuration in the `FABRIC_CA_HOME` directory. We refer to this file throughout these instructions as the "configuration .yaml" file. - Creates the TLS CA root signed certificate file `ca-cert.pem`, if it does not already exist in the CA Home directory. This is the **self-signed root certificate**, meaning it is generated and signed by the TLS CA itself and does not come from another source. This certificate is the public key that must be shared with all clients that want to transact with any node in the organization. When any client or node submits a transaction to another node, it must include this certificate as part of the transaction. @@ -139,12 +149,13 @@ The `init` command does not actually start the server but generates the required Now that you have initialized your server, you can edit the generated `fabric-ca-server-config.yaml` file to modify the default configuration settings for your use case according to the [Checklist for a production CA server](ca-config.html). At a minimum you should do the following: + - `port` - Enter the port that you want to use for this server. These instructions use `7054`, but you can choose your port. - `tls.enabled` - Recall that TLS is disabled in the default configuration file. Since this is a production server, enable it by setting this value to `true`. Setting this value to `true` causes the TLS signed certificate `tls-cert.pem` file to be generated when the server is started in the next step. The `tls-cert.pem` is the certificate the server will present to the client during a TLS handshake, which the client will then verify using the TLS CA’s `ca-cert.pem`. - `ca.name` - Give the CA a name by editing the parameter, for example `tls-ca`. - `csr.hosts` - Update this parameter to include a hostname, ip address, or domain name where this server is running, if it is different than what is already in this file. The host/domain names will be used to specify Subject Alternative Names when the server creates its self-signed TLS certificate tls-cert.pem when you start the server in the next step. - `signing.profiles.ca` - Since this is a TLS CA that will not issue CA certificates, the `ca` profiles section can be removed. The `signing.profiles` block should only contain `tls` profile. -- `operations.listenAddress:` - In the unlikely case that there is another node running on this host and port, then you need to update this parameter to use a different port. +- `operations.listenAddress:` - In the unlikely case that there is another node running on this host and port, then you need to update this parameter to use a different port. ### Delete the TLS CA server certificates @@ -153,18 +164,23 @@ Before starting the server, if you modified any of the values in the `csr` block ### Start the TLS CA server Run the following command to start the CA server: + ``` ./fabric-ca-server start ``` + When the server starts successfully you will see something similar to: + ``` [INFO] Listening on https://0.0.0.0:7054 ``` + Because you have enabled TLS communications but have not specified a TLS certfile, notice that the TLS signed certificate `tls-cert.pem` file is generated under the `FABRIC_CA_HOME` location. **Tip:** The CA `ADMIN_USER` and `ADMIN_PWD` that were set on the `init` command cannot be overridden with the `-b` flag on this `start` command. When you need to modify the CA admin password, use the Fabric CA client [identity](../clientcli.html#identity-command) command. **Optional flags**: + - `-d` - If you want to run the server in DEBUG mode which facilitates problem diagnosis, you can include the `-d` flag on the start command. However, in general it is not recommended to run a server with debug enabled as this will cause the server to perform slower. - `-p` - If you want the server to run on a port different than what is specified in the configuration .yaml file, you can override the existing port. @@ -175,14 +191,17 @@ Now that your TLS CA is configured and before you can deploy any other nodes for Performed by using the Fabric CA client, the enrollment process is used to generate the certificate and private key pair which forms the TLS CA bootstrap admin identity. You should have already setup the required folders in the [Fabric CA client](#fabric-ca-client) section. The folder structure that we are using for these Fabric CA client commands is: - ``` - fabric-ca-client - └── tls-ca - └── tls-root-cert - ``` - These folders are used by the Fabric CA client to: - - Store the certificates that are issued when the Fabric CA client enroll command is run against the TLS CA server to enroll the TLS CA bootstrap admin identity. (**tls-ca** folder) - - Know where the TLS CA root certificate resides that allows the Fabric CA client to communicate with the TLS CA server. (**tls-root-cert** folder) + +``` +fabric-ca-client + └── tls-ca + └── tls-root-cert +``` + +These folders are used by the Fabric CA client to: + +- Store the certificates that are issued when the Fabric CA client enroll command is run against the TLS CA server to enroll the TLS CA bootstrap admin identity. (**tls-ca** folder) +- Know where the TLS CA root certificate resides that allows the Fabric CA client to communicate with the TLS CA server. (**tls-root-cert** folder) 1. Copy the TLS CA root certificate file `fabric-ca-server-tls/ca-cert.pem`, that was generated when the TLS CA server was started, to the `fabric-ca-client/tls-root-cert/tls-ca-cert.pem` folder. Notice the file name is changed to `tls-ca-cert.pem` to make it clear this is the root certificate from the TLS CA. **Important:** This TLS CA root certificate will need to be available on each client system that will run commands against the TLS CA. @@ -191,15 +210,21 @@ The folder structure that we are using for these Fabric CA client commands is: ``` export FABRIC_CA_CLIENT_HOME= ``` + For example, if you are in the `fabric-ca-client` folder you can use: + ``` export FABRIC_CA_CLIENT_HOME=$PWD ``` + 3. You are ready to use the Fabric CA client CLI to enroll the TLS CA bootstrap admin identity. Run the command: + ``` ./fabric-ca-client enroll -d -u https://:@: --tls.certfiles --enrollment.profile tls --mspdir tls-ca/tlsadmin/msp ``` + Replace: + - `` - with the TLS CA admin specified on the `init` command. - `` - with the TLS CA admin password specified on the `init` command. - `` - with the hostname specified in the `csr` section of the TLS CA configuration .yaml file. @@ -207,6 +232,7 @@ The folder structure that we are using for these Fabric CA client commands is: - `` - with the path and name of the root TLS certificate file that you copied from your TLS CA. This path is relative to `FABRIC_CA_CLIENT_HOME`. If you are following the folder structure in this tutorial it would be `tls-root-cert/tls-ca-cert.pem`. For example: + ``` ./fabric-ca-client enroll -d -u https://tls-admin:tls-adminpw@my-machine.example.com:7054 --tls.certfiles tls-root-cert/tls-ca-cert.pem --enrollment.profile tls --mspdir tls-ca/tlsadmin/msp ``` @@ -219,7 +245,7 @@ The folder structure that we are using for these Fabric CA client commands is: When this command completes successfully, the `fabric-ca-client/tls-ca/tlsadmin/msp` folder is generated and contains the signed cert and private key for the TLS CA bootstrap admin identity. If the enroll command fails for some reason, to avoid confusion later, you should remove the generated private key from the `fabric-ca-client/tls-ca/admin/msp/keystore` folder before reattempting the enroll command. We will reference this crypto material later when it is required to register other identities with the TLS CA. - **Tip:** After you issue this first `enroll` command from the Fabric CA client, examine the contents of the generated `fabric-ca-client/fabric-ca-client-config.yaml` file to become familiar with the default settings that are used by the Fabric CA client. Because we are using a single Fabric CA client to interact with multiple CA servers, we need to use the `-u` flags on the client CLI commands to target the correct CA server. In conjunction, the `--mspdir` flag indicates the location of the cryptographic material to use on a `register` command or where to store the generated certificates on an `enroll` command. + **Tip:** After you issue this first `enroll` command from the Fabric CA client, examine the contents of the generated `fabric-ca-client/fabric-ca-client-config.yaml` file to become familiar with the default settings that are used by the Fabric CA client. Because we are using a single Fabric CA client to interact with multiple CA servers, we need to use the `-u` flags on the client CLI commands to target the correct CA server. In conjunction, the `--mspdir` flag indicates the location of the cryptographic material to use on a `register` command or where to store the generated certificates on an `enroll` command. The following diagram is a conceptual summary of the steps you perform to create a TLS CA server and enroll the bootstrap admin identity using the Fabric CA client: @@ -296,6 +322,7 @@ Because you've already registered and enrolled your organization CA bootstrap id - Using the following commands, copy the organization CA TLS certificate and key pair that you generated in the previous step to a location that can be accessed by this CA server, for example `fabric-ca-server-org1/tls`. These are the `fabric-ca-client/tls-ca/rcaadmin/msp/signcerts/cert.pem` and `fabric-ca-client/tls-ca/rcaadmin/msp/keystore/` files that were generated by the enroll command. **Note:** The following commands assume that: + - The generated private key under `fabric-ca-client/tls-ca/rcaadmin/msp/keystore/` was renamed to `key.pem`. - The `fabric-ca-client` and `fabric-ca-server-org1` folders are at the same level in your file structure. @@ -304,24 +331,26 @@ Because you've already registered and enrolled your organization CA bootstrap id mkdir tls cp ../fabric-ca-client/tls-ca/rcaadmin/msp/signcerts/cert.pem tls && cp ../fabric-ca-client/tls-ca/rcaadmin/msp/keystore/key.pem tls ``` + The resulting folder structure is similar to the following diagram. (Some folders and files have been omitted for clarity): - ``` - fabric-ca-client - └── tls-ca - ├── rcaadmin - ├── msp -       ├── IssuerPublicKey -       ├── IssuerRevocationPublicKey -       ├── cacerts -    ├── keystore -      └── key.pem -      ├── signcerts -          └── cert.pem - fabric-ca-server-org1 - └── tls - └── cert.pem - └── key.pem - ``` + + ``` + fabric-ca-client + └── tls-ca + ├── rcaadmin + ├── msp +       ├── IssuerPublicKey +       ├── IssuerRevocationPublicKey +       ├── cacerts +    ├── keystore +      └── key.pem +      ├── signcerts +          └── cert.pem + fabric-ca-server-org1 + └── tls + └── cert.pem + └── key.pem + ``` ### Initialize the CA server @@ -332,6 +361,7 @@ Run the command to initialize the server, specifying a new admin user id and pas ``` For example: + ``` ./fabric-ca-server init -b rcaadmin:rcaadminpw ``` @@ -341,6 +371,7 @@ For example: As we did with the TLS CA, we need to edit the generated `fabric-ca-server-config.yaml` file for the organization CA to modify the default configuration settings for your use case according to the [Checklist for a production CA server](ca-config.html). At a minimum, you should edit the following fields: + - `port` - Enter the port that you want to use for this server. These instructions use `7055`, but you can choose your port. - `tls.enabled` - Enable TLS by setting this value to `true`. - `tls.certfile` and `tls.keystore`- Enter the relative path and filenames for the TLS CA signed certificate and private key that were generated when the bootstrap admin for this CA was enrolled with the TLS CA. The signed certificate, `cert.pem`, was generated using the Fabric CA client and can be found under `fabric-ca-client/tls-ca/rcaadmin/msp/signcerts/cert.pem`. The private key is located under `fabric-ca-client/tls-ca/rcaadmin/msp/keystore`. The specified path name is relative to `FABRIC_CA_CLIENT_HOME` therefore if you are following the folder structure that is used throughout these instructions you can simply specify `tls/cert.pem` for the `tls.certfile` and `tls/key.pem` for the `tls.keystore` or you can specify the fully qualified path name. @@ -357,6 +388,7 @@ Before starting the server, if you modified any of the values in the `csr` block ### Start the CA server Run the following command to start the CA server: + ``` ./fabric-ca-server start ``` @@ -366,27 +398,32 @@ Run the following command to start the CA server: The final step for deploying the CA is to enroll the CA admin bootstrap identity (rcaadmin user). This will generate the rcaadmin user's signed certificate and private key. The key-pair is required so that the rcaadmin user can then register and enroll other identities in the organization. Again we will use the Fabric CA client CLI to enroll the admin. You should have already setup the required folders in the [Fabric CA client](#fabric-ca-client) section. The folder structure we are using for these commands is: - ``` - fabric-ca-client - └── org1-ca - └── tls-root-cert - ``` - These folders are used by the Fabric CA client to: - - Store the certificates that are issued when the Fabric CA client enroll command is run against the organization CA server. (**org1-ca** folder) - - Know where the TLS certificate resides that allows the Fabric CA client to communicate with the TLS CA server. (**tls-root-cert** folder) +``` +fabric-ca-client + └── org1-ca + └── tls-root-cert +``` + +These folders are used by the Fabric CA client to: + +- Store the certificates that are issued when the Fabric CA client enroll command is run against the organization CA server. (**org1-ca** folder) +- Know where the TLS certificate resides that allows the Fabric CA client to communicate with the TLS CA server. (**tls-root-cert** folder) 1. When you previously used the Fabric CA client to generate certificates for the TLS CA, you designated the value of the `FABRIC_CA_CLIENT_HOME`. Assuming that is still set you can proceed to the next step. Otherwise, you should be in the directory where the Fabric CA client binary resides and run the command: - ``` - export FABRIC_CA_CLIENT_HOME=$PWD - ``` + ``` + export FABRIC_CA_CLIENT_HOME=$PWD + ``` 2. Now you can use the Fabric CA client to generate the CA admin certificate and private key. You need this certificate and private key to be able to issue identities using this CA. We use the `--mspdir` flag on the enroll command to designate where to store the generated certificates. Run the command: + ``` ./fabric-ca-client enroll -d -u https://:@: --tls.certfiles --mspdir org1-ca/rcaadmin/msp ``` + Replace: + - `` - with the organization CA admin specified on the `init` command. - `` - with the organization CA admin password specified on the `init` command. - `` - with the hostname for the organization CA. @@ -396,6 +433,7 @@ The folder structure we are using for these commands is: In this case, the `-d` parameter runs the client in DEBUG mode which is useful for debugging command failures. For example: + ``` ./fabric-ca-client enroll -d -u https://rcaadmin:rcaadminpw@my-machine.example.com:7055 --tls.certfiles tls-root-cert/tls-ca-cert.pem --mspdir org1-ca/rcaadmin/msp ``` @@ -412,22 +450,24 @@ The folder structure we are using for these commands is: └── cert.pem ├── user ├── IssuerPublicKey - └── IssuerRevocationPublicKey - ``` + └── IssuerRevocationPublicKey + ``` Where: + - `my-machine-example-com-7055.pem` is the **Organization CA root certificate**. - `60b6a16b8b5ba3fc3113c522cce86a724d7eb92d6c3961cfd9afbd27bf11c37f_sk` is the **private key** for the organization CA admin identity. This key needs to be protected and should not be shared with anyone. It is required to be able to register and enroll other identities with this CA. Feel free to rename this file to something easier to reference, for example `org1-key.pem`. - `cert.pem` is the CA admin identity **signed certificate**. 3. (Optional) Register the intermediate CA bootstrap identity with the organization (root) CA. - If you plan to deploy an intermediate CA, you must register the intermediate CA bootstrap identity with its root CA in order to form the chain of trust. Recall that you already registered the `icaadmin` identity with the TLS CA. You also need to register the same identity with the (root) organization CA. And because this will be an intermediate CA, you must include the `hf.IntermediateCA=true` attribute. (Run this command from the same terminal window where you enrolled the organization CA admin in the previous step.) - ``` - ./fabric-ca-client register -u https://my-machine.example.com:7055 --id.name icaadmin --id.secret icaadminpw --id.attrs '"hf.Registrar.Roles=user,admin","hf.Revoker=true","hf.IntermediateCA=true"' --tls.certfiles tls-root-cert/tls-ca-cert.pem --mspdir org1-ca/rcaadmin/msp - ``` + If you plan to deploy an intermediate CA, you must register the intermediate CA bootstrap identity with its root CA in order to form the chain of trust. Recall that you already registered the `icaadmin` identity with the TLS CA. You also need to register the same identity with the (root) organization CA. And because this will be an intermediate CA, you must include the `hf.IntermediateCA=true` attribute. (Run this command from the same terminal window where you enrolled the organization CA admin in the previous step.) - The `--mspdir` flag on the register command points to the crypto material for the organization CA admin that we enrolled in the previous step and is authorized to register new users. We don't enroll the `icaadmin` identity with the organization CA. Rather this intermediate CA admin identity is enrolled later against the intermediate CA. + ``` + ./fabric-ca-client register -u https://my-machine.example.com:7055 --id.name icaadmin --id.secret icaadminpw --id.attrs '"hf.Registrar.Roles=user,admin","hf.Revoker=true","hf.IntermediateCA=true"' --tls.certfiles tls-root-cert/tls-ca-cert.pem --mspdir org1-ca/rcaadmin/msp + ``` + + The `--mspdir` flag on the register command points to the crypto material for the organization CA admin that we enrolled in the previous step and is authorized to register new users. We don't enroll the `icaadmin` identity with the organization CA. Rather this intermediate CA admin identity is enrolled later against the intermediate CA. ## (Optional) Deploy an intermediate CA @@ -445,6 +485,7 @@ Intermediate CAs form a chain a trust with the organization root CA and can be u - Use the following commands to copy the CA admin TLS certificate and key pair that you generated in the previous step to a location that can be accessed by this CA server, for example `fabric-ca-server-int-ca/tls`. These are the `fabric-ca-client/tls-ca/icaadmin/msp/signcerts/cert.pem` and `fabric-ca-client/tls-ca/icaadmin/msp/keystore/` files that were generated by the enroll command. **Note:** The following commands assume that: + - The generated private key under `fabric-ca-client/tls-ca/icaadmin/keystore/` is renamed to `key.pem`. - The `fabric-ca-client` and `fabric-ca-server-int-ca` folders are at the same level in your file structure. @@ -453,6 +494,7 @@ Intermediate CAs form a chain a trust with the organization root CA and can be u mkdir tls cp ../fabric-ca-client/tls-ca/icaadmin/msp/signcerts/cert.pem tls && cp ../fabric-ca-client/tls-ca/icaadmin/msp/keystore/key.pem tls ``` + - Because TLS communications are enabled, the intermediate CA needs the TLS CA root certificate to be able to securely communicate with the parent organization CA. Therefore, you need to copy the `fabric-ca-server-tls/ca-cert.pem`, that was generated when the TLS CA server was initialized, to the `tls` folder. Notice the file name is changed to `tls-ca-cert.pem` to make it clear this is the root certificate from the TLS CA. ``` cp ../fabric-ca-server-tls/ca-cert.pem tls/tls-ca-cert.pem @@ -460,26 +502,26 @@ Intermediate CAs form a chain a trust with the organization root CA and can be u The resulting folder structure is similar to the following structure. (Some folders and files have been omitted for clarity): - ``` - fabric-ca-client - └── tls-ca - ├── icaadmin - ├── msp -       ├── cacerts -    ├── keystore -      └── key.pem -      ├── signcerts -          └── cert.pem - ├── tlscacerts - ├── user - ├── IssuerPublicKey -      └── IssuerRevocationPublicKey - fabric-ca-server-int-ca - └── tls - └── tls-ca-cert.pem - └── cert.pem - └── key.pem - ``` +``` +fabric-ca-client + └── tls-ca + ├── icaadmin + ├── msp +       ├── cacerts +    ├── keystore +      └── key.pem +      ├── signcerts +          └── cert.pem + ├── tlscacerts + ├── user + ├── IssuerPublicKey +      └── IssuerRevocationPublicKey +fabric-ca-server-int-ca + └── tls + └── tls-ca-cert.pem + └── cert.pem + └── key.pem +``` Because you have already deployed the parent organization (root) CA, you can use the following steps to create the intermediate CA: @@ -488,21 +530,22 @@ Because you have already deployed the parent organization (root) CA, you can use ./fabric-ca-server init -b icaadmin:icaadminpw ``` 2. Modify the `fabric-ca-server-config.yaml` file. - * `port`: Specify a unique port for this server. These instructions use `7056`, but you can choose your port. - * `tls.enabled`: Must be set to `true`. - * `tls.certfile` and `tls.keystore`: Enter the path and filename for the TLS CA signed certificate and private key. These are the certificate and private key files that you created when you enrolled the `icaadmin` user with the TLS CA. The signed certificate, `cert.pem` can be found under `fabric-ca-client/tls-ca/icaadmin/msp/signcerts/cert.pem`. The private key is located under `fabric-ca-client/tls-ca/icaadmin/msp/keystore`. The specified path name is relative to `FABRIC_CA_CLIENT_HOME` therefore if you are following the folder structure that is used throughout these instructions you can simply specify `tls/cert.pem` for the `tls.certfile` and `tls/key.pem` for the `tls.keystore` or you can specify the fully qualified path name. - * `ca`: Specify a name for the ca. For example `ica`. - * `signing.profiles.ca.caconstraint.maxpathlen`: Set this value to 0, meaning there are no more intermediate CA's under this one. The default value is `0`. - * `csr.cn`: The common name must be blank for intermediate CAs. - * `csr.ca.pathlength`: Set this value to 0. - * `intermediate.parentserver.url`: Enter the value of the parent server URL, in the form `https://:@:`, for example `https://rcaadmin:rcaadminpw@my-machine.example.com:7055`. - * `intermediate.parentserver.caname`: Enter the value of the parent server `caname` from the parent organization CA server configuration .yaml file. In this tutorial, we named that CA, `org1-ca`. - * `intermediate.enrollment.hosts`: Enter the host name that the intermediate CA server is listening on. - * `intermediate.enrollment.profile`: Enter the name of the signing profile from `signing.profile` section to use when issuing certificates. Normally this value is `ca`. - * `intermediate.tls.certfiles`: Enter the path and file name to the TLS CA root `tls-ca-cert.pem` file. If you are following the folder structure that is used throughout these instructions you can simply specify `tls/tls-ca-cert.pem`. - * `operations.listenAddress`: If another CA is running on the same host, you need to specify a unique port. + - `port`: Specify a unique port for this server. These instructions use `7056`, but you can choose your port. + - `tls.enabled`: Must be set to `true`. + - `tls.certfile` and `tls.keystore`: Enter the path and filename for the TLS CA signed certificate and private key. These are the certificate and private key files that you created when you enrolled the `icaadmin` user with the TLS CA. The signed certificate, `cert.pem` can be found under `fabric-ca-client/tls-ca/icaadmin/msp/signcerts/cert.pem`. The private key is located under `fabric-ca-client/tls-ca/icaadmin/msp/keystore`. The specified path name is relative to `FABRIC_CA_CLIENT_HOME` therefore if you are following the folder structure that is used throughout these instructions you can simply specify `tls/cert.pem` for the `tls.certfile` and `tls/key.pem` for the `tls.keystore` or you can specify the fully qualified path name. + - `ca`: Specify a name for the ca. For example `ica`. + - `signing.profiles.ca.caconstraint.maxpathlen`: Set this value to 0, meaning there are no more intermediate CA's under this one. The default value is `0`. + - `csr.cn`: The common name must be blank for intermediate CAs. + - `csr.ca.pathlength`: Set this value to 0. + - `intermediate.parentserver.url`: Enter the value of the parent server URL, in the form `https://:@:`, for example `https://rcaadmin:rcaadminpw@my-machine.example.com:7055`. + - `intermediate.parentserver.caname`: Enter the value of the parent server `caname` from the parent organization CA server configuration .yaml file. In this tutorial, we named that CA, `org1-ca`. + - `intermediate.enrollment.hosts`: Enter the host name that the intermediate CA server is listening on. + - `intermediate.enrollment.profile`: Enter the name of the signing profile from `signing.profile` section to use when issuing certificates. Normally this value is `ca`. + - `intermediate.tls.certfiles`: Enter the path and file name to the TLS CA root `tls-ca-cert.pem` file. If you are following the folder structure that is used throughout these instructions you can simply specify `tls/tls-ca-cert.pem`. + - `operations.listenAddress`: If another CA is running on the same host, you need to specify a unique port. 3. **Important:** You must delete the intermediate CA `fabric-ca-server-int-ca/ca-cert.pem` and `fabric-ca-server-int-ca/msp` folders in order for them to be regenerated with the intermediate CA settings. 4. Start the intermediate CA server. Because the intermediate CA bootstrap identity is enrolled with the parent organization (root) CA when the server is started, **ensure that the parent organziation CA is running before you start the intermediate CA**. + ``` ./fabric-ca-server start ``` @@ -514,44 +557,52 @@ Because you have already deployed the parent organization (root) CA, you can use The final step for deploying the intermediate CA is to enroll the intermediate CA admin to generate the node signed certificate and private key which is required for the identity to be able to enroll other identities. You should have already setup the required folders in the [Fabric CA client](#fabric-ca-client) section. The folder structure we are using for these commands is - ``` - fabric-ca-client - └── int-ca - └── tls-root-cert - ``` - These folders are used by the Fabric CA client to: - - Store the certificates that are issued when the Fabric CA client enroll command is run against the TLS CA server. (**int-ca** folder) - - Know where the TLS certificate resides that allows the Fabric CA client to communicate with the TLS CA server. (**tls-root-cert** folder) + +``` +fabric-ca-client + └── int-ca + └── tls-root-cert +``` + +These folders are used by the Fabric CA client to: + +- Store the certificates that are issued when the Fabric CA client enroll command is run against the TLS CA server. (**int-ca** folder) +- Know where the TLS certificate resides that allows the Fabric CA client to communicate with the TLS CA server. (**tls-root-cert** folder) 1. When you previously used the Fabric CA client to generate certificates for the TLS CA and organization CA, you designated the value of the `FABRIC_CA_CLIENT_HOME`. Assuming that is still set, you can proceed to the next step. Otherwise, you should be in the directory where the Fabric CA client binary resides and run the command: - ``` - export FABRIC_CA_CLIENT_HOME=$PWD - ``` + ``` + export FABRIC_CA_CLIENT_HOME=$PWD + ``` 2. Now you can use the Fabric CA client to generate the CA admin certificate and private key. You need this certificate and private key to be able to issue identities using this CA. We use the `--mspdir` flag on the enroll command to designate where to store the generated certificates. Run the command: - ``` - ./fabric-ca-client enroll -d -u https://:@: --tls.certfiles --csr.hosts '' --mspdir int-ca/icaadmin/msp - ``` - Replace: - - `` - with the intermediate CA admin specified on the `init` command. - - `` - with the intermediate CA admin password specified on the `init` command. - - `` - with the hostname specified in the `csr` section of the intermediate CA configuration .yaml file. - - `` - with the port that the intermediate CA is listening on. - - `` - with the path to the tls-ca-cert.pem file that you copied from your TLS CA. This is the path relative to `FABRIC_CA_CLIENT_HOME`. - - `` - with a comma-separated list of host names for which the certificate should be valid. If not specified, the default value from the `fabric-ca-client-config.yaml` is used. If a host name is dynamic you can specify a wildcard for the domain. For example, when you include the flag `--csr.hosts 'host1,*.example.com'` it means that the hostname `host1` is recognized as well as any host from the `example.com` domain. - - For example: - ``` - ./fabric-ca-client enroll -d -u https://icaadmin:icaadminpw@my-machine.example.com:7056 --tls.certfiles tls-root-cert/tls-ca-cert.pem --csr.hosts 'host1,*.example.com' --mspdir int-ca/icaadmin/msp - ``` + +``` +./fabric-ca-client enroll -d -u https://:@: --tls.certfiles --csr.hosts '' --mspdir int-ca/icaadmin/msp +``` + +Replace: + +- `` - with the intermediate CA admin specified on the `init` command. +- `` - with the intermediate CA admin password specified on the `init` command. +- `` - with the hostname specified in the `csr` section of the intermediate CA configuration .yaml file. +- `` - with the port that the intermediate CA is listening on. +- `` - with the path to the tls-ca-cert.pem file that you copied from your TLS CA. This is the path relative to `FABRIC_CA_CLIENT_HOME`. +- `` - with a comma-separated list of host names for which the certificate should be valid. If not specified, the default value from the `fabric-ca-client-config.yaml` is used. If a host name is dynamic you can specify a wildcard for the domain. For example, when you include the flag `--csr.hosts 'host1,*.example.com'` it means that the hostname `host1` is recognized as well as any host from the `example.com` domain. + +For example: + +``` +./fabric-ca-client enroll -d -u https://icaadmin:icaadminpw@my-machine.example.com:7056 --tls.certfiles tls-root-cert/tls-ca-cert.pem --csr.hosts 'host1,*.example.com' --mspdir int-ca/icaadmin/msp +``` + When the enroll command runs, it creates the `fabric-ca-client/int-ca/icaadmin/msp` folder and contains the signed cert and private key for the intermediate CA. Notice the `/intermediatecerts` folder is also created and populated with the intermediate CA certificate which connects this intermediate CA to the root CA. **Tip:** After the intermediate CA is successfully deployed and you can register and enroll identities, then you can safely turn off the parent server root CA, the organization CA. ## Next steps -Minimally, you should now have a TLS CA and an organization CA configured for your organization. You can now use the Fabric CA client to register and enroll node admin identities, node identities, and organization identities with the TLS CA to generate their TLS certificates required for server side TLS communications. Likewise you will also need to register and enroll the same node admins and users with the organization CA to generate their enrollment certificates and MSPs. See [Use the CA to create identities and MSPs](https://hyperledger-fabric.readthedocs.io/en/release-2.1/deployment_guide_overview.html#dg-step-four-use-the-ca-to-create-identities-and-msps) for more information. If you did configure an intermediate CA, you can now use that CA to register and enroll identities for the organization instead of the root CA. +Minimally, you should now have a TLS CA and an organization CA configured for your organization. You can now use the Fabric CA client to register and enroll node admin identities, node identities, and organization identities with the TLS CA to generate their TLS certificates required for server side TLS communications. Likewise you will also need to register and enroll the same node admins and users with the organization CA to generate their enrollment certificates and MSPs. See [Use the CA to create identities and MSPs](https://hyperledger-fabric.readthedocs.io/en/{FABRIC_VERSION}/deployment_guide_overview.html#dg-step-four-use-the-ca-to-create-identities-and-msps) for more information. If you did configure an intermediate CA, you can now use that CA to register and enroll identities for the organization instead of the root CA. **Tip:** When you subsequently use the Fabric CA client to register identities with the intermediate CA, ensure that you specify the `--mspdir int-ca/icaadmin/msp` on the register command. @@ -560,6 +611,7 @@ Minimally, you should now have a TLS CA and an organization CA configured for yo ### Fabric CA client `enroll` command fails **Problem:** When running an enroll command with the Fabric CA client CLI, it fails with: + ``` Error: Failed to read config file at '/Users/mwp/.fabric-ca-client/fabric-ca-client-config.yaml': While parsing config: yaml: line 42: mapping values are not allowed in this context ``` @@ -577,36 +629,43 @@ Note that when `FABRIC_CA_CLIENT_HOME` is set and an enrollment command fails, i ### Intermediate CA server fails to start **Problem:** The intermediate CA server fails to start with the error: + ``` Error: Response from server: Error Code: 0 - Certificate signing failure: {"code":5300,"message":"Policy violation request"} ``` + You may also see the associated error on the root CA: + ``` [ERROR] local signer certificate disallows CA MaxPathLen extending [INFO] 9.27.117.220:49864 POST /enroll 500 0 "Certificate signing failure: {"code":5300,"message":"Policy violation request"}" ``` + **Solution:** The values of the `signing.profiles.ca.caconstraint.maxpathlen` and the `csr.ca.pathlength` fields in the intermediate CA configuration .yaml file need to be set to 0. ### Starting the intermediate CA fails **Problem:** When you start the intermediate CA it fails with an error: + ``` Post https://host1.com:7060/enroll: x509: certificate signed by unknown authority ``` And the Root organization CA, has the error: + ``` TLS handshake error from 192.168.1.134:63094: remote error: tls: bad certificate ``` **Solution:** -This problem occurs during enrollment of the intermediate CA admin user with the root CA when the intermediate CA server is started. To resolve this problem, make sure that the TLS certificate that is specified in the `intermediate.tls.certfiles` section of the intermediate CA `fabric-ca-server-config.yaml` file points to the TLS CA root certificate. If you are following these instructions it will be `tls/tls-ca-cert.pem`. +This problem occurs during enrollment of the intermediate CA admin user with the root CA when the intermediate CA server is started. To resolve this problem, make sure that the TLS certificate that is specified in the `intermediate.tls.certfiles` section of the intermediate CA `fabric-ca-server-config.yaml` file points to the TLS CA root certificate. If you are following these instructions it will be `tls/tls-ca-cert.pem`. ### Enrolling the intermediate CA admin user fails **Problem:** When you start the intermediate CA and the process fails with the error: + ``` Error: Response from server: Error Code: 0 - Chain file does not exist at /fabric-ca-server-int-ca/ca-chain.pem ``` diff --git a/docs/source/deployguide/use_CA.md b/docs/source/deployguide/use_CA.md index 6416dbbf0..836000db3 100644 --- a/docs/source/deployguide/use_CA.md +++ b/docs/source/deployguide/use_CA.md @@ -1,8 +1,8 @@ # Registering and enrolling identities with a CA -*Audience: organization administrators, node administrators* +_Audience: organization administrators, node administrators_ -If you've read our topics on [identity](https://hyperledger-fabric.readthedocs.io/en/{BRANCH}/identity/identity.html) and [Membership Service Provider (MSP)](https://hyperledger-fabric.readthedocs.io/en/{BRANCH}/membership/membership.html) you're aware that in Hyperledger Fabric, Certificate Authorities are used to generate the identities assigned to admins, nodes, and users (client applications). While any Certificate Authority that can generate x.509 certificates can be used to create the public/private key pair that constitutes an identity, the Fabric CA can additionally generate the local and organizational MSP folder structures that are required by Hyperledger Fabric. +If you've read our topics on [identity](https://hyperledger-fabric.readthedocs.io/en/{FABRIC_VERSION}/identity/identity.html) and [Membership Service Provider (MSP)](https://hyperledger-fabric.readthedocs.io/en/{FABRIC_VERSION}/membership/membership.html) you're aware that in Hyperledger Fabric, Certificate Authorities are used to generate the identities assigned to admins, nodes, and users (client applications). While any Certificate Authority that can generate x.509 certificates can be used to create the public/private key pair that constitutes an identity, the Fabric CA can additionally generate the local and organizational MSP folder structures that are required by Hyperledger Fabric. In this topic, we'll show a "happy path" for using the Fabric CA to generate identities and MSPs. Note that you do not have to use the Fabric CA to register and enroll identities. However, if you use a different CA, you will need to create the relevant identities and MSPs that Fabric uses to build organizations, client identities, and nodes. We will show examples of those MSPs below. @@ -44,7 +44,7 @@ If you've followed the process described in the CA deployment guide, you should ![Fabric CA client folder structure](./fabriccaclientfolders.png) -*The figure above shows the structure of folders associated with using a single Fabric CA client to connect to multiple CA servers.* +_The figure above shows the structure of folders associated with using a single Fabric CA client to connect to multiple CA servers._ As you can see, each CA server has a separate folder underneath the `fabric-ca-client` folder. Inside each of these CA folders is an `msp` folder that contains the public/private key pair for the identity of the admin of that CA. This is the `--mspdir` you must specify when administrating the CA (for example, when registering an identity). @@ -54,17 +54,17 @@ If you are not a CA admin, but rather have a Fabric CA client only for the purpo While the way you organize the folders of the CAs you operate using the Fabric CA client is determined in large part by the multiple CAs a typical CA admin will interact with, the organizational method you use to organize your organization MSPs will be determined in part by how many organizations you anticipate creating and administering. -For example, in the Fabric [test network](https://hyperledger-fabric.readthedocs.io/en/release-2.0/test_network.html), both peer organizations and orderer organizations are created. As a result, the scripts associated with the network create a folder called `organizations`, which contains an `ordererOrganization` and a `peerOrganization` folder. Each of these folders contains a folder for each organization, which contains both an MSP for that organization and a folder for each node owned by those organizations. +For example, in the Fabric [test network](https://hyperledger-fabric.readthedocs.io/en/{FABRIC_VERSION}/test_network.html), both peer organizations and orderer organizations are created. As a result, the scripts associated with the network create a folder called `organizations`, which contains an `ordererOrganization` and a `peerOrganization` folder. Each of these folders contains a folder for each organization, which contains both an MSP for that organization and a folder for each node owned by those organizations. ![Structuring organizations](./organizations.png) -*The figure above shows the structure of the organizations managed by an administrator.* +_The figure above shows the structure of the organizations managed by an administrator._ Even if you don't plan to create an orderer organization, this kind of structure provides the highest level of long term flexibility for your deployment. If you create a new peer, for example, you will know to create a folder at `organizations//`. This `` folder will be the location for the local MSP of the peer (generated when the peer identity is enrolled) and for the certificates generated through enrollment with the TLS CA. Similarly, the location of the MSP of the organization the peer belongs to can reference the `msp` folder of the organization (which includes both the `config.yaml` file if Node OUs are being used as well as the public certificate of the admin of the organization, which in many cases will be the admin of the peer). ![Organizations and peers](./organizationswithpeer.png) -*The figure above shows the subfolders inside of a peer owned by the organization. Note the `msp` folder here under the `peers` folder. This is the local MSP of the peer, not a duplicate of the `org1.example.com` MSP.* +_The figure above shows the subfolders inside of a peer owned by the organization. Note the `msp` folder here under the `peers` folder. This is the local MSP of the peer, not a duplicate of the `org1.example.com` MSP._ It is the best practice to create these folders before enrolling identities and then referencing them when issuing the enroll command through the `--mspdir` flag. Note that while the --mspdir flag is used to specify where the MSP of the CA admin is during **registration**, it is used instead during **enrollment** to specify the location on the filesystem where the folders and certificates returned by the CA will be stored. @@ -130,13 +130,13 @@ As discussed above, an identity is first registered with a CA by a CA admin. Thi Where the variables are the following: -* `ID_NAME`: The enroll ID of the identity. This name will be given to the user out of band, who will use it when enrolling. -* `ID_SECRET`: The secret (similar to a password) for the identity. This secret will also be given along to the user along with the enroll ID to use when enrolling. -* `CA_URL`: The URL of the CA, followed by the port `7054` (unless the default port has been changed). -* `CA_ADMIN`: The path to the location of the certificates for the admin of the CA. -* `ID_TYPE`: The type (or role) of the identity. There are four possible types: `peer`, `orderer`, `admin`, and `client` (used for applications). This type must be linked to the relevant [NodeOU](#specifying-nodeous). If NodeOUs are not being used, you can ignore the type and `--id.type` flag. -* `ID_ATTRIBUTE`: Any attributes specified for this identity. For more information about attributes, check out [Attribute based access control](https://hyperledger-fabric-ca.readthedocs.io/en/latest/users-guide.html#attribute-based-access-control). These attributes can also be added as a JSON array, therefore the `$ID_ATTRIBUTE` is not meant to represent a single attribute but any and all attributes, which should be placed in the register command after the `--id.attrs` flag. -* `TLSCERT`: The relative path to your the TLS CA root signed certificate (generated when creating the TLS CA). +- `ID_NAME`: The enroll ID of the identity. This name will be given to the user out of band, who will use it when enrolling. +- `ID_SECRET`: The secret (similar to a password) for the identity. This secret will also be given along to the user along with the enroll ID to use when enrolling. +- `CA_URL`: The URL of the CA, followed by the port `7054` (unless the default port has been changed). +- `CA_ADMIN`: The path to the location of the certificates for the admin of the CA. +- `ID_TYPE`: The type (or role) of the identity. There are four possible types: `peer`, `orderer`, `admin`, and `client` (used for applications). This type must be linked to the relevant [NodeOU](#specifying-nodeous). If NodeOUs are not being used, you can ignore the type and `--id.type` flag. +- `ID_ATTRIBUTE`: Any attributes specified for this identity. For more information about attributes, check out [Attribute based access control](https://hyperledger-fabric-ca.readthedocs.io/en/latest/users-guide.html#attribute-based-access-control). These attributes can also be added as a JSON array, therefore the `$ID_ATTRIBUTE` is not meant to represent a single attribute but any and all attributes, which should be placed in the register command after the `--id.attrs` flag. +- `TLSCERT`: The relative path to your the TLS CA root signed certificate (generated when creating the TLS CA). Note that the `-d` flag enables debug mode, which is useful for debugging if the registration fails. @@ -164,13 +164,13 @@ The command looks like this: With these variables: -* `ENROLL_ID`: The enroll ID that was specified when registering this identity. This will have to be communicated to the user of this identity out of band. -* `ENROLL_SECRET`: The enroll secret that was specified when registering this identity. This will have to be communicated to the user of this identity out of band. -* `CA_URL`: The URL of the CA, including the port (which is 7054 by default). If you have configured two CAs at the same location, you will also have to specify a CA name following a `--caname` flag, but in this tutorial we assume you are using a configuration of CAs as specified in the [CA deployment tutorial]. -* `PORT`: The port utilized by the CA you are enrolling with. -* `MSP_FOLDER`: The path to the MSP (the local MSP, if enrolling a node, or the org MSP, if enrolling an admin) on the filesystem. If you do not specify the `--mspdir` flag to specify a location, the certificates will be placed in a folder called `msp` at your current location (if this folder does not already exist, it will be created). -* `CSR_HOSTNAME`: Only relevant when obtaining (enrolling) a TLS certificate against a TLS CA for a node, this will encode the host name(s) or domain name(s) of a node into the TLS certificate Subject Alternative Name (SAN). For multiple names, use a comma-separated list with no spaces. If a host name is dynamic you can specify a wildcard for the domain. For example, when you include the flag `--csr.hosts 'host1,*.example.com'` it means that the hostname `host1` is recognized as well as any host from the `example.com` domain. -* `TLS_CERT`: The relative path to the TLS CA root signed certificate of the TLS CA associated with this organization. +- `ENROLL_ID`: The enroll ID that was specified when registering this identity. This will have to be communicated to the user of this identity out of band. +- `ENROLL_SECRET`: The enroll secret that was specified when registering this identity. This will have to be communicated to the user of this identity out of band. +- `CA_URL`: The URL of the CA, including the port (which is 7054 by default). If you have configured two CAs at the same location, you will also have to specify a CA name following a `--caname` flag, but in this tutorial we assume you are using a configuration of CAs as specified in the [CA deployment tutorial]. +- `PORT`: The port utilized by the CA you are enrolling with. +- `MSP_FOLDER`: The path to the MSP (the local MSP, if enrolling a node, or the org MSP, if enrolling an admin) on the filesystem. If you do not specify the `--mspdir` flag to specify a location, the certificates will be placed in a folder called `msp` at your current location (if this folder does not already exist, it will be created). +- `CSR_HOSTNAME`: Only relevant when obtaining (enrolling) a TLS certificate against a TLS CA for a node, this will encode the host name(s) or domain name(s) of a node into the TLS certificate Subject Alternative Name (SAN). For multiple names, use a comma-separated list with no spaces. If a host name is dynamic you can specify a wildcard for the domain. For example, when you include the flag `--csr.hosts 'host1,*.example.com'` it means that the hostname `host1` is recognized as well as any host from the `example.com` domain. +- `TLS_CERT`: The relative path to the TLS CA root signed certificate of the TLS CA associated with this organization. Here is an example enroll command corresponding to the example register command we used earlier: @@ -184,12 +184,12 @@ Here is a sample of the MSP that will be returned after your enroll the identity ![Enrolled identity](./enrollmentreturn.png) -*The figure above shows the subfolders returned by an enrollment.* +_The figure above shows the subfolders returned by an enrollment._ In certificate naming, it is helpful to use a convention that will help you keep track of whether you are referencing a public certificate or a private key. Given that both have the `.pem` extension, consider the following convention for naming public certs and private keys: -* Rename a public cert from `cert.pem` (which is the default name the Fabric CA will give a public cert) to something meaningful. For example, the public cert of an admin of "Org1" could be given a name like `org1-admin-cert.pem`. -* Rename a private key from `94u498f9r9fr98t49t345545345_sk` to something meaningful like `org1-admin-key.pem`. +- Rename a public cert from `cert.pem` (which is the default name the Fabric CA will give a public cert) to something meaningful. For example, the public cert of an admin of "Org1" could be given a name like `org1-admin-cert.pem`. +- Rename a private key from `94u498f9r9fr98t49t345545345_sk` to something meaningful like `org1-admin-key.pem`. In this convention, the last word in the name before appending the `.pem` extension would be either `cert` or `key` to help you remember which is which. @@ -199,7 +199,7 @@ As we have noted, enrolling an identity with the Fabric CA generates output that However, that does not mean that these folders can simply be dropped into a channel configuration (to join an org to a channel) or into the local configuration of a node (to create a local MSP). In the case of creating an org MSP that can be added to a channel, you will need to remove the private key of the admin. In the case of a local MSP, you will need to add the public certificate of an admin. -For more information about the folders and certificates that are needed in both an org MSP (also known as a "channel MSP", since it is added to a channel) and the local MSP of a node, check out [MSP structure](https://hyperledger-fabric.readthedocs.io/en/master/membership/membership.html#msp-structure). +For more information about the folders and certificates that are needed in both an org MSP (also known as a "channel MSP", since it is added to a channel) and the local MSP of a node, check out [MSP structure](https://hyperledger-fabric.readthedocs.io/en/{FABRIC_VERSION}/membership/membership.html#msp-structure). ### Create the org MSP needed to add an org to a channel @@ -222,12 +222,12 @@ Here is a sample of the folder structure you need to create when you want to add 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. +- `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. +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](#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**. @@ -249,7 +249,7 @@ As with all of the configuration parameters in the YAML file of a node, you have 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](https://hyperledger-fabric.readthedocs.io/en/master/membership/membership.html#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](https://hyperledger-fabric.readthedocs.io/en/{BRANCH}/operations_service.html). +For a look at a sample local MSP, check out [MSP structure](https://hyperledger-fabric.readthedocs.io/en/{FABRIC_VERSION}/membership/membership.html#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](https://hyperledger-fabric.readthedocs.io/en/{FABRIC_VERSION}/operations_service.html). Here is a sample local MSP as it might look when the node has been enrolled and the additional fields have been added: @@ -274,18 +274,17 @@ localmsp 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. +- `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**. - diff --git a/docs/source/operations_guide.rst b/docs/source/operations_guide.rst index 1c6c89075..9c8a6ee88 100644 --- a/docs/source/operations_guide.rst +++ b/docs/source/operations_guide.rst @@ -825,7 +825,7 @@ Create Genesis Block and Channel Transaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The orderer requires a genesis block that it uses to bootstrap itself. -You can find more information in the `Hyperledger Fabric documentation `_ +You can find more information in the `Hyperledger Fabric documentation `_ In documentation below, you'll find a snippet of ``configtx.yaml`` that is written for this specific deployment. For the full ``configtx.yaml``, click :doc:`here `. @@ -1125,4 +1125,4 @@ requires using the organization admin role, for example: export CORE_PEER_ADDRESS=peer1-org1:7051 export CORE_PEER_MSPCONFIGPATH=/tmp/hyperledger/org1/admin/msp -For additional chaincode deployment details see the `Fabric chaincode tutorial `_. \ No newline at end of file +For additional chaincode deployment details see the `Fabric chaincode tutorial `_.