Merge "Define offline methods in DRM HAL version 1.2"

// This file is autogenerated by hidl-gen -Landroidbp.

hidl_interface {

    name: "android.hardware.drm@1.2",

    root: "android.hardware",

    vndk: {

        enabled: true,

    },

    srcs: [

        "types.hal",

        "ICryptoFactory.hal",

        "IDrmFactory.hal",

        "IDrmPlugin.hal",

    ],

    interfaces: [

        "android.hardware.drm@1.0",

        "android.hardware.drm@1.1",

        "android.hidl.base@1.0",

    ],

    types: [

        "KeySetId",

        "OfflineLicenseState",

    ],

    gen_java: false,

}

/*

 * Copyright (C) 2018 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.hardware.drm@1.2;

import @1.1::ICryptoFactory;

/**

 * ICryptoFactory is the main entry point for interacting with a vendor's

 * crypto HAL to create crypto plugins. Crypto plugins create crypto sessions

 * which are used by a codec to decrypt protected video content.

 *

 * The 1.2 factory must always create 1.2 ICryptoPlugin interfaces, which are

 * returned via the 1.0 createPlugin method.

 *

 * To use 1.2 features the caller must cast the returned interface to a

 * 1.2 HAL, using V1_2::IDrmPlugin::castFrom().

 *

 * The ICryptoFactory hal is required because all top-level interfaces

 * have to be updated in a minor uprev.

 */

interface ICryptoFactory extends @1.1::ICryptoFactory {

};

/*

 * Copyright (C) 2018 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.hardware.drm@1.2;

import @1.1::IDrmFactory;

import @1.1::IDrmPlugin;

/**

 * IDrmFactory is the main entry point for interacting with a vendor's

 * drm HAL to create drm plugin instances. A drm plugin instance

 * creates drm sessions which are used to obtain keys for a crypto

 * session so it can decrypt protected video content.

 *

 * The 1.2 factory must always create 1.2 IDrmPlugin interfaces, which are

 * returned via the 1.0 createPlugin method.

 *

 * To use 1.2 features the caller must cast the returned interface to a

 * 1.2 HAL, using V1_2::IDrmPlugin::castFrom().

 *

 * The IDrmFactory hal is required because all top-level interfaces

 * have to be updated in a minor uprev.

 */

interface IDrmFactory extends @1.1::IDrmFactory {

};

/**

 * Copyright (C) 2018 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.hardware.drm@1.2;

import @1.1::IDrmPlugin;

import @1.0::Status;

/**

 * IDrmPlugin is used to interact with a specific drm plugin that was created by

 * IDrm::createPlugin. A drm plugin provides methods for obtaining drm keys that

 * may be used by a codec to decrypt protected video content.

 */

interface IDrmPlugin extends @1.1::IDrmPlugin {

    /**

     * The keys in an offline license allow protected content to be

     * played even if the device is not connected to a network.

     * Offline licenses are stored on the device after a key

     * request/response exchange when the key request KeyType is

     * OFFLINE. Normally each app is responsible for keeping track of

     * the KeySetIds it has created. In some situations however, it

     * may be necessary to request the list of stored offline license

     * KeySetIds. If an app loses the KeySetId for any stored licenses

     * that it created, for example, it must be able to recover the

     * stored KeySetIds so those licenses can be removed when they

     * expire or when the app is uninstalled.

     * <p>

     * This method returns a list of the KeySetIds for all offline

     * licenses. The offline license KeySetId may be used to query

     * the status of an offline license or remove it.

     *

     * @return status the status of the call. May be OK or

     *     ERROR_DRM_INVALID_STATE if the HAL is in a state where the

     *     KeySetIds can't be returned.

     * @return a list of offline license keySetIds. If there are no offline

     *     licenses, the list must be empty and OK must be returned as the

     *     status.

     */

    getOfflineLicenseKeySetIds() generates (Status status, vec<KeySetId> keySetIds);

    /**

     * Normally offline licenses are released using a key

     * request/response exchange using getKeyRequest where the KeyType

     * is RELEASE, followed by provideKeyResponse. This allows the

     * server to cryptographically confirm that the license has been

     * removed and then adjust the count of offline licenses allocated

     * to the device.

     * <p>

     * In some exceptional situations it may be necessary to directly

     * remove offline licenses without notifying the server, which may

     * be performed using this method.

     *

     * @param keySetId the id of the offline license to remove

     * @return status the status of the call. May be one of OK on

     *     success, BAD_VALUE if the license is not found or

     *     ERROR_DRM_INVALID_STATE if the HAL is in a state where the

     *     KeySetIds can't be returned.

     */

    removeOfflineLicense(KeySetId keySetId) generates (Status status);

    /**

     * Request the state of an offline license. An offline license may

     * be usable or inactive. The keys in a usable offline license are

     * available for decryption. When the offline license state is

     * inactive, the keys have been marked for release using

     * getKeyRequest with KeyType RELEASE but the key response has not

     * been received. The keys in an inactive offline license are not

     * usable for decryption.

     *

     * @param keySetId the id of the offline license

     * @return status the status of the call. May be one of OK on

     *     success, BAD_VALUE if the license is not found or

     *     ERROR_DRM_INVALID_STATE if the HAL is in a state where the

     *     offline license state can't be queried.

     * @return the offline license state, one of USABLE or INACTIVE.

     *     If the return status is not OK then state must be set to

     *     UNKNOWN.

     */

    getOfflineLicenseState(KeySetId keySetId) generates (Status status,

            OfflineLicenseState state);

};

/**

 * Copyright (C) 2018 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.hardware.drm@1.2;

enum OfflineLicenseState : uint32_t {

    /**

     * Offline license state is unknown

     */

    UNKNOWN,

    /**

     * Offline license state is usable, the keys may be used for decryption.

     */

    USABLE,

    /**

     * Offline license state is inactive, the keys have been marked for

     * release using {@link #getKeyRequest} with KEY_TYPE_RELEASE but the

     * key response has not been received.

     */

    INACTIVE

};

/**

 * KeySetId is an identifier that references a set of keys in an

 * offline license. The keySetId is created by the HAL implementation

 * and returned from provideKeyResponse and getOfflineLicenseIds. The

 * framework passes KeySetId back to the HAL when referring to the key

 * set in methods that take a KeySetId as an input parameter.

 */

typedef vec<uint8_t> KeySetId;