com.yello.api.secure

Class EMVConfig

java.lang.Object

com.yello.api.secure.EMVConfig

public class EMVConfig
extends java.lang.Object

The EMVConfig Class

The EMVConfig class enables the EMV configuration databases to be updated inside the security processor (terminal settings configuration for Contact, Visa, Mastercard, Amex, language settings, revocation list, etc).

Given that the feature provided by the EMVConfig class is security-critical, updates can only be done by opening a secure session with the security processor on the Yello terminal.

Normally, this operation will be performed by the Yello TMS server. However, this can also be done from the customer's own server or apk. To do this, credentials will have to be provided by Yello in form of an SSL certificate and SSL private key.

As the Yello API library is multi-platform, the EMVConfig class allows the user to perform the EMV configuration update either locally from an Android application running on the Yello terminal (via the method openSecureEMVSession(String, String, String, int)) or remotely from a PC or Server (via the method openSecureEMVSession(SocketChannel, String, String, String, int)), provided that there is a proxy agent running on the Yello terminal to relay the request. The proxy-agent can be implemented by the client.

NOTE: It is advisable to perform this operation remotely from the server, rather than locally on the Yello terminal to avoid the SSL certificates and SSL key being compromised.

When performing the EMV configuration update operation, an implementation of the ProgressListener interface can be registered via the method updateEMVConfig(EMVConfigType, byte[], int, ProgressListener) to receive notification about the progress of the update.

Examples of use

Updating the Contact Kernel terminal settings database locally on the Yello terminal without ProgressListener

 //Assuming that String ca_cert, cert and pkey are populated with data respectively from a SSL
 //CA Certificate, a SSL client certificate and SSL client private key, all in PEM format.
 //Assuming that byte[] emv_data is already populated with data from the Contact EMV configuration file in XML format

 String ca_cert, cert, pkey;
 byte[] emv_data;

 // Populate ca_cert, cert, pkey and emv_data

 ...
 EMVConfig emvConfig = EMVConfig.getInstance();
 try {
      //Using default timeout
      emvConfig.openSecureEMVSession(ca_cert, cert, pkey, 0);
      //Using default timeout with no EMVConfigProgessListener registered
      emvConfig.updateEMVConfig(EMVConfigType.CONTACT, emv_data, 0, null);
 } catch (Exception e) {
      Log.i("DEMOAPI", "failed to update EMV config " + e);
 } finally {
      emvConfig.closeSecureEMVSession();
 }
 

Updating the Contact Kernel terminal settings database locally on the Yello terminal with ProgressListener

 //Assuming that String ca_cert, cert and pkey are populated with data respectively from a SSL
 //CA Certificate, a SSL client certificate and SSL client private key, all in PEM format.
 //Assuming that byte[] emv_data is already populated with data from the Contact EMV configuration file in XML format

 private class MyProgressListener implements ProgressListener {
      public void showProgress(long progressPercentage) {
          Log.i("DEMOAPI", "Progress " + progressPercentage + "%");
      }
 }

 ...
 private MyProgressListener progressListener = new MyProgressListener();
 String ca_cert, cert, pkey;
 byte[] emv_data;

 // Populate ca_cert, cert, pkey and emv_data

 ...
 EMVConfig emvConfig = EMVConfig.getInstance();
 try {
      //Using default timeout
      emvConfig.openSecureEMVSession(ca_cert, cert, pkey, 0);
      //Using default timeout with a EMVConfigProgessListener registered
      emvConfig.updateEMVConfig(EMVConfigType.CONTACT, emv_data, 0, progressListener);
 } catch (Exception e) {
      Log.i("DEMOAPI", "failed to update EMV config " + e);
 } finally {
      emvConfig.closeSecureEMVSession();
 }
 

NOTE: full example of remote access will be provided at a later time.

Method Summary

Modifier and Type	Method and Description
void	closeSecureEMVSession() Closes the currently opened secure EMV session
java.util.List<EMVKernelType>	getAvailableEMVKernels(int timeoutMs) Gets the list of available EMV kernels from the security processor
IINDataBaseInfo	getEMVBrandInfo(int timeoutMs)
com.yello.api.secure.configuration.EMVConfiguration	getEMVConfig(EMVConfigType type, int timeoutMs) Gets an EMV configuration from the secure processor
static EMVConfig	getInstance() Gets the instance of the EMVConfig singleton
boolean	isSecureEMVSessionOpened() Checks if a secure EMV session to the secure processor is already opened
void	openSecureEMVSession(java.security.cert.Certificate caCert, java.security.cert.Certificate cert, java.security.Key pKey, int timeoutMs) Opens a local secure EMV session to the secure processor.
void	openSecureEMVSession(java.nio.channels.SocketChannel channel, java.security.cert.Certificate caCert, java.security.cert.Certificate cert, java.security.Key pKey, int timeoutMs) Opens a remote (from PC or Server) secure EMV session to the secure processor
void	openSecureEMVSession(java.nio.channels.SocketChannel channel, java.lang.String caCert, java.lang.String cert, java.lang.String pKey, int timeoutMs) Opens a remote (from PC or Server) secure EMV session to the secure processor
void	openSecureEMVSession(java.lang.String caCert, java.lang.String cert, java.lang.String pKey, int timeoutMs) Opens a local secure EMV session to the secure processor (from an Android application running on the Yello terminal)
void	updateEMVConfig(EMVConfigType type, byte[] data, int timeoutMs, ProgressListener listener) Performs an EMV configuration update on the secure processor

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static EMVConfig getInstance()

Gets the instance of the EMVConfig singleton

Returns:

the EMVConfig object.

openSecureEMVSession

