IBM Security Key Lifecycle Manager for z/OS, Version 1.1

Using Metadata

The Security Key Lifecycle Manager for z/OS must be configured to create an XML file that captures vital information as data is being encrypted and written to tape. This file can be queried by volume serial number to display the alias or key label that was used on the volume. Conversely, the file can be queried by alias to display all volumes associated with that key label/alias.
Note: If you do not configure a metadata file, the Security Key Lifecycle Manager for z/OS does not start.
As encryption processing is performed, the Security Key Lifecycle Manager for z/OS collects the following data:

When the collected data reaches a certain limit, it is written to an XML file. The default limit, which can be set in the Security Key Lifecycle Manager for z/OS properties file (ISKLMConfig.properties.zos), is 100 records. Once the file is written, it can be queried as long as the Security Key Lifecycle Manager for z/OS is running. To prevent the file from growing too large, it is automatically rolled over to a new file after a maximum file size is reached. The default maximum file size for rollover, which can also be set in the Security Key Lifecycle Manager for z/OS properties file, is 1 MB. Only a current and a previous file version is saved. The values to set in the Security Key Lifecycle Manager for z/OS configuration properties file are:

Audit.metadata.file.name
Name of XML file where metadata is saved. This configuration is required.
Audit.metadata.file.size
The maximum file size. This is specified in kilobytes, before rolling the file over from current to previous version. This configuration is optional. The default is 1024 (1MB).
Audit.metadata.file.cachecount
The number of records to be cached before writing the metadata file. This configuration is optional. The default is 100.

XML File Format

The file contains records in the following format.

<KeyUsageEvent>
<DriveSSN>FVTDRIVE0000</driveSSN> -Drive Serial Number
<VolSer>TESTER</volSer> -Volume Serial
<DriveWWN>57574E414D453030</driveWWN> -drive WWN
<keyAlias2>cert2</keyAlias2> -Key Alias1
<keyAlias1>cert1</keyAlias1> - keyAlias2
<dateTime>Tue Feb 20 09:18:07 CST 2007</dateTime> - creation date
</KeyUsageEvent>

Note: For LTO Ultrium 4 and LTO Ultrium 5 drives there is only <keyAlias1></keyAlias1> record. The DKi is not recorded.

Querying the metadata XML file

Use the ISKLMDataParser tool to query the metadata file. This tool parses the XML file using Document Object Model (DOM) techniques and cannot be run from the Security Key Lifecycle Manager for z/OS command-line interface. It is invoked as follows:

java com.ibm.ltklm.tools.ISKLMDataParser -filename full_path_to_metadata_file {-volser volser | -keyalias alias}

metadata_path
This path is the same directory path specified for the metadata file in Audit.metadata.file.name in the ISKLMConfig.properties.zos file.
-filename
filename is required and must be the name of the XML metadata file. The name usually matches the name specified in theAudit.metadata.file.name property in the ISKLMConfig.properties.zos file.
-volser
The volume serial number of the tape cartridge you are searching for in the XML file. Either -volser or -keyalias must be specified.
-keyalias
The key label or alias you are searching for in the XML file. Either -volser or -keyalias must be specified.

Example

The metadata file name property in ISKLMConfig.properties.zos is set to a value of metadata. The file is located in your local directory where the Security Key Lifecycle Manager for z/OS runs. The following command would filter (display) only the XML records related to volser 72448:

<jvm_path>/bin/java com.ibm.ltklm.tools.ISKLMDataParser -filename metadata -volser 72448

The output would be formatted as follows:

Table 1. Metadata Query Output Format
keyalias1 keyalias2 volSer dateTime driveSSN dki
cert1 cert2 72448 Wed Mar 14 10:31:32 CDT 2007 FVTDRIVE0004  

Recovering from a corrupted metadata file

The Security Key Lifecycle Manager for z/OS metadata file can become corrupted if the Security Key Lifecycle Manager for z/OS is improperly shutdown. It can also be corrupted if the system where the Security Key Lifecycle Manager for z/OS is running crashes. Improper editing or modification of the metadata file can also corrupt it. The corruption is unnoticed until the ISKLMDataParser parses the metadata file. The ISKLMDataParser can fail with an error like the following:

[Fatal Error] EKMData.xml:17:16: The end-tag for element type "KeyUsageEvent" 
must end with a '>' delimiter.
org.xml.sax.SAXParseException: The end-tag for element type "KeyUsageEvent" 
must end with a '>' delimiter.
at org.apache.xerces.parsers.DOMParser.parse(Unknown Source)
at org.apache.xerces.jaxp.DocumentBuilderImpl.parse(Unknown Source)
at javax.xml.parsers.DocumentBuilder.parse(Unknown Source)
at com.ibm.ltklm.tools.ISKLMDataParser.getData(ISKLMDataParser.java:80)
at com.ibm.ltklm.tools.ISKLMDataParser.viewData(ISKLMDataParser.java:143)
at com.ibm.ltklm.tools.ISKLMDataParser.main(ISKLMDataParser.java:337)

If this error occurs, it is due to a missing XML ending tag for an element. The Security Key Lifecycle Manager for z/OS metadata file can be recovered to allow the ISKLMDataParser to parse the file again.

  1. Make a backup copy of the Security Key Lifecycle Manager for z/OS metadata file.
  2. Edit the Security Key Lifecycle Manager for z/OS metadata file.
  3. In XML, there should be an initial tag and a corresponding ending tag for each piece of data or event.
    • Some examples of an initial tag:
      • <KeyUsageEvent>
      • <driveSSN>
      • <keyAlias1>
    • Some examples of an ending tag:
      • </KeyUsageEvent>
      • </driveSSN>
      • </keyAlias1>
  4. Scan the file and look for unmatched tags. The error message from the ISKLMDataParser lists which tag is missing its ending tag.
  5. When an unmatched tag is found, temporarily delete the event or add the necessary tags to complete the event.
    • The following excerpt from a Security Key Lifecycle Manager for z/OS metadata file shows a first KeyUsageEvent that has no ending tag:
      <KeyUsageEvent>
<driveSSN>001310000109</driveSSN>
<volSer>      </volSer>
<driveWWN>5005076312418B07</driveWWN>
<keyAlias1>key00000000000000000F</keyAlias1>
<dki>6B657900000000000000000F</dki>
<dateTime>Thu Aug 30 09:50:53 MDT 2007</dateTime>
<KeyUsageEvent>
<driveSSN>001310000100</driveSSN>
<volSer>      </volSer>
<driveWWN>5005076312418ABB</driveWWN>
<keyAlias1>key000000000000000000</keyAlias1>
<dki>6B6579000000000000000000</dki>
<dateTime>Thu Sep 06 16:49:39 MDT 2007</dateTime>
</KeyUsageEvent>
      Adding a </KeyUsageEvent> between the lines <dateTime>Thu Aug 30 09:50:53 MDT 2007</dateTime> and <KeyUsageEvent> would complete the first <KeyUsageEvent>.

Repairing the file corruption allows the ISKLMDataParser to successfully parse the data.


Feedback