Sample code uses ES6 language features such as arrow functions and promises. For compatibility with IE11, code written with these features must be either transpiled using tools like Babel or refactored accordingly using callbacks.
Introduction
The Generic token interface is an interface used to integrate all supported tokens. This interface relies on the fact that you will need to provide a valid module. The module suggested from the reader response can be used here.
Interface
Copy export interface AbstractEidGeneric {
allData(module: string, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllDataResponse) => void): Promise<TokenAllDataResponse>;
allCerts(module: string, parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsResponse) => void): Promise<TokenAllCertsResponse>;
biometric(module: string, callback?: (error: T1CLibException, data: TokenBiometricDataResponse) => void): Promise<TokenBiometricDataResponse>;
tokenData(module: string, callback?: (error: T1CLibException, data: TokenInfoResponse) => void): Promise<TokenInfoResponse>;
address(module: string, callback?: (error: T1CLibException, data: TokenAddressResponse) => void): Promise<TokenAddressResponse>;
picture(module: string, callback?: (error: T1CLibException, data: TokenPictureResponse) => void): Promise<TokenPictureResponse>;
rootCertificate(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
intermediateCertificates(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
authenticationCertificate(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
nonRepudiationCertificate(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
encryptionCertificate(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
issuerCertificate(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
allCertsExtended(module: string, parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsExtendedResponse) => void): Promise<TokenAllCertsExtendedResponse>;
rootCertificateExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
intermediateCertificatesExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
authenticationCertificateExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
nonRepudiationCertificateExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
encryptionCertificateExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
issuerCertificateExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
verifyPin(module: string, body: TokenVerifyPinData, callback?: (error: T1CLibException, data: TokenVerifyPinResponse) => void): Promise<TokenVerifyPinResponse>;
authenticate(module: string, body: TokenAuthenticateOrSignData, callback?: (error: T1CLibException, data: TokenAuthenticateResponse) => void): Promise<TokenAuthenticateResponse>;
sign(module: string, body: TokenAuthenticateOrSignData, bulk?: boolean, callback?: (error: T1CLibException, data: TokenSignResponse) => void): Promise<TokenSignResponse>;
signRaw(module: string, body: TokenAuthenticateOrSignData, bulk?: boolean, callback?: (error: T1CLibException, data: TokenSignResponse) => void): Promise<TokenSignResponse>;
allAlgoRefs(module: string, callback?: (error: T1CLibException, data: TokenAlgorithmReferencesResponse) => void): Promise<TokenAlgorithmReferencesResponse>
resetBulkPin(module: string, callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
} Models
All model information can be found in the Token typings model page
Initialise the Trust1Connector JS
Initialise a Trust1Connector client with a valid configuration:
Copy T1CSdk . T1CClient .initialize (config) .then (res => {
client = res;
} , err => {
console .error (error)
}); Obtain the Reader information
In order to get all connected card-readers, with available cards:
Copy var core = client .core ();
core .readersCardAvailable (callback); This function call returns:
Copy {
"data" : [
{
"card" : {
"atr" : "3B9813400AA503010101AD1311" ,
"description" : [ "Belgian eID Card" ]
} ,
"id" : "57a3e2e71c48cee9" ,
"name" : "Bit4id miniLector" ,
"pinpad" : false ,
"suggestedModule" : "beid"
}
] ,
"success" : true
} As you can see in the response we get a property suggestedModule which is returned based on the card, reader and AID information. This suggested module can be used in the generic interface.
Using the generic interface can be done as follows;
Copy var generic = client .generic ( selected_reader .id , pin , pinType); The pin and pinType are optional and are used for unlocking the pace layer (if the card is protected with a pace layer).
At this point for each use-case you will need to provide the module. This can be manually defined or be retrieved from the suggestedModule property in the reader-response. In the examples below we provide the module as a variable module
Cardholder Information
The card holder is the person identified using the Belgian eID card. It's important to note that all data must be validated in your backend. Data validation can be done using the appropriate certificate (public key).
Biometric data
Contains all card holder related data, excluding the card holder address and photo.
The service can be called:
Copy generic .biometric ( module , options , callback); An example callback:
Copy function callback (err , data) {
if (err){
console .log ( "Error:" , JSON .stringify (err , null , ' ' ));
}
else {
console .log ( JSON .stringify (data , null , ' ' ));
}
} Response:
Copy {
"birthDate" : "15 JUL 1993" ,
"birthLocation" : "Roeselare" ,
"cardDeliveryMunicipality" : "Avelgem" ,
"cardNumber" : "592..8233" ,
"cardValidityDateBegin" : "27.05.2015" ,
"cardValidityDateEnd" : "27.05.2025" ,
"chipNumber" : "U0xHk...EstwAjEpJQQg==" ,
"documentType" : "01" ,
"firstNames" : "Gilles Frans" ,
"name" : "Platteeuw" ,
"nationalNumber" : "930...154" ,
"nationality" : "Belg" ,
"nobleCondition" : "" ,
"pictureHash" : "Fqva9YCp...JKyn8=" ,
"rawData" : "AQw1OTIxMjQwNTgy...TARFBar2vWAqTW+axEIuyskBgFySsp/" ,
"sex" : "M" ,
"signature" : "hKys9WMjUm4ipg...14xUCg/98Y9/gP/vgG7JTRZJoKgDXLLTvLZO4qlfA==" ,
"specialStatus" : "0" ,
"thirdName" : "J" ,
"version" : "0"
} Address
Contains the card holder's address. The service can be called:
Copy generic .address ( module , callback); Response:
Copy {
"municipality" : "Hoeselt" ,
"rawData" : "ARJLZXJrc...AAAAAA==" ,
"signature" : "mhPyeRg25H...w==" ,
"streetAndNumber" : "Kerkstraat X" ,
"version" : "0" ,
"zipcode" : "3730"
} Picture
Contains the card holder's picture stored on the smart card. The service can be called:
Copy generic .picture ( module , callback); Response:
Copy {
"data" : "/9j/4AAQSkZJRgABA...59aVpcklSDzyKUTEDGK//9k=" ,
"success" : true
} Token info
The token info contains generic information about the card and it's capabilities. This information includes the serial number, file types for object directory files, algorithms implemented on the card, etc.
Response
Copy {
"data" : {
"eid_compliant" : 48 ,
"electrical_perso_interface_version" : 0 ,
"electrical_perso_version" : 3 ,
"graphical_perso_version" : 7 ,
"label" : "BELPIC" ,
"prn_generation" : 4 ,
"raw_data" : "MCcCAQAEEFNMSU4z...JFTFBJQwMCBDCeBAcDAAA=" ,
"serial_number" : "534C494E..1231C" ,
"version" : 0 ,
"version_rfu" : 0
} ,
"success" : true
} Certificates
Exposes all the certificates publicly available on the smart card.
Extended certificates
You can also fetch the extended versions of the certificates via the functions
Copy allCertsExtended(module: string, parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsExtendedResponse) => void): Promise<TokenAllCertsExtendedResponse>;
rootCertificateExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
intermediateCertificatesExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
authenticationCertificateExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
nonRepudiationCertificateExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
encryptionCertificateExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
issuerCertificateExtended(module: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>; this has the capabilities to return multiple certificates if the token has multiple of this type.
for a single certificate the response looks like:
Copy {
"success" : true
"data" : {
"certificates" : [{
"certificate" ? : string ,
"certificateType" ? : string ,
"id" ? : string ,
"subject" ? : string ,
"issuer" ? : string ,
"serialNumber" ? : string ,
"url" ? : string ,
"hashSubPubKey" ? : string ,
"hashIssPubKey" ? : string ,
"exponent" ? : string ,
"remainder" ? : string ,
"parsedCertificate" ? : Certificate
}]
}
} the allCertsExtended returns the following, with the contents of the certificates as the one you can see above;
Copy {
"success" : true
"data" : {
"rootCertificate" : {
"certificates" : [...]
} ,
"authenticationCertificate" : {
"certificates" : [...]
} ,
"nonRepudiationCertificate" : {
"certificates" : [...]
} ,
"intermediateCertificates" : {
"certificates" : [...]
} ,
"encryptionCertificate" : {
"certificates" : [...]
}
}
} Root Certificate
Contains the 'root certificate' stored on the smart card. The root certificate is used to sign the 'citizen CA 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 service can be called:
Copy generic .rootCertificate ( module , parseCertsBoolean , callback); Response:
Copy {
success : true ,
data : {
certificate ?: string ,
certificates ?: Array < string > ,
certificateType ?: string ,
id ?: string ,
parsedCertificate ?: Certificate ,
parsedCertificates ?: Array < Certificate >
}
} You can also fetch the root certificate via the function rootCertificateExtended this has the capabilities to return multiple certificates if the token has multiple of this type.
The response looks like:
Copy {
"success" : true
"data" : {
"certificates" : [
"certificate" ?: string ,
"certificateType" ?: string ,
"id" ?: string ,
"subject" ?: string ,
"issuer" ?: string ,
"serialNumber" ?: string ,
"url" ?: string ,
"hashSubPubKey" ?: string ,
"hashIssPubKey" ?: string ,
"exponent" ?: string ,
"remainder" ?: string ,
"parsedCertificate" ?: Certificate
]
}
} Authentication Certificate
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 and authentication. 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 service can be called:
Copy generic .authenticationCertificate ( module , parseCertsBoolean , callback); Response:
Copy {
success : true ,
data : {
certificate ?: string ,
certificates ?: Array < string > ,
certificateType ?: string ,
id ?: string ,
parsedCertificate ?: Certificate ,
parsedCertificates ?: Array < Certificate >
}
} You can also fetch the root certificate via the function authenticationCertificateExtended this has the capabilities to return multiple certificates if the token has multiple of this type.
The response looks like:
Copy {
"success" : true
"data" : {
"certificates" : [
"certificate" ?: string ,
"certificateType" ?: string ,
"id" ?: string ,
"subject" ?: string ,
"issuer" ?: string ,
"serialNumber" ?: string ,
"url" ?: string ,
"hashSubPubKey" ?: string ,
"hashIssPubKey" ?: string ,
"exponent" ?: string ,
"remainder" ?: string ,
"parsedCertificate" ?: Certificate
]
}
} Intermediate Certificate (citizen)
Contains the citizen certificate stored on the smart card. The 'citizen certificate' is used to sign the 'authentication certificate' and the 'non-repudiation 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 service can be called:
Copy generic .intermediateCertificates ( module , parseCertsBoolean , callback); Response:
Copy {
success : true ,
data : {
certificate ?: string ,
certificates ?: Array < string > ,
certificateType ?: string ,
id ?: string ,
parsedCertificate ?: Certificate ,
parsedCertificates ?: Array < Certificate >
}
} You can also fetch the root certificate via the function intermediateCertificateExtended this has the capabilities to return multiple certificates if the token has multiple of this type.
The response looks like:
Copy {
"success" : true
"data" : {
"certificates" : [
"certificate" ?: string ,
"certificateType" ?: string ,
"id" ?: string ,
"subject" ?: string ,
"issuer" ?: string ,
"serialNumber" ?: string ,
"url" ?: string ,
"hashSubPubKey" ?: string ,
"hashIssPubKey" ?: string ,
"exponent" ?: string ,
"remainder" ?: string ,
"parsedCertificate" ?: Certificate
]
}
} Non-repudiation Certificate
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. 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 service can be called:
Copy generic .nonRepudiationCertificate ( module , parseCertsBoolean , callback); Response:
Copy {
success : true ,
data : {
certificate ?: string ,
certificates ?: Array < string > ,
certificateType ?: string ,
id ?: string ,
parsedCertificate ?: Certificate ,
parsedCertificates ?: Array < Certificate >
}
}
Copy {
"success" : true
"data" : {
"certificates" : [
"certificate" ?: string ,
"certificateType" ?: string ,
"id" ?: string ,
"subject" ?: string ,
"issuer" ?: string ,
"serialNumber" ?: string ,
"url" ?: string ,
"hashSubPubKey" ?: string ,
"hashIssPubKey" ?: string ,
"exponent" ?: string ,
"remainder" ?: string ,
"parsedCertificate" ?: Certificate
]
}
} The response looks like:
You can also fetch the root certificate via the function nonRepudiationCertificateExtended this has the capabilities to return multiple certificates if the token has multiple of this type.
Encryption Certificate (RRN)
Contains the 'encryption certificate' stored on the smart card. The 'encryption certificate' corresponds to the private key used to sign the 'biometric' and 'Address' data. 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 service can be called:
Copy generic .encryptionCertificate ( module , parseCertsBoolean , callback); Response:
Copy {
success : true ,
data : {
certificate ?: string ,
certificates ?: Array < string > ,
certificateType ?: string ,
id ?: string ,
parsedCertificate ?: Certificate ,
parsedCertificates ?: Array < Certificate >
}
} You can also fetch the root certificate via the function encryptionCertificateExtended this has the capabilities to return multiple certificates if the token has multiple of this type.
The response looks like:
Copy {
"success" : true
"data" : {
"certificates" : [
"certificate" ?: string ,
"certificateType" ?: string ,
"id" ?: string ,
"subject" ?: string ,
"issuer" ?: string ,
"serialNumber" ?: string ,
"url" ?: string ,
"hashSubPubKey" ?: string ,
"hashIssPubKey" ?: string ,
"exponent" ?: string ,
"remainder" ?: string ,
"parsedCertificate" ?: Certificate
]
}
} All certificates
Contains the 'encryption certificate' stored on the smart card. The 'encryption certificate' corresponds to the private key used to sign the 'biometric' and 'Address' data. 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 service can be called:
Copy generic .allCerts ( module , parseCertsBoolean , callback); Response:
Copy {
"rootCertificate": {
...
},
"authenticationCertificate": {
...
},
"nonRepudiationCertificate": {
...
},
"intermediateCertificates": {
...
},
"encryptionCertificate": {
...
}
} You can also fetch the root certificate via the function allCertsExtended this has the capabilities to return multiple certificates if the token has multiple of this type.
The response looks like:
Copy {
"success" : true
"data" : {
"rootCertificate" : {
"certificates" : [...]
} ,
"authenticationCertificate" : {
"certificates" : [...]
} ,
"nonRepudiationCertificate" : {
"certificates" : [...]
} ,
"intermediateCertificates" : {
"certificates" : [...]
} ,
"encryptionCertificate" : {
"certificates" : [...]
}
}
} Data Filter
Filter Card Holder Data
All data on the smart card can be dumped at once, or using a filter. In order to read all data at once:
Copy var filter = [];
generic .allData ( module , { filters : filter} , callback); Response:
Copy {
"picture" : {
"picture": "/9j/4AAQSkZJRgABAgEBLAEsAAD/...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"
} ,
"biometric" : {
"birthDate" : "15 JUL 1993" ,
"birthLocation" : "Roeselare" ,
"cardDeliveryMunicipality" : "Avelgem" ,
"cardNumber" : "592124058233" ,
"cardValidityDateBegin" : "27.05.2015" ,
"cardValidityDateEnd" : "27.05.2025" ,
"chipNumber" : "...==" ,
"documentType" : "01" ,
"firstNames" : "Gilles Frans" ,
"name" : "Platteeuw" ,
"nationalNumber" : "..." ,
"nationality" : "Belg" ,
"nobleCondition" : "" ,
"pictureHash" : "...=" ,
"rawData" : "...+axEIuyskBgFySsp/" ,
"sex" : "M" ,
"signature": ".../OlA44h4YCM/h+J14xUCg/98Y9/.../C/RB2dtVbHwFvDuafmr4ZEshTlZTLidHKlISFvFWOtsLAEPCbl5LjfQwcOKe0pDADtHb4IStBnr+aaE8oHsTaKq66Y+zt+AbwdmWOrMA5URKKf7dZkY7jt3h8KZDw36VjcytUgjxVIdqwHsDkmIjK6mJtakIwybS5wn3RiQj33/vgG7JTRZJoKgDXLLTvLZO4qlfA==",
"specialStatus" : "0" ,
"thirdName" : "J" ,
"version" : "0"
} ,
"address" : {
"municipality" : "Hoeselt" ,
"rawData" : "...==" ,
"signature": "...+Evety1PnTE4pqXaHgBxIpk+P8kRL5W3zDV+../../..+YoHBC9KqTmSpl5KULxdnKiyCt+2RyJdzE2wyoymjRmysIhJy1wW9PRnx99S1TFqQLuc0tyBmkBPR4aFqmOq4a7zqd0q2Q1g+BbnwJ4d3oa10ia5+0kBXf0THoXv3HYIHlnwhBMfAtWzPnFrYBuAKTwyl7yBF5IFfXFpGWuVZUTJElgNcmNvsHMnAhVwDw==",
"streetAndNumber" : "Kerkstraat X" ,
"version" : "0" ,
"zipcode" : "3730"
}
} The filter can be used to ask a list of custom data containers. For example, we want to read only the biometric data
Copy var filter = [ 'biometric' ];
generic .allData ( module , { filters : filter } , callback); Response:
Copy {
"biometric" : {
"birthDate" : "15 JUL 1993" ,
"birthLocation" : "Roeselare" ,
"cardDeliveryMunicipality" : "Avelgem" ,
"cardNumber" : "592124058233" ,
"cardValidityDateBegin" : "27.05.2015" ,
"cardValidityDateEnd" : "27.05.2025" ,
"chipNumber" : "...==" ,
"documentType" : "01" ,
"firstNames" : "Gilles Frans" ,
"name" : "Platteeuw" ,
"nationalNumber" : "..." ,
"nationality" : "Belg" ,
"nobleCondition" : "" ,
"pictureHash" : "...=" ,
"rawData" : "...+axEIuyskBgFySsp/" ,
"sex" : "M" ,
"signature": ".../OlA44h4YCM/h+J14xUCg/98Y9/.../C/RB2dtVbHwFvDuafmr4ZEshTlZTLidHKlISFvFWOtsLAEPCbl5LjfQwcOKe0pDADtHb4IStBnr+aaE8oHsTaKq66Y+zt+AbwdmWOrMA5URKKf7dZkY7jt3h8KZDw36VjcytUgjxVIdqwHsDkmIjK6mJtakIwybS5wn3RiQj33/vgG7JTRZJoKgDXLLTvLZO4qlfA==",
"specialStatus" : "0" ,
"thirdName" : "J" ,
"version" : "0"
}
} Filter Certificates
All certificates on the smart card can be dumped at once, or using a filter. In order to read all certificates at once:
Copy var filter = [];
generic .allCerts ( module , parseCerts , { filters : filter} , callback); Response:
Copy {
"rootCertificate" : {
...
} ,
"authenticationCertificate" : {
...
} ,
"nonRepudiationCertificate" : {
...
} ,
"intermediateCertificates" : {
...
} ,
"encryptionCertificate" : {
...
}
} The filter can be used to ask a list of custom data containers. For example, we want to read only the rootCertificate
Copy var filter = [ 'rootCertificate' ];
generic .allCerts ( module , { filters : filter} , callback); Response:
Copy {
"rootCertificate" : {
...
}
} Sign Data
Data can be signed using the Belgian eID smart card. To do so, the T1C-GCL facilitates in:
Retrieving the certificate chain (citizen-certificate, root-certificate and non-repudiation certificate)
Perform a sign operation (private key stays on the smart card)
To get the certificates necessary for signature validation in your back-end:
Copy var filter = null ;
generic .allCerts ( module , { filters : filter} , callback); Response:
Copy {
"rootCertificate" : {
...
} ,
"authenticationCertificate" : {
...
} ,
"nonRepudiationCertificate" : {
...
} ,
"intermediateCertificates" : {
...
} ,
"encryptionCertificate" : {
...
}
} Depending on the connected smart card reader. A sign can be executed in 2 modes:
Using a connected card reader with 'pin-pad' capabilities (keypad and display available)
Using a connected card reader without 'pin-pad' capabilities (no keypad nor display available)
Security consideration: In order to sign a hash, security considerations prefer using a 'pin-pad'.
Sign Hash without pin-pad
When the web or native application is responsible for showing the password input, the following request is used to sign a given hash:
Copy var data = {
"pin" : "..." ,
"algorithm" : "sha1" ,
"data" : "I2e+u/sgy7fYgh+DWA0p2jzXQ7E=" ,
"osDialog" : true
}
generic .sign ( module , data , callback); Response is a base64 encoded signed hash:
Copy {
"success" : true ,
"data" : {
"data" : "W7wqvWA8m9S...="
}
} Sign Hash with pin-pad
When the pin entry is done on the pin-pad, the following request is used to sign a given hash:
Copy var data = {
"algorithm" : "sha1" ,
"data" : "I2e+u/sgy7fYgh+DWA0p2jzXQ7E=" ,
"osDialog" : false
}
generic .sign ( module , data , callback); Response is a base64 encoded signed hash:
Copy {
"success" : true ,
"data" : {
"data" : "W7wqvWA8m9S...="
}
} The core services lists connected readers, and if they have pin-pad capability. You can find more information in the Core Service documentation on how to verify card reader capabilities.
Raw data signing
With the function signRaw you can sign unhashed document data. This means that the Trust1Connector will hash the value itself depending on the provided sign algorithm.
Trust1Connector only supports SHA2 hashing at this point.
When using SHA3, the Trust1Connector will convert to SHA2 implicitly
Below you can find an example
Copy var data = {
"algorithm" : "sha256" ,
"data" : "vl5He0ulthjX+VWNM46QX7vJ8VvXMq2k/Tq8Xq1bwEw=" ,
"osDialog" : false
}
generic .signRaw ( module , data , callback); The function looks the same as a regular sign operation but expects a base64 data object that is unhashed.
Supported hash functions (SHA2) are;
Bulk Signing
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 Sign 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.
Copy const data = {
algorithm: "sha256",
data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
pin: "1234"
}
const bulk = true;
generic.sign(module, data, bulk).then(res => {
}, err => {
console.error(err)
}) Bulk PIN Reset
The PIN set for bulk signing can be reset by calling this method.
Copy generic.resetBulkPin(module).then(res => {
}, err => {
console.error(err)
}) Response will look like:
Copy {
"success": true,
"data": true
} Verify PIN
Verify PIN without pin-pad
When the web or native application is responsible for showing the password input, the following request is used to verify a card holder PIN:
Copy var data = {
"pin":"..."
}
generic.verifyPin(module, data, callback); Response:
Verify PIN with pin-pad
When the pin entry is done on the pin-pad, the following request is used to verify a given PIN:
Copy var data = {}
generic.verifyPin(module, data, callback); Response:
Authentication
The T1C 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.
External Challenge
An external challenge is provided in the data property of the following example:
Copy var data = {
"pin": "...",
"algorithm": "sha1",
"data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E="
}
generic.authenticate(module, data, callback); Response:
Copy {
"success": true,
"data": {
"data" : "W7wqvWA8m9S...="
}
} Take notice that the PIN property can be omitted when using a smart card reader with pin-pad capabilities.
Get valid algorithms to use for Sign or Authenticate
Via the Trust1Connector modules you are able to retrieve available algorithms to use for Signing or Authenticate
Copy generic.allAlgoRefs(module, callback); The response you can expect is a list of algorithms, an example can be found below (the values below are purely examplatory)
Copy {
"success": true,
"data": ["sha1", "sha256"]
