# FKME - User Manual

limes datentechnik gmbh <support@flam.de>
v5.1.27, 2022-07-29:
release.
Frankenstein Limes Key Management Extension (FKME)
Copyright © limes datentechnik ® 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 ® gmbh. These trademarked terms are marked with the appropriate symbol (® or ™), indicating registered or common law trademarks owned by limes datentechnik ® gmbh at the time this information was published. The following terms are trademarks of limes datentechnik ® gmbh in Germany, other countries, or both:

- LIMES® - Short company name of the owner of this document

- limes datentechnik® - Company name of the owner of this document

- FLCL® - Frankenstein Limes Command Line

- FLCC® - Frankenstein Limes Control Center

- FLAM® - Frankenstein Limes Access Method

- FLUC® - Frankenstein Limes Universal Converter

- FLIES® - Frankenstein Limes Integrated Extended Security

- FKMS® - Frankenstein Key Management System

- FKME® - Frankenstein Key Management Extension/Exit

- FLAMFILE® - A file based on FLAM syntax

- CLE/P® - Command line Executer/Parser

License terms

The license terms for all software components owned by limes datentechnik gmbh® 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 ®. 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® and provided to our users for individual extension to this software. The driver is conforming to this license terms but LIMES® 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®.

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.