IBM i 上的 MQSCO (TLS 配置选项)

MQSCO 结构 (包含 MQCD 结构中的 TLS 字段) 允许作为 IBM® MQ MQI client 运行的应用程序指定配置选项，这些选项用于在通道协议为 TCP/IP 时控制对客户机连接使用 TLS。

概述

用途:structure 是 MQCONNX 调用上的输入参数。

如果客户机通道的通道协议不是 TCP/IP ，那么将忽略 MQSCO 结构。

字符集和编码:MQSCO 中的数据必须包含由 CodedCharSetId 队列管理器属性提供的字符集以及由 ENNAT 提供的本地队列管理器的编码。

字段
初始值
RPG 声明

字段

MQSCO 结构包含以下字段; 这些字段按 字母顺序进行描述:

SCAIC (10 位有符号整数)

这是由 SCAIP 或 SCAIO 字段寻址的认证信息 (MQAIR) 记录数。有关更多信息，请参阅IBM i 上的 MQAIR (认证信息记录)。值必须大于等于零。如果该值无效，那么调用将失败，原因码为 RC2383。

这是一个输入字段。此字段的初始值为 0。

SCAIO (10 位有符号整数)

这是从 MQSCO 结构开始的第一个认证信息记录的偏移量 (以字节为单位)。偏移可以是正数或负数。如果 SCAIC 为零，那么将忽略该字段。

您可以使用 SCAIO 或 SCAIP 来指定 MQAIR 记录，但不能同时指定两者; 请参阅 SCAIP 字段的描述以获取详细信息。

这是一个输入字段。此字段的初始值为 0。

SCAIP (10 位有符号整数)

这是第一个认证信息记录的地址。如果 SCAIC 为零，那么将忽略该字段。

您可以通过以下两种方法之一提供 MQAIR 记录的数组:

通过使用指针字段 SCAIP
在这种情况下，应用程序可以声明与 MQSCO 结构不同的 MQAIR 记录数组，并将 SCAIP 设置为该数组的地址。

请考虑将 SCAIP 用于以可移植到不同环境 (例如 C 编程语言) 的方式支持指针数据类型的编程语言。
通过使用偏移量字段 SCAIO
在这种情况下，应用程序必须声明包含后跟 MQAIR 记录数组的 MQSCO 的复合结构，并将 SCAIO 设置为数组中第一个记录从 MQSCO 结构开始的偏移量。请确保此值正确，且其数值范围需符合MQLONG类型限制（ COBOL 是限制最严格的编程语言，其有效范围为-999 999 999至+999 999 999）。

对于不支持指针数据类型的编程语言，或以无法在不同环境间移植的方式实现指针数据类型的语言（例如 COBOL 编程语言），请考虑使用 SCAIO 替代方案。

无论您选择哪种技术，都只能使用 SCAIP 和 SCAIO 之一; 如果两者都非零，那么调用将失败，原因码为 RC2384 。

这是一个输入字段。此字段的初始值是那些支持指针的编程语言中的空指针，否则是全空字节字符串。

注: 在编程语言不支持指针数据类型的平台上，此字段声明为适当长度的字节字符串。

SCCERLBL (10 位有符号整数)

此字段提供正在使用的证书标签的详细信息。

IBM MQ 将 SCCERLBL 字段的值初始化为空白。请输入必需值，或者接受缺省值。

对于此字段， ibmwebspheremquser_id 是所有产品版本的有效值，而对于小于 5.0 的 MQSCO 版本，它是唯一的有效值。因此，将在运行时解释此字段的值，并在必要时进行更改。如果指定的 MQSCO 版本低于 5.0，或者接受 SCCERLBL 字段的缺省值为空白，那么系统将使用值 ibmwebspheremquser_id。

这是一个输入字段。

SCCERTVPOL (10 位带符号整数)

此字段指定使用的证书验证策略的类型。可以将该字段设置为下列其中一个值:

MQ_CERT_VAL_POLICY_ANY: 应用安全套接字库支持的每个证书验证策略。如果任何策略认为证书链有效，请接受该证书链。
MQ_CERT_VAL_POLICY_RFC5280: 仅应用符合 RFC5280 的证书验证策略。此设置提供比 ANY 设置更严格的验证，但是会拒绝一些较旧的数字证书。

此字段的初始值为 MQ_CERT_VAL_POLICY_ANY

SCCH (10 位带符号整数)

此字段提供连接到客户机系统的加密硬件的配置详细信息。

将字段设置为以下格式的字符串，或者将其保留为空或空:

GSK_PKCS11=the PKCS #11 driver path and file name;the PKCS #11
token label;the PKCS #11 token password;symmetric cipher setting>;

