fixup! fixup! fixup! [doc] Improvements on management of trusted certificates

Signed-off-by: Ming Lu <ming.lu@cloud.com>

Author: minglumlu

doc/content/design/trusted-certificates.md

@@ -70,22 +70,27 @@ This is an existing API to install a trusted certificate into the pool with its
 * name (string): the name of the certificate;
 * cert (string): the certificate in PEM format.
 
-In this design, it is used to install root CA certificates only.
-A new argument "purpose" is appended to specify the purposes of the trusted certificate to be installed. By default it is an empty set.
+Prior to this design, the API's name parameter represents the certificate file name as persisted on the dom0 file system.
+In this design, this API will be deprecated because it exposes implementation details that should remain internal and hidden from users.
+The new "pool.install_root_certificate" should be used instead.
+
+### pool.install_root_certificate
+This is a new API introduced in this design with its arguments being defined as:
 * session (ref session_id): reference to a valid session;
-* name (string): the name of the certificate;
-* cert (string): the certificate in PEM format;
-* purpose (string list): the purposes of the certificate
+* self (ref Pool): reference to the pool;
+* cert (string): the trusted root CA certificate in PEM format;
+* purpose (string list): the purposes of the trusted root CA certificate; it stands for a general purpose when it is an empty set.
+
+This new API is used to install trusted root CA certificates only.
 
 ### pool.install_peer_certificate
 This is a new API introduced in this design with its arguments being defined as:
 * session (ref session_id): reference to a valid session;
-* name (string): the name of the certificate;
-* cert (string): the certificate in PEM format;
-* purpose (string list): the purposes of the certificate.
+* self (ref Pool): reference to the pool;
+* cert (string): the trusted peer certificate in PEM format;
+* purpose (string list): the purposes of the trusted peer certificate; can't be an empty set.
 
-This new API can be used to install trusted peer certificates only.
-The "purpose" parameter cannot be empty.
+This new API is used to install trusted peer certificates only.
 
 ### pool.uninstall_certificate
 This is a new API introduced in this design to uninstall a trusted certificate with its arguments being defined as:
@@ -94,10 +99,10 @@ This is a new API introduced in this design to uninstall a trusted certificate w
 * force (bool): remove the database entry even if the file doesn't exist.
 
 ### pool.join
-Since the trusted certificates managed in this design are pool-wide, any existing trusted certificates on the joining host should be removed during pool.join.
-Instead, all trusted certificates from the pool will be synchronized to the new host in the pre-join phase.
+Prior to this design, trusted certificates are exchanged between the pool and the joining host during the pre‑join phase.
+This design preserves that behavior to ensure the joiner works correctly both before and after joining the pool.
 
-### Other APIs
+### Other APIs of managing trusted certificates
 The install/uninstall APIs above are not the only ways of managing the trusted certificates.
 A particular API, e.g. "pool.set_wlb_url", may also install the trusted certificate used to validate the WLB server on subsequent TLS connections.
 However, regardless of the entry point, all trusted certificates must be represented by a *Certificate* database object and stored in the same way described below as if installed by the install APIs.
@@ -112,35 +117,35 @@ The existing stores defined in the base design are:
 | Default Bundle  | /etc/stunnel/xapi-stunnel-ca-bundle.pem | no       | Bundle of certificates that hosts use to verify appliances (in particular WLB), this is kept in sync with "Trusted Default"
 | Pool Bundle     | /etc/stunnel/xapi-pool-ca-bundle.pem    | no       | Bundle of certificates that hosts use to verify other hosts on pool communications, this is kept in sync with "Trusted Pool"
 
-Regarding the "User-configurable", when it is "yes", it means a user can only install and remove the file via APIs; when it is "no", it means the user can't install or remove it even via APIs. In any cases, a user can't change the certificate files directly.
-
-When a trusted certificate is being installed via "pool.install_ca_certificate" but with an empty "purpose",
-the trusted certificate will be stored in the existing "Trusted Default" and "Default Bundle" for general purpose.
+Regarding the "User-configurable", when it is "yes", it means a user can only install and remove the file with "name" parameter of "pool.install_ca_certificate" ; when it is "no", it means the user can't install or remove it even via APIs. In any cases, a user can't change the certificate files directly.
 
-There is no general‑purpose store for trusted peer certificates, because each peer certificate is specific to a single server and therefore unsuitable for a shared trust bundle for general purpose.
+When a trusted certificate is being installed via "pool.install_ca_certificate", the trusted certificate will be stored in the "Trusted Default" and "Default Bundle".
+This design doesn't change this for backwards compatibility. But the API "pool.install_ca_certificate" will be marked as *deprecated*.
 
 The pool "Trusted Pool" and "Pool Bundle" are for host-to-host TLS communications within a pool. This design doesn't change them.
 
