AlisonJS SDK
Armando Carratala
Former user (Deleted)
Julio D'Angelo
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.
Related Product
Alison Desktop
Go to the Alison Desktop documentation.
AlisonGUI sdk
Go to the AlisonGUI SDK documentation.
Methods
List of available methods.
Constructor
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 ]. |
const alison = new AlisonJS.Desktop();
Version
Use the attribute libVersion to determine current version of the library.
const version = alisonSDK.libVersion;
.
Initialize
Opens a session with a certificate provider (Alison-Desktop or Alison-Server).
Must be called before any other methods.
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 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. |
alison.initialize({ accessToken: "eyJ2M9==" }).then( function() { // handle success }, function({ code, detail }) { // handle failure } )
.
Detect / Enable
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(): Promise<{ result: boolean }>
isEnabled()
Detect if Alison-Desktop is enabled into the browser used.
isEnabled(): Promise<{ result: boolean }>
enable()
Request AlisonDesktop to ingrate with the browser used.
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.
.
Generate CSR
Generates a keyPair and a Certificate Signing Request.
generateCsr({ keyStore: KeyStore options?: { algorithm?: string size?: number signatureAlgorithm?: string } securityPolicy?: SecurityPolicy }): Promise<{ csr: string }>
Argument | Required | Description |
---|---|---|
keyStore | ✔ | AlisonJS SDK#KeyStore where to generate the certificate request. |
options | ✘ | Options for generation. Default values are: |
securityPolicy | ✘ | Security requirements to be applied to the keyStore/profile. |
alison.generateCsr({ keyStore: { id: "WIN-ENH" }, options: { size: 2048 }, securityPolicy: { exportable: true } }).then( function({ csr }) { // handle success }, function({ code, detail }) { // handle failure } )
.
Install Certificate
Install the certificate into the Keystore/profile indicated. Returns AlisonJS SDK#WebCertificate
installPkcs7({ keyStore: KeyStoreSelector, pkcs7: string, securityPolicy?: SecurityPolicy }): Promise<{ certificate: WebCertificate }>
Argument | Required | Description |
---|---|---|
keyStore | ✔ | AlisonJS 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. |
securityPolicy | ✘ | Security requirements to be applied to the keyStore/profile. |
alison.installPkcs7({ keyStore: { id: "WIN-ENH" }, pkcs7: "MIICU5iNXuudGfc=" }).then( function({ certificate }) { // handle success }, function({ code, detail }) { // handle failure } )
.
List KeyStores
Lists ids of available Keystores found in Alison-Desktop.
listKeyStores(): Promise<{ keyStores: { id: string }[] }>
alison.listKeyStores().then( function({ keyStores }) { // handle success }, function({ code, detail }) { // handle failure } )
.
Import Certificate
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+.
importCertificate({ keyStore: KeyStoreSelector, securityPolicy?: SecurityPolicy certificateToImport: CertificateSelector }}): Promise<{ certificate: WebCertificate }>
Argument | Required | Description |
---|---|---|
keyStore | ✔ | AlisonJS 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. |
securityPolicy | ✘ | Security requirements to be applied to the keyStore/profile. |
Example:
alison.importCertificate({ keyStore: { id: "WIN-ENH" }, securityPolicy: {}, certificateToImport: { keyStoreId: "PFX", profileName: "-Select-" } }).then( function({ certificate }) { // handle success }, function({ code, detail }) { // handle failure } )
alison.importCertificate({ keyStore: { id: "MACOS" }, securityPolicy: {}, certificateToImport: { keyStoreId: "MEM", p12: "MIbYMPmA2udTAHhxywMVpqifY...74QShA67pLpk7yuYzVYYVAIDAYag" p12Password: "randomPass" } }).then( function({ certificate }) { // handle success }, function({ code, detail }) { // handle failure } )
.
Get KeyStore Information
Returns information about a specific Keystore.
keyStoreInfo(KeyStore): Promise<{ keyStore: KeyStoreInfo }>
Example:
alison.getKeystoreInfo({ id: "CSK" }).then( function({ keyStore }) { // handle success }, function({ code, detail }) { // handle failure } )
.
List Profiles
Lists available profiles found by Alison-Desktop.
Available from version AlisonJS v3.1.0+. Requires Desktop v3.1.8+.
listProfiles(): Promise<{ profiles: { id: string, name: string, friendlyName: string, keyStoreId: string, keyStoreFriendlyName?: string, keyStoreType: string }[] }>
Argument | Description |
---|---|
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. |
friendlyName | Profile Friendly Name, useful to be shown to the user. |
keyStoreId | KeyStoreID, as defined by the Desktop Application. |
keyStoreFriendlyName | Friendly Name of the keyStore, defined by the Desktop Application. |
keyStoreType | One of the following valued: WINDOWS, MACOS, FIREFOX, TOKEN, CSK, PFX. |
Example:
alison.listProfiles().then( function({ profiles }) { // handle success }, function({ code, detail }) { // handle failure } )
{ "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" } ] }
.
List Certificates
Lists certificates found in Alison-Desktop. Returns array of AlisonJS SDK#WebCertificate.
certificateList(): Promise<{ certificates: WebCertificate[]; }>;
Example:
alison.certificateList().then( function({ certificates }) { // handle success }, function(response) { // handle failure } )
.
Signing functions
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.
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.
getSignatures({ dataToSignB64: [string] format?: string algorithm: string; extraParams?: string; signingCertificate: CertificateSelector; }): Promise<{ signature: [string], certificate: WebCertificate, profileId: string }>;
Argument | Required | Description | Possible Values |
---|---|---|---|
dataToSignB64 | ✔ | Depending of the function:
| |
algorithm | ✔ | Signature Algorithm. |
|
format? | ✘ | Signature type. Some signatures are only supported by desktop. Default value is PKCS1. |
|
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. |
|
signingCertificate | ✔ | A Certificate Selector structure indicating the certificate used to sign. |
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
sign({ text: string certificate: string keyStore: KeyStoreSelector; options?: { algorithm?: string; format?: string; extraParams?: string; textFormat?: 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: 'SHA256withRSA', |
keyStore | ✘ | KeyStore where the certificate is located. |
Options fields
Argument | Required | Description | Possible Values |
---|---|---|---|
algorithm | ✔ | Signature Algorithm |
|
format | ✔ | Signature type. Some signatures are only supported by desktop (AD). Alison Server (AS) only supports some of them. |
|
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. |
|
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. |
|
Example:
alison.sign({ text: 'A43G3RWG224...', certificate: 'C22E8C20D6042B2BF6A6E054B7378FEC57414765', keyStore: { id: "WIN-ENH" } }).then( function({ signature }) { // handle success }, function(response) { // handle failure } )
.
Structures
The following interfaces are used by this library.
-
KeyStore
This structure was extended with more information from AlisonJS version 3.0.1 and Alison-Desktop 3.1.x+.
KeyStore { id: string, keyStoreId?: string, keyStoreType?: string, capabilities?: string, friendlyName?: string, status: { resultStatus: int, resultList: [] }, profiles?: string }
Security Policy
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.
{ }
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 } }
.
Certificate Selector
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 { keyStoreId: string profileName?: string thumbPrint?: string p12?: string p12Password?: string }
Field | Required | Description |
---|---|---|
keyStoreId | ✔ | KeyStoreID where the certificate is stored. |
profileName | ✘ | ProfileName where the certificate is stored. Under certtain functions, some fixed values can be:
|
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. |
p12 | ✘ | PKCS12 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. |
p12Password | ✘ | The password of p12 file. If no password is indicated, then the password will be required to open the p12 file. |
.
KeyStore Selector
This structure is used to reference a unique profile into a specific keystore.
KeyStoreSelector { id: string profile?: string }
Field | Required | Description |
---|---|---|
id | ✔ | KeyStoreID where the certificate is stored. |
profile | ✘ | ProfileName where the certificate is stored. |
.
Example
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}`) }