C calling an “assembler” function, setting the high order bit on, and passing parameters.

Since days of old when knights were bold, the standard parameter list to call an assembler function was to pass the addresses of the parameters, and set on the top bit of the address for the last address.
This way the called function knows how many parameters have been passed, and you do not need to pass a parameter count.

Setting the high order bit on, for the last parameter

I had to ask for help to remind me how to do it from C, so I could call “Assembler” functions.

You can get C to do this using

#pragma linkage(IRRSPK00 ,OS)

Example

The syntax of the routine from the RACF callable services documentation is

CALL IRRSPK00 (Work_area,
  ALET, SAF_return_code,
  ALET, RACF_return_code,
  ALET, RACF_reason_code,
  ALET, Function_code,
  Option_word,
  Ticket_area,
  Ticket_options,
  Ticket_principal_userid,
  Application_Id
)

Here is part of my C program.

#pragma linkage(IRRSPK00 ,OS)
...
long SAF_RC,RACF_RC,RACF_RS; 
SAF_RC=0 ; 
long ALET = 0; 
// ticket options needs special treatment, see below
int Ticket_options = 1; 
int * pTO = & Ticket_options; 

rc=IRRSPK00( 
         &work_area, 
         &ALET , &SAF_RC, 
         &ALET , &RACF_RC, 
         &ALET , &RACF_RS, 
         &ALET ,&Function_code, 
         &Option_word, 
         &ticket, // length followed by area 
         &pTO, 
         &userid, 
         &appl 
         );

If you use #pragma linkage(IRRSPK00 ,OS) it sets on the high order bit. You pass the address of the parameters. I just used &variable, there are other ways.

Passing variables

Most of the parameters are passed by address for example &ALET inserts the address of the variable, conforming to the z/OS standards.

There is a field Ticket_principal_userid which is the name of a 10-byte area that consists of a 2-byte length field followed by the userid id for whom a PassTicket operation is to be performed followed by an 8-byte PassTicket field.

I defined a structures for each variable like

struct {
  short length;
  char value[8];
} ticket;

In the program I used &ticket.

Ticket option

The documentation says

Ticket_options: The name of a fullword containing the address of a binary bit string that identifies the ticket-specific processing to be performed.

It took me a while to understand what this meant. I had to use

int Ticket_options = 1; 
int * pTO = & Ticket_options;

and use it

int Ticket_options = 1; 
int * pTO = & Ticket_options; 
...
 &ticket, // length followed by area 
 &pTO,

Whoops R_GenSec (IRRSGS00 or IRRSGS64): Generic security API interface

I had great problems getting this to work. The documentation said

The address double words from 31 bit callers should have the first word filled with
zeros and the second word filled with the 31 bit address. Sub-parameter addresses will be in the format of the AMODE of the caller.

I do not know what this means. When I coded it as expected I got

CEE3250C The system or user abend S0E0 R=00000029

Which means invalid ALET supplied.

I converted the program to 64 bit and it still failed!

Getting into supervisor mode and other hard things in C, is easy.

Some functions in z/OS need a user to be in a privileged state such as key zero or supervisor state. Writing the code in assembler has been pretty easy, but writing it in a C program has been hard.

For example you could write a function in assembler, and call it. This has the cross language challenges.

I recently found an easy way – just reuse some code from Zowe. This is open source, so you need to follow the license

This program and the accompanying materials are made available under the terms of the Eclipse Public License v2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html

SPDX-License-Identifier: EPL-2.0

Copyright Contributors to the Zowe Project.

The code uses __asm() Inline assembly statements (IBM extension).

The functions are

  • ddnameExists
  • wtoMessage
  • wtoPrintf3
  • atomicIncrement compare and swap
  • testauth
  • extractPSW
  • supervisorMode or back to problem state
  • setKey
  • getExternalSecurityManager
  • getCVT
  • getATCVT
  • getIEACSTBL
  • getCVTPrefix
  • getECVT
  • getTCB
  • getSTCB
  • getOTCB
  • getASCB
  • getASXB
  • getASSB
  • getJSAB
  • getCurrentACEE
  • getFirstChildTCB
  • getParentTCB
  • getNextSiblingTCB
  • resolveSymbolBySyscall Input: A symbol starting with & and not ending with .
  • resolveSymbol Input: A symbol starting with & and not ending with .
  • lots of saf functions see here
  • loadByName
  • getDSAB Data Set Association Block
  • isCallerLocked
  • isCallerCrossMemory

Some of these need to be APF protected, so although it is easy to use the above code, you may still need to get the load library APF authorised, and the code approved.


For example

Get into supervisor state

The code here.

int supervisorMode(int enable){
// Use MODESET macro for requests
  int currentPSW = extractPSW();
  if (enable){
    if (currentPSW & PROBLEM_STATE){
      __asm(ASM_PREFIX
            " MODESET MODE=SUP \n"
            :
            :
            :"r0","r1","r15");
      return TRUE;
    } else{
      return FALSE;  /* do nothing, tell caller no restore needed */
    }
  } else{
    if (currentPSW & PROBLEM_STATE){
      return TRUE;   /* do nothing, tell user was in problem state */
    } else{
      __asm(ASM_PREFIX
            " MODESET MODE=PROB \n"
            :
            :
            :"r0","r1","r15");
      return FALSE;
    }
  }
}

To compile it I used

// SET LOADLIB=COLIN.LOAD 
//DOCLG       EXEC   PROC=EDCCB,INFILE='ADCD.C.SOURCE(C)', 
//            CPARM='OPTF(DD:COPTS)' 
//*           CPARM='LIST,SSCOMM,SOURCE,LANGLVL(EXTENDED)' 
//COMPILE.ASMLIB DD  DISP=SHR,DSN=SYS1.MACLIB 
//COMPILE.COPTS DD * 
LIST,SOURCE 
aggregate(offsethex) xref 
SEARCH(//'ADCD.C.H',//'SYS1.SIEAHDR.H') 
TEST 
ASM 
RENT ILP32        LO 
OE 
NOMARGINS EXPMAC   SHOWINC XREF 
LANGLVL(EXTENDED) sscom dll 
DEFINE(_ALL_SOURCE) 
DEBUG 
/* 
...

You need to specify

  • //COMPILE.ASMLIB for the the assembler macro libraries.
  • and the compiler option ASM which enables inlined assembly code inside C/C++ programs.

I was all so easy, once I had been told about it.

Wow, how to logon securely is so complex….

I’ve been looking into login on to Zowe and z/OSMF, and have realised how complex it is to set up secure logon.

An obvious fact about real life

If someone has access to your machine, for example a hacker, then they have access to your files, and data in virtual storage.

I cover

A lot of the time it is not difficult, but you need to handle the edge cases. When there are multiple dimensions to the problem, the edge case becomes the corner case, and this is where it gets really hard.

I use the expression is not secure. Being secure is relative. If your machine is air gapped with no external access, the machine should be secure. If people can access your files, perhaps on a shared machine, or a hacker can accessed your machine, I would not consider this secure.

The simplest case of logging on manually from a client machine to the server

Of course you use a TLS session to ensure the session traffic is encrypted.

You can type the values into the userid and password fields. It works, simple. If I disconnect and reconnect, I need to re-enter the userid and password

If I am using more than one back end server, I’ll have to enter the userid and password for each system, while the session is active.

Once the userid and password have been used, the fields in memory should be overwritten (but I doubt if this is always the case), to minimise the time window when a hacker extract the values from memory.

The simple case of logging on from a script from the client to the server.

You will not be there to enter the password so it needs to be stored.

The script may prompt you for the userid and password. You enter the information once, and it keeps them in virtual storage, and does not write them to disk. At the end of the session these values need to be overwritten in case a hacker is wandering round your system.

The application may write the information to disk – and we immediately hit a major problem. If a hacker has access to your system, then they can access (and copy away from your machine) the file where the password is stored. On Linux I displayed the contents of the “secure store” with a few lines of Python. I believe it is the same for Windows and Apple machines. (If your userid needs access to the secure store for something, a hacker thread running with your userid can access the store).

We have quickly seen that the use of a password stored on the machine is not secure.

Use of a certificate

As part of the TLS handshake there is a private key kept on the local machine, and a public key is sent to the partner.

Trusting a certificate

As part of setting up the public key, I send the public key to the server. The server’s Certificate Authority does a checksum of the public key, then encrypts the checksum with the server’s private key. The public certificate, encrypted checksum and the CA’s public key are sent back to the originator.

When the public certificate is used as part of the TLS handshake, the server does the same checksum calculation as before on public certificate, and saves it momentarily. It takes the encrypted checksum from the payload, decrypts it, and compares the two checksum values. If they match, then the client’s certificate can be trusted and has not been changed. Therefore the certificate is trusted (for a given level of trust) to represent the end user.

My program has access to my private key – so authenticates as me

As part of the handshake data, the client encrypts some data using its private key, and sends this to the server. The server uses the public key it received, and decrypts this value. If the decrypted data matches what it is expecting, then this is proof that the client has the private key and is who they say they are.

The server can then use the mapping of “name in the public key” to a userid, to determine which userid the requester should run under.

Once this is set up, the client can connect to the server without specifying a userid and password.

There is a proposal to reduce the validity time of personal certificates from over a year to 47 (or less) days. This reduces the time window when a certificate can be used.

This is great … but

If your private key is stored on your disk, a hacker can steal a copy of the file and impersonate you. So once again this is not very secure.

Use a private key – external to your computer

You can get a dongle, such as a Yubikey which keep the private key secured on a detachable USB dongle. To use it, a request is passed to the dongle saying “please encrypt this data”. It encrypts the data, returns it, and it can be sent to the server. You cannot extract the private key from the dongle.

To use this for authentication you physically need the dongle. If someone has control of your machine, they can use this dongle when it is plugged in. If they just have a copy of your files they cannot use the dongle, and so this is secure.

If you remove the dongle when you are not using it, we have a secure solution, until you plug it back in! Most people may forget and leave the dongle in all day.

I’ve been to sites, where the private key is stored on their badge. When they want to authenticate they put their badge on a badge reader and authenticate. This is awkward, so they immediately take their badge off the reader after authentication.

Setting up these external key stores is not trivial.

Use of Multi Factor Authentication(MFA)

One of the main approaches to MFA is

  • something you have
  • something you know

MFA is often used in applications such as online banking.For some transactions you will have a code sent to your email address. Something you know is your application password, something you have is the code sent to you. To use the service, an application password and access to your email is required.

MFA can also use one time passwords – so if someone is monitoring your network traffic they will not be able to reuse the one-time-password.

You can get the one-time-password generated from your badge, a dongle attached to your machine, or an application, such as an authenticator application on your phone. Once these apps have been configured to the back-end, you can press a button and get a one time code.

To logon you may need your normal logon password (which you change monthly) and the one time code from the MFA device. You might just need the one-time-code – depends on how the environment has been set up.

This is great for you logon to a backed and stay connected. If you have script, or are using multiple back-end servers. This becomes impractical. You need a new one-time-code each time you logon. This can be automated if the MFA device is attached to your machine, but not if you are using a mobile phone application.

One small problem is when the user’s password has expired. They are prompted to change it, and now need another One Time Password – and they may have to wait for a period (seconds) before a new one is generated.

JSON Web tokens

See Are JSON Web Tokens secure? – Yes if used properly.

A JSON Web Token(JWT) provides a time limited key, and so avoids the problems when changing a password. Some of the concepts are similar to a certificate logon, but with a limited validity, from minutes to hours.

With RACF these are known as Identity token. (Having a different name, means RACF development can extend the support to cover additional tokens types.)

A JWT has three parts

  • Information about the JWT. This JWT has used an RSA certificate, and algorithm SHA256.
  • Identity information. The userid is…, it was issued by ( z/OSMF, or SAF), at this time…. and is valid until….
  • The above parts are check summed, and the check sum is encrypted using a private key.

The above 3 parts are base 64 encoded, and joined together with a ‘.’ between them.

Once a JWT token is created, it is valid until it expires. You need to consider if you want a JWT to be valid for a few minutes, or all day.

You create (or have the system create for you) the header and the payload. You calculate the checksum, and encrypt the checksum with the private key.

The parts of the JWT are assembled and sent to the partner.

The partner uses its copy of the public key, and checks that the checksum matches what it expects and, if it matches, can use the information in the payload part. This validation could be a call to a RACF service, a https request to a server, or Java.

Once the JWT has been validated, the server can use the information in the payload.

You do not want to use the userid in the JWT directly, because the userid COLIN on one system has no authority, but has super user authority on another system.

With RACF you can map a userid string to a RACF userid using profiles defined with the RACMAP command. See the r_usermap service.

While the JWT is valid it could be used by a hacker.

Overall

It looks like there is not one good solution to cover all cases.

Someone said “assume your machine will be hacked. Minimise what damage they can do”. This may be as simple as turning your machine off overnight, so the hackers cannot control it

The solution for scripts may be different to people logging on.

You may want to have a userid just for scripts, which has only enough authority and permissions to work, and no additional permissions.

You need to consider the options and risks, and not just sleepwalk into having an insecure system.

What are JSON Web Tokens and how do they work?

Wikipedia says

JSON Web Token (JWT) is a proposed Internet standard for creating data with optional signature and/or optional encryption whose payload holds JSON that asserts some number of claims. The tokens are signed either using a private secret or a public/private key

What does a JWT look like?

A JWT has three parts

  1. Header: Information about the JWT itself, such as the Algorithm type.
  2. Payload: This contains information such as creation datetime, expiry datetime, secret key, userid.
  3. Encrypted checksum: (the signature) of parts 1 and 2.

A header looks like

{
  "alg": "RS256"
}

A payload looks like

{
  "sub": "IBMUSER",
  "iat": 1753381341,
  "exp": 1753410141,
  "iss": "APIML",
  "jti": "699cdd3b-832a-4b27-95f6-2a0a9fd5375a",
  "dom": "security-domain"
}

Where

  • sub: is the principal (userid) within the payload
  • iat: issued time
  • exp: expiry time
  • jti: is unique value
  • dom: is the security domain.

These are converted to base64 where each 3 bytes are encoded as 4 printable characters.

The payload could include a userid and a file name, and because an authentication server has created the JWT, the server can send the file to the user without much more authentication.

How does it work?

I understand (from reading the limited online documentation), that it works as follows.

Create your payload.

Some fields you might specify are

  • sub: subject – such as a userid
  • iat: The issued time
  • exp: The expiry time
  • jti: A unique value for the JWT
  • You might put in a public certificate name
  • you can include a public key as a JSON Web Key (JWK) representation of cryptographic key.

This will include the algorithm used to sign the JWT.

Calculate the signature

You use a private key, and the algorithm, and calculate the signature (encrypted checksum) of the header and payload, and append it to the header and payload.

How long should it be valid for?

The JWT has the creation time, and the expiry time, after which the JWT is no longer valid.

You need to consider what valid interval to use. Remember a JWT is a pre-authorised userid token. It can be used multiple times before it expires. A hacker could copy it and use it.
You might chose a short time if it is just used to establish a session, and is not used again.

You might use a longer interval if you keep connecting and disconnecting from servers. Once it expires you have to request another JWT. The longer the expiry interval, the longer a hacker can use the JWT.

Creating the JWT

There are different ways of creating the JWT. For example

  • You can use Java
  • use the Python package pyJWT
  • Use RACF services. This creates a JWT. It requires supervisor state, so is not easy to set up. You can create RACF profiles which are used to create the JWT.

Send the JWT to the requester

The JWT is sent to the client which can use it to authenticate with a back end server which supports JWTs.

The server authenticates the JWT

This is server dependent.

  • One approach is to go through every public certificate in the key store, until the right one is found
  • You could specify the name of the public certificate in the header, and use that.

Note. This is different to TLS and certificates. With TLS the public certificate is sent as part of the handshake. The public key is authenticated by the Certificate Authority (CA) at the recipient. With TLS you only needs the CA certificate, not the individual certificates to validate. (Except for self signed which you should not be using). With a JWT you need the public certificate, it is not passed within the JWT

Note 2. There is discussion about a server sending the jti value in the JWT to an authorisation server, to get back the public key, which can be validated with a CA etc.

The back end may need to validate with the authorisation server. The request may be along the lines of “I’ve received userid COLIN, and the JTI from the JWT value is COLIN123456… is this valid?” This could be a cross memory request, for example using a RACF service, or it could be a TLS request to a server.

If the response is positive, then you can trust the information in the payload.

Use the information in the JWT payload.

The backend should not just use the userid in the payload, because I could easily create my own JWT (such as with pyJWT), as long as the server has my public key, the signature matches and verifies my unofficial JWT, and so I get unauthorised access.

With the openidConnectClient support in Liberty ( used by z/OSMF, MQWEB, and Zowe) you can have multiple openidConnectClient definitions. Each definition can have a filter, so you can restrict each openidConnectClient definition to a particular IP address range, or URL, (or both).

With openidConnectClient you specify the realm name to be used.

On midrange machines, it looks like the userid may be taken from the payload, and used!

Mapping name information to RACF userid.

Once the JWT has been validated in the openidConnectClient definition, the code looks up the JWT userid and realm combination to find which z/OS userid should be used.

There is a RACF service R_usermap (IRRSIM00): Map application user which maps a name and realm to a RACF userid.

You can define the mapping using the RACF command RACMAP, for example:

RACMAP ID(COLIN) MAP USERDIDFILTER(NAME('COLIN')) - 
                     REGISTRY(NAME('PRODZOSMF')) - 
                     WITHLABEL('COLIN')                         

RACMAP ID(ADCDA) MAP USERDIDFILTER(NAME('CN=HACKER')) - 
                     REGISTRY(NAME('*')) - 
                     WITHLABEL('ADCDA') 
                                                                
                                                                
RACMAP ID(COLIN) LISTMAP 
RACMAP ID(ADCDA) LISTMAP 
SETROPTS RACLIST(IDIDMAP) REFRESH

This says

  • if userid COLIN from the JWT, and the realm PRODZOSMF, then use userid COLIN.
  • If userid HACKER from the JWT in any realm, then use userid ADCDA.

If you get RACF abend 648 reason 0000004 see here.

To use this the userid using r_usermap needs permission.

PERMIT IRR.IDIDMAP.QUERY CL(FACILITY) ID (IBMUSER) ACCESS(READ) 
SETROPTS RACLIST(FACILITY) REFRESH

Note. The input to r_usermap is UTF8 (ascii) so the COLIN was passed in as 0x434F4C494E.

Use of different registries.

Because there may be multiple sites sending a JWT, you can use the REGISTRY name to further qualify the mapping. The registry is passed (in ASCII) on the r_usermap call – but you can specify a generic * (ASCII 0x2a) for any registry.

In the JWT above it had “dom”: “security-domain”. You could specify this as the registry.

Planning is required

To use the r_usermap service you need to plan before you start.

  • What format “userid” strings will be used? Is this just a string, or you you create a compound string “origin”.”userid” where origin and userid are taken from the JWT
  • Use of the registry field. If you want to use the registry field to identify different originators machines, you need to ensure that the JWTs are produced with the appropriate domain. If all requests have “dom”:”security-domain” it adds no value.

Zowe explorer: first baby steps to submitting jobs

I found using Zowe explorer was not intuitive, and I had a lot of help to get started.

This blog post explains how to submit JCL, look at the output etc.

Depending on how you are doing authentication you may get prompted for userid, password or both. I use certificate logon, so do not get prompted.

I have a PDS with C code, and a PDS containing the JCL to compile, bind and run the program. I wanted to edit the C source, submit the JCL, and look at the output.

Editing a C file

  • Open Zowe explorer (the Z in a diamond icon)
  • Under data sets, select a profile. You may be prompted to logon.
  • Select the search icon (magnifying glass)
  • Select an existing filter, or create a new one, (for example COLIN.C.Z* )
  • Press enter. This will list the data sets matching the search criteria
  • Single click the data set to display the members
  • Single click the member name to edit it
  • Use Ctrl+S to save your changes.

Editing the JCL file

  • Follow the steps above to open the JCL member
  • Right click and select Submit as JCL
  • This will create a pop up, at the bottom right of the screen with the job number.
  • You can click the job number, and this will open the job under JOBS and the profile on the left hand side. If you have a spool job filter, (to display your spool files) you may not want to click on the pop up job id.
  • Single click the job (under JOBS) to display the content of the spool data sets

Display your usual list of jobs

If you clicked on the pop up window giving the submitted job name, it creates a temporary filter under the JOBS profile.

To reset this back to normal, click on the profile’s search icon, select the filter you want, and select Select this query. (This is too many clicks for me!)

Edit the C file again

You can now go to the C source tab and continue editing your program.

To speed things up

Create/use a keyboard short cut

To jump between the editor windows. Ctrl+Tab, Tab etc to the window. Ctrl+shift+tab to tab backwards.

You can use keyboard short cuts for some of the above. I wanted to create a shortcut to submit JCL.

Ctrl+K Ctrl+S gives the current keyboard short cuts.

Type Ctrl+J in the search window. It gave me

Ctrl+J is in use, so I’ll use Ctrl+Alt+J

Type submit JCL into the search window. This gave me

So I can see it is not bound to a key.

Click on the item, and on the + sign which appears. A window pops up. Use the key combination, and press enter.

Use favourites

For data sets you often use, you can click on them and add to favourites, so they are always there

To have favourites spool job filters when you are looking at the spool.

  • Select the spool filter (and display any output)
  • Right click on the profile, and select Add to favourites
  • The filter will then appear in the Favourites section

If you submit a job, click on the popup window jobid, it will display it in the JOBS, under the active profile. You can get back to your usual spool filter settings, by going to the favourites.

Thanks

With thanks to Joshua Waters for all of his patience in helping me.

Zowe: Setting up vscode before you start, so the editors work

You can configure vscode to say if the type of the is JCL, then display a line at column 80, so you can tell when your lines spill, and other clever things.

You need to install the support

  • IBM provides Z Open Editor, This provides a lot of function – some of which is chargeable. The editing for COBOL, PL/I, REXX, HLASM, and JCL is free. Once is it installed, you can click on the settings icon and display more information about what is supported.
  • Broadcom provides JCL language Support

Open vscode

  • Open the extensions window, Ctrl+shift+X
  • Search for the extension you want, and install it
  • Restart vscode

Configure the vscode settings

You need to do some vscode configuration to get the full benefit of Zowe explorer.

Display the file associations.

Use ctrl+shift+p and type Preferences: Open user settings (JSON).

For me this displayed a file which included

 "files.associations": {
        "**/*.COBOL*{,/*}": "cobol",
        "**/*.COB*{,/*}": "cobol",
        "**/*.COBCOPY*{,/*}": "cobol",
        "**/*.COPYBOOK*{,/*}": "cobol",
        "**/*.COPY*{,/*}": "cobol",
        "**/*.PL1*{,/*}": "pl1",
        "**/*.PLI*{,/*}": "pl1",
        "**/*.INC*{,/*}": "pl1",
        "**/*.INCLUDE*{,/*}": "pl1",
        "**/*.JCL*{,/*}": "jcl",

If I edit a member in a data set which matches *.JCL*, it will be flagged as a language jcl.

Display the language settings

Ctrl+shift+P and search for Preferences: specify language specific settings. This displays all of the languages known to this instance of vscode. Scroll down to jcl. If jcl is missing, you need to install the support. See You need to install the support above

Click on JCL. Information about JCL is displayed. There is a box with @lang:jcl above the display. If you type @lang:jcl ruler it will display information about the ruler parameter

Mine says

Editor: Rulers  (Modified elsewhere . Default value changed)
Render vertical rulers after a certain number of monospace characters. Use multiple values for multiple rulers. No rulers are drawn if array is empty.
Edit in settings.json

If you click on Edit in settings.json it will put you into an edit session.

I inserted

 "[jcl]": {
        "editor.rulers": [10,16,80],      
    },

Save the files. Edit a JCL data set. The sessions should have vertical lines at 10,16, and 80.

Thanks

With thanks to Joshua Waters for getting me working, and answering my many questions.

Zowe: Colin’s zowe cli help options

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!

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

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.

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