Description

AlisonJS is a javascript client library to access [Alison-Desktop] functionalities from any browser.

The current version (3.x) is a major release and it has a totally different interface over previous releases, taking advantage of the new REST interface provided by Alison-Desktop and Alison-Server.

This library still maintains backward compatibility with Alison-Desktop v2.

Browser compatibility

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

Download

You can [download latest stable release] of AlisonJS

Integration

You must include the following line in your HTML page.

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

Disclaimer

This is a work in progress.

It may be subject to changes in the future.

Related Product

Alison Desktop

Go to the Alison Desktop documentation.

Methods

Constructor

Signature

constructor(urls?: string[]);

Argument	Required	Description
urls	✘	Array of interfaces to communicate with Alison-Desktop or Alison-Server. The default value is ['https://127.0.0.1:8004', https://127.0.0.1:8005 ].

Example

const alison = new AlisonJS.Desktop();

Initialize

Opens a session with a certificate provider (Alison-Desktop or Alison-Server).

Must be called before any other methods.

Signature

initialize({ accessToken: string }) : Promise<void>;

Argument

Required

Description

accessToken

✔

Package containing all the Licenses used by Alison-Desktop to enable its functionality on the domain where is invoked.

This string is in a Base64 format.

Example

alison.initialize({
	accessToken: "eyJ2M9=="
}).then(
	function() { 
		// handle success
	},
	function({ code, detail }) {
		// handle failure
	}
)

Generate CSR

Generates a keyPair and a Certificate Signing Request.

Signature

generateCsr({
	keyStore: KeyStore
	options?: {
 		algorithm?: string
		size?: number
		signatureAlgorithm?: string
	}
	securityPolicy?: SecurityPolicy
}): Promise<{ csr: string }>

Argument	Required	Description
keyStore	✔	Alison JS where to generate the certificate request.
options	✘	Default values are: { algorithm: 'RSA', size: 2048, csrAlgorithm: 'SHA256WITHRSA' }
securityPolicy	✘	Security requirements to be applied to the keyStore/profile.

Example

alison.generateCsr({
	keyStore: { id: "WIN-ENH" },
	options: { size: 2048 },
	securityPolicy: { exportable: true }
}).then(
	function({ csr }) { 
		// handle success
	},
	function({ code, detail }) {
		// handle failure
	}
)

Install Certificate

Installs the certificate into the Keystore/profile indicated. Returns Alison JS

Signature

installPkcs7({
	keyStore: KeyStore
	pkcs7: string
	securityPolicy?: SecurityPolicy
}): Promise<{ certificate: WebCertificate }>

Argument	Required	Description
keyStore	✔	Alison JS where the privateKey is stored
pkcs7	✔	Certificate (X.509) and/or Certificate chain (PKCS#7 structure) to be installed (in base64 format). No PEM header must be included.
securityPolicy	✘	Security requirements to be applied to the keyStore/profile.

Example

alison.installPkcs7({
	keyStore: { id: "WIN-ENH" },
	pkcs7: "MIICU5iNXuudGfc="
}).then(
	function({ certificate }) { 
		// handle success
	},
	function({ code, detail }) {
		// handle failure
	}
)

Get Available KeyStores

Lists ids of available Keystores found in Alison-Desktop.

Signature

listKeyStores(): Promise<{
	keyStores: {
		id: string
	}[]
}>

Example

alison.listKeyStores().then(
	function({ keyStores }) { 
		// handle success
	},
	function({ code, detail }) {
		// handle failure
	}
)

Get KeyStore Information

Returns information about a specific Keystore.

Signature

keyStoreInfo(KeyStore): Promise<{ keyStore: KeyStoreInfo }>

Example

alison.getKeystoreInfo({
	id: "CSK"
}).then(
	function({ keyStore }) { 
		// handle success
	},
	function({ code, detail }) {
		// handle failure
	}
)

Get Certificate List

Lists certificates found in Alison-Desktop. Returns array of Alison JS.

Signature

certificateList(): Promise<{
	certificates: WebCertificate[];
}>;

Example

alison.certificateList().then(
	function({ certificates }) { 
		// handle success
	},
	function(response) {
		// handle failure
	}
)

Sign text

Uses a certificate to sign a string.

Signature

sign({
    text: string
    certificate: string
    keyStore: KeyStore;
    options?: {
		algorithm?: string;
	  	format?: string;
	 	params?: string;
	}
}): Promise<{ signature: string }>;

Argument	Required	Description
text	✔	Text to be signed in base64 format.
certificate	✔	ThumbPrint of the certificate to use.
options	✘	defaults are { algorithm: 'SHA1withRSA', format: 'CAdES', params: '' }
keyStore	✘	KeyStore where the certificate is located.

Example

alison.sign({
	text: 'text to sign',
	ceritificate: 'C22E8C20D6042B2BF6A6E054B7378FEC57414765',
	keyStore: { id: "WIN-ENH" }
}).then(
	function({ signature }) { 
		// handle success
	},
	function(response) {
		// handle failure
	}
)

Structures

The following interfaces are used by this library.

KeyStore

Interface

KeyStore {
	id: string
	profile?: string
}

Security Policy

Interface

CapiSecurityPolicy {
	exportable?: boolean;
	protectionLevel?: number;
	title?: string;
	friendlyName?: string;
	description?: string;
}

DeviceSecurityPolicy {
	installDummy?: boolean
	generateOnBoard?: boolean
}

PassSecurityPolicy {
	passMinLength: number
	passComplexity: number
}

Pkcs11SecurityPolicy {
	installDummy?: boolean
	generateOnBoard?: boolean
	passMinLength?: number
	passComplexity?: number
}

CskSecurityPolicy {
	id: string
	passMinLength: number
	passComplexity: number
	passLockCount: number
	passExpiration: number
	lockTimeout: number
	idleTimeout: number
	certExport: number
}

SecurityPolicy =
  | EtokenSecurityPolicy
  | CapiSecurityPolicy
  | CskSecurityPolicy
  | DeviceSecurityPolicy
  | PassSecurityPolicy
  | Pkcs11SecurityPolicy
  | {}

Web Certificate

Interface

WebCertificate {
	serialNumber: string
	thumbPrint string
	subjectDN: string
	issuerDN: string
	validity: {
		from: string
		left: number
		until: string
		total: number
		isExpired: boolean
	}
}

Example

Generate and Install a certificate.

Generate and Install a certificate

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

const alison = new AlisonJS.Desktop()

// Call initialize method with License provided by Certisur
alison.initialize({
	accessToken: "eyJ2MSI6eyJpZHgiOiI0LUxpY2Vuc2UiLCJ2YWx1ZSI6IlErZ0ErZE1pSXBkN3pYRCtJNWpJY0g3TnhLY1J5ZndUM3ZTWUk2TmNoWE9lUURmL1JMZHltWFRNRXpsbndlcGJIR1lKVEJQQjFwcklnTE16Qlc5cnBiZFNZcEJBV3pvamhEdW9Ra29ZUWc3dENxSUpHbk9KV1ZYUkZFakhid3h2aVBtbEFkZ3Y3ZXdSNldxd0xpaHRNVVArNzlnRmg5TDMvKzBXd3JDbmd0MHhjbnNnRmpvZkhSeUowS21TQi9Ud25KK3ljZ2tod2ZwUkpUTmpYaGZnbmxIWTRyQXY0WkY0WGNtTkdjYUFkQmpIWFpMK1FOUnV3NitBbnFwekxmRkFrdTB0d2NOVVFoL3l1SlBIZlJYSjdZOGtTa0tzWDh2eTVjdW95ZG9kR3d5YndEUmFxUXprcHlyWkIzaFNKRU5RLzc4c1NYbGNwMDNuNWs0bFp0N0lNK0lOQmJMUlZFby9MUEtYTWIyTXFoaTFub3R0RDlEQ1pZRkJkMzU5ZG5Wd3piQUdlOFozTXpBam4wNUZPRkQzcUhtUGJZcFk1QXNwTzR5bE4wUUhGMUprYlRXVmk4MWh2Z244d1l4MEU1Nm9WRXV0UFg0SSs0TktnODVGV0hReGh5dmJDeVovNm1xeE9WVWhUQ3cyS2lvejRMZEpuVTVmRDZqck9rdCtlSU0yWFo5NUF4NEcvUHh2V2lnaWg1VFFhQT09In0sInYyIjp7ImlkeCI6IjItTGljZW5zZSIsInZhbHVlIjoiZXlKaGJHY2lPaUpTVXpJMU5pSjkuZXlKcFlYUWlPakUxTnpjNU56ZzJOemtzSW1WNGNDSTZNVGMwTkRJMU5EQXdNQ3dpWTI5dGNHRnVlVTVoYldVaU9pSkRaWEowYVZOMWNpQlRMa0V1SWl3aVlXeHNiM2RsWkU5eWFXZHBibk1pT2xzaUtpNWpaWEowYVhOMWNpNWpiMjBpTENJcUxtTmxjblJwYzNWeUxtNWxkQ0lzSW1Gc2FYTnZibVJsYzJ0MGIzQXVjR3RwYUc5emRDNWpiMjBpTENKaGJHbHpiMjVrWlhOcmRHOXdMbkJyYVdodmMzUXVZMjl0T2pnd01EVWlMQ0pqYUhKdmJXVXRaWGgwWlc1emFXOXVPaTh2YTNCcWJHRm5aR3B3WVdscGJXNWxZMlJpWkdOdVpHcGphV3B2WVd4aWJHRWlMQ0pzYjJOaGJHaHZjM1E2T0RBd015SXNJbTF2ZWkxbGVIUmxibk5wYjI0Nkx5OWtabUl3WldJM01pMDFOelU0TFRRek4ySXRZVFV3T0MweU9HUmhNVGs0Tm1Wa1ptUWlMQ0pzYjJOaGJHaHZjM1E2T0RBd05DSXNJbXh2WTJGc2FHOXpkRG80TURBMUlpd2liRzlqWVd4b2IzTjBJaXdpYkc5allXeG9iM04wT2pJd01EUWlMQ0pzYjJOaGJHaHZjM1E2TWpBd05TSXNJakV5Tnk0d0xqQXVNU0lzSWpFeU55NHdMakF1TVRvNE1EQTBJaXdpTVRJM0xqQXVNQzR4T2pnd01EVWlYWDAuYXlhY2hfcmxURzd5XzdDcGZ0c09MQ0MzZF80cko1M3NBZVRPeEVfLU43Qzh6QzdlWk9GUDhJNTBYUm03VTJLTTN4ZjBoQi0xdm0tcGQ1d1lfOFhpbUszZ3hVWl94eTRtNmVidmxmdmZudmFIZmxDTHZ4ZkpRellkclRFeXJtZXNBeEFySVUyX0JrTnJkRHAwUXJLRmhEcXpVbC1Sd291TG9hWEE0RVhhbURlcE1waDVsdDRKc2ZQQ0Q4X3JnMHB0d3lMRGprWXY1YkZtNXJaaEJMOGZJS1Zhd255eUhSY2VEekpZZzZnUXU1OTk1V3MyZExlYUVidVFQSWZVNmE5c29WR1o0WG5WX1pGX08tSnlwNkpVcFZTY1UzS0pjTkM1WDlSdG9mOGpMVjRfZ2pCcmhSUXh5UEgwQlpPUC1jZGhKUWlUa1pwYS1wb3RjZTdNUnVKVE1nIn19",
}).then(function() {
	// Generate KeyPair and Certificate Signing Request in MACOS keyStore

	alison.generateCsr( {
		keyStore: { id: "MACOS" },
		securityPolicy: { 
			installDummy: true
		}
	}).then(function({ csr }) {
		// issue the certificate through an external CA
		const pkcs7 = requestCertificateFromYourCA(csr)

		// install issued certificate
		alison.installPkcs7({
			keyStore: { id: "MACOS" },
			pkcs7: pkcs7
		}).then(function({ certificate }) {
			// Certificate is currently installed in the MACOS keyStore	


			// In case you want to use or test the certificate we just installed, 
			// You can use the "sign" method 
			alison.sign({
				text: 'test signature',
				certificate: certificate.thumbPrint,
				keyStore: { id: "MACOS" }
			}).then(function({ signature }){
				// Print signature result
				console.log(signature)
			}, printError)
		}, printError)
	}, printError)
}, printError)


function printError({ code, detail }) {
	console.log(`error ${code}: ${detail}`)
}