advanced_passport.htm

论坛软件系统亦称电子公告板(BBS)系统

		// 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);

	}
</pre></td></tr></table>

<p>passport_encode()是将数组转换合成为字串形式存储的函数：变量名和数值之间用等号连接，如果数值包含特殊字符，使用 urlencode() 将其转码。
多个变量间使用 & 分割。例如原始数组内容为 array('username' => 'abc', 'email' => '[e-mail]')，经过 passport_encode() 编码后
结果为 username=abc&email=my%2Bdiscuz%40gmail.com。

</ul><p class="subtitle">信息字串(auth)
<ul><p>应用程序在收到登录或注册请求，并读取到用户资料后，请按如下的要求将用户资料及部分其他信息存放于一个数组之中。数组各键值的含义为：

<ul><br><li>cookietime
<br>应用程序保存该用户登录记录的时间，可为非负整数，单位秒，Discuz! Passport 收到此参数后，会设置同样的 Cookie 过期时间，这样应用
程序和论坛可以保证同样的登录有效性。如不传递此参数，或参数数值不正确，则 Discuz! Passport 按照 0 设置 Cookie 有效期。

<br><br><li><b><u>time</b></u>
<br>应用程序所在服务器当前时间（9 或 10 位数字 Unix Timestamp），此参数用于 Discuz! 所在服务器当前时间进行比对，如果早于当前时间
超过若干秒（取决于 Discuz! Passport 中的“验证字串有效期”设定），则视为本 auth 内容无效，避免此URL被人得知后可能的安全问题。

