文章 姚 鑫 · 十一月 4, 2024 3m read

第十一章 本地进程间通信(管道) - OPEN 命令管道示例

OPEN 命令管道示例

以下是有效的命令管道OPEN语句。每个示例指定 10 秒的超时:

  OPEN "|CPIPE|1":"/nethome/myprog":10                                  // using shell, no args
  OPEN "|CPIPE|1":("/nethome/myprog":/WRITE):10                         // using shell, no args, WRITE
  OPEN "|CPIPE|2":/COMMAND="/nethome/myprog":10                         // no shell, no args
  OPEN "|CPIPE|3":("":/COMMAND="/nethome/myprog"):10                    // no shell, no args
  OPEN "|CPIPE|4":(/COMMAND="/nethome/myprog":/ARGS=arg1):10            // no shell, 1 arg
  OPEN "|CPIPE|5":("/nethome/myprog":/ARGS=arg1):10                     // no shell, 1 arg
  OPEN "|CPIPE|6":("/nethome/myprog":/ARGS=arg1:/WRITE):10              // no shell, 1 arg, WRITE
  OPEN "|CPIPE|7":(/COMMAND="/nethome/myprog":/ARGS=arg1,arg2):10       // no shell, 2 args
  OPEN "|CPIPE|8":(/COMMAND="/nethome/myprog":/ARGS=args...:/WRITE):10  // no shell, args array, WRITE

Windows 系统上,参数可以包含空格或双引号 (") 字符。在这些情况下,可以将参数加引号,并且可以通过加倍来转义文字双引号字符:

  OPEN "|CPIPE|9":("/nethome/myprog":/ARGS="string with blanks"):10
  OPEN "|CPIPE|10":("/nethome/myprog":/ARGS="string with literal "" character"):10

OPEN Errors

如果对非 IPC 设备发出带有QW参数的OPEN命令,当您尝试写入此设备时发生错误。

以下 UNIX® 示例打开一个到 lp 程序的输出管道,在本例中该程序的路径名为/usr/bin/lp 。然后它通过此管道将全局^TEXT的输出发送到打印机。

print ; Send the first layer of global ^TEXT to the printer. 
      SET IO="/usr/bin/lp"
      OPEN IO:"QW"   ; Open the pipe to lp 
      USE IO WRITE "The first layer of ^TEXT",!   ; Print the title 
      ;  . . .
      ;  Print each line, using $ORDER on the global ^TEXT
      USE IO WRITE !,"The End.",#
      CLOSE IO    ; close the pipe, spooling the file to lpsched 
      QUIT

可以更改此示例,以便OPEN命令将参数传递给 lp 程序。例如,要指定lp应将输出发送到名为 Laserjet 的打印机设备,可以将SET命令替换为以下内容:

   SET IO="/usr/bin/lp -dlaserjet"

以下示例展示了如何从外部程序读取数据。此处,该进程打开一个到 UNIX® 程序 who 的输入管道,以便它可以读取当前登录到 UNIX® 的所有用户的 ID

getids ; read the login IDs of everybody currently on 
       SET IO="/usr/bin/who"
       SET $ZTRAP="EOT"
       KILL LOGINS 
       OPEN IO:"Q"
       ; note that "R" (the default) is understood 
       SET users=0
       FOR I=0:0 {
          USE IO
          READ USER
          SET users=users+1
          SET LOGINS(USER)=""
          }
       QUIT
EOT    SET $ZTRAP=""
       USE 0
       WRITE !,USERS," is/are currently logged on.",!
       CLOSE IO
       QUIT

Windows 系统上,当 CPIPE OPEN程序参数指定 /COMMAND/ARGS 时,系统使用 CreateProcess() 来运行该命令。如果 CreateProcess() 失败,则 OPEN将失败并显示错误。 GetLastError() 值可通过$SYSTEM.Process.OSError()获得。

UNIX® 系统上,当 CPIPE OPEN程序参数指定 /COMMAND/ARGS 时,系统会创建一个新进程,该进程发出 exec() 来运行该命令。如果 exec() 失败, OPEN将失败并显示错误。 exec() errno 可通过$SYSTEM.Process.OSError() 获得。

0
0 95
文章 姚 鑫 · 十一月 3, 2024 2m read

第十章 本地进程间通信(管道) - 用于进程间通信的 OPEN 命令

用于进程间通信的 OPEN 命令

OPEN命令允许程序与 IRIS 外部的进程进行通信。

OPEN Arguments

cpipename 管道名称

仅命令管道— “|CPIPE|”或"|CPIPE|xxxxxx" ,其中xxxxxx表示用户指定的唯一标识符。

program 程序

命令管道可以使用命令 shell 或不使用命令 shell(直接)执行程序。在大多数情况下,首选不使用命令 shell 执行。标准管道使用命令 shell 执行程序。

仅命令管道— 要在不使用命令 shell 的情况下执行,请指定 /COMMAND= program 。如果程序有参数,则必须使用 /ARGS 关键字指定它们。如果指定 /COMMAND/ARGS 关键字,则无需命令 shell 即可执行程序: (/COMMAND=program)(/COMMAND=program:/ARGS=arg1)(program:/ARGS=arg1)都是有效的语法。 /ARGS 可以采用单个参数、以逗号分隔的参数列表或数组。例如, (/COMMAND=program:/ARGS=arg1,arg2) 。可以使用数组指定可变数量的参数:

  SET array(1)=arg1, array(2)=arg2, array=2
  OPEN device:(/COMMAND=cmd:/ARGS=array...)

要使用命令 shell 执行,请指定program ,并省略 /COMMAND/ARGS 关键字。

程序字符串包含系统上安装的程序的完整路径名。它包含要在主机系统上执行的命令名称及其参数(如果有)。对于标准管道,限制为 <256 个字符。对于命令管道,最大长度取决于平台,但实质上超过 256 个字符。

parameters 参数

Read 对于标准管道,指定QQR以打开队列或管道以接受来自另一个进程的输入。对于命令管道:因为命令管道明确是管道,所以不需要Q字母代码;指定R

Write 对于标准管道,指定QW打开队列以将输入发送到另一个进程。对于命令管道:因为命令管道明确是管道,所以不需要Q字母代码;指定W

Read and Write 对于可以是读管道或写管道的标准管道,指定QRW以打开队列或管道以接受来自另一个进程的输入并将输入发送到另一个进程。对于命令管道:因为命令管道明确是管道,所以不需要Q字母代码;指定RW

可以使用 /关键字参数指定这些参数和其他参数,并用冒号分隔。例如, OPEN "|CPIPE|":(cmd:/READ:/IOTABLE="UTF8") 。以下可选关键字参数通常与管道一起使用:

  • K/ name / (或K num )以启用 I/O 转换(如果已在系统范围内启用转换)。可以通过指定表的名称来标识转换所基于的先前定义的表。用于打开和关闭协议的+-选项不适用于K协议。
  • Y/ name / (或Y num )告诉系统使用命名的 $X/$Y 操作表。可以通过指定表名称来识别先前定义的 $X/$Y 操作表(转换所基于的操作表)。 $X/$Y 操作始终启用。如果未指定Y并且未定义系统默认 $X/$Y,则使用内置的 $X/$Y 操作表。用于打开和关闭协议的+-选项不适用于Y协议。

可以通过上述参数指定S (流)、 F (固定长度)或U (未定义长度)模式参数。无法指定V (可变长度)模式参数。

closetimeout 关闭超时

可选— 仅限 UNIX®:可以指定关闭管道命令设备时CLOSE命令等待命令进程退出的秒数。默认值为 30 秒。可以通过在进程间通信的 CLOSE 命令上指定“I”(立即)参数来覆盖此关闭超时。

timeout 暂停

可选— 一个正整数,其值(以秒为单位)是 IRIS 等待OPEN成功完成的最长时间。如果 IRIS 能够在超时到期之前打开进程间通信,则会将$TEST设置为 1。如果 IRIS 在超时到期之前无法打开进程间通信,则会将$TEST设置为 0。如果忽略超时或指定0OPEN立即将控制权返回给进程。

0
0 63
文章 姚 鑫 · 十一月 2, 2024 2m read

第九章 本地进程间通信(管道)

本页介绍如何通过管道与 IRIS® 数据平台外部的进程建立通信。

介绍

可以通过管道在 IRIS 进程和外部 UNIX®Windows 进程之间进行通信,就像在 UNIX®Windows 操作系统级别一样。可以将输出发送到管道或从管道接收输入。管道为单向;不能同时读取和写入同一个程序。

当打开另一个程序的管道进行输出时,可以像写入顺序文件一样对其进行写入。然后程序使用编写的内容作为其输入流。当希望 IRIS 进程与外部进程共享资源时,此功能特别有用。

打开 IRIS 实用程序的管道

可以打开通往 IRIS 实用程序以及 UNIX®Windows 进程的管道。在将管道用于实用程序 I/O 之前,系统管理员必须在 IRIS 系统上定义管道设备。

系统管理员定义管道设备后,当运行实用程序(例如^%RD )时,可以使用系统管理员定义的助记符回答Device:提示。输出会自动发送到该设备。

管道和命令管道

IRIS 支持标准管道和命令管道 (CPIPE)。标准管道用于相对较短的命令字符串,其中命令名称及其参数少于 256 个字符。当命令字符串长度为 256 个字符或更长时,使用命令管道。在这两种情况下,管道只能在 UNIX®Windows 系统上使用。

标准管道 OPEN

以下是标准管道的OPEN命令语法:

OPEN program:(parameters):timeout

因为program是第一个参数(设备参数),所以它必须遵循OPEN命令设备名称的256个字符的限制。

如果对已打开的标准管道发出OPEN命令,则第二个OPEN将被忽略。没有发出错误。

OPEN 命令管道打开

以下是命令管道的OPEN命令语法:

OPEN cpipename:program:timeout
OPEN cpipename:(program:parameters:::closetimeout):timeout

cpipename参数可以采用值“|CPIPE|”如果只有命令管道同时打开。要打开多个并发管道,请指定"|CPIPE|xxxxxx" ,其中xxxxxx表示用户指定的唯一标识符。此cpipename参数是为后续USECLOSE命令指定的参数。

由于program是第二个参数,因此它不限于256个字符。程序的最大长度取决于平台。

如果对已打开的命令管道发出OPEN命令,则第二个OPEN将被忽略。没有发出错误。

0
0 93
文章 姚 鑫 · 十一月 1, 2024 2m read

第八章 在 I/O 命令中指定设备 - 通过 IRIS ID 指定设备

通过 IRIS ID 指定设备

为了与其他 产品兼容并方便起见,可以通过设备编号(存储在设备表中)来引用设备。系统管理员可以使用管理门户将这些号码链接到设备。选择“系统管理” 、 “配置” 、 “设备设置” 、 “设备”以创建新设备或编辑现有设备。

系统管理员还可以将一个数字转换为另一个数字。因此,可以发出OPEN 47IRIS 会将其转换为OPEN 49

下表显示了设备编号。

IRIS 设备编号和设备

Device Numbers 设备编号Devices 设备
0主要设备(您登录的设备)。
2IRIS 假脱机程序。 UNIX®:助记符 SPOOL 适用于该设备。
3设备编号无效。尝试打开它会返回 <NOTOPEN> 错误,而不等待超时到期。
63查看缓冲区。
20-46, 200-223常规联锁装置。
224-255作业间通信设备。

示例

要打开假脱机程序,请发出以下命令:

OPEN 2

指定磁盘上的文件

可以使用双引号括起来的操作系统文件规范来打开磁盘文件。

Windows 文件规范具有以下格式:

device:\directory\file.type

UNIX® 文件规范具有以下格式:

/directory/name

UNIX 示例

如果 UNIX®Windows 系统上的当前默认目录是 /usr/user,则可以通过指定以下方式打开存储在当前默认目录中的名为pat_rec.dat的文件:

   OPEN "pat_rec.dat"

系统自动打开该文件。对于新文件,请包含参数字符串WN以避免挂起。

要打开存储在另一个目录中的同名文件pat_rec.dat ,还必须指定该目录,如下所示:

   OPEN "/usr/elsewhere/pat_rec.dat"
0
0 70
文章 姚 鑫 · 十月 31, 2024 2m read

第七章 在 I/O 命令中指定设备

当使用 I/O 命令OPENUSECLOSE在除正在使用的设备之外的任何设备上处理 I/O 时,必须指定一个 I/O 设备。可以根据设备类型以三种方式之一指定设备,如下表所示。

I/O 命令中指定设备

Type of Specification 规格类型Use for these Devices 用于这些设备
IRIS 设备名称Terminals and Printers 终端和打印机
IRIS 设备 ID 或设备别名除顺序文件外的所有设备
File Name 文件名Sequential Files 顺序文件

请注意,WindowsUNIX® 处理打印机I/O 的方式不同。有关详细信息,请参阅打印机。

按设备名称指定终端和打印机

如果的 I/O 操作是针对终端(或某些平台上的打印机),则可以使用操作系统(UNIX®Windows)应用的设备名称来指定设备。形式如下:

OPEN "device"  
USE "device"  
CLOSE "device"

其中device是设备的操作系统名称,用引号引起来。设备的最大长度为 256 个字符。

Windows 系统上指定终端

要打开连接到串行通信端口的 I/O 设备,请使用以下语法指定OPEN命令:

OPEN "comn:"

其中n表示设备所连接的端口号。

   OPEN "com1:"

UNIX® 上指定终端和打印机

要在具有 UNIX® 设备名称 /dev/tty06 的终端上打开 I/O 设备,请输入以下命令

 OPEN "/dev/tty06"

UNIX® 系统上,打印机由OPEN命令上的名称来标识,并在 tty 设备上作为“字符特殊”文件进行处理。因此,支持的OPENUSE命令参数与终端 I/O 的参数相同,而不是顺序文件 I/O。在 Windows 系统上,打印机 I/O 的处理方式与顺序文件 I/ 类似。

0
0 97
文章 姚 鑫 · 十月 30, 2024 2m read

第六章 主设备、当前设备、空设备

明确使用主设备

USE 0USE $principal向进程的主体设备隐式发出OPEN命令。如果另一个进程拥有该设备,则该进程会挂在隐式OPEN上,就像它遇到任何OPEN时一样。

为该进程不拥有的任何其他设备(由于先前的OPEN命令)发出USE命令会产生错误。

仅当进程获取设备时,没有超时的OPEN命令才将控制权返回给进程。可以通过键盘中断命令(如Ctrl-C )中断打开命令。由于保护问题或无效设备名称而无法成功的OPEN将永远挂起。当在OPEN命令中指定超时时, OPEN将在超时到期时将控制权返回给进程。

使用主设备的选项

根据主要设备的性质,可以指定其他特定于设备的参数,这些参数对于管道(进程间通信) 、文件和终端 I/O是不同的。例如,可以使用 TLS 连接打开主设备:

USE $principal:(::/TLS=ConfigName)

其中ConfigName是同一实例中定义的 TLS 配置的名称。

空设备

如果应用程序生成不希望出现在屏幕上的无关输出,可以将该输出定向到空设备。可以通过发出带有适当参数的 IRIS OPEN命令来指定空设备(见表)。 IRIS 将其视为虚拟设备。

空设备参数

Platform 平台Null Device Argument 空设备参数
UNIX®/dev/null/
Windows//./nul

后续READ命令立即返回空字符串。随后的WRITE命令立即返回成功。没有读取或写入实际数据。 NULL 设备完全绕过 UNIX® 打开、写入和读取系统调用。

注:如果从 IRIS 内部以外的地方打开 NULL 设备(例如,通过将 IRIS 输出从 UNIX® shell 重定向到 /dev/null),则 UNIX® 系统调用确实会像对任何其他设备一样发生。

注:当一个进程使用JOB命令启动另一个进程时,Jobbed 进程的默认主要输入和输出设备是空设备。

0
0 90
文章 姚 鑫 · 十月 29, 2024 2m read

第五章 主设备、当前设备、空设备

一个进程拥有一台设备

一次只有一个进程可以拥有一个设备,顺序文件除外。

换句话说,在进程成功向设备发出OPEN命令后,在第一个进程释放该设备之前,其他进程都无法打开该设备。进程通过以下任一方式释放设备:

  • 通过显式发出CLOSE命令。

  • 通过停下来。

每个进程都有一个主设备

每个 IRIS 进程都有一个主要输入设备和一个主要输出设备。默认情况下,这些是同一设备。当您登录终端并激活 IRIS 时,该终端将成为主要设备。由于 IRIS 隐式向该终端发出OPENUSE命令,因此可以立即向它发出READWRITE命令。 IRIS 主设备是操作系统指定为主输入设备的设备。 $PRINCIPAL特殊变量包含主设备的设备 ID

IRISI/O 命令定向到当前设备

IRIS 将输入和输出操作(包括READWRITEPRINTZLOAD命令)定向到当前设备。 $I特殊变量包含当前设备的设备 ID。当在终端上登录 IRIS 时, $IO最初包含终端的设备名称。换句话说,登录后,主设备和当前设备是相同的。在发出USE命令后,当前的设备( $IO中包含的设备)通常是执行的最后一次USE命令中指定的设备。

尽管可以在编程器模式下对主设备以外的设备发出OPENUSE ,但每次 IRIS 返回到>提示符时,它都会隐式发出USE 0。要继续使用 0 以外的设备必须发出USE在>提示符下输入的每一行中输入命令。

当主要设备成为当前的设备时

当执行以下任一操作时,主要设备将自动成为当前设备:

  • 首次登录。
  • 发出USE 0USE $principal命令。
  • 发出对%Library.Device 类的 ChangePrincipal()方法的调用。
  • 未设置错误陷阱时导致错误。
  • 关闭当前设备。
  • 返回程序员模式。
  • 通过发出HALT命令退出 IRIS
0
0 124
文章 姚 鑫 · 十月 28, 2024 2m read

第四章 I O 输入输出简介 - Read 命令

Read 命令

该命令从当前设备读取数据。对于某些设备,以星号开头的参数返回 ASCII 数字信息;对于其他人来说,它们表示控制功能。

语法

READ variable:timeout

WRITE 命令

该命令将数据写入当前设备。对于某些设备,以星号开头的参数允许使用其 ASCII 数值写入 ASCII 字符;对于其他人来说,它们表示控制功能。对于某些设备,以 # 字符开头的参数指示写入该字符的次数。

语法

WRITE variable

WRITE /mnemonic

WRITE /mnemonic 语法允许使用在助记符空间中的 IRIS 代码中定义的助记符来控制设备。助记符空间是一个 IRIS 例程,必须在OPENUSE命令中激活它,或者使用管理门户将其配置为设备的默认值。要了解如何定义和激活助记符空间,请参阅定义默认助记符空间。

要使用预定义的 ^%X364 助记符空间将光标移动到终端屏幕上的第 1 列第 2 行,请发出以下命令:

   WRITE /CUP(1,2)

CLOSE 命令

CLOSE命令释放指定设备的所有权。 CLOSE反转OPEN命令的效果。

语法

CLOSE device[:params] 

device

所需的设备名称、ID 号或助记符。

params

参数KIRIS 级别关闭设备,而不在操作系统级别关闭它。

K参数对 Windows 系统没有影响。该文件在操作系统级别关闭。

如果对主设备发出CLOSE命令,则主设备将保持分配给您的进程,直到注销为止。

其他几个条件可能会影响CLOSE的行为:

  • 如果由于某种原因停止向设备的输出, IRIS 可能无法完成向该设备的输出,在这种情况下无法关闭它,并且可能无法停止。例如,如果终端向操作系统发送Ctrl-S以告知其停止向终端输出,则必须通过按Ctrl-Q恢复向终端的输出。
  • 如果关闭当前设备, CLOSE会将系统变量 $IO 的值更改为主设备的值。仅当当前设备的所有输出完成后, CLOSE命令才会释放该设备的所有权。
  • 当进程停止时,系统会自动关闭该进程在 IRIS 中打开的所有设备。

如果由于某种原因停止向设备的输出 IRIS 可能无法完成向该设备的输出,在这种情况下可能无法关闭它或无法停止。

0
0 63
文章 姚 鑫 · 十月 27, 2024 1m read

第三章 I O 输入输出简介 - Use 命令

Use 命令

此命令使指定设备成为当前设备,并将特殊变量$IO设置为该设备。要使用主设备以外的设备,必须首先对其发出OPEN命令;否则,将收到错误。参数的含义与OPEN命令中的相同。

语法

USE device:(args):"mnespace"

device

所需的设备名称、ID 号或别名。设备的最大长度为 256 个字符。

args

可选— 某些设备所需的附加信息。管道(进程间通信) 、文件和终端 I/O的可用参数不同。

mnespace

可选— IRIS 例程的名称,包含控制助记符的定义,当将 I/O 定向到该设备时,可以与WRITE /mnemonic 命令一起使用。

Windows 上的使用示例

Windows 示例显示了用于通过 TCP 连接到远程主机larry上的时钟服务器的命令。它使用服务名称daytime ,本地系统将其解析为端口号。 USE命令用 PSTE 模式替换OPEN C 模式并关闭所有用户终止符:

   OPEN "|TCP|4":("larry":"daytime":"C")
   USE "|TCP|4":(::"PSTE")

UNIX® 上的使用示例

UNIX 示例显示了用于打开设备/dev/tty06I/O 通道并将其建立为当前设备的命令,并可以选择使用WRITE /mnemonicX364 终端助记符。

   OPEN "/dev/tty06"
   USE "/dev/tty06"::"^%x364"
0
0 91
文章 姚 鑫 · 十月 26, 2024 2m read

第二章 I O 输入输出简介 - Open 命令

Open 命令

OPEN建立指定设备的所有权并打开指定设备的 I/O 通道。此所有权将持续存在,直到发出CLOSE命令、进程终止或某些物理操作关闭设备。对于物理 I/O 设备或进程间通信(例如 TCP 连接),此所有权会阻止所有其他进程访问该设备。对于逻辑 I/O 设备(例如顺序文件),此所有权可能允许其他进程以某种形式共享访问该文件。打开同一顺序文件的多个进程的处理高度依赖于平台。强烈建议使用LOCK命令来限制对顺序文件的访问。

语法

OPEN device{:{(parameters)}{:{timeout}{:"mnespace"}}}

device

所需的设备名称、ID 号或助记符。设备的最大长度为 256 个字符。

parameters

可选— 一个或多个参数,指定某些设备所需的附加信息。该参数列表用括号括起来,列表中的参数之间用冒号分隔。管道(进程间通信) 、文件和终端 I/O的可用参数不同。

timeout

可选— 等待请求成功的秒数。前面的冒号是必需的。超时必须指定为整数值或表达式。如果超时设置为零 (0), OPEN将尝试打开文件一次。如果尝试失败, OPEN会立即失败。如果尝试成功,则成功打开文件。如果未设置超时 IRIS 将继续尝试打开设备,直到打开成功或手动终止该过程。

mnespace

可选—助记符空间的名称,包含与该设备一起使用的控制助记符,指定为带引号的字符串。将 I/O 定向到该设备时,可以通过WRITE /mnemonic 命令使用这些控制助记符。

Windows 系统上 OPEN 的示例

此命令打开从 Windows 系统到终端服务器的出站 Telnet 连接:

  OPEN "|TNT|node:port"

其中, node是节点名称, port是服务器上的 IP 端口。

此命令打开现有 Windows 文件的 I/O 通道:

   OPEN "c:\abc\test.out":"WS"

UNIX® 系统上的 OPEN 示例

此命令打开到 UNIX® 终端设备 /dev/tty06I/O 通道:

   OPEN "/dev/tty06/"
0
0 75
文章 姚 鑫 · 十月 25, 2024 2m read

第一章 I/O 输入/输出简介

本页概括地描述了如何在 IRIS 数据平台应用程序中以及在 IRIS 提示符下使用 I/O 设备。

介绍

IRIS 数据平台为多种不同类型的逻辑和物理设备提供支持。支持的逻辑设备包括:

  • 主要装置
  • 文件
  • 管道
  • TCP连接
  • 作业间通信 (IJC) 设备用于在 IRIS 进程之间进行通信
  • 假脱机程序

支持的物理设备包括

  • 终端
  • 打印机

I/O 命令概述

I/O 命令允许拥有、使用、读取、写入和关闭设备。要将 I/O 操作定向到设备,请首先发出以下命令:

  • 发出OPEN命令来建立所有权,除非该设备是主要设备。
  • 发出USE命令使该设备成为当前设备。
  • 随后的READWRITE命令将从该设备读取或写入该设备。
  • CLOSE命令释放设备的所有权,以便其他进程可以使用该设备。

以下通用语法适用于支持 ObjectScriptI/O 命令关键字的 I/O 命令:

OPEN device:paramlist:timeout:"mnespace"
USE device:paramlist:"mnespace"
CLOSE device:paramlist

其中paramlist可以是单个参数,也可以是括在括号中并用冒号分隔的参数列表:

 parameter  (parameter:parameter[:...]) 
```

参数可以是位置参数或关键字参数。关键字参数具有以下语法:

````java
/keyword[=value] 
```

前导斜杠区分关键字参数和位置参数值。位置参数值的含义源自其在冒号分隔列表中的位置。关键字参数值的含义源自指定的关键字。

请注意,位置参数和关键字参数都可以在同一个`paramlist`中指定。例如,以下示例混合位置参数和关键字参数,以使用 `JIS I/O` 转换以写入/顺序模式打开名为test.dat的新文件:

````java
   OPEN "test.dat":("NWS":/IOTABLE="JIS")
```
0
0 95
文章 姚 鑫 · 十月 24, 2024 1m read

第五十五章 安全元素的详细信息 - <ReferenceList> 详情

本节讨论在消息头中用作 <Security>子元素的 <ReferenceList> 元素。当以这种方式使用 <ReferenceList> 时,可以在签名之前执行加密。以下显示了此元素的一个示例:

<ReferenceList xmlns="http://www.w3.org/2001/04/xmlenc#">
   <DataReference URI="#Enc-358FB189-81B3-465D-AFEC-BC28A92B179C"></DataReference>
   <DataReference URI="#Enc-9EF5CCE4-CF43-407F-921D-931B5159672D"></DataReference>
</ReferenceList>

详情

在每个 <DataReference> 元素中,URI 属性指向消息中其他位置的 <EncryptedData> 元素的 Id 属性。

使用顶级 <ReferenceList> 元素时,<EncryptedKey> and <EncryptedData> 的详细信息有所不同,如下所示:

Scenario<EncryptedKey><EncryptedData>
<EncryptedKey> contains pointer to <EncryptedData>Includes <KeyInfo> (same for all associated <EncryptedData> elements)Does not include <KeyInfo>
Top-level <ReferenceList> element contains pointer to <EncryptedData>Does not include <KeyInfo>Includes <KeyInfo> (potentially different for each <EncryptedData> element.

消息中的位置

在 <Security> 中,应在关联的 <EncryptedKey> 之后包含一个 <ReferenceList> 元素。

0
0 72
文章 姚 鑫 · 十月 23, 2024 1m read

第五十四章 安全元素的详细信息 - <DerivedKeyToken> 详情

<DerivedKeyToken> 的目的是携带发送者和接收者可以独立使用的信息来生成相同的对称密钥。这些方可以使用该对称密钥对 SOAP 消息的相关部分进行加密、解密、签名和签名验证。

以下显示了部分示例:

<DerivedKeyToken xmlns="[parts omitted]ws-secureconversation/200512" 
                 xmlns:wsc="[parts omitted]ws-secureconversation/200512" 
                 wsu:Id="Enc-943C6673-E3F3-48E4-AA24-A7F82CCF6511">
   <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <Reference URI="#Id-658202BF-239A-4A8C-A100-BB25579F366B"></Reference>
   </SecurityTokenReference>
   <Nonce>GbjRvVNrPtHs0zo/w9Ne0w==</Nonce>
</DerivedKeyToken>

详情

该元素的各部分如下:

  • Id 是元素的唯一标识符。IRIS 会自动生成此标识符。
  • <EncryptionMethod>表示用于加密该数据的算法。

IRIS 中,可以指定此算法。请参阅指定块加密算法。

  • <SecurityTokenReference> 表示在计算派生密钥时用作基础的对称密钥。这可以包含一个 <Reference> 元素,其 URI 属性指向同一消息中的 <EncryptedKey> 或另一个 <DerivedKeyToken>

或者 <SecurityTokenReference>可以包含一个 <KeyIdentifier>,该 <KeyIdentifier> 引用所使用的 <EncryptedKey>SHA1 哈希值。例如:

<SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd" 
                               s01:TokenType="[parts omitted]#EncryptedKey" 
                               xmlns:s01="h[parts omitted]oasis-wss-wssecurity-secext-1.1.xsd">
   <KeyIdentifier EncodingType="[parts omitted]#Base64Binary" 
                              [parts omitted]#EncryptedKeySHA1">
                     U8CEWXdUPsIk/r8JT+2KdwU/gSw=
   </KeyIdentifier>
</SecurityTokenReference>
  • <Nonce> 是此派生密钥的密钥派生函数中的种子所使用的 base-64 编码值。

<DerivedKeyToken> 元素的计算使用 RFC 2246 中为 TLS 定义的机制的子集。

<DerivedKeyToken> 元素和关联的 <EncryptedData><Signature> 元素之间的连接处理如下:

  • 每个 <DerivedKeyToken> 都包含一个具有唯一标识符的 Id 属性。
  • 在每个已由给定 <DerivedKeyToken> 指示的对称密钥加密的 <EncryptedData>元素中,都有一个<SecurityTokenReference> 元素,其 URI 属性指向该 <DerivedKeyToken>
  • 在每个<Signature>元素中(其值由给定 <DerivedKeyToken> 指示的对称密钥计算),都有一个 <SecurityTokenReference> 元素,其 URI 属性指向该 <DerivedKeyToken>
  • 每个 <EncryptedData><Signature> 元素还包括具有唯一标识符的 Id 属性。
  • WS-Security 标头包含一个引用 <EncryptedData><Signature> 元素的 <ReferenceList>元素。

消息中的位置

<DerivedKeyToken> 应该包含在 <DerivedKeyToken> 中,位于引用它的任何 <EncryptedData><Signature> 元素之前。

0
0 57
文章 姚 鑫 · 十月 22, 2024 1m read

第五十三章 安全元素的详细信息 - <Signature> 详情

<Signature>的目的是携带可由消息接收者验证的数字签名。可以使用数字签名来检测消息更改,或者只是验证消息的某个部分是否确实由列出的实体生成。与传统的手写签名一样,数字签名是对文档的附加,只能由文档的创建者创建,并且不易伪造。

以下显示了部分示例:

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
   <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
      </CanonicalizationMethod>
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha256"></SignatureMethod>
      <Reference URI="#Timestamp-48CEE53E-E6C3-456C-9214-B7D533B2663F">
         <Transforms>
            <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></Transform>
         </Transforms>
         <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></DigestMethod>
         <DigestValue>waSMFeYMruQn9XHx85HqunhMGIA=</DigestValue>
      </Reference>
      <Reference URI="#Body-73F08A5C-0FFD-4FE9-AC15-254423DBA6A2">
         <Transforms>
            <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></Transform>
         </Transforms>
         <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></DigestMethod>
         <DigestValue>wDCqAzy5bLKKF+Rt0+YV/gxTQws=</DigestValue>
      </Reference>
   </SignedInfo>
   <SignatureValue>j6vtht/[parts omitted]trCQ==</SignatureValue>
   <KeyInfo>
      <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <Reference URI="#SecurityToken-411A262D-990E-49F3-8D12-7D7E56E15081" 
                    ValueType="[parts omitted]oasis-200401-wss-x509-token-profile-1.0#X509v3">
         </Reference>
      </SecurityTokenReference>
   </KeyInfo>
</Signature>

详情

该元素的各部分如下:

  • <SignedInfo> 指示消息中由此签名签名的部分,并指示这些部分在签名之前是如何处理的。

IRIS 中,可以指定摘要方法(由 <DigestMethod>Algorithm 属性显示)。请参阅指定摘要方法。

还可以指定用于计算签名的算法(由 <SignatureMethod>Algorithm 属性显示)。请参阅指定签名方法。

  • <SignatureValue 保存实际签名。在本例中,签名为 6vtht/[parts divided]trCQ==

该值是通过加密签名部分的连接摘要计算得出的。加密由发送者的私钥执行。

  • <KeyInfo> 标识用于创建签名的密钥。在 IRIS 中,<KeyInfo> 包含 <SecurityTokenReference>,它具有以下几种形式之一:
    • WS-Security 标头中前面的 <BinarySecurityToken> 的引用,如上例所示。在本例中,使用相应的私钥来创建签名。
    • 用于识别证书的信息,该证书可能是消息接收者先前收到并存储的。例如, <SecurityTokenReference> 可以包含证书的 SHA1 指纹,如下所示:
<SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <KeyIdentifier EncodingType="[parts omitted]#Base64Binary" 
                  ValueType="[parts omitted]#ThumbprintSHA1">
      maedm8CNoh4zH8SMoF+3xV1MYtc=
   </KeyIdentifier>
</SecurityTokenReference>

与前一种情况一样,使用相应的私钥来创建签名。

- 对 WS-Security 标头中先前的 <DerivedKeyToken>  的引用。例如:
<SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <Reference URI="#Enc-BACCE807-DB34-46AB-A9B8-42D05D0D1FFD"></Reference>
</SecurityTokenReference>

在这种情况下,签名是由该令牌指示的对称密钥创建的。

- 对隐含的 <DerivedKeyToken> 的引用。例如:
<SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd" 
              s01:Nonce="mMDk0zn8V7WTsFaIjUJ7zg==" 
              xmlns:s01="http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512">
   <Reference URI="#Id-93F97220-568E-47FC-B3E1-A2CF3F70B29B"></Reference>
</SecurityTokenReference>

在这种情况下,<Reference> 中的 URI 属性指向用于生成 <DerivedKeyToken>,的 <EncryptedKey>元素,而 Nonce 属性指示所使用的 nonce 值。

与前一种情况一样,派生密钥用于加密数据。

消息中的位置

如果有的话,<Signature> 元素应包含在<Security> 中,位于其使用的 <BinarySecurityToken> or <DerivedKeyToken> 之后。

0
0 84
文章 姚 鑫 · 十月 21, 2024 1m read

第五十二章 安全元素的详细信息 - <EncryptedData> 详情

<EncryptedData> 的作用是携带加密数据,部分示例如下:

<EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#" 
               Id="Enc-143BBBAA-B75D-49EB-86AC-B414D818109F" 
               Type="http://www.w3.org/2001/04/xmlenc#Content">
   <EncryptionMethod Algorithm="[parts omitted]#aes128-cbc"></EncryptionMethod>
   <CipherData>
      <CipherValue>MLwR6hvKE0gon[parts omitted]8njiQ==</CipherValue>
   </CipherData>
</EncryptedData>

详情

该元素的各部分如下:

  • Id 是元素的唯一标识符。 IRIS 会自动生成此标识符。
  • <EncryptionMethod> 表示用于加密该数据的算法。
  • <CipherData>携带加密数据,作为 <CipherValue>元素中的值。在此示例中,值 MLwR6hvKE0gon[parts divided]8njiQ== 为加密数据。
  • (未包含在示例中 <KeyInfo> 标识对称密钥。在本例中, <KeyInfo> 包含一个 <SecurityTokenReference> 元素,该元素包含对对称密钥的引用,其形式如下:
    • WS-Security 标头中先前的 <DerivedKeyToken> 的引用。
    • 对隐含的 <DerivedKeyToken>的引用。例如:
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
   <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd" 
                 s01:Nonce="mMDk0zn8V7WTsFaIjUJ7zg==" 
                 xmlns:s01="http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512">
      <Reference URI="#Id-93F97220-568E-47FC-B3E1-A2CF3F70B29B"></Reference>
   </SecurityTokenReference>
</KeyInfo>

在这种情况下,<Reference> 中的 URI 属性指向用于生成 <DerivedKeyToken><EncryptedKey> 元素,而 Nonce 属性指示所使用的 nonce 值。

在这两种情况下,这个派生密钥都用于加密此 <EncryptedData> 元素中携带的数据。

如果加密使用顶级 <ReferenceList> 元素,则会包含 <KeyInfo> 元素;请参阅 <ReferenceList>

消息中的位置

在 <Security> 中,应在关联的 <EncryptedKey> 之后包含一个 <EncryptedData> 元素。

<EncryptedData> 元素也可以是 SOAP 主体(<Body> 元素)的子元素。

0
0 72
文章 姚 鑫 · 十月 20, 2024 2m read

第五十一章 安全元素的详细信息 - <EncryptedKey> 详情

详情

该元素的各部分如下:

  • <EncryptionMethod> 表示用于加密对称密钥的算法。

IRIS 中,可以指定密钥传输算法(由 <EncryptionMethod>Algorithm 属性显示)。请参阅指定密钥传输算法。

  • <KeyInfo> 标识用于加密此对称密钥的密钥。在 IRIS 中,<KeyInfo> 包含 <SecurityTokenReference>,其具有以下形式之一:
    • WS-Security 标头中较早位置的 <BinarySecurityToken> 的引用,如前面的示例所示。
    • 用于唯一标识证书的信息,该证书可能是邮件收件人所拥有的。例如,<SecurityTokenReference> 可以包含证书的 SHA1 指纹,如下所示:
<SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <KeyIdentifier EncodingType="[parts omitted]#Base64Binary" 
                  ValueType="[parts omitted]#ThumbprintSHA1">
      maedm8CNoh4zH8SMoF+3xV1MYtc=
   </KeyIdentifier>
</SecurityTokenReference>

在这两种情况下,相应的公钥都用于加密此 <EncryptedKey> 元素中携带的对称密钥。

如果加密使用顶级 <ReferenceList> 元素,则省略此元素;请参阅 <ReferenceList>

  • <CipherData>携带加密后的对称密钥,作<CipherValue>元素中的值。本例中的值 WtE[parts divided]bSyvg== 即为加密后的对称密钥。
  • <ReferenceList> 表示此消息中使用此 <EncryptedKey> 元素中携带的对称密钥加密的部分或多个部分。具体而言,<DataReference> 的 URI 属性指向消息中其他地方的 <EncryptedData>元素的 Id 属性。

根据使用的技术,可能不包含此元素。可以通过顶级 <ReferenceList> 元素链接 <EncryptedData> 和相应的 <EncryptedKey> ;请参阅 <ReferenceList>

消息中的位置

<EncryptedKey> 元素应包含在 <Security> 中,位于其使用的任何 <BinarySecurityToken> 之后,以及引用它的所有 <EncryptedData> 和 <DerivedKeyToken> 元素之前。

0
0 75
文章 姚 鑫 · 十月 17, 2024 2m read

第五十章 安全元素的详细信息

本主题讨论 SOAP 消息中较常见的安全元素,特别是 IRIS Web 服务和客户端可以发送的变体。此信息旨在帮助那些不经常使用 SOAP 的人重温记忆。此处的详细信息也可能有助于故障排除。

<BinarySecurityToken>

<BinarySecurityToken> 的目的是携带消息中其他元素使用的安全凭证,供消息接收者使用。安全凭证以序列化、编码的形式携带。以下显示了部分示例:

<BinarySecurityToken wsu:Id="SecurityToken-4EC1997A-AD6B-48E3-9E91-8D50C8EA3B53" 
                     EncodingType="[parts omitted]#Base64Binary" 
                     ValueType="[parts omitted]#X509v3">
             MIICnDCCAYQ[parts omitted]ngHKNhh
</BinarySecurityToken>

详细

该元素的各部分如下:

  • Id 是此令牌的唯一标识符,包含该标识符以便此消息中的其他元素可以引用此令牌。如有必要, IRIS 会自动生成此标识符。
  • EncodingType 表示用于生成 <BinarySecurityToken> 中的值的编码类型。在 IRIS 中,<BinarySecurityToken> 中使用的唯一编码是 base-64 编码。
  • ValueType 表示令牌中包含的值的类型。在 IRIS 中,唯一支持的值类型是 X.509 证书。
  • <BinarySecurityToken> 元素中包含的值是序列化的编码证书。在此示例中,值 MIICnDCCAYQ[parts divided]ngHKNhh 是安全凭证。

如果此令牌与加密操作相关联,则所包含的证书是消息接收者的证书。如果此令牌与签名相关联,则所包含的证书是消息发送者的证书。

消息中的位置

<BinarySecurityToken> 应该包含在 <Security> 中,在任何引用它的元素之前。

<EncryptedKey>

<EncryptedKey> 的作用是携带供消息中其他元素使用的对称密钥。对称密钥以加密形式携带。以下显示了部分示例:

<EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#">
   <EncryptionMethod Algorithm="[parts omitted]xmlenc#rsa-oaep-mgf1p">
      <DigestMethod xmlns="http://www.w3.org/2000/09/xmldsig#" 
                    Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
      </DigestMethod>
   </EncryptionMethod>
   <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
      <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <Reference URI="#SecurityToken-4EC1997A-AD6B-48E3-9E91-8D50C8EA3B53" 
                    ValueType="[parts omitted]#X509v3">
         </Reference>
      </SecurityTokenReference>
   </KeyInfo>
   <CipherData>
      <CipherValue>WtE[parts omitted]bSyvg==</CipherValue>
   </CipherData>
   <ReferenceList>
      <DataReference URI="#Enc-143BBBAA-B75D-49EB-86AC-B414D818109F"></DataReference>
   </ReferenceList>
</EncryptedKey>

0
0 72
文章 姚 鑫 · 十月 16, 2024 1m read

第四十九章 解决安全问题 - 可能出现的错误

可能出现的错误

本节讨论 IRIS Web 服务和 Web 客户端中可能出现的与安全相关的错误:

  • 如果刚刚生成了 IRIS Web 服务或客户端,则可能尚未配置为识别 WS-Security 标头。在这种情况下,当您尝试执行 Web 方法时,会收到如下一般错误:
<ZSOAP>zInvokeClient+269^%SOAP.WebClient.1

将以下内容添加到Web服务或客户端并重新编译:

Parameter SECURITYIN="REQUIRE";

这种一般错误也可能是由于错误地调用 Web 方法(例如,在 Web 方法没有返回值时引用返回值)造成的。

如果使用 WS-Policy,则此项不适用。

  • 在其他情况下,当您尝试执行 Web 方法时,可能会收到以下安全错误:
ERROR #6454: No supported policy alternative in configuration 
Policy.Client.Demo1SoapConfig:service
  • 入站消息可能未通过验证。如果是这样,SOAP 日志会指出这一点。例如:
08/05/2011 14:40:11 *********************
Input to Web client with SOAP action = http://www.myapp.org/XMLEncr.DivideWS.Divide
<?xml version='1.0' encoding='UTF-8' standalone='no' ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' 
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:s='http://www.w3.org/2001/XMLSchema' 
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" >
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>wsse:FailedAuthentication</faultcode>
      <faultstring>The security token could not be authenticated or authorized</faultstring>
      <detail></detail>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
0
0 100
文章 姚 鑫 · 十月 15, 2024 2m read

第四十八章 解决安全问题

本主题提供信息来帮助识别 IRISSOAP 安全问题的原因。

有关与安全无关的问题的信息,请参阅 IRIS 中的 SOAP 问题故障排除。

故障排除所需的信息

要解决 SOAP 问题,通常需要以下信息:

  • WSDL 及其引用的所有外部文档。
  • (在出现与消息相关的问题的情况下)某种形式的消息记录或跟踪。有以下选择:
OptionUsable with SSL/TLS?Shows HTTP headers?Comments
IRIS SOAP logYesNo对于安全错误,此日志显示的详细信息比 SOAP 故障中包含的更多。
Web Gateway traceYesYes对于使用 MTOM(MIME 附件)的 SOAP 消息问题,查看 HTTP 标头至关重要。
Third-party tracing toolsNoDepends on the tool一些跟踪工具还显示较低级别的详细信息,例如实际发送的数据包,这在进行故障排除时至关重要。

发生安全错误时要检查的项目

IRIS 中的 SOAP 问题故障排除中进行了讨论。

  • 在极少数情况下, SOAP 客户端会使用 `HTTP 身份验证,请注意,可以启用身份验证的日志记录;请参阅提供登录凭据。

正确处理故障也非常有用,这样就可以收到最好的信息。请参阅 SOAP 故障处理。

如果入站消息验证失败或 IRIS 发出不支持的策略替代错误,则检查以下项目很有用:

  • 当检索存储的 IRIS 凭证集时,请确保正确输入其名称。
  • 检索 IRIS 凭证集后,检查对象的类型以确保它是 %SYS.X509Credentials
  • 确保使用的是适当的证书。

如果使用它进行加密,则使用要向其发送消息的实体的证书。加密使用此证书的公钥。

如果使用它进行签名,则使用自己的证书,并使用关联的私钥进行签名。在这种情况下,请确保已加载私钥,并且已正确指定私钥文件的密码。

  • 确保证书由 IRIS 信任的证书颁发机构签名。
  • 如果正在使用 WS-Policy,请务必编辑生成的配置类以指定要使用的 IRIS 凭证集。请参阅编辑生成的策略。
  • 如果 Web 服务需要 <UsernameToken>,请确保 IRIS Web 客户端正在发送此令牌,并且其中包含正确的信息。 IRIS 无法自动指定要发送的 <UsernameToken> ;这必须在运行时完成。请参阅添加时间戳和用户名令牌。

确保 IRIS 支持 Web 服务或客户端所需的至少一种安全策略。请参阅 SOAP 安全标准。

  • 如果身份验证失败,则在 <UsernameToken> 中识别用户,并检查该用户所属的角色。
0
0 64
文章 姚 鑫 · 十月 14, 2024 2m read

第四十七章 创建和添加 SAML 令牌 - <SubjectConfirmation>与 <EncryptedKey>

<SubjectConfirmation><EncryptedKey>

要添加带有 <SubjectConfirmationData>(其中包含 <EncryptedKey> 元素)的 <SubjectConfirmation>,请执行以下操作:

  1. 按照以编程方式检索凭证集中所述,创建 %SYS.X509Credentials 的实例。

或者使用与签署断言时使用的相同凭证集。

  1. 设置 SAML 断言对象的 Subject 属性的 NameID 属性。
  2. 调用 SAML 断言对象的 Subject 属性的 AddEncryptedKeyConfirmation() 方法。
method AddEncryptedKeyConfirmation(credentials As %X509.Credentials) as %Status

对于参数,请使用之前创建的 %SYS.X509Credentials实例。

<SubjectConfirmation>BinarySecret 作为密钥持有者

要添加以 BinarySecret 作为 Holder-of-key<SubjectConfirmation>,请执行以下操作:

  1. 签署 SAML 断言时,请按如下方式创建签名:
set sig=##class(%XML.Security.Signature).Create(assertion,$$$SOAPWSIncludeNone,$$$SOAPWSSAML)

其中断言是 SAML 断言。请注意,在此场景中使用 Create() 方法。$$$SOAPWSSAML 引用选项创建对 SAML 断言的引用。

  1. 创建 BinarySecret。为此,请调用 %SOAP.WST.BinarySecretCreate() 方法:
set binsec=##class(%SOAP.WST.BinarySecret).Create()
  1. 调用 SAML 断言对象的 Subject 属性的 AddBinarySecretConfirmation() 方法:
set status=assertion.Subject.AddBinarySecretConfirmation(binsec)

对于 binsec,请使用在上一步中创建的 BinarySecret

这将添加一个 <SubjectConfirmation>,其中包含一个 <SubjectConfirmationData>,该 <SubjectConfirmationData> 包含一个 <KeyInfo>,该 <KeyInfo> 包含 <BinarySecret>。

添加 <Conditions> 元素

要将 <Conditions> 元素添加到 %SAML.Assertion 实例 执行以下操作:

  1. 创建 %SAML.Conditions的实例。
  2. 根据需要指定此实例的属性。
  3. 将断言对象的“条件”属性设置为等于此实例。

添加 <Advice>元素

要将 <Advice> 元素添加到 %SAML.Assertion实例,请执行以下操作:

  1. 创建下列一个或多个类的实例:
  • %SAML.AssertionIDRef

  • %SAML.AssertionURIRef

  • %SAML.EncryptedAssertion

  1. 根据需要指定这些实例的属性。
  2. 创建一个包含这些建议实例的列表。
  3. 将断言对象的 Advice 属性设置为等于此列表。
0
0 72
文章 姚 鑫 · 十月 13, 2024 2m read

第四十六章 创建和添加 SAML 令牌 - <SubjectConfirmation> 使用方法 Holder-of-key

添加<Subject>元素

要将 <Subject> 元素添加到 %SAML.Assertion 实例,执行以下操作:

  1. 创建 %SAML.Subject 的新实例。
  2. 根据需要设置主题的属性。
  3. 将断言对象的 Subject 属性设置为等于此实例。

添加 <SubjectConfirmation> 元素

要将 <SubjectConfirmation> 元素添加到的 %SAML.Assertion 实例,请使用以下某个小节中的步骤。

<SubjectConfirmation>使用方法 Holder-of-key

要使用 Holder-of-key 方法添加 <SubjectConfirmation>,请执行以下操作:

  1. 按照以编程方式检索凭证集中所述,创建 %SYS.X509Credentials 的实例。

或者使用与签署断言时使用的相同凭证集。

  1. 可以选择创建并添加包含与给定凭据集关联的证书的二进制安全令牌。

要创建令牌,调用 %SOAP.Security.BinarySecurityTokenCreateX509Token() 类方法。例如:

 set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)

