aacs_api.h

Sigma SMP8634 Mrua v. 2.8.2.0

/*
 *
 * Copyright (c) Sigma Designs, Inc. 2005-2006. All rights reserved.
 *
 */
#ifndef __AACS_API_H__
#define __AACS_API_H__

#include "rmdef/rmdef.h"

#include "aacs_def.h"
#include "aacs_callbacks.h"

/** AACS module handle */
struct aacs_handle;

/** AACS session user-side context, opaque */
struct aacs_context;

/**
 * Open AACS module. 
 *
 * The AACS module also needs some RUA memory, already mapped, in order to
 * communicate bigger chunks of data to the XPU efficiently. The gbus address
 * and the mapped address should be given as parameters, along with the size
 * allocated. Also, to identify which XPU to use (in case of several chips),
 * chip should be set to the requested index (0 for the first one, ...).
 *
 * This API call is required for both BD-ROM and BD-RE.
 *
 * @param gbus_memory - gbus address of memory allocated for AACS 
 * @param mapped_memory - CPU virtual address of memory allocated for AACS 
 * @param mem_size - size of memory allocated for AACS 
 * @param chip - chip index 
 *
 * @return AACS handle, NULL on error (and aacs_error is set)
 */
struct aacs_handle * aacs_open(RMuint32 gbus_memory, RMuint32 mapped_memory, 
			       RMuint32 mem_size, RMuint32 chip);

/**
 * Open AACS module (preloaded). 
 *
 * The AACS module also needs some RUA memory, already mapped, in order to
 * communicate bigger chunks of data to the XPU efficiently. The gbus address
 * and the mapped address should be given as parameters, along with the size
 * allocated. Also, to identify which XPU to use (in case of several chips),
 * chip should be set to the requested index (0 for the first one, ...).
 *
 * This API call is required for both BD-ROM and BD-RE.
 *
 * @param gbus_memory - gbus address of memory allocated for AACS 
 * @param mapped_memory - CPU virtual address of memory allocated for AACS 
 * @param mem_size - size of memory allocated for AACS 
 * @param chip - chip index 
 * @param xtask_slot_id - image slot # for the preloaded xtask.
 * @param dmx_cphr - params for Demux CipherOnlyTask AES decryption (NULL to use XPU AES cipher)
 *                   (pointer must point to RUA memory!)
 * 
 * @return AACS handle, NULL on error (and aacs_error is set)
 */
struct aacs_handle * aacs_open_preloaded(RMuint32 gbus_memory, RMuint32 mapped_memory, 
			       RMuint32 mem_size, RMuint32 chip, RMuint32 slot, 
			       struct demux_cipher *dmx_cphr);

/**
 * Instanciates a new AACS engine.
 *
 * To manipulate the AACS device (drive, network, ...), a table of callbacks
 * and a callback context have to be provided.
 *
 * This API call is required for both BD-ROM and BD-RE
 *
 * @param aacs_handle - handle on the opened library
 * @param flags - flags (BD-ROM/BD-RE/HD-DVD...)
 * @param callbacks - table of callbacks, see aacs_callbacks.h 
 * @param callback_context - context holding drive and non volatile info
 * @return AACS context, NULL on error (and aacs_error is set)
 */
struct aacs_context * aacs_instantiate(struct aacs_handle *aacs_handle,
				      RMuint32 flags,
				      struct aacs_callbacks_s *callbacks,
				      void *callback_context);

/**
 * Authenticate the content
 *
 * This function authenticates the content and performs various other
 * operations, depending on the AACS flavor chosen. 
 *
 * For BD-ROM, it verifies the DRL, computes the Bus Key, the Media Key 
 * and processes the SKB(s).
 *
 * For BD-RE, it verifies the DRL, computes the Media Key and the 
 * Protected Area key.
 *
 * This API call is required for both BD-ROM and BD-RE
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @return RM_OK on success
 */
RMstatus aacs_authenticate(struct aacs_context *aacs_context);

