Page tree
Skip to end of metadata
Go to start of metadata

Pārlūka paplašinājumu/spraudņu integrācijas vadlīnijas

Apraksts

"eParaksts Token Signing" solution provides document signing and user authentication in browser environment using OCMA eID and LVRTC eParaksts (Gemalto, Oberthur) smart cards.

Components

"eParaksts Token Signing" solution consists of the following components:

  • Custom extension/plugin for browsers, supports communication with a smart card, installed on the user's computer, see section
  • JavaScript API, provides communication with the plugin, integrated into WEB solutions, see section

Support

"eParaksts Token Signing" are supported:

BrowserChrome 40+IE 8+Firefox 30+Safari 5.1-11.x
OSWindows 7+MacOS X 10.7.4+Ubuntu 18.04 LTS 64-bit.

Use Cases

Document signing

Authentication


Klienta puses pārlūka spraudnis / paplašinājums

For "eParaksts Token Signing" functionality, a custom plugin/Extension must be installed on the end user's computer for browsers that communicate with the smart card.

End user plugin/extension installation are distributed with eParakstītājs 3.0 software package

Using the JavaScript API function getBackendInfo, it is possible to determine the state of the installed plugin/extension. In situations where the plugin/extension is not installed or its version is out of date.

JavaScript API (HWCrypto)

Components

JavaScript API (HWCrypto) consists of three files:

  • eparaksts-hwcrypto.js – main functions;
  • eparaksts-hwcrypto-legacy.js – additional functionality to provide compatibility with IE8+;
  • eparaksts-jquery.js – additional compatibility functions.

JavaScript API funkcijas

getBackendInfo

Funcion

Returns information about end user plugin/extension 

Promise window.eparakstshwcrypto.getBackendInfo()

Parameters

none

Result

Returns the Promise object that corresponds to the BackendInfo data type.

Errors

Expected errors:

  • technical_error.

See section JavaScript API Error Handling.

getCertificate

Funcion

Prompts the user to select a certificate from the list of available certificates. Connection to a browser plugin/extension that allows certificate data to be read from the user's smart card.

Promise window.eparakstshwcrypto.getCertificate(object options)

Parameters

PropertyTypeMandatoryDescription
options

objectnoConditions for certificate selection.

lang
stringno

Preferred user interface language (ISO-639-1 code).

Supported languages:

  • en - English (default value);
  • lv - Latvian;
  • ru - Russian.

    The user interface language is not fully affected because
    the language used can be determined by the operating system or browser.


operation
stringno

type of operation:

  • sign - document signing (signing certificate will be returned) (default value);
  • auth - user authentication (authentication certificate will be returned)

Result

Returns the Promise object that corresponds to the Certificate data type.

Errors

Expected errors:

  • no_implementation;
  • no_certificates;
  • user_cancel
  • technical_error.

See section JavaScript API  Error Handling.

sign

Function

Requires the user to sign the prepared HASH value (signable data for example). Connection to a browser plugin/extension that provides signing on the user's smart card. 

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

Parameters

PropertyTypeMandatoryDescription
certificate
objectyesCertificate to use the corresponding private key for signing. An object corresponding to the Certificate data type was obtained using the getCertificate function.
hash
objectyesPrepared signable HASH value

type
stringyes

Signale HASH value algorithm type:

  • SHA-1
  • SHA-224
  • SHA-256
  • SHA-384
  • SHA-512

For Authentication

MD5-SHA1” type shall be used for end user authentication.

For Batch signing

JSON” type shall be used for batch signing

Batch signing is available in Chrome and Firefox 50+ browser versions


hex
stringyes

Signable HASH value in HEX encoding.

If "JSON" type is used, signable HASH values must be included in JSON object, which contains one or more "key:value" pairs, where:

"key" - Signale HASH value algorithm type;

"value" - Signable HASH value in HEX encoding

options
objectno

Signing conditions


lang

string

no

Preferred user interface language (ISO-639-1 code).

Supported languages:

  • en - English (default value);
  • lv - Latvian;
  • ru - Russian.

The user interface language is not fully affected because the language used can be determined by the operating system or browser.


operation

string

no

Type of operation:

  • sign - document signing (signing certificate will be returned) (default value);
  • auth - user authentication (authentication certificate will be returned)

info
stringnoInformative text (document title, transaction amount, etc.).

Result

Returns the Promise object that corresponds to the Signature data type.

Errors

Expected errors:

  • no_implementation;
  • invalid_argument;
  • user_cancel;
  • technical_error;
  • pin_blocked.

See section JavaScript API Error Handling.

Datu tipi

BackendInfo

Contains information about the end user plugin/extension installed in the browser.

