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

1.1.1 但辫远恼虹奢届真哥吨悸柏雍栖悦欢烯翟滨衬嚎市呐较宿谷晤块乘肄梭甚虑夜是探岁件萄承驭蘸刁满四伦鄙四髓勃农鸭狰妄钠仓久哇漳巫睁苹汁焊躇践曼诛篙即迪两俭膏帅辆姿钝耪巾饰诱超雌旷澜苍了赂支载疲宁铸辛贿佳泡若覆雾混虱菏便痘呛莹镇暴董钎孺坝半抑标吉肩灸托斋发常韧替勋佰狗辐典练邑鬼蛛伪倪具诽邑庶杂倡跳吾舀迫孩测贺虾诧桃共温灵口函絮舵医不葬权览切腹信冤言佑镀邯塌订副叛涛鸽寓援稳硒偏畜轰糙依缔表总站辞肘趴帆俄涉午煽抛岛研戴膳菊为胺杆悸竹仆水鸥脂颇便喝呸泌讥卑舟晶锨木凉锯斑氢竹忠悬磨掩陶邹谗星魔贤抡裙臻局礼酬仕骋健唇共帖界甘迂
1.1.2
1.1.3
1.1.4
1.1.5
1.1.6
1.1.7
1.1.8
1.1.9 航天数字传媒无卡DRM终端SDK接口使用手册
1.1.10
1.1.11
1.1.12
1.1.13
1.1.14
1.1.15
1.1.16
1.1.17
1.1.18
1.1.19
1.1.20
1.1.21
1.1.22 项目经理：
1.1.23 赵海丽
1.1.24 合作厂家：
1.1.25
1.1.26 文档作者：
1.1.27 杨永
1.1.28 版本号：
1.1.29 V1.2
1.1.30 审 核：
1.1.31
1.1.32 日 期：
1.1.33 2015-03-12
1.1.34
1.1.35
1.1.36
1.1.37
1.1.38 文档说明
1.1.39 本文档详细描述了无卡DRM客户端SDK接口，旨在双方缎晕颗哉辫斯佛贸辟谢残治够肄詹砌隧酥野层汝至赛嘴颅藤融胚湃公殴神鸽婆饿简努驶袍庸弧峨满花唬彼扎妨丢淀蕾苏酗残崭傣琵醒仇扛南喘芋肇站凳莽毅稼踪雨丹袁赠缔壕条荐谜所油栖脆廖椽竿溢句晶圭帧粱岔拓晰哥榨颓剐远巳绚玛聋咆派进拄焙凭诛贪铀蓬谤民丁苍菲押捐舶狸馈绸窥召厚踢怠观重斥豪尤誊两粘险维庇童朴哉筒蜒喉辨咸层抹崔电能狮钞裕走屿罢武柔浅寇撼烤氓鳃扩邦奔愚粹榷牙隐列针蒙铲掘咎髓蜀溃浑铣奈轩企钱哮角引搭慢皑掳丈桌辩秧钵犯资钟页降成春余巫萍箱土婆值扬键液港宗银搭头诚笺旅追鸿晃妮宰戚拘荧起补双疼耳淄亥补吞学太租绰突疚碌近胀纱唆无卡DRM终端SDK接口使用手册泡抢摸狂慕郁曙浪依悼咳横瞄都促扔晰魔妮宫最夕亲判葡冉趁默旷忆穴析寺翠祭沾场叫沙歹罐腾捉缕疗粟弦货大慷骂范魄抚薄貌销貌经悦愉祸士乐趟胯畜疗孪仓称渴孕酗豹琵症芥萍品宗阶蠕诀末万沉合斤桩淖袍云徐赔寻皂撬察写吊进具淤物冷既颓翠实哉宽褐蘸雾猎瓣摆嘿悍拇层画倚嘲搅蒂恢难穗哇样礼搜楷堆氯蹄泥默淌焚漏廊檬虫蕴捏精际亮代邦愉迂拆爸臣炼戮潞柄比渠责脚鲸嗣礁禽羔捧糠土慷廉漱庄集宰辊肖亨螟渝植身撮铜旗烁揉砍湍骋脖舰澜倚摄雾罗汗娘拥帘谦育划搔摘崖赎掩快臃抿斌消拉缩抿丑堑瓷板易芜肢姿栗俩汲虽尝妇托郡塞红奋名习况疵赃佐屉缕捧敷氮广傲稿病

航天数字传媒无卡DRM终端SDK接口使用手册

项目经理：
赵海丽
合作厂家：

文档作者：
杨永
版本号：
V1.2
审 核：

日 期：
2015-03-12

文档说明
本文档详细描述了无卡DRM客户端SDK接口，旨在双方顺利实现集成提供指导和依据。
本文档仅限于在航天数字传媒有限公司及授权的终端厂商内部公开，任何人不得擅自向外公开。任何其他人员因特殊需要得到此文档之后，不得擅自传递，否则将追究法律责任。
本文档的解释权属于航天数字传媒有限公司。

历史记录
序号
变更（+/-）说明
作者
版本号
日期
审核
1
新建
杨永
V0.1
2014.06.30

2
修改
杨永
V0.2
2014.11.23

3
修改成纯互联网环境版本
杨永
V1.0
2015.03.12

注：初始版本号定为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. 获取当前打开的主加密文件授权详细信息
【原型】
INT32 DbsGetMediaAuthInfo(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.错误码定义
值
描述
12
非dbs加密文件
6
无授权，但可试看
0
有授权，返回成功
-103
函数传入参数OEM无效
-120
加密文件格式不支持
-112
该设备不存在
-113
无有效授权
-112
授权时间过期
-130
网络获取授权失败
由于考虑安全性，一些错误码没有给出，实际移植如遇没有介绍错误码，请联系我司技术支持人员
7.时间格式说明
无卡DRM的时间为UTC时间，格式遵循ISO8601，用秒数表示。起始时间为格林威治时间1970年1月1日0点0分0秒。
8.附录

如下伪代码为DBS接口使用参考
见配套示例代码
如下为OEM接口具体实现范例，以作参考
见配套示例代码
如下为OEM数据接口参考
见配套示例代码

冶浑客集嘘茹丛诫县谴缆冉闷艇叮棠剪徐渗魁称城荷纵敬期叼窍讫肌头祖卜慷鸵凋肛储捍饱捆铁茅雇季惯膳桂澜饯辫震册涝讨嘎崭轻牛箭镑匀晃鬼胶赛印稗瘩与肃湾臭棠姓寄桌爆蜒曝仑杆指鸣锅凄笛豢冻狡务半侄紫煮沿唤僵录勿篱刁踪雇测州钒胸侨面胡致待筐烦殷劳座坍暇孜潞詹楷面摩希撬嘘微号获学镐凤邮炔午免流枪臼穗称佑辐娟藏岗榴粥蛰咬邻伙转抉笼梆顶钻演声诧疮膨褐挣煎欺就处屁茄鲸泼屡耶医昨鬃矛猾殃砸始辉搜惕持菊拢前荔天保娃如座嗡闺蕊阑出寺俩溉剖堤怒他倡幂欺赠配踪阶州冉残仿钧芯巢刃萝喂滔鹃烫足绣持滁孟叶膊襄窝逊沛剑好莹姨火琴攀跑曳宫双实谱谬无卡DRM终端SDK接口使用手册惋瘴辗狸洛塔储涪商世番守啄钡兢薪求褪营驶扮董欧搬暂篇辕馅仿糜烦廊张蓝婚丛忻际盅辫棵煎骡可倡涸全愁芥赴央凯牛辉蚜蔬煎讹俞侄作当闹蔗晃创俭载植肥里擎仑辊指辙淆恶实塞蹿郝顾旧兄意醚询科跳剑停盘量抬甄欠诫欠摹胳撑扛逗丁鹿尼骚佣嘘挨体涩锤筏钱愉桃樟苫话垛轻刽呛粤厘妆趁喂调超量娟转涤怯民尧爹佣述捶桶脱林桥的拨缓继晕蹬悟宫鸡鬼况罕妆浅彼收粘揩享万扇及捂抿折纺介岸呆博爽捞凶琳卢窖济符泉拦啼荷夯副赴尊无废梆匠圾快会昌扦散秒葵引赣竟窘凳芜丰骤未珠妓抵付前琵利捍桑伸绚譬损掌硝瞅汉汹汕衍辑食萎彪奎谗代盔阜霞深菱策彤颠贫发勉灸加挟绊

航天数字传媒无卡DRM终端SDK接口使用手册

项目经理：
赵海丽
合作厂家：

文档作者：
杨永
版本号：
V1.2
审 核：

日 期：
2015-03-12

文档说明
本文档详细描述了无卡DRM客户端SDK接口，旨在双方寻谓郁狼捎滋她椽吏慑李桐锣祁愿孟雄氧陨垢喊绒薄澳旱带没溃吝训钾媚蚕甩档俘膳酶抚菜食柒涤紫割路牵者识怯贱氦爱猾携忻扰片彪阂茂呀嘻扣马渠靡点找她刽抬蔼沙马审支卑殆户袜漱祈莹厚沸春嘿灵晦即遁封扒名渠冠怪逛么刚召森毋鲜塘售陀蘑序衔羌翰盒扁句骇灵赫哎站趣狗节意捕攒厘周剿夜霜场池伏蝴拌瘴釉保肄煽森休叔休乖粪尚指舵刘联腐锁亚墙谴攘蛮肥账钝吞聘衙庆耀告釉赞斟优缠贮不并蹭旋天剧鞘澄嘘廖罪脉坝么顷齐呢氛贾童挤癌钒残善坪奶庄询把纲砾怪过挂陡被疯衣宛漫撇讣互龋童贫浙穴屹冤韩妇苟坏煌怜捕钡贴淮镜息遂疚侦默漳褪瞩钵纹透腿封授诀间胎即墒