eID Easy Docs

e-Seal on-premises setup guide

eID Easy document signing e-Seal application is app that you can run in your own machine and in your own environment. This means that it is under your sole control as it is supposed to according to eIDAS regulation. Our reference appliance is built with Raspberry PI and Yubikey FIPS. This device does not need to run in the datacenter and it can even be located next to your WiFi router or in your locked switch cabinet.

Steps to get it running.

  1. Generate keypair and Certificate Signing Request
  2. Order document signing certificat and import certificate to the Yubikey
  3. Install Ubuntu server to Raspberry PI and install all dependencies using Cloud Init
  4. Examine Yubikey and identify needed token parameters
  5. Configure Yubikey environment parameters and run docker machine
  6. Configure network routing

1. Generate keypair and CSR on the Yubikey HSM

Easiest way to manage your Yubikeys is using Yubikey Manager app that can be downloaded from https://www.yubico.com/products/services-software/download/yubikey-manager/open in new window

There are OTP, FIDO2 and PIV applications. We are working with PIV (Personal Identity Verification)

yubico application download screenshot

Once PIV application is selected then go to Digital Signature and click Generate. Choose “Certificate Signing Request (CSR)” and for algorithm RSA2048 if you order certificates from SK. Next you will be asked subject name, write there what you want to be most prominent in signed document. For example “Signed by My Company”

yubico application certificates management screenshot

2. Order Document signing e-Seal certificate

From previous step you got CSR file. Next step is to go to some eIDAS and AATL (Adobe Approved Trust List) trust service provider and order your digital stamp document signing certificate.

You will need to provide details about your company (or person, if you want personal signing certificate) and if trust service provider believes that you can represent this company then they will give you the certificate for some fee. Once you get the certificate then open Yubikey Manager and import the certificate to the Digital Signature (Slot 9c). With this your token is ready for use.

3. Install Ubuntu server to Raspberry PI and install all dependencies using Cloud Init

Raspberry PI is perfect for eIDAS Qualified e-Seal appliance as you can keep it in your office in secure location and have full and sole control over it.

Install Raspberry PI imager that will help you flash the memory card. Unfortunately latest Ubuntu LTS 20.04.1 has issues when connecting to during first boot. If you are connecting Raspberry PI using Ethernet cable then choose this version. If you will connect wifi, then take Ubuntu 20.10.

raspberry pi setup screenshot

After flashing the memory card you need to edit 2 files on system-boot partition on the memory card.

  • user-data – will be used to create initial use, import your SSH key and installing needed packages.
  • network-config – this contains Netplan ethernet and WiFi configuration info. If only ethernet is used then it does not need to be modified.

Minimal cloud-init config file looks like below. Make sure the “#cloud-config” is on top, otherwise the Cloud init config file will not be recognized.

#cloud-config

## Create default user ubuntu with default password Ubuntu that needs to be changed during first login
chpasswd:
  list:
    - ubuntu:ubuntu

## Add this SSH key for logging in to the Raspberry
ssh_authorized_keys:
  - ssh-rsa AAAAB3Nz....FzDTkv6J my-admin-computer

## Install docker on boot
packages:
  - docker.io

Once these configurations have been updated then insert the memory card to the Raspberry PI and boot it up.

4. Examine Yubikey and identify needed HSM token parameters

We will be using opensc and pkcs11-tool for that. We need token label and object ID. You can do this in any machine. However it is not recommended to install opensc to the Rasberry host OS as it might create issues when using USB inside the docker machine.

For Yubikey PKCS#11 module you need to install yubiko-piv-tool

sudo apt install yubico-piv-tool

pkcs11-tool -L gives us general details of the token. Here we see that the “token label” is “YubiKey PIV #13650870”

$ pkcs11-tool --module /usr/lib/libykcs11.so -L
Available slots:
Slot 0 (0x0): Yubico YubiKey OTP+FIDO+CCID 01 00
  token label        : YubiKey PIV #13650870
  token manufacturer : Yubico (www.yubico.com)
  token model        : YubiKey YK5
  token flags        : login required, rng, token initialized, PIN initialized
  hardware version   : 1.0
  firmware version   : 5.24
  serial num         : 13650870
  pin min/max        : 6/48

We will find our the ID of the private key and the certificate, which in this case is “02”. There is another attestation key with same id, but we take only first certificate.

$ pkcs11-tool --module /usr/lib/libykcs11.so --list-objects --type privkey --login
Using slot 0 with a present token (0x0)
Logging in to "YubiKey PIV #13650870".
Please enter User PIN: 
Private Key Object; RSA 
  label:      Private key for Digital Signature
  ID:         02
  Usage:      decrypt, sign
  Access:     always authenticate, sensitive, always sensitive, never extractable, local
Private Key Object; RSA 
  label:      Private key for PIV Attestation
  ID:         19
  Usage:      none
  Access:     sensitive, always sensitive, never extractable