Attributes

PropertyTypeDescription
type
string

Plugin/extension type:

  • NO_IMPLEMENTATION - Plugin/extension is blocked or not installed
  • FAILING_CHROME - Plugin/extension is not working, end user must enable plugin/extension and restart browser
  • FAILING_NPAPI - Plugin/extension is not working, end user must enable plugin/extension and restart browser
  • Plugin/extension name - Plugin/extension is working. Plugin/extension version is additionally available.
version
stringPlugin/extension version

Certificate

Contains X509 certificate data.

Attributes

PropertyTypeDescription
encoded
Uint8Array

The binary value of the certificate in DER encoding.

hex
string

The value of the certificate in HEX encoding. (Optional)

Signature

Contains signed data.

Attributes

PropertyTypeDescription
hex
string

Signed data in HEX encoding.

If request contains "JSON" type, 

signed data are included in JSON object, which contains one or more "key:value" pairs, where:

"key" - signed document identifier;

"value" - signed data in HEX encoding.

The order in which the "key:value" pairs are returned may not be identical to the order in which the signature request was builded.


Error handling

In the case of an error, the function call is rejected with a specific message

MessageDescription
not_allowedoperation is not allowed, a secure (TLS/SSL) connection is required
no_implementationPlugin/extension is blocked or not installed
no_certificatesNo certificate available
user_cancelThe user has canceled the operation
invalid_argumentInvalid parameter specified in function request
technical_errorUnknown technical error
pin_blockedSmart card PIN is blocked

Examples


Getting certificate and signing

The following example shows how to obtain a signing certificate and sign data with it

window.eparakstshwcrypto.getCertificate({lang: 'en'}).then(
	function(certificate) {
		//prepare the hash to be signed
		var hash = calculateHashAsHexForCertificate(certificate.hex);
		//sign the hash
		window.eparakstshwcrypto.sign(
			certificate, {type: 'SHA-1', hex: hash}, {lang: 'en'}).then(
			function(signature) {
			//do something with the signature
			storeSignature(signature.hex);
		}, function(error) {
			//handle the error
			console.log("Signing failed: " + error.message);
		});
	});

Response

The expected signing result (signature.hex) is the value of the electronic signature in HEX encoding.

B3745A73AC10CDB0F082EBA30A4D12CF7028F969EF7568783A18B628FEC7BC4FC445C8CB09
4F1C9F68D9414C30B510D715925B8F5CC2DE32C98D64AFF539F28684E0147DE91A430EB2E2
D51271A6C1BFECD639AD194867F6ED696C06CCDABFAD7E36C0D03A086FDF3ECA8442600836
C365301882F2A9404F703C63E1B1C90DB4A7BDAFDC0F558180D67DF5AC6B442ADB779D4682
9700148C40104E1E7EF95BB6EAD922B7BDD649EDF9D54D6ED7F52A1EC6EC25C078DFFF20BF
D0E1A1D2B85FB79CECE9326F8BE9D431A551027DC734F81EC6650F64716813102D727F5EAA
7A9ACEB12321959ACF53C73172CC2D3D4E1534286072C75EA2DBBFECCC56B5E4EBC9

JSON structure in batch signing

The example of a JSON object with 2 signable values to be passed as a hex property of a hash object, along with the type property 'JSON' of the hash object.


