Merge pull request #12977 from qzhuyan/port/william/5/partial-chain

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 configuration manual document for more details.
+  
 - 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 configuration manual document for more details.
+     

rel/i18n/emqx_schema.hocon

@@ -685,13 +685,44 @@ 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.
+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 it is set to `false`, the trust anchor is the
+Root CA, and the certificate chain must be complete.
+However, if the setting is set to `true` or `cacert_from_cacertfile`,
+the last certificate in `cacertfile` will be used as the trust anchor
+certificate (intermediate CA). This creates a partial chain
+in the path validation.
+Alternatively, if it is configured with `two_cacerts_from_cacertfile`,
+one of the last two certificates in `cacertfile` will be used as the
+trust anchor certificate, forming a partial chain. This option is
+particularly useful for intermediate 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" means `id-pk 2` which is equivalent to `clientAuth`
+
+Comma-separated string is also supported for validating more than one 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

@@ -308,3 +308,4 @@ ElasticSearch
 doc_as_upsert
 upsert
 aliyun
+OID