CAS认证服务器接口使用基础手册V.doc

密级：一般秘密机密绝密
CAS6.0认证服务器接口使用手册
（C）-北京信城通数码科技版权全部
版本历史
版本号
生效日期
版本说明/变更理由/变更内容
作者
备注
V1.0
-5-17
建立
霍云

V2.0
-5-30
修改
霍云

V3.0
-9-23
修改整合
霍云

变更说明：C：Create，初始创建；A：Add，增加内容；M：Mod，修改；D：Del，删除

目录
1 序言 5
1.1 企业介绍 5
2 J2EE接口 5
2.1 接口介绍 5
2.2 接口安装 6
2.2.1 Casproxy.jar 6
2.2.2 加载服务器组件到应用系统中 6
2.2.2.1 Web.xml 6
2.2.2.2 拷贝配置文件 7
2.2.2.3 拷贝运行文件 8
2.2.2.4 cas.properties 8
2.2.2.5 caslog.xml 9
2.3 接口说明 11
2.3.1 函数说明 11
2.3.1.1 类 AuthBroker 11
2.3.1.2 接口 AuthBrokerIF 12
2.3.2 使用示例 15
3 C接口 19
3.1 接口介绍 19
3.2 安装说明 19
3.2.1 解压缩 19
3.2.2 config说明 21
3.2.2.1 casserver.config 21
3.2.2.2 casclient.config 22
3.2.3 配置环境 22
3.3 C接口说明 23
3.3.1 创建代理 23
3.3.2 注销代理 23
3.3.3 证书用户登录 23
3.3.4 证书用户登出 24
3.3.5 口令用户登录 24
3.3.6 口令用户登出 24
3.3.7 用户令牌校验 24
3.3.8 用户令牌校验并取用户属性（接口1） 25
3.3.9 用户令牌校验并取用户属性（接口2） 25
3.3.10 用户令牌比较 26
3.4 调用说明 26
3.5 返回值代码 27
4 CAS for CIQ接口（C接口和PowerBuilder接口） 27
4.1 接口介绍 27
4.2 接口安装 27
4.2.1 解压缩 27
4.2.2 config说明 28
4.2.3 配置环境 30
4.2.4 安装成功测试 30
4.3 接口说明 32
4.3.1 函数说明 32
4.3.1.1 C接口说明 32
4.3.1.2 PowerBuilder调用说明 33
4.3.2 返回码定义 34
5 技术支持及售后服务 35

1 序言
1.1 企业介绍
北京信城通数码科技（以下简称信城通）是8月在北京中关村科技园区丰台园注册成立高新技术企业，是经信息产业部同意跨地域增值电信业务服务商。
信城通业务关键包含电子数据交换服务、在线数据处理服务、在线交易处理服务、网络信息技术服务、信息安全服务、产品及应用软件研发等领域。企业80％以上职员拥有本科及以上学历，同时拥有多位业内顶级技术教授和资深业务骨干。凭借良好人才优势、强大技术实力和专业服务队伍，为各级检验检疫机构及广大进出口企业用户提供优质产品和服务，并成为联接二者优异桥梁。
经信息产业部电信管理部门审核同意，企业取得了《中国电信和信息服务经营许可证》（京ICP 证010524）。9月20日取得《中关村科技园丰台园高新技术企业证书》（证书号：0121618F）。8月18日，信城通经过ISO9001：标准质量管理体系认证，并已经正式开启CMMI认证进程。
北京信城通数码科技现有职员150多人，全部为大专以上学历，其中硕士占7%，本科占70%，大专占23%。高级管理人员14%，技术人员62%，通常管理人员24%。
11月28日，信城通正式入住在中关村科技园区丰台园总部基地新办公楼，它是信城通自成立以来快速发展标志，也是信城通以后长久稳定发展坚实基础。
信城通将一直秉承以用户为中心、以市场为导向、以服务为基础、以技术为后盾、以创新求发展、以诚信立长久企业宗旨，脚扎实地，开拓进取，连续不停地为广大用户提供优质产品和服务。

