fixup! 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

@@ -72,25 +72,20 @@ This is an existing API to install a trusted certificate into the pool with its
 
 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.
+The new "pool.install_trusted_certificate" should be used instead.
 
-### pool.install_root_certificate
+### pool.install_trusted_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;
 * 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.
+* kind (string): the kind of the certificate; it can be either "ca" or "peer";
+* cert (string): the trusted certificate in PEM format;
+* purpose (string list): the purposes of the trusted certificate.
 
-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;
-* 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 is used to install trusted peer certificates only.
+This new API is used to install trusted certificate.
+The value of *kind* can be "ca", which stands for root CA certificate, or "peer" which stands for peer certificate.
+When *purpose* is an empty set, it stands for a root CA certificate for general purpose.
+The *purpose* can not be an empty set when the *kind* is "peer", because each peer certificate is specific to a single server and therefore unsuitable for a shared trusted certificate for general purpose.
 
 ### pool.uninstall_certificate
 This is a new API introduced in this design to uninstall a trusted certificate with its arguments being defined as:
@@ -124,7 +119,7 @@ This design doesn't change this for backwards compatibility. But the API "pool.i
 
 The pool "Trusted Pool" and "Pool Bundle" are for host-to-host TLS communications within a pool. This design doesn't change them.
 
-The stores for the certificates installed via "pool.install_root_certificate" or "pool.install_peer_certificate" are defined as:
+The stores for the certificates installed via "pool.install_trusted_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.
@@ -137,8 +132,6 @@ The stores for the certificates installed via "pool.install_root_certificate" or
 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 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: