From c3f8ba57623cdb9c4439f7894d1c2fac4c3dcedb Mon Sep 17 00:00:00 2001 From: William Yang Date: Mon, 6 May 2024 11:17:45 +0200 Subject: [PATCH 1/3] 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 From 01467246fc253f3c64b078d19059ca92c78cea1a Mon Sep 17 00:00:00 2001 From: William Yang Date: Mon, 6 May 2024 17:02:33 +0200 Subject: [PATCH 2/3] 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"`""" From 28b17a25624409553c50cf5c31e79985f7cae376 Mon Sep 17 00:00:00 2001 From: William Yang Date: Mon, 6 May 2024 21:02:19 +0200 Subject: [PATCH 3/3] chore: fix nit for spellcheck --- rel/i18n/emqx_schema.hocon | 12 ++++++------ scripts/spellcheck/dicts/emqx.txt | 6 ------ 2 files changed, 6 insertions(+), 12 deletions(-) diff --git a/rel/i18n/emqx_schema.hocon b/rel/i18n/emqx_schema.hocon index 0a44ae010..a4565842d 100644 --- a/rel/i18n/emqx_schema.hocon +++ b/rel/i18n/emqx_schema.hocon @@ -706,12 +706,12 @@ For additional peer certificate validation, the value defined here must present [rfc5280](https://www.rfc-editor.org/rfc/rfc5280#section-4.2.1.12). Allowed values are -- "clientAuth" -- "serverAuth" -- "codeSigning" -- "emailProtection" -- "timeStamping" -- "ocspSigning" +- `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. diff --git a/scripts/spellcheck/dicts/emqx.txt b/scripts/spellcheck/dicts/emqx.txt index 218ef3795..3e7b811ff 100644 --- a/scripts/spellcheck/dicts/emqx.txt +++ b/scripts/spellcheck/dicts/emqx.txt @@ -307,10 +307,4 @@ ElasticSearch doc_as_upsert upsert aliyun -rootCA -clientAuth -serverAuth -codeSigning -emailProtection -ocspSigning OID