Eherkenning
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 following page describes how you can integrate the Eherkenning module exposed on the Trust1Connector onto your web application.
Interface
export interface AbstractEherkenning {
allCerts(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsResponse) => void): Promise<TokenAllCertsResponse>;
authenticationCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
nonRepudiationCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
allCertsExtended(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsExtendedResponse) => void): Promise<TokenAllCertsExtendedResponse>;
authenticationCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
nonRepudiationCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
validateSignature(body: TokenValidateSignatureRequest, callback?: (error: T1CLibException, data: TokenValidateSignatureResponse) => void): Promise<TokenValidateSignatureResponse>;
verifyPin(body: TokenVerifyPinData, callback?: (error: T1CLibException, data: TokenVerifyPinResponse) => void): Promise<TokenVerifyPinResponse>;
authenticate(body: TokenAuthenticateOrSignData, callback?: (error: T1CLibException, data: TokenAuthenticateResponse) => void): Promise<TokenAuthenticateResponse>;
sign(body: TokenAuthenticateOrSignData, bulk?: boolean, callback?: (error: T1CLibException, data: TokenSignResponse) => void): Promise<TokenSignResponse>;
signRaw(body: TokenAuthenticateOrSignData, bulk?: boolean, callback?: (error: T1CLibException, data: TokenSignResponse) => void): Promise<TokenSignResponse>;
allAlgoRefs(callback?: (error: T1CLibException, data: TokenAlgorithmReferencesResponse) => void): Promise<TokenAlgorithmReferencesResponse>
resetBulkPin(callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
}Token info
You can fetch the token information via the function. this will give all the information of the token you need according to the PKCS11 specifications
module.tokenData().then(res => {
// see response below
}){
"success": true,
"data": {
"info": {
"slot": "string",
"label": "string",
"manufacturerId": "string",
"model": "string",
"serialNumber": "string",
"flags": {
"isRandomNumberGenerator": "boolean",
"isWriteProtected": "boolean",
"isLoginRequired": "boolean",
"isUserPinInitialized": "boolean",
"isRestoreKeyNotNeeded": "boolean",
"isClockOnToken": "boolean",
"isProtectedAuthenticationPath": "boolean",
"isDualCryptoOperations": "boolean",
"isTokenInitialized": "boolean",
"isSecondaryAuthentication": "boolean",
"isUserPinCountLow": "boolean",
"isUserPinFinalTry": "boolean",
"isUserPinLocked": "boolean",
"isUserPinToBeChanged": "boolean",
"isSoPinCountLow": "boolean",
"isSoPinFinalTry": "boolean",
"isSoPinLocked": "boolean",
"isSoPinToBeChanged": "boolean"
},
"mechanisms": [
{
"mechanism": "string",
"flags": {
"isHardware": "boolean",
"isEncrypt": "boolean",
"isDecrypt": "boolean",
"isDigest": "boolean",
"isSign": "boolean",
"isSignRecover": "boolean",
"isVerify": "boolean",
"isVerifyRecover": "boolean",
"isGenerate": "boolean",
"isGenerateKeyPair": "boolean",
"isWrap": "boolean",
"isUnwrap": "boolean",
"isExtension": "boolean",
"isEcFP": "boolean",
"isEcNamedcurve": "boolean",
"isEcUncompress": "boolean",
"isEcCompress": "boolean"
},
"ulMinKeySize": "number",
"ulMaxKeySize": "number"
}
],
"ulMaxSessionCount": "number",
"ulSessionCount": "number",
"ulMaxRwSessionCount": "number",
"ulMaxPinLen": "number",
"ulMinPinLen": "number",
"ulTotalPubLicMemory": "number",
"ulFreePubMemory": "number",
"ulTotalPrivateMemory": "number",
"ulFreePrivateMemory": "number",
"hardwareVersion": "string",
"firmwareVersion": "string"
},
"infoType": "TokenInfoType"
}
}
//ENUM
TokenInfoType {
Token,
PKCS11,
File,
Payment,
HSM,
Vault,
Wallet,
}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
allCertsExtended(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsExtendedResponse) => void): Promise<TokenAllCertsExtendedResponse>;
authenticationCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
nonRepudiationCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
encryptionCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
rootCertificateExtended(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:
{
"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;
{
"success" : true
"data" : {
"authenticationCertificate": {
"certificates": [...]
},
"nonRepudiationCertificate": {
"certificates": [...]
},
"encryptionCertificate": {
"certificates": [...]
},
"rootCertificate": {
"certificates": [...]
}
}
}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:
generic.authenticationCertificate(module, parseCertsBoolean, callback);Response:
{
success: true,
data: {
certificate?: string,
certificates?: Array<string>,
certificateType?: string,
id?: string,
parsedCertificate?: Certificate,
parsedCertificates?: Array<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:
generic.nonRepudiationCertificate(module, parseCertsBoolean, callback);Response:
{
success: true,
data: {
certificate?: string,
certificates?: Array<string>,
certificateType?: string,
id?: string,
parsedCertificate?: Certificate,
parsedCertificates?: Array<Certificate>
}
}Encryption Certificate
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:
generic.nonRepudiationCertificate(module, parseCertsBoolean, callback);Response:
{
success: true,
data: {
certificate?: string,
certificates?: Array<string>,
certificateType?: string,
id?: string,
parsedCertificate?: Certificate,
parsedCertificates?: Array<Certificate>
}
}Root Certificate/Issuer Certificate
Contains the 'root certificate' or 'Issuer certificate stored on the smart card. The service can be called:
generic.rootCertificate(module, parseCertsBoolean, callback);Response:
{
success: true,
data: {
certificate?: string,
certificates?: Array<string>,
certificateType?: string,
id?: string,
parsedCertificate?: Certificate,
parsedCertificates?: Array<Certificate>
}
}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:
var filter = [];
generic.allCerts(module, parseCerts, { filters: filter}, callback);Response:
{
"authenticationCertificate": {
...
},
"nonRepudiationCertificate": {
...
},
"encryptionCertificate": {
...
}
}The filter can be used to ask a list of custom data containers. For example, we want to read only the rootCertificate
var filter = ['authenticationCertificate'];
generic.allCerts(module, { filters: filter}, callback);Response:
{
"authenticationCertificate": {
...
}
}Sign Data
To get the certificates necessary for signature validation in your back-end:
var filter = null;
module.allCerts({ filters: filter}, callback);Response:
{
"authenticationCertificate": {
...
},
"nonRepudiationCertificate": {
...
}
}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'.
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
var data = {
"algorithm":"sha256",
"data":"vl5He0ulthjX+VWNM46QX7vJ8VvXMq2k/Tq8Xq1bwEw=",
"osDialog": false
}
module.signRaw(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;
SHA256
SHA384
SHA512
Sign data 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:
var data = {
"pin":"...",
"algorithm":"sha256",
"data":"n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="
"osDialog": true
}
module.sign(data, callback);Response is a base64 encoded signed hash:
{
"success": true,
"data": {
"data" : "W7wqvWA8m9S...="
}
}The 'authenticationreference' property can contain the following values: sha1, sha256, sha512, md5.
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:
var data = {
"algorithm": "sha256",
"data":"n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="
"osDialog": false
}
module.sign(data, callback);Response is a base64 encoded signed hash:
{
"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
Validate signature
The module allows you to call a function on the token that can validate a signature. For this we need to use the validateSignature function. You can call this one via;
const body = {
"algorithm": 'sha256',
"hash": '...',
"signedHash": '...',
"osDialog": false,
"id": 'cert_id',
"pin": 'pin_code',
"timeout": 120 //timeout in seconds
}
safenet.validateSignature(body).then(response => {
response.valid
).catch(error => {
errorHandler(error)}
)The response of this function will return a valid property that is either true or false.
{
"success": true,
"data": {
"valid": true
}
}Last updated
Was this helpful?