From 01467246fc253f3c64b078d19059ca92c78cea1a Mon Sep 17 00:00:00 2001 From: William Yang Date: Mon, 6 May 2024 17:02:33 +0200 Subject: [PATCH] docs: Apply suggestions from code review Co-authored-by: Zaiming (Stone) Shi --- changes/ce/feat-11721.en.md | 4 ++-- rel/i18n/emqx_schema.hocon | 32 ++++++++++++-------------------- 2 files changed, 14 insertions(+), 22 deletions(-) diff --git a/changes/ce/feat-11721.en.md b/changes/ce/feat-11721.en.md index 42f1f3a2f..37eac8a5f 100644 --- a/changes/ce/feat-11721.en.md +++ b/changes/ce/feat-11721.en.md @@ -4,7 +4,7 @@ Enhance TLS listener to support more flexible TLS verifications. If the option `partial_chain` is set to `true`, allow connections with incomplete certificate chains. - Check the description in emqx schema for more. + Check the configuration manual document for more details. - Certificate KeyUsage Validation @@ -18,5 +18,5 @@ Enhance TLS listener to support more flexible TLS verifications. example: "serverAuth,OID:1.3.6.1.5.5.7.3.2" - Check the description in emqx schema for more. + Check the configuration manual document for more details. diff --git a/rel/i18n/emqx_schema.hocon b/rel/i18n/emqx_schema.hocon index 23cc135e7..0a44ae010 100644 --- a/rel/i18n/emqx_schema.hocon +++ b/rel/i18n/emqx_schema.hocon @@ -679,28 +679,20 @@ common_ssl_opts_schema_verify.label: """Verify peer""" common_ssl_opts_schema_partial_chain.desc: -"""Enable or disable peer verification with partial_chain: -- `false` -- `true` -- `cacert_from_cacertfile` -- `two_cacerts_from_cacertfile` - +"""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 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 +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 the setting is set to `two_cacerts_from_cacertfile`, -one of the last two certificates in the cacertfile will be used as the +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 CA certificate rotation. +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.""" @@ -708,7 +700,7 @@ 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). @@ -720,9 +712,9 @@ Allowed values are - "emailProtection" - "timeStamping" - "ocspSigning" -- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" +- 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 the subset of key usages. +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"`"""