其中 credset 是在上一步中创建的凭证集。

要将此令牌添加到 WS-Security 标头元素,请调用 Web 客户端或 Web 服务的 SecurityOut 属性的 AddSecurityElement() 方法。对于方法参数,请使用刚刚创建的令牌。

  1. 调用 SAML 断言对象的 Subject 属性的 AddX509Confirmation() 方法。
method AddX509Confirmation(credentials As %SYS.X509Credentials, 
                           referenceOption As %Integer) as %Status

对于凭证,请使用二进制安全令牌或凭证集。在前一种情况下,请勿指定referenceOption。在后一种情况下,请指定 X.509 凭证的引用选项中所述的值。

<SubjectConfirmation>元素基于 X.509 KeyInfo 元素。

<SubjectConfirmation> 使用方法 Sender-vouches

要使用 Sender-vouches 方法添加 <SubjectConfirmation> ,请执行以下操作:

  1. 设置 SAML 断言对象的 Subject 属性的 NameID 属性。
  2. 调用 SAML 断言对象的 Subject 属性的 AddConfirmation() 方法。
method AddConfirmation(method As %String) as %Status

对于方法,指定 $$$SAMLSenderVouches$$$SAMLHolderOfKey$$$SAMLBearer

在这种情况下,请务必签署 SAML 断言以保护它。

