(2012年2月8日更新)
安天实验室 APM开发小组

1      简介

Antiy Password Mixer（APM）是安天针对当前拖库等安全威胁发布的一套安全算法应用范例。其适用于中小规模的BBS、SNS、留言板、网页游戏等常见的WEB应用，以及其他可能通过网页进行用户注册、认证与密码管理的网站应用场景。APM面向WEB应用的规划、开发和维护者使用，可以解决WEB后台大多数身份认证和关键信息加密保存的需求。

APM是完全开源的，目前已经发布了Python版本、PHP和Ruby的版本。我们为APM提供后续的更新和对应的支持服务。

APM的相关特色包括：

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

但这一切是如何做到的呢？APM没有什么技术含量，也没有“自有自主知识产权”的国产算法，Python版本的主程序还不足300行。我们站在安全工程师的实践经验角度，利用现有的流行开源包，完成了对RSA、HASH+SALT算法的一个外围封装，给出了网站开发者应用这些算法的相对合理的范例。当然，这些开源包中的算法实现已经经过了我们的代码级安全分析。

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

当然，你也许鄙视会我们的代码，而希望自己去实现更精干和精彩的。我们只希望让更多的开发者了解安全并不神秘，一样有大量的资源可以借鉴和应用，只要我们合理去使用它们，我们就可以获得更多安全的保障。

2      安装指南

2.1运行环境

Python	PHP	Ruby
系统环境：Linux 运行环境：Python2.6 内存环境：256M 以上 处理器：PIII 以上处理器	系统环境：Linux 运行环境：PHP5 内存环境：256M 以上 处理器：PIII 以上处理器	系统环境：Linux 运行环境：Ruby 1.8.7 内存环境：256M 以上 处理器：PIII 以上处理器

2.2安装第三方库

在使用Antiy Password Mixer以前需要安装的的第三方程序或python模块列表如下：

1.       Openssl

在 ubuntu 下可以使用sudo apt-get install openssl 进行安装。

2.       kyotocabinet-1.2.72

下载地址：http://fallabs.com/kyotocabinet/pkg/ ，请选择下载 kyotocabinet-1.2.72.tar.gz。

下载后进行如下操作：

tar –zxvf kyotocabinet-1.2.72.tar.gz

cd kyotocabinet-1.2.72

./configure --prefix=/usr

make

sudo make install

3.       kyotocabinet-python-legacy-1.16

下载地址：http://fallabs.com/kyotocabinet/pythonlegacypkg/

请选择下载 kyotocabinet-python-legacy-1.16.tar.gz。

下载后进行如下操作：

tar –zxvf kyotocabinet-python-legacy-1.16.tar.gz

cd kyotocabinet-python-legacy-1.16.tar.gz

make

sudo python setup.py

4.       python-m2crypto

在 ubuntun 下可以使用 sudo apt-get install python-m2crypto 进行安装。

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/python-apm；

6.         sh ./initapm.sh。

执行python-apm目录下的initapm.sh后，会在/opt/AntiyPasswordMixer目录下创建两个目录。

具体描述如下表所示：

目录名称	存放文件名	描述
/opt/AntiyPasswordMixer /keys	1.       privkey.pem 2.       pubkey.pem	该目录下生成的文件分别是用于信息加密的私钥和公钥，在执行initapm.sh会生成到该目录下，请将privkey.pem妥善保存，并删除本机上的privkey.pem文件，防止泄密
/opt/AntiyPasswordMixer /database	userinfo.kch	该目录下生成的文件是保存用户信息的数据库，在首次调用用户注册接口后会生成该文件
/opt/AntiyPasswordMixer /database	pwd.lst	该目录下生成的文件是高频密码表，用于过滤高频密码，可以手工修改维护

3      接口使用方法

3.1 apm_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：保存用户信息失败，请确认磁盘空间是否不足，或数据库文件是否被破坏；

