Aventra

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

Interface Summary

The Abstract Aventra smartcard interface is summarized in the following snippet:

interface AbstractAventra{
    allDataFilters():Array<string>;
    allCertFilters():Array<string>;
    allKeyRefs():Array<string>;
    allAlgoRefsForAuthentication(callback:(error:CoreExceptions.RestException, data:any) => void):void;
    allAlgoRefsForSigning(callback:(error:CoreExceptions.RestException, data:any) => void):void;
    allCerts({ filters:string[], parseCerts: boolean }, callback:(error:CoreExceptions.RestException, data:any) => void):void;
    rootCertificate({ parseCerts: boolean }, callback:(error:CoreExceptions.RestException, data:any) => void):void;
    issuerCertificate({ parseCerts: boolean },callback:(error:CoreExceptions.RestException, data:any) => void):void;
    authenticationCertificate({parseCerts: boolean }, callback:(error:CoreExceptions.RestException, data:any) => void):void;
    signingCertificate({ parseCerts: boolean }, callback:(error:CoreExceptions.RestException, data:any) => void):void;
    encryptionCertificate({ parseCerts: boolean }, callback:(error:CoreExceptions.RestException, data:any) => void):void;
    verifyPin(body:any,callback:(error:CoreExceptions.RestException, data:any) => void):void;
    resetPin(body:any,callback:(error:CoreExceptions.RestException, data:any) => void):void;
    signData(body:any,callback:(error:CoreExceptions.RestException, data:any) => void):void;
    authenticate(body:any,callback:(error:CoreExceptions.RestException, data:any) => void):void;
}

Retrieve a connected card reader

In order to start with any use case, we need to select a card reader. The targeted reader will be passed as a parameter to the subsequent methods provided. This is part of the core Trust1Connector functionality. More information about core service functionality can be found on the following page: Core Services.

For demonstration purpose we'll add a simple console output callback, which we'll use throughout the documentation.

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

Just as an example, we instantiate a new gcl (local client) and ask for all connected smart card readers:

GCLLib.GCLClient.initialize(config, function(err, gclClient) {
    gclClient.core().readers(callback);
});

This will returns us all connected readers:

{
  "data": [
    {
      "card": {
        "atr": "3BF51800008131FE454D794549449A",
        "description": [
          "Aventra ActiveSecurity MyEID"
        ]
      },
      "id": "2e49386c82131cc1",
      "name": "Gemalto Ezio Shield",
      "pinpad": true
    }
  ],
  "success": true
}

In the example you'll notice that we are using a dual interface uTrust reader, and a card has been inserted.

The reader id '2e49386c82131cc1' can be used as parameter in the next steps in order to select a smartcard reader for the functionality we want to execute.

Applet information

The following call can be done in order to retrieve the Aventra applet information on the card:

var filter = ['applet-info'];
gclClient.aventra(reader_id).allData(filter,callback);

Example response:

{
  "data": {
    "applet_info": {
      "change_counter": 77,
      "name": "MyEID",
      "serial": "00006064024681982647",
      "version": "3.3.3"
    }
  },
  "success": true
}

Certificates

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

T1C-JS will return the raw base64 certificate and the ID of the certificate., optionally it can also return an object representing the certificate as parsed by PKI.js. To enable parsing, parseCerts must be set to true. The ID will be required by the signature functions as it indicates which private key linked to the certificate will be used to perform the signing.

Certificate Chain

Root Certificate

Contains the 'root certificate' stored on the smart card. The service can be called:

gclClient.aventra(reader_id).rootCertificate({ parseCerts: true }, callback);

Response:

