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
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
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 unerlying platform limitations.
isAvailable
webeid.isAvailable(object options)
parameter
type
options
object
additional options (optional)
options
timeout
timeout in seconds or Infinity. Default is 0
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 dynamicallly 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
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
SCardConnect is called with SCARD_SHARE_EXCLUSIVE or if it is not possible, with SCARD_SHARE_SHARED and a SCardBeginTransaction() on non-Windows machines
SCardDisconnect is called with SCARD_RESET_CARD argument
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