Clarify csr.hosts in docs

Clarify csr.hosts references in the docs to indicate that
it is used to specify Subject Alternative Names for TLS certificates.
Multiple values can be provided, inculding host names, IP addresses, or domain names (with wildcards).

Signed-off-by: David Enyeart <enyeart@us.ibm.com>

docs/source/deployguide/cadeploy.md

@@ -142,7 +142,7 @@ 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 this hostname and ip address where this server is running, if it is different than what is already in this file. The host 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.
+- `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.
 
@@ -235,7 +235,7 @@ The TLS CA server was started with a bootstrap admin identity (tlsadmin) which h
 
 Notice that the `--mspdir` flag on the command points to the location of TLS CA admin msp certificates that we generated in the previous step. This crypto material is required to be able to register nodes with the TLS CA.
 
-Next, we need to enroll the `rcaadmin` identity to the TLS CA to generate the TLS certificates for the organization CA server. In this case, we use the `--mspdir` flag on the enroll command to designate where the generated organization CA TLS certificates should be stored for the `rcaadmin` identity. Because these certificates are for a different identity, it is a best practice to put them in their own folder. Therefore, instead of generating them in the default `msp` folder, we will put them in a new folder named `rcaadmin` that resides along side the `tlsadmin` folder. Also note that because we are generating a TLS certificate, we must pass `--csr.hosts` to specify the Subject Alternative Name in the generated TLS certificate. The hosts must match the host names that clients will use when communicating to the organization CA server in order for the TLS handshake to succeed.
+Next, we need to enroll the `rcaadmin` identity to the TLS CA to generate the TLS certificates for the organization CA server. In this case, we use the `--mspdir` flag on the enroll command to designate where the generated organization CA TLS certificates should be stored for the `rcaadmin` identity. Because these certificates are for a different identity, it is a best practice to put them in their own folder. Therefore, instead of generating them in the default `msp` folder, we will put them in a new folder named `rcaadmin` that resides along side the `tlsadmin` folder. Also note that because we are generating a TLS certificate, we must pass `--csr.hosts` to specify the Subject Alternative Name (SAN) in the generated TLS certificate. The host names (or domain names) must match the host names (or domain names) that clients will use when communicating to the organization CA server in order for the TLS handshake to succeed. For multiple names, use a comma-separated list with no spaces.
 
 ```
 ./fabric-ca-client enroll -d -u https://rcaadmin:rcaadminpw@my-machine.example.com:7054 --tls.certfiles tls-root-cert/tls-ca-cert.pem --enrollment.profile tls --csr.hosts 'host1,*.example.com' --mspdir tls-ca/rcaadmin/msp
@@ -345,7 +345,7 @@ At a minimum, you should edit the following fields:
 - `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.
 - `ca.name` - Give the organization CA a name by specifying a value in this parameter, for example `org1-ca`.
-- `csr.hosts` - Typically this parameter should be the hostname and ip address where this server is running so that it can be injected into the TLS certificate Subject Alternative Name, however in this case the server will not generate its own TLS certificate (it was generated already from the TLS CA) and therefore no configuration is needed.
+- `csr.hosts` - Typically this parameter should be the hostname, ip address, or domain name where this server is running so that it can be injected into the TLS certificate Subject Alternative Name, however in this case the server will not generate its own TLS certificate (it was generated already from the TLS CA) and therefore no configuration is needed.
 - `csr.ca.pathlength`: This field is used to limit CA certificate hierarchy. Setting this value to `1` for the root CA means the root CA can issue intermediate CA certificates, but these intermediate CAs cannot in turn issue other **CA** certificates. In other words the intermediate CA cannot enroll other intermediate CAs, but it can issue enrollment certificates for users. The default value is `1`.
 - `signing.profiles.ca.caconstraint.maxpathlen` - This field represents the maximum number of non-self-issued intermediate certificates that can follow this certificate in a certificate chain. **If this will be a parent server for an intermediate CA, and you want that intermediate CA to act as a parent CA for another intermediate CA, this root CA needs to set this value to greater than 0 in the configuration .yaml file.** See the instructions for the [signing](ca-config.html#signing) section. The default value is `0`.
 - `operations.listenAddress:` - If there is another CA running on this host, then you need to update this parameter to use a different port.

docs/source/deployguide/use_CA.md

@@ -143,7 +143,7 @@ Note that the `-d` flag enables debug mode, which is useful for debugging if the
 Here is a sample register command for an admin identity:
 
 ```
