com.yello.api.system

Class Sys

java.lang.Object

com.yello.api.system.Sys

All Implemented Interfaces:

SessionHandler

public class Sys
extends java.lang.Object
implements SessionHandler

The Sys Singleton Class

The Sys singleton class comprises methods that one can use to access non-security related system features (like get hardware information, secure date time, setting led animation, etc) provided by the secure processor available on the Yello terminal.

Given that the Yello API library is multi-platform, the Sys singleton class allows the user to access the system features either locally from the Yello Android device or remotely from a PC or Server, provided that there is a proxy agent running on the Yello terminal to relay the system requests. The proxy-agent can be implemented by the client.

System features are accessed locally on the Yello terminal via the methods openSession(int) or openSession(String, String, String, int), which notably allow an Android application to open respectively a normal session or a secure session to the secure processor.

System features are accessed remotely from a PC or Server via the methods openSession(SocketChannel, int) or openSession(SocketChannel, String, String, String, int), which allows to open respectively a normal session or a secure session to the secure-processor on the Yello terminal via a SocketChannel connected to a proxy agent running on the Android side of the Yello terminal. In this case, the proxy agent will just relay information being sent between the remote client-application and the secure-processor.

NOTE: in both use-cases, opening a secure session will require SSL certificates and key provided by Yello.

Examples of use

Getting date-time from the secure processor locally on the Yello terminal via a normal session

 import org.joda.time.Instant;

 ...
 Sys sys = Sys.getInstance();
 try {
     //Use default connection timeout
     sys.openSession(0);
     //Use default request timeout
     Instant date = sys.getSecureDateTime(0);
     Log.i("DEMOAPI", "Secure date-time " + date.toString());
 } catch(Exception e) {
     Log.e("DEMOAPI", "Exception " + e);
 } finally {
     sys.closeSession();
 }
 

Getting date-time from the secure process locally on the Yello terminal via a secure session

 //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.

 import org.joda.time.Instant;

 ...
 Sys sys = Sys.getInstance();
 //Use default connection timeout
 try {
     sys.openSession(ca_cert, cert, pkey, 0);
     //Use default request timeout
     Instant date = sys.getSecureDateTime(0);
     Log.i("DEMOAPI", "Secure date-time " + date.toString());
 } catch(Exception e) {
     Log.e("DEMOAPI", "Exception " + e);
 } finally {
     sys.closeSession();
 }
 

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

Method Summary

Modifier and Type	Method and Description
void	closeSession() Closes the currently opened session (normal or secure) to the secure processor
static Sys	getInstance() Gets the instance of the Sys singleton
org.joda.time.Instant	getSecureDateTime(int timeoutMs) Gets date-time from the secure processor in UTC
HardwareInfo	getSecureHardwareInfo(int timeoutMs) Gets hardware information relative to the secure processor
LifeCycleType	getSecureLifeCycleState(int timeoutMs) Gets the current life cycle state of the secure processor
int	getSecureTimeZoneOffset(int timeoutMs) Gets the timezone offset in the secure processor
boolean	isSessionOpened() Checks if a session to the secure processor is already opened
void	openSession(int timeoutMs) Opens a local session to the secure processor (from an Android application running on the Yello terminal)
void	openSession(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 a PC or server) secure session to the secure processor.
void	openSession(java.nio.channels.SocketChannel channel, int timeoutMs) Opens a remote (from PC or Server) session to the secure processor
void	openSession(java.nio.channels.SocketChannel channel, java.lang.String caCert, java.lang.String cert, java.lang.String pKey, int timeoutMs) Opens a remote (from a PC or server) secure session to the secure processor.
void	openSession(java.lang.String caCert, java.lang.String cert, java.lang.String pKey, int timeoutMs) Opens a local secure session to the secure processor (from an Android application running on the Yello terminal)
void	setSecureTimeZoneOffset(int offset, int timeoutMs) Sets the timezone offset in the secure processor
int	setSecurityLedBrightness(int brightness, int timeoutMs) Set security LEDs brightness
void	startLedAnimation(LedAnimationType type, int durationMs, int timeoutMs) Starts a led animation on the yello device
void	stopLedAnimation(int timeoutMs) Stops a led animation on the yello device
void	useExistingSession(boolean secure) Uses an existing session opened by another SessionHandler

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static Sys getInstance()

Gets the instance of the Sys singleton

Returns:

the Sys object.

getSecureTimeZoneOffset

public int getSecureTimeZoneOffset(int timeoutMs)
                            throws java.lang.Exception

Gets the timezone offset in the secure processor

Parameters:

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

Returns:

integer representing the secure timezone offset in seconds

Throws:

java.io.IOException - if the secure timezone cannot be obtained due to IO errors.

