Sonos Music API - Getting Started Guide

TLS/SSL Security Overview

As more private data migrates online, services that handle this data have to consider enabling stronger security protocols. Therefore, Sonos requires that you implement the Transport Layer Security (TLS) and Secure Sockets Layer (SSL) security requirements listed below in your Sonos Music API (SMAPI) implementation.

Sonos players are embedded systems with limited memory and a small number of Certificate Authority (CA) certificates preinstalled. If you don't use one of the preinstalled CA certificates, we also verify certificates remotely by querying a list of CAs on our own hosted service. However, occasionally this may be less reliable than using embedded certificates.

To avoid interruption of your service, we recommend that you use a certificate from one of the CAs listed below. If you have to use one from a CA that is not on the list, please coordinate with us by emailing us at partnerships@sonos.com. Since we would have to support the certificate on an embedded device, it may take some time for us to make a change available to all Sonos users. Therefore we ask that you give us as much advance notice as you can so that we can work with you to ensure continuity of service.

Security Requirements

In order to be listed on the Sonos Audio Platform, your music service must:

  • Implement HTTPS to protect the SecureURI endpoint in the SMAPI Service Configuration (see the Secure Endpoint URL in Adding a Service for an example). Use of HTTPS for serving content is supported, but optional.
    Note that your content could be compromised and stolen if you choose to allow HTTP access to your SMAPI SOAP service. To secure your content, be sure to test that calls such as getMediaURI do not work over HTTP.
  • HTTPS endpoints must support Transport Layer Security (TLS) 1.2.
  • Support at least one of the following cipher suites:
    • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (secp256r1 elliptic curve)
    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (secp256r1 elliptic curve)
    • TLS_RSA_WITH_AES_256_GCM_SHA384
    • TLS_RSA_WITH_AES_128_GCM_SHA256
    • TLS_RSA_WITH_AES_256_CBC_SHA256
    • TLS_RSA_WITH_AES_256_CBC_SHA
    • TLS_RSA_WITH_AES_128_CBC_SHA256
    • TLS_RSA_WITH_AES_128_CBC_SHA
  • Have a valid X.509 certificate for the DNS name. See the Common Reasons for SSL Handshake Failures section below for details.
  • Support RFC 5746.
  • Not use an SSL/TLS implementation exposed to any known vulnerabilities, for example, Heartbleed or CRIME.

Future Requirements: dropping TLS 1.0 and TLS 1.1 Support

In upcoming releases, we plan to drop support for TLS 1.0 and TLS 1.1, following the industry best practices.

Certificate Authorities Trusted by Sonos players

We store certificates for the following Certificate Authorities (CAs) locally on our players and controllers. If you aren't using one of them, please let us know by emailing us at partnerships@sonos.com. Additionally, if you are switching your commercial Certificate Authority to one that is not on the list, we recommend that you let us know in advance of the switch to ensure a smooth transition.

The current Certificate Authority certificates trusted by Sonos products are listed below by common name, except where indicated. This list may change with future Sonos software updates.

  • AddTrust External CA Root
  • Baltimore CyberTrust Root
  • DigiCert Global Root CA
  • DigiCert Global Root G2
  • DigiCert High Assurance EV Root CA
  • DST Root CA X3
  • GeoTrust Global CA
  • GlobalSign Root CA
  • GlobalSign RootCA - R2 *
  • GlobalSign Root CA - R3 *
  • Go Daddy Root Certificate Authority - G2
  • SecureTrust CA
  • Starfield Class 2 Certification Authority *

* organization and/or organizational unit

Testing your certificate

We run tests against your service to ensure that your service supports our security requirements. These may be useful to you as well. To run them, your OpenSSL library version needs to be at least 1.0.1. The ssl_validation tests are in the Python Self-Test Suite (download this from the QUALITY & TESTING TOOLS SUITE section on the front page). Validation of a certificate chain is done locally if the root CA or an intermediate CA is one from the list above. We run the following tests:

  • test_use_secure_endpoint - verifies that your secure end point is using HTTPS.
  • test_support_tls_10 - verifies that your server supports TLS 1.0.
  • test_support_secure_renegotiation - verifies that your server supports secure renegotiation (RFC 5746). Secure renegotiation prevents an attacker from injecting traffic of their own as a prefix to the intercepted client's interaction with the server. Note that your server must support secure renegotiation although Sonos does not support any renegotiation. However, it is unlikely that this could cause an interoperability problem between Sonos and your service. The following are two places where renegotiation tends to get used:
    • For servers that require client authentication only on some URLs but not all.
    • For persistent data connections with such long lifetimes that the other party wants to change the session key.
  • test_DNS_has_valid_x509_certificate - verifies that your server has a valid X.509 certificate that matches the DNS name. See RFC 5280, section 3.1 for more details about X.509 Public Key Infrastructure certificates.
  • test_certificate_expiration - verifies that the leaf certificate is not expired. This test warns you if it will expire within 30 days.
  • test_certificate_chain - verifies that the entire certificate chain for the secure endpoint is valid.

Note that the results of the ssl_validation tests are only valid if DNS and TCP are working. You should test those before deciding that there are SSL problems. 

Additionally, if you are implementing DeviceLink, be sure that all tokens have a short life. For details about token life spans, please refer to Implementing OAuth 2.0 Token Refresh tutorial.

What happens if your certificate fails in production?

If your certificate isn’t configured properly or has expired, your service will fail on Sonos. Users will not be able to browse your service on Sonos.

COMMON REASONS FOR SSL HANDSHAKE FAILURES

  • Expired certificate: Every certificate has a validity window before it expires. You need to present Sonos with unexpired certificates.
  • DNS name mismatch: Your certificate must match the DNS name used in the Sonos service catalog. If the URL in the Sonos service catalog is https://stremingservice.example.com/svc then your certificate must have a subjectAltName or a Common Name matching streamingservice.example.com. Any mismatches will cause an outage. For example, this may occur if you introduce a Content Delivery Network (CDN) into your setup as this may affect the DNS names and certificates involved.
  • Missing intermediate CA cert: Most certificate authorities do not issue individual server certificates directly from their root CA certificate. They often use an intermediate CA certificate. Usually the chain looks like this:
    Root CA certificate -> intermediate CA certificate -> your service’s SSL server certificate.
    In these cases, you must configure your SSL server to send Sonos the intermediate CA certificate as well as your SSL server certificate. Without this, Sonos will not be able to validate the full chain and the validation may fail.