Security runtime environment variables

Environment variables can be defined in the current command shell by using the export command. Environment variables can also be defined in an environment variable (envar) file, which is processed during security runtime initialization. Any variables that are defined through the shell override the same variables in the envar file. The _EUV_ENVAR_FILE environment variable can be used to specify the location of the envar file. By default, the $HOME/envar file is used.

z/OS® generally sets environment variables in either /etc/profile (system-wide settings) or in $HOME/.profile (user-specific settings). Environment variables that are defined in either place override the same variables in the envar file.

The following environment variables are supported:
Table 1. Environment variables for security runtime
Environment Variable Explanation
_EUV_ENVAR_FILE Specifies the name of the file that contains environment variable definitions. If this variable is not set, the default is to use the envar file that is in the home directory (as specified by the _EUV_HOME or HOME environment variable). A data set name can be specified by preceding the data set name with '"//", and a DD name can be specified by preceding the DD name with"//DD:"

Each line of the file consists of the variable name followed by "=" followed by the variable value with no intervening blanks or other punctuation. The variable value consists of everything following the "=" up to the end of the line (including any trailing blanks). Any line beginning with "#" is treated as a comment line. A line can be continued by ending the line with "\".

The environment variables are not set until the first time that a function in the security runtime is called. Thus, it is useful for setting environment variables that are used by functions within the security runtime, although it can be used to set environment variables that are used by the application as well. In this case, the application should not rely on the environment variable values until after the security runtime is initialized.

The application can access these environment variables that use the getenv() function. The environment variables are maintained by the C runtime library, so they are not available to operating system functions.
_EUV_EXC_ABEND_DUMP Specifies whether a dump is to be generated when an abnormal termination occurs within the security runtime. This environment variable applies only to errors that are caught and processed by the security runtime. The default is to not take a dump if an abnormal termination occurs (the system can still take a dump if the exception percolates to the beginning of the condition handler stack without being handled). No dump is taken if _EUV_DUMP is set to 0 even if _EUV_EXC_ABEND_DUMP is set to enable a dump.
The following values can be specified for dump control:
  • 0 = No dump (default)
  • 1 = Dump only if no CATCH/CATCH_ALL was found to handle the exception
  • 2 = Dump only if no explicit catch clause was found to handle the exception (that is, the exception was caught by a CATCH_ALL clause)
_EUV_HOME The security runtime home directory is set to the value of this environment variable. If this variable is not specified, the HOME variable is used to determine the security runtime home directory. If the HOME variable is not set, the current directory is used.
_EUV_HW_CRYPTO Specifies whether the hardware Cryptographic Support is used. A value of 0 disables the use of the hardware support, and a value of 65535 enables the use of the hardware support. The hardware support is used if this environment variable is not defined. Integrated Cryptographic Service Facility (ICSF) must be configured and running before using the hardware Cryptographic Support.

Selected hardware cryptographic functions can be disabled by setting the appropriate bits to zero in the _EUV_HW_CRYPTO value. The corresponding software algorithms are used when a hardware function is disabled. For example, DES can be enabled and DES3 can be disabled by setting _EUV_HW_CRYPTO to 2.

The following bit assignments are defined:
  • 2 = DES encryption/decryption
  • 4 = DES3 encryption/decryption
  • 8 = AES128 encryption/decryption
  • 16 = AES256 encryption/decryption
Note: This environment variable has been deprecated.
_EUV_SEC_KRB5CCNAME_FILE Specifies the name of the file that is used to locate the default Kerberos credentials cache. If this variable is not set, the default is to use the krb5ccname file that is in the security runtime home directory (the home directory is specified by _EUV_HOME or HOME). Precede the data set name with"//" to specify an MVS data set name and precede the DD name with "//DD:" to specify an MVS DD name.
_EUV_SVC_DBG

Specifies subcomponents and levels for the debug messages. Debug messages for a particular subcomponent are not logged unless the subcomponent is included in the _EUV_SVC_DBG list and the debug message level is greater than or equal to the specified level. An asterisk (*) can be used to specify all subcomponents. Debug level 1 generates the minimum amount of debug output, debug level 8 generates the maximum amount of debug output, and debug level 9 generates data dumps in addition to the debug messages. The debug level must be an integer between 0 and 9. All debug messages are suppressed for a subcomponent when its debug level is 0.

