Discuz! Passport 接口技术文档
Discuz! Passport 的优点
Discuz! Passport 系统使用了 Discuz! 独有的技术，并不等同于以往使用过的一些方法，与传统的实现方式相比，具备（不限于）以下优势：
Discuz! Passport 的局限
您在开始利用 Discuz! Passport 进行二次开发时，需要了解这个系统的局限性，以对未来的工作进行正确的评估与安排。
Discuz! Passport 原理与流程
假设已设置如下变量或参数
开启通行证后的用户登录流程
开启通行证后的用户退出流程
开启通行证后的用户注册流程
本部分中，加下划线显示的部分，是需要对您的应用程序进行更改的部分，事实上，这部分更改会非常容易和方便。
Discuz! Passport 参数规格与加密方式
私有密匙(passport_key)
加密算法
/**
* Passport 加密函数
*
* @param string 等待加密的原字串
* @param string 私有密匙(用于解密和加密)
*
* @return string 原字串经过私有密匙加密后的结果
*/
function passport_encrypt($txt, $key) {
// 使用随机数发生器产生 0~32000 的值并 MD5()
srand((double)microtime() * 1000000);
$encrypt_key = md5(rand(0, 32000));
// 变量初始化
$ctr = 0;
$tmp = '';
// for 循环，$i 为从 0 开始，到小于 $txt 字串长度的整数
for($i = 0; $i < strlen($txt); $i++) {
// 如果 $ctr = $encrypt_key 的长度，则 $ctr 清零
$ctr = $ctr == strlen($encrypt_key) ? 0 : $ctr;
// $tmp 字串在末尾增加两位，其第一位内容为 $encrypt_key 的第 $ctr 位，
// 第二位内容为 $txt 的第 $i 位与 $encrypt_key 的 $ctr 位取异或。然后 $ctr = $ctr + 1
$tmp .= $encrypt_key[$ctr].($txt[$i] ^ $encrypt_key[$ctr++]);
}
// 返回结果，结果为 passport_key() 函数返回值的 base64 编码结果
return base64_encode(passport_key($tmp, $key));
}
/**
* Passport 解密函数
*
* @param string 加密后的字串
* @param string 私有密匙(用于解密和加密)
*
* @return string 字串经过私有密匙解密后的结果
*/
function passport_decrypt($txt, $key) {
// $txt 的结果为加密后的字串经过 base64 解码，然后与私有密匙一起，
// 经过 passport_key() 函数处理后的返回值
$txt = passport_key(base64_decode($txt), $key);
// 变量初始化
$tmp = '';
// for 循环，$i 为从 0 开始，到小于 $txt 字串长度的整数
for ($i = 0; $i < strlen($txt); $i++) {
// $tmp 字串在末尾增加一位，其内容为 $txt 的第 $i 位，
// 与 $txt 的第 $i + 1 位取异或。然后 $i = $i + 1
$tmp .= $txt[$i] ^ $txt[++$i];
}
// 返回 $tmp 的值作为结果
return $tmp;
}
/**
* Passport 密匙处理函数
*
* @param string 待加密或待解密的字串
* @param string 私有密匙(用于解密和加密)
*
* @return string 处理后的密匙
*/
function passport_key($txt, $encrypt_key) {
// 将 $encrypt_key 赋为 $encrypt_key 经 md5() 后的值
$encrypt_key = md5($encrypt_key);
// 变量初始化
$ctr = 0;
$tmp = '';
// for 循环，$i 为从 0 开始，到小于 $txt 字串长度的整数
for($i = 0; $i < strlen($txt); $i++) {
// 如果 $ctr = $encrypt_key 的长度，则 $ctr 清零
$ctr = $ctr == strlen($encrypt_key) ? 0 : $ctr;
// $tmp 字串在末尾增加一位，其内容为 $txt 的第 $i 位，
// 与 $encrypt_key 的第 $ctr + 1 位取异或。然后 $ctr = $ctr + 1
$tmp .= $txt[$i] ^ $encrypt_key[$ctr++];
}
// 返回 $tmp 的值作为结果
return $tmp;
}
/**
* Passport 信息(数组)编码函数
*
* @param array 待编码的数组
*
* @return string 数组经编码后的字串
*/
function passport_encode($array) {
// 数组变量初始化
$arrayenc = array();
// 遍历数组 $array，其中 $key 为当前元素的下标，$val 为其对应的值
foreach($array as $key => $val) {
// $arrayenc 数组增加一个元素，其内容为 "$key=经过 urlencode() 后的 $val 值"
$arrayenc[] = $key.'='.urlencode($val);
}
// 返回以 "&" 连接的 $arrayenc 的值(implode)，例如 $arrayenc = array('aa', 'bb', 'cc', 'dd')，
// 则 implode('&', $arrayenc) 后的结果为 ”aa&bb&cc&dd"
return implode('&', $arrayenc);
}
信息字串(auth)
应用程序在收到登录或注册请求，并读取到用户资料后，请按如下的要求将用户资料及部分其他信息存放于一个数组之中。数组各键值的含义为：
如果应用程序提交过来的用户名不符合上述规则，Passport 将自动去处其中的特殊字符，将过滤后的结果写入数据库中。
以 上参数中，以黑体下划线显示的 time、username、password、email 是必须传递的参数，缺少上述参数 Passport 将无法正常工作。其他的参数是可选的，如果不传递某些参数，则 Passport 会进行识别，自动不更新没有传递的参数所在的字段。所有数值，请提供原始值，而非经过反斜线转义（addslashes）后的结果。
把上述信息存放于数组中，假定为如下的形式：
$member = array ( 'cookietime' => 31536000, 'time' => 1117415922, 'username' => 'Abcd', 'password' => 'e2fc714c4727ee9395f324cd2e7f331f', 'email' => 'abcd@efgh.com', 'credits' => 123, 'regip' => '210.120.222.111', 'regdate' => '1012752000', 'msn' => 'email@hotmail.com' );
将其经过如下的加密变换，即可得到 auth 的值：
$auth = passport_encrypt(passport_encode($member), $passport_key);
其中，passport_encode() 在前文已做了说明，用于将数组内容存放于特定的格式，$passport_key 是私有密匙。
切记：由于 $auth 中可能含有等号、加号等特殊字符，请将 $auth 经过 rawurlencode() 编码后再在 URL 中传递，否则可能会产生问题。
导向字串(forward)
导向字串用于通知 Discuz! Passport 在完成自身操作后，返回到哪一个 URL 地址，例如 http://www.myforums.com/forumdisplay.php?fid=2。如果 forward 为空，则默认导向到应用程序的首页
切记：由于 $forward 中可能含有冒号、问号、等号等特殊字符，请将 $forward 经过 rawurlencode() 编码后再在 URL 中传递，否则可能会产生问题。
验证字串(verify)
验证字串用户检验 auth 和 forward 两个参数的合法性，避免非法构造参数进行破坏的可能。无论 auth 和 forward 变量是否存在，验证字串（verify）的值均为：
$verify = md5($action.$auth.$forward.$passport_key);
其中，$action 是当前执行的 Passport 操作，如 login 等等；$auth 是用户信息加密后，并经 rawurlencode() 之前的内容。$forward 是经 rawurlencode() 前的导向字串、$passport_key 是私有密匙。如果 verify 的值不匹配，则 Passport 拒绝进行下一步操作。
Discuz! Passport 设置与启用
内置关联
Discuz! 以战略合作的方式，与业内知名的产品实现了 Passport 关联，目前内置了 SiteEngine 建站引擎（http://www.siteengine.net）和 Shopex 通用型网上商店系统（http://www.shopex.cn）的相关接口，这样用户只须透过在两套软件中简单的设置，即可开启这些关联。
其他应用程序
由于 Discuz! Passport 的高可扩展性和平台无关性，使得您可以参照前文的说明，稍稍改动小部分的代码，便将任何 B/S 模式的应用程序与 Discuz! 进行关联。
参数设置
您可以在 Discuz! 系统设置中，看到相应的通行证设置功能，在 Discuz! 合作伙伴的软件中，也可以找到这些设置入口。相关的操作已比较简单，在此不再详细叙述。
特别说明
如果您先运营了论坛，后与其他应用程序启用了 Passport 关联，由于之前论坛中的用户数据没有同步，您需要先写一个导入程序，将论坛的用户数据导入到应用程序的用户表中，否则以往在论坛注册的用户将无法通过 Passport 登录。已成功关联后新注册的用户无此问题。
在开启了 Discuz! 通行证后，您仍然可以通过 logging.php?action=login 这个链接来登录论坛，以备调试之用，但页面上显示的链接将改为应用程序的登录 URL。注意：开启通行证后，建议您通过 Discuz! 选项关闭论坛本身的注册功能，以免用户通过论坛注册而产生无法同步的问题。
您可以在 Discuz! 的 api/passport.php 找到 Discuz! Passport 的全部源程序，您也许通过他更好的理解 Passport 的原理，更快的完成应用程序与 Discuz! 之间的整合。
典型错误提示
Illegal request
非法请求，当验证字串 verify 不匹配时会产生此提示。可能是应用程序与 Discuz! 配置的私有密匙不同，或是通过 URL 传递前，未将必要的参数（如 auth、forward 等）进行 URL 编码，也有可能是使用了经过 URL 编码的参数值用来计算 verify 的 md5 值造成。以 PHP 语言为例，正确的代码应当是类似于的如下的格式：
$action = 'login';
$auth = passport_encrypt(passport_encode($autharray), $passport_key);
$forward = 'http://www.discuz.net/index.php';
$verify = md5($action.$auth.$forward.$passport_key);
header("Location: http://www.discuz.net/api/passport.php".
"?action=$action".
"&auth=".rawurlencode($auth).
"&forward=".rawurlencode($forward).
"&verify=$verify");
Lack of required parameters
auth 内容解密后，缺少必要的信息 time、username、password、email。
Request expired
请求过期。当前服务器时间与应用程序提交过来的 time 之差大于 Discuz! Passport 中设置的请求有效期。可能是使用以往的代码非法尝试，也可能是由于应用程序和 Discuz! 论坛所在的两台服务器，时间设置有误造成。
Invalid action
没有指定 Passport 所执行的 action。