KMEXIT

Synopsis

HELP:   Function name of FKME ['']
TYPE:   STRING
SYNTAX: KMEXIT/KMEEXIT/KMEFUC/KME/KMFUNC='str'

Description

z/OS

Activates the key management exit.

This user exit is an interface to a special (e.g. user written) key management system.

On encryption, parameters (KMPARM=...) are passed to the module. It returns a key for encryption of the FLAMFILE and a string up to 512 byte. These data are stored in the FLAMFILE as an user header (see parameter COMMENT or function FLMPUH).

On decryption, parameters (KMPARM=...) and the data stored in the user header are passed to the exit. The module returns the same key as on encryption.
It is up to the module, how to create a key and what kind of information are to be stored into the user header of the FLAMFILE. These data will help the module to find the correct key on decryption.

The exit is activated via the parameter KMEXIT=<name>. The user exit module must be contained in the library that has been assigned with the STEPLIB command (z/OS only).

Unix

This parameter -kmexit=[(]func[([lib])[exparm]][)] specifies a user exit routine for automatic key management.

With this parameter, FLAM is told the name of a function it has to invoke in order to receive a password needed for encryption or decryption of a file. This function must reside in a shared library (file type .so) the name of which may be specified after the function name. After the library name, an alphanumeric string may be appended that will be passed as a parameter string to the invoked function.

Windows

With the parameter kmexit the name of the procedure that is to be used from the library is specified for automatic key management.

Parameters in the same context: KMPARAMETER and KMDLL

Value

• z/OS
  • KMEXIT=name or KME=name of the module
    Max. 8 characters for name of the module, free choice.
    The module is loaded dynamically..
• Unix, FLAM command
  • -kmexit=exit specification
    • exit specification has the general form: [(]func[([lib])[exparm]][)]
    • With this parameter, FLAM is told the name of a function it has to invoke in order to receive a password needed for encryption or decryption of a file. This function must reside in a shared library (file type .so) the name of which may be specified after the function name. After the library name, an alphanumeric string may be appended that will be passed as a parameter string to the invoked function.

      func

      is the name of a function in a shared library that supplies the password (key) needed for en/decryption.

      lib

      is the name of a shared library (without the .so suffix) containing func. When lib is omitted, FLAM loads the function from libflamkm.so which it expects to find in directory $FLAM_PATH/../lib when that environment variable is defined, or otherwise in /usr/lib.
      Note: When entered in a shell command, each parenthesis must be preceded by an escape character (\) to avoid it being interpreted by the shell. Escape characters are not required in parameter Files.

      exparm

      is a sequence of up to 256 characters to be passed to the password function func. It must not contain space characters or parentheses. If it contains commas, the entire Exit specification must be enclosed in parentheses. exparm must always be preceded by a pair of parentheses which may be empty when lib is omitted.

• Unix, Programming Key Exit
  • -kmfunc
    The user exits for automatic key management can be activated via the subprogram interface flamup and - in contrast to the access exits - through the flam command, but not through the record interface flamrec. This user exit can be used at encryption or decryption to provide a password automatically. It is activated by the parameter -kmexit=exit specification in the flam command or in the parameter_string argument of the subprogram call flamup. The actual name used instead of kmfunc may be any valid function name. It sends a return code when it returns control to FLAM.
    • Syntax restrictions for FLAMv4 or older
      void kmfunc(signed long *functioncode,
            signed long *returncode,
            const unsigned long *parmlen,
            const unsigned char *param,
            unsigned long *datalen,
            unsigned char *data,
            unsigned long *ckylen,
            unsigned char *cryptokey,
            unsigned long *msglen,
            unsigned char *message);
      
    • Arguments
      • functioncode
        This argument transfers a function code to the user exit. The valid values are as follows:
        • -1 call for version identification
        • 0 call for decryption
        • 1 call for encryption
      • returncode
        The user exit sends a return code to FLAM with this argument; 0 = Success, otherwise Error.
      • parmlen
        When functioncode is 0 or 1, this argument contains the byte length of the data in the param argument. That may be an integer value between 0 and 256.
      • param
        When parmlen > 0, this argument contains the exparm- part of the exit specification in the -kmexit parameter.
      • datalen
        When functioncode is 0 or 1, this argument contains the byte length of the data in the data argument. That may be an integer value between 0 and 512. For calls for encryption, it is set by the exit routine. For calls for decryption, it is set by FLAM.
      • data
        When datalen > 0 with calls for encryption (functioncode 1), the exit routine returns here the data required for retrieving the password needed for decryption. FLAM stores these data in a user-specific FLAM file header. With calls for decryption (functioncode 0), FLAM returns here these data to the exit routine.
      • ckylen
        After a successful call to the exit routine with functioncode 0 or 1, this argument contains the byte length of the password returned to FLAM in the cryptokey argument. Maximum key length is 64 bytes.
      • cryptokey
        In this argument, FLAM receives after exit calls with functioncode 0 or 1 the password for encryption or decryption with the length specified in ckylen.
      • msglen
        Upon return to FLAM, this argument indicates the byte length of the string in the message argument. Maximum is 128 bytes.
      • message
        The exit routine may put here a message text which will be output to the log file by FLAM
• Windows
  • kmeexit=nameOfKmProcedure
    With the parameter kmexit the name of the procedure that is to be used from the library is specified.

Default

• No default value can be set for -kme user exit.

Valid for

• compression
• decompression