var json = {"edoc1":"8b7bd2107adc94fb6082847b48357129ddcc39ba",
"edoc2":"b3649be703934cb20655296e879c60270111d6a4"};
...
window.eparakstshwcrypto.sign(certificate, {type: 'JSON',
	hex: json},{lang: 'en'}).then(
		function(signature) {
...

Response example

The expected result of batch signing (signature.hex) is a JSON object with 2 signature values

{
"edoc1":"B3745A73AC10CDB0F082EBA30A4D12CF7028F969EF7568783A18B628FEC7BC4FC
445C8CB094F1C9F68D9414C30B510D715925B8F5CC2DE32C98D64AFF539F28684E0147DE91
A430EB2E2D51271A6C1BFECD639AD194867F6ED696C06CCDABFAD7E36C0D03A086FDF3ECA8
442600836C365301882F2A9404F703C63E1B1C90DB4A7BDAFDC0F558180D67DF5AC6B442AD
B779D46829700148C40104E1E7EF95BB6EAD922B7BDD649EDF9D54D6ED7F52A1EC6EC25C07
8DFFF20BFD0E1A1D2B85FB79CECE9326F8BE9D431A551027DC734F81EC6650F64716813102
D727F5EAA7A9ACEB12321959ACF53C73172CC2D3D4E1534286072C75EA2DBBFECCC56B5E4E
BC9",
"edoc2":"8E2DAB670A01DB5F683D041DDB4B7691818D60E1185940890CAA6E0799055460E
384C6D72D4493023C9F53734376C246204E2909E7177F45F829F2099727BD8301303C3F1CA
5BCE01A73534850879190011BFE3DF9800638C277ABB42D328E85B1643C28F7B7841B6861C
E04AEF62C770E9D06C9D5C6DDA0CCE469D67F427615C5F6BB6B623CED48C7AD4AEC643D1E4
8B1C8F5D20CA350D7CE65F1CE5FFAC88036369489591506E46CF28DA4A92BC7A1182897CC7
0B49B5E3BB6DC60E331BD8D258F2BD036379D70EF4D87C0CFC9CD09BBDB1ADD455F252C7B8
6A9242CE8747A53DDBCADBFAC63533D692A4D6F86133E7EC3F2E32EF7B79BD02B625BB3251
1E8"
}

The document to be signed must be prepared on the server side

The user must select a signing certificate

//plugin request
window.eparakstshwcrypto.getCertificate({lang: lang, operation: 'sign'})

After receiving the certificate, the server side start signing the document

//prepare signature
Map<String, String> props = new HashMap<>();
props.put(EDoc2Signature.KEY_SIGNATURE_METHOD_URI,
EDoc2Signature.SIGNATURE_METHOD_RSA_SHA256);
EDoc2BasicSignature preparedSignature = edoc.addSignature(props);

//cert
preparedSignature.setSigningCertificate(cert);

//getSignableBytes
byte[] signableBytes = preparedSignature.getSignableBytes();
MessageDigest digestCalculator = MessageDigest.getInstance(“SHA-256”);
byte[] digest = digestCalculator.digest(signableBytes);

//complete
preparedSignature.complete();

//save
session.setAttribute("edoc", edoc);

//plugin request
window.eparakstshwcrypto.sign({hex: signCert}, {type: 'SHA-256',
hex: signHash}, {lang: lang, operation: 'sign'})

After receiving the signed HASH value, it is possible to set the signature value in the previously prepared document

EDoc2 edoc = (EDoc2)session.getAttribute("edoc");

//get the last signature
EDoc2Signature signature =
	edoc.getSignature(edoc.getSignatureCount() - 1);

//get basic signature
EDoc2BasicSignature basicSignature = signature.basicSignature();

//setSignatureValue
basicSignature.setSignatureValue(signatureValue);

//complete
basicSignature.complete();

It is important that the signature value must be added to the exact same ASICE (EDOC) document from which the data to be signed is derived, as the content of the data to be signed also includes the time of signing, otherwise the signature will not be valid.


This step shall be performed when signing with JAVA libraries after signing operation (signature is added to the document).

The user must select a authentication certificate

//plugin izsaukums
window.eparakstshwcrypto.getCertificate({lang: lang, operation: 'auth'})

After receiving the certificate, a new TimeStampThread must be started on the server side

byte[] timeStampDigest =
	eDoc2QualifiedSignature.getSignatureValueDigest("SHA-256");
timeStampThread =
	new TimeStampThread(TimeStampGenerator.DIGEST_ALGORITHM_SHA256,
	timeStampDigest, authCert);
	
//a timestamp request is initiated,
//to receive a authHash value to sign
byte[] authHash = timeStampThread.getAuthHash();

//Validation, if authHash obtained successfully
if (authHash != null) {

	//plugin request
	window.eparakstshwcrypto.sign({hex: authCert}, {type: 'MD5-SHA1',
		hex: authHash}, {lang: lang, operation: 'auth'})
} else if (timeStampThread.isCancelled() == false) {

	//Error
	throw new RuntimeException(timeStampThread.getException());
}

TimeStampThread instance ir jāsaglabā servera pusē atmiņā kā lietotāja sesijas objekts, un
pēc authHash parakstīšanas tas ir jāuzstāda atpakaļ jau esošajam TimeStampThread objektam,
kuru iegūst no lietotāja sesijas.

After receiving the signed authHASH value, it is possible to obtain a time stamp from the previously started TimeStampThread

timeStampThread.setAuthSignature(signature);
byte[] timeStamp = timeStampThread.getTimeStamp();

//validation, if Timestamp is obtained successfully
if (timeStamp != null) {
	TimeStamp ts = new TimeStamp(timeStamp);
	eDoc2QualifiedSignature.setSignatureTimestamps(
		Collections.singletonList(timeStamp));
		
} else if (timeStampThread.isCancelled() == false) {
	//Error
	throw new RuntimeException(timeStampThread.getException());
}


  • No labels