Chapter 1: About This Manual

Alliance Key Retrieval library

The Alliance Key Retrieval library is delivered as a library to be linked into client applications on the z/OS, which can retrieve keys securely from the Alliance Key Manager key server product. The library is implemented as a DLL, or dynamic link library, for development and deployment under the z/OS Language Environment. While written in C, the library can be called from any LE conforming application. Sample programs that demonstrate calling the Key Retrieval library are provided in C and COBOL.

Who is this for?

This manual is designed to help IBM System z Mainframe application developers and project managers implement key retrieval in their business applications. This guide provides basic information on the process to install and implement key retrieval and sample application code.

This document describes using the Key Retrieval library in the MVS/batch environment.

Other resources

The following manuals provide information on the installation and use of Alliance Key Manager:

• AKM User Guide

• AKM Server Management Guide

• AKM Administrative Console Guide

• AKM Key Service API Reference

Notices

This product and documentation is covered by U.S. and International copyright law. This product may incorporate software licensed under one or more open source license agreements. Government users please note that this product is provided under restricted government use license controls. Please refer to the Alliance Key Manager End User License Agreement for more information.

Change log

The following table provides information on the changes to this documentation:

Chapter 2: Preparation

The following steps must be completed before continuing with client setup and configuration:

• Install and set up the primary AKM server and any secondary mirror servers (instructions are located in platform specific deployment guides)

• Create encryption keys (available as an option during AKM server setup, or, through the AKM Administrative Console application)

• Download certificates from the AKM server

• Know the IP address(es) of the AKM server(s) and port numbers for the desired services (key retrieval or remote encryption)

See below for more information.

Licensing

A temporary or permanent license is required to use or evaluate AKM. All deployments of AKM create a 30-day license automatically during setup and initialization, except for the Amazon Web Services fee-based deployment, which generates a permanent license.

A temporary license will enable a fully functional AKM server that may be run in your environment for evaluation or testing. If the temporary license expires, a permanent license may be purchased from Townsend Security or your software vendor. See your AKM platform specific deployment guide for information on installing a permanent license.

Certificates

The following certificates are required for client authentication with the AKM server:

• AKM’s certificate authority (CA) certificate in .pemformat (AKMRootCACertificate.pem)

• Client certificate/private key in .p12 format (AKMClientCertificateAndPrivateKey.p12) and associated password

These certificates are generated during AKM server initialization and stored on the server. See your platform specific deployment guide for instructions on downloading certificates.

See Chapter 3 for more information on managing certificates on zOS.

SECURITY ALERT: Private key files must be protected during creation, distribution, and storage to prevent loss. The loss of these files will compromise the security of the AKM server. Depending on the file format, the private key files may be bundled with a certificate or they may be separate files. Transfer the private key files by sharing them over a secure network, placing them in a password-protected zip file, sending them using SFTP, or another secure method. Use the same level of care you would employ to protect encryption keys, including encryption. In the event the private keys are compromised or lost, you should immediately replace the certificate authority on the AKM server and all client certificates in that chain of trust. See the AKM Certificate Manager Guide for more information.

Server information

The following server information is required for client setup and configuration:

• The IP address or DNS name of the primary AKM server and any secondary AKM servers

• The port number that AKM has been configured to use for key retrieval (the default is 6000)

Encryption keys

To set up client key retrieval, you must have the name(s) of the encryption key(s) on AKM you would like to use.

AKM setup and initialization includes the option to generate an initial set of encryption keys. See your platform-specific AKM deployment guide for more information on encryption keys available for use, if that option was selected.

If needed, encryption keys can be created using the AKM Administrative Console application. See the AKM Administrative Console Guide for more information.

Chapter 3: Certificates

The Key Retrieval library uses Digital Certificates to authenticate both the server to the client, and the client to the server. A local certificate repository, keyring, must be maintained at the client installation.

Topics specific to certificate usage on the z/OS are addressed here. A significant difference in AllKeyRtv certificate usage between Linux and z/OS is a consequence of the respective TLS implementations. AllKeyRtv on z/OS does not rely on OpenSSL as on Linux, but rather on IBM’s SystemSSL support, which is native to z/OS. Some of these differences involve the format of certificate files, where they are stored, and how managed and accessed.

It is important to distinguish between “user” certificates, and “authority” certificates. The key retrieval library is a client to the secure AKM server which requires authentication from clients using digital certificates. The client’s certificate is a user certificate, and must be signed by a Certificate Authority recognized by the AKM server.