/**
 * Performs AACS content revocation (content hashing)
 *
 * This API call is specific to BD-ROM.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_content_revocation(struct aacs_context *aacs_context);

/**
 * Ready title for playback
 *
 * This function performs various operation to make a title ready. It outputs
 * the basic CCI for AACS, using the following format :
 *
 *    +-------------------------------+-----------------+
 *    | Syntax                        | No. of bits     |
 *    +-------------------------------+-----------------+ 
 *    | (reserved)                    | 5               | \
 *    | EPN                           | 1               | | 
 *    | CCI                           | 2               | |  Basic CCI for AACS  
 *    | (reserved)                    | 3               | |
 *    | ICT                           | 1               | |
 *    | DOT                           | 1               | |
 *    | APS                           | 3               | /
 *    |                               |                 |
 *    | (reserved)                    | 240             |
 *    +-------------------------------+-----------------+
 *
 * Content authentication must have been performed before calling this 
 * API.
 *
 * This API call is specific to BDMV content. This applies to BD-ROM
 * and BD-RE 3.0.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @param title_id - Title number for BD-ROM/BD-RE, ...
 * @param basic_cci - Basic CCI for AACS
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_title_ready(struct aacs_context *aacs_context,
			  RMuint32 title_id,
			  RMuint8 basic_cci[AACS_BCCI_SIZE]);

/**
 * BDAV-specific: ready clip for playback.
 *
 * This function performs various operations to prepare the playback of a clip. 
 * It returns the basic CCI for AACS using the same format as that used for a
 * title (for BDMV).
 *
 * This API call is specific to BDAV content. This applies to BD-RE 2.0.
 *
 * @param aacs_context - aacs_context
 * @param clip_id - clip ID as defined in BD recordable 3.2.2
 * @param bd_directory - BD directory in which to look for the clip
 * @param cci - returned CCI information (including sequence CCI) extracted 
 *              from the CPS unit usage file
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_clip_ready(struct aacs_context *aacs_context,
			 RMuint16 clip_id, RMuint8 bd_directory, RMuint8 cci[AACS_SCCI_SIZE]);

/**
 * BDRE-specific: ready clip(s) for playback
 *
 * This function takes a group of clips (count specified by no_clips) and calculates
 * and caches unit key and CCI information per each clip.  The benefit and purpose of
 * this method is to allow better performance and flexibility for clip initialization.
 *
 * To enable use of a cached clip the AACS inband AACS_IBC_CMD_CACHE_CLIP must be used.
 *
 * This is specifically useful for the case of seamless connections where the cost of
 * preparing several clips at once has the potential to starve playback.
 *
 * This API call is specific to BD-RE content.  This applies to BD-RE 2.0/3.0
 *
 * @param aacs_context - aacs_context
 * @param clip_info    - pointer to an array of clip_info structures which contain 
 *                       all necessary information for initializing a clip, including
 *                       clip_id, bd_directory (for 2.0) and CCI information.
 * @param no_clips     - this is the number of clips present in the passed array clip_info
 *
 * @return RM_OK on sucess, RM_ERROR on error and aacs_error is set
 * 
 */
RMstatus aacs_clips_ready(struct aacs_context	*aacs_context,
                          struct clip_info *clip_info, 
                          RMuint32 no_clips);
/**
 * Processes the key and usage information associated with a BDAV thumbnail,
 * and decrypts thumbnail data. It also returns the basic CCI information 
 * associated to the CPS Unit that the thumbnail belongs to.
 *
 * The thumbnail to decrypt is identified by its type (aacs_tn_type_menu or
 * aacs_tn_type_mark) and the BDAV directory it belongs to (value between 0 and
 * 4 as described in BD recordable 3.1.2)
 *
 * The thumbnail data must be provided as a set of tn_sub blocks as 
 * described in BD recordable 3.3.2. The number of sub_blocks passed in
 * is specified in n_tn_sub.
 *
 * The input (encrypted) data and output (decrypted) data are passed in
 * tn_sub_in and tn_sub_out respectively. It is OK for both pointers to point 
 * to the same buffer.
 *
 * This API call is specific to BDAV content. This applies to BD-RE 2.0.
 *
 * @param aacs_context - the AACS context
 * @param tn_type - the type of the thumbnail (Menu or Mark)
 * @param bd_directory - the BD directory for this thumbnail
 * @param tn_sub_in - the thumbnail data to be decrypted
 * @param tn_sub_out - the returned, decrypted thumbnail data
 * @param cci - returned CCI information (including sequence CCI) extracted 
 *              from the CPS unit usage file
 * @return RM_OK on success, RM_ERROR else and aacs_error is set.
 */
RMstatus aacs_decrypt_thumbnail(struct aacs_context *aacs_context,
		enum bdav_tn_type tn_type, 
		RMuint8 bd_directory,
		RMuint8 *tn_sub_in,
		RMuint8 *tn_sub_out,
		RMuint32 n_tn_sub,
		RMuint8 cci[AACS_SCCI_SIZE]);
