The DRM provides functions for drm devices.

Required Header

#include <hal-drm.h>

Overview

The drm devices have various specifications, so it's hard to control them using single code. The drm HAL provides common abstraction interfaces to control drm devices which are different.

The DRM HAL allows creation of components required in secure playback including:

managing drm sessions.
device provisioning.
decrypt DRM content.

State Diagram

State Transitions

FUNCTION	PRE-STATE	POST-STATE	SYNC TYPE
hal_drm_init()	NONE	INITIALIZED	SYNC
hal_drm_deinit()	INITIALIZED	NONE	SYNC

For more information on the DRM features and the macros, see HAL DRM programming guides and tutorials.

Typedefs
typedef enum hal_drm_error	hal_drm_error_e
	Enumeration for the DRM error.
typedef enum hal_drm_state	hal_drm_state_e
	Enumeration for the DRM state.
typedef enum hal_drm_command	hal_drm_command_e
	Enumeration for the DRM command.
typedef struct hal_drm_batch_command_control	hal_drm_batch_command_control_s
	The structure type of batch command.
typedef enum hal_drm_message_type	hal_drm_message_type_e
	Enumeration for the DRM message type.
typedef struct hal_drm_message	hal_drm_message_s
	The structure type of the DRM message.
typedef int(*	hal_drm_message_cb )(hal_drm_message_s message, void user_data)
	Callback function for notification from DRM HAL.
typedef enum hal_drm_media_type	hal_drm_media_type_e
	Enumeration for encrypted content media type.
typedef enum hal_drm_cipher_phase	hal_drm_cipher_phase_e
	Enumeration for cipher phase.
typedef struct _hal_backend_drm_funcs	hal_backend_drm_funcs
	The structure type of the DRM HAL functions.

Data Structure Documentation

struct hal_drm_custom_command_s

The structure type of the DRM HAL custom command.

Since:: HAL_MODULE_DRM 1.0

Data Fields
const char *	name
void *	value

Field Documentation

const char* hal_drm_custom_command_s::name

The name of custom command

void* hal_drm_custom_command_s::value

The value of custom command

struct hal_drm_batch_command_control

The structure type of batch command.

Since:: HAL_MODULE_DRM 1.0

Data Fields
uint64_t	command_set_flag
hal_drm_custom_command_s	custom

Field Documentation

uint64_t hal_drm_batch_command_control::command_set_flag

flag for updating commands

hal_drm_custom_command_s hal_drm_batch_command_control::custom

The value for custom command

struct hal_drm_message

The structure type of the DRM message.

Since:: HAL_MODULE_DRM 1.0

Data Fields
hal_drm_message_type_e	type
const char *	license_request
hal_drm_error_e	error_code

Field Documentation

hal_drm_error_e hal_drm_message::error_code

The error code

const char* hal_drm_message::license_request

The license request message

hal_drm_message_type_e hal_drm_message::type

The type of message

struct hal_drm_data_s

Serialized byte data with specific size.

Since:: HAL_MODULE_DRM 1.0

Data Fields
uint32_t	size
unsigned char *	data

Field Documentation

unsigned char* hal_drm_data_s::data

The pointer of byte data array

uint32_t hal_drm_data_s::size

The size of data

struct hal_drm_key_info_s

The key id that indicates decryption key and status of decryption key.

Since:: HAL_MODULE_DRM 1.0

Data Fields
hal_drm_data_s	key_id
hal_drm_key_status_e	status

Field Documentation

hal_drm_data_s hal_drm_key_info_s::key_id

Key ID

hal_drm_key_status_e hal_drm_key_info_s::status

Status of decryption key indicated by key_id

struct hal_drm_key_info_list_s

The set of key status information.

Since:: HAL_MODULE_DRM 1.0

Data Fields
uint32_t	num_of_key_infos
hal_drm_key_info_s *	key_infos

Field Documentation

hal_drm_key_info_s* hal_drm_key_info_list_s::key_infos

Key ID and key status

uint32_t hal_drm_key_info_list_s::num_of_key_infos

The number of key information

struct hal_drm_crypto_info_s

The structure type of crypto information for decryption.

Since:: HAL_MODULE_DRM 1.0

Data Fields
hal_drm_cipher_algorithm_e	algorithm
hal_drm_media_type_e	type
hal_drm_cipher_phase_e	phase
unsigned char *	key_id
uint32_t	key_id_size
unsigned char *	iv
uint32_t	iv_size