A Certificate Authority (or “CA”) is a certificate which is either signed by another CA, or is “self-signed”. Generally a self-signed CA certificate would not be trusted outside of the organization which generated it. However, if both the server and all client applications are under one organization’s control, a self-signed (or “private”) CA can be used securely, since the origins and custody of that CA are known.

The CA generated during AKM server initialization is a private self-signed CA certificate.

Configuring z/OS keyring with private certificates

This document assumes that user and CA certificates for the server and all clients are generated by the server initialization process.

The same CA certificate must be installed on both the server and client, but the client will have its own client certificate signed by the AKM CA certificate. The client certificate files must be transferred to the z/OS once created; steps to manage certificate formats and import them into the z/OS keyring are described below.

Exporting user certificates from other platforms

It is also possible to use certificates that were not generated by AKM. If you have client certificates in the .pem format for x509 certificates used on the Linux platform, they must be converted to PKCS#12 (.p12) format to import into the SystemSSL keyring. PKCS#12 files include a private key associated with the certificate, and are password protected.

Using the OpenSSL command line tool, create the client keypair and certificate, in .pem format, and sign the client certificate with the AKM CA certificate. (see the AKM Certificate Guide for OpenSSL for details on this step).

Create the PKCS#12 file with this command (substitute actual filenames for the filenames shown):

openssl pkcs12 -export -out filename.p12 -in certfile.pem -inkey keyfile.pem 

This will create a .p12 file based on the client certificate pem file and the client private key pem file. The command will prompt for a password, which will be used later in importing the .p12 file to the z/OS keyring.

The resulting .p12 file should be transferred to z/OS in binary mode.

Exporting CA certificates from other platforms

CA certificates are Base64 ASCII and must be transferred in text mode, to convert to EBCDIC. If a private CA has been installed on the AKM server with a .pem file, that file should be transferred to the z/OS in text mode, which will convert the Base64 text to EBCDIC; it can then be imported to the local keystore.

Managing the certificate keyring with the gskkyman tool

The key retrieval library uses a certificate repository, which is maintained as an USS/HFS file in the .kdb format. This “keyring” file is created and managed using a tool (part of the SystemSSL component) called “gskkyman”.

The keyring file is the only USS dependency for the z/OS key retrieval client, which is otherwise deployed and used in the batch environment. After the keyring (.kdb file) is created and configured with certificates, access to the .kdb file should be secured with USS permissions and/or RACF enabled ACL’s.

The gskkyman utility is a USS/OMVS based tool with a simple menu driven interface. While many operations can be scripted, some, such as creating a new keyring, must be done via the menu interface.

This document is focused on the subset of features and steps to support the Alliance Key Retrieval library.

Online documentation for gskkyman can be found at:

• https://publib.boulder.ibm.com/infocenter/zos/v1r9/index.jsp?topic=/com.ibm.zos.r9.gska100/sssl2gsk1725369.

To launch the tool, access the USS shell directly via telnet, or the OMVS shell from ISPF option 6 (Command) and type OMVS (the ISHELL interface is not suited to the key manager tool). The user running the gskkyman tool to create the keyring and import certificates should have read, write and execute permissions for the USS/HFS directory used, and steps to fully secure the keyring with RACF and ACL’s (as described below in a separate section) should be done after keyring has been created and populated with certificates.

Creating the keyring

The first step is to create a key/certificate database (keyring). This is menu option 1, and it will prompt for a path and filename to create; there will also be a prompt to set a password (required). An expiration, in number of days, can be entered next, or press Enter for no expiration. A final prompt asks for the key database record length; the default is too small, a minimum value of 8192 is recommended.

The path and filename is named in the ALLKeyRtv configuration file cert section, in the KeyringName line, and the password goes in the KeyringPassword line.

In describing the steps, arbitrary names are used here, and can be changed for production. For example, after selecting menu option 1, at the filename prompt, entering “allkeyrtv.kdb” will create a keyring of that name in the current directory. If the current directory is something like: /u/akm, then the full pathname /u/akm/allkeyrtv.kdb would be entered in the configuration file, and read/write access rights should be granted to that directory for any key retrieval jobs.

Subsequently, menu option 2 can be used to open and work with an existing keyring; the full pathname of the .kdb file and the password must be supplied.

NOTE: The gskkyman menu interface is not very robust: typing errors will generally not be correctable, and the operation must be re-attempted.

Installing certificates to the keyring

Once the keyring has been created, to communicate with the AKM server, a trusted client certificate must be installed. The certificate is trusted if it is digitally signed by a Certificate Authority (CA) which is trusted by the AKM server (See the AKM User Guide for more information about server certificates and CAs). The trusted CA certificate must first be installed to the keyring before the client certificate.

The CA certificate installed on the AKM server must be imported to the z/OS keyring. This document assumes the CA certificate is in the .pem format. A PEM file will be Base64 ASCII text. Before importing into a gskkyman keyring, the Base64 ASCII file must be converted to EBCDIC.

When the file is ready to import, and the keyring has been created or opened in gskkyman, menu option 7 (Import a certificate) can be used to import the CA certificate file. The full path and filename must be entered when prompted. A second prompt asks for a label. Any unique value can be supplied to reference the certificate in later operations using gskkyman. This label is not referenced by the Key Retrieval library or configuration file; the label referenced in the configuration file is the label for the Client (user) certificate.

After the keyring contains a trusted CA, the client certificate itself can be imported to the keyring, provided it has been signed by the AKM trusted CA. Client certificates generated during AKM server initialization fulfill this requirement.

See the AKM Certificate Guide for OpenSSL for details on creating the client certificate with the OpenSSL tools, and for certain requirements (such as the ‘Organizational Unit’, or ‘OU’ value), which are specific to using the certificate with AKM.

If the client certificate was generated on Linux with OpenSSL, it will need to be converted to PKCS#12, along with the client’s private key (the public key is embedded in the certificate itself). If a client certificate exists in a Windows keystore, it will already be in PKCS#12 format, and Windows documentation should be followed to export the cert to a .p12 file.

To import an existing signed client certificate, once it has been converted to PKCS#12 format and transferred to z/OS in binary mode, use gskkyman menu option 8 (Import a certificate and a private key). The exact full path and filename and password must be supplied, and a label.

This password is the same as used when creating the .p12 file from the client certificate and private key pem files as described in the CERTIFICATES section. However, this password is not referenced in the configuration file; the password in the configuration file is for the keyring (.kdb file) itself. This password, for the PKCS#12 file, is to protect the private key and certificate while being transferred.

As with importing a CA, the label supplied in this step must be unique to the keyring, but is otherwise arbitrary. The client certificate label is referenced in the configuration file’s [cert] section, in the Label line.

When finished using the gskkyman tool, the USS shell can be closed by typing the ‘exit’ command.

Chapter 4: Supported Platforms and Dependences

The AllKeyRtv library for z/OS was developed and tested on z/OS v1R9. The key retrieval library uses the IBM SystemSSL library, which is part of the System SSL Cryptographic Services Base element of z/OS, and installed with Cryptographic Services Security Level 3 (FMID JCPT391).

More information on system configuration and dependencies can be found on IBM’s online documentation:

• https://publib.boulder.ibm.com/infocenter/zos/v1r9/index.jsp?topic=/com.ibm.zos.r9.gska100/sssl2int1001213.htm

• https://publib.boulder.ibm.com/infocenter/zos/v1r9/index.jsp?topic=/com.ibm.zos.r9.csf/csf.htm

The SystemSSL library depends on the POSIX environment, and it is critical to set the POSIX runtime option on for any program which uses the Key Retrieval library. This is shown in the sample JCL bundled with the library; see Appendix A and Appendix B for more detail on setting POSIX for C and COBOL .

Chapter 5: Sample Programs

A sample C program that illustrates the key retrieval API is distributed with the library. COBOL examples are also supplied, showing similar usage as the C sample. The C and COBOL examples can be built using the associated sample JCL files, to compile, link and run the samples.

See Appendix A and Appendix B for more details on the samples and programming notes about the key retrieval interface.

Chapter 6: Configuration File

Certain installation specific values are set in a configuration file, including network addresses for key servers and information about certificates used for secure communication with AKM.

This file is in a common ‘ini file’ format, with named sections and individual name=value format lines. Leading whitespace is ignored, and anything after a semi-colon (;) is ignored, thus allowing comments.

There are 3 “sections” in the Key Retrieval configuration file for z/OS:

• The [ip] section specifies the network location(s) of the AKM server(s).

• The [timeout] section specifies a maximum time to wait while attempting a connection.

• The [cert] section specifies the client certificate used for secure communication with AKM.

Each section is marked by a line containing the section name in square brackets, thus: [ip], [timeout], [cert]. The sections can be in any order, and do not have to begin the line. (see Appendix C about possible issues with square brackets in the ISPF editor).

