无卡DRM终端SDK接口使用手册

1.1.1
航天数字传媒无卡DRM终端SDK接口使
用手册
文档说明
本文档详细描述了无卡DRM客户端SDK接口，旨在双方顺利实现集成提供指导和依据。

本文档仅限于在航天数字传媒有限公司及授权的终端厂商内部公开，任何人不得擅自向外公开。

任何其他人员因特殊需要得到此文档之后，不得擅自传递，否则将追究法律责任。

本文档的解释权属于航天数字传媒有限公司。

历史记录
注：初始版本号定为0.1，审核通过基线版本为1.0，可进行归档。

1.0及以上版本修改
需要进行审批。

目录
文档说明 (3)
历史记录 (3)
目录 (4)
1接口形式 (5)
2使用环境要求 (5)
3数据类型约定 (5)
4接口说明 (6)
5相关数据说明 (18)
6错误码定义 (19)
7时间格式说明 (20)
8附录 (21)
1.接口形式
本SDK采用C语言开发，SDK以SO库以及头文件的形式向外发布，厂商需要加载SO 库并实现OEM部分接口，方可调用DBS接口实现无卡DRM客户端功能。

2.使用环境要求
目前SDK使用环境为linux平台与windows平台。

移植终端自身为linux系统，终端厂商需要提供交叉编译环境，由我方交叉编译之后提供库以及对应头文件。

移植终端为android平台，我方默认采用最新android ndk编译，终端厂商也可以提供交叉编译环境，由我方编译后提供库文件以及头文件。

移植终端为windows平台，我方直接提供库文件以及头文件。

我方提供的SDK不论什么平台都需要openssl的支持，目前使用0.9.8版本。

3.数据类型约定
UINT8 8位无符号整型数据
UINT16 16位无符号整型数据
UINT32 32位无符号整形数据
UINT64 64位无符号整形数据
CHAR 8位字符型数据
INT16 16位有符号整形数据
INT32 32位有符号整形数据
INT64 64位有符号整形数据
VOID 32位空类型
4.接口说明
以下接口为OEM接口，厂商必须实现。

1.获取设备ID
【原型】
INT32 OemGetSN(VOID * vOem, UINT8 * sn)
【功能要求】
获取设备ID号，该号码为设备出厂时烧写序列号，作为设备的唯一标志，该序列为6字节，每个字节取值范围均为0-255。

在SDK库调用该接口之前，sn内存已经分配，函数实现只需找到设备的ID，拷贝给sn为起始地址的连续6个字节即可。

如果码值过长或过短，请自行截断，或者补0。

该接口必须实现，不同的设备调用该函数返回的值必须不同。

【参数】
vOem - 输入参数，OEM厂商自行定义的结构体，见相关数据说明章节。

SN - 输出参数，SN长度固定为16字节，内存已经分配，只需对其赋值。

【返回值】
返回值整数类型，如果返回0代表成功，非0代表失败。

2.打开主加密文件
【原型】
INT32 OemOpen(VOID * vOem)
【功能要求】
打开主加密文件。

【参数】
vOem - 输入参数，OEM厂商自行定义的结构体，见相关数据说明章节。

【返回值】
返回值整数类型，成功返回0，失败返回非0。

3.读主加密文件
【原型】
INT32 OemRead(VOID * vOem, UINT8 * pbBuf, INT32 iBufLen)
【功能要求】
读取主加密文件内容。

【参数】
vOem - 输入参数，OEM厂商自行定义的结构体，见相关数据说明章节。

pbBuf - 输出参数，读取文件数据存放的首地址。

iBufLen - 输入参数，要读取的文件数据的长度。

【返回值】
返回值整数类型，返回实际读取数据数据长度。

4.设置主加密文件指针偏移位置
【原型】
INT64 OemSeek(VOID * vOem , INT64 lPos , INT32 FromWhere)
【功能要求】
偏移主加密文件的文件指针。

【参数】
vOem - 输入参数，OEM厂商自行定义的结构体，见相关数据说明章节。

lPos - 输入参数，加密媒体文件指针偏移量。

FromWhere - 输入参数，与标准C语言库中的fseek最后一个参数功能一样，取三种值，分别为0,1,2含义分别为文件开头、文件当前、文件结尾位置。

【返回值】
返回值整数类型，成功更改偏移指针返回当前文件指针位置，失败返回非O。

5.读主加密文件大小
【原型】
INT64 OemSize(VOID * vOem);
【功能要求】
返回主加密文件的大小
【参数】
vOem - 输入参数，OEM厂商自行定义的结构体，见相关数据说明章节。

【返回值】
返回值整数类型，成功返回加密文件实际大小，失败返回小于等于0
以下接口为DBS接口，调用如下接口，方可实现DRM功能。

6.DRM初始化
【原型】
INT32 DbsInit(UINT8 vDbs[2048], VOID * vOem)
【功能】
主加密文件的初始化操作，必须调用完毕该接口，才能调用其他DBS接口。

特别说明：在调用该接口时，OEM数据中关于如何读取加密主文件的参数可以不用设置，因为初始化操作不回去操作某个特定的加密文件，而是去读取一些DRM自己的数据、机顶盒相关参数、设置过滤器等。

【参数】
vDbs - 输入参数，无卡DRM运行所需要的数据存储位置，移植端不需要关注其具体结构，给其分配2048字节数组即可，此空间由移植方申请。

vOem - 输入参数，OEM厂商自行定义的结构体，见相关数据说明章节。

