/
AlisonJS SDK

AlisonJS SDK


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.



Constructor
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 ].


Example
const alison = new AlisonJS.Desktop();

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

Library Version
const version = alisonSDK.libVersion;

.


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

Must be called before any other methods.


Initialize
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.


Example
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 Desktop v3.0.1+.

isRunning()

Detect if Alison-Desktop is running.

Note: this function depends on browser security policy, and this policy can change between different browser manufacturers and versions. By default, this function will return false, except if the library can detect that Desktop client is running and security browser policy allows its detection.

isRunning
isRunning(): Promise<{ result: boolean }>

isEnabled()

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

isEnabled
isEnabled(): Promise<{ result: boolean }>

enable()

Request AlisonDesktop to ingrate with the browser used.

enable
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.


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

AlisonJS SDK#KeyStore where to generate the certificate request.

options

Options for generation. Default values are:
{
     algorithm: 'RSA',
     size: 2048,
     signatureAlgorithm: '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 the certificate into the Keystore/profile indicated. Returns AlisonJS SDK#WebCertificate


installCertificate
installPkcs7({
	keyStore: KeyStoreSelector,
	pkcs7: string,
	securityPolicy?: SecurityPolicy
}): Promise<{ certificate: WebCertificate }>
ArgumentRequiredDescription
keyStoreAlisonJS SDK#KeyStore 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.
Example
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.


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


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

.


Import a certificate and its private key into a Keystore. (> v3.1.1)

Available from version AlisonJS v3.1.1+. Requires Desktop v3.2.0+.


import Certificate
importCertificate({
	keyStore: KeyStoreSelector,
	securityPolicy?: SecurityPolicy
    certificateToImport: CertificateSelector
    }}): Promise<{ certificate: WebCertificate }>
ArgumentRequiredDescription
keyStoreAlisonJS SDK#KeyStore where the private Key and certificate will be imported.
certificateToImport

A Certificate Selector to indicate the source of the certificate and private key to be imported. The private key of the certificate must be exportable from the Keystore that contains it. 

securityPolicySecurity requirements to be applied to the keyStore/profile.

Example:

Example from PFX file
alison.importCertificate({
	keyStore: { id: "WIN-ENH" },
	securityPolicy: {},
	certificateToImport: {
		keyStoreId: "PFX",
		profileName: "-Select-"
	}
}).then(
	function({ certificate }) { 
		// handle success
	},
	function({ code, detail }) {
		// handle failure
	}
)
Example from embed PKCS#12 file
alison.importCertificate({
	keyStore: { id: "MACOS" },
	securityPolicy: {},
	certificateToImport: {
		keyStoreId: "MEM",
		p12: "MIbYMPmA2udTAHhxywMVpqifY...74QShA67pLpk7yuYzVYYVAIDAYag"
		p12Password: "randomPass"
	}
}).then(
	function({ certificate }) { 
		// handle success
	},
	function({ code, detail }) {
		// handle failure
	}
)

.


Returns information about a specific Keystore.


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


Example:

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

.


Lists available profiles found by Alison-Desktop. 

Available from version AlisonJS v3.1.0+. Requires Desktop v3.1.8+.

keyStore List
listProfiles(): Promise<{
	profiles: {
		id: string,
        name: string,
        friendlyName: string,
        keyStoreId: string,
        keyStoreFriendlyName?: string,
        keyStoreType: string
	}[]
}>
ArgumentDescription
id

Profile ID, composed by KeyStoreID + KeyStoreName

name

Profile Name. It's usually composed by <port>:<profile_name>. Profile_name depends on the kind of Keystore.

friendlyNameProfile Friendly Name, useful to be shown to the user.
keyStoreIdKeyStoreID, as defined by the Desktop Application.
keyStoreFriendlyNameFriendly Name of the keyStore, defined by the Desktop Application.
keyStoreTypeOne of the following valued: WINDOWS, MACOS, FIREFOX, TOKEN, CSK, PFX.

Example:

Example
alison.listProfiles().then(
	function({ profiles }) { 
		// handle success
	},
	function({ code, detail }) {
		// handle failure
	}
)
Result Example
{
	"profiles": [
		{
			"id": "FF-NSS#>2:first-working-profile",
			"name": "2:first-working-profile",
			"friendlyName": "first-working-profile",
			"keyStoreId": "FF-NSS",
			"keyStoreFriendlyName": "Firefox KeyStore",
			"keyStoreType": "FIREFOX"
		},
		{
			"id": "ETOKEN#>0:a-personal-7",
			"name": "0:a-personal-7",
			"friendlyName": "a-personal-7",
			"keyStoreId": "ETOKEN",
			"keyStoreFriendlyName": "Gemalto eToken",
			"keyStoreType": "TOKEN"
		},
		{
			"id": "MACOS#>login.keychain",
			"name": "login.keychain",
			"friendlyName": "MacOS Login Keychain",
			"keyStoreId": "MACOS",
			"keyStoreFriendlyName": "MacOS Keychain",
			"keyStoreType": "MACOS"
		}

	]
}


