Python

 View Only

Hosting a Secure Flask API on z/OS Using RACF Keyrings and py-zcrypto

By Seo Hyun Jeong posted 09/16/26 02:48 PM

  

When you deploy a Python web service on z/OS, the certificates you need often already exist inside RACF. System administrators define keyrings - named containers that group related certificates together - and associate them with specific user IDs. The challenge for a Python developer is bridging that z/OS-native credential store with the standard Python TLS machinery. 

  

This blog walks through a working demo that does exactly that. Starting from a RACF keyring that already contains a self-signed certificate, the demo uses the py-zcrypto package to extract the certificate and private key, converts them into PEM format, and then passes them directly to Flask's built-in TLS support. The result is a running HTTPS API endpoint on z/OS whose certificate came entirely from RACF. 

The complete flow looks like this:   

   RACF Keyring -> py-zcrypto -> cert.pem / key.pem -> Flask ssl_context -> HTTPS 

The Python Package: py-zcrypto 

py-zcrypto is an IBM-authored Python package that wraps z/OS's Certificate Management Services (CMS) API. It exposes a small, Python class that lets you open a keyring, export certificates and private keys to files, and close the connection cleanly. 

 

Installing the package also installs a companion module called helper, which bundles together the format-conversion steps (DER to PEM, PKCS#12 to PEM) that are almost always needed immediately after an export.

Prerequisites and Setup 

z/OS environment 

  • IBM Open Enterprise SDK for Python 
  • (Optional) IBM Open XL C/C++ compiler.  
    • py-zcrypto Can be obtained from the Python AI Toolkit for IBM z/OS, which does not require a C/C++ compiler. If building the package from source, a C/C++ compiler is required 
  • A RACF keyring that already exists and already contains a certificate with a private key 
  • The running user must have READ access to that keyring in RACF 

Installing the Prerequisites 

The following script sets up Python 3.14 and our C/C++ compiler, then installs the required packages. Once this is complete, we are ready to extract our certificate from RACF, convert it to a format that Python can use, and then run our Flask server using it. 

  # Environment variables for Python 

  export PATH=/u/ibmuser/python/usr/lpp/IBM/python/v3r14/pyz/bin:$PATH 

  export LIBPATH=/u/ibmuser/python/usr/lpp/IBM/python/v3r14/pyz/lib:$LIBPATH 

  export _BPXK_AUTOCVT='ON' 

  export _CEE_RUNOPTS='FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)' 

 

  # Set up our C/C++ compiler  

  export CC=/bin/xlc 

  export CXX=/bin/xlc++ 

  export LDSHARED=/bin/xlc 

 

  # Create our virtual environment 

  rm -rf venv 

  python3 -m venv venv --system-site-packages 

  source ./venv/bin/activate 

 

  # Install required package 

  pip3 install flask py-zcrypto 

 

Extracting & Converting the Certificates 

The py-zcrypto package contains both functionality to extract and convert the certificate that we want to get access to. In our example, within RACF we have a ring named RINGNAME, and it contains a self-signed certificate called LABELNAME.  

import sys 
from helper import export_keypair 
from py_zcrypto import zcrypto 

# Load up our testing ring named RINGNAME 
py_zcrypto_obj = zcrypto() 
rc = py_zcrypto_obj.open_key_ring('RINGNAME') 
if rc != 0: 
    print('Error: {}'.format(py_zcrypto_obj.get_error_string(rc))) 
    sys.exit(1) 

# Using py-zcryptos helper, extract & convert the certificate 
export_keypair(py_zcrypto_obj, 'cert', 'RINGNAME', ‘<your_password>’, 'LABELNAME', 'key.pem') 

# Cleanup 
py_zcrypto_obj.close_database() 

Once this script has been run, you will have both a cert.pem (public key) and key.pem (private key) in the local directory that can be used. You can use the following to run it: 

  export PATH=/u/ibmuser/python/usr/lpp/IBM/python/v3r14/pyz/bin:$PATH 

  export LIBPATH=/u/ibmuser/python/usr/lpp/IBM/python/v3r14/pyz/lib:$LIBPATH 

  export _BPXK_AUTOCVT='ON' 

  export _CEE_RUNOPTS='FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)' 

 

  source ./venv/bin/activate 

  python3 extract.py 

 

Running Flask using this certificate 

Now that we have the keys in a format that Flask can use, we can run our Flask server. The following code creates a simple https server using our certificate.  

from flask import Flask 

app = Flask(__name__) 

@app.route("/") 
def root(): 
       return {'result': 'success'} 

if __name__ == '__main__': 
        app.run(host='0.0.0.0', ssl_context=('cert.pem', 'key.pem'), port=5000) 

From another machine, you can test this endpoint using passing the cert.pem that is used. For example: 

from requests import get 
r = get('https://your_machine_host:5000’, verify='cert.pem') 
print("return code: ", r) 

And that’s all that’s required. You’ve now setup a Flask server using certificates stored in RACF. 

0 comments
19 views

Permalink