S/MF
StackMF Knowledge Base • z/OS
DevOps & Automation 10 min read 2026-09-27

Resolving SSL/TLS Certificate Untrusted and Handshake Errors in Zowe z/OSMF Connections

A
Reviewed by Anshu
Chief Technology Architect & Mainframe Systems SME
Enterprise Modernization Advisory
Google AI Overview & Featured Snippet Quick Answer

Executive Summary: Resolving SSL/TLS Certificate Untrusted and Handshake Errors in Zowe z/OSMF Connections

Zowe CLI and VS Code Zowe Explorer connections fail when z/OSMF presents a self-signed or enterprise internal root certificate. Learn how to export the z/OS CA certificate using RACF RACDCERT, import it into client truststores, and eliminate 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' errors.

1 Problem Statement & Architecture Context: Resolving SSL/TLS Certificate Untrusted and Handshake Errors in Zowe z/OSMF Connections

Developers configuring Zowe CLI encounter blocking connection errors:

text
Error: unable to verify the first certificate
code: UNABLE_TO_VERIFY_LEAF_SIGNATURE
Request failed to: https://zsys1.stackmf.internal:443/zosmf/restjobs/jobs

Developers add rejectUnauthorized: false as an insecure workaround, violating corporate security compliance.

2 Technical Root Cause & Architecture Mechanics

By default, IBM z/OSMF uses a local self-signed certificate authority created during configuration (e.g. zOSMFCA).

Client operating systems (Windows, macOS, Linux) and Node.js do not trust internal mainframe CAs unless the root certificate is imported into the client truststore or specified in the Zowe profile.

3 Implementation Guide & Modernization Strategy

# 1. Export the z/OSMF Certificate Authority from RACF

Have the security administrator issue:

text
RACDCERT CERTAUTH EXPORT(LABEL('zOSMFCA')) -
         DSN('SYS1.ZOSMF.CACERT.DER') FORMAT(CERTDER)

# 2. Download Certificate to Local Machine via Binary Transfer

Transfer the exported DER file to your workstation and convert to PEM if needed:

bash
zowe zos-files download data-set "SYS1.ZOSMF.CACERT.DER" --binary --file ./certs/zosmf-ca.cer
openssl x509 -inform der -in ./certs/zosmf-ca.cer -out ./certs/zosmf-ca.pem

# 3. Configure Zowe Profile to Trust the Mainframe CA

Update your zowe.config.json with the path to the trusted certificate:

json
{
  "profiles": {
    "base": {
      "type": "base",
      "properties": {
        "host": "zsys1.stackmf.internal",
        "port": 443,
        "rejectUnauthorized": true,
        "ca": "./certs/zosmf-ca.pem"
      }
    }
  }
}

Now, all Zowe CLI and VS Code connections establish verified, hardened TLS 1.3 tunnels without certificate warnings!

Technical Specifications Matrix

Attribute Specification
Target Environment IBM z/OS • DevOps & Automation
Key Technologies Zowe, z/OSMF, SSL
Delivery SLA Accelerated Sprint Delivery via StackMF Pods
Technical Reviewer Anshu, Chief Technology Architect • StackMF Architecture Pod

Production Readiness & Verification Checklist

? Frequently Asked Questions

What is the root cause of Resolving SSL/TLS Certificate Untrusted and Handshake Errors in Zowe z/OSMF Connections? ↓
By default, IBM z/OSMF uses a local self-signed certificate authority created during configuration (e.g. zOSMFCA).
How do you resolve Resolving SSL/TLS Certificate Untrusted and Handshake Errors in Zowe z/OSMF Connections in production? ↓
Zowe CLI and VS Code Zowe Explorer connections fail when z/OSMF presents a self-signed or enterprise internal root certificate. Learn how to export the z/OS CA certificate using RACF RACDCERT, import it into client truststores, and eliminate 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' errors.
How can teams prevent Resolving SSL/TLS Certificate Untrusted and Handshake Errors in Zowe z/OSMF Connections in enterprise pipelines? ↓
Never deploy `--rejectUnauthorized false` in production or corporate laptops.

Recommended Technical Runbooks

Authoritative Reference Documentation

Official IBM manuals, Redbooks, and vendor technical advisories:

Related Topics: Zowez/OSMFSSLTLSCertificatesRACFTroubleshooting
Diagnostic Runbook Notice & Nominative Fair Use Disclaimer

This diagnostic runbook is published by StackMF Technologies LLP for educational and architectural reference only. All code snippets, JCL, and procedures are provided "AS IS" without warranty of any kind. Always test changes thoroughly in non-production sysplex environments prior to production rollout.

IBM, z/OS, CICS, Db2, IMS, RACF, and IDz are registered trademarks of International Business Machines Corporation. Broadcom, CA-7, and Endevor are trademarks of Broadcom Inc. All other trademarks belong to their respective owners and are referenced under the Nominative Fair Use Doctrine (US Lanham Act 15 U.S.C. ยง 1125 / Section 30 of the Indian Trade Marks Act, 1999) solely for technology compatibility and diagnostic identification. StackMF Technologies LLP is an independent consulting entity not affiliated with or endorsed by these vendors. View Full Legal & IP Policy →

Enterprise Advisory

Struggling with Critical Mainframe Incidents or Vendor Renewal Pressure?

StackMF deploys certified Senior Mainframe Engineers fluent in both z/OS legacy internals (COBOL, DB2, CICS, VSAM, CA-7, Endevor) and modern cloud stacks (React, Kafka, AWS, Git). Onboard dedicated pods in 48 hours or cut Broadcom licensing by 60%.