0
0 72
文章 姚 鑫 · 十月 11, 2024 2m read

第四十五章 创建和添加 SAML 令牌 - 变体:不使用 <BinarySecurityToken>

变体:不使用 <BinarySecurityToken>

<BinarySecurityToken> 包含序列化、base-64 编码格式的证书。可以忽略此令牌,而改用标识证书的信息;接收方使用此信息从相应位置检索证书。为此,请使用上述步骤,并进行以下更改:

  • 跳过步骤 23。也就是说,不要创建和添加 <BinarySecurityToken>.。
  • 在步骤 4 中,使用凭证集(而不是二进制安全令牌)作为 CreateX509() 的第一个参数。例如:
 set assertion=##class(%SAML.Assertion).CreateX509(credset,referenceOption)

对于 referenceOption,可选择指定一个值,如 X.509 凭证的参考选项中所述。可以使用除 $$$SOAPWSReferenceDirect 之外的任意值。

如果指定凭证集作为第一个参数(正如我们在这个变体中所做的那样),则默认引用选项是证书的指纹。

变体:创建未签名的 SAML 断言

要创建未签名的 SAML 断言,请使用上述步骤,并进行以下更改:

  • 跳过步骤 123。也就是说,不要创建和添加 <BinarySecurityToken>.。
  • 对于步骤 4,请使用 Create() 方法而不是 CreateX509()。此方法不带参数。例如:
 set assertion=##class(%SAML.Assertion).Create()

此方法返回 %SAML.Assertion的一个实例。 IRIS 会自动设置此实例的 SAMLIDVersion 属性。Signature 属性为空。

添加 SAML 语句

要将 SAML 语句添加到 %SAML.Assertion 实例,请执行以下操作:

  1. 创建适当语句类的一个或多个实例:
  • %SAML.AttributeStatement

  • %SAML.AuthnStatement

  • %SAML.AuthzDecisionStatement

  1. 根据需要指定这些实例的属性。

对于 %SAML.AttributeStatementAttribute 属性是 %SAML.Attribute%SAML.EncryptedAttribute 的实例。

%SAML.Attribute 在其 AttributeValue 属性中带有属性值,该属性值是的 %SAML.AttributeValue实例的列表。

要在实例中向 %SAML.Attribute添加属性值:

a. 创建 %SAML.AttributeValue 的实例。

b. 使用 %SAML.AttributeValue的方法在中将属性指定为 XML、字符串或单个子元素。

c. 创建一个包含这些属性值实例的列表。

d. 将属性对象的 AttributeValue 属性设置为等于此列表。

或者直接指定 AttributeValueOverride 属性。对于值,使用值所需的精确字符串(XML 混合内容字符串)。

  1. 创建一个包含这些语句实例的列表。
  2. 将断言对象的 Statement 属性设置为等于此列表。
