Securing Communication by Creating TLS Communication Keys

Important: When EFTLink and Xstore are running separate JREs, it is strongly recommended that you update both JREs to their latest versions to avoid issues with TLS Communications.

Although TLS communication Keys are generated by default. You may wish to regenerate your keys. A batch file, CreateKeys.bat, and a Linux script, CreateKeys.sh is included in the EFTLink project to facilitate creation of encryption keys.

  1. Locate the CreateKeys.bat / CreateKeys.sh file in the EFTLink folder.

  2. From a terminal, run the CreateKeys script file with an appropriate set of parameters to create encryption keys. 

    CreateKeys.bat	-e <algorithm> <bitlength> <signAlgorithm> <daysValidity> [-dname] 
    CreateKeys.sh	-e <algorithm> <bitlength> <signAlgorithm> <daysValidity> [-dname]

    For example, CreateKeys.bat-e RSA 4096 SHA256withRSA 750

    For example, CreateKeys.bat-e RSA 4096 SHA256withRSA 750 -dname

    Table 2-5 SelfSigned Certificate Parameters

    Switch Parameter Description Supported Value

    -e

    <algorithm>

    Algorithm used for TLS keys encryption.

    EC,DSA,RSA

    <bitlength>

    Number of bits - higher values equate to a higher level of encryption.

    256 (when using EC),

    1024,2048 (when using DSA),

    1024,2048,3072,4096,7680,8192,15360 (when using RSA)

    <signAlgorithm>

    Signature Algorithm used.

    SHA256withECDSA, SHA384withECDSA, SHA512withECDSA (when using EC), SHA256withDSA (when using DSA), SHA256withRSA, SHA384withRSA, SHA512withRSA (when using RSA)

    <daysValidity>

    Number of days after creation that the certificate will remain valid.

    100 to 750 days
     

    [-dname]

    Prompt for POS and Eftlink keystores certificate Distinguished Name information.

    		  

  3. Once encryption keys are created, five files will be present on the system in the keys subfolder of EFTLink:

    pos.private.jks to be MOVED to the POS client

    pos.public.jks - to remain on the EFTLink Server

    eftlink.private.jks - to remain on the EFTLink Server

    eftlink.public.jks - to be MOVED to the POS client

    comms.keystore.properties - required to be held on both POS and EFTLink Server

  4. The following files should be REMOVED from the EFTLink system and placed on the POS in the folder [xstore root]\keys, where xstore root is the main POS client folder. For example, C:\xstoredata\xstore\keys, or prior to version 22 of Xstore in C:\xstore\keys).

    pos.private.jks

    eftlink.public.jks

  5. The following file should be COPIED from the EFTLink system and placed on the POS in the folder [xstore root]\keys, where xstore root is the main POS client folder. For example, C:\xstoredata\xstore\keys, or prior to version 22 of Xstore in C:\xstore\keys):

    comms.keystore.properties

  6. This will leave the following three files on the EFTLink server in the folder [eftlink root]\keys:

    eftlink.private.jks

    pos.public.jks

    comms.keystore.properties

  7. The removal of the appropriate files from the EFTLink server is to limit the availability of TLS keys only to where they are required, and in order to reduce the possibility of the keys being obtained and used to monitor traffic between POS and EFTLink server.

    These instructions are repeated by the CreateKeys script file when keys are generated.

    Note:

    From V20 onwards, expiry of TLS certificates is enforced by default. Self-signed certificates will be valid for a maximum of 750 days.

  8. Clear warnings will be placed in log files when certificates are due to expire. Expired certificates will not result in loss of communication between POS and EFTLink.

CA Certificates

Optionally, the EFTLink application TLS encryption keys for secure communication between POS client and EFTLink server may be signed by a CA. A batch file, CreateKeys.bat, and a Linux script, CreateKeys.sh is included in the EFTLink project to facilitate creation of encryption keys, generation of signing request and import of the signed certificates.

  1. Locate the CreateKeys.bat / CreateKeys.sh file in the EFTLink folder.

  2. From a terminal, run the CreateKeys script file with an appropriate set of parameters to create encryption keys. The parameters are like those when used to generate self-signed certificates but specify the first parameter as -s.

    CreateKeys.bat	-s <algorithm> <bitlength> <signAlgorithm> <daysValidity> [-dname] 
    CreateKeys.sh	-s <algorithm> <bitlength> <signAlgorithm> <daysValidity> [-dname]

    For example,

    CreateKeys.bat-s RSA 4096 SHA256withRSA 750

    CreateKeys.bat-s RSA 4096 SHA256withRSA 750 -dname

    Table 2-6 CA Certificate Parameters

    Switch Parameter Description Supported Value

    -s

    <algorithm>

    Algorithm used for TLS keys encryption.

    EC,DSA,RSA

    <bitlength>

    Number of bits - higher values equate to a higher level of encryption.

    256 (when using EC),

    1024,2048 (when using DSA),

    1024,2048,3072,4096,7680,8192,15360 (when using RSA)

    <signAlgorithm>

    Signature Algorithm used.

    SHA256withECDSA, SHA384withECDSA, SHA512withECDSA (when using EC), SHA256withDSA (when using DSA), SHA256withRSA, SHA384withRSA, SHA512withRSA (when using RSA)

    <daysValidity>

    Number of days after creation that the certificate will remain valid.

    100 to 750 days

    [-dname]

    Prompt for POS and Eftlink keystores certificate Distinguished Name information.

  3. Once encryption keys are created, a sub-folder based on the current date/time is created containing the encryption keys along with signing requests:

    For example,

    Folder name: keys20200710115046

    Eftlink.private.jks - selfsigned file

    Pos.private.jks - selfsigned file

    Eftlink.private.csr - certificate signing request

    Pos.private.csr - certificate signing request

    Eftlink.private.jks - backup of selfsigned file

    Pos.private.jks - backup of selfsigned file

    comms.keystore.properties - keystore encryption data file

    The backup files are required for the situation where a subsequent import is attempted but does not give the required results - further attempts may be made at importing the signed certificates received from the CA.

    For this reason, do not remove the backup files.

    File are held in this temporary folder rather than the keys folder as the signing process may take some time, and several sets of signed keys can be handled.

  4. Deliver to your CA the following files:

    Eftlink.private.csr

    Pos.private.csr

    In reply, you should receive the following files (filenames may vary):

    Eftlink.private.cer.der - signing of EFTLink.private.csr

    Pos.private.cer.der - signing of POS.private.csr

    Root.cer - root certificate used to sign

    Optional Intermediate.cer - one or more intermediate certificates

  5. Import the signed certificates into the keystores, by placing the signed files and root certificate (plus optional intermediate certificates) in the temporary signing keys folder keys[date] then running the following command.

    Createkeys -I <foldername> <root cert> <eftlink signed file> <pos signed file> <(optional) intermediate certificate 1><(optional) intermediate certificate 2>

    Table 2-7 Signed Files, Root Certificates and Intermediate Certificates

    Switch Parameter Description Supported

    -e

    <foldername>

    Temporary keys Subfolder name. Do not provide the full path, just the foldername.

    18 character folder name

    <root cert>

    The root certificate provided by the CA

    Security certificate

    <eftlink signed file>

    Signed file returned by CA

    Security certificate

    <pos signed file>

    Signed file returned by CA

    Security certificate

    <intermediate certificate 1>

    CA Intermediate certificate

    Optional Security certificate

    <intermediate certificate 2>

    CA Intermediate certificate

    Optional Security certificate

    For example, createkeys -i keys20200101010101 ca_root.cer eftlink.private.der.cer pos.private.der.cer ca_intermediate1.cer ca_intermediate2.cer

  6. Archive the temporary keys[date] folder to a safe location as this contains sensitive information.

  7. The following files should be REMOVED from the EFTLink system and placed on the POS in the folder [xstore root]\keys, where xstore root is the main POS client folder. For example, C:\xstoredata\xstore\keys, or prior to version 22 of Xstore in C:\xstore\keys):

    pos.private.jks

    eftlink.public.jks

  8. The following file should be COPIED from the EFTLink system and placed on the POS in the folder [xstore root]\keys, where xstore root is the main POS client folder. For example, C:\xstoredata\xstore\keys, or prior to version 22 of Xstore in C:\xstore\keys): 

    comms.keystore.properties

  9. This will leave the following three files on the EFTLink server in the folder [eftlink root]\keys:

    eftlink.private.jks

    pos.public.jks

    comms.keystore.properties

  10. The removal of the appropriate files from the EFTLink server is to limit the availability of TLS keys only to where they are required, and to reduce the possibility of the keys being obtained and used to monitor traffic between POS and EFTLink server. These instructions are repeated by the CreateKeys script file when keys are generated.

    Note:

    From version 20 onwards, expiry of TLS certificates is enforced by default. Self-signed certificates will be valid for a maximum of 750 days.

  11. Clear warnings will be placed in log files when certificates are due to expire. Expired certificates will not result in loss of communication between POS and EFTLink.