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