-
-When the "purpose" is not empty, the stores for the certificates installed via "pool.install_ca_certificate" or "pool.install_peer_certificate" are defined as:
-| Name | Filesystem location | User-configurable | Used for |
-| ---- | ------------------- | ----------------- | -------- |
-| Trusted Peer | /etc/trusted-certs/peer-\<PURPOSE\>/     | yes (using API) | Trusted peer certificates that users can install to validate a peer’s identity when establishing a TLS connection for \<PURPOSE\>
-| Trusted CA | /etc/trusted-certs/ca-\<PURPOSE\>/         | yes (using API) | Trusted root CA certificates that users can install to validate a peer’s identity when establishing a TLS connection for \<PURPOSE\>
-| Peer Bundle  | /etc/trusted-certs/peer-bundle-\<PURPOSE\>.pem | no | Bundle of trusted peer certificates under /etc/trusted-certs/peer-\<PURPOSE\>/ to verify a peer's identity when establishing a TLS connection for \<PURPOSE\>
-| CA Bundle     | /etc/trusted-certs/ca-bundle-\<PURPOSE\>.pem  | no | Bundle of trusted root CA certificates under /etc/trusted-certs/ca-\<PURPOSE\>/ to verify a peer's identity when establishing a TLS connection for \<PURPOSE\>
+The stores for the certificates installed via "pool.install_root_certificate" or "pool.install_peer_certificate" are defined as:
+| Name | Filesystem location | Used for |
+| ---- | ------------------- | -------- |
+| Trusted General CA | /etc/trusted-certs/ca-general/     | Trusted root CA certificates that users can install to validate a peer’s identity when establishing a TLS connection for general purpose.
+| Trusted Peer | /etc/trusted-certs/peer-\<PURPOSE\>/     | Trusted peer certificates that users can install to validate a peer’s identity when establishing a TLS connection for \<PURPOSE\>.
+| Trusted CA | /etc/trusted-certs/ca-\<PURPOSE\>/         | Trusted root CA certificates that users can install to validate a peer’s identity when establishing a TLS connection for \<PURPOSE\>.
+| General Bundle  | /etc/trusted-certs/ca-bundle-general.pem    | Bundle of trusted root CA certificates under /etc/trusted-certs/ca-general/ to verify a peer's identity when establishing a TLS connection for general purpose.
+| Peer Bundle  | /etc/trusted-certs/peer-bundle-\<PURPOSE\>.pem | Bundle of trusted peer certificates under /etc/trusted-certs/peer-\<PURPOSE\>/ to verify a peer's identity when establishing a TLS connection for \<PURPOSE\>.
+| CA Bundle     | /etc/trusted-certs/ca-bundle-\<PURPOSE\>.pem  | Bundle of trusted root CA certificates under /etc/trusted-certs/ca-\<PURPOSE\>/ to verify a peer's identity when establishing a TLS connection for \<PURPOSE\>.
 
 The filesystem location is derived from the \<PURPOSE\>. Each \<PURPOSE\> string corresponds to a predefined value of the "purpose" type in the database, implemented as predefined constants.
-The certificate file names under filesystem locations of "Trusted Peer" and "Trusted CA" should not rely on the "name" field of *Certificate* objects anymore.
-Instead, the UUIDs of the *Certificate* objects are used as the file names.
+The certificate file names under filesystem locations of "Trusted General CA", "Trusted Peer" and "Trusted CA" will be the UUIDs of the *Certificate* objects.
+
+There is no general‑purpose store for trusted peer certificates, because each peer certificate is specific to a single server and therefore unsuitable for a shared trust bundle for general purpose.
 
 ## Precedence order of choosing trust stores
 The "Peer Bundle", "CA Bundle", and "Default Bundle" can be directly used when establishing TLS connections.
 The endpoint to validate the peer's identity must unambiguously choose only one non-empty bundle from them with the following precedence order:
 1. "Peer Bundle"
 2. "CA Bundle"
-3. "Default Bundle"
+3. "General Bundle"
 
 No more attempts on remaining bundles when validation with the selected one fails (the server certificate is not trusted by the selected bundle).
 
-For example, if "Peer Bundle" doesn't exist and "CA Bundle" (not empty) is selected to do the validation, the endpoint should not try with "Default Bundle" even when the validation with "CA Bundle" failed.
+For example, if "Peer Bundle" doesn't exist and the "CA Bundle" (if not empty) is selected to do the validation, the endpoint should not try with "General Bundle" even when the validation with "CA Bundle" failed.