.NET连接外部托管IBM MQ报Reason Code 2009错误排查咨询

错误说明 #

• MQRC 2009 (MQRC_CONNECTION_BROKEN)：连接在SSL握手或初始鉴权阶段被对端主动断开，90%以上场景为SSL配置不匹配导致
• MQRC 2277 (MQRC_CLIENT_CONN_ERROR)：客户端连接配置无效，多为CCDT(.tab)文件加载失败、参数冲突导致

2009错误排查步骤（直连配置场景） #

你当前使用TRANSPORT_MQSERIES_MANAGED托管传输模式，该模式对证书库、加密套件的规则和非托管模式存在差异，按以下优先级核对：

1. 证书库配置校验
   SSL_CERT_STORE_PROPERTY的取值必须是证书文件的全路径，且不带.kdb后缀。同时要保证程序运行身份对同目录下的.kdb、.rdb、.sth、.crl四个文件均有读取权限，不要将证书放在包含中文、空格、特殊字符的路径下，9.3版本托管客户端对特殊路径解析存在已知问题。
   例：证书存放在C:\mq-config\cert\client.kdb时，配置值应为C:\mq-config\cert\client
2. TLS版本与加密套件校验
   9.3版本IBMMQDotnetClient默认禁用TLS1.0、TLS1.1，若服务端未开启TLS1.2/1.3支持，握手会直接失败，需要在初始化连接前显式指定支持的协议版本：

   // 放在MQQueueManager实例化代码前执行
   System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12 | System.Net.SecurityProtocolType.Tls13;
   

   注意：托管模式下SSL_CIPHER_SUITE_PROPERTY需要填写.NET框架可识别的密码套件名称，不能直接填写IBM MQ自定义的CipherSpec名称，名称不匹配是2009错误的最高发原因，需要向MQ服务方确认对应CipherSpec的.NET兼容套件值，不要自行猜测。
3. 客户端证书标签校验
   KDB证书库中的客户端个人证书标签必须严格符合ibmwebspheremq<客户端运行账号的小写用户名>格式，托管客户端默认按该规则查找客户端证书，标签不匹配会直接导致握手失败。可以使用MQ自带的runmqakm工具查看库内证书列表：

   runmqakm -cert -list -db <kdb文件全路径> -stashed
   

2277错误排查步骤（CCDT连接场景） #

使用.tabCCDT文件+无参构造连接时报2277，通常由以下原因导致：

• 环境变量加载时机错误：MQ_CHANNEL_LIB、MQ_CHANNEL_TAB两个环境变量必须在进程启动前配置完成，进程运行中动态赋值不会被托管客户端识别，客户端仅在初始化阶段读取一次这两个变量
• CCDT版本不兼容：如果提供.tab文件的MQ服务端版本高于9.3，生成的CCDT文件无法被9.3版本客户端识别，需要让服务方导出兼容9.3客户端版本的CCDT文件
• 参数冲突：使用CCDT连接时，不要额外在连接属性中配置HOST、PORT、CHANNEL参数，否则会覆盖CCDT配置触发参数校验失败

定位根因的快捷方法 #

开启客户端跟踪日志可以直接看到SSL握手阶段的具体报错，在连接代码前添加以下配置即可：

// 提前创建日志目录并给运行账号分配写入权限
MQEnvironment.TraceLevel = 1;
MQEnvironment.TracePath = @"C:\mq-trace\";

复现报错后，在跟踪日志中搜索SSL Handshake关键字，即可直接定位是证书信任问题、套件不匹配还是协议版本不支持的具体原因。

内容的提问来源于stack exchange，提问作者Cuken