0
0 68
文章 姚 鑫 · 十月 10, 2024 3m read

第四十四章 创建和添加 SAML 令牌

本主题描述如何将SAML 令牌添加到 WS-Security 标头元素。

另请参阅 %SAML.Assertion 的类参考和相关类。

未实现完整的 SAML 支持。 IRIS 中的 SAML 支持仅指 IRIS 中的 WS-Security 支持中列出的详细信息。

概述

借助 IRIS SOAP 支持,可以将 SAML 令牌添加到 WS-Security 标头元素。

可以选择将此 SAML 令牌用作签名或加密的密钥材料。如果这样做, IRIS 将遵循 WS-Security SAML 令牌配置文件规范。密钥材料来自 SAML 断言的 <SubjectConfirmation> 元素(带有 Holder-of-key (HOK) 方法)和 <SubjectConfirmationData> 或 <KeyInfoConfirmationData>(带有 <KeyInfo> 子元素)。

或者,可以使用 Sender-vouches (SV) 方法添加 <SubjectConfirmation>;在这种情况下,主题不包含密钥。为了保护这种情况下断言,建议您添加从消息签名到 SAML 令牌的安全令牌引用。

基本步骤

要创建 SAML 令牌并将其添加到出站 SOAP 消息,可以使用此处的基本过程或小节中描述的变体。

  1. 可选择包含 %soap.inc 包含文件,它定义了可能需要使用的宏。
  2. 创建 %SYS.X509Credentials 的实例,如以编程方式检索凭据集中所述。

IRIS 凭证集必须包含自己的证书。例如:

 Set x509alias = "servercred" 
 Set pwd = "mypassword" 
 Set credset = ##class(%SYS.X509Credentials).GetByAlias(x509alias,pwd)
  1. 创建包含与给定凭证集关联的证书的二进制安全令牌。为此,调用 %SOAP.Security.BinarySecurityTokenCreateX509Token() 类方法。例如:
 set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)

其中 credset 是在上一步中创建的 IRIS 凭证集。

  1. 将此令牌添加到 WS-Security 标头元素。为此,请调用 Web客户端或 Web 服务的 SecurityOut 属性的 AddSecurityElement() 方法。对于方法参数,请使用刚刚创建的令牌。例如:
 do ..SecurityOut.AddSecurityElement(bst)
  1. 根据二进制安全令牌创建签名的 SAML 断言。为此,中调用 %SAML.AssertionCreateX509() 类方法。例如:
 set assertion=##class(%SAML.Assertion).CreateX509(bst)

此方法返回 %SAML.Assertion的实例。 IRIS 会自动设置此实例的 SignatureSAMLIDVersion 属性。

该实例代表 <Assertion> 元素。

  1. 指定 %SAML.Assertion 实例的以下基本属性:
  2. 添加 SAML 语句,如添加 SAML 语句中所述。
  3. SAML 断言添加 <Subject> 元素,如添加 <Subject> 元素中所述。
  4. 可选择向 <Subject>添加<SubjectConfirmation> 元素,如添加 <SubjectConfirmation> 元素中所述。

可以使用“钥匙持有人”方法或“发送方凭证”方法确认主题。

  1. 指定 SAML &<Conditions>元素,如添加 <Conditions> 元素中所述。
  2. 可选择添加 <Advice> <Advice>元素,如添加 <Advice> 元素中所述。
  3. 调用 Web 客户端或 Web 服务的 SecurityOut 属性的 AddSecurityElement() 方法。对于方法参数,请使用您创建的 SAML 令牌。
  4. (可选)通过将 SOAP 消息签名中的引用添加到 SAML 断言来签署 SAML 断言。

如果签名是对象中的 %XML.Security.Signature,那么将按如下方式签署 SAML 断言:

  Set str=##class(%SOAP.Security.SecurityTokenReference).GetSAMLKeyIdentifier(assertion) 
  Set ref=##class(%XML.Security.Reference).CreateSTR(str.GetId()) 
  Do signature.AddReference(ref)

特别是当使用 Sender Vouches 方法添加 <SubjectConfirmation> 时,建议执行此步骤。

  1. 发送 SOAP 消息。请参阅添加安全标头元素中的一般注释。
0
0 72
文章 姚 鑫 · 十月 9, 2024 3m read

第四十三章 使用 WS-ReliableMessaging - 对 WS-ReliableMessaging 标头进行签名

WS-ReliableMessaging 标头进行签名

可以通过以下任一方式签署 WS-ReliableMessaging 标头。

使用 SecurityContextToken 对标头进行签名

如果还使用 WS-SecureConversation,则 Web 客户端的 SecurityContextToken 属性包含一个对称密钥,可以使用该密钥对 WS-ReliableMessaging 标头元素进行签名。为此,请在调用 %SOAP.RM.CreateSequence实例的 AddSTR() 方法,并将 SecurityContextToken 属性作为参数传递:

 do createsequence.AddSTR(client.SecurityContextToken)

在调用 %StartRMSession() 之前执行此操作。

签署消息时签署标头

还可以使用与签署消息其余部分相同的方式签署 WS-ReliableMessaging 标头。为此,在调用 %XML.SignatureCreate()CreateX509() 方法时,将值 $$$SOAPWSIncludeRMHeaders 添加到 signatureOptions 参数。$$$SOAPWSIncludeRMHeaders 宏包含在 %soap.inc 文件中。

修改 Web 服务以支持 WS-ReliableMessaging

要修改 IRIS Web 服务以支持 WS-ReliableMessaging,请修改 Web 方法以便它们执行以下操作:

  • 验证入站请求消息是否包含 WS-ReliableMessaging 标头。
  • 验证 WS-ReliableMessaging 标头是否已签名。

请注意 IRIS 会自动检查任何签名是否有效。请参阅验证和解密入站消息。

  • 可选择指定 Web 服务类的参数来微调 Web 服务的行为,如下一节所述。

控制 Web 服务如何处理可靠消息

可以指定 Web 服务类的以下参数来微调 Web 服务的行为:

RMINORDER

对应于 WS-ReliableMessagingInOrder 策略断言。将其指定为 0(false)1 (true)。有关详细信息,请参阅 Web Services Reliable Messaging Policy 1.1 规范。

默认情况下,当未指定此参数时, IRIS Web 服务不会发出有关消息顺序的 SOAP 错误。

RMDELIVERYASSURANCE

对应于 WS-ReliableMessagingDeliveryAssurance 策略断言。将其指定为“ExactlyOnce”、“AtLeastOnce”或“AtMostOnce”。有关详细信息,请参阅 Web Services Reliable Messaging Policy 1.1 规范。

默认情况下,当未指定此参数时,IRIS Web 服务不会发出有关根据此策略断言进行传送的任何失败的 SOAP 故障。

RMINACTIVITYTIMEOUT

指定 Web 服务接收的序列的不活动超时时间(以秒为单位)。默认值为 10 分钟。

