android.media.MediaCas Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* Copyright (C) 2017 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.media;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.hardware.cas.V1_0.*;
import android.media.MediaCasException.*;
import android.os.Handler;
import android.os.HandlerThread;
import android.os.IHwBinder;
import android.os.Looper;
import android.os.Message;
import android.os.Process;
import android.os.RemoteException;
import android.util.Log;
import android.util.Singleton;
import java.util.ArrayList;
/**
* MediaCas can be used to obtain keys for descrambling protected media streams, in
* conjunction with {@link android.media.MediaDescrambler}. The MediaCas APIs are
* designed to support conditional access such as those in the ISO/IEC13818-1.
* The CA system is identified by a 16-bit integer CA_system_id. The scrambling
* algorithms are usually proprietary and implemented by vendor-specific CA plugins
* installed on the device.
*
* The app is responsible for constructing a MediaCas object for the CA system it
* intends to use. The app can query if a certain CA system is supported using static
* method {@link #isSystemIdSupported}. It can also obtain the entire list of supported
* CA systems using static method {@link #enumeratePlugins}.
*
* Once the MediaCas object is constructed, the app should properly provision it by
* using method {@link #provision} and/or {@link #processEmm}. The EMMs (Entitlement
* management messages) can be distributed out-of-band, or in-band with the stream.
*
* To descramble elementary streams, the app first calls {@link #openSession} to
* generate a {@link Session} object that will uniquely identify a session. A session
* provides a context for subsequent key updates and descrambling activities. The ECMs
* (Entitlement control messages) are sent to the session via method
* {@link Session#processEcm}.
*
* The app next constructs a MediaDescrambler object, and initializes it with the
* session using {@link MediaDescrambler#setMediaCasSession}. This ties the
* descrambler to the session, and the descrambler can then be used to descramble
* content secured with the session's key, either during extraction, or during decoding
* with {@link android.media.MediaCodec}.
*
* If the app handles sample extraction using its own extractor, it can use
* MediaDescrambler to descramble samples into clear buffers (if the session's license
* doesn't require secure decoders), or descramble a small amount of data to retrieve
* information necessary for the downstream pipeline to process the sample (if the
* session's license requires secure decoders).
*
* If the session requires a secure decoder, a MediaDescrambler needs to be provided to
* MediaCodec to descramble samples queued by {@link MediaCodec#queueSecureInputBuffer}
* into protected buffers. The app should use {@link MediaCodec#configure(MediaFormat,
* android.view.Surface, int, MediaDescrambler)} instead of the normal {@link
* MediaCodec#configure(MediaFormat, android.view.Surface, MediaCrypto, int)} method
* to configure MediaCodec.
*
*
Using Android's MediaExtractor
*
* If the app uses {@link MediaExtractor}, it can delegate the CAS session
* management to MediaExtractor by calling {@link MediaExtractor#setMediaCas}.
* MediaExtractor will take over and call {@link #openSession}, {@link #processEmm}
* and/or {@link Session#processEcm}, etc.. if necessary.
*
* When using {@link MediaExtractor}, the app would still need a MediaDescrambler
* to use with {@link MediaCodec} if the licensing requires a secure decoder. The
* session associated with the descrambler of a track can be retrieved by calling
* {@link MediaExtractor#getCasInfo}, and used to initialize a MediaDescrambler
* object for MediaCodec.
*
*
Listeners
* The app may register a listener to receive events from the CA system using
* method {@link #setEventListener}. The exact format of the event is scheme-specific
* and is not specified by this API.
*/
public final class MediaCas implements AutoCloseable {
private static final String TAG = "MediaCas";
private ICas mICas;
private EventListener mListener;
private HandlerThread mHandlerThread;
private EventHandler mEventHandler;
private static final Singleton gDefault =
new Singleton() {
@Override
protected IMediaCasService create() {
try {
return IMediaCasService.getService();
} catch (RemoteException e) {}
return null;
}
};
static IMediaCasService getService() {
return gDefault.get();
}
private void validateInternalStates() {
if (mICas == null) {
throw new IllegalStateException();
}
}
private void cleanupAndRethrowIllegalState() {
mICas = null;
throw new IllegalStateException();
}
private class EventHandler extends Handler
{
private static final int MSG_CAS_EVENT = 0;
public EventHandler(Looper looper) {
super(looper);
}
@Override
public void handleMessage(Message msg) {
if (msg.what == MSG_CAS_EVENT) {
mListener.onEvent(MediaCas.this, msg.arg1, msg.arg2,
toBytes((ArrayList) msg.obj));
}
}
}
private final ICasListener.Stub mBinder = new ICasListener.Stub() {
@Override
public void onEvent(int event, int arg, @Nullable ArrayList data)
throws RemoteException {
mEventHandler.sendMessage(mEventHandler.obtainMessage(
EventHandler.MSG_CAS_EVENT, event, arg, data));
}
};
/**
* Describe a CAS plugin with its CA_system_ID and string name.
*
* Returned as results of {@link #enumeratePlugins}.
*
*/
public static class PluginDescriptor {
private final int mCASystemId;
private final String mName;
private PluginDescriptor() {
mCASystemId = 0xffff;
mName = null;
}
PluginDescriptor(@NonNull HidlCasPluginDescriptor descriptor) {
mCASystemId = descriptor.caSystemId;
mName = descriptor.name;
}
public int getSystemId() {
return mCASystemId;
}
@NonNull
public String getName() {
return mName;
}
@Override
public String toString() {
return "PluginDescriptor {" + mCASystemId + ", " + mName + "}";
}
}
private ArrayList toByteArray(@NonNull byte[] data, int offset, int length) {
ArrayList byteArray = new ArrayList(length);
for (int i = 0; i < length; i++) {
byteArray.add(Byte.valueOf(data[offset + i]));
}
return byteArray;
}
private ArrayList toByteArray(@Nullable byte[] data) {
if (data == null) {
return new ArrayList();
}
return toByteArray(data, 0, data.length);
}
private byte[] toBytes(@NonNull ArrayList byteArray) {
byte[] data = null;
if (byteArray != null) {
data = new byte[byteArray.size()];
for (int i = 0; i < data.length; i++) {
data[i] = byteArray.get(i);
}
}
return data;
}
/**
* Class for an open session with the CA system.
*/
public final class Session implements AutoCloseable {
final ArrayList mSessionId;
Session(@NonNull ArrayList sessionId) {
mSessionId = sessionId;
}
/**
* Set the private data for a session.
*
* @param data byte array of the private data.
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasException for CAS-specific errors.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
public void setPrivateData(@NonNull byte[] data)
throws MediaCasException {
validateInternalStates();
try {
MediaCasException.throwExceptionIfNeeded(
mICas.setSessionPrivateData(mSessionId, toByteArray(data, 0, data.length)));
} catch (RemoteException e) {
cleanupAndRethrowIllegalState();
}
}
/**
* Send a received ECM packet to the specified session of the CA system.
*
* @param data byte array of the ECM data.
* @param offset position within data where the ECM data begins.
* @param length length of the data (starting from offset).
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasException for CAS-specific errors.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
public void processEcm(@NonNull byte[] data, int offset, int length)
throws MediaCasException {
validateInternalStates();
try {
MediaCasException.throwExceptionIfNeeded(
mICas.processEcm(mSessionId, toByteArray(data, offset, length)));
} catch (RemoteException e) {
cleanupAndRethrowIllegalState();
}
}
/**
* Send a received ECM packet to the specified session of the CA system.
* This is similar to {@link Session#processEcm(byte[], int, int)}
* except that the entire byte array is sent.
*
* @param data byte array of the ECM data.
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasException for CAS-specific errors.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
public void processEcm(@NonNull byte[] data) throws MediaCasException {
processEcm(data, 0, data.length);
}
/**
* Close the session.
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
@Override
public void close() {
validateInternalStates();
try {
MediaCasStateException.throwExceptionIfNeeded(
mICas.closeSession(mSessionId));
} catch (RemoteException e) {
cleanupAndRethrowIllegalState();
}
}
}
Session createFromSessionId(@NonNull ArrayList sessionId) {
if (sessionId == null || sessionId.size() == 0) {
return null;
}
return new Session(sessionId);
}
/**
* Query if a certain CA system is supported on this device.
*
* @param CA_system_id the id of the CA system.
*
* @return Whether the specified CA system is supported on this device.
*/
public static boolean isSystemIdSupported(int CA_system_id) {
IMediaCasService service = getService();
if (service != null) {
try {
return service.isSystemIdSupported(CA_system_id);
} catch (RemoteException e) {
}
}
return false;
}
/**
* List all available CA plugins on the device.
*
* @return an array of descriptors for the available CA plugins.
*/
public static PluginDescriptor[] enumeratePlugins() {
IMediaCasService service = getService();
if (service != null) {
try {
ArrayList descriptors =
service.enumeratePlugins();
if (descriptors.size() == 0) {
return null;
}
PluginDescriptor[] results = new PluginDescriptor[descriptors.size()];
for (int i = 0; i < results.length; i++) {
results[i] = new PluginDescriptor(descriptors.get(i));
}
return results;
} catch (RemoteException e) {
}
}
return null;
}
/**
* Instantiate a CA system of the specified system id.
*
* @param CA_system_id The system id of the CA system.
*
* @throws UnsupportedCasException if the device does not support the
* specified CA system.
*/
public MediaCas(int CA_system_id) throws UnsupportedCasException {
try {
mICas = getService().createPlugin(CA_system_id, mBinder);
} catch(Exception e) {
Log.e(TAG, "Failed to create plugin: " + e);
mICas = null;
} finally {
if (mICas == null) {
throw new UnsupportedCasException(
"Unsupported CA_system_id " + CA_system_id);
}
}
}
IHwBinder getBinder() {
validateInternalStates();
return mICas.asBinder();
}
/**
* An interface registered by the caller to {@link #setEventListener}
* to receives scheme-specific notifications from a MediaCas instance.
*/
public interface EventListener {
/**
* Notify the listener of a scheme-specific event from the CA system.
*
* @param MediaCas the MediaCas object to receive this event.
* @param event an integer whose meaning is scheme-specific.
* @param arg an integer whose meaning is scheme-specific.
* @param data a byte array of data whose format and meaning are
* scheme-specific.
*/
void onEvent(MediaCas MediaCas, int event, int arg, @Nullable byte[] data);
}
/**
* Set an event listener to receive notifications from the MediaCas instance.
*
* @param listener the event listener to be set.
* @param handler the handler whose looper the event listener will be called on.
* If handler is null, we'll try to use current thread's looper, or the main
* looper. If neither are available, an internal thread will be created instead.
*/
public void setEventListener(
@Nullable EventListener listener, @Nullable Handler handler) {
mListener = listener;
if (mListener == null) {
mEventHandler = null;
return;
}
Looper looper = (handler != null) ? handler.getLooper() : null;
if (looper == null
&& (looper = Looper.myLooper()) == null
&& (looper = Looper.getMainLooper()) == null) {
if (mHandlerThread == null || !mHandlerThread.isAlive()) {
mHandlerThread = new HandlerThread("MediaCasEventThread",
Process.THREAD_PRIORITY_FOREGROUND);
mHandlerThread.start();
}
looper = mHandlerThread.getLooper();
}
mEventHandler = new EventHandler(looper);
}
/**
* Send the private data for the CA system.
*
* @param data byte array of the private data.
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasException for CAS-specific errors.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
public void setPrivateData(@NonNull byte[] data) throws MediaCasException {
validateInternalStates();
try {
MediaCasException.throwExceptionIfNeeded(
mICas.setPrivateData(toByteArray(data, 0, data.length)));
} catch (RemoteException e) {
cleanupAndRethrowIllegalState();
}
}
private class OpenSessionCallback implements ICas.openSessionCallback {
public Session mSession;
public int mStatus;
@Override
public void onValues(int status, ArrayList sessionId) {
mStatus = status;
mSession = createFromSessionId(sessionId);
}
}
/**
* Open a session to descramble one or more streams scrambled by the
* conditional access system.
*
* @return session the newly opened session.
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasException for CAS-specific errors.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
public Session openSession() throws MediaCasException {
validateInternalStates();
try {
OpenSessionCallback cb = new OpenSessionCallback();
mICas.openSession(cb);
MediaCasException.throwExceptionIfNeeded(cb.mStatus);
return cb.mSession;
} catch (RemoteException e) {
cleanupAndRethrowIllegalState();
}
return null;
}
/**
* Send a received EMM packet to the CA system.
*
* @param data byte array of the EMM data.
* @param offset position within data where the EMM data begins.
* @param length length of the data (starting from offset).
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasException for CAS-specific errors.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
public void processEmm(@NonNull byte[] data, int offset, int length)
throws MediaCasException {
validateInternalStates();
try {
MediaCasException.throwExceptionIfNeeded(
mICas.processEmm(toByteArray(data, offset, length)));
} catch (RemoteException e) {
cleanupAndRethrowIllegalState();
}
}
/**
* Send a received EMM packet to the CA system. This is similar to
* {@link #processEmm(byte[], int, int)} except that the entire byte
* array is sent.
*
* @param data byte array of the EMM data.
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasException for CAS-specific errors.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
public void processEmm(@NonNull byte[] data) throws MediaCasException {
processEmm(data, 0, data.length);
}
/**
* Send an event to a CA system. The format of the event is scheme-specific
* and is opaque to the framework.
*
* @param event an integer denoting a scheme-specific event to be sent.
* @param arg a scheme-specific integer argument for the event.
* @param data a byte array containing scheme-specific data for the event.
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasException for CAS-specific errors.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
public void sendEvent(int event, int arg, @Nullable byte[] data)
throws MediaCasException {
validateInternalStates();
try {
MediaCasException.throwExceptionIfNeeded(
mICas.sendEvent(event, arg, toByteArray(data)));
} catch (RemoteException e) {
cleanupAndRethrowIllegalState();
}
}
/**
* Initiate a provisioning operation for a CA system.
*
* @param provisionString string containing information needed for the
* provisioning operation, the format of which is scheme and implementation
* specific.
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasException for CAS-specific errors.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
public void provision(@NonNull String provisionString) throws MediaCasException {
validateInternalStates();
try {
MediaCasException.throwExceptionIfNeeded(
mICas.provision(provisionString));
} catch (RemoteException e) {
cleanupAndRethrowIllegalState();
}
}
/**
* Notify the CA system to refresh entitlement keys.
*
* @param refreshType the type of the refreshment.
* @param refreshData private data associated with the refreshment.
*
* @throws IllegalStateException if the MediaCas instance is not valid.
* @throws MediaCasException for CAS-specific errors.
* @throws MediaCasStateException for CAS-specific state exceptions.
*/
public void refreshEntitlements(int refreshType, @Nullable byte[] refreshData)
throws MediaCasException {
validateInternalStates();
try {
MediaCasException.throwExceptionIfNeeded(
mICas.refreshEntitlements(refreshType, toByteArray(refreshData)));
} catch (RemoteException e) {
cleanupAndRethrowIllegalState();
}
}
@Override
public void close() {
if (mICas != null) {
try {
mICas.release();
} catch (RemoteException e) {
} finally {
mICas = null;
}
}
}
@Override
protected void finalize() {
close();
}
}