### Key Label Handling

For cryptographic operations (signing, encryption) keys are required. Beside passwords and passphrases FLAM supports professional key management solutions, based on different cryptographic infrastructures and hardware security modules. For example, on z/OS ICSF on other IBM platforms CCA and on distributed platforms PKCS#11 are supported. If a key protected by a shielded hardware module it must be normally referenced by a name called key label. These names or better the convention for these key labels can be different from client to client. To support different key label conventions FLAM supports key label templates. Key label templates using the same replacement mechanismen for environment variables (<ENNVAR>) described in the file name handling above. Only the sepcial characters used as abbrevation are differ.

     '!' = <ENVID>   - the environment qualifier (T-TEST or P-PROD)
     '~' = <SYSUID>  - current user id (logon name)
     '^' = <OWNERID> - current owner id (defined over the configuration)

FLAM use hard coded default key label templates for the different encryption solutions. For the OpenPGP support for example:

     '!FLAMPGP.%u.%t'

Depending on the application several %x replacments can be supported. These qualifier (%u/%t) are replaced with the corresponding variables. In the OpenPGP example above %u are replaced with the USERID or KEYID and %t are replaced with the internal used key type definition. If you provide as USERID for example '~' or '<SYSUID>' then the current logon name is used a user id. First the %x is replaced by the variable and then the replacement with the defined environemnt variables is done.

Below you can see a few examples with an environment id 'T' for TEST and the internal types 'PUBLIC' or 'PRIVATE':

     TEMPLATE='!FLAMPGP.%u.%t'
       USERID='FREI'
     -------->'TFLAMPGP.FREI.PRIVATE

     TEMPLATE='!FLAMPGP.%u.%t'
       USERID='<HOME>' #this makes not realy sense, but it is possible#
     -------->'TFLAMPGP./home/frei.PUBLIC

     TEMPLATE='!FLAMPGP.%u.%t'
       USERID='~'
     -------->'TFLAMPGP.frei.PRIVATE

     TEMPLATE='!FLMPGP.<OWNERID>.%u.T%t'
       USERID='~'
     -------->'TFLAMPGP.limes.frei.TPUBLIC

     TEMPLATE='!FLMPGP.^.%u.TYP.%t.MYKEY'
       USERID='~'
     -------->'TFLAMPGP.limes.frei.TYP.PRIVATE.MYKEY

The internal type is defined by the application (mainly the used FLAM key management extension version 5 (FKM5)). Over the key template only the position of the internal type can be defined, the value is given by FLAM.

The key template handling and limitations (how long, which characters, how many qualifiers also) are depending on the FKM5. The underlying cryptographic infrastructure defines what is possible. For example, a key label in PKCS#11 can be free defined and for ICSF/CCA it must conform to host data set names. Have a look at the FKM5BOOK for these details.

Since version 5.1.16, the replacement characters are no longer case sensitive. The two templates below are equivalent

     TEMPLATE='!FLAMPGP.%u.%t'
     TEMPLATE='!FLAMPGP.%U.%tT'

This change is making it easier to define such templates in JCL (CAPS ON) on z/OS.