此外,还可以实现 Web 服务的 %OnCreateRMSession() 回调方法。此方法在 WS-ReliableMessaging 会话开始时调用,然后返回 %SOAP.RM.CreateSequenceResponse。此时,响应参数已完全创建,但尚未返回。此回调使有机会将任何所需的 Security 标头元素添加到 Web 服务的 SecurityOut 属性。如果使用 WS-Policy,则 WS-Policy 支持会自动执行此操作。有关方法签名,请参阅 %SOAP.WebService的类参考。

0
0 59
文章 姚 鑫 · 十月 8, 2024 2m read

第四十二章 使用 WS-ReliableMessaging

IRIS 支持 WS-ReliableMessaging 规范的部分内容,如简介中所述。此规范提供了一种按顺序可靠地传递一系列消息的机制。本页介绍如何手动使用可靠消息传递。

Web 客户端发送一系列消息

要将一系列消息从 IRIS Web 客户端可靠地发送到支持 WS-ReliableMessagingWeb 服务,请执行以下操作:

  1. 根据需要指定 Web 客户端的安全标头元素。

如果正在使用 WS-SecureConversation,请启动安全对话。

  1. 调用 %SOAP.RM.CreateSequenceCreate() 类方法。这将返回该类的一个实例。

此方法具有以下签名:

classmethod Create(addressingNamespace As %String, 
                   oneWay As %Boolean = 0, 
                   retryInterval As %Float = 1.0, 
                   maxRetryCount As %Integer = 8, 
                   expires As %xsd.duration, 
                   SSLSecurity As %Boolean = 0) as %SOAP.RM.CreateSequence
  • addressingNamespace 是用于 WS-Addressing 支持的命名空间。默认值为“http://www.w3.org/2005/08/addressing”
  • 如果仅创建请求序列,则 oneWay 为真。
  • retryInterval 是重试之前等待的间隔(以秒为单位)。
  • maxRetryCount 是未发生任何活动时的最大重试次数。
  • expiresXML 格式的持续时间,用于指定要发送的序列的请求持续时间。
  • SSLSecurity 指定 Web 客户端是否使用 SSL 连接到 Web 服务。
  1. 调用 Web 客户端的 %StartRMSession() 方法,并的 %SOAP.RM.CreateSequence例作为参数传递。

请注意,使用 %SOAP.RM.CreateSequence 实例一次。也就是说,不能稍后使用它来创建另一个会话。

  1. 根据需要调用 Web 方法。

每次使用相同的 Web 客户端实例。

  1. 发送消息完成后,调用 Web 客户端的 %CloseRMSession() 方法。

重要提示:还要确保按照下一节中的说明签署 WS-ReliableMessaging 标头。

0
0 67
文章 姚 鑫 · 十月 7, 2024 2m read

第四十一章 创建安全对话 - 使用 <SecurityContextToken>

Web 服务使用 <SecurityContextToken>, 做出响应后,客户端实例和服务实例可以访问相同的对称密钥。有关此密钥的信息包含在两个实例的 SecurityContextToken 属性中。建议的程序如下:

  1. 在客户端中,将 SecurityOut 属性设置为 null,以删除请求消息中使用的安全标头。

Web 服务中不需要这样做,因为 Web 服务会在每次调用后自动清除安全标头。

  1. (可选)将 <SecurityContextToken> 添加到 WS-Security 标头元素。为此,请调用 Web 客户端或 Web 服务的 SecurityOut 属性的 AddSecurityElement() 方法。例如:
 set SCT=..SecurityContextToken
 do ..SecurityOut.AddSecurityElement(SCT)

如果在下一步创建派生密钥令牌时使用 $$$SOAPWSReferenceSCT 引用选项,则此步骤是必需的。否则,此步骤不是必需的。

  1. 根据 <SecurityContextToken>创建一个新的 <DerivedKeyToken> 。为此,调用 %SOAP.WSSC.DerivedKeyTokenCreate() 方法,如下所示:
 set dkenc=##class(%SOAP.WSSC.DerivedKeyToken).Create(SCT,refOpt)

在这种情况下,必须指定 Create() 的第一个参数,并且 refOpt 必须是以下参考值之一:

  • $$$SOAPWSReferenceSCT(本地引用)— 引用的 URI 属性以 # 开头,指向 <SecurityContextToken>元素的 wsu:Id 值,该值必须包含在消息中。
  • $$$SOAPWSReferenceSCTIdentifier(远程引用)——引用的 URI 属性包含 <SecurityContextToken> 元素的 <Identifier> 值,该值不必包含在消息中。
 set dkenc=##class(%SOAP.WSSC.DerivedKeyToken).Create(SCT,$$$SOAPWSReferenceSCT)
  1. 使用新的 <DerivedKeyToken> 来指定安全标头。请参阅使用派生密钥令牌进行加密和签名。
  2. 发送 SOAP 消息。请参阅添加安全标头元素中的一般注释。
  //initiate conversation -- not shown here
  //clear SecurityOut so that we can respecify the security header elements for
  //the secure conversation
  set client.SecurityOut=""

  //get SecurityContextToken
  set SCT=client.SecurityContextToken
  do client.SecurityOut.AddSecurityElement(SCT) 

  // get derived keys
  set dksig=##class(%SOAP.WSSC.DerivedKeyToken).Create(SCT,$$$SOAPWSReferenceSCT)
  do client.SecurityOut.AddSecurityElement(dksig)

  // create and add signature
  set sig=##class(%XML.Security.Signature).Create(dksig,,$$$SOAPWSReferenceDerivedKey)
  do client.SecurityOut.AddSecurityElement(sig) 

  
  //invoke web methods

结束安全对话

一旦 <SecurityContextToken> 过期,安全对话就会结束,但 Web 客户端也可以通过取消未过期的 <SecurityContextToken>来结束它。

要结束安全对话,请调用 Web 客户端的 CancelSecureConversation() 方法。例如:

 set status=client.CancelSecureConversation()

该方法返回一个状态值。

请注意,此方法将客户端的 SecurityOut 属性设置为空字符串。

0
0 83
文章 姚 鑫 · 十月 7, 2024 3m read

第四十章 创建安全对话 - 启用 IRIS Web 服务以支持 WS-SecureConversation

启用 IRIS Web 服务以支持 WS-SecureConversation

Web 客户端向 Web 服务发送请求安全对话的消息时,安全对话就开始了。作为响应,Web 服务发送双方都可以使用的 <SecurityContextToken>

要使 IRIS Web 服务能够使用此令牌进行响应,请重写 Web 服务的 OnStartSecureConversation() 方法。此方法具有以下签名:

Method OnStartSecureConversation(RST As %SOAP.WST.RequestSecurityToken) As 
                          %SOAP.WST.RequestSecurityTokenResponseCollection

该方法应该执行以下操作:

  1. 加密 SOAP 主体。OnStartSecureConversation() 发送的消息包含必须保护的信息;此信息在 SOAP 主体中携带。

根据需要,可以选择采用其他方式保护消息安全。

  1. (可选)调用 %SOAP.WST.EntropyCreateBinarySecret() 方法。此方法返回表示随机服务器熵的该类的实例。该方法接受一个参数,即熵的大小(以字节为单位)。
 set serverEntropy=##class(%SOAP.WST.Entropy).CreateBinarySecret(32)

该实例表示 <Entropy>元素和其中包含的 <BinarySecret>

  1. OnStartSecureConversation() 收到的实例中调用 %SOAP.WST.RequestSecurityTokenCreateIssueResponse() 方法。CreateIssueResponse() 方法采用以下参数:

a. $THIS,代表当前的 Web 服务实例。

b. keysize,所需密钥的大小(以字节为单位)。仅当同时提供服务器熵和客户端熵时才使用此参数。默认值是较小密钥的大小(给定客户端熵中的密钥和服务器熵中的密钥)。

c. requireClientEntropy,其值为 truefalse,取决于 Web 服务是否要求请求包含客户端熵。如果为 false,则请求不得包含客户端熵。

d. serverEntropy,在步骤2中创建的服务器熵对象(如果适用)。

e. error错误,作为输出参数返回的状态代码。

f. lifetime,一个整数,指定安全对话的生存期(以秒为单位)。

 set responseCollection=RST.CreateIssueResponse($this,,1,serverEntropy,.error)
  1. 检查上一步中的错误输出参数。如果发生错误,代码应设置 Web 服务的 SoapFault 属性并返回一个空字符串。
  2. 如果成功,则中返回由步骤 2 创建 的 %SOAP.WST.RequestSecurityTokenResponseCollection 的实例。

该实例代表<RequestSecurityTokenResponseCollection>元素,其中包含双方可以使用的 <SecurityContextToken>

以下显示一个例子:

Method OnStartSecureConversation(RST As %SOAP.WST.RequestSecurityToken) 
As %SOAP.WST.RequestSecurityTokenResponseCollection
{
 // encrypt the SOAP body sent by this messsage 
 //because it contains part of the shared secret key
 Set x509alias = "clientnopassword" 
 Set cred = ##class(%SYS.X509Credentials).GetByAlias(x509alias)
 set enckey=##class(%XML.Security.EncryptedKey).CreateX509(cred)
 do ..SecurityOut.AddSecurityElement(enckey)

 //Supply the server entropy
 set serverEntropy=##class(%SOAP.WST.Entropy).CreateBinarySecret(32)
 // Get the response collection for computed key
 set responseCollection=RST.CreateIssueResponse($this,,1,serverEntropy,.error)
 
 If error'="" {
    set ..SoapFault=##class(%SOAP.WST.RequestSecurityTokenResponse).MakeFault("InvalidRequest")
    Quit ""
    }
 
 Quit responseCollection
}

注意:OnStartSecureConversation() 方法最初定义为仅当策略指定时才返回 <SecurityContextToken>。请参阅创建和使用策略。

0
0 101
文章 姚 鑫 · 十月 4, 2024 3m read

第三十九章 创建安全对话

IRIS 支持安全对话,遵循 WS-SecureConversation 1.3 规范。本页介绍如何手动创建安全对话。

概述

在安全对话中,Web 客户端向 Web 服务发出初始请求并接收包含 <SecurityContextToken> 的消息。此元素包含双方都可以使用的对称密钥的信息。此信息指的是只有双方知道的共享密钥。然后双方可以在后续交换中使用对称密钥,直到令牌过期或客户端取消令牌。

