- Created by Armando Carratala , last modified on Jan 19, 2021
You are viewing an old version of this content. View the current version.
Compare with Current View Version History
« Previous Version 82 Next »
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 | ✘ | Default values are: { algorithm: 'RSA', size: 2048, csrAlgorithm: 'SHA256WITHRSA' } |
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 certificateSelector: { keyStoreId: string, profileName: string, thumbPrint?: String, p12?: string, p12Password?: string }}): Promise<{ certificate: WebCertificate }>
Argument | Required | Description |
---|---|---|
keyStore | ✔ | AlisonJS SDK#KeyStore where the private Key and certificate will be imported. |
certificateSelector | ✔ | 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. |
CertificateSelector:
Argument | Required | Description |
---|---|---|
keyStoreId | ✔ | AlisonJS SDK#KeyStore where the privateKey and certificate will be imported. |
profileName | ✔ | A Certificate Selector to indicate the source of the certificate and private key to be imported. Possible fixed values:
|
thumbPrint | ✘ | Thumbprint of the certificate to be imported when the keystore have more than one enduser certificate. |
p12 | ✘ | PKCS12 file in Base64 format. This certificate will be imported. |
p12Password | ✘ | Password of p12 file. If none password is indcated, then the user have to enter the password to open the p12 file. |
Example:
alison.importCertificate({ keyStore: { id: "WIN-ENH" }, securityPolicy: {}, certificateSelector: { keyStoreId: "PFX", profileName: "-Select-" } }).then( function({ certificate }) { // handle success }, function({ code, detail }) { // handle failure } )
alison.importCertificate({ keyStore: { id: "MACOS" }, securityPolicy: {}, certificateSelector: { 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 } )
.
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 } )
.
Sign
Uses a certificate to sign a string.
sign({ text: string certificate: string keyStore: KeyStore; 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. |
|
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
KeyStore { id: string profile?: string }
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. Go 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 } 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 } }
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}`) }
- No labels