Versions Compared
Version | Old Version 76 | New Version 77 |
---|---|---|
Changes made by | ||
Saved on |
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Image Removed
Image Added
Table of Contents | ||||
---|---|---|---|---|
|
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.
Note | ||
---|---|---|
| ||
DisclaimerThis 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
List of available methods.
Constructor
Code Block | ||||
---|---|---|---|---|
| ||||
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 ]. |
Code Block | ||||
---|---|---|---|---|
| ||||
const alison = new AlisonJS.Desktop(); |
Version
Use the attribute libVersion to determine current version of the library.
Code Block | ||||
---|---|---|---|---|
| ||||
const version = alisonSDK.libVersion; |
.
Anchor | ||||
---|---|---|---|---|
|
Opens a session with a certificate provider (Alison-Desktop or Alison-Server).
Must be called before any other methods.
Code Block | ||||
---|---|---|---|---|
| ||||
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. |
Code Block | ||||
---|---|---|---|---|
| ||||
alison.initialize({ accessToken: "eyJ2M9==" }).then( function() { // handle success }, function({ code, detail }) { // handle failure } ) |
.
Anchor | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
| ||||
isRunning(): Promise<{ result: boolean }> |
isEnabled()
Detect if Alison-Desktop is enabled into the browser used.
Code Block | ||||
---|---|---|---|---|
| ||||
isEnabled(): Promise<{ result: boolean }> |
enable()
Request AlisonDesktop to ingrate with the browser used.
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Code Block | ||||
---|---|---|---|---|
| ||||
generateCsr({ keyStore: KeyStore options?: { algorithm?: string size?: number signatureAlgorithm?: string } securityPolicy?: SecurityPolicy }): Promise<{ csr: string }> |
Argument | Required | Description |
---|---|---|
keyStore | ✔ | 950519 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. |
Code Block | ||||
---|---|---|---|---|
| ||||
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 950519
Code Block | ||||
---|---|---|---|---|
| ||||
installPkcs7({ keyStore: KeyStore pkcs7: string securityPolicy?: SecurityPolicy }): Promise<{ certificate: WebCertificate }> |
Argument | Required | Description |
---|---|---|
keyStore | ✔ | 950519 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. |
Code Block | ||||
---|---|---|---|---|
| ||||
alison.installPkcs7({ keyStore: { id: "WIN-ENH" }, pkcs7: "MIICU5iNXuudGfc=" }).then( function({ certificate }) { // handle success }, function({ code, detail }) { // handle failure } ) |
.
KeyStore List
Lists ids of available Keystores found in Alison-Desktop.
Code Block | ||||
---|---|---|---|---|
| ||||
listKeyStores(): Promise<{ keyStores: { id: string }[] }> |
Code Block | ||||
---|---|---|---|---|
| ||||
alison.listKeyStores().then( function({ keyStores }) { // handle success }, function({ code, detail }) { // handle failure } ) |
.
KeyStore Information
Returns information about a specific Keystore.
Code Block | ||||
---|---|---|---|---|
| ||||
keyStoreInfo(KeyStore): Promise<{ keyStore: KeyStoreInfo }> |
Code Block | ||||
---|---|---|---|---|
| ||||
alison.getKeystoreInfo({ id: "CSK" }).then( function({ keyStore }) { // handle success }, function({ code, detail }) { // handle failure } ) |
.
Certificate List
Lists certificates found in Alison-Desktop. Returns array of 950519.
Code Block | ||||
---|---|---|---|---|
| ||||
certificateList(): Promise<{ certificates: WebCertificate[]; }>; |
Code Block | ||||
---|---|---|---|---|
| ||||
alison.certificateList().then( function({ certificates }) { // handle success }, function(response) { // handle failure } ) |
.
Sign
Uses a certificate to sign a string.
Code Block | ||||
---|---|---|---|---|
| ||||
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. |
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Anchor | ||||
---|---|---|---|---|
|
Code Block | ||||
---|---|---|---|---|
| ||||
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 | ||
---|---|---|
| ||
KeyStore { id: string, keyStoreId?: string, keyStoreType?: string, capabilities?: string, friendlyName?: string, status: { resultStatus: int, resultList: [] }, profiles?: string } |
Anchor | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
| ||||
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 | {} |
Anchor | ||||
---|---|---|---|---|
|
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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}`) } |