Safenet*

Introduction

The following page describes how you can integrate the Safenet module exposed on the Trust1Connector onto your web application.

Middleware of Safenet has to be installed to be able to fully use the Safenet token.

Supported version of the middleware is; Windows: 10.2 - 64bit & 32bit MacOS: 10.2

Interface

export interface AbstractSafenet {
    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>;
    tokenData(callback?: (error: T1CLibException, data: TokenInfoResponse) => void): Promise<TokenInfoResponse>;
}

Models

All model information can be found in the Token typings model page

Get Safenet container object

Initialise a Trust1Connector client:

T1CSdk.T1CClient.initialize(config).then(res => {
    client = res;
}, err => {
    console.error(error)
});

Get the container service:

var client = client.safenet(reader_id);

Call a function for the Belgian eID container:

function callback(err,data) {
    if(err){console.log("Error:",JSON.stringify(err, null, '  '));}
    else {console.log(JSON.stringify(data, null, '  '));}
}
beid.biometric(callback);

Obtain the Reader-ID

The constructor for the Belgian eID expect as the parameter to be a valid reader-ID. A reader-ID can be obtained from the exposed core functionality, for more information see Core services responds with available card-readers, available card in a card-reader, etc. For example: In order to get all connected card-readers, with available cards:

var core = client.core();
core.readersCardAvailable(callback);

This function call returns:

{
  "data": [
    {
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": [""]
      },
      "id": "57a3e2e71c48cee9",
      "name": "JC Token",
      "pinpad": false
    }
  ],
  "success": true
}

All methods for safenet will use the selected reader - identified by the reader_id.

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

client.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>;

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": [...]
        },
   }
}

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:

client.beid(reader_id).rootCertificate(parseCertsBoolean, callback);

Response:

{
    success: true,
    data: {
        certificate?: string,
        certificates?: Array<string>,
        certificateType?: string,
        id?: string,
        parsedCertificate?: Certificate,
        parsedCertificates?: Array<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:

client.beid(reader_id).authenticationCertificate(parseCertsBoolean, callback);

Response:

{
    success: true,
    data: {
        certificate?: string,
        certificates?: Array<string>,
        certificateType?: string,
        id?: string,
        parsedCertificate?: Certificate,
        parsedCertificates?: Array<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:

client.beid(reader_id).intermediateCertificates(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:

client.beid(reader_id).nonRepudiationCertificate(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:

client.beid(reader_id).encryptionCertificate(parseCertsBoolean, callback);

Response:

{
    success: true,
    data: {
        certificate?: string,
        certificates?: Array<string>,
        certificateType?: string,
        id?: string,
        parsedCertificate?: Certificate,
        parsedCertificates?: Array<Certificate>
    }    
}

Data Filter

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 = [];
client.beid(reader_id).allCerts(parseCerts, { filters: filter}, callback);

Response:

{
 "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

var filter = ['rootCertificate'];
client.safenet(reader_id).allCerts(parseCerts, { filters: filter}, callback);

Response:

{
 "rootCertificate": {
  ...
 }
}

Sign Data

Signing

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)

• Return the signed hash

To get the certificates necessary for signature validation in your back-end:

var filter = null;
client.safenet(reader_id).allCerts(parseCerts, { filters: filter}, callback);

Response:

{
 "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)

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:

var data = {
      "pin":"...",
      "algorithm":"sha1",
      "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
      "osDialog": true
}
client.safenet(reader_id).sign(data, callback);

Response is a base64 encoded signed hash:

{
  "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:

var data = {
      "algorithm":"sha1",
      "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
      "osDialog": false
}
client.safenet(reader_id).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.

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
}
client.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

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:

var data = {
      "pin":"..."
}
client.safenet(reader_id).verifyPin(data, callback);

Response:

{
  "verified": true
}

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:

var data = {}
client.safenet(reader_id).verifyPin(data, callback);

Response:

{
  "verified": true
}

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:

  var data = {
    "pin": "...",
    "algorithm": "sha1",
    "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E="
  }
  client.safenet(reader_id).authenticate(data, callback);

  Response:

  {
    "success": true,
    "data": {
      "data" : "W7wqvWA8m9S...="
    }
  }

  Take notice that the PIN property can be omitted when using a smart card reader with pin-pad capabilities. The 'algorithm_reference' property can contain the following values: sha1, sha256, sha512, md5.

  Generated Challenge

  A server generated challenge can be provided to the JavaScript library. In order to do so, an additional contract must be provided with the 'OCV API' (Open Certificate Validation API).

The calculated digest of the hash is prefixed with:
DigestInfo ::= SEQUENCE {
      digestAlgorithm AlgorithmIdentifier,
      digest OCTET STRING
  }
Make sure this has been taken into consideration in order to validate the signature in a backend process.

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

client.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)

{
    "success": true,
    "data": ["sha1", "sha256"]
}

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
}
client.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
    }
}