The subcomponent list consists of a subcomponent name and a debug level that is separated by a period. Multiple subcomponents can be specified by separating the entries with commas. For example, 
_EUV_SVC_DBG=*.1,KRB_CCACHE.8
enables debug level 1 for all subcomponents and debug level 8 for the KRB_CCACHE subcomponent.
Note: IBM® does not recommend debug tracing to be running indefinitely due to potential performance impacts.
_EUV_SVC_DBG_FILENAME Specifies the fully qualified name of the file to receive debug messages. Debug messages are written to the file specified by the _EUV_SVC_STDOUT_FILENAME if this environment variable is not defined. If _EUV_SVC_STDOUT_FILENAME is not specified, debug messages are written to stdout.

The current process identifier is included as part of the trace file name when the name contains a percent sign (%). For example, if _EUV_SVC_DBG_FILENAME is set to /tmp/kerberos.%.out and the current process identifier is 247, then the file name is /tmp/kerberos.247.out.
_EUV_SVC_DBG_MSG_LOGGING Specifies whether debug messages are generated. The default is to suppress debug messages.
The following values can be specified:
  • 0 = Suppress debug messages
  • 1 = Write debug messages
_EUV_SVC_DUMP Specifies whether a dump is taken by the security runtime if a serious error is detected. This environment variable applies only to errors that are caught and processed by the security runtime. Error processing for errors that are handled by the Language Environment® (LE) runtime are controlled by the LE runtime options that are in effect at the time of the error.
The following values can be specified for this value:
  • 0 = No dump is taken. This suppresses dumps generated as a result of an exception as well as dumps requested by the security runtime. A dump can still be taken by the operating system depending upon the nature of the error.
  • 1 = A dump is taken (this is the default)
_EUV_SVC_MSG_FACILITY

Specifies the facility class for messages that are written to the system logging facility. The valid facility classes are: KERN, USER, MAIL, NEWS, UUCP, DAEMON, AUTH, CRON, LPR, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7. The default is USER.
_EUV_SVC_MSG_IDENTITY Specifies the identity string that is prefixed to messages written to the system logging facility. The default is SKRB.
_EUV_SVC_MSG_LEVEL Specifies the message level when logging messages. Messages that do not meet this criterion are suppressed. The default is to log all messages.
The following values can be specified:
  • FATAL - Only fatal messages are logged
  • ERROR - Only fatal and error message are logged.
  • USER - Only fatal, error, and user messages are logged
  • WARNING - Only fatal, error, user, and warning messages are logged
  • NOTICE - Only fatal, error, user, warning, and notice messages are logged
  • VERBOSE - All messages are logged.
_EUV_SVC_MSG_LOGGING Specifies the target where messages are logged. The default is to write informational messages to stdout and error messages to stderr.
The following values can be specified:
  • NO_LOGGING = Suppress all messages
  • STDOUT_LOGGING = Write all messages (informational and error) to stdout and also write error messages to stderr
  • STDERR_LOGGING = Write informational messages to stdout and error messages to stderr.
  • SYSTEM_LOGGING = Write all messages to the system logging facility (syslogd daemon).
_EUV_SVC_STDERR_FILENAME Specifies the fully qualified name of the file to receive standard error messages. Messages are written to stderr if this environment variable is not defined.

The current process identifier is included as part of the file name when the name contains a percent sign (%). For example, if _EUV_SVC_STDERR_FILENAME is set to /tmp/kerberos.%.out and the current process identifier is 247, then the file name is /tmp/kerberos.247.out.
_EUV_SVC_STDOUT_FILENAME Specifies the fully qualified name of the file to receive standard output messages. Messages are written to stdout if this environment variable is not defined.

