[IBM i]

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

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

概述

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

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

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

字段

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 999)。

    请考虑将 SCAIO 用于不支持指针数据类型的编程语言，或者以无法移植到不同环境 (例如， COBOL 编程语言) 的方式实现指针数据类型的编程语言。

无论您选择哪种技术，都只能使用 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
备注信息：
  1. 不推荐 CipherSpec TLS_RSA_WITH_3DES_EDE_CBC_SHA。
  2. 在可能的情况下，如果配置了仅 FIPS CipherSpecs ，那么 MQI 客户机将拒绝指定非 FIPS CipherSpec withRC2393的连接。 IBM MQ 不保证拒绝所有此类连接，您负责确定 IBM MQ 配置是否符合 FIPS 标准。
SCKR (10 位有符号整数)

此字段仅与在 UNIX 和 Windows 系统上运行的 IBM MQ MQI clients 相关。 它指定存储密钥和证书的密钥数据库文件的位置。 密钥数据库文件必须具有格式为 zzz.kdb的文件名，其中 zzz 是用户可选择的。 SCKR 字段包含此文件的路径以及文件名词干 (文件名中的所有字符最多但不包括最终 .kdb)。 将自动添加 .kdb 文件后缀。

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

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

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

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

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

SCSID (10 位数字带符号整数)
这是结构标识; 值必须为:
SCSIDV
TLS 配置选项结构的标识。

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

SCVER (10 位带符号整数)
这是结构版本号; 值必须为:
SCVER1
Version-1 TLS 配置选项结构。
SCVER2
Version-2 TLS 配置选项结构。
以下常量指定当前版本的版本号:
SCVERC
TLS 配置选项结构的当前版本。

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

初始值

表 1. MQSCO 中字段的初始值
字段名称 常量的名称 常量值
SCSID SCSIDV 'SCO¬'
SCVER SCVER5 1
SCKR None 空字符串或空白
SCCH None 空字符串或空白
SCAIC None 0
SCAIO None 0
SCAIP None 空指针或空字节
SCKRC None 空指针或空字节
SCFR None 空指针或空字节
SCEPSUITEB None 空指针或空字节
SCCERTVPOL None 空指针或空字节
SCCERLBL None 空指针或空字节
备注信息：
  1. 符号 ¬ 表示单个空白字符。
  2. 请参阅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 **