{
  "data": {
    "base64": "MIIFwzCCA6ugAwIBAgIU....OAgwrr",
    "id": "56",
    "parsed": { // parsed certificate object }
  },
  "success": true
}

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, authentication and signing. In the response the whole certificate chain will be returned, with the authentication certificate as the first item. The service can be called:

gclClient.aventra(reader_id).authenticationCertificate({ parseCerts: true }, callback);

Response:

{
  "data": [{
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", 
    "id": "45",
    "parsed": { // parsed certificate object }
  },{
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", 
    "id": "55",
    "parsed": { // parsed certificate object }
  },{
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", 
    "id": "56",
    "parsed": { // parsed certificate object }
  }],
  "success": true
}

Signing 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. In the response the whole certificate chain will be returned, with the signing certificate as the first item. The service can be called:

gclClient.aventra(reader_id).signingCertificate({ parseCerts: true }, callback);

Response:

{
  "data": [{
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", 
    "id": "46",
    "parsed": { // parsed certificate object }
  },{
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", 
    "id": "55",
    "parsed": { // parsed certificate object }
  },{
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", 
    "id": "56",
    "parsed": { // parsed certificate object }
  }],
  "success": true
}

Issuer Certificate

The service can be called:

gclClient.aventra(reader_id).issuerCertificate({ parseCerts: true }, callback);

Response:

{
  "data": {
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
    "id": "55",
    "parsed": { // parsed certificate object }
  },
  "success": true
}

Encryption Certificate

In the response the whole certificate chain will be returned, with the encryption certificate as the first item.

The service can be called:

gclClient.aventra(reader_id).encryptionCertificate({ parseCerts: true }, callback);

Response:

{
  "data": [{
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", 
    "id": "47",
    "parsed": { // parsed certificate object }
  },{
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", 
    "id": "55",
    "parsed": { // parsed certificate object }
  },{
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", 
    "id": "56",
    "parsed": { // parsed certificate object }
  }],
  "success": true
}

Data Filter

Available Data Filters

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

Response:

{
  "data": {
    "applet_info": {
      "change_counter": 77,
      "name": "MyEID",
      "serial": "00006064024681982647",
      "version": "3.3.3"
    },
    "authentication_certificate": {
      "base64": "MIIFjjCCA3agAwI...323424321123+M+xeIctrC0WnP7u4xg==",
      "id": "45",
      "parsed": { // parsed certificate object }
    },
    "encryption_certificate": {
      "base64": "MIIFjjCCA3agAwI...dffTESD32331+M+xeIctrC0WnP7u4xg==",
      "id": "47",
      "parsed": { // parsed certificate object }
    },
    "signing_certificate": {
      "base64": "MIIFjjCCA3agAwI...rTBDdrlEDEaLrY+M+xeIctrC0WnP7u4xg==",
      "id": "46",
      "parsed": { // parsed certificate object }
    },
    "issuer_certificate": {
      "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
      "id": "47",
      "parsed": { // parsed certificate object }
    },
    "root_certificate": {
      "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
      "id": "56",
      "parsed": { // parsed certificate object }
    }
  },
  "success": true
}

The filter can be used to ask a list of custom data containers. For example, we want to read only the 'root-certificate' and the 'authentication_certificate':

var filter = ['authentication-certificate','signing_certificate'];
gclClient.aventra(reader_id).allCerts({ filters: filter, parseCerts: true }, callback);

Response:

{
  "data": {
    "authentication_certificate": {
      "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
      "id": "45",
      "parsed": { // parsed certificate object }
    },
    "signing_certificate": {
      "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
      "id": "46",
      "parsed": { // parsed certificate object }
    }
  },
  "success": true
}

Verify PIN

Without a pinpad

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":"...",
      "private_key_reference": "authenticate"
}
gclClient.aventra(reader_id).verifyPin(data, callback);

The allowed values for private_key_referenceare authenticate, sign and encrypt. These values allow you to indicate which PIN code you want to verify.

Response:

{
  "success": true
}

With a pinpad

When the pin entry is done on the pin-pad, the following request is used to verify a card holder PIN:

var data = {
    "private_key_reference": "authenticate"
}
gclClient.aventra(reader_id).verifyPin(data, callback);

Response:

{
    "success": true
}

Reset PIN

When the web or native application is responsible for showing the password input, the following request is used to reset a PIN using the PUK code when the PIN is blocked:

var data = {
      "puk":"...",
      "new_pin":"...",
      "private_key_reference": "authenticate"
}
gclClient.aventra(reader_id).resetPin(data, callback);

The allowed values for private_key_referenceare authenticate, sign and encrypt. These values allow you to indicate which PIN code you want to reset.

Response:

{
  "success": true
}

The possible "private_key_reference" values can be retrieved calling:

gclClient.aventra.allKeyRefs() //returns Array<string>

Sign Data

Data can be signed using the Aventra smartcard. To do so, the T1C-GCL 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 hash

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

var filter = [];
gclClient.aventra(reader_id).allCertificates({ filters: filter, parseCerts: false }, callback);

Response:

{
  "authentication_certificate": {
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
    "id": "45"
  },
  "encryption_certificate": {
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
    "id": "47"
  },
  "issuer_certificate": {
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
    "id": "55"
  },
  "root_certificate": "{
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
    "id": "56"
  },
  "signing_certificate": {
    "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
    "id": "46"
  },
}

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'.

Signing algorithm references supported by the card

In order to verify which algorithm can be used for a 'sign' operation, you can call the following method:

gclClient.aventra(reader_id).allAlgoRefsForSigning(callback);

Example response:

{
  "data": [
    "SHA1",
    "SHA256",
    "SHA512"
  ],
  "success": true
}

Sign Hash

In the sign data, you'll need to pass the identifier (id) of the signing certificate which is retrieved by the certificate endpoints.

Without a pinpad

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_reference":"sha1",
      "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
      "id": "46"
}
gclClient.aventra(reader_id).signData(data, callback);

Response is a base64 encoded signed hash:

{
  "success": true,
  "data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="
}

With a pinpad

When the pin entry is done on the pin-pad, the following request is used to sign a given hash:

var data = {
    "algorithm_reference":"sha1",
    "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
    "id": "46"
}
gclClient.aventra(reader_id).signData(data, callback);

Response is a base64 encoded signed hash:

{
    "success": true,
    "data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="
}

The 'algorithm_reference' property can contain the following values: sha1, sha256 and sha512.

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.

Calculate Hash

In order to calculate a hash from the data to sign, you need to know the algorithm you will use in order to sign. You might have noticed the algorithm_reference property provided in the sign request. The algorithm_reference can be one of the values: sha1, sha256 and sha512. For example, we want the following text to be signed using:

This is sample text to demonstrate siging with Aventra smartcard

You can use the following online tool to calculate the SHA1: http://www.sha1-online.com

Hexadecimal result:

OTY4ODM2ODg3ODg3YWViYzdlZDBiMDgwMjQxZGQ5N2M4N2ZlMWRhZQ==

Notice that the length of the SHA1 is always the same. Now we need to convert the hexadecimal string to a base64-encoded string, another online tool can be used for this example: hex to base64 converter

Base64-encoded result:

OTY4ODM2ODg3ODg3YWViYzdlZDBiMDgwMjQxZGQ5N2M4N2ZlMWRhZQ==

Now we can sign the data:

var data = {
      "pin":"...",
      "algorithm_reference":"sha1",
      "data":"OTY4ODM2ODg3ODg3YWViYzdlZDBiMDgwMjQxZGQ5N2M4N2ZlMWRhZQ==",
      "id": "46"
}
gclClient.aventra(reader_id).signData(data, callback);

Result:

{
  "data": "C7SG5eix1+lzMcZXgL0bCL+rLxKhd8ngrSj6mvlgooWH7CloEU13Rj8QiQHdhHnZgAi4Q0fCMIqAc4dn9uW9OP+MRitimRpYZcaDsGrUehPi/JpOD1e+ko7xKZ67ijUU4KTmG4HXc114oJ7xxx3CGL7TNFfvuEphLbbZa+9IZSSnYDOOENJqhggqqu7paSbLJrxC2zaeMxODKb5WSexHnZH6NnLPl2OmvPTYtxiTUMrLbFRsDRAziF6/VQkgM8/xOm+1/9Expv5DSLRY8RQ+wha6/nMlJjx50JszYIj2aBQKp4AOxPVdPewVGEWF4NF9ffrPLrOA2v2d7t5M4q7yxA==",
  "success": true
}

Authentication

The T1C-GCL 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.

Authentication algorithm references supported by the card

In order to verify which algorithm can be used for a 'sign' operation, you can call the following method:

gclClient.aventra(reader_id).allAlgoRefsForAuthentication(callback);

Example response:

{
  "data": [
    "SHA1",
    "SHA256",
    "SHA512"
  ],
  "success": true
}

External Challenge

Without a pinpad

An external challenge is provided in the data property of the following example:

var data = {
  "pin": "...",
  "algorithm_reference": "sha1",
  "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
  "id": "45"
}
gclClient.aventra(reader_id).authenticate(data, callback);

Response:

{
"success": true,
"data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="
}

Without a pinpad

An external challenge is provided in the data property of the following example:

var data = {
    "algorithm_reference": "sha1",
    "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
    "id": "45"
}
gclClient.aventra(reader_id).authenticate(data, callback);

Response:

{
    "success": true,
    "data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="
}

The 'algorithm_reference' property can contain the following values: sha1, sha256 and sha512.

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.

Error Handling

Error Object

The functions specified are asynchronous and always need a callback function. The callback function will reply with a data object in case of success, or with an error object in case of an error. An example callback:

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

The error object returned:

{
  success: false,
  description: "some error description",
  code: "some error code"
}

For the error codes and description, see Status codes.

PreviousPKINextLuxTrust SmartCard/Signing Stick

Last updated