Field Documentation

hal_drm_cipher_algorithm_e hal_drm_crypto_info_s::algorithm

Cipher algorithm

unsigned char* hal_drm_crypto_info_s::iv

The IV(Initialization Vector) for block cipher modes of operation

uint32_t hal_drm_crypto_info_s::iv_size

The size of IV

unsigned char* hal_drm_crypto_info_s::key_id

The Key ID

uint32_t hal_drm_crypto_info_s::key_id_size

The size of Key ID

hal_drm_cipher_phase_e hal_drm_crypto_info_s::phase

Cipher phase

hal_drm_media_type_e hal_drm_crypto_info_s::type

Media type

struct hal_drm_subsample_s

The structure type of subsample.

Since:: HAL_MODULE_DRM 1.0

Data Fields
uint32_t	bytes_of_clear_data
uint32_t	bytes_of_protected_data

Field Documentation

uint32_t hal_drm_subsample_s::bytes_of_clear_data

The size of clear data(BytesOfClearData in CENC specification)

uint32_t hal_drm_subsample_s::bytes_of_protected_data

The size of protected data(BytesOfProtectedData in CENC specification)

struct hal_drm_protection_pattern_s

The structure type of protection pattern information for pattern encryption.

Since:: HAL_MODULE_DRM 1.0

Data Fields
bool	use_pattern
uint32_t	crypt_byte_block
uint32_t	skip_byte_block

Field Documentation

uint32_t hal_drm_protection_pattern_s::crypt_byte_block

If use_pattern is true, count of the encrypted blocks in the protection pattern

uint32_t hal_drm_protection_pattern_s::skip_byte_block

If use_pattern is true, count of the unencrypted blocks in the protection pattern

bool hal_drm_protection_pattern_s::use_pattern

true if cbcs pattern scheme is used, otherwise false

struct hal_drm_buffer_s

The structure type of DRM buffer.

Since:: HAL_MODULE_DRM 1.0

Data Fields
int	index
bool	is_secure
uint32_t	size
unsigned char *	data
int	fd
int	secure_handle
int *	split_offsets
uint32_t	num_of_subsamples
hal_drm_subsample_s *	subsamples
hal_drm_protection_pattern_s	pattern_encryption

Field Documentation

unsigned char* hal_drm_buffer_s::data

The pointer of data buffer

int hal_drm_buffer_s::fd

The fd(file descriptor) of data buffer. When fd is not used, it will be set -1

int hal_drm_buffer_s::index

The index of buffer

bool hal_drm_buffer_s::is_secure

The flag which indicates the real data is managed in secure world or not

uint32_t hal_drm_buffer_s::num_of_subsamples

The number of subsamples

hal_drm_protection_pattern_s hal_drm_buffer_s::pattern_encryption

The information of pattern encryption

int hal_drm_buffer_s::secure_handle

The secure handle of data buffer. When handle is not used, it will be set 0

uint32_t hal_drm_buffer_s::size

The size of data buffer

int* hal_drm_buffer_s::split_offsets

Sample offset. Nullable. If used, -1 terminated int array. The max number of split_offsets are 15

hal_drm_subsample_s* hal_drm_buffer_s::subsamples

The subsamples in CENC(Common Encryption)

struct _hal_backend_drm_funcs

The structure type of the DRM HAL functions.

Since:: HAL_MODULE_DRM 1.0