要使用符合 PKCS11 接口 (例如， IBM 4960 或 IBM 4963) 的加密硬件，请指定 PKCS11 驱动程序路径， PKCS11 令牌标签和 PKCS11 令牌密码字符串，每个都以分号终止。

PKCS #11 驱动程序路径是提供 PKCS #11 卡支持的共享库的绝对路径。 PKCS #11 驱动程序文件名是共享库的名称。 PKCS #11 路径和文件名所需的值的示例为:

/usr/lib/pkcs11/PKCS11_API.so

PKCS #11 令牌标签必须完全为小写。如果已使用混合大小写或大写令牌标签配置硬件，请使用此小写标签对其进行重新配置。

如果不需要加密硬件配置，请将该字段设置为空白或空。

如果该值比字段的长度短，那么用空字符终止该值，或用空白填充该字段的长度。如果该值无效，或者在用于配置加密硬件时导致失败，那么调用将失败，原因码为 RC2382。

这是一个输入字段。此字段的长度由 LNSSCH 给出。此字段的初始值为空白字符。

CEPSUITEB (10 位数字的带符号整数)

此字段指定是否使用符合 Suite B 的密码术以及使用的强度级别。该值可以是下列其中一项或多项:

SCEPSUITEB0
不使用符合套件 B 的密码术。
SCEPSUITEB1
使用套件 B 128 位强度安全性。
SCEPSUITEB2
使用套件 B 192 位强度安全性。

注: 将 SCEPSUITEB0 与此字段中的任何其他值配合使用是无效的。

SCFR (10 位有符号整数)

可以使用加密硬件配置 IBM MQ ，以便所使用的加密模块是硬件产品提供的模块; 这些模块可以通过 FIPS 认证到特定级别，具体取决于正在使用的加密硬件产品。

使用此字段来指定如果在 IBM MQ提供的软件中提供了密码术，那么仅使用 FIPS 认证的算法。

安装 IBM MQ 时，还会安装 TLS 密码术的实现，这将提供一些经 FIPS 认证的模块。

值可以是:

MQSSL_FIPS_NO

这是缺省值。设置为该值时:

可以使用特定平台上支持的任何 CipherSpec 。
如果在不使用加密硬件的情况下运行，那么以下 CipherSpecs 在 IBM MQ 平台上使用 FIPS 140-2 认证的密码术运行:
- TLS_RSA_WITH_3DES_EDE_CBC_SHA
- TLS_RSA_WITH_AES_128_CBC_SHA
- TLS_RSA_WITH_AES_256_CBC_SHA

MQSSL_FIPS_YES

设置为该值时，除非您正在使用加密硬件来执行密码术，否则可以确保

此客户机连接所应用的 CipherSpec 中只能使用 FIPS 认证的密码算法。
仅当使用了下列其中一个密码规范时，入站和出站 TLS 通道连接才会成功:
- TLS_RSA_WITH_3DES_EDE_CBC_SHA
- TLS_RSA_WITH_AES_128_CBC_SHA
- TLS_RSA_WITH_AES_256_CBC_SHA

注：

不推荐 CipherSpec TLS_RSA_WITH_3DES_EDE_CBC_SHA。
在可能的情况下，如果配置了仅 FIPS CipherSpecs ，那么 MQI 客户机将拒绝指定非 FIPS CipherSpec withRC2393的连接。 IBM MQ 不保证拒绝所有此类连接，您负责确定 IBM MQ 配置是否符合 FIPS 标准。

SCKEYPWL (10 位带符号整数)

这是 TLS 密钥存储库口令的长度。

密钥存储库口令的最大长度为 128 个字符。如果密钥存储库口令大于允许的最大长度，那么连接将失败并返回 RC2381。

这是一个输入字段。此字段的初始值为 0。

SCKEYPWO (10 位带符号整数)

这是 TLS 密钥存储库口令的偏移量 (以字节计)。偏移可以是正数或负数。

可以使用 SCKEYPWO 或 SCKEYPWP 来指定密钥存储库口令，但不能同时指定两者。有关更多信息，请参阅 SCKEYPWP 字段的描述。

这是一个输入字段。此字段的初始值为 0。

SCKEYPWP (指针)

这是 TLS 密钥存储库口令的地址。

这是一个输入字段。此字段的初始值为空指针。

可以将密钥存储库口令指定为纯文本字符串或已使用 runmqicred 实用程序加密的口令。

使用该字段指定的密钥存储库口令会覆盖使用MQKEYRPWD环境变量或客户端配置文件 SSL 节中的SSLKeyRepositoryPassword属性指定的任何密钥存储库口令。

