Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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>

Future Releases

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



Methods

List of available methods.



Code Block
languagejs
titleSignature
constructor(urls?: string[]);


ArgumentRequiredDescription
urlsArray 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 ].


Code Block
languagejs
titleExample
const alison = new AlisonJS.Desktop();


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

Code Block
languageactionscript3
titleLibrary Version
const version = alisonSDK.libVersion;

.


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

Must be called before any other methods.


Code Block
languagejs
titleSignature
initialize({ accessToken: string }) : Promise<void>;


ArgumentRequiredDescription
accessToken

Package containing all the Licenses used by Alison-Desktop to enable its functionality on the domain where is invoked. This value is provided by CertiSur S.A. and includes product license and other information used by the library.

This string is in a Base64 format.


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


.


Detect if some certificate provider (AlisonDesktop) is installed and enabled into the browser.

These methods allow to check if Alison-Desktop is running, and if it is enabled into the browser used. These method must be used after Alison-Desktop initialization returning an error code 20404.

If method initialize() was successful, it's not necessary to call any of these methods.

Available from version 3.0.1+.

isRunning()

Detect if Alison-Desktop is running.

Code Block
languagejs
titleExample
isRunning(): Promise<{ result: boolean }>


isEnabled()

Detect if Alison-Desktop is enabled into the browser used.

Code Block
languagejs
titleExample
isEnabled(): Promise<{ result: boolean }>


enable()

Request AlisonDesktop to ingrate with the browser used.

Code Block
languagejs
titleExample
enable(): Promise<{}>


Note: all these methods depend on security features enabled by browsers, and its accuracy cannot be guaranteed working on any platform and/or browser. 


.


Generates a keyPair and a Certificate Signing Request.


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


ArgumentRequiredDescription
keyStore

950519 where to generate the certificate request.

optionsDefault values are: { algorithm: 'RSA', size: 2048, csrAlgorithm: 'SHA256WITHRSA'  }
securityPolicy

Security requirements to be applied to the keyStore/profile.


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


.


Installs the certificate into the Keystore/profile indicated. Returns 950519


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


ArgumentRequiredDescription
keyStore950519 where the privateKey is stored
pkcs7

Certificate (X.509) and/or Certificate chain (PKCS#7 structure) to be installed (in base64 format). None PEM header must be included.

securityPolicySecurity requirements to be applied to the keyStore/profile.


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


.


Lists ids of available Keystores found in Alison-Desktop.


Code Block
languagejs
titleSignature
listKeyStores(): Promise<{
	keyStores: {
		id: string
	}[]
}>


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


.


Returns information about a specific Keystore.


Code Block
languagejs
titleSignature
keyStoreInfo(KeyStore): Promise<{ keyStore: KeyStoreInfo }>


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


.


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


Code Block
languagejs
titleSignature
certificateList(): Promise<{
	certificates: WebCertificate[];
}>;


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


.


Uses a certificate to sign a string.


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


ArgumentRequiredDescription
textText to be signed in base64 format.
certificateThumbPrint of the certificate to use.
optionsdefaults are {

algorithm: 'SHA1withRSA', format: 'CAdES', params: ''

}
keyStore

KeyStore where the certificate is located.


Code Block
languagejs
titleExample
alison.sign({
	text: 'A43G3RWG224...',
	certificate: 'C22E8C20D6042B2BF6A6E054B7378FEC57414765',
	keyStore: { id: "WIN-ENH" }
}).then(
	function({ signature }) { 
		// handle success
	},
	function(response) {
		// handle failure
	}
)


.


The following interfaces are used by this library.




Code Block
languagejs
titleInterface
KeyStore {
	id: string
	profile?: string
}


This structure was extended with more information from AlisonJS version 3.0.1 and Alison-Desktop 3.1.x.

Code Block
titleKeyStore Structure
KeyStore {
	id: string,
	keyStoreId?: string,
	keyStoreType?: string,
	capabilities?: string,
	friendlyName?: string,
	status: {
		resultStatus: int,
		resultList: []
	},
	profiles?: string
}


A security policy defines behaviour of the keystore or profile, depending each kind of them. Go to this link for a better description of them.

An empty JSON structure must be used to indicate the default one. 

{ }


Code Block
languagetext
titleInterface
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 =
  | CapiSecurityPolicy
  | CskSecurityPolicy
  | DeviceSecurityPolicy
  | PassSecurityPolicy
  | Pkcs11SecurityPolicy
  | {}




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




Generate and Install a certificate.


Code Block
languagejs
themeEclipse
titleGenerate 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}`)
}