The current process identifier is included as part of the file name when the name contains a percent sign (%). For example, if _EUV_SVC_STDOUT_FILENAME is set to /tmp/kerberos.%.out and the current process identifier is 247, then the file name is /tmp/kerberos.247.out.
GSS_CRL_CACHE_TIMEOUT Specifies the number of hours that a cached CRL remain valid. The valid timeout values are 0 - 720 and defaults to 24. A value of 0 disables the CRL cache.
GSS_KEY_LABEL Specifies the label of the key that is used to authenticate the application. The default key is used if a key label is not specified.
GSS_KEYRING_NAME Specifies the name of the key database ZFS file or the SAF key ring. A key database is used if the GSS_KEYRING_PW or GSS_KEYRING_STASH environment variable is also specified. Otherwise, a SAF key ring is used. The SAF key ring name is specified as "userid/keyring". The current user ID is used if the user ID is omitted. The user must have READ access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class when using a SAF key ring owned by the user. The user must have UPDATE access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class when using a SAF key ring owned by another user. Certificate private keys are not available when using a SAF key ring owned by another user.
GSS_KEYRING_PW Specifies the password for the key database.
GSS_KEYRING_STASH Specifies the name of the key database password stash file. The stash file name always has an extension of ".sth" and the supplied name is changed if it does not have the correct extension. The GSS_KEYRING_PW environment variable is used instead of the GSS_KEYRING_STASH environment variable if it is also specified.
GSS_LDAP_PASSWORD Specifies the password to use when connecting to the LDAP server. This environment variable is ignored if the GSS_LDAP_USER environment variable is not defined.
GSS_LDAP_PORT Specifies the LDAP server port. Port 389 is used if no LDAP server port is specified.
GSS_LDAP_SERVER Specifies one or more blank-separated LDAP server host names. Each host name can contain an optional port number that is separated from the host name by a colon. The LDAP server is used to obtain CA certificates when validating a certificate and the local database does not contain the required certificate. The local database must contain the required certificates if no LDAP server is specified. Even when an LDAP server is used, root CA certificates must be found in the local database since the LDAP server is not a trusted data source. The LDAP server is also used to obtain certificate revocation lists.
GSS_LDAP_USER Specifies the distinguished name to use when connecting to the LDAP server. An anonymous connection is used if this environment variable is not defined.
KRB5CCNAME Specifies the default name for the credentials cache and is specified as "type:name." The supported types are FILE and MEMORY. The default credentials cache name is obtained from the credentials cache pointer file that is identified by the _EUV_SEC_KRB5CCNAME_FILE environment variable if the KRB5CCNAME environment variable is not set.
KRB5RCACHEDIR Specifies the default replay cache directory and defaults to /tmp.
KRB5RCACHENAME Specifies the default replay cache name. The Kerberos runtime generates a replay cache name if the KRB5RCACHENAME environment variable is not defined.
KRB5RCACHETYPE Specifies the default replay cache type and defaults to dfl.
KRB5_CONFIG Specifies one or more configuration file names that are separated by colons. The default configuration file is /etc/skrb/krb5.conf.
KRB5_KTNAME Specifies the default key table name. The default key table name is obtained from the default_keytab_name configuration file entry if the KRB5_KTNAME environment variable is not defined. The default key table is /etc/skrb/krb5.keytab if no configuration file entry is found.
KRB5_SERVER_KEYTAB If this environment variable is set to 1, the gss_accept_sec_context() and krb5_rd_req() routines use a local instance of the Kerberos security server to decrypt service tickets instead of obtaining the key from a key table. The application must have at least READ access to the IRR.RUSERMAP facility to use this capability.

The Kerberos principal that is associated with the current system identity must be the same as the Kerberos principal in the service ticket. The key table is used if the Kerberos principal for the system identity is not the same as the Kerberos principal for the service ticket.

If this environment variable is set to 2, the behavior is the same as if it was set to 1 except for the following:
  1. The application does not need access to the IRR.RUSERMAP facility.
  2. The current system identity must have one of the following:
    1. Its associated principal matches the Kerberos principal in the service ticket.
    2. READ access in the KERBLINK class to the Kerberos principal in the service ticket.
  3. A key table is not to be used even if the call to the local instance of the Kerberos security server fails.