Within each section are one or more item lines, which are in the form of name=value. The names and possible values are described in detail for each section. There should be no spaces before or after the equals sign (=).

Unrecognized or malformed section or item lines are ignored; while this means that a bad line in the configuration file may not stop the key retrieval library from running, it may not give the expected results. If not connecting to the AKM server, the configuration file and key retrieval log (see LOGFILE section) should be reviewed.

The ip section contains one type of line which specifies an IP address and port number. The name KeyStoreIpPort is assigned an IP address and port number separated by a colon, for example:

[ip] 
KeyStoreIpPort=127.0.0.1:6000 

The timeout section contains a single line with a timeout value in seconds, which applies to each AKM server listed in the ip section.

Example:

[timeout] 
TimeoutSeconds=10 

The cert identifies the keyring, a password for the keyring, and a label for the client certificate in the keyring.

The KeyringName field is assigned a value which identifies the certificate/key database. The KeyringPassword field is for the password to access the keyring named in the KeyringName field. The Label field is assigned a label value given to the client certificate in the keyring.

Example:

[cert] 
KeyringName=/u/ibmuser/akm.kdb 
KeyringPassword=xyzzy 
Label=AKMCLIENT 

The cert section values and how to determine them are further described in the CERTIFICATES section of this document in connection with importing client certificates into the keyring.

Both the configuration file and certificate keyring are sensitive and should be secured using z/OS access control techniques, described in another section of this document.

The configuration file bundled with the library is a sample only, and must be edited with actual values for the specific installation.

Chapter 7: Log File

The key retrieval library produces logging output, to record the address of which server it connects with, whether timed out and connecting to an alternate server, and certain errors, if they occur.

This log output goes to the C standard error stream by default and can be controlled with the JCL that runs the job which uses the library. From JCL, this would be SYSOUT.

A DD statement could capture SYSOUT to a DSN, or to the JES output, or, if no log is wanted, a DD DUMMY statement could discard it entirely. Thus, to include the log in the job output:

//SYSOUT DD SYSOUT=* 

To save the log to a dataset (dataset name shown as example, any DSN can be used):

//SYSOUT DD DSN=AKM.ALLKYRTV.LOG(000001),DISP=SHR 

To discard the log:

// SYSOUT DD DUMMY 

For C programs, this output is distinct from the ‘standard out’ stream, which can be routed with SYSPRINT; for COBOL programs, see Appendix B for more detail on separating the program output from the logging output.

If capturing SYSOUT to a dataset, it must first be allocated; the Key Retrieval Library distribution does not include a dataset for logs. Although the log does not display passwords or key values, if retained in a dataset, it could be secured with the same RACF procedures described below for securing the configuration file.

Chapter 8: Access Control of Configuration File and Keyring

The keyring (.kdb) USS file which stores certificates and keys is critical for secure operation of the key retrieval client and communication with the AKM server, and should be managed with USS file permissions and/or RACF Access Control Lists to control access.

USS files are associated with an ‘owner’ and a ‘group’. These are logon account names (owner), and a set of logon accounts (group). File permissions can restrict or enable access to a file for read, write and execute, limiting or allowing for the file’s owner, a defined group of users, or all users.

The strictest policy would be to limit access only to the owner of the file. The owner would be the user logon when the file was created. Slightly less strict, but useful, would be to limit access to a group of users.

USS file permissions are expressed with triples of octal digits, with 0 for no permissions, and 7 for all. The order is owner, group, other. For example to allow only the owner full access, the value would be 700. To allow full access to everyone, 777. A common setting would be 740, giving the owner full control, members of the group id associated with the file read access, and denying all others all access.

Further detail on USS user and group administration is available online from IBM:

• https://publibz.boulder.ibm.com/cgi-bin/bookmgr_OS390/BOOKS/bpxza470/18.0?DT=20060602105904

Beyond USS file permission management, RACF can be used to further secure USS files. RACF settings can enable “Access Control Lists” that allow for very flexible administration of which users and groups can access both USS files and MVS datasets. With RACF ACL’s configured, unauthorized users cannot access keyring nor even the directory holding the keyring.

The AKM keyring comprises 2 related files: a .kdb file and a .rdb file of the same base name. The gskkyman tool will create both, and uses the .rdb file for internal housekeeping.

While it is recommended to set read only access for the .kdb file (after it has been created and configured with certificates), the .rdb file must have both read and write access. Furthermore, due to the nature of the USS file system, read and execute access must be set for the directory that the .kdb and .rdb files reside in.

