Skip to content
This repository was archived by the owner on Mar 19, 2025. It is now read-only.

Backend LegacyAPI

Jump to bottom
Kristel Merilain edited this page Jul 25, 2022 · 3 revisions

NB! This page is not to be used as a reference documentation or for creating web applications, it is here for purely historical and concentrated informational purposes.

Current NPAPI-style plugins

  • As implemented by: https://github.com/open-eid/browser-token-signing
  • MIME type: application/x-digidoc
  • Synchronous interface.
  • Talk via various backends to supported tokens (PKCS#11 and CryptoAPI)
  • Calling website needs to embed/inject the plugin invocation code into the website, with something like:
  • <object id="IdCardSigning" type="application/x-digidoc"/>
  • plugin.errorCode is used to communicate last error
  • plugin.pluginLanguage is used to set the language code of the native UI (et, en etc)
    • only matters for non-Windows platforms
    • argument for .sign() overrides .pluginLanguage

plugin.getVersion()

Returns the version of the native plugin. NB! Not all implementations have it, some have only plugin.version

  • arguments
  • none
  • returns
  • String: version string of the plugin (informative only)

plugin.getCertificate()

Native plugin displays a certificate selection window where the user can select the certificate he/she would like to use on the website. Certificates are listed from a pre-configured PKCS#11 module or Windows certificate store.

  • arguments
  • none
  • returns
  • Object: dictionary where important are the id opaque identifier of the user-selected certificate (in real life: md5 of the certificate) and cert as the hex-encoded certificate.

plugin.sign(id, hash)

Signs the hash with the certificate with the specified id.

  • arguments
  • String id: opaque identifier for a key/certificate pair. Normally fetched with getCertificate().
  • String hash: the hash to be signed, represented as a hex string
  • returns
  • String: resulting signature, represented as a hex string

Chrome Native Messaging extension

Native Messaging provides the same API but with success/failure callbacks appended to function signatures and the functionality hidden behind a IdCardPluginHandler(lang) class:

  • plugin = IdCardPluginHandler('est');
  • plugin.getVersion(success, failure)
  • plugin.getCertificate(success, failure)
  • plugin.sign(id, hash, success, failure)

Error codes

(see also: hwcrypto.js#error-handling)

  • 1: cancelled
  • 2: no certificate (if called with incorrect certificate ID. Means "invalid argument")
  • 4: PIN blocked (or "Crypto API error", BHO only)
  • 5: reader-not-found / unknown error (BHO: invalid hash length for sign)
  • 9: incorrect PIN
  • 12: reading card failed (?)
  • 14: technical error (?)
  • 15: missing software (?)
  • 16: invalid certificate id (? not found or ?)
  • 17: invalid hash
  • 19: must be https
  • 100: software missing (?)

Q:

  • 2 vs empty selection
  • 12 vs 14
  • 15 vs 100 ?

Errors and glitches

  • BHO doest not have .getVersion(), only .version
  • BHO requires third language argument for .sign()
  • BHO has .errorCode as string, not integer
  • "PIN blocked" window is shown asynchronously on OSX (window gets hanging, can crash extension)
  • BHO .sign() returns empty string if getCertificate() is not called before, ignoring certificate parameter
  • Windows: entering PIN with length 0 displays no error and "3 more tries remaining"
  • Certificate selection returns user_cancel even if no certificates available
  • Windows and pinpad: pressing cancel on the reader displays "incorrect PIN", re-starts the countdown timer and pressing cancel on the countdown popup makes the browser hang for a few seconds until failing with technical error
Clone this wiki locally