2 J2EE接口
2.1 接口介绍
本手册介绍了CAS6.0认证服务器门户接口函数。这部分接口函数实现了两类功效：用户标识校验和取证书相关信息。本接口关键用于应用程序和CAS整合，经过调用本接口，应用程序使用CAS提供认证服务。本接口适适用于Java形式应用程序。

2.2 接口安装
2.2.1 Casproxy.jar
本接口现在封装在casproxy.jar中。应用程序使用时，取得casproxy.jar文件，放入对应目录中，并在应用程序工程中加入对应路径。

2.2.2 加载服务器组件到应用系统中
2.2.2.1 Web.xml
确定有效web.xml，本文件位置在应用WEB-INF目录下。
（1）假如Servlet版本为2.3，则需要增加：
<listener>
<listener-class>p.ice.ApplicationListener</listener-class>
</listener>
和
<servlet>
<servlet-name>ProxyManagerServlet</servlet-name>
<display-name>ProxyManagerServlet</display-name>
<description><![CDATA[this is a ice servlet]]></description>
<servlet-class>p.server.ProxyManagerServlet</servlet-class>
<init-param>
<param-name>progname</param-name>
<param-value>proxycomp</param-value>
</init-param>
<init-param>
<param-name>configFile</param-name>
<param-value>/WEB-INF/casconf/cas.properties</param-value>
</init-param>
<init-param>
<param-name>configLog4j</param-name>
<param-value>/WEB-INF/casconf/caslog.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
到适宜位置，
（2）假如Servlet版本为2.2，则需要增加：
<servlet>
<servlet-name>ProxyManagerServlet</servlet-name>
<display-name>ProxyManagerServlet</display-name>
<description><![CDATA[this is a ice servlet]]></description>
<servlet-class>p.server.ProxyManagerServlet</servlet-class>
<init-param>
<param-name>progname</param-name>
<param-value>proxycomp</param-value>
</init-param>
<init-param>
<param-name>configFile</param-name>
<param-value>/WEB-INF/casconf/cas.properties</param-value>
</init-param>
<init-param>
<param-name>configLog4j</param-name>
<param-value>/WEB-INF/casconf/caslog.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
到适宜位置，
说明：
因Servlet规范2.2不支持listener，所以不需要配置<listener>。
2.2.2.2 拷贝配置文件
在WEB-INF目录下建立新目录casconf，把配置文件（cas.properties和caslog.xml）拷贝到casconf下，完成后结构以下：

图2.2-1 casconf
2.2.2.3 拷贝运行文件
把对应jar文件：（commons-codec-1.3.jar、commons-collections.jar、commons-pool-1.2.jar、log4j-1.2.13.jar、ice.jar)拷贝到WEB-INF/lib目录下，这些Java库文件文件能够从产品光盘上取得或从网上下载，完成后目录内容以下：

图2.2-2 lib

2.2.2.4 cas.properties
它包含以下内容，以＃开头表示是注释，
名称
值
说明
Ice.Warn.Connections
0
显示连接警告信息，缺省为0
Ice.ACM.Client
0
用户端活动Socket连接空闲存活时间，超出此时间，连接将被关闭。缺省为0，表示严禁此功效。
Ice.Trace.Network
0－不跟踪
1－跟踪连接建立和关闭
2－类似1，但更具体部分
3－类似2，但跟踪数据

