ModernAPI

Renamed to API

Types:

• Certificate
• Signature

Methods:

• getCertificate()
• sign()
• debug()
• use()

How to use

• Example

---

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:

• http://www.w3.org/TR/WebCryptoAPI/#dfn-SubtleCrypto-method-sign
• http://www.w3.org/TR/WebCryptoAPI/#sha-registration

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:

• https://code.google.com/p/chromium/issues/detail?id=362214#c7 (NotSupportedError for not_allowed)
• http://www.w3.org/TR/WebCryptoAPI/#SubtleCrypto-Exceptions
• LegacyAPI#error-codes

Usage

• if you expect your users to have browsers without Promise support (IE < 11), include a polyfill
  • For example https://github.com/getify/native-promise-only
• include hwcrypto.js in your website

<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.