getContentKey

Players use getContentKey to decrypt HLS content. See HTTP Live Streaming (HLS) for details about HLS. See Encrypt content for details about DRM.

Sonos makes this request on your secure (HTTPS) endpoint.

Request parameters

NameTypeDescription
idstring (255)Unique ID of the HLS stream currently playing, the same as what was sent in the [getMediaURI](https://developer.sonos.com/reference/sonos-music-api/getmediauri/) request.
uriuriThe URI for the content key being requested. This is the same URI that we see in the media playlist, tagged as EXT-X-KEY.
deviceSessionTokenstring (2048)(Optional) A token representing the session between a specific Sonos player and your service. The player caches the value that you send in your response and sends it back in this parameter. The Sonos player performs a straight string comparison on the previous value for replacement of the cached value. Thus, the first time the player sends this response, it may not have a value for this parameter.

This data is opaque to Sonos, and is passed as context. It's offered as a lower cost shortcut for encoding session keys. By using tokens, your service does not have to re-validate the device certificate.

While this can be any XML-encoded string, we suggest using hexadecimal characters or base64.

Response

Include the response in a contentKey element in a getContentKeyResponse.

NameTypeDescription
uriuriThe full URI to the audio stream data.
deviceSessionTokenstring (2048)(Optional) A token provided by your service representing the session between your service and a Sonos player. The token is opaque to Sonos and passed back in subsequent calls to use as session context. See the description of the deviceSessionToken in the Parameters table above for details.
deviceSessionKeystring(Optional) A key for the Sonos player to decrypt the contentKey. If this is not included, the contentKey should not be encrypted.

This string should be encrypted using the device certificate and RSA with OAEP. The player will decrypt the string and use the result to decrypt the contentKey string.

This element should have a type attribute that describes the type of encryption your service used to encrypt the contentKey. This attribute is an enum and should be one of the following values:

- NONE for no encryption (this is functionally equivalent to omitting this element).
- AES-ECB for advanced encryption standard electronic codebook encryption.
- AES-CBC for advanced encryption standard cipher block chaining encryption. Separate the key and IV with a colon. See below for details.
contentKeystring(Optional) The encryption key the player uses to decrypt the audio stream content.

This element should have a type attribute that describes the type of encryption your service used to encrypt the content. This attribute is an enum and should be one of the following values:

- NONE for no encryption.
- AES-ECB for advanced encryption standard electronic codebook encryption.
- AES-CBC for advanced encryption standard cipher block chaining encryption. Separate the key and IV with a colon. See below for details.You need to return an encrypted contentKey if you also return the deviceSessionKey. In this case, the player will do the following:

1. Decrypt the deviceSessionKey.
2. Use the decrypted deviceSessionKey to decrypt the contentKey.
3. Use the decrypted contentKey to decrypt the content.

Specify the encryption schema for AES-CBC encryption

For AES-CBC, specify the encryption schema using a colon between the key and initialization vector (IV). Both the key and IV should be in hexadecimal format. The number of characters in the key shall define the size of the key, for example, a 128-bit decryption key will include 32 hex characters. The IV should always be 128-bits (32 hex characters). Valid key lengths are 128-bits (32-chars), 196-bits (48-chars), and 256-bits (64-chars).

Sample request

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
    <soap:Header>
        <ns:credentials>
            <ns:deviceId>A8-F9-32-B0-01-23:0</ns:deviceId>
            <ns:deviceCert>....</ns:deviceCert>
            <ns:zonePlayerId>B8-E9-37-C0-01-18:0</ns:zonePlayerId>
            <ns:deviceProvider>Sonos</ns:deviceProvider>
            <ns:loginToken>
              <ns:token>12345678</ns:token>
              <ns:key>123456789</ns:key>
            </ns:loginToken>
        </ns:credentials>
    </soap:Header>
   <soap:Body>
      <ns:getContentKey>
         <ns:id>...</ns:id>
         <ns:uri>...</ns:uri>
         <ns:deviceSessionToken>234567890-90</ns:deviceSessionToken>
      </ns:getContentKey>
   </soap:Body>
</soap:Envelope>

Sample response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <soap:Body>
      <ns:getContentKeyResponse>
         <contentKey>
            <ns:uri>...</ns:uri>
            <ns:deviceSessionToken>234567890-90</ns:deviceSessionToken>
            <ns:deviceSessionKey type="AES-ECB">FEDBCA9876543210FEDBCA9876543210</ns:deviceSessionKey>
            <ns:contentKey type="AES-CBC">0123456789ABCDEF0123456789ABCDEF:FEDBCA9876543210FEDBCA9876543210</ns:contentKey>
         </contentKey>
      </ns:getContentKeyResponse>
   </soap:Body>
</soap:Envelope>