Cryptographic operations

The methods described below are provided to perform cryptographic operations. Note that only operations with the private keys are available (which requires access to the hardware). Operations using the public keys can be made using pure-JavaScript libraries provided by third-parties.

Key.sign(hash[, algorithm])

Signs the provided hash using a private key. For RSA keys, the operation will use PKCS#1 padding or PSS padding depending on given algorithm parameter. For EC keys, the operation will use PKCS#1 padding and return the signature in RAW format.

The algorithm parameter indicates the algorithm to use and can take the following values:

  • for PKCS#1 padding, the algorithm of the hash needs to be indicated if the OID needs to be added within the signature block. The algorithm parameter can take the following values:

    • null or undefined: The hash data will be signed as provided. Not available for qualified signature keys.

    • "sha1", "sha256", "sha384" or "sha512": The corresponding OID will be prepended. Not available for qualified signature keys.

    • "sha1-partial" or "sha256-partial": The hash must be provided as a partial hash block (containing intermediate hash values) as defined by the IAS specifications. The hash will be finalized by the card and the corresponding OID will be prepended. Available only for qualified signature keys.

  • for RSA PSS padding, algorithm parameter is a JavaScript object with the following attributes:

    • mgf: mask generation function to use as a string. Can be "sha1", "sha256", "sha384" or "sha512".

    • saltLen: salt length to use as an integer.

Note that the Key.partialHash property can be used to check whether the key is a qualified signature key that requires partial hashing.

Arguments:

  • hash – The hash value as an ArrayBuffer or as an Uint8Array.

  • algorithm – (optional) The signature algorithm (padding, hash) to use as a string or as a JavaScript Object.

Returns:

A Promise resolving to an ArrayBuffer containing the signature.

Key.hashAndSign(data, algorithm)

Hashes the provided data and signs the hash using a private key. For RSA keys, the operation will use PKCS#1 padding or PSS padding depending on given algorithm parameter. For EC keys, the operation will use PKCS#1 padding and return the signature in RAW format.

The algorithm parameter indicates the algorithm to use and can take the following values:

  • for PKCS#1 padding, algorithm parameter is a string which defines hash algorithm to use:

    • "sha1" or "sha256": Available for all keys (SHA-1 may be forbidden with qualified signature keys depending on the card profile). The API will automatically take care of the partial hashing requirement when used with a qualified signature key.

    • "sha384" or "sha512": Not available for qualified signature keys.

  • for RSA PSS padding, algorithm parameter is a JavaScript object with the following attributes:

    • hashAlg: hash algorithm to use as a string. Can be "sha1", "sha256", "sha384" or "sha512".

    • mgf: mask generation function to use as a string. Can be "sha1", "sha256", "sha384" or "sha512".

    • saltLen: salt length to use as an integer.

Arguments:

  • data – Data to hash, provided as a string or as a Blob object.

  • algorithm – The signature algorithm (padding, hash) to use as a string or as a JavaScript Object.

Returns:

A Promise resolving to an ArrayBuffer containing the signature.

Key.decrypt(data)

Decrypts the provided data using a private key. The operation will use PKCS#1 padding.

Arguments:

  • data – ArrayBuffer or Uint8Array containing the ciphertext data to decrypt.

Returns:

A Promise resolving to an ArrayBuffer containing the plaintext data.