java.lang.Exception - for other types of exceptions

setSecureTimeZoneOffset

public void setSecureTimeZoneOffset(int offset,
                                    int timeoutMs)
                             throws java.lang.Exception

Sets the timezone offset in the secure processor

Parameters:

offset - integer representing the timezone offset to set in seconds

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

Throws:

java.io.IOException - if the secure timezone cannot be obtained due to IO errors.

java.lang.Exception - for other types of exceptions

getSecureDateTime

public org.joda.time.Instant getSecureDateTime(int timeoutMs)
                                        throws java.lang.Exception

Gets date-time from the secure processor in UTC

Parameters:

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

Returns:

Instant representing the secure date-time in UTC

Throws:

java.io.IOException - if the secure date-time cannot be obtained due to IO errors.

java.lang.Exception - for other types of exceptions

startLedAnimation

public void startLedAnimation(LedAnimationType type,
                              int durationMs,
                              int timeoutMs)
                       throws java.lang.Exception

Starts a led animation on the yello device

Parameters:

type - type of led animation to perform as defined in LedAnimationType

durationMs - duration of the animation in milliseconds. If durationMs = 0, animation is performed forever.

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

Throws:

java.lang.IllegalArgumentException - if parameters are invalid

java.io.IOException - if the led animation cannot be performed due to IO errors.

java.lang.Exception - for other types of exceptions

stopLedAnimation

public void stopLedAnimation(int timeoutMs)
                      throws java.lang.Exception

Stops a led animation on the yello device

Parameters:

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

Throws:

java.io.IOException - if the led animation cannot be stopped due to IO errors.

java.lang.Exception - for other types of exceptions

getSecureLifeCycleState

public LifeCycleType getSecureLifeCycleState(int timeoutMs)
                                      throws java.lang.Exception

Gets the current life cycle state of the secure processor

Parameters:

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

Returns:

LifeCycleType representing the current life cycle state of the secure processor

Throws:

java.io.IOException - if the life cycle state cannot be retrieved due to IO errors.

java.lang.Exception - for other types of exceptions

getSecureHardwareInfo

public HardwareInfo getSecureHardwareInfo(int timeoutMs)
                                   throws java.lang.Exception

Gets hardware information relative to the secure processor

Parameters:

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

Returns:

HardwareInfo representing the secure hardware information

Throws:

java.io.IOException - if the secure hardware information cannot be retrieved due to IO errors.

java.lang.Exception - for other types of exceptions

setSecurityLedBrightness

public int setSecurityLedBrightness(int brightness,
                                    int timeoutMs)
                             throws java.lang.Exception

Set security LEDs brightness

Parameters:

brightness - brightness value

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

Returns:

integer execution K81 status code, 0 - success, < 0 failure

Throws:

java.lang.IllegalArgumentException - if parameters are invalid

java.io.IOException - if the led animation cannot be performed due to IO errors.

java.lang.Exception - for other types of exceptions

openSession

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

Description copied from interface: SessionHandler

Opens a remote (from a PC or server) secure session to the secure processor.

Specified by:

openSession in interface SessionHandler

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 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

openSession

public void openSession(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

Description copied from interface: SessionHandler

Opens a remote (from a PC or server) secure session to the secure processor.

Specified by:

openSession in interface SessionHandler

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 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

openSession

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

Description copied from interface: SessionHandler

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

Specified by:

openSession in interface SessionHandler

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 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

openSession

public void openSession(java.nio.channels.SocketChannel channel,
                        int timeoutMs)
                 throws java.lang.Exception

Description copied from interface: SessionHandler

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

Specified by:

openSession in interface SessionHandler

Parameters:

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

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

openSession

public void openSession(int timeoutMs)
                 throws java.lang.Exception

Description copied from interface: SessionHandler

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

Specified by:

openSession in interface SessionHandler

Parameters:

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

isSessionOpened

public boolean isSessionOpened()

Description copied from interface: SessionHandler

Checks if a session to the secure processor is already opened

Specified by:

isSessionOpened in interface SessionHandler

Returns:

true if a session is opened.

closeSession

public void closeSession()

Description copied from interface: SessionHandler

Closes the currently opened session (normal or secure) to the secure processor

Specified by:

closeSession in interface SessionHandler

useExistingSession

public void useExistingSession(boolean secure)
                        throws java.lang.Exception

Description copied from interface: SessionHandler

Uses an existing session opened by another SessionHandler

Specified by:

useExistingSession in interface SessionHandler

Parameters:

secure - boolean indicating whether to reused a secure session or plain session

Throws:

java.lang.IllegalAccessException - if no session is opened.

java.lang.Exception - for other types of exceptions