Data Fields
int(*	init )(void **drm_handle)
int(*	deinit )(void *drm_handle)
int(*	set_message_callback )(void drm_handle, hal_drm_message_cb callback, void user_data)
int(*	get_cdm_version )(void drm_handle, char *version)
int(*	session_create )(void drm_handle, hal_drm_session_type_e type, hal_drm_data_s *session_id)
int(*	session_load )(void drm_handle, hal_drm_data_s session_id)
int(*	session_generate_request )(void drm_handle, hal_drm_data_s session_id, hal_drm_init_data_type_e type, hal_drm_data_s init_data, hal_drm_data_s *request)
int(*	session_update )(void drm_handle, hal_drm_data_s session_id, hal_drm_data_s *license)
int(*	session_get_expiration )(void drm_handle, hal_drm_data_s session_id, int64_t *expiration)
int(*	session_get_key_infos )(void drm_handle, hal_drm_data_s session_id, hal_drm_key_info_list_s **key_info_list)
int(*	session_close )(void drm_handle, hal_drm_data_s session_id)
int(*	session_remove )(void drm_handle, hal_drm_data_s session_id)
int(*	get_provisioning_request )(void drm_handle, hal_drm_data_s *request)
int(*	set_provisioning_response )(void drm_handle, hal_drm_data_s response)
int(*	get_service_certificate_request )(void drm_handle, hal_drm_data_s *request)
int(*	load_service_certificate_response )(void drm_handle, hal_drm_data_s response, hal_drm_data_s **certificate)
int(*	set_service_certificate )(void drm_handle, hal_drm_data_s certificate)
int(*	allocate_output_buffer )(void drm_handle, uint32_t size, bool is_secure, hal_drm_buffer_s *buffer)
int(*	release_output_buffer )(void drm_handle, hal_drm_buffer_s buffer)
int(*	release_data )(void drm_handle, hal_drm_data_s data)
int(*	release_key_info_list )(void drm_handle, hal_drm_key_info_list_s key_info_list)
int(*	decrypt )(void drm_handle, hal_drm_buffer_s input, hal_drm_crypto_info_s decrypt_info, hal_drm_buffer_s output)
int(*	set_command )(void drm_handle, hal_drm_command_e command, void value)
int(*	get_command )(void drm_handle, hal_drm_command_e command, void *value)
int(*	set_batch_command )(void drm_handle, hal_drm_batch_command_control_s batch_command, hal_drm_command_e *error_command)

Field Documentation

int(* _hal_backend_drm_funcs::allocate_output_buffer)(void *drm_handle, uint32_t size, bool is_secure, hal_drm_buffer_s **buffer)

Allocates drm output buffer

int(* _hal_backend_drm_funcs::decrypt)(void *drm_handle, hal_drm_buffer_s *input, hal_drm_crypto_info_s *decrypt_info, hal_drm_buffer_s *output)

Decrypts encrypted data

int(* _hal_backend_drm_funcs::deinit)(void *drm_handle)

Deinitializes DRM HAL backend handle

int(* _hal_backend_drm_funcs::get_cdm_version)(void *drm_handle, char **version)

Gets the cdm version

int(* _hal_backend_drm_funcs::get_command)(void *drm_handle, hal_drm_command_e command, void **value)

Gets the current value of command

int(* _hal_backend_drm_funcs::get_provisioning_request)(void *drm_handle, hal_drm_data_s **request)

Gets the provisioning request message

int(* _hal_backend_drm_funcs::get_service_certificate_request)(void *drm_handle, hal_drm_data_s **request)

Gets the service certificate request

int(* _hal_backend_drm_funcs::init)(void **drm_handle)

Initializes DRM HAL backend handle

int(* _hal_backend_drm_funcs::load_service_certificate_response)(void *drm_handle, hal_drm_data_s *response, hal_drm_data_s **certificate)

Loads the service certificate response

int(* _hal_backend_drm_funcs::release_data)(void *drm_handle, hal_drm_data_s *data)

Releases hal_drm_data_s type data

int(* _hal_backend_drm_funcs::release_key_info_list)(void *drm_handle, hal_drm_key_info_list_s *key_info_list)

Releases hal_drm_key_info_list_s type data

int(* _hal_backend_drm_funcs::release_output_buffer)(void *drm_handle, hal_drm_buffer_s *buffer)

Releases drm output buffer

int(* _hal_backend_drm_funcs::session_close)(void *drm_handle, hal_drm_data_s *session_id)

Closes session

int(* _hal_backend_drm_funcs::session_create)(void *drm_handle, hal_drm_session_type_e type, hal_drm_data_s **session_id)

Creates session

int(* _hal_backend_drm_funcs::session_generate_request)(void *drm_handle, hal_drm_data_s *session_id, hal_drm_init_data_type_e type, hal_drm_data_s *init_data, hal_drm_data_s **request)

Generates request

int(* _hal_backend_drm_funcs::session_get_expiration)(void *drm_handle, hal_drm_data_s *session_id, int64_t *expiration)

Gets the key expiration

int(* _hal_backend_drm_funcs::session_get_key_infos)(void *drm_handle, hal_drm_data_s *session_id, hal_drm_key_info_list_s **key_info_list)