-./fabric-ca-client register -d --id.name org1admin --id.secret org1adminpw -u https://example.com:7054 --mspdir ./org1-ca/msp --id.type admin --tls.certfiles ../tls/tls-ca-cert.pem --csr.hosts 'host1,*.example.com'
+./fabric-ca-client register -d --id.name org1admin --id.secret org1adminpw -u https://example.com:7054 --mspdir ./org1-ca/msp --id.type admin --tls.certfiles ../tls/tls-ca-cert.pem
 ```
 
 After the identity has been successfully registered, the CA admin would give the enroll ID (`org1admin`) and enroll secret (`org1adminpw`) to the user who will enroll as an admin.
@@ -168,14 +168,14 @@ With these variables:
 * `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 to node identities, this will encode the domain name of a node. For example, MagnetoCorp might choose a hostname of `peer0.mgntoorg.magnetocorp.com`.
+* `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:
 
 ```
-./fabric-ca-client enroll -u https://org1admin:org1adminpw@example.com:7054 --mspdir ./org1.example.com/msp --csr.hosts 'org1,*.example.com' --tls.certfiles ../tls/tls-ca-cert.pem
+./fabric-ca-client enroll -u https://org1admin:org1adminpw@example.com:7054 --mspdir ./org1.example.com/msp --csr.hosts 'host1,*.example.com' --tls.certfiles ../tls/tls-ca-cert.pem
 ```
 
 Unlike a typical CA, in which an enrollment command will return only the public/private key pair, the Fabric CA returns a folder structure called an MSP. This MSP can then be used to create a structure that can be consumed by Fabric when creating nodes or adding organizations to a channel. In the case of enrolling an admin, the MSP forms the basis of an organization. In the case of enrolling a node identity, it forms the basis for the local MSP for the node. Note that this folder structure will also be returned by the TLS CA. However, only the relevant TLS certificates are needed.

docs/source/operations_guide.rst

@@ -65,7 +65,7 @@ and TLS mutual authentication is disabled.
 .. note:: In a production environment, you will probably use your organization's CA
           to get TLS certificates. You will have to transfer out-of-band your CA's
           certificate with organizations that will validate your TLS certificates.
-          Thus, unlike this example, each organization would have its own TLS CA. 
+          Thus, unlike this example, each organization would have its own TLS CA.
 
 A docker service, such as the one below can be used to a launch a Fabric TLS CA
 container.
@@ -410,9 +410,9 @@ band process.
 
 Next step is to get the TLS cryptographic material for the peer. This requires another enrollment,
 but this time you will enroll against the ``tls`` profile on the TLS CA. You will
-also need to provide the address of the Peer1's host machine in the enrollment
-request as the input to the ``csr.hosts`` flag. In the command below, we will
-assume the certificate of the TLS CA has been copied to
+also need to provide the address of the Peer1's host name or domain name in the enrollment
+request as the input to the ``csr.hosts`` flag. This value will be used for the TLS certificate's Subject Alternative Name.
+In the command below, we will assume the certificate of the TLS CA has been copied to
 ``/tmp/hyperledger/org1/peer1/assets/tls-ca/tls-ca-cert.pem``
 on Peer1's host machine.
 
@@ -449,7 +449,7 @@ machine.
 
 Next step is to get the TLS cryptographic material for the peer. This requires another enrollment,
 but this time you will enroll against the ``tls`` profile on the TLS CA. You will
-also need to provide the address of the Peer2's host machine in the enrollment
+also need to provide the address of the Peer2's host name or domain name in the enrollment
 request as the input to the ``csr.hosts`` flag. In the command below, we will
 assume the certificate of the TLS CA has been copied to
 ``/tmp/hyperledger/org1/peer2/assets/tls-ca/tls-ca-cert.pem``

docs/source/users-guide.rst

@@ -249,10 +249,10 @@ The following links shows the :doc:`Server Command Line <servercli>` and
           specified either by specifying the option with comma-separated list
           elements or by specifying the option multiple times, each with a
           string value that make up the list. For example, to specify
-          ``host1`` and ``host2`` for the ``csr.hosts`` option, you can either
+          ``host1`` and ``host2`` as TLS certificate Subject Alternative Names in the ``csr.hosts`` option, you can either
           pass ``--csr.hosts 'host1,host2'`` or
           ``--csr.hosts host1 --csr.hosts host2``. When using the former format,
-          please make sure there are no space before or after any commas.
+          please make sure there are no spaces before or after any commas.
 
 `Back to Top`_