As noted above, when first creating the keyring, a user with full privileges should run the gskkyman tool. This section applies to subsequently securing the keyring for users and jobs that will run applications which incorporate the Alliance Key Retrieval library.

A basic description is given here of protecting the USS keyring file; this is an example, actual names and settings would be chosen according to local policy and convention. Complete RACF usage is beyond the scope of this document, only those steps to illustrate the example are described here.

It is recommended that a group be configured which will contain any users running applications which incorporate the AKM key retrieval library. This group is named “AKM#GRP” for this example; again, local naming conventions may vary.

The AKM#GRP can be create from the main RACF menu, option 3 (Group Profiles and User connections), then option 1 (Add); the OMVS Parameters option should be selected, and on the next screen, a unique group ID assigned.

Users can be connected to the group also using the RACF menu option 3, then selecting sub menu option 4 (Connect). Initially set UACC to NONE; later specific ACL’s and dataset profiles will selectively allow fine-grained access.

Securing the keyring

Once the group and users have been configured, the settings for the actual keyring file can be set. A RACF class (FSSEC) setting enables USS file system security.

This uses the FSSEC attribute, reachable from the RACF menu option 5 (System Options). Then submenu option 3 (Class options); in this screen, enter YES next to the field marked SPECIFIC, to bring up a screen that maps specific class attributes. In the CLASS column enter FSSEC and in the ACTIVE column enter YES.

This is a global attribute, in that it will enable or disable the use of RACF file system security for all USS files. It can be disabled by entering NO in the ACTIVE column of this same screen.

With FSSEC enabled, the next step is to set Access Control List (ACL) values for the keyring files and directory. This example assumes the keyring to be in the USS directory /akm.

ACL settings for the USS file system can be managed with the ISHELL interface, reachable from the ISPF main menu option 6. At the prompt, type ISHELL, and in the entry area in the ISHELL screen, type a slash (/) representing the root directory of the USS file system, and press the Enter key. This shows a list of files and directories.

Tabbing to the /akm directory, enter an a in the entry field to the left, to bring up an action menu to manage attributes. Then use the Edit menu and select 8 for access control lists. Option 1 can add a group, and the Read and Execute access options should be enabled. Presuming that the .kdb and .rdb files have already been created and placed in this directory, it should not be necessary to grand Write access to the directory itself.

Then the individual files can be configured with the same technique. Back to the ISHELL interface, instead of a in the entry field next to the /akm directory, a slash (/), then the Enter key brings up the files in the directory.

The .kdb file should be set for Read access only, and the .rdb file both Read and Write.

At this point the keyring is enabled for the users in the AKM#GRP group. Other users not in the AKM#GRP will not be able to access the keyring.

Securing the configuration datatset

RACF can also be used to control access to MVS datasets. The AKR configuration file is an MVS dataset, and should be secured with RACF, as it contains sensitive information such as the keyring name and password. While there are some differences in using RACF to secure USS files versus MVS datasets, both involve managing User and Group profiles and permissions.

The actual dataset name for the configuration file is arbitrary, and is mapped in JCL with the DD name ZAKRINI. In the JCL samples bundled with the key retrieval library, the dataset AKM.AKRLIB.INI is used. Again, the DSN can be changed, although the record type should be fixed length format, but the DD name ZAKRINI must be used.

To manage access to the AKR configuration dataset AKM.AKRLIB.INI:

From the RACF main menu, option 1 (Dataset Profiles) is used. The profile name should be a mask to match the datasets of interest, in this case, the single dataset name: AKM.AKRLIB.INI (If desired, key retrieval log files could also be secured with these same techniques).

If the dataset is not yet “known” to RACF, a screen will show the owner and other settings; enter YES in the prompted field for Optional Information, then press Enter; on the next screen, tab to Access List and enter Yes, then press Enter key. (after the dataset profile has been defined, from the RACF menu 1, submenu 4 (access) will get to the next set of screens directly.)

Once the Profile name has been specified for the dataset to protect, pressing Enter brings up a screen with 3 options; option 1 will add user or group access rights. After selecting option 1, tab to the prompt field SPECIFY and enter YES, then press Enter, to bring up a screen that allows entry of a user or group name and the AUTHORITY for various access actions. To protect the AKM.AKRLIB.INI dataset, enter READ authority, then tab down to the area to enter the group name: AKR#GRP.

This will set read only access to this file for members of the AKM#GRP, and exclude other users. Additionally, RACF will audit unauthorized access attempts.