/**
 * Read AACS PSR
 *
 * This function returns the value of a given AACS PSR (aacs_psr_96 
 * or aacs_psr_97)
 *
 * This API call is meaningful only for SKB content for BD-ROM.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @param psr - number of the AACS PSR to get (0 or 1)
 * @param psr_value - returned value of the PSR 
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_get_psr(struct aacs_context *aacs_context,
		      enum aacs_psr psr,
		      RMuint32 *psr_value);

/**
 * Read BD-J Root Certificate Hash
 *
 * This API call is specific to BD-ROM.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @param hash - 20 bytes long buffer to receive the SHA1
 * @param aid - returned Applicant ID
 * @param csn - returned Content Sequence Number
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_get_bdj_hash(struct aacs_context *aacs_context,
			   RMuint16 *aid,
			   RMuint32 *csn,
			   RMuint8 hash[AACS_SHA1_SIZE]);

/**
 * Read Pre-Recorded Media Serial Number. If there is no PMSN recorded on
 * the BD-ROM disc, the invalid PMSN with all bits set is returned as 
 * specified in the BD+ specification.
 *
 * This API call is specific to BD-ROM.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @param pmsn - 16 bytes buffer to receive the pmsn
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_get_pmsn(struct aacs_context *aacs_context,
		       RMuint8 pmsn[AACS_PMSN_SIZE]);

/**
 * Get AACS Volume ID
 *
 * This API call is specific to BD-ROM.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @param vid - 16 bytes buffer to receive the VolumeID
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_get_volume_id(struct aacs_context *aacs_context,
			    RMuint8 vid[AACS_VID_SIZE]);

/**
 * Cancel AACS Processing
 *
 * This API call applies to both BD-ROM and BD-RE.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_cancel(struct aacs_context *aacs_context);

/**
 * Set AACS KCD params (implementation specific)
 *
 * For those implementations that obtain the KCD outside of the scope
 * of the AACS implementation, the KCD data can be passed to the AACS
 * engine through this call.
 *
 * This API call is specific to BD-ROM.
 *
 * @param aacs_context - context
 * @param data - data to process to get the KCD
 * @param size - size of the data to process < KCD_MAX_SIZE
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_set_kcd(struct aacs_context *aacs_context,
		      const RMuint8 *data,
		      RMuint32 size);

/**
 * Generate random 128bits
 *
 * This API call applies for both BD-ROM and BD-RE.
 *
 * @param aacs_context - AACS context
 * @param rnd - 16 bytes buffer to received random data
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_random_gen(struct aacs_context *aacs_context,
			 RMuint8 *rnd);

/**
 * Get decryption information
 *
 * This API call applies to both BD-ROM and BD-RE.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @param xtask_pid - returned PID of the xtask
 * @param cookie - decryption cookie, returned
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_get_decrypt_info(struct aacs_context *aacs_context,
			       RMuint32 *xtask_pid, void **cookie);

/**
 * For BD+, on title initialize, send a FUT to the core in order to perform the
 * Media Transform.
 *
 * This API call applies only to BD-ROM.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @param data - fixup table data
 * @param size - data size
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_send_fut(struct aacs_context *aacs_context, RMuint8 *data,
		       RMuint32 size);

/**
 * For BD+, set the Media Transform parameters for a given slot.
 *
 * This API call applies only to BD-ROM.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @param slot_id - slot to setup (0 to 4)
 * @param clip_id - Clip ID
 * @param sp_id - Secret Parameter Identifier
 * @param sp - Secret Parameter
 * @param fm_id - Forensic Mark ID
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_set_sp(struct aacs_context *aacs_context, RMuint8 slot_id,
		     RMuint32 clip_id, RMuint16 sp_id, RMuint8 sp[BDP_SP_SIZE],
		     RMuint8 fm_id[BDP_FM_SIZE]);

/**
 * Terminate a AACS session
 *
 * This API call is required for both BD-ROM and BD-RE.
 *
 * @param aacs_context - aacs_context initialized with init_aacs
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_finalize(struct aacs_context *aacs_context);

/**
 * Close AACS module, free allocated resources
 *
 * This API call is required for both BD-ROM and BD-RE.
 *
 * @return RM_OK on success, RM_ERROR on error and aacs_error is set
 */
RMstatus aacs_close(struct aacs_handle *aacs_handle);

/**
 *  Generate a AACS managed copy record
 *
 *  This method is for Sigma internal use only.
 *
 * @param aacs_context - aacs_context initialized with aacs
 * @param record - Encrypted MC record (100 bytes long)
 * @param qualify - extra secret required for generation of MC data.
 * @return RM_OK on success, RM_ERROR on error.
 * 
 */
RMstatus aacs_generate_mc_record(struct aacs_context* aacs_context, RMuint8* record, RMuint8* qualify);
/**
 *  Set a AACS managed copy record
 *
 *  This method is for Sigma internal use only.
 *
 * @param record - Encrypted MC record (100 bytes long)
 * @return RM_OK on success, RM_ERROR on error.
 * 
 */

RMstatus aacs_set_mc_record( struct aacs_context* aacs_context, RMuint8* record, RMuint8 pmsn[AACS_PMSN_SIZE]);

#endif /* __AACS_API_H__ */