Remote Loader (ReLo)

Introduction

The ReLo (Remote Loading) container is provided through the T1C (Trust1Connector) in order to provide a secured communication channel to execute APDU commands that are generated from a back-end service (which can be optionally signed by a HSM).

The ReLo provides smart card operations, like for example:

  • open/close session
  • execute APDUs (single or in bulk)
  • retrieve card/card reader features
  • verify if card present
  • retrieve ATR
  • ...

Communication Flow

The ReLo-API is an example back-end service implementing different smart card or token profiles (there is no limitation to smart cards). The T1V (Trust1Vault) is a Trust1Team product operating as a secured vault, and integrating with a HSM.

Get ReLo container object

For more information on how to configure the T1C-JLIB client library see Client Configuration. Initialize a T1cClient:

LibConfig conf = new LibConfig();
conf.setEnvironment(Environment.DEV);
conf.setDsUri(DS_URI);
conf.setOcvUri(OCV_URI);
conf.setGclClientUri(URI_T1C_GCL);
conf.setApiKey(API_KEY);
conf.setHardwarePinPadForced(false);
conf.setDefaultPollingIntervalInSeconds(5);
conf.setDefaultPollingTimeoutInSeconds(10);
conf.setSessionTimeout(60);
T1cClient client = new T1cClient(conf);

Get the ReLo container:

RemoteLoadingContainer container = client.getRemoteLoadingContainer(reader);

For demonstration purpose we will use the aforementioned callback, which only outputs the data and eventual error messages. During integration meaningful functionality should be provided.

Obtain the GclReader object

The constructor for the RemoteLoading container expects a GclReader object as parameter. A GclReader can be obtained from the exposed core functionality, for more information see Core Services. Core services responds with available card-readers, available card in a card-reader, etc. For example: In order to get all connected card-readers, with available cards:

List<GclReader> reader = client.getCore().getReadersWithInsertedCard();

This function call returns a list of the following objects:

com.t1t.t1c.GclReader

Name Description Example Value Type
id The reader ID "57a3e2e71c48cee9" java.lang.String
name The reader name "Bit4Id miniLector" java.lang.String
pinpad The presence of a hardware PIN-pad false java.lang.Boolean
card The inserted card see below com.t1t.t1c.core.GclCard

com.t1t.t1c.GclCard

Name Description Example Value Type
atr Answer to Reset "3B9813400AA503010101AD1311" java.lang.String
description List of descriptions ["LuxTrust Card"] java.util.List<java.lang.String>

SessionID is optional

For any function that accepts a sessionId parameter, the parameter is optional. If a sessionId is provided, the corresponding session will be used for the request and then will be _kept open_once the request completes. This means that if this was the last request that needed to be made, the session needs to be explicitly closed with a call tocloseSession.

If no sessionId is provided, the request will still complete, but the GCL will set up a new session, perform the required action and then close the session. This means that there is _no open session_once the request completes.

