Apply suggestions from code review

Co-authored-by: Ivan Blinkov <ivan@blinkov.ru>

ydb/docs/en/core/devops/manual/node-authorization.md

@@ -1,22 +1,22 @@
 # Database node authentication and authorization
 
-Node authentication in the {{ ydb-short-name }} cluster ensures that database nodes are authenticated when making service requests to other nodes via the gRPC protocol. Node authorization ensures that the privileges required by the service requests are checked and granted during the request processing. These service calls include the database nodes registration within the cluster and access the [dynamic configuration](../../maintenance/manual/dynamic-config.md) information. The use of node authorization is recommended for all {{ ydb-short-name }} clusters, as it allows to avoid the unauthorized access to data by adding the nodes controlled by an attacker into the cluster.
+Node authentication in the {{ ydb-short-name }} cluster ensures that database nodes are authenticated when making service requests to other nodes via the gRPC protocol. Node authorization ensures that the privileges required by the service requests are checked and granted during request processing. These service calls include database node registration within the cluster and access to [dynamic configuration](../../maintenance/manual/dynamic-config.md) information. The use of node authorization is recommended for all {{ ydb-short-name }} clusters, as it helps prevent unauthorized access to data by adding nodes controlled by an attacker to the cluster.
 
-Database node authentication and authorization is performed in the following order:
+Database node authentication and authorization are performed in the following order:
 
-1. The database node being started opens a gRPC connection to one of the cluster storage nodes specified in the `--node-broker` command line option. The connection uses the TLS protocol, and the certificate of the running node is used as the client certificate for the connection.
-2. The storage node and the database node perform mutual authentication checks using the TLS protocol: the certificate trust chain is checked and the host name is matched against the value of the "Subject Name" field of the certificate.
+1. The database node being started opens a gRPC connection to one of the cluster storage nodes specified in the `--node-broker` command-line option. The connection uses the TLS protocol, and the certificate of the running node is used as the client certificate for the connection.
+2. The storage node and the database node perform mutual authentication checks using the TLS protocol: the certificate trust chain is checked, and the hostname is matched against the value of the "Subject Name" field of the certificate.
 3. The storage node checks the "Subject" field of the certificate for compliance with the requirements set in the static configuration.
