使用 ID Recovery API 实现 Notes ID 自动化管理

文档选项 未显示需要 JavaScript 的文档选项 样例代码

级别： 初级

王 磊建 (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，它不含有恢复信息，现在要求为其添加正确的恢复信息，则相关流程如下：

1. Domino 管理员在服务器端设置恢复信息
   1. 在服务器配置文档中选择 certification 项
   2. 点击“Edit Recovery Information”选项，在弹出的对话框里选择相应的 Server 以及 cert ID，点击确认按钮并输入 cert ID 的密码
   3. 在图 1 所示的对话框中进行相应的配置，包括 RA（Recovery Authority）的人数，恢复密码的长度等。
      
      图 1. 配置 RA 人数和恢复密码的长度等
      
      
      
   4. 点击 Export 按钮，在图 2 所示对话框中进行相应的配置，包括目标用户的邮件地址，邮件头和邮件内容等。
      
      图 2. 配置目标用户的邮件地址，邮件头和邮件内容等
      
      
      
2. 用户确认恢复信息

   在上面步骤之后，目标用户将会收到邮件，邮件里面包含最新的 ID 文件的恢复信息，用户选择菜单命令“Accept Recovery Information”就可以将恢复信息添加到自己的 Notes ID 文件当中。

3. ID 的恢复

   现在我们假设用户突然忘记了密码，于是他向管理员申请密码恢复。

   1. 管理员从 ID 备份库中取得该用户加密过的 Notes ID
   2. 在 Server 配置文件的 certification 项中点击“Extract Recovery Password”
   3. 选择 Notes ID 文件，确认之后，就可以得到对应着该管理员的恢复密码

   由于一个 ID 文件可能有多个 RA，每个 RA 都依次执行上述步骤，用户在获得足够多的 Recovery Password 之后，就可以在客户端登陆要求输入密码的时候选择“cancel”，然后选择“Try to recovery your password”选项，在弹出的对话框中，依次输入恢复密码，确认之后输入新密码，就可以完成密码的恢复工作。

至此，我们完成了整个的 Notes ID 的加密、备份以及恢复的流程。可以看出这个流程虽然完整，但是还是存在如下的缺憾：

1. 流程比较繁琐，因此也会比较费时，倘若用户丢失 ID，可能导致相当时间不能访问重要信息，这是绝对应该避免的状况。
2. 设想一下必须对大量的 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所示：

系统设计思想如下：

1. 首先创建一个 NSF 数据库 IDStore.nsf，并设计表单如下图所示：
   
   图 4. 设计表单
   
   
   

   表单设计说明：

   • 用户 ID：Composite 域，用户将 ID 文件 attach 到这个域中；
   • 加密后的 ID 名字：文本域，用户输入加密后 Notes ID 的名字；
   • ID 密码：文本域，用户输入 Notes ID 的密码；
   • 处理状态：文本域，非用户输入（实际应用中可设计为隐藏域），代表文档处理状态，服务器任务程序在处理完文档之后会修改域的状态，并据此判断本文档是否已经被处理。
2. 没有 ID 加密备份文件的用户可以登陆本数据库，并将相关的信息写入数据库中。
3. 生成的文档都会出现在 IDWaitProcess 视图之中。
4. 设计一个服务器任务程序 processid.exe，该程序在运行期间，会不断查询 IDStore.nsf 数据库中的文档，并从中取出未处理文档中附有的 ID 文件以及相应密码，置于本地保存，然后修改文档的状态为“已处理”，最后调用 ID Recovery API 中的 SECBuildEncryptedBackupIDFile 函数对 ID 文件进行加密备份。加密之后的备份文件，可以保存到安全的地方，以备不测之需。
5. 本实例程序的验证步骤如下：
   • 创建 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 */
		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 可能带来的效率和效益上的提升，我们希望读者能从本文中有所收获，并根据现实中的具体问题实现更有创造性的应用。

回页首

下载

	关于下载方法的信息

参考资料

• 参阅 developerWorks 文章 “体验 Lotus Notes 8 Beta2 新功能”。
  
  
• 参阅 developerWorks 文章 “IBM Lotus Notes/Domino V8 新特性”。
  
  
• 参阅 developerWorks 文章 “IBM Lotus Notes V8 中全新的 Out of Office 功能”。
  
  
• 参阅 developerWorks 文章 “扩展 IBM Lotus Notes V8 侧栏和工具栏”。
  
  
• 参阅“IBM Lotus Notes and Domino V8 Reviewer's Guide”。
  
  

• 下载 IBM Lotus Notes/Domino V8 的公共测试版。
  
  

• 参与 developerWorks Lotus 团队博客。

作者简介

		王磊建，IBM WPLC Toolkit Team 软件工程师，负责 C API 的相关工作, 电子邮箱：wangleij@cn.ibm.com。

		Albert Hsieh，IBM WPLC Toolkit Team Leader，电子邮箱：hsiehcy@tw.ibm.com。

对本文的评价

太差！ (1) 需提高 (2) 一般；尚可 (3) 好文章 (4) 真棒！(5) 建议？

回页首