Using the SDK within your application

The source code inside sample-app-src.zip contains an Android application that can be used as a reference for integrating SDK. Further information can be found in javadoc.jar.

A customer-specific Operator Vault file (not provided with the SDK or the sample application source) is required to match your SSP configuration. There is also a configuration file in the sample application source that requires adjustment; see the README.md file included in the sample-app-src.zip package.

The general operations you will need to use are as follows:

Access DAS SDK instance

The DAS SDK instance is a singleton accessed through DasApi.instance(). The default DRM scheme when initialising is Widevine, but others can be used by passing the UUID of the scheme as a parameter, for example DasApi.instance(Das.CONNECT_UUID).

Widevine requires no other initialisation, but others may.

Authenticate device and exchange secure keys

A POST request to the Authenticate endpoint of your DAS server ({server_url}/das/v1/{drm_scheme}/authenticate) will need to be made to initially register the app/device on the server.

In the example application, the Retrofit library defines the DAS API endpoints available and makes HTTP requests.

See the com.nagra.das.testapp.service package, in particular DasService.java for details on how that is used.
See the method doAuthenticationRequest() in MainActivity.java for how this can be done.

The response from the Authentication request is not needed for any further actions but gives you the device's server ID and user-friendly model name. Once that has been done, Secure Key Exchange requests can be made ({server_url}/das/v1/{drm_scheme}/secureKeyExchange).

See the method doSecureKeyExchange() in MainActivity.java for how this can be done.

The important thing to note with Secure Key Exchange is that Das.instance().importKeys() must be called on a successful response, passing the encryptedSessionRight element of the response as a parameter. Only then can the other functions be used.

Both of these requests use the DRM challenge string returned from com.nagra.das.sdk.AuthenticationData.dasMessage(). See the DAS API documentation for more information on the format of these requests.

Authentication does not need to be done before each key exchange, but key exchange will fail if authentication has not been done at least once.

Encrypt/decrypt data

For encryption or decryption of a payload, use Das.instance().encrypt() or Das.instance().decrypt(), passing the ClientSession obtained from Das.instance().getAuthenticationData().authSession along with the operator key ID, the encryption initialisation vector and payload to be encrypted.

See encryptClick() and decryptClick() in MainActivity.java.

Sign/verify data

To sign a payload, use Das.instance().sign(), again passing Das.instance().getAuthenticationData().authSession, operators key ID and payload.
To verify a previously signed payload, use Das.instance().verify() passing Das.instance().getAuthenticationData().authSession, operator key ID, payload, and signature obtained from Das.instance().sign().

See signClick() and verifyClick() in MainActivity.java.

setSecurityLevel/getSecurityLevel for Widevine DRM

For WIDEVINE DRM, the default security level depends on the device. To force a different security level other than the default, you can use the DAS setSecurityLevel API.

To set the security level for DAS WIDEVINE DRM session, use Das.instance().setSecurityLevel() with Das.WIDEVINE_SECURITY_LEVEL_L1/L2 or Das.WIDEVINE_SECURITY_LEVEL_L3 as the argument.
To verify the security level set for DAS WIDEVINE DRM session, use Das.instance().getSecurityLevel().

These APIs calls will not set any security level for a DAS CONNECT DRM session.

Multi-DRM

When using multiple DRM systems in your application, you will need to ensure that com.nagra.das.sdk.Das.releaseInstance() is called and the new instance is initialised before attempting to exchange keys again.

CONNECT DRM

As shown below, an opvault file must be loaded when the DAS instance is initialised to use CONNECT DRM.

JAVA

DasApi dasApi = Das.instance(Das.CONNECT_UUID);
//set opvault for connect, where opvault is a byte[]
dasApi.setPropertyByteArray("nagraOpVault", opvault);
AuthenticationData authenticationData = dasApi.getAuthenticationData();
authSession = authenticationData.authSession;
return authenticationData;