Table of Contents

maxLevel	2
indent	circle

Description

AlisonGUI is a javascript client library to access Alison-Desktop and AlisonServer certificates functionalities from any browser. It provides a graphical interface to list and select certificates.

AlisonGUI embeds AlisonJS into it.

Browser compatibility

Chrome	Firefox	Safari	Opera	Brave	Edge	IExplorer
Latest ✔	Latest ✔	Latest ✔	Latest ✔	Latest ✔	Latest ✔	11 ✔

Download

You can [download latest stable release] of AlisonGUI.

Integration

You must include the following line in your HTML page.

<script type="text/javascript" src="alisonGUI.js"></script>

Future Releases

It is possible to access future releases of the library to test new features to be implemented.

Related Product

Alison Desktop

Go to the Alison Desktop documentation.

AlisoJS sdk

Go to the AlisosJS sdk documentation.

Methods

List of available methods.

Version

Use the attribute libVersion to determine current version of the library.

Code Block

language	actionscript3
title	Library Version

const version = alisonGUI.libVersion;

.

Anchor
methodInitialize
methodInitialize
Mount

This method initialize the defined providers, set filters and display features and show a dialog windows to perform the selected operation.

Code Block

language	js
title	Initialize

AlisonGUI.mount( parameter );

Argument

Required

Description

parameter

✔

A JSon string defining all the components and operations.

A description of each field can be found below.

.

Parameters

Following fields can be present into the parameters.

Code Block

language	js
title	Fields

{
	gui?: {...},
	filters?: [...],
	select?: {...},

	providers: {...},
	modes?: operation_mode,
	signature?: {...},
	onConfirm: (result) {...},
	onCancel: (result) {...}
}

.

gui:

These values define some graphics features of the library.

Code Block

language	js
title	gui:

gui: {
	logoUrl: logoUrl?,
	theme?: {
		name: themeId?,
		palette: palette?
	},
	header: header?,
	language: language?,
	viewSignature: boolean?
}

Argument	Required	Description
logoUrl	✘	URL to the logo image to be included into the header of the dialog window.
theme	✘	Name of the graphic theme to be used. Default value: "theme1". Currently "theme1", "theme2" and "theme3" are valid. Palette defines a colore pantone to overwrite the default colors defines in each theme.
header	✘	String to describe the operation.
language	✘	Language. It none is defined, library uses browser language, or "en" if the language is not supported by the library.
viewSignature	✘	If "true", the text to be signed is displayed on frame of the same window.
wizard_url		set the wizard URL, if a value is not provided, it takes as default value https://alison.certisur.com/acme

Palette allows to overwrite the default color values of the selected theme.

Code Block

language	bash
title	gui: theme: palette
collapse	true

palette: {
	"common": {
		"main": "#37474F",
		"color": "#37474F99",
		"light": "white",
		"background": "white"
	},
	"primary": {
		"main": "#2e8055"
	},
	"secondary": {
		"main": "#FFFFFF",
		"light": "#FFFFFF",
		"dark": "#B2C6CB"
	},
	"warning": {
		"main": "#CE9F1E"
	},
	"error": {
		"main": "#F44336",
		"light": "#FDE3E1"
	},
	"button": {
		"submit": {
			"color": "#E3EBEC",
			"background": "primary",
			"hover": {
				"color": "#387056",
				"background": "white"
			}
		},
		"cancel": {
			"color": "white",
			"background": "rgba(178, 198, 203, 0.8)",
			"hover": {
				"color": "rgba(178, 198, 203, 1)",
				"background": "white"
			}
		},
		"boxShadow": "none",
		"borderRadius": "32px"
	}
}

Language is a more complex structure since it allows to select the language of the message and also to extend default message definitions or to add new ones. Following example shows how to define a new language and its values.

Code Block

title	Language Definition

"language": {
	"key": "jp",
	"resources": [
		{
			"key": "jp",
			"resource": "translations/jp.json"
		}
	]
}

Argument	Required	Description
key	✔	Language. It must be a 2 letter definition.
resources	✘	Array of resources where new languages are defined. Follow previous example.

Themes

Color and styles can be overwritten.

Theme1	Theme2

.

filters:

It's possible to define a filter to be applied on the certificate list. A filter can define several conditions.

Code Block

language	js
title	gui:

filters: [
	{
		subject: subject?,
		issuer: issuer?,
		keysore: keystoreArray?,
		expirationWindow: expirationWindow?
	} , ...
}

Argument	Required	Description
subject	✘	A string that is included into the Distinguished Name (DN) of the subject's certificate.
issuer	✘	A string that is included into the Distinguished Name (DN) of the issuer's certificate.
keystore	✘	An array of valid keystores. Ex: "CSK", "MACOS"].
expirationWindow	✘	A certificate can be filtered by its expiration date. This field must define 2 integer values: "<past-days>,<previous-days>", and these values allows to create a range around the expiration date of the certificate. A wildcard () can be used to disable one of the values. Some examples: 0 , : all valid certificates. * , 0 : all expired certificates. 0 , 60 : valid certificates with less than 60 days of validity. -30 , 90 : certificates close to expire (less than 90 days), or expired (less than 30 expired days). 60 , * : certificates with more than 60 days of validity.

Example: valid certificates issued by "Banco Internacional SA".

Code Block

title	Filter Example

filters: [
	{
		"windowValidity": "0,*",
		"issuer": "Banco Internacional SA"
	}
]

.

select:

This parameter allows selection of a certificate from all the certificates found.

Code Block

language	js
title	gui:

selector: {
	thumbPrint: thumbPrint,
	profileName: profileName?,
	keyStoreId: keyStoreId?
}

Argument	Required	Description
thumbPrint	✔	ThumbPrint of the certificate. This value is required. If more than one certificate is present, then profileName and keyStoreId is used to select the right certificate.
profileName	✘	ProfileName that contains the selected certificate.
keyStoreId	✘	KeyStoreId that contains the selected certificate, ie: "MACOS", "ETOKEN".

.

modes:

This value is used to indicate the kind of operation selected.

Code Block

language	js
title	gui:

modes: operation_mode

Posible values:

Argument	Description
select	Show the list of certificate and user can select one of them. None access to the private key is done.
authenticate	User have to select a certificate to access a web site. An autogenerated text, which includes the hostname and date is signed using the private key.
test	User have to select a certificate and sign a dummy text (don't visible to the user). This mode can be used to validate that a certificate is installed and working.
renew	User have to select a certificate and sign a text used to validate the certificate. This signature is used to validate the certificate and generate a renew request.
sign	User have to select a certificate and sign the text. The signing text can be displayed by the user on the screen.

.

signature:

Uses a certificate to sign a string or an array of string.

Code Block

language	js
title	Signature

signature:{
    dataToSign: [string]
	options: {
	    format?: string
    	algorithm: string;
    	extraParams?: string;
	}
}

Argument	Required	Description	Possible Values
dataToSignB64	✔	Array of Strings in base64 format.
algorithm	✔	Signature Algorithm.	SHA1withRSA(1.2.840.113549.1.1.5) SHA256withRSA(1.2.840.113549.1.1.11) SHA384withRSA(1.2.840.113549.1.1.12) SHA512withRSA (1.2.840.113549.1.1.13)
format?	✘	Signature type. Some signatures are only supported by desktop. Default value is PKCS1.	CAdES (0.4.0.19122) XAdES XAdES Detached XAdES Enveloped XAdES Enveloping XMLDSig XMLDSig Detached XMLDSig Enveloped XMLDSig Enveloping XMLDSig SignedInfo (custom - desktop) PAdES PKCS1 \| NONE
extraParams	✘	Extra name-value pairs, separated by enter (\n). These values can be used by the signer to modify or extend some attributes of the signature.	mode=<explicit\|implicit>. Indicates if the signed text must be included outside the structure (implicit) or it is included into it (explicit). Default depends of the kind of format. contentTypeOid contentDescription includeOnlySignningCertificate precalculatedHashAlgorithm policyIdentifier policyIdentifierHash policyIdentifierHashAlgorithm
signingCertificate	✔	A Certificate Selector structure indicating the certificate used to sign.

.

Example

Select a certificate

Code Block

language	js
theme	Eclipse
title	Select a Certificate

<script src="./alisonGUI.umd.js"></script>

AlisonGUI.mount({
	gui: {
		logoUrl: company.logo,
		language: "en"
	},
	providers: {
		desktop: {
			url: 
			accessToken: "ewogICJ2MiI..."
		},
		tad: {
			requestUrl: 'https://localhost:3000/requestSignature',
			responseUrl: 'https://localhost:3000/responseSignature'
		}
	},
	filters: [
		{
            expirationWindow: '0,*',
            issuer: 'CN=Bank*'
		}
	],
	onConfirm: (result) => {
		console.log("onConfirm"); 
		console.log(result);
	},
	onCancel: (result) => {
		console.log("onCancel"); 
		console.log(result);
	}
});

Providers:

Following fields can be present into the parameters.

Code Block

language	js
title	providers:

providers: {
	desktop?: {...},
	server?: {...},
	tad?: {...}
}

desktop:

This parameter allows access to your desktop certificates.

Code Block

language	js
title	desktop:

desktop: {
	urls?: urls,
	accessToken: accessToken,
}

Argument	Required	Description
urls		Can provide an ordered array of URLs through which the connection will be attempted.
accessToken	✘	Access code needed to obtain your desktop certificates.

server:

This parameter allows access to your cloud certificates.

Code Block

language	js
title	server:

server: {
	url?: url,
	accessTokentoken: accessTokentoken,
	userType: userType,
	tenant: tenant,
}

Argument	Required	Description
url		Specific url through which the connection will be attempted
accessTokentoken		Access code to obtain your cloud certificates. If it is not provided you can access the certificates with your credentials.
userType		Type of credentials that will be requested to obtain your certificates. Default value: "email". Other options: "doc", "user" or"emal".
tenant	✘	Tenant name, ie. "acme"

TAD-proxy:

(Tramites A Distancia, Argentina Government Digital Signature)

This parameter allows access to tst services.

Code Block

language	js
title	tad:

tad: {
	url?: urls,
}

Argument	Required	Description
url		Specific url through which the connection will be attempted

Since none of the parameters are required you can provide an empty object (i.e. "tad: {}").

Version	Old Version 13	New Version Current
Changes made by	Armando Carratala	Tomás Arras
Saved on	Nov 21, 2023	Mar 15, 2024

Content Comparison

Versions Compared

Key

Description

Browser compatibility

Download

Integration

Future Releases

Related Product

Alison Desktop

AlisoJS sdk

Methods

Version

AnchormethodInitializemethodInitializeMount

Parameters

gui:

Themes

filters:

select:

modes:

signature:

Example

Select a certificate

Providers:

desktop:

server:

TAD-proxy:

(Tramites A Distancia, Argentina Government Digital Signature)

Anchor
methodInitialize
methodInitialize
Mount