<br><br><li><b><u>username</b></u>
<br>用户登录或注册的用户名。Discuz! 的注册用户名规则为：
<ul>
<li>长度 1~15 个字符，不得为空
<li>不得为 c:\con\con、游客(gb2312 或 big5 内码)、Guest
<li>不得包含 (,)、(*)、(")、([TAB])、([SPACE])、([\r])、([\n])、(<)、(>)、(&)其中之一
</ul>
<br>如果应用程序提交过来的用户名不符合上述规则，Passport 将自动去处其中的特殊字符，将过滤后的结果写入数据库中。

<br><br><li><b><u>password</b></u>
<br>用户密码经 MD5 不可逆加密后的值。如果此密码使用非 MD5 加密，则应用程序和 Passport 不能正常关联和使用。

<br><br><li><b><u>email</b></u>
<br>用户 Email 地址（50 个字节以内）。

<br><br><li>isadmin
<br>当前用户是否是应用程序的最高管理员，1=是，0=否。最高管理员的权限，将同步到论坛中去，其他下级管理员的身份将不进行同步，而由最高
管理员分别在不同的系统中进行设置。

<br><br><li>credits
<br>当前用户在应用程序中的积分值，范围 -2147483648 到 2147483647，如果 Discuz! Passport 中设置了目标积分项，则用户登录时，Passport
会把应用程序传递过来的 credits 值同步到指定的论坛的指定积分项目中

<br><br><li>gender
<br>当前用户的性别，1=男，2=女，0=未知。

<br><br><li>bday
<br>当前用户的生日，格式 yyyy-mm-dd。

<br><br><li>regip
<br>当前用户注册时的 IP 地址。

<br><br><li>regdate
<br>当前用户注册的时间（9 或 10 位数字 Unix Timestamp）。

<br><br><li>nickname
<br>当前用户的昵称（30 个字节以内，如传递此参数，必须打开相应用户组的昵称权限，否则用户在控制面板中提交个人资料时，会导致昵称失效）。

<br><br><li>site
<br>当前用户的主页地址（包含http://）。

<br><br><li>qq
<br>当前用户的 QQ 号码。

<br><br><li>ICQ
<br>当前用户的 ICQ 账号。

<br><br><li>msn
<br>当前用户的 MSN Messenger 账号。

<br><br><li>yahoo
<br>当前用户的 Yahoo! Messanger 账号。

</ul><p><b>以上参数中，以黑体下划线显示的 time、username、password、email 是必须传递的参数，缺少上述参数 Passport 将无法正常工作。其他的参数是可选的，如果
不传递某些参数，则 Passport 会进行识别，自动不更新没有传递的参数所在的字段。所有数值，请提供原始值，而非经过反斜线转义（addslashes）后
的结果。</b>


<p>把上述信息存放于数组中，假定为如下的形式：

<br><br><table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>

	$member = array
		(
		'cookietime'	=> 31536000,
		'time'		=> 1117415922,
		'username'	=> 'Abcd',
		'password'	=> 'e2fc714c4727ee9395f324cd2e7f331f',
		'email'		=> '[e-mail]',
		'credits'	=> 123,
		'regip'		=> '210.120.222.111',
		'regdate'	=> '1012752000',
		'msn'		=> '[e-mail]'
		);
</pre></td></tr></table>

<p>将其经过如下的加密变换，即可得到 auth 的值：

<br><br><table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>

	$auth = passport_encrypt(passport_encode($member), $passport_key);
</pre></td></tr></table>

<p>其中，passport_encode() 在前文已做了说明，用于将数组内容存放于特定的格式，$passport_key 是私有密匙。

<p><b>切记：由于 $auth 中可能含有等号、加号等特殊字符，请将 $auth 经过 rawurlencode() 编码后再在 URL 中传递，否则可能会产生问题。</b>

</ul><p class="subtitle">导向字串(forward)
<ul><p>导向字串用于通知 Discuz! Passport 在完成自身操作后，返回到哪一个 URL 地址，例如 http://www.myforums.com/forumdisplay.php?fid=2。
如果 forward 为空，则默认导向到应用程序的首页

<p><b>切记：由于 $forward 中可能含有冒号、问号、等号等特殊字符，请将 $forward 经过 rawurlencode() 编码后再在 URL 中传递，否则可能会
产生问题。</b>

</ul><p class="subtitle">验证字串(verify)
<ul><p>验证字串用户检验 auth 和 forward 两个参数的合法性，避免非法构造参数进行破坏的可能。无论 auth 和 forward 变量是否存在，验证字串
（verify）的值均为：

<br><br><table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>

	$verify = md5($action.$auth.$forward.$passport_key);
</pre></td></tr></table>

<p>其中，$action 是当前执行的 Passport 操作，如 login 等等；$auth 是用户信息加密后，并经 rawurlencode() 之前的内容。$forward 是经
rawurlencode() 前的导向字串、$passport_key 是私有密匙。如果 verify 的值不匹配，则 Passport 拒绝进行下一步操作。

</ul><br></td></tr><tr><td class="title">Discuz! Passport 设置与启用</td></tr>
<tr><td><br>

<p class="subtitle">内置关联
<ul><p>Discuz! 以战略合作的方式，与业内知名的产品实现了 Passport 关联，目前内置了 SiteEngine 建站引擎（http://www.siteengine.net）和
Shopex 通用型网上商店系统（http://www.shopex.cn）的相关接口，这样用户只须透过在两套软件中简单的设置，即可开启这些关联。

</ul><p class="subtitle">其他应用程序
<ul><p>由于 Discuz! Passport 的高可扩展性和平台无关性，使得您可以参照前文的说明，稍稍改动小部分的代码，便将任何 B/S 模式的应用程序与
Discuz! 进行关联。

</ul><p class="subtitle">参数设置
<ul><p>您可以在 Discuz! 系统设置中，看到相应的通行证设置功能，在 Discuz! 合作伙伴的软件中，也可以找到这些设置入口。相关的操作已比较简单，
在此不再详细叙述。

</ul><p class="subtitle">特别说明
<ul><p>如果您先运营了论坛，后与其他应用程序启用了 Passport 关联，由于之前论坛中的用户数据没有同步，您需要先写一个导入程序，将论坛的用户
数据导入到应用程序的用户表中，否则以往在论坛注册的用户将无法通过 Passport 登录。已成功关联后新注册的用户无此问题。

<p>在开启了 Discuz! 通行证后，您仍然可以通过 logging.php?action=login 这个链接来登录论坛，以备调试之用，但页面上显示的链接将改为应用程序
的登录 URL。<b>注意：开启通行证后，建议您通过 Discuz! 选项关闭论坛本身的注册功能，以免用户通过论坛注册而产生无法同步的问题。</b>

<p>您可以在 Discuz! 的 api/passport.php 找到 Discuz! Passport 的全部源程序，您也许通过他更好的理解 Passport 的原理，更快的完成应用程序与
Discuz! 之间的整合。

</ul><br></td></tr><tr><td class="title">典型错误提示</td></tr>
<tr><td><br>

<p class="subtitle">Illegal request
<ul><p>非法请求，当验证字串 verify 不匹配时会产生此提示。可能是应用程序与 Discuz! 配置的私有密匙不同，或是通过 URL 传递前，未将必要的参数
（如 auth、forward 等）进行 URL 编码，也有可能是使用了经过 URL 编码的参数值用来计算 verify 的 md5 值造成。以 PHP 语言为例，正确的代码
应当是类似于的如下的格式：

<br><br><table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>

	$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");
</pre></td></tr></table>

</ul><p class="subtitle">Lack of required parameters
<ul><p>auth 内容解密后，缺少必要的信息 time、username、password、email。

</ul><p class="subtitle">Request expired
<ul><p>请求过期。当前服务器时间与应用程序提交过来的 time 之差大于 Discuz! Passport 中设置的请求有效期。可能是使用以往的代码非法尝试，也可能是
由于应用程序和 Discuz! 论坛所在的两台服务器，时间设置有误造成。

</ul><p class="subtitle">Invalid action
<ul><p>没有指定 Passport 所执行的 action。

</ul></td></tr></table>

<script language="JavaScript" src="footer.js"></script>
</body>
</html>