= FKME - User Manual

limes datentechnik gmbh <support@flam.de> +
v5.1.27, 2022-07-29: +
release. +
 +
 +
 +
 +
Frankenstein Limes Key Management Extension (FKME) +
Copyright (C) limes datentechnik (R) gmbh +
All rights reserved
 +
 +
 +
 +

.Abstract

libfkme joins all FKME implementations of limes datentechnik into one
library. For each supported specification (FINPIN, KMIP, PGP) several
implementations (Software (SWE), PKCS#11 (P11), IBM CCA) are available.
This document describes all the currently available FKME functions.

The FLAM Key Management Extension (FKME) is a service provider interface
to integrate FLAM4 into different cryptographic infrastructures.

.Trademarks

Below, you can find all trademarks or registered trademarks of limes
datentechnik (R) gmbh. These trademarked terms are marked with the
appropriate symbol ((R) or (TM)), indicating registered or common law
trademarks owned by limes datentechnik (R) gmbh at the time this
information was published. The following terms are trademarks of
limes datentechnik (R) gmbh in Germany, other countries, or both:

* LIMES(R)     - Short company name of the owner of this document
* limes datentechnik(R) - Company name of the owner of this document
* FLCL(R)      - Frankenstein Limes Command Line
* FLCC(R)      - Frankenstein Limes Control Center
* FLAM(R)      - Frankenstein Limes Access Method
* FLUC(R)      - Frankenstein Limes Universal Converter
* FLIES(R)     - Frankenstein Limes Integrated Extended Security
* FKMS(R)      - Frankenstein Key Management System
* FKME(R)      - Frankenstein Key Management Extension/Exit
* FLAMFILE(R)  - A file based on FLAM syntax
* CLE/P(R)     - Command line Executer/Parser

.License terms

The license terms for all software components owned by limes datentechnik gmbh(R)
can be found in LICENSE(.txt) in the installation folder doc/txt or in the
partitioned dataset HLQ.FLAM.DOCTXT. Additional license information for
external libraries used by this software can be found in ABOUT(.txt).
The replacement of external libraries (LGPL) is described following the
changelog in the file README(.txt). All license terms of the external
libraries are included as files (LICxxxxx(.txt)) in doc/txt folder
or in HLQ.FLAM.DOCTXT partitioned dataset.

All old FLAM components till version 4 are completely owned by limes
datentechnik gmbh (R). Only on Linux systems the glibc is used in
unmodified form as prerequisite (part of the operating system, not part
of the distribution) based on the LGPL license. The old FLAM4 components
don't provide additional about and version commands or functions.

The service provider interfaces (exits, extensions) of FLAM are owned
completely by limes datantechnik gmbh(R) and provided to our users for
individual extension to this software. The driver is conforming to this
license terms but LIMES(R) is not responsible for such individual
implementations which are not part of our distributen. Our own
implementations against these SPIs (e.g. FAVECAV, PKCS#11, IBM-CCA/ICSF)
are in sync with the stated license terms here.

A lot of this information is generated in the package build process
and can be requested over the corresponding built-in commands of our
utilities or the corresponding functions of the APIs. To request
the current valid state, please use the command or functions below
(there are more APIs with analog functions available):

------------------------------------------------------------------------
 COMMAND            API 1      API 2      ...   API n
 > fkme license   fcblic()   FCRLIC()   ...   fliconv_license()
 > fkme about     fcbabo()   FCRABO()   ...   fliconv_about()
 > fkme version   fcbvsn()   FCRVSN()   ...   fliconv_version()
------------------------------------------------------------------------

The about and version information are also added as appendix to the
manual's provided by limes datentechnik gmbh(R).

The version information contains version, release and revision number of
each component followed by the current build number. The versioning of
the different components is independent of each other. The build number
must be the same for each component and must correspond to the build
number of the installation package. If the build number is not identical
for all compiled and linked components, then the installation is wrong. 

== Preface

The FKME parameter list is parsed based on the CLE/P library. The CLE/P
library was developed by limes datentechnik and released as open source
under the ZLIB license.
CLE/P is a compiler to provide a platform-independent command line
interface for each kind of batch processing environment.

The CLE/P library provides a lot of features, including help and
documentation. For example: We use this library to automatically
create this document as part of our build process. If we add a
parameter to the CLE/P tables and build the FL5 project, this
manual will be regenerated as well in order to be always up to date.

This manual is generated with the INFO command of FLCL provided by
CLE/P library by calling the command below:

-----------------------------------------------------------------------
   flcl info get.fkme(docu) output=fkmebook.txt
-----------------------------------------------------------------------

== FKME overview

The FLAM key-management extension (FKME) links between FLAM's
cryptographic protection mechanisms (privacy, integrity, completeness),
various cryptographic infrastructures (KMIP, x509-PKI, FINPIN, ...), and
various architectures of hardware security modules (HSM (IBM-CCA/ICSF,
PKCS#11, ...)) in order to provide a professional key management where
access to data can be controlled. Of course, FLAM also supports
protection by a simple passphrase or an internal constant as key, but
professional solutions are implemented by means of this service provider
interface which has been available since FLAM version 4.

.Benefits

* Use of existing cryptographic infrastructures for protecting "flam'd" data
* Processes for key management and permission granting can be re-used
* Top security due to support of various hardware security modules (HSM)
* No downstream costs caused by encryption (reuse of key management)
* Compliance with security requirements and standards (PCI DSS)

.Implementation

The following FLAM4-based solutions are currently available:

* FIN/PIN Symmetric Key Infrastructure for data exchange
** PKCS#11 HSM or soft tokens
** IBM-CCA-based HSM (inclusive ICSF on z/OS)
** Reference implementation in software
* FKMESTD0 Default FKME providing the default passphrase
* FKMEFILE Reads the key value (passphrase) from a file

The FIN/PIN implementation for PCI DSS is a specification for secure
ordering of debit and credit cards that relies on the existing
cryptographic infrastructure for the Financial-PIN-Support. For this,
there exist two different specifications: one for triple-DES and one for
AES which exists in two versions (transfer and storage).

The following FKMEs are planned as part of the FLAM5 project:

* OpenPGP keyrings
* x509 public key infrastructure
* KMIP (Key-Management-Interoperability-Protocol)

In various other projects, customers have developed their own
specifications and implemented their own solutions.


== The use of FKME in FLAM

This chapter describes the usage of FKMEs developed by limes
datentechnik. Calling custom developed FKME works in the same way, but
mostly has another structure for the FKME parameter string. The FLAM
subsystem on ZOS has special LE-less FKMEs developed in assembler,
implementing the FIN/PIN specification against ICSF (FKMECCAx). These
load modules are still available and must be used with the subsystem.
'libfkme' is an LE-based DLL and cannot be used with this environment.
The parameter string of FKMECCAx differs from the 'libfkme' parameter
string of function SYMNCCA, but it does the same thing. Documentation
for the FKMECCAx load modules can be found in the FLAM4 user manual.

To call a simple load module on ZOS, only the function name must be
specified. To call a function of 'libfkme' on ZOS, the library name of
the DLL and function name must be specified. On other platforms (Windos,
UNIX), the default library name is 'libfkme' and the default function
name is 'FKMESTD0', which is also the default function name on z/OS.

NOTE: In some environments, you have to escape quotation marks of the FKME
parameter string with backslashes: \\".
------------------------------------------------------------------------
   KMPAR='...\"....\"...'
------------------------------------------------------------------------


== FKME FUNCTION FKMESTD0

FKME function FKMESTD0 is an FKME using the default password/key and
needs no parameter. This FKME is called if no other function is defined.

.Example

-----------------------------------------------------------------------
...kml=libfkme kmf=FKMESTD0...
-----------------------------------------------------------------------


== FKME FUNCTION SYMNP11

FKME function SYMNP11 is an FKME which uses the PKCS#11 secure token
interface to implement the FINPIN-based specification for PCIDSS conform
data exchange. Currently, it supports two variants: AES (with SHA-256)
and 3DES/TDES (with SHA-1).

This FKME function can be used with several PKCS#11 conform crypto
devices on Windows / Unix platforms or EP11 on ZOS. The specification
was designed for PCI DSS conform ordering of credit cards and to exchange
other card holder data in a secure and PCI DSS conform manner.

The specification can be found at:

https://www.flam.de/en/technology/download/documentation/

On ZOS, this FKME is available (like on all other platforms) as function
of the LIBFKME DLL and also as separate load module 'SYMNP110'.


=== libfkme.SYMNP11.ENC 'PKCS11'
.Synopsis

-----------------------------------------------------------------------
HELP:   FKME PKCS11 parameter for symmetric encryption
PATH:   limes.FKME
TYPE:   OBJECT
SYNTAX: > FKME PKCS11(LIBRARY='str',SLOT=num,PIN='str',ALGO=AES/TDES,LABEL='str',TEMPLATE='str',KEYLENGTH=num/KL16/KL24/KL32)
-----------------------------------------------------------------------

.Description

Parameter of FKME library libfkme function SYMNP11 for encryption.

.Example

-----------------------------------------------------------------------
...kml=libfkme kmf=SYMNP11 kmp="pkcs11(library=p11lib slot=0 pin=1234 ALGO=AES label=FKME4711 template=FKME++** KEYLENGTH=16)"...
-----------------------------------------------------------------------


.Arguments

* `STRING: LIBRARY='str' - PKCS11 library name (CRYPTOKI DLL/SO)`
* `NUMBER: SLOT=num - Slot number of PKCS11 token [0]`
* `STRING: PIN='str' - PKCS11 pin for authentication`
* `NUMBER: ALGO=AES/TDES - Algorithm used by FKME [TDES]`
** `AES - AES algorithm`
** `TDES - Triple DES (3DES) algorithm`
* `NUMBER: KEYLENGTH=num/KL16/KL24/KL32 - Key length of FMKY [KL16]`
** `KL16 - 128 Bit AES / 112 Bit TDES`
** `KL24 - 192 Bit AES / 168 Bit TDES`
** `KL32 - 256 Bit AES`

==== Parameter 'LABEL'
.Synopsis

-----------------------------------------------------------------------
HELP:   PKCS11 key label
PATH:   PKCS11
TYPE:   STRING
SYNTAX: LABEL='str'
-----------------------------------------------------------------------

.Description

The fully qualified label is only required to reference the correct key
value on write. It must contain a generation and version (2 hex digits
each) which are determined based on the key label template.


==== Parameter 'TEMPLATE'
.Synopsis

-----------------------------------------------------------------------
HELP:   PKCS11 key label template
PATH:   PKCS11
TYPE:   STRING
SYNTAX: TEMPLATE='str'
-----------------------------------------------------------------------

.Description

The FKME template is used on write to determine the generation and
version from a key label.

The replacement characters below are defined:

------------------------------------------------------------------------
   Generation '++'
   Version    '**'
------------------------------------------------------------------------

All other characters of the label can be substituted by '%', to define
the position of generation and version in the label. The remaining
characters must correspond to those in the label.

For example:

------------------------------------------------------------------------
   TEMPLATE='TFMKY.%%%%%%%%.%%%%%%%%.DAT0++**'
------------------------------------------------------------------------

On read, only a key label template must be provided. The generation (**)
and version (++) is filled in by the FKME. The wildcard '%' is not
allowed.

------------------------------------------------------------------------
   TEMPLATE='TFMKY.BV000000.GUD00000.DAT0++**'
------------------------------------------------------------------------

If the label is for example:

------------------------------------------------------------------------
   LABEL='TFMKY.BV000000.GUD00000.DAT04711'
------------------------------------------------------------------------

then the generation is 47 and the version is 11.


=== libfkme.SYMNP11.DEC 'PKCS11'
.Synopsis

-----------------------------------------------------------------------
HELP:   FKME PKCS11 parameter for symmetric decryption
PATH:   limes.FKME
TYPE:   OBJECT
SYNTAX: > FKME PKCS11(LIBRARY='str',SLOT=num,PIN='str',TEMPLATE='str')
-----------------------------------------------------------------------

.Description

Parameter of FKME library libfkme function SYMNP11 for decryption.

.Example

-----------------------------------------------------------------------
 ...kml=libfkme kmf=SYMNP11 kmp="pkcs11(library=cryptoky slot=0 pin=1234 template=FKME++**)"...
-----------------------------------------------------------------------


.Arguments

* `STRING: LIBRARY='str' - PKCS11 library name (CRYPTOKI DLL/SO)`
* `NUMBER: SLOT=num - Slot number of PKCS11 token[0]`
* `STRING: PIN='str' - PKCS11 pin for authentication`

==== Parameter 'TEMPLATE'
.Synopsis

-----------------------------------------------------------------------
HELP:   PKCS11 key label template
PATH:   PKCS11
TYPE:   STRING
SYNTAX: TEMPLATE='str'
-----------------------------------------------------------------------

.Description

The FKME template is used on write to determine the generation and
version from a key label.

The replacement characters below are defined:

------------------------------------------------------------------------
   Generation '++'
   Version    '**'
------------------------------------------------------------------------

All other characters of the label can be substituted by '%', to define
the position of generation and version in the label. The remaining
characters must correspond to those in the label.

For example:

------------------------------------------------------------------------
   TEMPLATE='TFMKY.%%%%%%%%.%%%%%%%%.DAT0++**'
------------------------------------------------------------------------

On read, only a key label template must be provided. The generation (**)
and version (++) is filled in by the FKME. The wildcard '%' is not
allowed.

------------------------------------------------------------------------
   TEMPLATE='TFMKY.BV000000.GUD00000.DAT0++**'
------------------------------------------------------------------------

If the label is for example:

------------------------------------------------------------------------
   LABEL='TFMKY.BV000000.GUD00000.DAT04711'
------------------------------------------------------------------------

then the generation is 47 and the version is 11.




== FKME FUNCTION SYMNCCA

FKME function SYMNCCA, is an FKME which uses IBM CCA (Common
Cryptographic Architecture (ICSF on ZOS)) to implement the FINPIN based
specification for PCI DSS conform data exchange. Currently, it supports
two variants: AES (with SHA-256) and 3DES/TDES (with SHA-1).

This FKME function can be used with ICSF on ZOS or IBM47xx Cryptocards
on Windows or UNIX platforms. The specification was designed for PCI DSS
conform ordering of credit cards and to exchange other card holder data
in a secure and PCI DSS conform manner.

The specification can be found at URL below:

https://www.flam.de/en/technology/download/documentation/

For ICSF, the library to find the callable services must not be
specified because all functions are simple load modules in the dataset
'CSF.SCSFMOD0'. These modules are fetched by 'libfkme'. If you would
specify a library name, 'libfkme' would try to load a ZOS-DLL, which
would not work. To fetch the ICSF service routines, the 'CSF.SCSFMOD0'
library must be in the STEPLIB concatenation for the program.

The default library name for SAPI on windows is 'csunsapi' and on UNIX
systems 'libcsulsapi'. The directory for this DLL/SO must be defined in
the library path environment variable.

On ICSF-based CCA systems (z/OS), authentication against the CCA HSM is
not possible. For such an environment, please don't use the userid and
passphrase login. On other systems, the userid and passphrase are
optional. If you don't provide them, the default role is used.

On ZOS, this FKME is available (like on all other platforms) as a
function of the LIBFKME DLL and additionally as separate load module
'SYMNCCA0'.


=== libfkme.SYMNCCA.ENC 'CCA'
.Synopsis

-----------------------------------------------------------------------
HELP:   FKME CCA/ICSF parameter for symmetric encryption
PATH:   limes.FKME
TYPE:   OBJECT
SYNTAX: > FKME CCA(LIBRARY='str',USERID='str',PASSWORD='str',ALGO=AES/TDES,LABEL='str',TEMPLATE='str',KEYLENGTH=num/KL16/KL24/KL32,CLEARKEY/C)
-----------------------------------------------------------------------

.Description

Parameter of FKME library libfkme function SYMNCCA for encryption.

.Example

-----------------------------------------------------------------------
...kml=libfkme kmf=SYMNCCA kmp="cca(library=csunsapi user=smith password=1234 ALGO=AES label=FKME4711 template=FKME++** KEYLENGTH=16)"...
-----------------------------------------------------------------------


.Arguments

* `STRING: LIBRARY='str' - CCA library name (SAPI DLL/SO or empty for ICSF)`
* `STRING: USERID='str' - User ID for authentication [optional]`
* `STRING: PASSWORD='str' - Password for authentication [optional]`
* `NUMBER: ALGO=AES/TDES - Algorithm used by FKME [TDES]`
** `AES - AES algorithm`
** `TDES - Triple DES (3DES) algorithm`
* `NUMBER: KEYLENGTH=num/KL16/KL24/KL32 - Key length of FMKY [KL16]`
** `KL16 - 128 Bit AES / 112 Bit TDES`
** `KL24 - 192 Bit AES / 168 Bit TDES`
** `KL32 - 256 Bit AES`
* `SWITCH: CLEARKEY/C - Allow clear key operations (ICSF only) [FALSE]]`

==== Parameter 'LABEL'
.Synopsis

-----------------------------------------------------------------------
HELP:   CCA key label
PATH:   CCA
TYPE:   STRING
SYNTAX: LABEL='str'
-----------------------------------------------------------------------

.Description

The fully qualified label is only required to reference the correct key
value on write. It must contain a generation and version (2 hex digits
each) which are determined based on the key label template.


==== Parameter 'TEMPLATE'
.Synopsis

-----------------------------------------------------------------------
HELP:   CCA key label template
PATH:   CCA
TYPE:   STRING
SYNTAX: TEMPLATE='str'
-----------------------------------------------------------------------

.Description

The FKME template is used on write to determine the generation and
version from a key label.

The replacement characters below are defined:

------------------------------------------------------------------------
   Generation '++'
   Version    '**'
------------------------------------------------------------------------

All other characters of the label can be substituted by '%', to define
the position of generation and version in the label. The remaining
characters must correspond to those in the label.

For example:

------------------------------------------------------------------------
   TEMPLATE='TFMKY.%%%%%%%%.%%%%%%%%.DAT0++**'
------------------------------------------------------------------------

On read, only a key label template must be provided. The generation (**)
and version (++) is filled in by the FKME. The wildcard '%' is not
allowed.

------------------------------------------------------------------------
   TEMPLATE='TFMKY.BV000000.GUD00000.DAT0++**'
------------------------------------------------------------------------

If the label is for example:

------------------------------------------------------------------------
   LABEL='TFMKY.BV000000.GUD00000.DAT04711'
------------------------------------------------------------------------

then the generation is 47 and the version is 11.


=== libfkme.SYMNCCA.DEC 'CCA'
.Synopsis

-----------------------------------------------------------------------
HELP:   FKME CCA/ICSF parameter for symmetric decryption
PATH:   limes.FKME
TYPE:   OBJECT
SYNTAX: > FKME CCA(LIBRARY='str',USERID='str',PASSWORD='str',TEMPLATE='str',CLEARKEY/C)
-----------------------------------------------------------------------

.Description

Parameter of FKME library libfkme function SYMNCCA for decryption.

.Example

-----------------------------------------------------------------------
...kml=libfkme kmf=SYMNCCA kmp="cca(library=libcsufsapi user=smith password=1234 template=FKME++**)"...
-----------------------------------------------------------------------


.Arguments

* `STRING: LIBRARY='str' - CCA library name (SAPI DLL/SO or empty for ICSF)`
* `STRING: USERID='str' - User ID for authentication [optional]`
* `STRING: PASSWORD='str' - Password for authentication [optional]`
* `SWITCH: CLEARKEY/C - Allow clear key operations (ICSF only) [FALSE]]`

==== Parameter 'TEMPLATE'
.Synopsis

-----------------------------------------------------------------------
HELP:   CCA key label template
PATH:   CCA
TYPE:   STRING
SYNTAX: TEMPLATE='str'
-----------------------------------------------------------------------

.Description

The FKME template is used on write to determine the generation and
version from a key label.

The replacement characters below are defined:

------------------------------------------------------------------------
   Generation '++'
   Version    '**'
------------------------------------------------------------------------

All other characters of the label can be substituted by '%', to define
the position of generation and version in the label. The remaining
characters must correspond to those in the label.

For example:

------------------------------------------------------------------------
   TEMPLATE='TFMKY.%%%%%%%%.%%%%%%%%.DAT0++**'
------------------------------------------------------------------------

On read, only a key label template must be provided. The generation (**)
and version (++) is filled in by the FKME. The wildcard '%' is not
allowed.

------------------------------------------------------------------------
   TEMPLATE='TFMKY.BV000000.GUD00000.DAT0++**'
------------------------------------------------------------------------

If the label is for example:

------------------------------------------------------------------------
   LABEL='TFMKY.BV000000.GUD00000.DAT04711'
------------------------------------------------------------------------

then the generation is 47 and the version is 11.




== FKME FUNCTION SYMSWE

FKME function SYMSWE is an FKME which simulates the symmetric PKCS#11 or
CCA implementations. You can define the secret key as clear value.
Currently it supports two variants: AES (with SHA-256) and 3DES/TDES
(with SHA-1).

NOTE: This FKME function extists only for testing purposes. Don't
      use clear key values in production.

On ZOS, this FKME is available (like on all other platforms) as function
of the LIBFKME DLL and also as separate load module 'FKMESWE0'.


=== libfkme.SYMSWE.ENC 'SWE'
.Synopsis

-----------------------------------------------------------------------
HELP:   FKME software emulation parameter
PATH:   limes.FKME
TYPE:   OBJECT
SYNTAX: > FKME SWE(ALGO=AES/TDES,KEY='str',GENERATION='str',VERSION='str')
-----------------------------------------------------------------------

.Description

Parameter of FKME library libfkme function SYMSWE for encryption.

.Example

-----------------------------------------------------------------------
...kml=libfkme kmf=SYMSWE kmp="SWE(ALGO=AES KEY=0123456789abcdeffedcba9876543210)"...
-----------------------------------------------------------------------


.Arguments

* `NUMBER: ALGO=AES/TDES - Algorithm used by FKME [TDES]`
** `AES - AES algorithm`
** `TDES - Triple DES (3DES) algorithm`
* `STRING: KEY='str' - Clear secret key vale in HEX`
* `STRING: GENERATION='str' - Key generation`
* `STRING: VERSION='str' - Key version`

=== libfkme.SYMSWE.DEC 'SWE'
.Synopsis

-----------------------------------------------------------------------
HELP:   FKME software emulation parameter
PATH:   limes.FKME
TYPE:   OBJECT
SYNTAX: > FKME SWE(KEY='str')
-----------------------------------------------------------------------

.Description

Parameter of FKME library libfkme function SYMSWE for decryption.

.Example

-----------------------------------------------------------------------
...kml=libfkme kmf=SYMSWE kmp="SWE(ALGO=TDES KEY=0123456789abcdeffedcba9876543210)"...
-----------------------------------------------------------------------


.Arguments

* `STRING: KEY='str' - Clear secret key value in HEX`



== FKME FUNCTION FKMEFILE

The function FKMEFILE is an FKME which reads the secret FLAM key from a
file. This is useful if the secret key should not be printed to the
logged output.

The file should only contain the key in its first record.

On ZOS, this FKME is available (like on all other platforms) as function
of the LIBFKME DLL and also as separate LE-less load module 'FKMEFILE'.


=== libfkme.FKMEFILE 'FILE'
.Synopsis

-----------------------------------------------------------------------
HELP:   FKME read password from file
PATH:   limes.FKME
TYPE:   OBJECT
SYNTAX: > FKME FILE(NAME/FILENAME='str')
-----------------------------------------------------------------------

.Description

Parameter of FKME library libfkme function FKMEFILE for encryption or
decryption.

.Example

-----------------------------------------------------------------------
...kml=libfkme kmf=FKMEFILE kmp="FILE=filename"
-----------------------------------------------------------------------


.Arguments

* `STRING: NAME/FILENAME='str' - File with key`



== Imprint

-----------------------------------------------------------------------
limes datentechnik(R) gmbh
Louisenstrasse 101
D-61348 Bad Homburg v.d.H.
phone: +49(0)6172-5919-0
fax:   +49(0)6172-5919-39
mail:  info@flam.de
web:   www.flam.de or www.limes.de
area of jurisdiction: Bad Homburg vor der Hoehe HRB 3288 (gegr. 1985)
managing directors: Falk Reichbott, Ute Wiebach
limes datentechnik(R): efficiency at the limit of possibility.
-----------------------------------------------------------------------