Gets the key information including key id and key status

int(* _hal_backend_drm_funcs::session_load)(void *drm_handle, hal_drm_data_s *session_id)

Loads session

int(* _hal_backend_drm_funcs::session_remove)(void *drm_handle, hal_drm_data_s *session_id)

Removes session

int(* _hal_backend_drm_funcs::session_update)(void *drm_handle, hal_drm_data_s *session_id, hal_drm_data_s *license)

Updates session

int(* _hal_backend_drm_funcs::set_batch_command)(void *drm_handle, hal_drm_batch_command_control_s *batch_command, hal_drm_command_e *error_command)

Sets a set of commands

int(* _hal_backend_drm_funcs::set_command)(void *drm_handle, hal_drm_command_e command, void *value)

Sets the various command and value

int(* _hal_backend_drm_funcs::set_message_callback)(void *drm_handle, hal_drm_message_cb callback, void *user_data)

Sets a callback of message

int(* _hal_backend_drm_funcs::set_provisioning_response)(void *drm_handle, hal_drm_data_s *response)

Sets the provisioning response message

int(* _hal_backend_drm_funcs::set_service_certificate)(void *drm_handle, hal_drm_data_s *certificate)

Sets the service certificate

Typedef Documentation

typedef struct _hal_backend_drm_funcs hal_backend_drm_funcs

The structure type of the DRM HAL functions.

Since:: HAL_MODULE_DRM 1.0

typedef struct hal_drm_batch_command_control hal_drm_batch_command_control_s

The structure type of batch command.

Since:: HAL_MODULE_DRM 1.0

typedef enum hal_drm_cipher_phase hal_drm_cipher_phase_e

Enumeration for cipher phase.

Since:: HAL_MODULE_DRM 1.0

typedef enum hal_drm_command hal_drm_command_e

Enumeration for the DRM command.

Since:: HAL_MODULE_DRM 1.0

typedef enum hal_drm_error hal_drm_error_e

Enumeration for the DRM error.

Since:: HAL_MODULE_DRM 1.0

typedef enum hal_drm_media_type hal_drm_media_type_e

Enumeration for encrypted content media type.

Since:: HAL_MODULE_DRM 1.0

typedef int(* hal_drm_message_cb)(hal_drm_message_s *message, void *user_data)

Callback function for notification from DRM HAL.

Since:: HAL_MODULE_DRM 1.0

Parameters:

[in]	message	The message from DRM HAL
[in]	user_data	The user data for callback

See also:: hal_hal_drm_add_message_callback(); hal_hal_drm_remove_message_callback()

typedef struct hal_drm_message hal_drm_message_s

The structure type of the DRM message.

Since:: HAL_MODULE_DRM 1.0

typedef enum hal_drm_message_type hal_drm_message_type_e

Enumeration for the DRM message type.

Since:: HAL_MODULE_DRM 1.0

typedef enum hal_drm_state hal_drm_state_e

Enumeration for the DRM state.

Since:: HAL_MODULE_DRM 1.0

Enumeration Type Documentation

enum hal_drm_cipher_algorithm_e

Enumeration for cipher algorithm.

Since:: HAL_MODULE_DRM 1.0

Enumerator:

HAL_DRM_CIPHER_RC4	Rivest Cipher 4 stream cipher algorithm
HAL_DRM_CIPHER_AES128_CTR	AES(Advanced Encryption Standard) 128bit key with CTR(CounTeR) operation mode
HAL_DRM_CIPHER_AES128_CBC	AES(Advanced Encryption Standard) 128bit key with CBC(Cipher Block Chaining) operation mode
HAL_DRM_CIPHER_AES128_CBC_PKCS5	AES(Advanced Encryption Standard) 128bit key with CBC(Cipher Block Chaining) operation mode, PKCS5 padding

enum hal_drm_cipher_phase

Enumeration for cipher phase.

Since:: HAL_MODULE_DRM 1.0

Enumerator:

HAL_DRM_CIPHER_PHASE_NONE	None
HAL_DRM_CIPHER_PHASE_INIT	Initialize phase
HAL_DRM_CIPHER_PHASE_UPDATE	Update phase
HAL_DRM_CIPHER_PHASE_FINAL	Final phase

enum hal_drm_command