可以使用 SCKEYPWO 或 SCKEYPWP 来指定密钥存储库口令，但不能同时指定两者。

SCKR (10 位有符号整数)

此字段指定存储密钥和证书的密钥数据库文件的位置。 [MQ 9.3.0 2022 年 6 月] 如果未指定文件后缀，那么将自动添加后缀 .kdb 。

每个密钥数据库文件都可以具有关联的 密码存储文件。这将保存用于允许程序化访问密钥数据库的加密密码。密码隐藏文件必须位于同一目录中，并且具有与密钥数据库相同的文件系统，并且必须以后缀 .sth结尾。

例如，如果密钥数据库文件是 /xxx/yyy/key.kdb，那么密码存储文件必须是 /xxx/yyy/key.sth，其中 xxx 和 yyy 表示目录名称。

[MQ 9.3.0 2022 年 6 月] 还可以使用 SCKEYPWP 或 SCKEYPWO 字段指定密钥数据库密码。

如果该值比字段的长度短，那么用空字符终止该值，或用空白填充该字段的长度。未检查该值; 如果访问密钥存储库时发生错误，那么调用将失败，原因码为 RC2381。

要从 IBM MQ MQI client运行 TLS 连接，请将 SCKR 设置为有效的密钥数据库文件名。

这是一个输入字段。此字段的长度由 LNSSKR 给出。此字段的初始值为空白字符。

SCSID (10 位数字带符号整数)

这是结构标识; 值必须为:

SCSIDV: TLS 配置选项结构的标识。

这始终是一个输入字段。此字段的初始值为 SCSIDV。

SCVER (10 位带符号整数)

这是结构版本号; 值必须为:

SCVER1: Version-1 TLS 配置选项结构。
SCVER2: Version-2 TLS 配置选项结构。
SCVER3: Version-3 TLS 配置选项结构。
SCVER4: Version-4 TLS 配置选项结构。
SCVER5: Version-5 TLS 配置选项结构。
SCVER6: Version-6 TLS 配置选项结构。

以下常量指定当前版本的版本号:

SCVERC: TLS 配置选项结构的当前版本。

这始终是一个输入字段。此字段的初始值为 SCVER1。

初始值

表 1. MQSCO 中的字段
字段名称	常量的名称	常量值
`SCSID`	SCSIDV	`'SCO¬'`
`SCVER`	SCVER1	`1`
`SCKR`	None	空字符串或空白
`SCCH`	None	空字符串或空白
`SCAIC`	None	`0`
`SCAIO`	None	`0`
`SCAIP`	None	空指针或空字节
`SCKRC`	None	空指针或空字节
`SCFR`	None	空指针或空字节
`SCEPSUITEB`	None	空指针或空字节
`SCCERTVPOL`	None	空指针或空字节
`SCCERLBL`	None	空指针或空字节
`SCKEYPWP`	None	空指针或空字节
`SCKEYPWO`	None	`0`
`SCKEYPWL`	None	`0`
注：符号 `¬` 表示单个空白字符。请参阅 RPG 声明以获取 `SCEPSUITEB` 选项。

RPG 声明

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D* MQSCO Structure
     D*
     D* Structure identifier
     D  SCSID                  1      4    INZ('SCO ')
     D* Structure version number
     D  SCVER                  5      8I 0 INZ(1)
     D* Location of TLS key repository
     D  SCKR                   9    264    INZ
     D* Cryptographic hardware configuration string
     D  SCCH                 265    520    INZ
     D* Number of MQAIR records present
     D  SCAIC                521    524I 0 INZ(0)
     D* Offset of first MQAIR record from start of MQSCO structure
     D  SCAIO                525    528I 0 INZ(0)
     D* Address of first MQAIR record
     D SCAIP                 529    544*   INZ(*NULL)
     D* Ver:1 **
     D* Number of unencrypted bytes sent/received before secret key is
     D* reset
     D SCKRC                 545    548I 0 INZ(0)
     D* Using FIPS-certified algorithms
     D SCFR                  549    552I 0 INZ(0)
     D* Ver:2 **
     * Use only Suite B cryptographic algorithms
     D SCEPSUITEB0
     D SCEPSUITEB1           553    556I 0 INZ(1)
     D SCEPSUITEB2           557    560I 0 INZ(0)
     D SCEPSUITEB3           561    564I 0 INZ(0)
     D SCEPSUITEB4           565    568I 0 INZ(0)
     D SCEPSUITEB                    10I 0 DIM(4) OVERLAY(SCEPSUITEB0)
     D* Ver:3 **
     D* Certificate validation policy
     D SCCERTVPOL            569    572I 0 INZ(0)
     D* Ver:4 **