diff --git a/changes/ce/feat-11721.en.md b/changes/ce/feat-11721.en.md index 0dfa3245a..37eac8a5f 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 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. + diff --git a/rel/i18n/emqx_schema.hocon b/rel/i18n/emqx_schema.hocon index 712dc9209..b29e05538 100644 --- a/rel/i18n/emqx_schema.hocon +++ b/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""" diff --git a/scripts/spellcheck/dicts/emqx.txt b/scripts/spellcheck/dicts/emqx.txt index af5a34531..084c49644 100644 --- a/scripts/spellcheck/dicts/emqx.txt +++ b/scripts/spellcheck/dicts/emqx.txt @@ -308,3 +308,4 @@ ElasticSearch doc_as_upsert upsert aliyun +OID