public void openSecureEMVSession(java.nio.channels.SocketChannel channel,
                                 java.lang.String caCert,
                                 java.lang.String cert,
                                 java.lang.String pKey,
                                 int timeoutMs)
                          throws java.lang.Exception

Opens a remote (from PC or Server) secure EMV session to the secure processor

Parameters:

channel - SocketChannel opened and connected to a proxy agent running on the Yello terminal

caCert - String containing SSL CA certificate data in PEM format

cert - String containing an SSL client certificate data in PEM format

pKey - String containing an SSL client private key data in PEM format

timeoutMs - Timeout in milliseconds. If timeoutMs is <= 0, internal default timeout will be used

Throws:

java.lang.IllegalAccessException - if a secure EMV session is already opened

java.io.IOException - if the session cannot be opened due to IO errors or if the SocketChannel provided as parameter is not connected.

java.lang.Exception - for other types of exceptions

openSecureEMVSession

public void openSecureEMVSession(java.nio.channels.SocketChannel channel,
                                 java.security.cert.Certificate caCert,
                                 java.security.cert.Certificate cert,
                                 java.security.Key pKey,
                                 int timeoutMs)
                          throws java.lang.Exception

Opens a remote (from PC or Server) secure EMV session to the secure processor

Parameters:

channel - SocketChannel opened and connected to a proxy agent running on the Yello terminal

caCert - SSL CA certificate

cert - SSL client certificate

pKey - SSL client private key

timeoutMs - Timeout in milliseconds. If timeoutMs is <= 0, internal default timeout will be used

Throws:

java.lang.IllegalAccessException - if a secure EMV session is already opened

java.io.IOException - if the session cannot be opened due to IO errors or if the SocketChannel provided as parameter is not connected.

java.lang.Exception - for other types of exceptions

openSecureEMVSession

public void openSecureEMVSession(java.lang.String caCert,
                                 java.lang.String cert,
                                 java.lang.String pKey,
                                 int timeoutMs)
                          throws java.lang.Exception

Opens a local secure EMV session to the secure processor (from an Android application running on the Yello terminal)

Parameters:

caCert - String containing SSL CA certificate data in PEM format

cert - String containing an SSL client certificate data in PEM format

pKey - String containing an SSL client private key data in PEM format

timeoutMs - Timeout in milliseconds. If timeoutMs is <= 0, internal default timeout will be used

Throws:

java.lang.IllegalAccessException - if a secure EMV session is already opened

java.io.IOException - if the session cannot be opened due to IO errors or if the SocketChannel provided as parameter is not connected.

java.lang.Exception - for other types of exceptions

openSecureEMVSession

public void openSecureEMVSession(java.security.cert.Certificate caCert,
                                 java.security.cert.Certificate cert,
                                 java.security.Key pKey,
                                 int timeoutMs)
                          throws java.lang.Exception

Opens a local secure EMV session to the secure processor.

Parameters:

caCert - SSL CA certificate

cert - SSL client certificate

pKey - SSL client private key

timeoutMs - Timeout in milliseconds. If timeoutMs is <= 0, internal default timeout will be used

Throws:

java.lang.IllegalAccessException - if a session (either secure or non-secure) is already opened

java.io.IOException - if the session cannot be opened due to IO errors or if the SocketChannel provided as parameter is not connected.

java.lang.Exception - for other types of exceptions

isSecureEMVSessionOpened

public boolean isSecureEMVSessionOpened()

Checks if a secure EMV session to the secure processor is already opened

Returns:

true if a secure EMV session is opened

closeSecureEMVSession

public void closeSecureEMVSession()

Closes the currently opened secure EMV session

updateEMVConfig

public void updateEMVConfig(EMVConfigType type,
                            byte[] data,
                            int timeoutMs,
                            ProgressListener listener)
                     throws java.lang.Exception

Performs an EMV configuration update on the secure processor

Parameters:

type - type of EMV configuration update as defined by EMVConfigType

data - data in bytes containing the EMV configuration XML data to update

timeoutMs - Timeout in milliseconds. If timeoutMs is <= 0, internal default timeout will be used

listener - ProgressListener to keep track of the update. Optional, can be null.

Throws:

java.io.IOException - if the EMV configuration update cannot be performed due to IO errors

java.lang.IllegalArgumentException - if EMV configuration XML data is not valid

java.lang.Exception - for other types of exceptions.

getAvailableEMVKernels

public java.util.List<EMVKernelType> getAvailableEMVKernels(int timeoutMs)
                                                     throws java.lang.Exception

Gets the list of available EMV kernels from the security processor

Parameters:

timeoutMs - Timeout in milliseconds. If timeoutMs is <= 0, internal default timeout will be used

Returns:

List of EMVKernelType representing the list of EMV kernels available

Throws:

java.util.NoSuchElementException - if not EMV kernels are available

java.lang.Exception - for other type of errors

getEMVConfig

public com.yello.api.secure.configuration.EMVConfiguration getEMVConfig(EMVConfigType type,
                                                                        int timeoutMs)
                                                                 throws java.lang.Exception

Gets an EMV configuration from the secure processor

Parameters:

type - type of EMV configuration as defined by EMVConfigType

timeoutMs - Timeout in milliseconds. If timeoutMs is <= 0, internal default timeout will be used

Returns:

EMVConfiguration object representing the EMV configuration

Throws:

java.io.IOException - if the EMV configuration update cannot be performed due to IO errors

java.lang.IllegalArgumentException - if the EMV configuration data is not valid

java.lang.Exception - for other types of exceptions.

getEMVBrandInfo

public IINDataBaseInfo getEMVBrandInfo(int timeoutMs)
                                throws java.lang.Exception

Throws:

java.lang.Exception