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

Name	Type	Description
`id`	string (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.
`uri`	uri	The URI for the content key being requested. This is the same URI that we see in the media playlist, tagged as `EXT-X-KEY`.
`deviceSessionToken`	string (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.

Name	Type	Description
`uri`	uri	The full URI to the audio stream data.
`deviceSessionToken`	string (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.
`deviceSessionKey`	string	(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.
`contentKey`	string	(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>