IZ00548: ENCRYPTION KEY MANAGER DOCUMENTATION UPDATES

APAR status

• Closed as documentation error.

Error description

• Documentation Updates for Encryption Key Manger (EKM):
  
  1) On page 57 under Create a member in EKMSERV.ENCRYPT.CONFIG
     the shell script contains the following 3 lines:
  
     # Set JZOS specific options
     export ZZZZ="/ekmetc/JA0/KeyManagerConfig.properties"
     export XXXX="com.ibm.keymanager.KMSAdminCmd"
     export JZOS_MAIN_ARGS="$XXXX $ZZZZ"
  
     in the example ZZZZ is defined first, but used last on the
     JZOS_MAIN_ARGS line.  This is misleading and caused confusion
     for customers who specified it backwards leading to a non
     descriptive error.
  
     JVMJZBL2007E Stack trace follows:
     java.lang.ClassNotFoundException
     .at java.lang.Class.forName1(Native Method)
     .at java.lang.Class.forName(Class.java:180)
  
     The documentation should be updated as:
     # Set JZOS specific options export
     EKMCLASS="com.ibm.keymanager.KMSAdminCmd" export
     KEYFILE=
     "/ekmetc/JA0/KeyManagerConfig.properties.jce4758racfks"
     export JZOS_MAIN_ARGS="$EKMCLASS $KEYFILE"
  
  
  2)Current Documentation
    IBM Redbook:
    Tape Encryption: Planning, Implementation,
    and Usage Guide
    www.redbooks.ibm.com/cgi-bin/searchsite.cgi?query=SG24-7320-00
  
  
    IBM Encryption Key Manager component for the Java
    platform Introduction, Planning, and User's Guide
    GA76-0418-00
  
    http://publibfp.boulder.ibm.com/epubs/pdf/a7641800.pdf
  
  
  
    These documents do not discuss EKM's relationship with expired
    certificates.
  
    LOCAL FIX:
    Q. What happens when the certificate being used to encrypt
       the tapes,expires? Will EKM read previously encrypted
       tapes?
  
    A. EKM will not care if the certificate has expired.  It will
       continue to honor these certificates.
  
  
    Q. Will EKM require that a certificate be renamed on renewal?
  
    A. Because EKM will honor expired certificates, it does not
       require a renewal or a name change.  If the user does
       decide to renew the certificate, just the certificate
       alone (validity dates) would be renewed but not the
       associated keys.
  
  
    Q. Will later versions of EKM still read the encrypted tapes
       created with earlier versions of the software?
  
    A. Yes.  EKM will honor certificates regardless of release.
  
  
    Q. Does EKM perform any CRL (Certificate Revocation List)
       checking
  
    A. No, EKM does not perform any CRL checking
  
  
  
  
  
  3) Looking in the doc for IBM Encryption Key Manager component
     for the Java platform introduction, Planning, and User's
     Guide at:
     ftp://ftp.software.ibm.com/storage/Encryption/a7641803.pdf
  
     on page 55, the following is listed in a section labeled
     Quick Test running the EKM under USS
  
     Note: Unlike JCEKS and JCE4758KS, both JCE4758RACFKS and
     JCERACFKS require the -Djava.protocol.handler.pkgs
     parameters, which are defined differently for each as shown
     above.
  
     A customer running in production via a JZOS script had a
     problem because there is no mention of this requirement when
     running under JZOS.
  
     It would be helpful to include a section about adding the
     following:
  
     IJO="-Djava.protocol.handler.pkgs=com.ibm.crypto.provider" in
     the EKM2ENV file that yes it is required, when using a
     jceracfks keystore.
  
  
  4)  Also, with relation to certificates in general, EKM will NOT
      read a certificate with a NO-TRUST status.  To verify the
      status with RACF:  issue a RACDCERT LIST command to see the
      certificate.
  
  
      Please note, this will pertain to ACF2 or other security
      products as well.
  
  
  5)  If the filesystem fills up and can no longer be extended,
      EKM will continue to run without logging, however,
      a noticeable performance degredation may be encountered if
      the filesystem is an HFS.  If using ZFS, there should not
      be any change in performance.
  
  
  6)  Question:  Since RACF keyrings don't have a password, what
      should the following statements have coded for a password
      value?
  
      Answer:
      config.keystore.password = password
      TransportListener.ssl.keystore.password = password
      TransportListener.ssl.truststore.password = password
  
      Where password is literally, password
  
      OR
  
      Omit these three options altogether from the config file.
  

Local fix

• GA76-0418-03
  
  This APAR documents all changes to this version of the
  following doc
  
  IBM Encryption Key Manager
  
  Introduction, Planning, and User's Guide
  

Problem summary

•      EKM IPUG needs update to z/OS section on
  setting JZOS-specific options.
  

Problem conclusion

•  PROBLEM CONCLUSION: Pub corrected. New edition (GA76-0418-05)
  available through IBM pubs search at
  http://www.elink.ibmlink.ibm.com/publications/servlet/pbi.wss?CT
  Y=US
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

Fix information

Applicable component levels