The above description does not completely cover all aspects of using RACF to define profiles, users, groups, and access rights, but is a simple overview of the type of steps to take. In an production environment, there will likely be administrative policies and conventions to follow, and a security administrator can adapt this example accordingly.

For further information on RACF user/group management:

• https://publibz.boulder.ibm.com/cgi-bin/bookmgr_OS390/BOOKS/BPXZB281/4.0?DT=20080125072750

Chapter 9: Installation

The Alliance Key Retrieval client for z/OS is distributed as a set of XMIT files and associated documentation. These XMIT files themselves are organized as members of a PDS, and another XMIT file contains that PDS.

The XMIT files, when restored with the RECEIVE command will contain the following:

The key retrieval library is a binary executable file, as a PDSE load module. A ‘side-deck’ file associated with the load module, allows for application code to link to the library.

The key retrieval library uses a (required) configuration file, and a sample configuration file is distributed. This sample file must be modified with actual production values; see the “CONFIGURATION FILE” section above for more details.

Several other datasets are also distributed with the library to support programming applications in C to use the library; these include a dataset with two C ‘header’ files and a C sample program that links to and calls the key retrieval library, and sample JCL to build and run that sample. Additional sample programs in COBOL are supplied, and the JCL to link and run those.

Dataset names in the JCL examples are based on an AKM qualifier. When unpacking the XMIT files this can be overridden with other dataset names; if so, the JCL should be modified accordingly.

The dataset: AKM.ZAKRLIB.XMIT contains the PDS whose members are individual XMIT files. Thus, to “unload” the distribution, first do a RECEIVE on AKM.ZAKRLIB.XMIT, then each member in turn should be RECEIVE‘d to reconstruct the individual datasets. Thus:

RECEIVE INDSNAME('AKM.ZAKRLIB.XMIT')

and at the prompt:

da('AKM.XMIT.AKRFILES')

This gives a PDS named AKM.XMIT.AKRFILES, containing the members:

_________ COBOLJCL (contains the JCL for the COBOL samples)
_________ COBOLSRC (contains the COBOL sample source code)
_________ DLLH (contains the header (".h") files for use in C applications that call the library)
_________ DLLIMPRT (contains the side-deck for applications to include when linking to the library)
__________DLLINI (contains a sample configuration file, which must be modified)
_________ DLLLOAD (contains the key retrieval library executable code, as a load module)
_________ USRCJCL (contains JCL to build the C sample pgm)
_________ USRCSRC (contains the source code of a C sample pgm)
_________ USRH (contains copies of the header files in the DLLH member)

Each of the members is itself an XMIT file, but not named as such, and should be unloaded with the RECEIVE command. For example, to unload the COBOL JCL, at the TSO command prompt:

RECEIVE INDSNAME('AKM.XMIT.AKRFILES(COBOLJCL)')

When prompted during the RECEIVE operation to “Enter restore parameters”, if the default parameters are accepted, the above XMIT would unload to a dataset with the logged on user id as the high level qualifier. If that user id was AKM, then the above would result in a PDS named: AKM.COBOL.JCL. The default dataset names, beginning with AKM.* can be overridden with another value, for example, the following will restore the JCL dataset to IBMUSER.COBOL.JCL:

da('IBMUSER.COBOL.JCL')

The above RECEIVE step should be done for each member in the AKM.XMIT.AKRFILES dataset after it has been RECEIVE‘d from the distribution XMIT file (AKM.ZAKRLIB.XMIT).

If the default datasets are overridden, as shown above, then it will be necessary to edit the JCL to change all references to datasets beginning with AKM to begin with IBMUSER.

Where to unload the XMIT files, and how to name the datasets is mostly arbitrary and can follow installation specific policies and conventions. Most of the dataset names referenced by the JCL can be changed, however the configuration file data definition must remain as: //ZAKRINI DD. The DSN itself can be changed. The member names of the AKM.DLL.H dataset should not be changed; if the dataset name itself is changed, also change the LSEARCH parameter in the compile step of the JCL for the C example.

Allocating load and object datasets

The distribution includes the executable binary Alliance Key Retrieval library as a load module in a PDSE, and several other datasets containing the library side-deck for linking applications, sample C and COBOL source code and JCL to compile, link and run the samples.

However, in order to run the JCL it will be necessary to allocate datasets to hold compiled object code and the linked load module(s). While the PDS which contains the library could be used to also hold an application load module, it is recommended to use a separate load module for applications which use the library.