-4. If the above checks are successful, the connection from the database node is considered as authenticated, and it gets assigned a special [SID](../../concepts/glossary.md#access-sid), determined by the settings.
-5. The database node uses the established gRPC connection to register with the cluster and to obtain the dynamic configuration through the corresponding service requests.
+4. If the above checks are successful, the connection from the database node is considered authenticated, and it is assigned a special [SID](../../concepts/glossary.md#access-sid) determined by the settings.
+5. The database node uses the established gRPC connection to register with the cluster and obtain the dynamic configuration through the corresponding service requests.
 6. The storage node checks whether the SID assigned to the connection is in the list of acceptable ones. If this check is successful, the storage node performs the requested action.
 
 Below are the steps required to enable the node authentication and authorization feature.
 
-## Configuration pre-requisites
+## Configuration prerequisites
 
-1. The deployed {{ ydb-short-name }} cluster should have the [gRPC traffic encryption](../../reference/configuration/tls.md#grpc) configured for using the TLS protocol.
-1. When preparing node certificates for a cluster where you plan to use the node authorization feature, the uniform rules must be used for populating the "Subject" field of the certificates, which allows to identify the certificates issued for the cluster nodes. For more information, see the [certificate verification rules documentation](../../reference/configuration/node-authentication.md).
+1. The deployed {{ ydb-short-name }} cluster must have [gRPC traffic encryption](../../reference/configuration/tls.md#grpc) configured to use the TLS protocol.
+1. When preparing node certificates for a cluster where you plan to use the node authorization feature, uniform rules must be used for populating the "Subject" field of the certificates. This allows the identification of certificates issued for the cluster nodes. For more information, see the [certificate verification rules documentation](../../reference/configuration/node-authentication.md).
 
     {% note info %}
 
@@ -26,13 +26,13 @@ Below are the steps required to enable the node authentication and authorization
 
 1. The command-line parameters for [starting database nodes](../../devops/manual/initial-deployment.md#start-dynnode) must include options that specify the paths to the trusted CA certificate, the node certificate, and the node key files. The required additional command-line options are shown in the table below.
 
-    | **Command line option**    | **Description** |
-    |----------------------------|-----------------|
-    | `--grpc-ca`                | Path to trusted certification authority file `ca.crt` |
-    | `--grpc-cert`              | Path to node certificate file `node.crt` |
-    | `--grpc-key`               | Path to node secret key file `node.key` |
+    | **Command-line option** | **Description** |
+    |-------------------------|-----------------|
+    | `--grpc-ca`             | Path to the trusted certification authority file `ca.crt` |
+    | `--grpc-cert`           | Path to the node certificate file `node.crt` |
+    | `--grpc-key`            | Path to the node secret key file `node.key` |
 
-    Below is the example of the complete command to start the database node, with the extra options for gRPC TLS key and certificate files:
+    Below is an example of the complete command to start the database node, including the extra options for gRPC TLS key and certificate files:
 
     ```bash
     /opt/ydb/bin/ydbd server --yaml-config  /opt/ydb/cfg/config.yaml --tenant /Root/testdb \

ydb/docs/en/core/reference/configuration/node-authentication.md

@@ -1,16 +1,16 @@
 # Database node authentication
 
-Database node authentication within the {{ ydb-short-name }} cluster ensures that service connections between cluster nodes are assigned the correct security identifiers, or [SIDs](../../concepts/glossary.md#access-sid). The process of database node authentication applies to connections that use the gRPC protocol and provide functions for registering nodes in the cluster, as well as for accessing configuration information. SIDs assigned to connections are taken into account when checking the authorization rules that apply to the corresponding gRPC service calls.
+Database node authentication within the {{ ydb-short-name }} cluster ensures that service connections between cluster nodes are assigned the correct security identifiers, or [SIDs](../../concepts/glossary.md#access-sid). The process of database node authentication applies to connections that use the gRPC protocol and provide functions for registering nodes in the cluster, as well as for accessing configuration information. SIDs assigned to connections are considered when checking the authorization rules that apply to the corresponding gRPC service calls.
 
 Node authentication settings are configured within the [static configuration](./index.md) of the cluster.
 
-## client_certificate_authorization - node authentication settings
+## client_certificate_authorization – node authentication settings
 
-This section specified the authentication settings for database node connections, by defining the requirements for the content of "Subject" and "Subject Alternative Name" node certificates, and the list of [SID](../../concepts/glossary.md#access-sid) values being assinged to the connections.
+This section specifies the authentication settings for database node connections by defining the requirements for the content of the "Subject" and "Subject Alternative Name" fields in node certificates, as well as the list of [SID](../../concepts/glossary.md#access-sid) values assigned to the connections.
 
-The "Subject" field of the node certificate may contain multiple components (such as `O` - organization, `OU` - organizational unit, `C` - country, `CN` - common name), and checks can be configured against one or more of these components.
+The "Subject" field of the node certificate may contain multiple components (such as `O` – organization, `OU` – organizational unit, `C` – country, `CN` – common name), and checks can be configured against one or more of these components.
 
-The "Subject Alternative Name" field of the node certificate is the list of network names or IP-addresses of the node. Checks can be configured to match the names specified in the certificate against the expected values.
+The "Subject Alternative Name" field of the node certificate is a list of the node's network names or IP addresses. Checks can be configured to match the names specified in the certificate against the expected values.
 
 ### Syntax
 
@@ -34,17 +34,17 @@ client_certificate_authorization:
 
 Key  | Description
 ---- | ---
-`request_client_certificate` | Request the valid client certificate for node connections.<br/>Allowed values:<br/><ul><li>`false` — certificate is not required (used by default if the parameter is omitted);</li><li>`true` — certificate is required for all node connections.</li></ul>
-`default_group` | SID being assigned to all connections providing the trusted client certificate when no explicit settings are provided in the `client_certificate_definitions` section
-`client_certificate_definitions` | Section defining the requirements for database node certificates
-`member_groups` | SIDs which are assigned to the connections that conform to the requirements of the current configuration block
-`require_same_issuer` | Require that the value of the "Issuer" field (typically containing the Certification Authority name) should be the same for the client (database node) and server (storage node) certificates.<br/>Allowed values:<br/><ul><li>`true` — the values must be the same (used by default if the parameter is omitted);</li><li>`false` — the values can be different (which effectively means that client and server certificates may be issued by different Certification Authorities).</li></ul>
-`subject_dns` | Allowed values for the "Subject Alternative Name" field, specified as allowed full values (sub-key `values` used) or allowed suffixes (sub-key `suffixes` used). The check is successful when the actual value matches any full name or any suffix specified.
-`subject_terms` | The requirements for the "Subject" field value. Contains the component name (in the sub-key `short_name`), and the list of full values (sub-key `values`) or suffixes (sub-key `suffixes`). The check is successful when the actual value of each component matches either the allowed full value, or the allowed suffix.
+`request_client_certificate` | Request a valid client certificate for node connections.<br/>Allowed values:<br/><ul><li>`false` — A certificate is not required (used by default if the parameter is omitted).</li><li>`true` — A certificate is required for all node connections.</li></ul>
+`default_group` | SID assigned to all connections providing a trusted client certificate when no explicit settings are provided in the `client_certificate_definitions` section.
+`client_certificate_definitions` | Section defining the requirements for database node certificates.
+`member_groups` | SIDs assigned to connections that conform to the requirements of the current configuration block.
+`require_same_issuer` | Require that the value of the "Issuer" field (typically containing the Certification Authority name) is the same for both client (database node) and server (storage node) certificates. <br/>Allowed values:<br/><ul><li>`true` — The values must be the same (used by default if the parameter is omitted).</li><li>`false` — The values can be different (allowing client and server certificates to be issued by different Certification Authorities).</li></ul>
+`subject_dns` | Allowed values for the "Subject Alternative Name" field, specified as either full values (using the `values` sub-key) or suffixes (using the `suffixes` sub-key). The check is successful if the actual value matches any full name or any suffix specified.
+`subject_terms` | Requirements for the "Subject" field value. Contains the component name (in the `short_name` sub-key) and a list of full values (using the `values` sub-key) or suffixes (using the `suffixes` sub-key). The check is successful if the actual value of each component matches either an allowed full value or an allowed suffix.
 
 ### Examples
 
-The next configuration fragment enables node authentication, and requires the "Subject" field to include the component `O=YDB`. Upon successful authentication, the connection will be assigned the `registerNode@cert` SID.
+The following configuration fragment enables node authentication and requires the "Subject" field to include the component `O=YDB`. Upon successful authentication, the connection is assigned the `registerNode@cert` SID.
 
 ```yaml
 client_certificate_authorization: