Secure store aren’t

Applications such as Zowe can store secure information on the end user’s machine. This is not very secure! It is built into the operating systems. It is a bit like securing a door with a bit of string. Joshua Waters pointed out

The fact of the matter is that regardless of whether or not you are storing your credentials on a machine, if there is a virus or malicious actor on it, your credentials are up for grabs while the user is logged in. The only time they wouldn’t be up for grabs is if you were using an application that either require some master key to access the credentials store for it, or every authed request to the server requires user to re-enter credentials.

On Linux

The information is in the gnome-keyring ~/.local/share/keyrings/login.keyring .

You can use the Linux command seahorse to display the contents of the gnome-keyring. The user’s password is used to decrypt the store.
The following python code display the keyring contents

import secretstorage
conn = secretstorage.dbus_init()
collection = secretstorage.get_default_collection(conn)
for item in collection.get_all_items():
    print('='*30)
    print('label:', item.get_label())
    print('attributes:')
    for k,v in item.get_attributes().items():
        print('\t%-12s: %s' % (k,v))
    print('secret:',item.get_secret())

This gave

label: Zowe/secure_config_props
attributes:
account : secure_config_props
service : Zowe
xdg:schema : org.freedesktop.Secret.Generic
secret: b'eyIva...9fQ=='

The secret is based64 encoded. You can decode it (on Linux) with

base64 -d <<<"eyIva...9fQ=="  

This gave

{"/home/colinpaice/ssl/ssl2/zowe.config.json":
{"profiles.project_base.properties.user":"colin",
"profiles.project_base.properties.password":"password"
}
}

Where /home/colinpaice/ssl/ssl2/zowe.config.json is the name of the configuration file it applies to.

You can delete an entry using

import secretstorage
conn = secretstorage.dbus_init()
collection = secretstorage.get_default_collection(conn)
for item in collection.get_all_items():
print('='*30)
print('label:', item.get_label())
if item.get_label() == "Zowe/secure_config_props":
item.delete()
print("delete")
continue

This deletes all of the entries for that component – so all the Zowe data.

Who can see the contents of the store?

Your gnome-keyring is encrypted with your password, so you can access it. Someone one else would need your password to be able to decrypt it and see the contents.

What happens on other platforms?

On Windows and Mac’s it is essentially the same. There is a secure disk, and you need to be running as the owner to access it.

If your machine is infected with a virus, which runs under your userid, it can access the key stores and so get userid and password information store in the “secure store”.

Zowe cli help command is not helpful!

The zowe cli help option does not easily tell you how to get all of the help. In order to get the syntax of the command – you have to know the full command with the and then add the --help option! (This is working as designed!)

There is some online help here in a tree view or a “flat view of all of the commands“.

Whoops profile options not found


Step 1

The command zowe --help gives output including

USAGE
zowe <group>

Where <group> is one of the following:

GROUPS
auth Connect to Zowe API ML authentication service
config Manage JSON project and global configuration
zos-console | console Issue z/OS console commands and collect responses

...

Step 2

Now you know there is a console command….

The command zowe --help console gives output including

 USAGE

zowe zos-console <group>

Where <group> is one of the following:

GROUPS

collect Collect z/OS console command responses
issue Issue z/OS console commands

Step 3

Now you know there is a console issue command…

The command zowe --help console issue finally gives lots of output including

  • OPTIONS
    • --console-name | --cn | -c
    • --include-details | --id | -i
    • --key-only | --ko | -k (boolean)
    • --return-first | --rf | -r (boolean)
    • --solicited-keyword | --sk | -s (string)
  • ZOSMF CONNECTION OPTIONS
    • --host | -H (string) The z/OSMF server host name.
    • --port | -P (number) The z/OSMF server port. Default value: 443
    • --user | -u (string) Mainframe (z/OSMF) user name, which can be the same as your TSO login. Your TSO logon userid
    • --password | --pass | --pw (string) Mainframe (z/OSMF) password, which can be the same as your TSO password. Your TSO userid’s password
    • --reject-unauthorized | --ru (boolean) Reject self-signed certificates. Default value: true
    • --base-path | --bp (string) The base path for your API mediation layer instance. Specify this option to prepend the base path to all z/OSMF resources when making REST requests. Do not specify this option if you are not using an API mediation layer.
    • --protocol (string)
    • --cert-file (local file path) The file path to a certificate file to use for authentication
    • --cert-key-file (local file path) The file path to a certificate key file to use for authentication
    • --completion-timeout | --cto (number) The amount in time, in seconds, a REST operation should wait to complete before timing out
    • --establish-connection-timeout | --ecto (number) The amount of time, in seconds, a REST operation should wait while connecting to the server before timing out.
  • PROFILE OPTIONS
    • --zosmf-profile | --zosmf-p (string) The name of a (zosmf) profile to load for this command execution.
    • --base-profile | --base-p (string) The name of a (base) profile to load for this command execution.
  • BASE CONNECTION OPTIONS
    • --token-type | --tt (string) The type of token to get and use for the API. Omit this option to use the default token type, which is provided by ‘zowe auth login’.
    • --token-value | --tv (string) The value of the token to pass to the API.
  • MQ options
    • --mq-profile | --mq-p (string) The name of a (MQ) profile to load for this command execution.

Now you know what the options are you can search for them. This pointed me to the console command page.

Whoops profile options not found

I fell over trying to specify a nested profile.

For example

...
"profiles": {
"qa_lpar": { // Base profile connection properties are used unless overriden
"type": "base",
"properties": {
}
},
"profiles": {
"mq": {...
},

This is referred to as qa_lpar.mq .

What would I have done?

Personally I would have have a help page which listed all of the common options then list commands for example

  • Common options
    • --host etc

Specific commands

Why did that curl request take so long?

I’ve just discovered that you can get curl to report how long each part of a session took.

I set up a bash script

t=(--write-out "\n DNS Lookup:%{time_namelookup}s\n TCP Connect:%{time_connect}s\n TLS Handshake: %{time_appconnect}s\n Total Time: %{time_total}s\n")
...
curl -X PUT --header 'Content-Type: application/json' "${t[@]}" ....

and in the output it gives

 DNS Lookup:0.000033s
TCP Connect:0.003088s
TLS Handshake: 0.322826s
Total Time: 0.981765s

Note the \n in the text to give new lines.

For more details

see curl man page. –write-out.

You can specify an output file, stderr or stdout.

There are many parameters, the performance timing ones are

  • time_appconnect: The time, in seconds, it took from the start until the SSL/SSH/etc connect/handshake to the remote host was completed.
  • time_connect: The time, in seconds, it took from the start until the TCP connect to the remote host (or proxy) was completed.
  • time_namelookup: The time, in seconds, it took from the start until the name resolving was completed.
  • time_posttransfer:The time it took from the start until the last byte is sent by libcurl. In microseconds.
  • time_pretransfer: The time, in seconds, it took from the start until the file transfer was just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved.
  • time_queue: The time, in seconds, the transfer was queued during its run. This adds the queue time for each redirect step that may have happened. Transfers may be queued for significant amounts of time when connection or parallel limits are in place.
  • time_redirect: The time, in seconds, it took for all redirection steps including name lookup, connect, pretransfer and transfer before the final transaction was started. “time_redirect” shows the complete execution time for multiple redirections.
  • time_starttransfer: The time, in seconds, it took from the start until the first byte was received. This includes time_pretransfer and also the time the server needed to calculate the result.
  • time_total: The total time, in seconds, that the full operation lasted.
  • tls_earlydata: The amount of bytes that were sent as TLSv1.3 early data. This is 0 if this TLS feature was not used and negative if the data sent had been rejected by the server. The use of early data is enabled via the command line option “–tls-earlydata“.

z/OSMF console times out with return code 2 reason code 21

When trying to use the z/OSMF console interface to issue a console command and get the response I got after 60 seconds.

{“reason”:”Timeout when creating TSO address space for console COLIN99″,”return-code”:2,”reason-code”:21}

This was caused by PARMLIB(IZUPRMCM) not having a HOSTNAME specified, and was picking up a HOSTNAME of S0W1.DAL-EBIS.IHOST.COM. When I specified HOSTNAME(10.1.1.2) and restarted z/OSMF it all worked!

The HOSTNAME can be in various places in TCP/IP and the value from TSO (and jobs) may be different from a Unix thread.

I had to use the address of the TCP/IP stack for example 10.1.1.2; using the address of 127.0.0.1 didn’t work. I could not connect to z/OSMF from my client.

It was strange that with the HOSTNAME missing, I could create TSO address spaces.

How did I diagnose this problem?

In the file /global/zosmf/data/logs/IZUG0.log were entries like

INFO:Prepare to start new TSO/E address space with acct: ACCT#, proc: IZUFPROC, rsize: 50000, apptag: IZUCONAP 
Ýtx000000000000000E:IBMUSER@10.1.0.2 (PUT) /zosmf/restconsoles/consoles/COLIN99?null¨
2025-06-28T16:44:02.114Z|00000092|com.ibm.zoszmf.consoles.tsoconnect.Connection|run
WARNING:exception when run as server:
java.net.SocketTimeoutException: Connect timed out
...
at java.base/sun.net.www.http.HttpClient.openServer(HttpClient.java:531)
...
at com.ibm.zoszmf.consoles.tsoconnect.Connection$3.run(Connection.java:372)

This shows the TSO account number, the TSO procedure, the region size. I checked these were valid, and the userid had access to them.

The http request was a clue that this was using TCP/IP, and not using the TSO services available through CEA interface.

How did I run the command?

I used a script like

name=”colinpaice”
cert=” –cert ./$name.pem:password –key $name.key.pem”

insecure=”–insecure”
curl -X PUT –header ‘Content-Type: application/json’ $cert –header ‘Accept: application/json’
–insecure -d ‘{ “cmd”: “d a,l”, “sol-key”: “JES” }’
https://10.1.1.2:10443/zosmf/restconsoles/consoles/COLIN99&#8217;

What CEA TSO operator commands are there?

Part of the CEA facility service on z/OS, provides the capability for an application to start TSO address spaces, send it TSO commands, and receive the responses. This is used by products lie z/OSMF. You can have a CEA TSO address spaces for a user, as well as a “normal” TSO userid, where you logon and use ISPF.

More information about the commands

Change the CEA parameters F CEA,CEA=(x1,x2,…xN)

Display the CEA configuration parameters F CEA,D,P

STATUS: ACTIVE-FULL      CLIENTS: 0  INTERNAL: 0            
CEA = (00)
SNAPSHOT = N
HLQLONG = CEA HLQ =
BRANCH = COUNTRYCODE =
CAPTURE RANGE FOR SLIP DUMPS:
LOGREC = 01:00:00 LOGRECSUMMARY= 04:00:00
OPERLOG = 00:30:00
CAPTURE RANGE FOR ABEND DUMPS:
...
CAPTURE RANGE FOR CONSOLE DUMPS:
...
TSOASMGR:
RECONSESSIONS = 0 RECONTIME = 00:00:00
MAXSESSIONS = 50 MAXSESSPERUSER= 10

Display a summary of CEA TSO regions F CEA,D,S

STATUS: ACTIVE-FULL      CLIENTS: 0  INTERNAL: 0         
EVENTS BY TYPE: #WTO: 0 #ENF: 0 #PGM: 0
TSOASMGR: ALLOWED: 50 IN USE: 1 HIGHCNT: 0

Display client summary F CEA,D,CLIENTSUMMARY and D CEA,CLIENT=*

STATUS: ACTIVE-FULL      CLIENTS: 0  INTERNAL: 0                   
EVENTS BY TYPE: #WTO: 0 #ENF: 0 #PGM: 0
TSOASMGR: ALLOWED: 50 IN USE: 1 HIGHCNT: 0
NO CLIENTS KNOWN TO CEAS AT THIS TIME
12I CN=L700 DEVNUM=0700 SYS=S0W1

Display the session information F CEA,DIAG,SESSTABLE

INDEX=0001 USERID=COLIN    APPID=IZUCONAP ASID=004E MSGQID=00060018                       
COUNT=0001 ASCBADDR=FC3B80 STOKEN=0000013800000009 STTIME=15:34:43.966
LRTIME=15:34:43.967 LOGONPROC=IZUFPROC GROUP= REGION=50000
CODEPG=1047 CHARSET=697 ROWS=204 COLS=160 RECONN=N RCTIME=00:00:00.000
ACCT=ACCT#
HOST REMOTESYS= REMOTEQID=00000000 CALLERSYS=

This shows information like the TSO LOGON procedure used, the screen size,the region size and the account number.

Mapping a certificate to a userid and so avoid needing a password is good – but…

You can use the RACDCERT MAP command to map a certificate to a userid, and so avoid the need for specifying a password. Under the covers code uses the pthread_security_np and pass a certificate, or a userid and password, and if validated, the thread becomes that userid, just the same as if the userid was logged on.

Is this secure?

If you store a userid and password on your laptop, even though the data may be “protected” someone who has access to your machine may be able to copy the file and so impersonate you.

With a public certificate and private key, if someone can access your machine, they may be able to copy these files and so impersonate you.

You can get dongles which you plug into your laptop on which you can store protected data. In order to use the data, you need the physical device.

You need to protect the RACF command

Because the RACFCERT command has the power to be dangerous, you need to protect it.

You do not want someone to specify their certificate maps to a powerful userid, such as SYS1. The documentation says

To issue the RACDCERT MAP command, you must have the SPECIAL attribute or sufficient authority to the IRR.DIGTCERT.MAP resource in the FACILITY class for your intended purpose.

For a general user to create a mapping associated with their own user ID they need READ access to IRR.DIGTCERT.MAP.

For a general user to create a mapping associated with another user ID or MULTIID, they need need UPDATE access to IRR.DIGTCERT.MAP.

What’s the best way to set this up?

I think that as part of your process for setting up userids, the process should create the mapping for the certificate to a userid. This way you do not have people creating the mapping. If a mapping already exists, you cannot create another mapping.

You may want an automated process which checks the approval, and issues the commands, and so you do not have humans with the authority to issue the commands.

Of course you’ll have a break-glass all powerful userid in case of emergencies.

But….


Even though the password had expired, I could logon using the certificate. If I revoked the userid the logon failed.

I used certificate logon from z/OSMF and issued console commands. The starts a TSO address space, and z/OSMF passes the commands and responses to the tso address space.

Once a TSO address space has been started, there are no more checks to see if the userid is still valid.

If you want to inactivate the userid, you’ll need to revoke it, and then cancel all the TSO address spaces running on behalf of the userid. Walking someone off site is not good enough. There may be scripts which are automated, and will logon with no human intervention.
TSO address spaces may be configured to be cancelled if there is no activity. If the TSO address space is kept busy, (for example by sending it requests) it may never be forced off.

Wow – sdsf can remember thousands of console commands

By default SDSF can remember up to 50 commands.

SDSF can support 1000’s of commands in its history list – and can also group them by user specified name. I have a group called zosmf, and it has all the commands for managing z/OSMF. I have another group for zowe, and this has the commands I use for Zowe.

This is documented here.

Customisation

This is documented here.

I allocated the dataset COLIN.SDSF.ISFTABL as a PDS FB LRECL80, 1 Cyl primary, 1 Cyl secondary.

I blogged on how to create a logon script for allocating your definitions.

The important part is you need to allocate the data set as ISFTABL

SET &SDSFTAB= &STR(&SYSUID..SDSF.ISFTABL)
ALLOC DA('&SDSFTAB') SHR FILE(ISFTABL)

Using it

Use the / command to display the pop up the System Command Extension window.

This has

   Edit  Options  Help                                                
────────────────────────────────────────────────────────────────────
System Command Extension

===> p izusvr1______________________________________________________
===> _______________________________________________________________

Comment

Group ZOSMF Show ZOSMF (F4 for list)

=> p izusvr1
=> s izusvr1
=>
=>

F5=FullScr F6=Details F7=Up F8=Down F10=Save F11=Clear F12=Cancel

Type a command, specify a group, and press PF10 for save.

To display the commands for a group, either

  • tab down to Show and type the group name, or
  • tab down to Show and press PF4, then select the group

You use the Group field when saving commands, and Show when displaying commands.

Full screen display

You can press PF5 to make it full screen (or not full screen).