网络跟踪选项
Ice.ThreadPerConnection
1
每个连接关联线程数，在TCP连接条件下，一个socket连接能够有多个线程，但在SSL环境下只能设置为1（JSSE限制），
Ice.Plugin.IceSSL
IceSSL.PluginFactory
在使用SSL连接条件下，必需包含此插件。
IceSSL.Trace.Security
0－不跟踪，缺省值
1－跟踪少许信息
2－比较具体
SSL连接跟踪信息。
IceSSL.Client.Ciphers
NONE (RSA) !(EXPORT) !(NULL)
SSL协商时，支持密码算法。
IceSSL.Client.Keystore
F:/reports/certs/client.jks
证书和私钥库，javaKeyStore格式。
IceSSL.Client.KeystorePassword
changeit
密钥库密码，
IceSSL.Client.Certs
F:/reports/certs/cacerts.jks
可信任证书库
IceSSL.Client.CertsPassword
password
证书库密码
Cas.ConnectionPool.max.active
10
连接到CAS最大Socket连接数，缺省是20个。
Cas.ConnectionPool.wait.time
5
从Socket连接池中取得一个连接等候最长时间，超出这个时间，将返回错误。
Cas.Application.Login.Identity
sso-portal
应用系统在CAS服务器中注册应用系统标识。
Cas.Application.Login.Password
sso-password
应用系统在CAS服务器中注册应用系统标识对应口令。
Cas.CasServer.Endpoints
tcp -h 10.98.157.34 -p 10000
CAS服务器地址和端口号，仅支持IPV4，tcp表示是TCP协议，ssl表示是SSL协议，-h指定CAS服务器地址，-p指定CAS服务器端口号。
表2.1-1 cas.properties
2.2.2.5 caslog.xml
日志支持5个等级，等级越高，统计信息越具体。
等级
值
说明
1
fatal
严重等级，
2
error
错误
3
warn
警告（生产环境下设置等级）
4
info
信息（调试状态）
5
debug
调试（调试状态）
表2.1-2 caslog.xml
配置文件为xml格式，缺省条件下，日志输出到系统标准输出中，要修改只是日志等级，见红色部分。
2.2.2.5.1 缺省配置
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

<log4j:configuration xmlns:log4j="">
<appender name="stdout" class="org.apache.log4j.ConsoleAppender">
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%5p [%t] (%F:%L) - %m%n"/>
</layout>
</appender>
<root>
<priority value="info"/>
<appender-ref ref="stdout" />
</root>
</log4j:configuration>
2.2.2.5.2 输出到文件配置
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

<log4j:configuration xmlns:log4j="">
<appender name="rollfile" class="org.apache.log4j.RollingFileAppender">
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%5p [%t] (%F:%L) - %m%n"/>
</layout>
<param name="File" value="example.log" />
<param name="Append" value="true" />
<param name="MaxFileSize" value="100KB" />
<param name="MaxBackupIndex" value="1" />
</appender>
<root>
<priority value="info"/>
<appender-ref ref=" rollfile" />
</root>
</log4j:configuration>
说明：
1． 在<param name="File" value="example.log" />中要指定日志文件绝对路径，替换红色部分即可。
2． 在<priority value="info"/>中指定日志等级，替换红色部分即可。
3． 注意，<appender name="rollfile" class="org.apache.log4j.RollingFileAppender">和<appender-ref ref=" rollfile" />中蓝色部分名称要一致。

