Key/License Protection with the Native SDKs

Introduction

Key/license protection offers an extra level of security when using Dynamic Delivery with DRM-protected or HTTP Live Streaming Encryption (HLSe) content. License requests can be authenticated using a signed JSON Web Token (JWT).

The token is used when requesting the video license, once the video has been loaded to the player and the source has been selected.

If you are not familiar with this feature, see the Overview: Brightcove Playback Restrictions document.

Android Implementation

The Native SDK for Android currently supports Key/license protection for HLSe and Widevine DASH sources. You will provide your authorization token as part of the Brightcove catalog request for a single video or a playlist.

To make a Brightcove catalog request, follow these steps:

1. Create an HttpRequestConfig object and set the Brightcove Authorization token as shown here:

   HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
     .setBrightcoveAuthorizationToken("your jwt token")
     .build();
   

   The value of the Authorization token will be the value of your JSON Web Token.

2. Once you have created the HttpRequestConfig object, pass it to one of the following Catalog methods:

   For a video request, use one of the following:

   findVideoByID(String, HttpRequestConfig, VideoListener)
   

   findVideoByReferenceID(String, HttpRequestConfig, VideoListener)
   

   For a playlist request, use one of the following:

   findPlaylistByID(String, HttpRequestConfig, PlaylistListener)
   

   findPlaylistByReferenceID(String, HttpRequestConfig, PlaylistListener)
   

   The details of token usage for HLSe and Widevine license acquisition are handled by the SDK.

Code example

Here is an example that shows how to pass your authorization token when making a Catalog request:

String myToken = "...";
HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
  .setBrightcoveAuthorizationToken(myToken)
  .build();
…

Catalog catalog = new Catalog(eventEmitter, accountId, policyKey, playbackApiBaseUrl);
catalog.findVideoByReferenceID(videoReferenceId, httpRequestConfig, new VideoListener(){...});

Offline Playback

The OfflineCatalog findVideo, requestPurchaseLicense and requestRentalLicense methods all take an HttpRequestConfig as an argument.

Here's an example:

private HttpRequestConfig httpRequestConfig;
private String pasToken = "your jwt token";
...
HttpRequestConfig.Builder httpRequestConfigBuilder = new HttpRequestConfig.Builder();
httpRequestConfigBuilder.setBrightcoveAuthorizationToken(pasToken);
httpRequestConfig = httpRequestConfigBuilder.build();
playlist.findPlaylist(catalog, httpRequestConfig, new PlaylistListener() {
    @Override
    public void onPlaylist(Playlist playlist) {
        videoListAdapter.setVideoList(playlist.getVideos());
        onVideoListUpdated(false);
        brightcoveVideoView.addAll(playlist.getVideos());
    }

    @Override
    public void onError(String error) {
        String message = showToast("Failed to find playlist[%s]: %s", playlist.displayName, error);
        Log.w(TAG, message);
        onVideoListUpdated(true);
    }
});

For details, see the Offline Playback sample app.

Responses

The following responses are associated with PAS:

• 200 - License is allowed to continue
• 401 - The License delivery must not be allowed to continue

Limitations

There is a limitation with the current release:

• Chromecast is not supported with key/license protection.

iOS Implementation

When using key/license protection, you will need to use the playback service methods that allow you to pass in your authorization token. This is done using the authToken parameter.

For a video request, use one of the following:

- (void)findVideoWithVideoID:(NSString *)videoID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler;

- (void)findVideoWithReferenceID:(NSString *)referenceID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler;

For a playlist request, use one of the following:

- (void)findPlaylistWithPlaylistID:(NSString *)playlistID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler;

- (void)findPlaylistWithReferenceID:(NSString *)referenceID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler;

The details of token usage for HLSe and FairPlay license acquisition are handled by the SDK.

For details, see the Playback Authorization Service section of the Native SDK for iOS reference.

Offline Playback

If you are using the Playback Authorization Service with Offline Playback, there is a new method for renewing a FairPlay license which accepts an authorization token:

// Request license renewal
    [BCOVOfflineVideoManager.sharedManager renewFairPlayLicense:offlineVideoToken
        video:video // recent video from Playback API or Playback Service class
        authToken: authToken
        Parameters: parameters
        completion:^(BCOVOfflineVideoToken offlineVideoToken, NSError *error)
    {
        // handle errors
    }];

When license renewal is finshed, the completion block will be called with the same offline video token that was passed in. An NSError will indicate any problem that occurred (or nil if no error).

For details, see the Renewing a FairPlay License section of the Native SDK for iOS reference.

Responses

The following responses are associated with PAS:

• 200 - License is allowed to continue
• 401 - The License delivery must not be allowed to continue