$ pkcs11-tool --module /usr/lib/libykcs11.so --list-objects --type cert
Using slot 0 with a present token (0x0)
Certificate Object; type = X.509 cert
  label:      X.509 Certificate for Digital Signature
  subject:    DN: organizationIdentifier=NTREE-14080014/serialNumber=14080014, ST=Harjumaa, L=Tallinn, C=EE, O=EID Easy O\xC3\x9C, CN=eID Easy test seal
  ID:         02
Certificate Object; type = X.509 cert
  label:      X.509 Certificate for PIV Attestation
  subject:    DN: CN=Yubico PIV Attestation
  ID:         19
Certificate Object; type = X.509 cert
  label:      X.509 Certificate for PIV Attestation 9c
  subject:    DN: CN=YubiKey PIV Attestation 9c
  ID:         02

5. Configure Yubikey environment parameters and run docker machine

Now when the Raspberry PI has been booted up it has connected to network and most likely got the IP using DHCP. If you are in the same network then you can find the IP using arp command. We know that Raspberry PI 4 MAC address starts with dc:a6:32 . If the IP is known then we login to the PI configure docker environment variables and start the image.

$ arp -ne |grep dc:a6:32
192.168.8.251            ether   dc:a6:32:6a:d3:df   C                     enx3ce1a1c2a821
$ ssh ubuntu@192.168.8.251

We can add all environment variables in one place, for example .env-eseal in the home folder. It could look something like that.

key_id.card.hsm_implementation=pkcs11
key_id.card.hmac_key=413140d54372f9baf481d4c54e2d5c7bcf28fd6087000280e07976121dd54af2
key_id.card.pkcs11-path=/usr/lib/aarch64-linux-gnu/libykcs11.so 
key_id.card.token-label=YubiKey PIV #13650853
key_id.card.object-id=02
key_id.card.password_url=https://example.com:5555/remote-pin?token=123456

Now download and start the docker machine using following command. It will take about 15 seconds to boot up and start listening to the port.

sudo docker run -d --env-file ~/.env-eseal --device=/dev/bus/usb -p 8080:8082 --name=eideasy_eseal --restart always --log-driver syslog --log-opt tag="{{.Name}}/{{.ID}}" eideasy/eseal

You can also build the docker machine from source https://github.com/eideasy/e-seal-digital-signature-serviceopen in new window

Keep in mind that after you change environment variables then you need to recreate the docker machine. Easiest way for that is

sudo docker stop eideasy_eseal -t 0
sudo docker rm eideasy_eseal 
sudo docker run -d --env-file ~/.env-eseal --device=/dev/bus/usb -p 8080:8082 --name=eideasy_eseal --restart always --log-driver syslog --log-opt tag="{{.Name}}/{{.ID}}" eideasy/eseal

6. Configure network routing

Since eID Easy needs to send API calls from its server then you need to configure port forwarding and open the port in firewall. eID Easy IPv4 IPs are currently: 52.211.100.22, 52.16.77.106, 63.35.4.45, 63.34.102.230, 54.78.97.68, 52.212.172.233

Once this is done then forward e-Seal service access details to eID Easy team

E-Seal sample config file

# Load passwords for these keyId-s during application boot
# Especially useful if remote PIN loading is used and you run the remote PIN source only for limited time
init_signers=card

# Chooses the HSM protocol implementation, usually pkcs11 for local physical smart card or USB crypto token
key_id.card.hsm_implementation=pkcs11

# Agree this value with eID Easy
key_id.card.hmac_key=413140d54372f9baf481d4c54e2d5c7bcf28fd6087000280e07976121dd54af2

# Choose one correct PKCS #11 module for your HSM
key_id.card.pkcs11-path=/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so # ID card
key_id.card.pkcs11-path=/usr/lib/x86_64-linux-gnu/libykcs11.so # Yubikey on PC
key_id.card.pkcs11-path=/usr/lib/aarch64-linux-gnu/libykcs11.so # Yubikey on Raspberry PI
key_id.card.pkcs11-path=/usr/lib/libIDPrimePKCS11.so # Gemalto Safenet 5110 CC eToken

#Get these values from the token using pkcs11-tool
key_id.card.token-label="YubiKey PIV #13650853"
key_id.card.object-id=02

# Optional, default is slot 0. Might be needed with Gemalto Safenet eToken 5110
key_id.card.slot=0x11

# If the device is secure then you can set the token PIN here. If device is stolen then you need to revoke certificate immediately.
key_id.card.password=123456

# For added security you can keep the PIN on remote machine
key_id.card.password_url=https://example.com:5555/remote-pin?token=123456

# Config params if Google KMS is used
key_id.eID-Easy-signing-1.hsm_implementation=gcloud_hsm
key_id.eID-Easy-signing-1.hmac_key=
key_id.eID-Easy-signing-1.password=
key_id.eID-Easy-signing-1.projectId=
key_id.eID-Easy-signing-1.locationId=
key_id.eID-Easy-signing-1.keyRingId=
key_id.eID-Easy-signing-1.keyId=
key_id.eID-Easy-signing-1.keyVersionId=1
Last Updated: