Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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)
Update DS (distribution server) metadata
Increment use case counter
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
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)
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 pinpad
property):
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.
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
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
:
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.
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 Consent 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;
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
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
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
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
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
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 ID-One Cosmo V7-n is part of the Oberthur family of cryptographic modules called ID-One Cosmo V7. Modules within
this family share the same functionalities and the description of the ID-One Cosmo V7 applies to all versions including the “-n” subject to this validation.
This document describes the functionality provided by the Oberthur ID-One smartcard - which is a PKI container - on the T1C-GCL (Generic Connector Library) implemented version:
ID-One Cosmo V7-n; FIPS 140-2 Security Policy
All model information can be found in the Token typings model page
When initialisation is finished you can continue using the aventra object to execute the functions below.
The expected response for this call should be;
The expected response for this call should be;
Exposes all the certificates publicly available on the smart card. The following certificates can be found on the card:
Root certificate
Signing certificate
Authentication certificate
Issuer certificate
Encryption certificate
When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.
The expected response for this call should be;
This will return information of the Aventra card.
The expected response for this call should be;
When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.
Contains the 'root certificate' stored on the smart card. The service can be called:
Contains the 'authentication certificate' stored on the smart card. The 'authentication certificate' contains the public key corresponding to the private RSA authentication key. The 'authentication certificate' is needed for pin validation, authentication and singing. The service can be called:
Contains the 'non-repudiation certificate' stored on the smart card. The 'non-repudiation certificate' contains the public key corresponding the private RSA non-repudiation key. The service can be called:
The expected response for these calls should be in the following format;
The expected response for these calls should be in the following format;
Data can be signed using the smartcard. To do so, the SDK facilitates in:
Retrieving the certificate chain (root, intermediate and non-repudiation certificate)
Perform a sign operation (private key stays on the smart card)
Return the signed has
To sign data, an algorithm must be specified in the algorithm
property (see Supported Algorithms), and a Base64-encoded string representation of the digest bytes of the same algorithm in the data
property.
Additionally, it is possible to bulk sign data without having to re-enter the PIN by adding an optional bulk
parameter set to true
to the request. Subsequent sign requests will not require the PIN to be re-entered until a request with bulk
being set to false
is sent, or the Bulk PIN Reset method is called.
When using bulk signing, great care must be taken to validate that the first signature request was successful prior to sending subsequent requests. Failing to do this will likely result in the card being blocked.
The expected response for this call should be;
The PIN set for bulk signing can be reset by calling this method.
Response will look like:
The SDK is able to authenticate a card holder based on a challenge. The challenge can be:
provided by an external service
provided by the smart card
An authentication can be interpreted as a signature use case, the challenge is signed data, that can be validated in a back-end process.
The expected response for this call should be;
The expected response for this call should be;
Aventra MyEID PKI Card is a cryptographic smart card conforming to common Public Key Infrastructure standards like ISO/IEC-7816 and PKCS#15v1.0 specification. It can be used for various tasks requiring strong cryptography, e. g. logging securely to Windows, encrypting e-mail, authentication, and electronic signatures. The card is also available as a Dual Interface version, compatible with T=CL protocol and also emulating Mifare™. The card is a JavaCard with Aventra MyEID applet that implements the functionality.
The applet implements the FINEID S1 v1.12 specification and it can be configured to include all or any subset of the features specified in FINEID S4-1 or S4-2 specifications. Starting from version 2.2.0 the applet supports both 1024 and 2048 bit RSA keys. From version 3.0.0 (MyEID3) the applet supports keys from 512 bit up to 2048 bit in increments of 64 bits. The applet is fully compatible with JavaCard 2.1.1 and GlobalPlatform 2.0.1 specifications. The new MyEID version 3 (MyEID3) is now released and it uses the new JavaCard 2.2.1 and GlobalPlatform 2.1.1 platform. The new MyEID3 now supports RSA keys from 512 up to 2048 bits in 64 bit increments. MyEID3 supports file sizes up to 32767 bytes and 14 different PIN-codes can be created and used. The number of RSA keys is only limited by the available memory and maximum numbers of files (see PUT DATA: INITIALISE APPLET).
References
The most relevant specifications and standards are:
ISO/IEC 7816-4
ISO/IEC 7816-8
ISO/IEC 7816-9
JavaCard 2.1.1, MyEID3: 2.2.1
GlobalPlatform 2.0.1 ' (Open Platform), MyEID3: GlobalPlatform 2.1.1
FINEID S1 and S4 documentation
This document describes the functionality provided by the Aventra smartcard - which is a PKI container - on the T1C-GCL (Generic Connector Library) implemented version:
MyEID - reference manual v1.7.36
All model information can be found in the Token typings model page
When initialisation is finished you can continue using the aventra object to execute the functions below.
The expected response for this call should be;
The expected response for this call should be;
Exposes all the certificates publicly available on the smart card. The following certificates can be found on the card:
Root certificate
Signing certificate
Authentication certificate
Issuer certificate
Encryption certificate
When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.
The expected response for this call should be;
This will return information of the Aventra card.
The expected response for this call should be;
When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.
Contains the 'root certificate' stored on the smart card.
Contains the 'authentication certificate' stored on the smart card. The 'authentication certificate' contains the public key corresponding to the private RSA authentication key. The 'authentication certificate' is needed for pin validation, authentication and signing.
Contains the 'non-repudiation certificate' stored on the smart card. The 'non-repudiation certificate' contains the public key corresponding the private RSA non-repudiation key.
The expected response for these calls should be in the following format;
The expected response for these calls should be in the following format;
To sign data, an algorithm must be specified in the algorithm
property (see Supported Algorithms), and a Base64-encoded string representation of the digest bytes of the same algorithm in the data
property.
Additionally, it is possible to bulk sign data without having to re-enter the PIN by adding an optional bulk
parameter set to true
to the request. Subsequent sign requests will not require the PIN to be re-entered until a request with bulk
being set to false
is sent, or the Bulk PIN Reset method is called.
When using bulk signing, great care must be taken to validate that the first signature request was successful prior to sending subsequent requests. Failing to do this will likely result in the card being blocked.
The expected response for this call should be;
The PIN set for bulk signing can be reset by calling this method.
Response will look like:
The expected response for this call should be;
The expected response for this call should be;
The expected response for this call should be;
Each lawyer in Belgium registered at the balie is obliged since 1/1/2018 to have an electronic lawyer card. This is declared in atr. 193bis of the Codex Deontologie voor Advocaten:
“De advocaat moet voor zijn identificatie en voor de authenticatie beschikken over de elektronische CCBE-advocatenkaart.”
More info at https://www.diplad.be/en-GB/t/23/elektronische-advocatenkaart.aspx.
All model information can be found in the Token typings model page
Response will look like: