Client Certificates

Client Certificates for IP Communications

In order for CSDK to establish a secure TCP/IP (also referred to as INET) connection with a card reader, there are a few prerequisites involving client certificates that must be met. Due to the difference between Windows and Android OSs, the certificate files and their formats for Desktop and Android application are different. The following steps describe how to prepare your application to support INET connections to the card reader.

Windows Desktop Application

CSDK integrators receive two client certificate related files from Elavon: Client_CERT.PEM and Client_KEY.PEM. As the names indicate, one is the client certificate itself and the other file is the private key for the certificate, both in PEM format. Integrators should include these two files as part of their application files as CSDK will load them during application runtime. You can see an example of this in the desktop sample application (in the certificates folder).

CSDK requires two additional DLLs: libeay32.dll and ssleay32.dll which are used to load the certificate and apply the cryptographic algorithm. Please put those two DLLs (included in the sample application) in your application’s java library path. Additionally please add the full path for the java library path to the environment variable PATH (put it at the front) of the machine where the application runs on.

Android Application

CSDK integrators receive three certificate related files: Client_CERT.PEM, Client_KEY.PEM and CA.PEM. Two of these files were explained in the section above. The third file: CA.PEM is the Certificate Authority certificate file used to create Client_CERT.PEM. Integrators should use these files to create a BKS key store which is required during application runtime. The following steps describe how to create a BKS keystore file:

  1. Download Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7 from Oracle. Extract these policy files into your JRE’s security directory.

  2. Convert a PEM certificate file and a private key to PKCS#12 (.pfx .p12) with the following command. You will then be prompted for a password. Make sure you remember this password as it will be used in the next step.

    openssl pkcs12 -export -out CLIENT.p12 -inkey CLIENT_KEY.PEM -in CLIENT_CERT.PEM -certfile CA.PEM

  3. Convert .p12 to a Java Key Store file:

    keytool -importkeystore -deststorepass [password_from_the_previous_step] -destkeypass [password_from_the_previous_step] -destkeystore CLIENT.jks -srckeystore CLIENT.p12 -srcstoretype PKCS12 -srcstorepass [password_from_the_previous_step] -alias 1

  4. Now we need to convert a .jks file to a .bks file. To do that, you can download a tool named portecle from http://sourceforge.net/projects/portecle/files/portecle/1.7/portecle-1.7.zip/download, and run the tool with the following command:

    java -jar portecle.jar

    In the program you should:

    1. Use File->Open Keystore File to navigate to your CLIENT.jks and open it.
    2. Use Tools->Change Keystore Type->BKS to convert the keystore to BKS format.
    3. Use File->Save Keystore to save your new CLIENT.BKS file to disk.
  5. Add CLIENT.bks and CA.PEM file as assets for your application. You can see an example in the android sample application (src/main/assets).

iOS Application

CSDK integrators receive three certificate related files: Client_CERT.PEM, Client_KEY.PEM and CA.PEM. Integrators should use these files to create a P12 file which is required during application runtime. The following command can convert a PEM certificate file and a private key to PKCS#12 (.pfx .p12). Please enter a password when prompted:

openssl pkcs12 -export -out CLIENT.p12 -inkey CLIENT_KEY.PEM -in CLIENT_CERT.PEM -certfile CA.PEM

You need to add the generated CLIENT.p12 file to the resource bundle of your application. This file and the password you created earlier will be used in your application during construction of an ECLInetAddress object. An example can be found in the sample app’s AccountDelegate.m file.