 | 级别： 初级 王 磊建 (wangleij@cn.ibm.com), 软件工程师
Albert Hsieh (hsiehcy@tw.ibm.com), 高级软件工程师
2007 年 6 月 28 日
本文介绍 Notes/Domino C API 8.0 中将要发布的 ID Recovery API。这些 API 的出现将使得合作伙伴以及 Notes 程序开发人员获得通过应用程序来加密、备份以及恢复 Notes ID 的能力，通过一些创造性的应用开发，就可以将繁琐的 ID 管理工作变得简洁而高效。
在本文中，我们将简单回顾 Domino 对于 Notes ID 备份和恢复等管理工作的基本流程，然后对 ID Recovery API 作简单介绍，最后通过一个应用程序实例，将这些 API 融合到一个服务器任务程序，展示了通过创造性的应用，ID Recovery API 将可能为客户带来的效率上的提升和崭新的体验。
对 Notes ID 备份恢复工作的简单回顾
Notes ID 的重要性是不言自喻的，没有了 Notes ID，将直接导致用户不能访问服务器、邮件以及用 Notes ID 加密过的私有信息。但是一个用户的 Notes ID 存在丢失或者损坏的可能性，更常见的情况是用户忘记了 Notes ID 的密码。为了防止这种危险状态，Domino 制定了一个相应的流程来进行 Notes ID 的备份和恢复。举一个简单的例子，假设有一个 Notes ID，它不含有恢复信息，现在要求为其添加正确的恢复信息，则相关流程如下：
- Domino 管理员在服务器端设置恢复信息
- 在服务器配置文档中选择 certification 项
- 点击“Edit Recovery Information”选项，在弹出的对话框里选择相应的 Server 以及 cert ID，点击确认按钮并输入 cert ID 的密码
- 在图 1 所示的对话框中进行相应的配置，包括 RA（Recovery Authority）的人数，恢复密码的长度等。
图 1. 配置 RA 人数和恢复密码的长度等
- 点击 Export 按钮，在图 2 所示对话框中进行相应的配置，包括目标用户的邮件地址，邮件头和邮件内容等。
图 2. 配置目标用户的邮件地址，邮件头和邮件内容等
- 用户确认恢复信息
在上面步骤之后，目标用户将会收到邮件，邮件里面包含最新的 ID 文件的恢复信息，用户选择菜单命令“Accept Recovery Information”就可以将恢复信息添加到自己的 Notes ID 文件当中。
- ID 的恢复
现在我们假设用户突然忘记了密码，于是他向管理员申请密码恢复。
- 管理员从 ID 备份库中取得该用户加密过的 Notes ID
- 在 Server 配置文件的 certification 项中点击“Extract Recovery Password”
- 选择 Notes ID 文件，确认之后，就可以得到对应着该管理员的恢复密码
由于一个 ID 文件可能有多个 RA，每个 RA 都依次执行上述步骤，用户在获得足够多的 Recovery Password 之后，就可以在客户端登陆要求输入密码的时候选择“cancel”，然后选择“Try to recovery your password”选项，在弹出的对话框中，依次输入恢复密码，确认之后输入新密码，就可以完成密码的恢复工作。
至此，我们完成了整个的 Notes ID 的加密、备份以及恢复的流程。可以看出这个流程虽然完整，但是还是存在如下的缺憾：
- 流程比较繁琐，因此也会比较费时，倘若用户丢失 ID，可能导致相当时间不能访问重要信息，这是绝对应该避免的状况。
- 设想一下必须对大量的 ID 文件进行这样的操作，对 Domino 管理员来说这简直是一场灾难。
请不必紧张， ID Recovery API 的出现可以使得 Domino 管理员们长吁一口气，通过这些 API，Notes 开发者能够以一种更便捷的方法来进行 Notes ID 的备份和恢复管理工作，下面我们就对这些 API 进行简单的介绍，并将开发一个简单的例子对其使用方法做进一步探讨，作者希望可以抛砖引玉，激发大家更加有创造性的应用。
ID Recovery API 的简单介绍
在 Notes/Domino C API 8.0 中，将发布六个与 ID Recovery 相关的 API，关于这些 API 的详细介绍，请读者查阅 API 用户手册，本节只对它们作一个概括性的介绍：
-
SECBuildEncryptedBackupIDFile
输入某 ID 文件的位置以及其密码，该 API 对指定的 ID 文件进行加密，并保存到指定位置。在用户要求的情况下，也可以返回 Domino Server 配置中指定的接收 ID 文件的邮件数据库的地址。
-
SECMailRecoveryID
输入某 ID 文件的位置以及其密码，该 API 会从指定的 ID 文件中抽取其中的 ID 恢复信息，然后创建一个 ID 备份文件，接着在指定的邮件数据库或者 mail.box 数据库中创建一个 mail note，将 ID 备份文件附着到 mail note 中，并发送邮件到 Domino Server 配置中指定的接收 ID 文件的邮件数据库。
-
SECGetRecoveryInfo
如果输入 certifier ID 的句柄，该 API 会从 certifier ID 中抽取 ID 恢复信息并保存到 RECOVERY_INFO 数据结构中；如果输入保存有 certifier 记录的 note 句柄，该 API 会从此 note 的 ITEM_RECOVERY_INFO 域中抽取恢复信息并保存到 RECOVERY_INFO 数据结构中。
RECOVERY_INFO 的定义如下：
typedef struct {
WORD Quorum;
WORD NumberOfRAs; // RA 的个数（最多八个）
WORD RALength[8]; // RA 的长度
char RAs[8][MAXUSERNAME+1]; //RA 的名字
WORD RecoveryPasswordLength; //恢复密码的长度
Char MailAddress[MAXPATH+1]; //接收ID文件的邮件数据库
char CustomMsg[MAX_IDRecovery_CustomMessage]; //定制的邮件体内容
} RECOVERY_INFO;
|
-
SECImportRecoveryInfo
将从 SECGetRecoveryInfo 函数中得到的恢复信息导入到指定的 Notes ID 文件中去。
-
SECExtractRecoveryPassword
根据输入的 RA（Recovery Authority）和加密过的 ID 备份文件，该 API 会从 ID 备份文件中获取相应的恢复密码。
-
SECRecoverIDFile
根据输入的多个 ID 恢复密码，恢复指定 ID 并为其设置新的指定密码。
现在我们已经了解了 ID Recovery API 的基本功能，接下来，我们就用一个简单的例子来看看这样的 API 可以为我们带来什么样的工作效率上的提升以及应用上的创新。
ID Recovery API 应用的简单例子
首先假设由于某些原因，某公司需要对大量的 Notes ID 进行加密备份，如果采用本文第一部分介绍的手工管理的方式，必然耗费大量的时间。现在我们使用 ID Recovery API 来设计一个简单的应用，来实现这个流程的程序化和自动化。为了使本例尽量简单，我们对一些问题进行了简化和省略，在真正的系统实现的时候，还有许多其它的工作要做，譬如说对 notes ID 的密码进行加密保护以及解密等。
整个系统的架构如图3所示：
图 3. 系统架构
系统设计思想如下：
- 首先创建一个 NSF 数据库 IDStore.nsf，并设计表单如下图所示：
图 4. 设计表单
表单设计说明：
- 用户 ID：Composite 域，用户将 ID 文件 attach 到这个域中；
- 加密后的 ID 名字：文本域，用户输入加密后 Notes ID 的名字；
- ID 密码：文本域，用户输入 Notes ID 的密码；
- 处理状态：文本域，非用户输入（实际应用中可设计为隐藏域），代表文档处理状态，服务器任务程序在处理完文档之后会修改域的状态，并据此判断本文档是否已经被处理。
- 没有 ID 加密备份文件的用户可以登陆本数据库，并将相关的信息写入数据库中。
- 生成的文档都会出现在 IDWaitProcess 视图之中。
- 设计一个服务器任务程序 processid.exe，该程序在运行期间，会不断查询 IDStore.nsf 数据库中的文档，并从中取出未处理文档中附有的 ID 文件以及相应密码，置于本地保存，然后修改文档的状态为“已处理”，最后调用 ID Recovery API 中的
SECBuildEncryptedBackupIDFile 函数对 ID 文件进行加密备份。加密之后的备份文件，可以保存到安全的地方，以备不测之需。
- 本实例程序的验证步骤如下：
- 创建 NSF 数据库 IDStore.nsf，表单和视图的具体设计如上所述。
- 用户登陆 IDStore.nsf 数据库，并填入正确的信息。
- 编译附件中的程序 processid.cpp，生成 processid.exe 程序。
- 将 processid.exe 程序拷贝到 domino 安装目录下。
- 在 domino 控制台运行命令“load processid”。
- 可以看到用户在数据库中添加的 ID 文件会被加密并备份到 D 盘根目录下（本实例程序仅适用于 Windows 系统）。
有关 Domino 任务程序的编程规范以及其它相关信息，请参考 Notes/Domino C API 的参考文档以及随 API Toolkit 一起发布的程序示例。本实例中的任务程序的设计结构可以参考如下代码：
//包含 C 头文件
……………………
//包含 Notes C API 头文件
……………………
char *DB_NAME="IDStore.nsf";
char *view_name = "IDWaitProcess";
STATUS doJob(char *);
void printAPIError(STATUS error);
STATUS LNPUBLIC note_action(VOID *db_handle,
SEARCH_MATCH far *pSearchMatch, ITEM_TABLE *summary_info);
STATUS LNPUBLIC AddInMain (HMODULE hModule, int argc, char *argv[]) // Server Task 入口点
{
/* 局部变量声明. */
STATUS error = 0; /* return code from API calls */
HANDLE hOldStatusLine; /* handle to initial default status line*/
HANDLE hStatusLineDesc; /* handle to new default status line */
HMODULE hMod; /* add-in task's module handle */
char statusline[] = "Build encrypted back up ID file from IDStire.nsf";
//服务器任务初始化
AddInQueryDefaults (&hMod, &hOldStatusLine);
AddInDeleteStatusLine (hOldStatusLine);
hStatusLineDesc = AddInCreateStatusLine(statusline);
AddInSetDefaults (hMod, hStatusLineDesc);
/* 开始循环，当 AddInIdle 函数返回 TRUE 时，退出循环 */
while (!AddInIdle()) {
/* For non-preemptive operating systems, give up control to other tasks.
OSPreemptOccasionally will do nothing in preemptive operating systems. */
OSPreemptOccasionally();
/*每隔三分钟检查 IDStore.nsf 数据库，查看是否有新的未处理文档出现*/
if (AddInMinutesHaveElapsed(3)) {
doJob(DB_NAME);
}
} /* 结束循环 */
return (NOERROR);
}
//执行任务
STATUS doJob(char *db_name){
DBHANDLE db_handle;
NOTEHANDLE note_handle;
NOTEID view_id;
STATUS error = 0;
//打开 "IDStore.nsf" 数据库
if (error = NSFDbOpen(db_name, &db_handle)) {
printAPIError(error);
}
//搜索 IDStore.nsf 数据库，如果有新的未处理文档出现，采取行动处理它
if (error = NSFSearch (
db_handle, /* database handle */
NULL, /* selection formula */
view_name, /* title of view in selection formula */
|-------10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- XML error: The previous line is longer than the max of 90 characters ---------|
0, /* search flags */
NOTE_CLASS_DOCUMENT, /* note class to find */
NULL, /* starting date (unused) */
note_action, /* action routine for notes found */
&db_handle, /* parameter to action routine */
NULL)) /* returned ending date (unused) */
{
printAPIError(error);
}
NSFDbClose(db_handle);
return error;
}
//打印 API 函数返回的错误值对应的文本信息
void printAPIError(STATUS error){
WORD len = 0;
char msgtxt[MAXUSERNAME] = {0};
len = OSLoadString(NULL, error, msgtxt, MAXUSERNAME-1);
AddInLogMessageText(msgtxt, NOERROR);
}
//NSFSearch 的回调函数，处理找到的文档
STATUS LNPUBLIC note_action(VOID *db_handle,
SEARCH_MATCH far *pSearchMatch,
ITEM_TABLE *summary_info){
STATUS err = NOERROR;
/*对于新的未处理文档采取如下动作
1) 提取 ID 文件
2) 得到 ID 文件的密码
3) 调用 ID recovery API 来创建加密备份文件，并加以保存
4) 修改当前处理文档的状态
*/
//具体的代码请参考附件 processid.cpp
return err;
}
|
总结
本文介绍了在 Notes/Domino C API 8.0 中将要发布的 ID Recovery API，并且用一个简单的应用实例展示了这些 API 可能带来的效率和效益上的提升，我们希望读者能从本文中有所收获，并根据现实中的具体问题实现更有创造性的应用。
下载 | 名字 | 大小 | 下载方法 |
|---|
| processid.zip | 3 KB | HTTP |
参考资料 学习
获得产品和技术
讨论
作者简介
对本文的评价
| |
