web-eid.js ·

web-eid.js is a ultrathin wrapper on top of the messaging interface provided by the Web eID app, either via web-eid-extension HTML5 postMessage interface or WebSockets or some other message transport in the future (like Android Intents)

It makes using the features provided by Web eID installation as available via web-eid.com super-easy:

• provides an asynchronous, Promise-based DWIM interface
• listens to incoming messages and turns them into resolved Promises

Please note that this library is not an all-inclusive toolkit for developing web apps that use cryptography, it is intended as a companion library for WebCryptoAPI and/or PKI.js or similar. Web eID solves two low hanging fruits that are missing from browser implementations but necessary to develop apps today, that make use of the hundreds of millions of devices deployed in the field: controlled access to smart card based pre-provisioned certificates (that by definition do not fall under the Same Origin Policy of WebCryptoAPI) for authentication, signing and decryption and controlled direct access to a smart card, like a local PC/SC application would have.

Installation

Browser installation

Just download the file and use it in a script tag

<script src="web-eid.js"></script>

Functionality shall be bound to window.webeid

Bower

$ bower install --save web-eid

Webpack & Browserify

$ npm install --save web-eid

And simply

webeid = require('web-eid');

Note for IE users

IE 11 does not have Promise support, thus a polyfill is required.

API

• All calls are asynchronous in nature and return a Promise
• While asynchronous, the API is still sequential - only one call can be serviced by a smart card (reader) at a time. If a call can not be serviced because this reason, the promise shall be rejected
• The message property of a rejected promise (an Error) shall contain a symbolic error code that can be parsed
• Conformance to https://www.w3.org/2001/tag/doc/promises-guide is intended

Note about API and stability

At this point of time no API stability is assured. Please note that if window.hwcrypto from hwcrypto.js is detected, hwcrypto.getCertificate() and hwcrypto.sign() are monkeypatched.

Timeouts

By default the execution time of a call depends on the underlying hardware and timeout is infinite. A timeout can be set for some calls, so that the operations that depend on user action would fail sooner (e.g. do not wait forever but fail in 2 minutes, if the user does not connect a card reader and insert a card in time) or set to 0 to get an instant error code. Please note that not all calls are cancelable on all platforms, due to underlying platform limitations.

isAvailable

webeid.isAvailable(object options)

parameter	type
options	object	additional options (optional)

options
timeout	timeout in seconds or Infinity. Default is 0

• does the discovery of client application and MUST be called before any other calls. Safe to call several times.
• resolves to false if client software is not available or to a string that describes the connection type of the application (webextension or websocket)
• if false, the recommended action is to display a notice with a link to https://web-eid.com
• if called with timeout = Infinity, the recommended action is to display a dynamic notice during the call that asks the user to install or start the client app
• recommended use: guard function before dynamically showing login button; general client availability check before calling rest of the API etc

PKI operations