返回-7：密码为高频密码，用户不可使用该密码。

3.2 apm_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是否存在，以及该文件是否有权限访问；

返回-7：密码为高频密码，用户不可使用该密码。

3.3 apm_delete_user(user)

描述：删除用户及用户相关信息；

参数：

user (string) – 用户名称，不可以使用空字符串。

返回结果：

返回0：函数执行成功；

返回-1：无法打开数据库，请确认是否有访问/opt/AntiyPasswordMixer/database/目录的权限；

返回-2：用户名输入为空；

返回-3：该用户名不存在。

3.4 apm_authenticate_user(user, password)

描述：验证用户名及密码是否正确。

参数：

user (string) – 用户名称，不可以使用空字符串；

password(string) – 密码，不可以使用空字符串。

返回结果：

返回0：函数执行成功；

返回-1：无法打开数据库，请确认是否有访问/opt/AntiyPasswordMixer/database/目录的权限；

返回-2：用户名或密码输入为空；

返回-3：该用户名不存在；

返回-4：该用户己被置为无效用户；

返回-5：输入的密码错误。

3.5 apm_set_user_validity(user, validity)

描述：设置用户是否有效。

参数：

user (string) – 用户名称，不可以使用空字符串；

validity (int) – 有效性，输入0 该用户名失效，输入1 用户名有效。

返回结果：

返回0：函数执行成功；

返回-1：无法打开数据库，请确认是否有访问/opt/AntiyPasswordMixer/database/目录的权限；

返回-2：该用户名不存在；

返回-3：保存用户信息失败，请确认磁盘空间是否不足，或数据库文件是否被破坏。

4      FAQ

Q: 如何使用APM 提供的注册用户信息接口?

A: 使用方式如下：

   from apm import *

   ret = apm_register_user(“testuser”, “istest”, “testuser@test.com”)

   if ret == 0:

       print “register user successful !”

 

Q: 如何使用APM验证用户信息?

A: 使用方式如下：

   from apm import *

   if apm_authenticate_user(“testuser”, “istest”) == 0:

     print “authenticate user successful !”

   else

     print “authenticate user failed !”

 

Q: 如何使用APM 删除用户注册信息?

A: 使用方式如下：

   from apm import *

   apm_delete_user(“testuser”)

 

Q：使用APM希望保存用户的原始密码，怎么办?

A：APM 默认不保存用户的原始密码，如果需要保存，请修改apm_config.py 中的 g_apm_register_type 变量，将该值设置为1 ，则保存用户的原始密码。

 

Q: 如何设置数据库的存储位置?

A: 请修改apm_config.py 中的 g_apm_db_path 变量，例如 g_apm_db_path = “/usr/apm/base”。

 

Q: 如何设置公钥存放的位置

A: 请修改apm_config.py 中的 g_apm_pub_key_path 变量，例如 g_apm_pub_key_path = “/usr/apm/key”。

 

Q: 如何确保在调用用户注册函数效率最高?

A: 可选择不保存用户原始密码及其它信息，APM 默认不保存用户的原始密码，在调用apm_register_user函数时ext_info设置为空字符串，例如: apm_register_user(“testuser”, “istest”, “”)。

Q：使用APM希望过滤高频密码，怎么办?

A：APM 默认不过滤高频密码，如果需要过滤，请修改apm_config.py 中的 g_apm_check_frequently_used_pwd变量，将该值设置为1 ，则过滤高频密码。

 

Q：什么是高频密码?为什么要过滤高频密码？

A：安天针对当前拖库等安全威胁中泄露的密码进行统计，对用户使用最多密码进行排序的TOP 100的列表。

该列表中的密码使用数量占用户总数的20%~30%之间，是最容易被猜测命中及暴力破解的密码。APM中加入了高频密码的过滤功能，但出于效率的考虑该开关默认是关闭的。在APM的下一个版本中将会推出高频密码过滤在客户端可应用的Javascript脚本。