Enumeration for the DRM command.

Since:: HAL_MODULE_DRM 1.0

Enumerator:

HAL_DRM_COMMAND_BASE	Base of command
HAL_DRM_COMMAND_CUSTOM	Custom

enum hal_drm_error

Enumeration for the DRM error.

Since:: HAL_MODULE_DRM 1.0

Enumerator:

HAL_DRM_ERROR_NONE	Error none
HAL_DRM_ERROR_NOT_SUPPORTED	Not supported
HAL_DRM_ERROR_INVALID_PARAMETER	Invalid parameter
HAL_DRM_ERROR_INVALID_STATE	Invalid state
HAL_DRM_ERROR_OUT_OF_MEMORY	Out of memory
HAL_DRM_ERROR_NEED_PROVISIONING	Need to device provisioning
HAL_DRM_ERROR_NEED_KEY	Need key
HAL_DRM_ERROR_TYPE	Type error
HAL_DRM_ERROR_INTERNAL	Internal
HAL_DRM_ERROR_NOT_IMPLEMENTED	Not implemented
HAL_DRM_ERROR_UNKNOWN	Unknown

enum hal_drm_init_data_type_e

The type of init data which is used for generating license request.

Since:: HAL_MODULE_DRM 1.0

Enumerator:

HAL_DRM_INIT_DATA_TYPE_CENC	Common encryption
HAL_DRM_INIT_DATA_TYPE_KEY_IDS	Key IDs
HAL_DRM_INIT_DATA_TYPE_WEBM	WebM

enum hal_drm_key_status_e

The status of decryption key.

Since:: HAL_MODULE_DRM 1.0

Enumerator:

HAL_DRM_KEY_STATUS_USABLE	Key is usable
HAL_DRM_KEY_STATUS_EXPIRED	Key is expired
HAL_DRM_KEY_STATUS_OUTPUT_RESTRICTED	Key is usable but output restricted
HAL_DRM_KEY_STATUS_PENDING	Key status not clear
HAL_DRM_KEY_STATUS_ERROR	Key status internal error
HAL_DRM_KEY_STATUS_RELEASED	Key is released

enum hal_drm_media_type

Enumeration for encrypted content media type.

Since:: HAL_MODULE_DRM 1.0

Enumerator:

HAL_DRM_MEDIA_TYPE_NONE	None
HAL_DRM_MEDIA_TYPE_FMP4	FMP4(Fragmented MP4)
HAL_DRM_MEDIA_TYPE_TS	TS(Transport Stream)
HAL_DRM_MEDIA_TYPE_ASF	ASF(Advanced Systems Format)
HAL_DRM_MEDIA_TYPE_FMP4_AUDIO	FMP4 Audio
HAL_DRM_MEDIA_TYPE_FMP4_VIDEO	FMP4 Video
HAL_DRM_MEDIA_TYPE_CLEAN_AUDIO	Clean Audio Data
HAL_DRM_MEDIA_TYPE_PES	Packetized ES(Elementary Stream) Payload

enum hal_drm_message_type

Enumeration for the DRM message type.

Since:: HAL_MODULE_DRM 1.0

Enumerator:

HAL_DRM_MESSAGE_TYPE_LICENSE_REQUEST_GENERATED	DRM license request message is generated
HAL_DRM_MESSAGE_TYPE_KEY_STATUS_CHANGED	DRM key status is changed
HAL_DRM_MESSAGE_TYPE_ERROR	The error

enum hal_drm_session_type_e

The type of DRM session.

Since:: HAL_MODULE_DRM 1.0

Enumerator:

HAL_DRM_SESSION_TYPE_TEMPORARY	Temporary
HAL_DRM_SESSION_TYPE_PERSISTENT_LICENSE	Persistent license
HAL_DRM_SESSION_TYPE_PERSISTENT_USAGE_RECORD	Persistent usage record

enum hal_drm_state

Enumeration for the DRM state.

Since:: HAL_MODULE_DRM 1.0

Enumerator:

HAL_DRM_STATE_NONE	None state
HAL_DRM_STATE_INITIALIZED	Initialized state for DRM device
HAL_DRM_STATE_SESSION_CREATED	Created session state for DRM device

Required Header

Overview

State Diagram

State Transitions

Typedefs

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Typedef Documentation

Enumeration Type Documentation