ModernAPI

Martin Paljak edited this page Jan 17, 2017 · 23 revisions

Renamed to API

Types:

Methods:

How to use


getCertificate

Promise window.hwcrypto.getCertificate(object options)

Asks the user to choose a certificate from the list of available smart card certificates. The supplied filter can be used to limit the list of certificates based on type, issuer etc.

Parameters
object (optional) options options for the certificate chooser
options
string (optional) lang UI language hint (ISO 639-1 code)
object (optional) filter TBD - filter for the certificate selection

UI language (like "en" or "et") support in implementations can vary and the hint can be ignored, e.g. the actual UI language might be platform or browser default.

Returns a Promise which resolves to a Certificate object. Expected failures: no_implementation, no_certificates, user_cancel, technical_error.

Certificate

Represents a X509 certificate and also works as an opaque handle to the chosen certificate.

properties
Uint8Array encoded DER encoded certificate
string (optional) hex certificate encoded as hex (legacy)

sign

Promise window.hwcrypto.sign(object certificate, object hash, object options)

Signs the plain input hash (no hash OID in the hash value) with the private key associated with the certificate (which MUST be acquired with a call to getCertificate())

Parameters
object certificate the Certificate object which private key to use
object hash the hash to be signed
object (optional) options options for the signing process
hash
string type hash type, enum of "SHA-1", "SHA-224", "SHA-256", "SHA-384" or "SHA-512"
Uint8Array value hash value
string hex hash value as hex (legacy)
options
string (optional) lang UI language hint (ISO 639-1 code)
string (optional) info Informational message (document name, transaction sum etc)

Returns a Promise which resolves to a Signature object. Expected failures: no_implementation, invalid_argument, user_cancel, technical_error, pin_blocked.

Signature

Encapsulates a signature.

properties
Uint8Array value signature as bytes
string (optional) hex signature encoded as hex (legacy)

See also:

Internal functions

These functions are described only for developer convenience but the presence and stability of these functions is not guaranteed.

debug

Promise<String> window.hwcrypto.debug()

Resolves to a string with relevant information about the API implementation (hwcrypto.js version), effective backend and its version.

use

Promise<Boolean> window.hwcrypto.use(string backend)

Tries to use specific backend. The details and result of this function are implementation-specific. Calling with null or "auto" does the default, which is autodetection. This MUST be called before using any of the public methods.

Error handling

In case of errors, the Promise gets rejected with an Error and a fixed message:

  • "user_cancel" - user has explicitly cancelled the operation via GUI or via pinpad.
  • "no_certificates" - no certificates available for the plugin for listing.
  • "invalid_argument" - developer has sent an invalid argument to the API.
  • "technical_error" - unexpected technical error in the plugin
  • "no_implementation" - no plugins or extensions or necessary platform support found
  • "not_allowed" - execution not allowed by policy (like not using https)
  • "pin_blocked" - the smart card is blocked

When encountering user_cancel, no_certificates, technical_error and under some circumstances even pin_blocked, the application can consider re-trying the operation after instructing the user. When encountering invalid_argument, not_allowed and no_implementation it usually doesn't make sense to try to recover and the ongoing operation should be cancelled on the application side.

See also:

Usage

<script src="hwcrypto.js"></script>
  • fetch the certificate and sign with it
// NB! This sample uses the legacy `hex` property!
window.hwcrypto.getCertificate({lang: 'en'}).then(function(certificate) {
   // Do something with the certificate, like prepare the hash to be signed
   var hash = calculateSHA256SignatureHashAsHexForCertificate(certificate.hex);
   // Now sign the hash
   window.hwcrypto.sign(certificate, {type: 'SHA-256', hex: hash}, {lang: 'en'}).then(function(signature) {
      // Do something with the signature
      storeSignature(signature.hex);
   }, function(error) {
      // Handle the error. `error.message` is one of the described error mnemonics
      console.log("Signing failed: " + error.message);
   });
});

Important facts

  • the certification selection is bound the the lifecycle of the window object: re-loading the page invalidates the selection and calling sign() is not possible.
  • because of the above, all operations should be done on the same page, storing Certificate objects in some kind of session variables is not possible.
  • note to Estonian users: cards with 1024b RSA keys have a upper limit for hash size: SHA-224.