.


Lists certificates found in Alison-Desktop. Returns array of AlisonJS SDK#WebCertificate.


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


Example:

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

.


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

Available from AlisonJS version 3.1.3. Requires Alison-Desktop 3.2.0.

Signature
getSignature({
    dataToSignB64: string
    format?: string
    algorithm: string;
    extraParams?: string;
    signingCertificate: CertificateSelector;
}): Promise<{ signature: string, 
			  certificate: WebCertificate, 
			  profileId: string }>;

Available from AlisonJS version 3.1.5. Requires Alison-Desktop 3.2.0.

Signature
getSignatures({
    dataToSignB64: [string]
    format?: string
    algorithm: string;
    extraParams?: string;
    signingCertificate: CertificateSelector;
}): Promise<{ signature: [string], 
			  certificate: WebCertificate, 
			  profileId: string }>;
ArgumentRequiredDescriptionPossible Values
dataToSignB64

Depending of the function:

  • String in base64 format.
  • Array of Strings in base64 format.

algorithmSignature 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:

Example
alison.getSignature({
	dataToSignB64: 'A43G3RWG224...',
	algorithm: 'SHA256withRSA',
	signingCertificate: { 
		keyStoreId: 'WIN-ENH';
		thumpPrint: 'C22E8C20D6042B2BF6A6E054B7378FEC57414765',
 }
}).then(
	function({ signature }) { 
		// handle success
	},
	function(response) {
		// handle failure
	}
)

Available up to AlisonJS - version 3.0.5

Signature
sign({
    text: string
    certificate: string
    keyStore: KeyStoreSelector;
    options?: {
		algorithm?: string;
	  	format?: string;
	 	extraParams?: string;
	 	textFormat?: string;
	}
}): Promise<{ signature: string }>;
ArgumentRequiredDescription
textText to be signed in base64 format.
certificateThumbPrint of the certificate to use.
optionsdefaults are {

    algorithm: 'SHA256withRSA',
    format: 'CAdES',
    extraParams: '',
    textFormat: ''

}
keyStore

KeyStore where the certificate is located.


Options fields

ArgumentRequiredDescriptionPossible Values
algorithmSignature 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 (AD).

Alison Server (AS) only supports some of them.

  • PKCS1 | NONE (AD | AS)
  • CAdES (0.4.0.19122) (AD | AS)
  • XAdES (AD)
  • XAdES Detached (AD)
  • XAdES Enveloped (AD)
  • XAdES Enveloping (AD)
  • XMLDSig (AD)
  • XMLDSig Detached (AD)
  • XMLDSig Enveloped (AD)
  • XMLDSig Enveloping (AD)
  • XMLDSig SignedInfo (custom - desktop) (AD)
  • PAdES (AD)
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

textFormat

Format of the text to be signed. This value is used to transform the signed text before of showing it to the end-user.

  • base64
  • <empty>

Example:

Example
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.

-


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

KeyStore 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.

Follow to this link for a better description of them.

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

{ }
Security Policy
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
    modelTemplate?: string
}

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

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

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

.


This structure is used to reference a unique certificate. It must be used in some functions, like to generate a signature or import a certificate.

CertificateSelector Interface
CertificateSelector {
	keyStoreId: string
	profileName?: string
	thumbPrint?: string
	p12?: string
	p12Password?: string
}
FieldRequiredDescription
keyStoreIdKeyStoreID where the certificate is stored.
profileName

ProfileName where the certificate is stored.

Under certtain functions, some fixed values can be:

  • "-New-": a new profile will be created. This value only is valid with some kind of Keystore, like PKCS#12 or CSK.
  • "-Select-": select one of the profiles available, for example, to open a PKCS#12 file.
thumbPrint

Thumbprint of the certificate to be used.

When profileName is '-Select-', this value is completed by Desktop App when user select the certificate. Under other conditions, this value must be set with the thumbPrint of the certificate.

p12PKCS12 file in Base64 format. This value can be used to import a certificate into a keyStore. A PKCS#12 file in base64 format must be included here.
p12PasswordThe password of p12 file. If no password is indicated, then the password will be required to open the p12 file. 

.


This structure is used to reference a unique profile into a specific keystore.
KeyStoreSelector Interface
KeyStoreSelector {
	id: string
	profile?: string
}
FieldRequiredDescription
idKeyStoreID where the certificate is stored.
profile

ProfileName where the certificate is stored.

.


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}`)
}

Related content

AlisonGUI SDK
More like this
Alison SDK
More like this
Alison Desktop
More like this
Alison Suite Products
Alison Suite Products
More like this
CoLT Issue Certificate
CoLT Issue Certificate
Read with this
AlisonSDK v1 - legacy
AlisonSDK v1 - legacy
More like this