Enable PKI and SmartCard support on Web

This section describes how to enable PKI and SmartCard support for the web application using Idopte’s Smart Card Middleware.

Idopte Smart Card Middleware, installed on the user’s computer, provides the Smart Card Web Services (SCWS) that are necessary to communicate with a smart card from the web browser.

Why Idopte?

There is no standard way to access the smart card hardware from the web browser. A couple of alternatives were considered, among which we can mention the Web Smart Card API but, at the time of writing, the API is in draft.

We chose Idopte, a French software company specialized in Smart Card Middleware, mainly because:

It provides a simple and functional JavaScript API allowing communication with the smart card from the browser (through their middleware)
The Parsec customer needing web smart card support is already using Idopte middleware with other web applications.

Note

We are open to consider other options for smart card web support.

Please feel free to contact us if you know of any other alternatives supporting following features:

List available certificate (at least their DER contents)
Check certificate trust (either providing CRL or doing the check itself)
Allow to sign/verify data
Allow to encrypt/decrypt data

Prerequisites

Before you begin, make sure you meet the following prerequisites:

You have an RSA Private key.
Tip

You can generate a private key with openssl:
```
openssl genrsa -out idopte-service.key 4096
```
Idopte provided you a web certificate including the public key of the RSA private key above.
Tip

openssl can help you generate the public key:
```
openssl rsa -in idopte-service.key -out idopte-service.pub
```
You have Idopte’s public keys, used during the mutual authentication process
You have a copy of the patched scwsapi.js file

Important

You cannot use a non-patched scwsapi.js file else the web application will not be able to load it.

Note

For legal reasons, we are currently unable to distribute the patched scwsapi.js file.

Configure the webapp

Follow these steps to configure the web application:

Copy the scwsapi.js file into the assets folder:
Tip

To improve caching, we recommend renaming the scwsapi.js file to have it’s checksum in the name:
```
mv scwsapi.js scwsapi-$(sha256sum scwsapi.js | cut -c -6).js
```
Edit the following meta tags in the index.html file:
- Put the web certificate provided by Idopte in the content of the meta tag named scws-web_application_certificate
- Edit the content of the meta tag with the name scws-scwsapi_js-location to path from where the SCWS javascript file is served

Configure Parsec Server

The server needs additional configuration to be able to perform the mutual authentication with the client middleware:

Make Idopte’s public keys accessible to the server. Put the keys into a file and either set the option --scws-idopte-public-keys-file or the env variable PARSEC_SCWS_IDOPTE_PUBLIC_KEYS_FILE to the file location.
Provide the private key to use:

Important

The private key is expected to be provide in its PEM format

For that you can either specify the key file via the --scws-web-application-private-key-file option or the env variable PARSEC_SCWS_WEB_APPLICATION_PRIVATE_KEY_FILE.

Or via it’s content in base64 with the env variable PARSEC_SCWS_WEB_APPLICATION_PRIVATE_KEY_CONTENT
```
export PARSEC_SCWS_WEB_APPLICATION_PRIVATE_KEY_CONTENT=$(base64 idopte-service.key)
```
Warning

The server also provides the --scws-web-application-private-key-content option but it’s not recommended because the private key will then be present in the shell history.