chore: update doc for `partial_chain` and `verify_peer_ext_key_usage`

changes/ce/feat-11721.en.md

@@ -1,5 +1,22 @@
-Port two TLS handshake validation features from emqx 4.4
+Enhance TLS listener to support more flexible TLS verifications.
 
 - partial_chain support
+
+  If the option `partial_chain` is set to `true`, allow connections with incomplete certificate chains.
+  
+  Check the description in emqx schema for more. 
+  
 - Certificate KeyUsage Validation
 
+  Added support for required Extended Key Usage defined in 
+  [rfc5280](https://www.rfc-editor.org/rfc/rfc5280#section-4.2.1.12).
+
+  Introduced a new option (`verify_peer_ext_key_usage`) to require specific key usages (like "serverAuth") 
+  in peer certificates during the TLS handshake.
+  This strengthens security by ensuring certificates are used for their intended purposes.
+
+  example:
+     "serverAuth,OID:1.3.6.1.5.5.7.3.2"
+    
+  Check the description in emqx schema for more. 
+     

rel/i18n/emqx_schema.hocon

@@ -679,13 +679,52 @@ common_ssl_opts_schema_verify.label:
 """Verify peer"""
 
 common_ssl_opts_schema_partial_chain.desc:
-"""Enable or disable peer verification with partial_chain"""
+"""Enable or disable peer verification with partial_chain:
+- `false`
+- `true`
+- `cacert_from_cacertfile`
+- `two_cacerts_from_cacertfile`
+
+When local verifies a peer certificate during the x509 path validation
+process, it constructs a certificate chain that starts with the peer
+certificate and ends with a trust anchor.
+
+By default, if the setting is set to `false`, the trust anchor is the
+rootCA, and the certificate chain must be complete.
+
+If the setting is set to `true` or `cacert_from_cacertfile`,
+the last certificate in the cacertfile will be used as the trust anchor
+certificate (such as an intermediate CA). This creates a partial chain
+in the path validation.
+
+Alternatively, if the setting is set to `two_cacerts_from_cacertfile`,
+one of the last two certificates in the cacertfile will be used as the
+trust anchor certificate, forming a partial chain. This option is
+particularly useful for CA certificate rotation.
+However, please note that it incurs some additional overhead, so it
+should only be used for certificate rotation purposes."""
 
 common_ssl_opts_schema_partial_chain.label:
 """Partial chain"""
 
 common_ssl_opts_verify_peer_ext_key_usage.desc:
-"""Verify Extended Key Usage in Peer's certificate"""
+"""Verify Extended Key Usage in Peer's certificate
+For additional peer certificate validation, the value defined here must present in the
+'Extended Key Usage' of peer certificate defined in
+[rfc5280](https://www.rfc-editor.org/rfc/rfc5280#section-4.2.1.12).
+
+Allowed values are
+- "clientAuth"
+- "serverAuth"
+- "codeSigning"
+- "emailProtection"
+- "timeStamping"
+- "ocspSigning"
+- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2"
+
+Comma-separated string is also supported for validating the subset of key usages.
+
+For example, `"serverAuth,OID:1.3.6.1.5.5.7.3.2"`"""
 
 common_ssl_opts_verify_peer_ext_key_usage.label:
 """Verify KeyUsage in cert"""

scripts/spellcheck/dicts/emqx.txt

@@ -307,3 +307,10 @@ ElasticSearch
 doc_as_upsert
 upsert
 aliyun
+rootCA
+clientAuth
+serverAuth
+codeSigning
+emailProtection
+ocspSigning
+OID