Versions Compared
Version | Old Version 82 | New Version 83 |
---|---|---|
Changes made by | ||
Saved on |
Key
- This line was added.
- This line was removed.
- Formatting was changed.
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.
Related Product
Alison Desktop
Go to the Alison Desktop documentation.
AlisonGUI sdk
Go to the AlisonGUI SDK 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 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.
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 | ✘ | Options for generation. Default values are:
|
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
Install the certificate into the Keystore/profile indicated. Returns 950519
Code Block | ||||
---|---|---|---|---|
| ||||
installPkcs7({ keyStore: KeyStoreSelector, 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 } ) |
.
List KeyStores
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 } ) |
.
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+.
Code Block | ||||
---|---|---|---|---|
| ||||
importCertificate({ keyStore: KeyStoreSelector, securityPolicy?: SecurityPolicy certificateSelector: { keyStoreId: string, profileName: string, thumbPrint?: String, p12?: string, p12Password?: string }}): Promise<{ certificate: WebCertificate }> |
Argument | Required | Description |
---|---|---|
keyStore | ✔ | 950519 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 | ✔ | 950519 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:
Code Block | ||||
---|---|---|---|---|
| ||||
alison.importCertificate({ keyStore: { id: "WIN-ENH" }, securityPolicy: {}, certificateSelector: { keyStoreId: "PFX", profileName: "-Select-" } }).then( function({ certificate }) { // handle success }, function({ code, detail }) { // handle failure } ) |
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Code Block | ||||
---|---|---|---|---|
| ||||
keyStoreInfo(KeyStore): Promise<{ keyStore: KeyStoreInfo }> |
Example:
Code Block | ||||
---|---|---|---|---|
| ||||
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+.
Code Block | ||||
---|---|---|---|---|
| ||||
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:
Code Block | ||||
---|---|---|---|---|
| ||||
alison.listProfiles().then( function({ profiles }) { // handle success }, function({ code, detail }) { // handle failure } ) |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"profiles": [
{
"id": "FF-NSS#>2:primer-acarrata",
"name": "2:primer-acarrata",
"friendlyName": "primer-acarrata",
"keyStoreId": "FF-NSS",
"keyStoreFriendlyName": "Firefox KeyStore",
"keyStoreType": "FIREFOX"
},
{
"id": "ETOKEN#>0:acarrata-personal-7",
"name": "0:acarrata-personal-7",
"friendlyName": "acarrata-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 950519.
Code Block | ||||
---|---|---|---|---|
| ||||
certificateList(): Promise<{ certificates: WebCertificate[]; }>; |
Example:
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; 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:
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}`) } |