If a PKI call fails, the promise shall be rejected with an Error object, which message property shall be a string from CKR_* series (PKCS#11, CNG/CryptoAPI return codes are mapped)

authenticate

webeid.authenticate(string nonce, object options)

parameter	type
nonce	string	nonce for the session (required)
options	object	additional options (optional)

options
timeout	timeout in seconds or Infinity. Default is Infinity

• resolves to a string containing the JWT token. JWT token description: https://github.com/martinpaljak/x509-webauth/wiki/OpenID-X509-ID-Token
• possible reasons for rejection: timeout or user cancels authentication, no certificates available, some other technical error
• used certificate is available in the x5c header field of the JWT token.
• expected behavior: user is instructed though the process of attaching a reader and a card, if necessary
• possible changes: resolving to undefined when no certificates are available

getCertificate

webeid.getCertificate(object options)

parameter	type
options	object	additional options (optional)

options
filter	type of certificate to return. Default is sign
timeout	timeout in seconds or Infinity. Default is Infinity

• resolves to an ArrayBuffer with the certificate
• intended to be used with the following webeid.sign() operation
• expected behavior: user is instructed though the process of attaching a reader and a card, if necessary
• possible reasons for rejection: user cancels certificate selection, no certificates available, some other technical error
• possible changes: resolving to undefined when no certificates available

sign

webeid.sign(ArrayBuffer certificate, ArrayBuffer hash, object options)

parameter	type
certificate	ArrayBuffer	certificate to use (required)
hash	ArrayBuffer	hash to sign (required)
options	object	additional options (optional)

options
hashalgo	hash algorithm type ("SHA-256" etc). (required)
timeout	timeout in seconds or Infinity. Default is Infinity

• resolves to a ArrayBuffer containing the signature of the hash parameter (ArrayBuffer) generated with the private key belonging to the certificate (ArrayBuffer). Hash type is specified in options.hashalgo (string) and is one of "SHA-256", "SHA-384", "SHA-512"
• possible reasons for rejection: user cancels/refuses signing, user PIN is blocked, some other technical error
• possible changes: support for "last round on card" hashing

decrypt (WIP)

webeid.decrypt(ArrayBuffer certificate, ArrayBuffer payload, object options)

parameter	type
certificate	ArrayBuffer	certificate to use (required)
payload	ArrayBuffer	payload to decrypt (required)
options	object	additional options (optional)

options
algorithm	algorithm type ("RSA-OAEP" etc). (required)
timeout	timeout in seconds or Infinity. Default is Infinity

• resolves to a ArrayBuffer containing the decrypted data of the payload parameter (ArrayBuffer).
• possible reasons for rejection: user cancels/refuses decryption, no key, user PIN is blocked, some other technical error
• please note that the result of decryption is usually a transport key (3DES, AES or some other symmetric algorithm)

WebSocket operations

authenticatedWebSocket

webeid.authenticatedWebSocket(string url, object options)

parameter	type
url	string	URL to connect to (required)
options	object	additional options (optional)

options
autoclose	set to true to close the socket when the card is removed
timeout	timeout in seconds or Infinity. Default is Infinity

• the first message from the service MUST be JSON and MUST contain the nonce {"nonce": "noncevalue"}
• authenticate() is called with the nonce
• the authentication token is sent back to the service as JSON {"token": "authenticationtoken"}
• promise is resolved with the WebSocket object
• if a card remove event is detected and autoclose is enabled, the socket is closed

PC/SC operations

• if rejected, the message of the Error object for PC/SC operations shall be a PC/SC API error code as a string (e.g. "SCARD_E_NOT_TRANSACTED")
• Tutorial

connect

webeid.connect(object options)

parameter	type
options	object	additional options (optional)

options
atrs	list of expected ATR-s in base64. Default is []
protocol	protocol to use (T=0, T=1, *. Default is *)
timeout	timeout in seconds or Infinity. Default is Infinity

• resolves to a Reader object
  • name - string - name of the reader
  • protocol - string - protocol of the connection (T=0 or T=1)
  • atr - ArrayBuffer - ATR of the card, as reported by the host PC/SC API
  • transmit(ArrayBuffer) - function - transmits the APDU to the card, returns a Promise that resolves to the response
  • disconnect() - function- disconnects the card, returns a Promise
  • reconnect(string protocol) - function - reconnects with the specified protocol, returns a Promise
• equivalent for SCardConnect in the PC/SC API
• SCardConnect is called with SCARD_SHARE_EXCLUSIVE or if it is not possible, with SCARD_SHARE_SHARED and a SCardBeginTransaction() on non-Windows machines

Reader.transmit(bytes)

• resolves to ArrayBuffer of the response
• equivalent for SCardTransmit in PC/SC API
• resembles transmitRaw, without the tidbits of channels or 61XX/6CXX handling
• comparable to transceive() in Android IsoDep API

Reader.reconnect(protocol)

• resolves to true. Reader object properties protocol and atr might have changed
• equivalent for SCardReconnect in PC/SC API

Reader.disconnect()

• equivalent for SCardDisconnect in PC/SC API
• SCardDisconnect is called with SCARD_RESET_CARD argument

Reader.control(code, bytes) (WIP)

• see @web-eid/web-eid#47 for a tracking issue
• resolves to ArrayBuffer of the response
• equivalent for SCardControl in PC/SC API
• NB! Probably will not happen, will only have verify/modify with transparent pinpad support. +1 the ticket to have plain SCardControl support

Reader.verifyPIN(options) (WIP)

• resolves to ArrayBuffer of the response
• equivalent for SCardControl in PC/SC API with the appropriate PC/SCv2 part 10 block based on options or client side PIN input UI

Reader.modifyPIN(options) (WIP)

• resolves to ArrayBuffer of the response
• equivalent for SCardControl in PC/SC API with the appropriate PC/SCv2 part 10 block based on options or client side PIN input UI

Error codes

• SCARD_E_READER_UNAVAILABLE - if webeid.connect() has not been called or the reader has disappeared
• SCARD_E_SHARING_VIOLATION - if webeid.connect() can not establish a reliable (no interference from other applications on the computer) connection to the card