The Appendix sections for the C and COBOL samples show example allocation parameters suitable for the small sample programs; actual size of the application datasets should be based on anticipated application needs.

Allocating logfile datasets

As noted in the LOGFILE section, the Key Retrieval Library distribution does not include a dataset to hold log output. If capturing the logging output from SYSOUT to a dataset, that dataset must be allocated first. A record length of 80 characters or more is recommended.

Appendix A: Using Allkeyrtv from C

The key retrieval interface comprises the function: AllKeyRtv(), which does not return a value directly, but sets a return code in a supplied pointer argument. Several other function arguments are also modified by the function, and are described as OUT arguments.

There are 3 significant IN arguments, which determine the key to be found and how the OUT key value will be formatted. Two arguments, the keysize and format arguments, are supplied to and modified by the function, although the expectation is that the returned value should match the original input value. The keysize argument is not a criteria for finding a key, but it must match the size of the key found, or the function will return an error code.

The complete list or arguments and their types:

unsigned char* pcaKeyName, /* IN: name of key to search for */
unsigned char* pcaKeyInstance, /*IN: instance of named key, if blank, the first key
that matches the keyname arg is returned */
unsigned long* pulKeySize, /* IN,OUT: keysize in bits, */
unsigned long* pulFormat, /* IN,OUT: returned key format */
unsigned char* pcaKey, /* OUT: returned key */
unsigned char* pcaInstanceUsed, /* OUT: returned key instance */
unsigned char* pcaExpiration, /* OUT: expiration date of key */
unsigned char* pcaLastChange, /* OUT: last change date of key */
unsigned long* pulReturn; /* OUT: return code 0=success, or err */

Note that all the arguments are pointers, although not all values are modified. It is the caller’s responsibility to allocate the memory for the OUT char* pointers, and the IN char* pointers should be blank filled.

The header file: zalkyrtv.h contains the AllKeyRtv() prototype and other definitions to aid in coding the calling arguments to the function, including the lengths of all the buffer (char*) arguments and valid values for the keysize and format arguments.

Possible error codes returned by AllKeyRtv() are in the header file zakrerr.h; each error has a #define constant and a comment with a brief descriptive string. Error codes returned in the final function argument (*pulReturn) are distinct from “error” response codes from the AKM server.

If the AKM server receives a request, it may return a response indicating an “error”, such as no key being found that meets the criteria, or other errors. For a full listing of AKM server errors, see the AKM Error Codes Reference.

The error codes in the zakrerr.h header represent error conditions in the calling of the key retrieval API itself, or communication errors, and a limited number of server error response codes.

The zalkyrtv.h and zakerrr.h headers are supplied as members of the AKM.DLL.H dataset to be used to compile client C code in the batch environment. The PDS qualified dataset name should be referenced in the C compiler option LSEARCH (see the C sample JCL).

A sample C program bundled with the library shows a key searched for by name, and some result fields displayed. An associated JCL file is supplied that builds and runs the C sample program.

The library itself is the (ALLKYRTV) member in the load module AKM.DLL.LOADLIB; this load module must be referenced, as shown, in the STEPLIB concatenation for the GO step of the job. The key retrieval library uses the native z/OS SystemSSL libraries, which run in a POSIX environment. Thus the PARM clause of the EXEC statement sets the POSIX runtime option. Without setting this POSIX runtime option, the program will abend.

There is a side-deck associated with the library, in the dataset AKM.DLL.IMPORTS(ALLKYRTV). This side deck, and the SystemSSL side-decks, SYS1.SIEASID(GSKSSL) and SYS1.SIEASID(GSKCMS31), should be referenced as shown in the pre-link step. The ALLKYRTV and SystemSSL library modules are referenced in the link step.

A convention used in the bundling of the library and datasets has the library itself, and associated side-deck and header files are in datasets named: AKM.DLL.* (see INSTALLATION section). The sample program source and JCL datasets follow the convention: AKM.USR*. Copies of the header files are also in AKM.USR.H, and this dataset is included in the LSEARCH compile option when compiling the sample C program.

The JCL references the Key Retrieval configuration file with a DD statement:

//ZAKRINI DD DSN=AKM.AKRLIB.INI,DISP=SHR

This DD name is required, while the DSN value is arbitrary. The sample configuration file is a sequential dataset, but any fixed length dataset can be used and assigned to the DD name ZAKRINI.