双方不应该直接使用 <SecurityContextToken> 执行这些任务(不推荐),而应该从中生成一个 <SecurityContextToken>,然后使用它进行加密、签名、解密和签名验证。

共享密钥可以通过以下任一方式指定:

  • 双方共同提供随机熵值。这是典型的情况。
  • 由客户端,如果客户端提供了一个随机的客户端熵值。
  • 由服务提供,如果服务提供了随机的服务熵值。

开始安全对话

Web 客户端启动安全对话。要在 IRIS 中执行此操作,请在 Web 客户端中执行以下操作:

  1. 加密 SOAP 主体。客户端发送的请求包含必须保护的信息;此信息在 SOAP 主体中携带。

根据需要,可以选择采用其他方式保护请求消息。

  1. 在调用 %SOAP.WST.EntropyCreateBinarySecret() 方法。此方法返回表示随机客户端熵的该类的实例。该方法接受一个参数,即熵的大小(以字节为单位)。
 set clientEntropy=##class(%SOAP.WST.Entropy).CreateBinarySecret(32)

该实例表示 <Entropy> 元素和其中包含的 <BinarySecret>

  1. 在调用 %SOAP.WST.RequestSecurityTokenCreateIssueRequest() 类方法。此方法返回此类的一个实例,客户端将使用该实例请求安全对话。该方法具有以下参数:

a. Interval间隔,请求的令牌的生命周期。默认值为 300 秒;使用空字符串则不指定生命周期。

b. clientEntropy,在上一步中创建的客户端熵对象(如果适用)。

c. requireServerEntropy,一个布尔值,指定服务器在创建 <SecurityContextToken>时是否必须使用服务器熵。默认值为 false

 set RST=##class(%SOAP.WST.RequestSecurityToken).CreateIssueRequest(300,clientEntropy,1)
  1. 可以选择实例中指定 %SOAP.WST.RequestSecurityTokenComputedKeySize 属性。
  2. 调用 Web 客户端的 StartSecureConversation() 方法。此方法向 Web 服务发送一条消息,请求双方都可以使用的 <SecurityContextToken>。此方法接受一个参数,即上一步中在中打开的 %SOAP.WST.RequestSecurityToken实例。

此方法返回一个状态代码,代码应该检查该代码。如果响应表示成功,则客户端的 SecurityContextToken 属性包含一个 %SOAP.WSSC.SecurityContextToken 实例,该实例表示从客户端返回的 <SecurityContextToken>。此元素包含有关对称密钥的信息,双方都可以使用该密钥进行加密、签名、解密和签名验证。

  1. 使用 <SecurityContextToken> 根据需要重新指定安全标头。请参阅使用 <SecurityContextToken>
  //encrypt the SOAP body because it contains part of the shared secret key
  Set x509alias = "servernopassword" 
  Set cred = ##class(%SYS.X509Credentials).GetByAlias(x509alias)
  set enckey=##class(%XML.Security.EncryptedKey).CreateX509(cred)
  do client.SecurityOut.AddSecurityElement(enckey)
 
  // if client entropy to be passed
  set entropy=##class(%SOAP.WST.Entropy).CreateBinarySecret(32)
  // request with 300 second lifetime and computed key using both client 
  //and server entropy.
  set RST=##class(%SOAP.WST.RequestSecurityToken).CreateIssueRequest(300,entropy,1)
  set sc=client.StartSecureConversation(RST)  ; sends a SOAP message
0
0 62
文章 姚 鑫 · 十月 3, 2024 3m read

第三十八章 验证和解密入站消息 - 实例身份验证和 WS-Security

实例身份验证和 WS-Security

了解 IRIS 网络服务有两个独立的机制在起作用是很有用的:IRIS 服务器和网络服务代码。

  • 在管理门户中,您可以为 Web 应用程序指定允许的身份验证模式,从而控制对 %Service_WebGateway 服务的访问。(有关详细信息,请参阅时间戳和用户名令牌示例。有关更多背景信息,请参阅 Web 应用程序。)如果您选择密码选项,则 Web 应用程序可以接受 IRIS 用户名/密码对;这称为实例身份验证。
  • 除此之外,Web 服务还可以要求 IRIS 用户名/密码对。

这些机制协同工作如下:

  1. 收到消息后,Web 服务将检查是否存在名为 <Security> 的标头元素,而不会检查该元素的内容。
  2. 如果不存在 <Security>标头元素并且 SECURITYIN 参数等于 REQUIRE,则 Web 服务将发出故障并退出。
  3. 如果<Security> 标头元素包含<UsernameToken> 元素:
  • 如果为 Web 应用程序选择了密码选项,则 Web 服务将读取 <UsernameToken>元素,从中获取用户名和密码,并登录到 Web 应用程序。

Web 服务对 SECURITYIN 参数的任何值(IGNOREALL 除外)都执行此操作。

用户名可在 $USERNAME 特殊变量和 Web 服务的 Username 属性中找到。密码不可用。

  • 如果没有选择密码选项,则不会登录。

注意:如果关联(和编译)配置类中存在安全策略,则 SECURITYIN 参数将被忽略。

检索安全标头元素

在某些情况下,可能希望为 WS-Security 标头元素添加自定义处理。为此,请使用 Web 服务或客户端的 SecurityIn 属性。如果服务或客户端收到 WS-Security 标头元素,则此属性是包含标头元素的 %SOAP.Security.Header 实例。例如:

 Set secheader=myservice.SecurityIn

然后使用该实例的以下方法之一来检索标题元素:

FindByEncryptedKeySHA1()

method FindByEncryptedKeySHA1(encryptedKeySHA1 As %Binary) as %SOAP.Security.Element

从与给定 EncryptedKeySHA1 参数对应的 <EncryptedKey> 元素中返回密钥。如果没有匹配,则返回空字符串。

FindElement()

method FindElement(type As %String, ByRef pos As %String) as %SOAP.Security.Element

返回位置 pos 之后的第一个指定类型的安全元素。如果没有匹配,该方法将返回空字符串(并将 pos 返回为 0)。

对于类型,指定“Timestamp”、“BinarySecurityToken”、“UsernameToken”、“Signature”或“EncryptedKey”

FindLastElement()

method FindLastElement(type As %String, ByRef pos As %String) as %SOAP.Security.Element

返回指定类型的最后一个安全元素。如果没有匹配,该方法将返回空字符串(并将 pos 返回为 0)。

有关类型的信息,请参阅 FindElement() 的条目。

所有这些方法都会中返回 %SOAP.Security.Element 的实例或以下子类之一的实例,具体取决于元素类型:

Element TypeSubclass Used
"Timestamp"%SOAP.Security.Timestamp
"BinarySecurityToken"%SOAP.Security.BinarySecurityToken
"UsernameToken"%SOAP.Security.UsernameToken
"Signature"%XML.Security.Signature

检查签名确认

WS-Security 1.1<SignatureConfirmation>功能使 Web 客户端能够确保收到的 SOAP 消息是响应 Web 客户端发送的原始请求而生成的。客户端请求通常经过签名,但并非必须如此。在此机制中,Web 服务将 <SignatureConfirmation> 元素添加到安全标头元素,Web 客户端可以检查该 <SignatureConfirmation>元素。

对于 Web 客户端,要验证从 Web 服务收到的响应中的 <SignatureConfirmation> 元素,请调用 Web 客户端的 WSCheckSignatureConfirmation() 方法。如果 <SignatureConfirmation> 元素有效,则此方法返回 true,否则返回 false

0
0 70
文章 姚 鑫 · 十月 1, 2024 2m read

第三十七章 验证和解密入站消息

本主题介绍如何验证 IRIS Web 服务或 Web 客户端收到的消息中的安全元素(并自动解密任何加密内容)。

概述

IRIS 网络服务和网络客户端可以验证入站 SOAP 消息的 WS-Security 标头元素,以及自动解密入站消息。

IRIS Web 服务和 Web 客户端还可以处理已签名的 SAML 断言令牌并验证其签名。但是,验证 SAML 断言的详细信息是您的应用程序的责任。

如果使用安全策略,所有上述活动都是自动的。

在所有场景中,IRIS 都使用其根颁发机构证书集合;请参阅设置和其他常见活动。

验证 WS-Security 标头

要验证任何入站 SOAP 消息中包含的 WS-Security 标头元素,请执行以下操作:

  1. Web 服务或 Web 客户端中,设置 SECURITYIN 参数。使用以下值之一:
    • REQUIREWeb 服务或 Web 客户端验证 WS-Security 标头元素,如果不匹配或缺少此元素,则会发出错误。
    • ALLOWWeb 服务或 Web 客户端验证 WS-Security 标头元素。

在这两种情况下,Web 服务或 Web 客户端都会验证 &<Timestamp>, <UsernameToken>, <BinarySecurityToken>, <Signature>, and <EncryptedKey> 标头元素。它还会验证标头中 SAML 断言中的 WS-Security 签名(如果有)。如果合适,还会解密消息。

如果验证失败,则返回错误。

SECURITYIN 参数还有两个可能的值,可用于测试和故障排除:

  • IGNOREWeb 服务或客户端忽略除 <UsernameToken> 之外的 WS-Security 标头元素,如 CSP 身份验证和 WS-Security 中所述。

为了向后兼容,此值是默认值。

  • IGNOREALL — Web 服务或客户端忽略所有 WS-Security 标头元素。

注意:如果关联(和编译)配置类中存在安全策略,则 SECURITYIN 参数将被忽略。

访问 WS-Security 标头中的 SAML 断言

如果 WS-Security 标头元素包含 <Assertion> 元素,则 IRIS Web 服务或 Web 客户端会自动验证该 SAML 断言的签名(如果已签名)。

注意:验证需要可信证书。如果 IRIS 可以验证签名者的证书链(从签名者自己的证书到 IRIS 信任的证书颁发机构 (CA) 的自签名证书,包括中间证书(如果有),则它可以验证签名。

但是, IRIS 不会自动验证断言。代码应该检索断言并进行验证。

要访问 SAML 断言,请找到安全标头元素的 <Assertion> 元素。为此,请使用服务或客户端的 SecurityIn 属性的 FindElement() 方法,如下所示:

 Set assertion=..SecurityIn.FindElement("Assertion") 

这将中返回 %SAML.Assertion 的一个实例。根据需要检查此对象的属性。

0
0 59