Skip to content

Commit

Permalink
Fix broken URL links
Browse files Browse the repository at this point in the history
Some links refer to the Fabric master branch, both in the GitHub
repository and in the published documentation. The GitHub branch is now
main, and the documentation is categorised by version, with latest
replacing master.

Added a replacement pattern in the doc configuration to specify the
FABRIC_VERSION of the Fabric documentation. References to the Fabric
documentation in the generated docs now use this replacement pattern.

Signed-off-by: Mark S. Lewis <Mark.S.Lewis@outlook.com>
bestbeforetoday authored and denyeart committed Sep 20, 2024

Verified

This commit was signed with the committer’s verified signature.
mkniewallner Mathieu Kniewallner
1 parent 8574fb3 commit 0157e03
Showing 7 changed files with 264 additions and 194 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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.

<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
7 changes: 4 additions & 3 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -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
myst_all_links_external = True
44 changes: 27 additions & 17 deletions docs/source/deployguide/ca-config.md

Large diffs are not rendered by default.

11 changes: 6 additions & 5 deletions docs/source/deployguide/ca-deploy-topology.md
Original file line number Diff line number Diff line change
@@ -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.

Loading

0 comments on commit 0157e03

Please sign in to comment.