Contribute in GitHub: Open doc issue|Edit online

Session Link Encryption

Link encryption is the mechanism that creates an encrypted communication session between the Agent and a client. The critical data to protect are user IDs and potentially logon passwords. Key material itself is always encrypted.

Diffie-Hellman (DH) link encryption is the preferred link encryption scheme. It provides the strongest link encryption algorithm and key size, and can be achieved from the very first connection between the Agent and the client. The keys used in the Diffie-Hellman link encryption are 521 bit size ECC keys, while the generated session encryption keys are AES 256 CIPHER keys. Trust is created between the client and the EKMF Agent by the SHA-256 value of the ECC signature public key tokens.

The DH link encryption requires the following to create public key tokens:

The EKMF Agent will accept the client's public key token by having access to the XFACILIT class resource KMG.WS.<64-character-hex-fingerprint>.

For example, if your EKMG Agent's <task-user> is 'EKMF' and the SHA-256 value of the ECC signature public key token for the client is 8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102, then define and permit this profile for the EKMF Agent:

RDEFINE XFACILIT -                                                         
KMG.WS.8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102
PERMIT -   
KMG.WS.8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102 -
CLASS(XFACILIT) ACC(READ) ID(EKMF)

SETROPTS RACL(XFACILIT) REFRESH

An EKMF client user ID must be given permission to be used with an EKMF agent running under the specific task user ID. Therefore, every EKMF Workstation <client-user> must have access to the KMG.EKMF.KMGPRACF.<task-user> profile in the FACILITY class. While EKMF Web only has one client user ID, there may be multiple client user IDs for the EKMF Workstation.

For example, the following commands are used to permit client user 'EKMFCLT' to be used with an EKMF agent running as user 'EKMF': 

RDEFINE FACILITY KMG.EKMF.KMGPRACF.EKMF
PERMIT KMG.EKMF.KMGPRACF.EKMF CLASS(FACILITY) ACC(READ) ID(EKMFCLT)

In addition, for EKMF Web only, the Agent requires access to the KMG.WEBCLIENT.<client-user> and KMG.LG.<64-character-hex-fingerprint> profiles in the XFACILIT class. The <client-user> must match the value specified for the &WEBCLIENT parameter in KMGPARM.

For example, using 'EKMF' as the EKMF agent task user ID, &WEBCLIENT(EKMFCLT) in KMGPARM and 8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102 as fingerprint, specify: 

RDEFINE XFACILIT KMG.WEBCLIENT.EKMFCLT
PERMIT KMG.WEBCLIENT.EKMFCLT CLASS(XFACILIT) ACC(READ) ID(EKMF)
RDEFINE XFACILIT -
KMG.LG.8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102
PERMIT -
KMG.LG.8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102 -
CLASS(XFACILIT) ACC(READ) ID(EKMF)

Where to find EKMF Web's identity key

EKMF Web calls this value the 'Backend public key hash' and displays this value on its About screen. The Agent uses this key to authenticate EKMF Web.

About screen

Preventing clients from disabling link encryption (optional)

There is a possibility to establish an unencrypted connection to an Agent. For the Agent to accept those connection, its <task-user> must have READ access to KMG.EKMF.LNKCRYOFF. It is recommended to define the profile with UACC(NONE) to avoid unecrypted connections. 

RDEFINE FACILITY KMG.EKMF.LNKCRYOFF UACC(NONE) 
SETROPTS RACLIST(FACILITY) REFRESH

The Agent can be configured to turn off the checking of the client's signature (when the KMGPARM &WS-AUTH is set to 'OFF'). To allow this, the Agent <task-user> must have READ access to KMG.WS.AUTHOFF. It is recommended to define the profile with UACC(NONE) to ensure client signatures are always checked. 

RDEFINE XFACILIT KMG.WS.AUTHOFF UACC(NONE) 
SETROPTS RACLIST(XFACILIT) REFRESH