When a wrong sessionID is sent in a request, an error message will be returned. The status code will be 'invalid sessionID' or 'no active session' (see https://t1t.gitbooks.io/t1c-java-guide/content/status-codes.html).

Response structure

All responses follow a similar structure:

com.t1t.t1c.model.T1cResponse

Name Description Example Value Type
data The data payload N/A T
success The status of the request true java.lang.Boolean

The successproperty indicates whether or not the request was completed successfully. The dataproperty is where returned information will be found; the type of data varies with each function.

Detailed Function Overview

openSession

Opens a new session. Returns the sessionId, which will need to be stored by the client application for later use.

String sessionId = container.openSession(30);

Parameters

  • timeout (optional): session timeout in seconds. If not provided, will default to value set in GCLConfig. Must be a number > 0.

Response

"1877dd41-6d41-40b6-b14c-e4c3e19449fa"

executeCommand

Sends a command to the reader for execution.

GclRemoteLoadingCommand command = container.executeCommand("00A4020C023F00");

Parameters

  • command: command-string to be executed
  • sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

com.t1t.t1c.containers.remoteloading.GclRemoteLoadingCommand
Name Description Example Value Type
tx Input "00A4020C023F00" java.lang.String
rx Output null java.lang.String
sw Status Word "9000" java.lang.String

executeCcid

Executes a command for a CCID feature

GclRemoteLoadingCommand command = container.executeCcid("GET_TLV_PROPERTIES", "1E1E8947040C0402010904000000000D000000002000010820FFFFFFFFFFFFFF");
Parameters
  • feature: feature to check
  • apdu: command to send to the ccid reader (hex format)
  • sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.
Output
com.t1t.t1c.containers.remoteloading.GclRemoteLoadingCommand

closeSession

Closes currently open session.

Boolean closed = container.closeSession(sessionId);
Parameters
  • none
Output
java.Lang.Boolean

isCardPresent

Checks if the card for this session is still present.

If no sessionId is provided, checks if a card is present in the reader.

Boolean present = container.isCardPresent();
Parameters
  • sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.
Output
java.Lang.Boolean

getAtr

Retrieves the ATR for the card currently in the reader.

String atr = container.getAtr()
Parameters
  • sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.
Output
"3B9813400AA503010101AD1311"

ccidFeatures

Returns a list of available CCID features for the current reader.

List<GclRemoteLoadingCcidFeature> features = container.getCcidFeatures()
Parameters
  • sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.
Output
`java.util.List<com.t1t.t1c.containers.remoteloading.GclRemoteLoadingCcidFeature>
Name Description Example Value Type
controlCode The control code 1110638610 java.lang.Integer
id The feature ID "GET_TLV_PROPERTIES" java.lang.String

apdu

Executes an APDU call on the current reader. The difference with the commandfunction is that theapdu function takes an APDU object, whereas commandtakes a string.

GclRemoteLoadingCommand command = container.executeApduCall(
                                      new GclRemoteLoadingApdu()
                                          .withCla("F1")
                                          .withIns("95")
                                          .withP1("F7")
                                          .withP2("E4")
                                          .withData("FE0000040001300000"));
Parameters
  • apdu: object containing the APDU to be executed
  • sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

APDU Object:

Name Description Example Value Type
cla NA "F1" java.lang.Integer
ins NA "95" java.lang.String
p1 NA "F7" java.lang.String
p2 NA "E4" java.lang.String
data NA "FE0000040001300000" java.lang.String
le NA null java.lang.String
Output
com.t1t.t1c.containers.remoteloading.GclRemoteLoadingCommand

Bulk Actions

For the apduand commandfunctions, it is possible to send an array of apdu's/commands.

apdu (bulk)

Executes an array of APDU calls on the current reader.

List<GclRemoteLoadingCommand> commands = container.executeApduCalls(
                                                               Arrays.asList(
                                                                   new GclRemoteLoadingApdu()
                                                                           .withCla("F1")
                                                                           .withIns("95")
                                                                           .withP1("F7")
                                                                           .withP2("E4")
                                                                           .withData("FE0000040001300000"),
                                                                   new GclRemoteLoadingApdu()
                                                                           .withCla("F1")
                                                                           .withIns("95")
                                                                           .withP1("F7")
                                                                           .withP2("E4")
                                                                           .withData("FE0000040001300000")
                                                               ));
Parameters
  • apdus: java.util.List containing the APDU objects to be executed
  • sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.
Output
java.util.List<com.t1t.t1c.containers.remoteloading.GclRemoteLoadingCommand>

command (bulk)

Executes an array of commands on the current reader.

List<GclRemoteLoadingCommand> commands = container.executeCommands(
                                                               Arrays.asList(
                                                                       "00A4020C023F00",
                                                                       "00A4020C02DF01",
                                                                       "00A4020C024031",
                                                                       "00B00000B3")
                                                                       );
Parameters
  • commands : java.util.List containing the command strings to be executed
  • sessionId (optional) : sessionId to use. Required if the session needs to be kept open after the request completes.
Output
java.util.List<com.t1t.t1c.containers.remoteloading.GclRemoteLoadingCommand>

results matching ""

    No results matching ""