AWS amazon-mq: Add ActiveMQ TLS certificate SAN verification best practice
Summary
Adds a new best-practices section instructing Amazon MQ for ActiveMQ clients to verify the broker TLS certificate against the subjectAltName (dNSName) extension using the broker endpoint FQDN, not the Common Name, and warns against disabling verification or pinning individual certificates/subjects.
Security assessment
The new section documents safe TLS server-identity verification (RFC 9525 SAN matching) and explicitly warns against disabling certificate verification or pinning certificates/subjects, which otherwise facilitates man-in-the-middle interception of broker connections. It is security hardening guidance, not a fix tied to a specific disclosed vulnerability.
Evidence
+Do not disable certificate verification, and do not pin an individual broker certificate or a specific certificate subject. Amazon MQ rotates broker certificates, and the contents of the certificate subject can change. Clients that pin a certificate or a subject value might fail to connect after a certificate is rotated.
Diff
diff --git a/amazon-mq/latest/developer-guide/best-practices-activemq.md b/amazon-mq/latest/developer-guide/best-practices-activemq.md index e6d483ea3..b32208f7c 100644 --- a//amazon-mq/latest/developer-guide/best-practices-activemq.md +++ b//amazon-mq/latest/developer-guide/best-practices-activemq.md @@ -7 +7 @@ -Never Modify or Delete the Amazon MQ Elastic Network InterfaceAlways Use Connection PoolingAlways Use the Failover Transport to Connect to Multiple Broker EndpointsAvoid Using Message SelectorsPrefer Virtual Destinations to Durable SubscriptionsIf using Amazon VPC peering, avoid client IPs in CIDR range 10.0.0.0/16Disable Concurrent Store and Dispatch for Queues with Slow ConsumersChoose the Correct Broker Instance Type for the Best ThroughputChoose the correct broker storage type for the best throughputConfigure Your Network of Brokers CorrectlyAvoid slow restarts by recovering prepared XA transactions +Never Modify or Delete the Amazon MQ Elastic Network InterfaceAlways Use Connection PoolingAlways Use the Failover Transport to Connect to Multiple Broker EndpointsAvoid Using Message SelectorsPrefer Virtual Destinations to Durable SubscriptionsIf using Amazon VPC peering, avoid client IPs in CIDR range 10.0.0.0/16Disable Concurrent Store and Dispatch for Queues with Slow ConsumersChoose the Correct Broker Instance Type for the Best ThroughputChoose the correct broker storage type for the best throughputConfigure Your Network of Brokers CorrectlyAvoid slow restarts by recovering prepared XA transactionsAlways Verify the Broker TLS Certificate Against Its Subject Alternative Names @@ -209,0 +210,35 @@ In a real-world scenario, you could check your prepared XA transactions against +## Always Verify the Broker TLS Certificate Against Its Subject Alternative Names + +Amazon MQ brokers present a server certificate that identifies the broker by its fully qualified domain name (FQDN). Your client is responsible for verifying this certificate when it establishes a TLS connection. + +**Example FQDNs:** + + + b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.ap-southeast-2.amazonaws.com + b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-2.mq.ap-southeast-2.amazonaws.com + +Every Amazon MQ for ActiveMQ broker instance has its own host name, which always carries an instance suffix. A single-instance broker has one host name, ending in `-1`. An active/standby deployment has two, ending in `-1` and `-2`. The broker certificate covers both names, so a client connecting through the Failover Transport verifies successfully against whichever endpoint it uses. + +Use the host names exactly as Amazon MQ advertises them, including the instance suffix. Verify each endpoint in your Failover Transport URI against the host name in that endpoint. + +We recommend that you configure your client to verify the broker certificate as described in [RFC 9525, Service Identity in TLS](https://www.rfc-editor.org/rfc/rfc9525.html). When your client connects to an Amazon MQ broker, it should do the following: + + * **Use the broker endpoint FQDN as the reference identifier.** Use the FQDN from the broker endpoint returned by the `DescribeBroker` operation, or shown on the broker details page in the Amazon MQ console. Do not derive the identifier from an IP address or from a DNS alias of your own. + + * **Verify the identifier against the`subjectAltName` extension.** Match the broker FQDN against the `dNSName` entries in the certificate `subjectAltName` (SAN) extension. + + * **Do not use the Common Name (CN).** The CN does not identify the broker, and it cannot contain the broker FQDN. Clients that match only the CN, or that require a specific value in the CN, might fail to connect. + + + + +###### Important + +Do not disable certificate verification, and do not pin an individual broker certificate or a specific certificate subject. Amazon MQ rotates broker certificates, and the contents of the certificate subject can change. Clients that pin a certificate or a subject value might fail to connect after a certificate is rotated. + +###### Note + +Most TLS client libraries verify the broker FQDN against the `subjectAltName` extension by default when you supply the broker endpoint host name. If your client overrides the verification hostname, or supplies its own verification callback, make sure that it uses the broker FQDN and matches against `subjectAltName`. + +For more information about Amazon MQ broker certificates, including the certificate types that Amazon MQ issues and annotated examples of each, see [Amazon MQ broker TLS certificates](./amazon-mq-certificates.html). +