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
Just download the file and use it in a script tag
<script src="web-eid.js"></script>
Functionality will be bound to window.webeid
$ bower install --save web-eid
$ npm install --save web-eid
And simply
webeid = require('web-eid');
IE 11 does not have Promise
support, thus a polyfill is required.
- 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) will contain a symbolic error code that can be parsed - Conformance to https://www.w3.org/2001/tag/doc/promises-guide is intended
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.
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.
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
orwebsocket
) - 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
If a PKI call fails, the promise will be rejected with an Error
object, which message
property will be a string from CKR_* series (PKCS#11, CNG/CryptoAPI return codes are mapped)
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
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
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 thehash
parameter (ArrayBuffer) generated with the private key belonging to thecertificate
(ArrayBuffer). Hash type is specified inoptions.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
- if rejected, the message of the Error object for PC/SC operations will be a PC/SC API error code as a string (e.g.
"SCARD_E_NOT_TRANSACTED"
)
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= , T=1 , * . Default is * ) |
timeout |
timeout in seconds or Infinity . Default is Infinity |
- resolves to an
object
reader
-string
- name of the readerprotocol
-string
- protocol of the connection (T=0
orT=1
)atr
-ArrayBuffer
- ATR of the card, as reported by the host PC/SC API
- equivalent of
SCardConnect
in the PC/SC API
- resolves to
ArrayBuffer
of the response - equivalent of
SCardTransmit
in PC/SC API - resembles transmitRaw, without the tidbits of channels or
61XX
/6CXX
handling - comparable to transceive() in Android IsoDep API
- resolves to
ArrayBuffer
of the response - equivalent of
SCardControl
in PC/SC API
- equivalent of
SCardDisconnect
in PC/SC API
- TBD