arlpEid JS

A JS library for authenticating and signing with the Estonian ID card and Mobile ID. Currently, the package supports signing by ID card. Still to implement:

• Authentication by ID card
• Authentication by Mobile ID
• Signing by Mobile ID

To install: npm install https://bitbucket.org/maagiline/arlp-eid-js/ --save

Demo mode

Enabling demo mode allows to use this library without access to an actual Estonian ID card. Demo mode should never be enabled in production.

In demo mode, no signature is actually given. Whenever signing is initiated, it is considered to be successful.

When in demo mode, you may specify who the arlpEid service will return as the authenticated user:

curl -X POST \
  https://arlp-eid.maagiline.ee/demo/authenticatable \
  -H 'Content-Type: application/json' \
  -d '{
	"firstName": "Kimo",
	"lastName": "Kerr",
	"ssn": "39104090041"
}'

Examples

Initialize

import ArlpEid from 'arlp-eid'
const arlpEidUrl = 'https://arlp-eid.maagiline.ee'
const isDemo = true
const arlpEid = new ArlpEid(arlpEidUrl, isDemo)

Sign by ID card

const lang = 'et'
const containerId = 1
arlpEid.sign.idCard.sign(lang, containerId).then(() => {
    console.log('Signing was successful')
}).catch(e => {
    console.log('Signing failed', e)
})

Authenticate by ID card

const lang = 'et'
arlpEid.authenticate.idCard.getPerson(lang).then((personData) => {
    console.log('Auth was successful. ', personData)
    // Auth was successful. {"firstName":"Kimo","lastName":"Kerr","socialSecurityNumber":"39104090041","timestamp":1543426131,"hmac":"243fe31badfa2e4e4d703866017b910dff37fb96815f573a2506c21c04c97ad7ab332040e19383a4ceec022be8e50eb461fad3be11af0d3d6821048585f37238"}
}).catch(e => {
    console.log('Auth failed', e)
})

Workflow

Estonian ID signing is done via containers. Container wraps the original document in a file that can be signed. In the ARLP system, we need to keep containers for each document. When a signature is added, the container file will be overwritten with a new container, this one containing the new signature.

Workflow: ID card authenticate

Below is a scheme of the workflow of ID card authentication. Areas with black color are areas that need to be integrated with / implemented in the ARLP system. Areas in gray color are those handled by the ArlpEID JS package and ArlpEID back-end.

For hmac validation, a secret string key will be provided. On the demo server (arlp-eid.maagiline.ee), the key is the following: E)H@MbQeThWmZq4t7w!z%C*F-JaNdRfUjXn2r5u8x/A?D(G+KbPeShVkYp3s6v9y

Workflow: ID card sign

Below is a scheme of the workflow of ID card signing. Areas with black color are areas that need to be integrated with / implemented in the ARLP system. Areas in gray color are those handled by the ArlpEID JS package and ArlpEID back-end.

Checking hash

When sends their authentication data, we must ensure that this data was approved by the arlpEid server. We do this by validating the hmac that was sent from the arlpEid server:

// The data sent by client
$personData = {"firstName":"Kimo","lastName":"Kerr","socialSecurityNumber":"39104090041","timestamp":1543426131,"hmac":"243fe31badfa2e4e4d703866017b910dff37fb96815f573a2506c21c04c97ad7ab332040e19383a4ceec022be8e50eb461fad3be11af0d3d6821048585f37238"}

// Concat values of firstName, lastName, socialSecurityNumber, timestamp: KimoKerr391040900411543426131
$personDataConcat = 

create hmac using key and sha512: $soughtHash = hash_hmac('sha512','KimoKerr391040900411543426131','E)H@MbQeThWmZq4t7w!z%C*F-JaNdRfUjXn2r5u8x/A?D(G+KbPeShVkYp3s6v9y')

Check hmac against the one sent by client, using hash_equals: $clientHashIsValid = hash_equals($soughtHash, $clientHash)

Testing this package

To test this package, maagiline/arlp-eid-js-test repo is available, which provides a html+JS front-end for testing this package in conjunction with the arlpEid back-end.