安天实验 ANTIY PASSWORD MIXER FOR PHP 接口说明书

A NTIY P ASSWORD M IXER F OR PHP接口使用手册
安天实验室
2011-12-28
文档信息
修订记录
目录
第1章简介 (1)
第2章安装指南 (2)
2.1 运行环境 (2)
2.2 安装第三方库 (2)
2.3 安装过程 (2)
第3章接口使用方法 (3)
3.1 APM_REGISTER_USER (USER, PASSWORD, EXT_INFO) (3)
3.2 APM_CHANGE_PWD(USER, OLDPWD, NEWPASSWORD) (3)
3.3 APM_DELETE_USER(USER) (4)
3.4 APM_AUTHENTICATE_USER(USER, PASSWORD) (4)
3.5 APM_SET_USER_VALIDITY(USER, VALIDITY) (5)
第4章FAQ (5)
A NTIY P ASSWORD M IXER F OR PHP接口
使用手册
第1章简介
Antiy Password Mixer（APM）是安天针对当前脱库等安全威胁发布的一套安全算法应用范例。

其适用于中小规模的BBS、SNS、留言板、网页游戏等常见的WEB应用，以及其他可能通过网页进行用户注册、认证与密码管理的网站应用场景。

APM面向WEB应用的规划、开发和维护者使用，可以解决WEB后台大多数身份认证和关键信息加密保存的需求。

APM是完全开源的，目前已经发布了Python版本及PHP版本，Ruby的版本我们也在开发之中。

我们为APM提供后续的更新和对应的支持服务。

APM的相关特色包括：
简单，低代价的集成方案,能够容易的集成到现有的企业环境中
可有效对抗统计攻击、普通暴力破解、GPU加速破解、基于云计算的破解
具备加密单向不可还原数据和支持解密明文信息两种使用模式。

正确的经过严格代码审查的算法实现
在当前0day横行，几乎没有网站和应用可以绝对保证自己数据库系统的安全的情况下，使用APM能使数据库遭到窃取后的损失降低到最小程度，一旦被公开，也能将企业的社会压力和法律责任降低到最小限度。

但这一切是如何做到的呢？APM没有什么技术含量，也没有“自有自主知识产权”的国产算法，Python版本的主程序还不足300行。

我们站在安全工程师的实践经验角度，利用现有的流行开源包，完成了对RSA、HASH+SALT算法的一个外围封装，给出了网站开发者应用这些算法的相对合理的范例。

当然，这些开源包中的算法实现已经经过了我们的代码级安全分析。

我们希望用这种办法，让目前还在明文保存密码的网站和使用相关算法策略并不合理（比如那些联合使用HASH或者加入单一SALT的情况）的网站，能够了解如何科学使用这些数学方法，降低安全应用的门槛；我们也希望打消那些中小网站试图自己研究一个算法的努力。

放弃这些已经被经过理论和实践检验过的算法实现，而徒耗心力和人月，是不值得的。

当然，你也许鄙视会我们的代码，而希望自己去实现更精干和精彩的。

我们只希望让更多的开发者了解安全并不神秘，一样有大量的资源可以借鉴和应用，只要我们合理去使用它
们，我们就可以获得更多安全的保障。

第2章安装指南
2.1运行环境
系统环境：Linux
运行环境：PHP5
内存环境：256M 以上
处理器：PIII 以上处理器
2.2安装第三方库
在使用Antiy Password Mixer以前需要安装的的第三方程序或php模块列表如下：
1.Openssl
在ubuntu 下可以使用sudo apt-get install openssl 进行安装
2.php-db
在ubuntu 下可以使用sudo apt-get install php-db 进行安装
2.3安装过程
假设当前用户为antiytest，操作步聚如下:
1.创建目录sudo mkdir /opt/AntiyPasswordMixer
2.更改目录拥有者sudo chown –R antiytest /opt/AntiyPasswordMixer
3.下载AntiyPasswordMixer.tar.gz
4.tar –zxvf AntiyPasswordMixer.tar.gz
5.cd ./AntiyPasswordMixer/php-apm
6.sh ./initapm.sh
执行php-apm目录下的initapm.sh后，会在/opt/AntiyPasswordMixer目录下创建两个目录。

具体描述如下表所示：
第3章接口使用方法
3.1apm_register_user ($user, $password, $ext_info)
注册用户名、密码、以及其它信息到数据库中
参数:
$user (string) –用户名称，不可以使用空字符串
$password(string) –密码，不可以使用空字符串
$ext_info(string) –其它信息，可以使用空字符串
返回结果:
返回0: 函数执行成功
返回-1: 无法打开数据库，请确认是否有访问/opt/AntiyPasswordMixer/database/目录的权限
返回-2: 用户名或密码输入为空
返回-3: 该用户名己经注册
返回-4: 保存原始密码失败，请确认/opt/AntiyPasswordMixer/keys/pubkey.pem是否存在，以及该文件是否有权限访问
返回-5: 保存其它信息失败，请确认/opt/AntiyPasswordMixer/keys/pubkey.pem是否存在，以及该文件是否有权限访问
返回-6: 保存用户信息失败，请确认磁盘空间是否不足，或数据库文件是否被破坏3.2apm_change_pwd($user, $oldpwd, $newpassword)
修改密码
参数:
$user (string) –用户名称，不可以使用空字符串
$oldpwd (string) –原始密码，不可以使用空字符串
$newpassword(string) –修改后的密码，不可以使用空字符串
返回结果:
返回0: 函数执行成功
返回-1: 无法打开数据库，请确认是否有访问/opt/AntiyPasswordMixer/database/目录的权限
返回-2: 用户名或密码输入为空
返回-3: 该用户名不存在或输入的原始密码错误
返回-4: 该用户己被置为无效用户
返回-5: 保存用户信息失败，请确认磁盘空间是否不足，或数据库文件是否被破坏
返回-6: 保存原始密码失败，请确认/opt/AntiyPasswordMixer/keys/pubkey.pem是否存在，以及该文件是否有权限访问
3.3apm_delete_user($user)
删除用户及用户相关信息
参数:
$user (string) –用户名称，不可以使用空字符串
返回结果:
返回0: 函数执行成功
返回-1: 无法打开数据库，请确认是否有访问/opt/AntiyPasswordMixer/database/目录的权限
返回-2: 用户名输入为空
返回-3: 该用户名不存在
3.4apm_authenticate_user($user, $password)
验证用户名及密码是否正确
参数:
$user (string) –用户名称，不可以使用空字符串
$password(string) –密码，不可以使用空字符串
返回结果:
返回0: 函数执行成功
返回-1: 无法打开数据库，请确认是否有访问/opt/AntiyPasswordMixer/database/目录的权限
返回-2: 用户名或密码输入为空
返回-3: 该用户名不存在
返回-4: 该用户己被置为无效用户
返回-5: 输入的密码错误
3.5apm_set_user_validity($user, $validity)
设置用户是否有效
参数:
$user (string) –用户名称，不可以使用空字符串
$validity (int) –有效性，输入0 该用户名失效，输入1 用户名有效
返回结果:
返回0: 函数执行成功
返回-1: 无法打开数据库，请确认是否有访问/opt/AntiyPasswordMixer/database/目录的权限
返回-2: 该用户名不存在
返回-3: 保存用户信息失败，请确认磁盘空间是否不足，或数据库文件是否被破坏
第4章FAQ
A: 如何使用APM 提供的注册用户信息接口?
Q: 使用方式如下:
include_once("./apm.php");
$ret = apm_register_user(“testuser”, “istest”, “*****************”)
if (ret == 0)
{
print “register user successful !\n”;
}
A: 如何使用APM验证用户信息?
Q: 使用方式如下:
include_once("./apm.php");
if (apm_authenticate_user(“testuser”, “istest”) == 0)
{
print “authenticate user successful !\n”;
}
else
{
print “authenticate user failed !\n”;
}
A: 如何使用APM 删除用户注册信息?
Q: 使用方式如下：
include_once("./apm.php");
apm_delete_user(“testuser”);
A：使用APM希望保存用户的原始密码，怎么办?
Q：APM 默认不保存用户的原始密码，如果需要保存，请修改apm_config.php 中的$g_apm_register_type 变量，将该值设置为1 ，则保存用户的原始密码
A: 如何设置数据库的存储位置?
Q: 请修改apm_config.php 中的$g_apm_db_path 变量，例如$g_apm_db_path = “/usr/apm/base”;
A: 如何设置公钥存放的位置
Q: 请修改apm_config.php 中的$g_apm_pub_key_path 变量，例如$g_apm_pub_key_path = “/usr/apm/key”;
A: 如何确保在调用用户注册函数效率最高?
Q: 可选择不保存用户原始密码及其它信息，APM 默认不保存用户的原始密码，在调用apm_register_user函数时ext_info设置为空字符串，例如: apm_register_user(“testuser”, “istest”, “”);。