From c884b7d6a94c75775529bebd1da22f02e638b12f Mon Sep 17 00:00:00 2001 From: Rohit Joshi Date: Fri, 21 Nov 2025 16:27:16 +0000 Subject: [PATCH 1/6] MTM-65166 Add breaking-change announcement for MQTT CN validation enforcement --- ...ervice-0.9.x-cn-validation-announcement.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md diff --git a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md new file mode 100644 index 0000000000..73b37cfe79 --- /dev/null +++ b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md @@ -0,0 +1,47 @@ +--- +date: 2025-11-XX +title: MQTT Service will enforce CN validation for certificate-authenticated clients +change_type: + - value: change-inv-3bw8e + label: Announcement +product_area: Platform services +component: + - value: component-LcWEQW5gs + label: MQTT +build_artifact: + - value: tc-hc5Tfixeqqei + label: mqtt-service +issue: MTM-65167 +--- + +### Introduction + +To strengthen identity assurance for certificate-authenticated MQTT clients, the {{< product-c8y-iot >}} [MQTT Service](/device-integration/mqtt-service/) will begin enforcing **Common Name (CN) validation** during client certificate authentication. + +Currently, the MQTT Service accepts certificates where the CN does not match the MQTT client ID. +This will change: the CN must correspond to the client ID used during connection, improving device-to-certificate integrity and reducing the risk of certificate misuse. + +### What is changing? + +When an MQTT client connects using certificate-based authentication: + +* The **CN in the certificate must match the MQTT client ID**. +* SmartREST-style identifiers are supported, including: + * `CN == ` + * `CN == "d:"` + +Only clients using certificate-based authentication are affected. +No changes apply to clients using other authentication mechanisms. + +### Impact on existing MQTT clients + +This is a **breaking change**. +Devices using certificates whose CN does not align with the MQTT client ID will fail authentication once enforcement begins. + +Customers should verify and update their certificate issuance processes during the grace period. + +For support, please contact product support. + +### Roll-out plan + +To allow a smooth transition, CN validation will be introduced **four weeks after this announcement**. \ No newline at end of file From 06ec92bfc01c65c860b22c061c55a5a71e572775 Mon Sep 17 00:00:00 2001 From: Rohit Joshi <89976252+rohitjoshi-c8y@users.noreply.github.com> Date: Mon, 24 Nov 2025 15:12:03 +0000 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Scott Mitchell <46353356+scmi-c8y@users.noreply.github.com> --- .../mqtt-service-0.9.x-cn-validation-announcement.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md index 73b37cfe79..5093c2a2a3 100644 --- a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md +++ b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md @@ -1,6 +1,6 @@ --- date: 2025-11-XX -title: MQTT Service will enforce CN validation for certificate-authenticated clients +title: MQTT Service will enforce Common Name validation for certificate-authenticated clients change_type: - value: change-inv-3bw8e label: Announcement @@ -19,7 +19,8 @@ issue: MTM-65167 To strengthen identity assurance for certificate-authenticated MQTT clients, the {{< product-c8y-iot >}} [MQTT Service](/device-integration/mqtt-service/) will begin enforcing **Common Name (CN) validation** during client certificate authentication. Currently, the MQTT Service accepts certificates where the CN does not match the MQTT client ID. -This will change: the CN must correspond to the client ID used during connection, improving device-to-certificate integrity and reducing the risk of certificate misuse. +After this change, the CN must match the client ID used during connection. +This tight binding of certificates to devices will significantly reduce the risk of certificate misuse. ### What is changing? @@ -44,4 +45,4 @@ For support, please contact product support. ### Roll-out plan -To allow a smooth transition, CN validation will be introduced **four weeks after this announcement**. \ No newline at end of file +To allow a smooth transition, CN validation will be introduced no sooner than **four weeks after this announcement**. \ No newline at end of file From 48863d674afb7698d0e7b733cee8f7d9f5b04ad6 Mon Sep 17 00:00:00 2001 From: Rohit Joshi Date: Mon, 24 Nov 2025 15:23:08 +0000 Subject: [PATCH 3/6] Addressed Review Comments --- ...t-service-0.9.x-cn-validation-announcement.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md index 5093c2a2a3..429cbc1207 100644 --- a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md +++ b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md @@ -24,15 +24,15 @@ This tight binding of certificates to devices will significantly reduce the risk ### What is changing? -When an MQTT client connects using certificate-based authentication: +When an MQTT client connects using certificate-based authentication, **the Common Name (CN) in the certificate must match the MQTT client ID**. -* The **CN in the certificate must match the MQTT client ID**. -* SmartREST-style identifiers are supported, including: - * `CN == ` - * `CN == "d:"` +Only **two CN formats** will be accepted for any given client ID: +1. `CN == ` - the standard and **required** format for all new devices. +2. `CN == d:` - supported **only for legacy SmartREST devices** migrating to the MQTT Service. This format must **not** be used for new devices. -Only clients using certificate-based authentication are affected. -No changes apply to clients using other authentication mechanisms. +If the CN does not match one of these two allowed forms for the client ID presented during connection, the client will fail authentication. + +Only certificate-authenticated clients are affected; all other authentication methods remain unchanged. ### Impact on existing MQTT clients @@ -41,7 +41,7 @@ Devices using certificates whose CN does not align with the MQTT client ID will Customers should verify and update their certificate issuance processes during the grace period. -For support, please contact product support. +Please contact [Cumulocity Support](/additional-resources/contacting-support/) if you have any questions or concerns about these changes. ### Roll-out plan From de351d5546bab6deb5ba768f243b4d2b38c879f9 Mon Sep 17 00:00:00 2001 From: Rohit Joshi Date: Fri, 28 Nov 2025 16:23:14 +0000 Subject: [PATCH 4/6] Apply review suggestions --- ...ervice-0.9.x-cn-validation-announcement.md | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md index 429cbc1207..9a19557848 100644 --- a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md +++ b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md @@ -14,6 +14,12 @@ build_artifact: issue: MTM-65167 --- +{{< c8y-admon-caution >}} +This change only affects the new {{< product-c8y-iot >}} [MQTT Service](/device-integration/mqtt-service/) capability. + +The existing {{< product-c8y-iot >}} [Core MQTT](/device-integration/mqtt/) capability is **not** affected. +{{< /c8y-admon-caution >}} + ### Introduction To strengthen identity assurance for certificate-authenticated MQTT clients, the {{< product-c8y-iot >}} [MQTT Service](/device-integration/mqtt-service/) will begin enforcing **Common Name (CN) validation** during client certificate authentication. @@ -24,20 +30,24 @@ This tight binding of certificates to devices will significantly reduce the risk ### What is changing? -When an MQTT client connects using certificate-based authentication, **the Common Name (CN) in the certificate must match the MQTT client ID**. +When an MQTT client connects using certificate-based authentication, **the Common Name (CN) in the certificate must match the MQTT device ID**. + +MQTT clients may identify themselves using either of the following client ID formats: +1. `` – standard format +2. `d:` – supported only for legacy SmartREST devices migrating to the MQTT Service. This format must **not** be used for new devices. + +However, in **both** cases, the certificate’s CN must be: -Only **two CN formats** will be accepted for any given client ID: -1. `CN == ` - the standard and **required** format for all new devices. -2. `CN == d:` - supported **only for legacy SmartREST devices** migrating to the MQTT Service. This format must **not** be used for new devices. +* `CN == ` -If the CN does not match one of these two allowed forms for the client ID presented during connection, the client will fail authentication. +Any certificate whose CN does not equal the device ID will fail authentication. Only certificate-authenticated clients are affected; all other authentication methods remain unchanged. ### Impact on existing MQTT clients This is a **breaking change**. -Devices using certificates whose CN does not align with the MQTT client ID will fail authentication once enforcement begins. +Devices using certificates whose CN does not match the device ID will fail authentication once enforcement begins. Customers should verify and update their certificate issuance processes during the grace period. From 554cfd4206980e66312c1d684d90be1c71f53de0 Mon Sep 17 00:00:00 2001 From: Rohit Joshi Date: Fri, 28 Nov 2025 16:29:55 +0000 Subject: [PATCH 5/6] Apply review suggestions --- .../mqtt-service-0.9.x-cn-validation-announcement.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md index 9a19557848..07c8e0b031 100644 --- a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md +++ b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md @@ -55,4 +55,8 @@ Please contact [Cumulocity Support](/additional-resources/contacting-support/) i ### Roll-out plan +{{< c8y-admon-info >}} +Because the {{< product-c8y-iot >}} [MQTT Service](/device-integration/mqtt-service/) is currently in Public Preview, it is not subject to the standard 6-month compatibility notice period defined in the Cumulocity IoT [Compatibility policy](/service-terms/compatibility-policy/). +{{< /c8y-admon-info >}} + To allow a smooth transition, CN validation will be introduced no sooner than **four weeks after this announcement**. \ No newline at end of file From dc8127a326709ef0c3dbc549e21ffc52de56872a Mon Sep 17 00:00:00 2001 From: Rohit Joshi Date: Tue, 2 Dec 2025 11:16:29 +0000 Subject: [PATCH 6/6] Added date --- .../mqtt-service-0.9.x-cn-validation-announcement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md index 07c8e0b031..2aa3afabde 100644 --- a/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md +++ b/content/change-logs/platform-services/mqtt-service-0.9.x-cn-validation-announcement.md @@ -1,5 +1,5 @@ --- -date: 2025-11-XX +date: 2025-12-02 title: MQTT Service will enforce Common Name validation for certificate-authenticated clients change_type: - value: change-inv-3bw8e