2.3 接口说明
2.3.1 函数说明
2.3.1.1 类 AuthBroker
java.lang.Object
cn.itownet.sdk.cas.AuthBroker
全部已实现接口：
AuthBrokerIF
方法摘要
static AuthBrokerIF
loginCheck(HttpServletRequest request, HttpServletResponse response)
验证用户登录令牌，假如没有发觉令牌，则重定向到门户进行登录， 登录成功后，再重新返回到本接口。
static AuthBrokerIF
tokenCheck(HttpServletRequest request, HttpServletResponse response)
验证现在已经登录用户令牌是否继续有效，当用户重新登录后，前次登录令牌将失效。
表3.1-1
2.3.1.1.1 loginCheck
public static final AuthBrokerIF loginCheck(HttpServletRequest request,
HttpServletResponse response)
throws java.lang.Exception
验证用户登录令牌，假如没有发觉令牌，则重定向到门户进行登录， 登录成功后，再重新返回到本接口。
参数：
request - http请求对象
response - http响应对象
返回：
－假如验证成功，返回AuthBrokerIF实例，能够取对应属性。
－假如为null，表示需要进行重定向，调用者只需返回即可。
－Exception，表示验证错误，不需要继续处理。
抛出：
java.lang.Exception
2.3.1.1.2 tokenCheck
public static final AuthBrokerIF tokenCheck(HttpServletRequest request,
HttpServletResponse response)
throws java.lang.Exception
验证现在已经登录用户令牌是否继续有效，当用户重新登录后，前次登录令牌将失效。
参数：
request - http请求对象
response - http响应对象
返回：
－假如验证成功，返回AuthBrokerIF实例，能够取对应属性。
－Exception，表示验证错误，说明本令牌已经失效，或没有找到令牌，能够进行错误处理。
抛出：
java.lang.Exception
2.3.1.2 接口 AuthBrokerIF
全部已知实现类：
AuthBroker
public interface AuthBrokerIF
方法摘要
java.lang.String
getC()
get subject's country
java.lang.String
getCN()
get subject's commonName
java.lang.String
getDN()
get subject's DN
java.lang.String
getEntityID()
get subject's entityID
java.lang.String
getL()
get subject's locality
java.lang.String
getO()
get subject's orgnization
java.util.Vector
getOs()
get subject's orgnizations
java.lang.String
getOU()
get subject's orgnizationUnit
java.util.Vector
getOUs()
get subject's orgnizationUnits
java.lang.String
getSN()
get certificate's serialNumber
java.lang.String
getSN0()
已过时。
java.lang.String
getST()
get subject's stateOrProvince
表3.1-2
2.3.1.2.1 getC
java.lang.String getC()
get subject's country
返回：
country code
2.3.1.2.2 getST
java.lang.String getST()
get subject's stateOrProvince
返回：
stateOrProvince
2.3.1.2.3 getL
java.lang.String getL()
get subject's locality
返回：
city
2.3.1.2.4 getO
java.lang.String getO()
get subject's orgnization
返回：
orgnization
2.3.1.2.5 getOs
java.util.Vector getOs()
get subject's orgnizations
返回：
all orgnizations
2.3.1.2.6 getOU
java.lang.String getOU()
get subject's orgnizationUnit
返回：
orgnizationUnit
2.3.1.2.7 getOUs
java.util.Vector getOUs()
get subject's orgnizationUnits
返回：
all orgnizationUnits
2.3.1.2.8 getCN
java.lang.String getCN()
get subject's commonName
返回：
common name
2.3.1.2.9 getDN
java.lang.String getDN()
get subject's DN
返回：
distinguish name
2.3.1.2.10 getSN0
java.lang.String getSN0()
已过时。
Warning, deprecated, please use getEntiryID
返回：
entity id
2.3.1.2.11 getSN
java.lang.String getSN()
get certificate's serialNumber
返回：
cert serial number
2.3.1.2.12 getEntityID
java.lang.String getEntityID()
get subject's entityID
返回：
entity id
2.3.2 使用示例
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
/**
* Servlet implementation class for Servlet: RedirectTestServlet
*
* @web.servlet name="RedirectTestServlet" display-name="RedirectTestServlet"
*
* @web.servlet-mapping url-pattern="/RedirectTestServlet"
*
*/
public class RedirectTestServlet extends javax.servlet.http.HttpServlet
implements javax.servlet.Servlet {
/*
* (non-Java-doc)
*
* @see javax.servlet.http.HttpServlet#HttpServlet()
*/
public RedirectTestServlet() {
super();
}

/*
* (non-Java-doc)
*
* @see javax.servlet.http.HttpServlet#doGet(HttpServletRequest request,
* HttpServletResponse response)
*/
protected void doGet(HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException {
try {
AuthBrokerIF abi = AuthBroker.loginCheck(request, response);
if (abi == null)
return;
response.setContentType("text/html; charset=GBK");
PrintWriter out = null;
try {
out = response.getWriter();
out.println("<html><head><title>"
+ "show-token-data</title></head><body>");
} catch (Exception e) {
e.printStackTrace();
return;
}
// verify info
out.append("<br><table>");
out.append("<tr><td>用户实体标识1-EID</td><td>" + abi.getEntityID()
+ "</td></tr>");
out.append("<tr><td>用户实体标识2-SN0</td><td>" + abi.getSN0() + "</td></tr>");
out.append("<tr><td>用户序列号SN</td><td>" + abi.getSN() + "</td></tr>");
out.append("<tr><td>DN</td><td>" + abi.getDN() + "</td></tr>");
out.append("<tr><td>国家信息C值</td><td>" + abi.getC() + "</td></tr>");
out.append("<tr><td>通用名称CN值</td><td>" + abi.getCN() + "</td></tr>");
out.append("<tr><td>用户地域L值</td><td>" + abi.getL() + "</td></tr>");
out.append("<tr><td>用户组织O值</td><td>" + abi.getO() + "</td></tr>");
out.append("<tr><td>用户组织OU值</td><td>" + abi.getOU() + "</td></tr>");
out.append("<tr><td>用户ST值</td><td>" + abi.getST() + "</td></tr>");
out.append("</table><br>");
out.println("</body></html>");
out.close();
} catch (Exception e) {
e.printStackTrace();
}
}

/*
* (non-Java-doc)
*
* @see javax.servlet.http.HttpServlet#doPost(HttpServletRequest request,
* HttpServletResponse response)
*/
protected void doPost(HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException {
try {
AuthBrokerIF abi = AuthBroker.tokenCheck(request, response);
response.setContentType("text/html; charset=GBK");
PrintWriter out = null;
try {
out = response.getWriter();
out.println("<html><head><title>"
+ "show-token-data</title></head><body>");
} catch (Exception e) {
e.printStackTrace();
return;
}
// verify info
out.append("<br><table>");
out.append("<tr><td>用户实体标识1-EID</td><td>" + abi.getEntityID()
+ "</td></tr>");
out.append("<tr><td>用户实体标识2-SN0</td><td>" + abi.getSN0() + "</td></tr>");
out.append("<tr><td>用户序列号SN</td><td>" + abi.getSN() + "</td></tr>");
out.append("<tr><td>DN</td><td>" + abi.getDN() + "</td></tr>");
out.append("<tr><td>国家信息C值</td><td>" + abi.getC() + "</td></tr>");
out.append("<tr><td>通用名称CN值</td><td>" + abi.getCN() + "</td></tr>");
out.append("<tr><td>用户地域L值</td><td>" + abi.getL() + "</td></tr>");
out.append("<tr><td>用户组织O值</td><td>" + abi.getO() + "</td></tr>");
out.append("<tr><td>用户组织OU值</td><td>" + abi.getOU() + "</td></tr>");
out.append("<tr><td>用户ST值</td><td>" + abi.getST() + "</td></tr>");
out.append("</table><br>");
out.println("</body></html>");
out.close();
} catch (Exception e) {
e.printStackTrace();
}
}
}
3 C接口
3.1 接口介绍
本手册介绍了CAS6.0认证服务器门户接口函数。这部分接口函数实现了两类功效：用户标识校验和取证书相关信息。本接口关键用于应用程序和CAS整合，经过调用本接口，应用程序使用CAS提供认证服务。本接口适适用于C语言应用程序。

3.2 安装说明
3.2.1 解压缩
Linux下安装时，先取得接口Linux版压缩包aspicas.tar.gz，然后用tar命令把aspicas.tar.gz解压缩到一个路径中。压缩包展开后内容以下：

其中：
目录
说明
casservertest
本目录中包含一个简单cas测试服务器，casservertest。
其中casserver.config为测试服务器配置文件，各项解释见2.2节

如目前路径在casservertest目录，服务器运行使用命令：
./casservertest –Ice.Config=casserver.config
config
用户端配置文件，casclient.config，各项解释见2.2节
include
CAS aspi C接口头文件，aspicas6.h
lib
CAS aspi C接口本身库文件为libaspicas_c.so.6.1.0
其它全部是接口依靠库文件

对于Windows版接口安装，请先取得Windows版接口压缩包aspicas.zip，然后把压缩包解压得如Linux版类似目录结构和内容：

其中lib目录下aspicas6c.dll是接口动态库，其它是接口依靠库文件

3.2.2 config说明
3.2.2.1 casserver.config
它内容以下：
―――――――――――――――――――