【返回值】
见错误码定义章节
7.主加密文件打开
【原型】
INT32 DbsOpen(UINT8 vDbs[2048])
【功能】
主加密文件打开，该函数调用成功方可调用 DbsRead DbsSeek DbsPos DbsSize 函数
通过调用该函数，可以判定当前加密文件授权状态，根据返回值判定。

只有在返回值大于等于0的时候，才能去掉用下方所有接口，如果返回负值，请查表定位错误，解决错误后再重新调用。

【参数】
vDbs - 输入参数，无卡DRM运行所需要的数据存储位置，移植端不需要关注其具体结构，给其分配2048字节数组即可，此空间由移植方申请。

【返回值】
见错误码定义章节
8.获取解密后文件目前指针位置
【原型】
INT64 DbsPos(UINT8 vDbs[2048]);
【功能】
获取解密后的清流文件的文件偏移指针位置
【参数】
vDbs - 输入参数，无卡DRM运行所需要的数据存储位置。

【返回值】
见错误码定义章节
9.读解密后文件数据
【原型】
INT32 DbsRead(UINT8 vDbs[2048], UINT8 * pbBuf, INT32 iBufLen)
【功能】
读取解密后的主加密文件数据。

（读取的数据已为清流）
【参数】
vDbs - 输入参数，无卡DRM运行所需要的数据存储位置。

pbBuf - 输出参数，读到的数据的首地址。

iBufLen - 输入参数，读取数据的长度。

【返回值】
见错误码定义章节
10.设置解密后文件偏移指针
【原型】
INT64 DbsSeek(UINT8 vDbs[2048], INT64 lPos , INT32 FromWhere)
【功能】
设置解密后的主加密文件指针偏移位置
【参数】
vDbs - 输入参数，无卡DRM运行所需要的数据存储位置。

（调用init函数时，分配的内存区域）
lPos - 输入参数，文件偏移指针数据。

FromWhere - 输入参数，与标准C语言库中的fseek最后一个参数功能一样，取三种值，分别为0,1,2含义分别为文件开头、文件当前、文件结尾位置。

【返回值】
目前解密后的文件指针真实位置，<=0则见错误码章节。

基于卫星技术的数字发行系统
需求规格说明书
11.获取解密后文件大小
【原型】
INT64 DbsSize(UINT8 vDbs[2048])
【功能】
获取解密后的文件实际大小
【参数】
vDbs - 输入参数，无卡DRM运行所需要的数据存储位置。

（调用init函数时，分配的内存区域）
【返回值】
返回解密后文件的大小，如有错误见错误码定义章节
12.获取当前打开的主加密文件授权详细信息
【原型】
INT32DbsGetMediaAuthInfo(UINT8 vDbs[2048] , DBSAuthInfo *Info);
【功能】
获取当前正在解密的文件的授权信息，例如影片名、影片编号CID，开始时间、
截止时间、剩余次数等
【参数】
vDbs - 输入参数，无卡DRM运行所需要的数据存储位置。

（调用init函数时，分配的内存区域）
Info - 输出参数，该结构定义见SDK配套的头文件中DBSAuthInfo结构体定义。

【返回值】
见错误码定义章节
13.获取设备有关信息
【原型】
INT32 DbsGetDeviceInfo(VOID * dbs , DBSDeviceInfo * deviceInfo);
【功能】
获取设备基本信息
【参数】
vDbs - 输入参数，无卡DRM运行所需要的数据存储位置。

（调用init函数时，分配的内存区域）
deviceInfo - 输出参数，返回设备基本信息，主要有DRM版本信息、设备ID等
【返回值】
见错误码定义章节
5.相关数据说明
接口中主要涉及要两点数据需要详细解释
1.OEM数据。

在OEM起始的接口中，第一个参数都是VOID * OEM类型，此数据类型
是需要移植方自己定义，以结构体指针形式存在，结构体中的内容不作要求，但
会做出建议。

此数据结构库自身不会做任何修改，库只起到传递的作用。

由于需
要该SDK支持场景较多（eg：本地文件，网络文件），所以有必要设置该OEM参
数。

例如，加密文件以文件的形式存在本地，则OEM结构体中可以存储文件的位
置等参数，OEMRead、OEMSeek 等接口主要就是实现读取该加密文件即可。

如果加密文件在服务器上，则OEM结构体中可以存储服务器位置等信息，相应的
OEMRead 、OEMSeek等则是在读取网络数据。

2.DBS数据。

在DBS起始的接口中，第一个参数都是 VOID * dbs类型。

该数据为无卡
DRM开始一个加密工作后，DRM自身中间运算数据的存储地。

当移植方每次调用
DbsInit接口时，为其开辟2048内存空间，把空间首地址传给该接口的第一个参
数，这是无卡DRM工作的必要条件。

3.一组OEM数据刻画了一个加密文件各项信息，一组DBS数据则为该加密文件中间运
算提供了内存空间，两两属于绑定关系。

如果想要同时对多个加密文件进行解密
操作，则需要多组绑定的OEM DBS数据。

DbsInit接口为DRM初始化接口，通过
该接口进行OEM 与 DBS之间的绑定。

6.错误码定义
7.时间格式说明
无卡DRM的时间为UTC时间，格式遵循ISO8601，用秒数表示。

起始时间为格林威治时间1970年1月1日0点0分0秒。

21 / 22
8.附录
如下伪代码为DBS接口使用参考
见配套示例代码
如下为OEM接口具体实现范例，以作参考
见配套示例代码
如下为OEM数据接口参考
见配套示例代码
22 / 22。