Image Removed

Table of Contents
maxLevel 2 indent circle

Image Added

Related Product

Alison Desktop

Go to the Alison Desktop documentation.

AlisonGUI SDK

Go to the AlisonGUI SDK documentation.

Methods

List of available methods.

constructor(urls?: string[]);

const alison = new AlisonJS.Desktop();

const version = alisonSDK.libVersion;

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

Must be called before any other methods.

initialize({ accessToken: string }) : Promise<void>;

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

.

Generates a keyPair and a Certificate Signing Request.

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

950519 where to generate the certificate request.

Options for generation. Default values are:
{
     algorithm: 'RSA',
     size: 2048,
     signatureAlgorithm: 'SHA256WITHRSA' 
}

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 the certificate into the Keystore/profile indicated. Returns 950519

installPkcs7({
	keyStore: KeyStoreSelector,
	pkcs7: string,
	securityPolicy?: SecurityPolicy
}): Promise<{ certificate: WebCertificate }>

Certificate (X.509) and/or Certificate chain (PKCS#7 structure) to be installed (in base64 format). None PEM header must be included.

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.

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

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

importCertificate({
	keyStore: KeyStoreSelector,
	securityPolicy?: SecurityPolicy
    certificateToImport: CertificateSelector
    }}): Promise<{ certificate: WebCertificate }>

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. 

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

.

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

.

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
	}[]
}>

Profile ID, composed by KeyStoreID + KeyStoreName

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

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"
		}

	]
}

.

Lists certificates found in Alison-Desktop. Returns array of 950519.

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

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.

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 }>;

Depending of the function:

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

• 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)

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
  

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

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 }>;

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

KeyStore where the certificate is located.

Options fields

• 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)

• 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
  

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

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:

alison.sign({
	text: 'A43G3RWG224...',
	certificate: 'C22E8C20D6042B2BF6A6E054B7378FEC57414765',
	keyStore: { id: "WIN-ENH" }
}).then(
	function({ signature }) { 
		// handle success
	},
	function(response) {
		// handle failure
	}
)

.

-

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
}

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
  | {}

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
}

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

.

ProfileName where the certificate is stored.

.