Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
File digests config doesn't take the path differences between Mac OS and Windows into account
PKCS11 configuration cookie cannot be created on Windows devices
PKCS11 returns null pointer exception when no pin is provided
Unresolved address exception when the Trust1Connector is installed or started without internet connection
As an end user I can use RMC with the new T1C v3 for the belgian eID and the file exchange
Windows installers are signed with the Trust1Team certificate
Windows installer includes the firewall settings upfront
All endpoints communicating with smartcards/tokens/... need to be protected by means of JWT
PKCS11 SlotId in config issue
Fileexchange when canceling file or directory dialogs, no error is thrown but an empty path is returned
Catch errors with regards to the GRPC service nog being running
File IO needs to check if access rights for file are fulfilled otherwise return 803
Cookie implementation for the Trust1Connector JS SDK in shared environments
check fileexchange file/directory access rights before executing the command
After reinstallation the v3.0.1 of the t1c api config defines its running in a shared environment but there are no other instances running on the machine
When no connector is installed no valid error code is returned in JS
Play.pid blocking reinstallation of Trust1Connector API
Move file location of the T1C v3 file-exchange config to the new folder structure instead of using the old folder structure
Audit logging for tampering checks in the Trust1Connector
Configure logging for T1C-API
Keep audit record for lifecycle changes T1C-API (restart sandbox, ...)
As an integrator I want to have the RemoteLoading functionality in REST available
Support for silent install on Win Platforms
Remove sensitive system info from API & Proxy exposed on /info endpoint
Remove from API & Proxy the temp folder path on the /info
Provide the possibility to use PKCS11 objects instead of keystores
Integrate PKCS11 container in the sandbox-service
Maintain a transaction log with labels
Ability to do bulk signing with the generic token interface
Fileexchange v2 recovery failed due to wrong encoding
T1C JS SDK fix typo for responseObject info endpoint
Typescript typings are conflicting with eachother (generics)
T1C SDK pkcs11generic slots should be numbers instead of strings
Keep DS logs for 1 year
As the Trust1Connector I want the Sandbox to have an automatic recovery when an unexpected shutdown happens
Add parameter validation to each endpoint which requires it
The Trust1Connector API requires a valid JWT token to be provided in the Authorization header. This JWT token can be retrieved by asking the Distribution Service to generate a token for a specific API-key.
It is important that this API-key is not exposed in the front-end application as this is a security violation.
When you've received a valid JWT token from the DS you can provide this into the configuration object when initialising the Trust1Connector JS client.
When using the Trust1Connector Javascript SDK the Authorization header is automatically populated with the JWT provided while initialising.
When the Token has expired there is a function which you can call to provide a new token and which will in turn return an updated client to be used.
Retrieving a valid JWT token happens via the DS. When passing a valid API-key to header of the endpoint {{ds-url}}/v3/tokens/application (GET) you wil in turn receive a valid JWT token.
Example response
A JWT token is only valid for a certain period. After this period the API will return an error. At this point you need to request a new JWT token to be able to communicate with the API.
In the T1C JS SDK there is a function which you can use to re-initalise the client with a new valid JWT token.
The updateJWT function can be found in the Core service. After initialising you can retrieve the core as follows:
The function's interface is as follows;
This function returns an updated client which you can continue to use for your desired use-cases.
// Config object definition
export class T1CConfigOptions {
constructor(
public t1cApiUrl?: string,
public t1cApiPort?: string,
public t1cProxyUrl?: string,
public t1cProxyPort?: string,
public dsUrl?: string,
public jwt?: string
) {}
}
// example
const configoptions = new T1CSdk.T1CConfigOptions(
environment.t1cApiUrl,
environment.t1cApiPort,
environment.t1cApiUrl,
environment.t1cApiPort,
environment.dsUrl,
environment.jwt
);
config = new T1CSdk.T1CConfig(configoptions);curl --location --request GET 'https://acc-ds.t1t.io/v3/tokens/application' \
--header 'apikey: your-api-key'{
"success": true,
"data": "eyJraWQiOiJ0MWNkcyIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJ0MWNkcy1hcHAiLCJzdWIiOiJkZXZlbG9wbWVudCIsImV4cCI6MTU5OTA1MTExMywiaWF0IjoxNTk5MDQ5OTEzLCJuYmYiOjE1OTkwNDk5MDh9.LE_AdYv9PWxqSRm6-lkV_3TxInCqbf_hTwHFKCFfYwkuzex6AMkeW6FaVCOxu-EBU158S2g70i4VBpeT2TAr0IoOyjK-nalvVG5aB9MwidZMtiPlidcUfsDhsyhbhwqlhI2dzB5J5KsBmvZwpoG-Pg2koUSidruixg3SxRrCMotBRlRNKItnYgfs6_wvd_OOLXs2OlufYOD876MWcJymBK48wf9ESQ50clR3zwPAQsNnXFq2Augk0gOlCgWO1--WgaFeMnBF28b7genZXIkwZCfT82nRYtiOs0zLK2WtyireTHDgjIZif4nX8pggE7t_63Hbv8wCvv8_Mg2PfdhCMQ"
}const configoptions = new T1CSdk.T1CConfigOptions(
environment.t1cApiUrl,
environment.t1cApiPort,
environment.t1cApiUrl,
environment.t1cApiPort,
environment.dsUrl,
environment.jwt
);
config = new T1CSdk.T1CConfig(configoptions);
T1CSdk.T1CClient.initialize(config).then(res => {
client = res;
console.log("Client config: ", client.localConfig)
core = client.core();
}, err => {});updateJWT(jwt: string, callback?: (error: T1CLibException, data?: T1CClient) => void): Promise<T1CClient>Migration from the v2 to the v3 of the Trust1Connector can be done in 2 ways;
Integration of the API
Integration via the deprecated Javascript SDK
Both are viable integrations but we strongly suggest to integrate via the API since the JS SDK does not include all features, only the ones which were available in the v2. When integrating via the API you have more control over the Javascript packages used.
The Javascript SDK has the following packages as dependencies;
For updating your web application first of all you need to use the new Javascript SDK. After this there are some differences in using the SDK from the v2.
The configuration from the v2 has changed, we simplified this.
The v2 had the following configuration options;
With the v3 this is significantly simplified to the following;
Some of the config options of the v3 are still in review and can be removed up until the final release of the v3, in the table below you will find more information
After you've created your configuration object you can do the initialisation of the Trust1Connector SDK. This has largely remained the same except for the error codes.
V2 example:
V3 example;
This value represents the port where the Proxy webserver is listening on. By default this is 51983
gwOrProxyUrl
t1cProxyUrl
Similar to the api url this is the URL where the proxy used in shared environment is running on. This is by default the same as the API url
apiKey
/
gwJwt
jwt
JWT token used for authentication of the web application towards the Trust1Connector. This must be retrieved from the web applications backend
tokenExchangeContextPath
/
ocvContextPath
/
dsContextPath
dsUrl
in v2 this was the context path for the DS based on the gwOrProxyUrl, in the v3 this is the complete DS root url
dsFileContextPath
/
pkcs11Config
/
agentPort
/
implicitDownload
/
forceHardwarePinpad
/
sessionTimeout
/
consentDuration
/
syncManaged
/
osPinDialog
osPinDialog
boolean which depicts the default os pin dialog value (This is up for review to be removed from v3 config)
containerDownloadTimeout
/
localTestMode
/
lang
/
providedContainers
/
V2 config option
V3 config option
Description
gclUrl
t1cApiUrl
in the V2 this was https://localhost:10443 while in the V3 this will be https://t1c.t1t.io (for T1T)
t1cApiPort
is the port where the webserver is listening on, in the v2 this is 10443 but in the v3 by default(T1T) this is 51983
t1cRpcPort
this is the port where the sandbox is running (card communication)
t1cProxyPort
"@types/lodash": "^4.14.150",
"Base64": "^1.1.0",
"axios": "^0.19.2",
"jsencrypt": "^3.0.0-rc.1",
"lodash": "^4.17.15",
"logger-bootstrap": "^2.0.0-alpha2",
"semver": "^7.3.2",
"sha256": "^0.2.0",
"store2": "^2.11.1",
"uuid": "^8.0.0"export class GCLConfigOptions {
constructor(public gclUrl?: string,
public gwOrProxyUrl?: string,
public apiKey?: string,
public gwJwt?: string,
public tokenExchangeContextPath?: string,
public ocvContextPath?: string,
public dsContextPath?: string,
public dsFileContextPath?: string,
public pkcs11Config?: Pkcs11ModuleConfig,
public agentPort?: number,
public implicitDownload?: boolean,
public forceHardwarePinpad?: boolean,
public sessionTimeout?: number,
public consentDuration?: number,
public consentTimeout?: number,
public syncManaged?: boolean,
public osPinDialog?: boolean,
public containerDownloadTimeout?: number,
public localTestMode?: boolean,
public lang?: string,
public providedContainers?: T1CContainerid[]) {
}
}export class T1CConfigOptions {
constructor(
public t1cApiUrl?: string,
public t1cApiPort?: string,
public t1cRpcPort?: string,
public t1cProxyUrl?: string,
public t1cProxyPort?: string,
public dsUrl?: string,
public jwt?: string,
public osPinDialog?: boolean
) {}
}config = new GCLLib.GCLConfig(configoptions);
GCLLib.GCLClient.initialize(config).then(res => {
client = res;
core = client.core();
console.log("GCLClient: ", res)
}, err => {
console.log("GCL error:", err)
if (err.code == 301 || err.code == 302) {
err.client.download("v2.1.0").then(res => {
let download = "Download the GCL here";
document.querySelector(".download").classList.remove("hidden")
document.querySelector(".download").innerHTML = download.link(res.url);
});
}
})config = new T1CSdk.T1CConfig(configoptions);
T1CSdk.T1CClient.initialize(config).then(res => {
client = res;
console.log("Client config: ", client.localConfig)
core = client.core();
}, err => {
if (err.code == 500) {
console.log(err)
client = err.client
$('#consentModal').modal('show', {
keyboard: false
});
$('.consent-token').text(makeid(20));
} else if (err.code == 115) {
$('.consent-token').text(makeid(20));
} else if (err.code == 199) {
document.querySelector("#initAlert").classList.remove("d-none")
document.querySelector("#initAlert").innerHTML = err.description;
} else {
console.error("T1C error:", err)
}
});The Trust1Connector core services address communication functionality with local devices. The Trust1Connector core exposes 2 main interfaces:
interface for web/native applications using JavaScrip/Typescript
REST API as a new approach and to incorporate the Trust1Connector as a microservice in the application architecture
In this guide, we target only the use of Trust1Connector's core interface for web/native applications.
The T1C-SDK-JS exposes protected resources for administration and consumer usage.
The JavaScript library must be initialized with a correct token in order to access the all resource. The security policy for Trust1Connector v3 secured ALL endpoints.
Protected resources are administration resources. The JavaScript library must be initialized with a correct token in order to access the resource.
Download Trust1Connector installer
Get Information of the device and user context
Register T1C for device
Update T1C on device (install new version)
Executing these functionality is explained further.
Consumer resources are typically used from an application perspective:
Get pub-key certificate
Get version
Get Information (operating system, runtime, user context, variable configuration)
List card-readers
Executing these functionality is explained further.
The Trust1Connector functionalities are about secured communication with device hardware.
The document highlights communication with smart card readers - contact and contact-less. Other hardware devices can be enabled or integrated as well in the solution. Some of the already are, for example printer drivers, signature tablet drivers, ...
The client can be initialized by passing a T1CConfig object in the constructor
Returns a list of available card readers. Multiple readers can be connected. Each reader is identified by a unique reader_id.
The response will contains a list of card readers:
When multiple readers are attached to a device, the response will show all connected card readers:
Important to notice:
The response adds a card-element when a card is inserted into the card reader.
The response contains card-reader pin-pad capabilities
As mentioned in the List card-readers, when a smart-card is inserted/detected, the reader will contain the cart-type based on the ATR. The ATR (Anwser To Reset), is the response from any smart-card when powered, and defines the card type.
The Trust1Connector recognized more than 3k smart-card types.
As mentioned in the List card-readers, when a card-reader has pin-pad capabilities, this will be mentioned in the response (notice the pinpadproperty):
The following example is the response for List card-readers on a device with 4 different card-readers attached:
In the above example you notice that 4 card-readers are connected. Each card-reader receives his temporary id which can be used for other functions where a card-reader id is needed.
This method can be requested in order to list all available card-readers, and optional cards-inserted.
Each card-reader has a vendor provided name, which is retrieved from the card-reader itself.
An additional property pinpad, a boolean value, denotes if the card-reader has pin-pad capabilities. A pin-pad is a card-reader, most of the times with its own display and key-pad.
From a security perspective, it's considered best practice to use as much as possible pin-pad capabilities of a pin-pad card-reader.
When a reader has a smart-card inserted (contact interface) or detected (contactless interface), the card type will be resolved by the GCL in order to respond with a meaningful type.
In the above examples you see that; one card-reader has a Belgian eID card; another card-reader has a MisterCash or VISA Card available for interaction.
The readers returned, are the card-readers with a card available. The card-readers where no card is presented, are ignored.
Returns a list of available card readers with a smart card inserted. Multiple readers can be connected with multiple smart cards inserted. Each reader is identified by a unique reader_id and contains information about a connected smart card. A smart card is of a certain type. The Trust1Connector detects the type of the smart card and returns this information in the JSON response.
Response:
The T1C JS SDK no longer has a method to download the T1C installer.
Instead, the T1C installer can be downloaded by navigating the client browser to the /v3/downloads/installer endpoint of the Distribution Service (e.g. https://acc-ds.t1t.io/v3/downloads/installer). The Distribution Service will analyze the User-Agent header and automatically initiate the download of an OS-appropriate installer of the latest configured version. The user agent string parsing is considered "best-effort"; as they can vary wildly depending OS and browser software.
Alternatively, you can also initiate the download of a T1C installer with the following endpoints:
/v3/downloads/installers/{{OS}}: This endpoint allows you to specify the OS for which you wish to obtain an installer. The possible values are win32, win64, unix, macos.
/v3/downloads/installers/{{OS}}/versions/{{version}}: This endpoint allows you to download a specific version of a T1C installer for a specific OS.
Update DS (distribution server) metadata
Increment use case counter
List modules
Get module
Get card-reader
Get card-reader with cards inserted
Get card-readers without card
Get consent (needed for shared environments)
Detect card for card-reader (polling utility resource)
Detect any card (polling utility resource)
Detect card-readers (polling utility resource)
Browser Information (utility resource)
config = new T1CSdk.T1CConfig(configoptions);
T1CSdk.T1CClient.initialize(config).then(res => {
client = res;
console.log("Client config: ", client.localConfig)
core = client.core();
}, err => {
if (err.code == 500) {
console.log(err)
client = err.client
$('#consentModal').modal('show', {
keyboard: false
});
$('.consent-token').text(makeid(20));
} else if (err.code == 115) {
$('.consent-token').text(makeid(20));
} else if (err.code == 199) {
document.querySelector("#initAlert").classList.remove("d-none")
document.querySelector("#initAlert").innerHTML = err.description;
} else {
console.error("T1C error:", err)
}
});T1CClient.initialize(config).then(res => {
var coreService = res.core();
core.readers(callback);
}){
"success": true,
"data": [
{
"id": "57a3e2e71c48cee9",
"name": "Bit4id miniLector",
"pinpad": false,
"card": {
"atr": "3B9813400AA503010101AD1311",
"description": [
"Belgium Electronic ID card (eID)"
],
"module": "beid"
}
}
]
}{
"data": [
{
"id": "ec3109c84ee9eeb5",
"name": "Identiv uTrust 4701 F Dual Interface Reader(2)",
"pinpad": false
},
{
"card": {
"atr": "3B9813400AA503010101AD1311",
"description": [
"Belgium Electronic ID card"
]
},
"id": "57a3e2e71c48cee9",
"name": "Bit4id miniLector",
"pinpad": false
},
{
"id": "c8d31f8fed44d952",
"name": "Identiv uTrust 4701 F Dual Interface Reader(1)",
"pinpad": false
}
],
"success": true
}{
"data": [
{
"card": {
"atr": "3B9813400AA503010101AD1311",
"description": [
"Belgium Electronic ID card"
]
},
"id": "57a3e2e71c48cee9",
"name": "Bit4id miniLector",
"pinpad": false
}
],
"success": true
}{
"data": [
{
"card": {
"atr": "3B9813400AA503010101AD1311",
"description": [
"Belgium Electronic ID card"
]
},
"id": "57a3e2e71c48cee9",
"name": "Bit4id miniLector",
"pinpad": false
}
],
"success": true
}{
"data": [
{
"id": "ec3109c84ee9eeb5",
"name": "Identiv uTrust 4701 F Dual Interface Reader(2)",
"pinpad": false
},
{
"card": {
"atr": "3B67000000000000009000",
"description": [
"MisterCash & Proton card",
"VISA Card (emitted by Bank Card Company - Belgium)"
]
},
"id": "e5863fcc71478871",
"name": "Gemalto Ezio Shield Secure Channel",
"pinpad": true
},
{
"card": {
"atr": "3B9813400AA503010101AD1311",
"description": [
"Belgium Electronic ID card"
]
},
"id": "57a3e2e71c48cee9",
"name": "Bit4id miniLector",
"pinpad": false
},
{
"id": "c8d31f8fed44d952",
"name": "Identiv uTrust 4701 F Dual Interface Reader(1)",
"pinpad": false
}
],
"success": true
}GCLClient.initialize(config, function(err, client) {
var coreService = client.core();
core.readersCardAvailable(callback);
});{
"data": [
{
"card": {
"atr": "3B9813400AA503010101AD1311",
"description": []
},
"id": "57a3e2e71c48cee9",
"name": "Bit4id miniLector",
"pinpad": false
}
],
"success": true
}The Trust1Connector supports 2 different user consent mechanisms for applications:
implicit user consent: the user will be provided with a consent token which can be pasted into his clipboard. The T1C-GCL will implicitly retrieve the consent token form the clipboard and perform a verification (the token pasted in the clipboard - form the application context - should match with the token available on the clipboard for the T1C-GCL)
For an implicit consent, the T1C is performing the verification of the shared code word.
The consent can be configured to have an expiration date, when this expiration date has been exceeded, a new consent will be asked towards the user.
If the consent has been enabled upon installation of the Trust1Connector, a user will not be able to retrieve any data from the connector without first giving its consent, agreeing to give access to his/her card reader of filestorage. Without this consent, all requests will return a 401 Unauthorized response with error code 500 No valid consent found or at initialisation of the Trust1Connector SDK an error code 500 No valid consent found. The application should detect these error codes and use it to trigger the consent dialog.
The application shows this code word on screen and provide a button for 'copy-to-clipboard'. When the user has copied the code word to the clipboard (on user click button event), an implicit consent request can be executed towards the T1C. The T1C will grab the pasted code word from the user system clipboard and if both match, an implicit user consent has been granted for the calling application. The relation between the application and the local T1C instance is 'approved'. At this point the Trust1Connector returns a cookie that should be stored in the browser. This cookie will be re-used the next time the user wants to use the Trust1Connector until the cookie expires.
Initially the concept was based on copying programmatically the code word, from the application context, to the user system clipboard. Although, through CAB forum, this not allowed; A user interaction is mandatory. The application should provide a 'copy-to-clipboard' button or alike in order to 'trigger' a user action. Once this action has been done, the T1C executes the flow automatically, this is retrieval and verification of the code word.
Currently, the need for a user interaction is a known limitation (aka. ). As this is the case, the W3C has a project ' ' to propose a solution for a new clipboard API in browsers. The use case for 'Remote clipboard synchronisation' as a use case included in this draft proposal. As this is a draft, and not yet supported by the browsers, we can not perform an automatic 'paste' ('copy' in terms of the browser) to the clipboard.
Sending an implicit consent request can be done as follows:
This call has 1 required and 2 optional parameters:
Code Word (required): a code word in string format that will be shown in the consent dialog.
Consent duration in days (optional): Allows the application the specify how long this consent is to be valid if granted
Callback function (optional): function to be called with the result of the consent request.
The response of the consent will be an updated T1C Client which you after this point can use to continue your use-case(s).
The response can also be a 400 Bad Request with status code 115 "No agents registered to the proxy service" which means that the request has been sent with the unique code but the Proxy cannot not find the user associated with it by checking the clipboards of all connected users.
This could mean that there is no T1C API client present or it is not running correctly.
T1CSdk.T1CClient.initialize(config).then(res => {
client = res;
console.log("Client config: ", client.localConfig)
core = client.core();
}, err => {
if (err.code == 500) {
client = err.client
$('#consentModal').modal('show', {
keyboard: false
});
$('.consent-token').text(makeid(20));
} else if (err.code == 115) {
$('.consent-token').text(makeid(20));
} else {
console.error("T1C error:", err)
}
});
$('#consentModal .btn-primary').on('click', (ev) => {
const tokenNode = document.querySelector('.consent-token');
var range = document.createRange();
range.selectNode(tokenNode);
window.getSelection().addRange(range);
try {
document.execCommand('copy');
} catch (err) {
console.log('Oops, unable to copy');
}
window.getSelection().removeRange(range);
const clipboardData = tokenNode.textContent;
client.core().getImplicitConsent(clipboardData).then(consentRes => {
client = consentRes // replace the client and other set variables of the T1C
core = client.core();
core.version().then(versionResult => console.log("T1C running on core " + versionResult));
$('#consentModal').modal('hide');
}, err => {
console.error(err)
})
});Running the Trust1Connector in a shared environment, such as Citrix, XenApp and Remote Desktop, requires additional installation steps. In this section we explain the concept and approach used.
The following schematic seems rather complicated as it explains the inner workings of the Trust1Connector components, the concept is elaborate further on this page. If you are only interested in what the integration impact is for your Web Application in a Shared Environment, you can skip directly to the section: Integration in Web Applications
The Web Application can use the T1C-SDK-JS or a custom REST API client for integration purpose. As the Web Application operates in a browser context, resolving an agent, by means of a consent, will result in a browser cookie being provided.
The T1C-SDK-JS implements the detection of a Shared Environment during the initialisation of the library. When initialisation succeeds without a controlled exception, the setup is a standalone; when the initialisation throws an 401 Error, the T1C-SDK-JS can be used to request the user for a Consent.
When using the REST API directly form your web application, reading the browser cookie and performing the initialisation must be done by the integrating Web Application itself.
Compared to Trust1Connector v2, the v3 release has a separate component to be be installed on a shared host. This component is called the T1C-Proxy and only exposes the following use cases:
Verify random available ports [in a predefined range] which can be used by an Agent (Session of T1C-API running in user space)
Port reservation upon installation of a new T1C-API in an active user session
Port registration upon initialisation of a T1C-API in an active user session
Management of an in-memory list of active Agents
The T1C-Proxy operates by Default on the API port defined in the T1C-DS (Distribution Server). From a Web Application perspective, this is the only information known. When a Web Application requests the information of the device, the PROXY device type will inform the Web Application that the targeted underlying API is a PROXY, which means that the Web Application must ask for the Agent specific API port to configure an URI which can be used to execute the use cases.
When using the T1C-SDK-JS this is done implicitly during initialisation.
A T1C-API installed for a specific users runs in [User Space]. To avoid possible attack vectors, the Trust1Connector v3 will always run in [User Space].
Upon installation of the T1C-API, during the post install phase, the T1C-API will try to verify automatically if it is running in a shared environment. If this is the case, the T1C-API will ask the T1C-Proxy for available ports and will reserve those post, prior to initialisation and startup.
The ports which are reserved by the T1C-Proxy are the following:
T1C-API Port: This is the port exposing the OpenAPI interface towards Web Applications and used by the T1C-SDK-JS
T1C-gRPC Port: This is the port exposing the gRPC interface locally towards the T1C-API component. The T1C-gRPC runs in a sandboxed and hardened environment, it contains the implementation modules needed for hardware communication with local or remote peripherals.
When receiving ports during post-install, an user agent device is temporary RESERVED in the Agent Registry of the T1C-Proxy. Upon T1C-API initialisation, the port configurations will be confirmed and the Agent Registry will set the device state on REGISTERED. From this moment on, a T1C-API instance, running in an active user session, will be available for the Web Application.
The T1C-gRPC instance is inherently a component from the T1C-API, and thus is managed by the T1C-API. As each user must have it's own hardened runtime for communication purpose, the port assigned for T1C-gRPC will be registered and configured by the T1C-API (and restarted when needed).
Starting from this release (v3) of the Trust1Connector, each device must have a link with an active and running T1C-DS (Trust1Connector Distribution Server). This is to guarantee security, updates, and avoid potential risk in production.
The T1C-DS is proceeded by an API Gateway who is managing the security offloading in the application layer. For a Web Application to communicate with a T1C-Proxy or T1C-API, a JWT (Json Web Token) is needed and obliged. The T1C-DS is responsible for the key management, the certificate management and other use cases which are described in a separate wiki.
In order to retrieve a valid JWT, the T1C-DS can be requested from your application back-end with a valid api-key. The JWT is valid for a given amount of time, and sets the context used when requesting the T1C-API on a device.
Management of user consents in a shared environment by means of browser cookies with an optional configurable TTL (time to live)
export class ModuleDescriptionResponse extends DataObjectResponse {
constructor(public data: TokenModuleDescription, public success: boolean) {
super(data, success);
}
}
export class TokenAddressResponse extends DataObjectResponse {
constructor(public data: TokenAddressData, public success: boolean) {
super(data, success);
}
}
export class TokenPictureResponse extends DataObjectResponse {
constructor(public data: TokenPictureData, public success: boolean) {
super(data, success);
}
}
export class TokenVerifyPinResponse extends DataObjectResponse {
constructor(public data: TokenVerifyPinResponseData, public success: boolean) {
super(data, success);
}
}
export class TokenVerifyPinResponseData {
constructor(
public verified: boolean
) {}
}
export class TokenSignResponse extends DataObjectResponse {
constructor(public data: TokenSignResponseData, public success: boolean) {
super(data, success);
}
}
export class TokenSignResponseData {
constructor(
public data?: string
) {}
}
export class TokenAuthenticateResponse extends DataObjectResponse {
constructor(public data: TokenAuthenticateResponseData, public success: boolean) {
super(data, success);
}
}
export class TokenAuthenticateResponseData {
constructor(
public data?: string
) {}
}
export class TokenModuleDescription {
constructor(
public desc: string
) {}
}
export class TokenAddressData {
constructor(
public municipality?: string,
public rawData?: string,
public signature?: string,
public streetAndNumber?: string,
public version?: number,
public zipcode?: string
) {}
}
export class TokenAllDataResponse extends DataObjectResponse {
constructor(public data: TokenAllData, public success: boolean) {
super(data, success);
}
}
export class TokenAllData {
constructor(
public picture?: TokenPictureData,
public biometric?: TokenBiometricData,
public address?: TokenAddressData,
) {}
}
export class TokenPictureData {
constructor(
public picture?: string,
public signature?: string,
public width?: number,
public height?: number,
) {}
}
export class TokenData {
constructor(
public rawData?: string,
public version?: string,
public serialNumber?: string,
public label?: string,
public prnGeneration?: string,
public eidCompliant?: string,
public graphicalPersoVersion?: string,
public versionRfu?: string,
public electricalPersoVersion?: string,
public electricalPersoInterfaceVersion?: string,
public changeCounter?: number,
public activated?: string,
) {}
}
export class TokenDataResponse extends DataObjectResponse {
constructor(public data: TokenData, public success: boolean) {
super(data, success);
}
}
export class TokenBiometricData {
constructor(
public birthDate?: string,
public birthLocation?: string,
public cardDeliveryMunicipality?: string,
public cardNumber?: string,
public cardValidityDateBegin?: string,
public cardValidityDateEnd?: string,
public chipNumber?: string,
public documentType?: string,
public firstNames?: string,
public name?: string,
public nationalNumber?: string,
public nationality?: string,
public nobleCondition?: string,
public pictureHash?: string,
public rawData?: string,
public sex?: string,
public signature?: string,
public specialStatus?: string,
public thirdName?: string,
public version?: number,
public issuer?: string
) {}
}
export class TokenBiometricDataResponse extends DataObjectResponse {
constructor(public data: TokenBiometricData, public success: boolean) {
super(data, success);
}
}
export class TokenAlgorithmReferencesResponse {
constructor(public data: TokenAlgorithmReferences, public success: boolean) {
}
}
export class TokenAlgorithmReferences {
constructor(public ref: Array<string>) {
}
}
export class TokenResetPinResponse {
constructor(public data: TokenResetPin, public success: boolean) {
}
}
export class TokenResetPin {
constructor(public verified: boolean) {
}
}
export class PinType {
static PIN = 'Pin';
static CAN = 'Can';
}A Web Application interacts with the Trust1Connector on standalone devices or within a shared environment. The Web Application is not aware, but must take this into consideration upon integration.
Integrating the Trust1Connector can be done via the Javascript SDK. This SDK is compiled in regular javascript and in Typescript. Each release of the Javascript SDK will have the following files;
dist
T1CSdk.js (complete SDK)
T1CSdk.js.map
lib (typings, default Typescript compilation)
lib-esm (typings, Compilation with ES6 module support)
In V3 of the Trust1Connector the javascript SDK is meant as a comparable manner of integrating like the V2. The SDK includes most of the API featureset but not all.
We strongly encourage to integrate via the API, since this will be the most feature-complete and the de facto manner of integration in the future.
All examples below will be shown in regular Javascript. Javascript for changing UI behavior will not be present.
For initialisation of the T1C you need to prepare your application first by adding the SDK JS files to your project and importing them in such a way that you can call for the Javascript functions when you need them.
Next up we will prepare the SDK's configuration Object, this object is used to pass information about which default port the Trust1Connector is running on, JWT key, API url, ...
When the configuration is set you can initialise the Trust1Connector with that Config and an optional property for clipboardData. This clipboard data is used for initialisation of the Trust1Connector in a shared environment. This will be handled later.
You can see in the code above we catch 3 errors;
500: Consent error, this means the user is running in a shared environment and needs to provide his consent
115: Initialisation error: The Trust1Connector is not able to initialise because it could not
199: T1C exception, this will be thrown when the T1C is not available
To retrieve the reader after initialisation you can do the following;
After initialisation of the T1C you can start using it. For example the BEID module needs to be initialised with a readerId, That is why fetching the readers and providing the user-selected reader to the client is a necessity.
The code above will return a BEID client which can be used to execute the BEID functionality.
Initialisation of the Trust1Connector for shared environments is similar to the regular initialisation with the difference being a required consent. More information can be found in the page.
For initialising the Trust1Connector in a shared environment you need to setup the config so that it contacts the Proxy. When initialising you need to provide a token that is residing on the user's clipboard, via this clipboard token the Proxy can determine which which user is trying to communicate and will return an updated configuration value for the API and the sandbox service.
This configuration update is handled by the SDK itself.
The code above is an example of how you can integrate a copy command in the webbrowser. When the data is copied to the clipboard you just need to pass it to the initialize function like so;
let environment = {
t1cApiUrl: 'https://t1c.t1t.io',
t1cApiPort: '51983',
t1cRpcPort: '50051',
dsUrl: 'http://acc-ds.t1t.io',
jwt: '' // retrieve via Back-end
};
const configoptions = new T1CSdk.T1CConfigOptions(
environment.t1cApiUrl,
environment.t1cApiPort,
environment.t1cApiUrl,
environment.t1cApiPort,
environment.dsUrl,
environment.jwt
);
config = new T1CSdk.T1CConfig(configoptions);T1CSdk.T1CClient.initialize(config).then(res => {
client = res;
console.log("Client config: ", client.localConfig);
core = client.core();
core.version().then(versionResult => console.log("T1C running on core "+ versionResult));
}, err => {
else if (err.code == 500) {
$('#consentModal').modal('show', {
keyboard: false
});
$('.consent-token').text(makeid(20));
}
else if (err.code == 115) {
$('.consent-token').text(makeid(20));
}
else if(err.code == 199) {
document.querySelector("#initAlert").classList.remove("d-none")
document.querySelector("#initAlert").innerHTML = err.description;
} else {
console.error("T1C error:", err)
}
});core.readersCardAvailable().then(res => {
//Reader response
}, err => {
console.log("Cards available error:", err)
})function getBeid() {
if(selected_reader === null || selected_reader === undefined) return undefined
else return client.beid(selected_reader.id);
}const tokenNode = document.querySelector('.consent-token');
var range = document.createRange();
range.selectNode(tokenNode);
window.getSelection().addRange(range);
try {
// Now that we've selected the anchor text, execute the copy command
document.execCommand('copy');
} catch(err) {
console.log('Oops, unable to copy');
}
// Remove the selections - NOTE: Should use
// removeRange(range) when it is supported
window.getSelection().removeRange(range);
const clipboardData = tokenNode.textContent;
T1CSdk.T1CClient.initialize(config).then(res => {
// initialised
}, err => {
// Error handeling
})T1C uses the following HTTP response codes when handling a request.
In case of an error the response will contain a body with more detailed information about the error:
All possible values of the codes are described below in "Application Status Codes" The description field contains more information
These errors are still in draft. These can change until the final release of the v3
In order to use the JS-SDK, the library must be initialised with an api-key. The api-key is a key received upon subscription. The JS-SDK is a client library for web based consumers. As a reminder, the T1C can be used from a native applications context using a native client, or addressing directly the T1C interface. In order to work with an api-key in a browser context, 2 type of consumers can be distinguished:
SPA (Single Page Application) integration: this is a web application without any back-end
{
description: "some error description",
code: "some error code"
}function not available
106
function not implemented
107
service not supported
108
service not available
109
service not implemented
110
Pace layer error
111
Reader error
112
Notification error
160
Digest error
115
Initialisation error
116
DistributionService error
117
Rest exception
118
JSON Parsing error
119
JWT parsing error
120
Forbidden error
121
Unauthorized error
122
Invalid DS JWE
123
Device keystore missing
125
Parameter exception
130
Proxy service exception
131
Invalid T1C state exception
199
T1C unavailable exception (JS)
500
Agent consent missing or expired (JS)
configuration related error
Source '/Users/gilles/Desktop/fileextest/test.plist' does not exist
355
112
No valid dir path returned, no valid file path returned, Timeout, No PIN entered
356
804
No Type with name test was found in entity with name testEnt,
357
804
type with name testType already exists
358
not applicable
error 801 will be thrown with a more detailed message
359
not applicable
360
805
Entity with name testEnt already exists
361
805
No Entity with name testEnt was found
/
806
No configuration found (file-exchange config file is missing/deleted…)
Code
Description
100
general t1c error
101
Module not supported
102
Module not available
103
Module not implemented
104
function not supported
Code
Description
300
General transaction error
301
Pin error
304
Puk error
305
Not supported error
Code
Description
400
General certificate error
Code
Description
800
General fileexchange error
801
IO exception (files/folder)
803
Access exception ( not enough rights )
804
Type related errors
805
Entity related errors
Old code
New code
example description
351
803
/Library/Updates/ProductMetadata2.plist (Operation not permitted)
352
803
/Library/Updates/ProductMetadata2.plist (Operation not permitted)
353
803
/Library/Updates/ProductMetadata2.plist (Operation not permitted)
354
Code
Description
900
Internal error
105
806
801
Web Application integration: this is a web application with a back-end implementation
For an SPA, an api-key (thus the access token to the Distribution Service) is considered unsafe in a browser context. For SPA's, Trust1Team configures extra security measures on infrastructure level. A mutual authentication is required and additional policies are applied (IP restriction policy, ...).
The api-key must be translated into an JWT token in order to enable communication with the T1C.
To initialise the JavaScript client library, the library must be loaded into your HTML page:
Once loaded, the script will expose a GCLLib global. This global will allow you to create a GCLConfig:
The GCLConfigOptions object will allow you to specify and/or override the configuration to be used. Configuration options can be found in the Configuration Options below. You can create a GCLConfigOptions as follows:
Now that we have a configuration, we can initialise the client library. The following example creates a Promise that will resolve with an instance of a T1CClient:
<script src="../T1CSdk.js" charset="utf-8"></script>var config = new T1CSdk.T1CConfig(configOptions);var configOptions = new T1CSdk.T1CConfigOptions(
environment.t1cApiUrl,
environment.t1cApiPort,
environment.t1cProxyUrl,
environment.t1cProxyPort,
environment.t1cDSUrl,
environment.jwt,
);T1CSdk.T1CClient.initialize(config).then(res => {
client = res;
console.log("Client config: ", client.localConfig)
core = client.core();
}, err => {});