The SYSPRINT program output in the sample JCL as shown is routed to the job output. The SYSOUT output will contain the standard error stream, used by the Key Retrieval library for log output. The JCL shows the log routed to the job output also, or it could be saved to a dataset. The log output could also be discarded with DD DUMMY.

Allocating the C sample usr loadlib and object module datasets

The object module and loadlib datasets for the C samples are not included in the distribution and must be pre-allocated before running the samples.

Example allocation parameters are shown below; the actual allocation units and sizes may be adjusted as per production needs; the dataset organizations should be kept as shown.

Data Set Name . . . : AKM.USR.LOADLIB ...

Organization . . . : PO Current Utilization
Record format . . . : U Used pages . . . . : __
Record length . . . : 0 % Utilized . . . . : __
Block size . . . . : 4096 Number of members . : __
1st extent cylinders: 4
Secondary cylinders : 8

Data set name type : LIBRARY

Data Set Name . . . : AKM.USR.OBJECT ...
Organization . . . : PO Current Utilization
Record format . . . : FB Used pages . . . . :__
Record length . . . : 80 % Utilized . . . . : ___
Block size . . . . : 3200 Number of members . : ___
1st extent cylinders: 1
Secondary cylinders : 1	
Data set name type : LIBRARY

Appendix B: Using Allkeyrtv from Cobol

There are two COBOL samples bundled with the Key Retrieval library. The first is a standalone COBOL program that demonstrates a simple call to the library and displays results. Sample JCL to build and run this is also supplied.

Because the ALLKeyRtv API is based on pointer arguments, and the library modifies some of its arguments as a way to “return” values, the COBOL arguments are passed BY REFERNCE. See the details in Appendix A for API usage details; while C oriented, the description of the types and meaning of the arguments is still applicable.

The second COBOL program is a callable module, or sub-program, which can be called from other COBOL programs; again JCL is supplied to demonstrate this usage.

As with the C samples, the key retrieval side-deck must be referenced in the link step, and the key retrieval load module must be referenced in the STEPLIB concatenation of the GO step. Similarly, the configuration file dataset must be referenced in the GO step of the job with the DD name ZAKRINI; the actual DSN is arbitrary, but should be a fixed length record format.

Because the SystemSSL library requires the POSIX environment, any application using the Key Retrieval library must be executed with the POSIX runtime option. This can be done with inline CEEOPTS in the EXEC step of the job, and is shown in the COBOL JCL examples.

The Key Retrieval library’s log output can be managed with the SYSOUT DD statement, as with the C example, however the COBOL program’s DISPLAY output, by default, will also be routed to the same destination.

One way to separate the COBOL DISPLAY output is to direct it to SYSPUNCH in the COBOL source, and then route SYSPUNCH via a DD statement in the JCL to a dataset; this is shown in the COBOL example ALLKEYR.

Allocating the key retrieval COBOL loadlib and object module datasets

The AKM.COBOL.LOADLIB dataset in the COBOL JCL samples must be allocated. The members will be created by the running the JCL members in AKM.COBOL.JCL. A sample allocation could be based on the following:

Data Set Name . . . : AKM.COBOL.LOADLIB ... 

Organization . . . : PO Current Utilization 
Record format . . . : U Used pages . . . . : __ 
Record length . . . : 0 % Utilized . . . . : __ 
Block size . . . . : 4096 Number of members . : __ 
1st extent cylinders: 4 
Secondary cylinders : 8 
Data set name type : LIBRARY 

Allocation units and sizes may be adjusted for specific needs, but it is recommended to keep the dataset organization as shown.

Similarly, the AKM.COBOL.OBJECT dataset must be pre-allocated (again allocation units and extents adjustable):

Data Set Name . . . : AKM.COBOL.OBJECT ... 

Organization . . . : PO Current Utilization 
Record format . . . : FB Used pages . . . . : __ 
Record length . . . : 80 % Utilized . . . . : __ 
Block size . . . . : 3200 Number of members . : __ 
1st extent cylinders: 1 
Secondary cylinders : 1 
Data set name type : LIBRARY

Appendix C: Square Brackets and the ISPF Editor

Square bracket characters ( the [ and ] symbols) can be problematic in the ISPF editor, due to lack of standard code page definitions for these characters. This can impact C programming, since the square bracket characters are part of the array syntax. The Key Retrieval configuration file also uses square brackets for the section marker lines.

It may be advisable to edit C source and the configuration file in another editor and copy the file(s) to the appropriate datasets, if the right code-page cannot be loaded for the ISPF editor. See the following link for more information:

• https://x3270.bgp.nu/Brackets.html