From c3f8ba57623cdb9c4439f7894d1c2fac4c3dcedb Mon Sep 17 00:00:00 2001 From: William Yang Date: Mon, 6 May 2024 11:17:45 +0200 Subject: [PATCH] chore: update doc for `partial_chain` and `verify_peer_ext_key_usage` --- changes/ce/feat-11721.en.md | 19 +++++++++++++- rel/i18n/emqx_schema.hocon | 43 +++++++++++++++++++++++++++++-- scripts/spellcheck/dicts/emqx.txt | 7 +++++ 3 files changed, 66 insertions(+), 3 deletions(-) diff --git a/changes/ce/feat-11721.en.md b/changes/ce/feat-11721.en.md index 0dfa3245a..42f1f3a2f 100644 --- a/changes/ce/feat-11721.en.md +++ b/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. + diff --git a/rel/i18n/emqx_schema.hocon b/rel/i18n/emqx_schema.hocon index 2df26b2d3..23cc135e7 100644 --- a/rel/i18n/emqx_schema.hocon +++ b/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""" diff --git a/scripts/spellcheck/dicts/emqx.txt b/scripts/spellcheck/dicts/emqx.txt index d68c85716..218ef3795 100644 --- a/scripts/spellcheck/dicts/emqx.txt +++ b/scripts/spellcheck/dicts/emqx.txt @@ -307,3 +307,10 @@ ElasticSearch doc_as_upsert upsert aliyun +rootCA +clientAuth +serverAuth +codeSigning +emailProtection +ocspSigning +OID