web-pki/lacuna-web-pki.d.ts

The Lacuna Web PKI component enables web applications to interact with digital certificates through javascript, without the need of Java.

export default LacunaWebPKI;

export declare class LacunaWebPKI {

	/**************************************************************
	 * Instatiates a new Lacuna Web PKI object.
	 * @param license The license for the component. May be a string or an object (see [Licensing](http://docs.lacunasoftware.com/articles/web-pki/licensing)).
	 * In order for the component to work, you must set a valid purchased license that matches the URL of the site running the code.
	 * If no licesnse is set, the component will work in localhost only, so you can test as much as you want in development before deciding to license it.
	 *
	 * @returns
	 *
	 * Binary license sample
	 * ```javascript
	 * // Here, we use the binary format of our license. This is preferred if you want to hide the details of your license
	 * // (expiration date and allowed domains). Please note that the details are not encrypted, just encoded in Base64.
	 * var pki = new LacunaWebPKI('ASYAanNmaWRkbGUubmV0LHdlYnBraS5sYWN1bmFzb2Z0d2FyZS5jb20AAAABClKvO1J22vAD+YmfANiKQLbcLE1lNraPKCel6tRM+ZxR+h6M/crtJYRRVGGz7hrdbM0Y0mfTu15RMYGqQMi1QNZS6GrT4vNzIayv552Fl0EFWQA7jWlctUwfYoHRHVEnCNx9YGXDiA9+yDoGlVwgTR7fjzNeS3Fen1MVIyKBF464gN0JvdiCRJMI47JGVDkPmKjcrYIvJs6y5Lg25RW4ZnBKVruS+HR2s3k8ZrV4y4RCQE4UYMKbukF9vsF+JqAEifRlPq2xLcrNdxBveVDSXS/LRHAcrZrMM+Iw4A79jl0ngWPcy+CwinAhT+3dxVo5ZWMRQFpmTkylEMDvTjV9wQ==');
	 * ```
	 *
	 * JSON license sample
	 * ```javascript
	 * // Here, we use the JSON format of our license. If you don't mind having the details of your license (expiration
	 * // date and allowed domains) in the source code of your page, this option is preferred because it makes it
	 * // easier to diagnose problems such as an expired license.
	 * var pki = new LacunaWebPKI( {
	 *     "format": 1,
	 *     "allowedDomains": [
	 *         "webpki.lacunasoftware.com",
	 *         "jsfiddle.net"
	 *     ],
	 *     "expiration": null,
	 *     "signature": "ClKvO1J22vAD+YmfANiKQLbcLE1lNraPKCel6tRM+ZxR+h6M/crtJYRRVGGz7hrdbM0Y0mfTu15RMYGqQMi1QNZS6GrT4vNzIayv552Fl0EFWQA7jWlctUwfYoHRHVEnCNx9YGXDiA9+yDoGlVwgTR7fjzNeS3Fen1MVIyKBF464gN0JvdiCRJMI47JGVDkPmKjcrYIvJs6y5Lg25RW4ZnBKVruS+HR2s3k8ZrV4y4RCQE4UYMKbukF9vsF+JqAEifRlPq2xLcrNdxBveVDSXS/LRHAcrZrMM+Iw4A79jl0ngWPcy+CwinAhT+3dxVo5ZWMRQFpmTkylEMDvTjV9wQ=="
	 * });
	 * ```
	 */
	constructor(license?: string | Object);

	readonly standardTrustArbitrators: {
		pkiBrazil: TrustArbitrator,
		pkiItaly: TrustArbitrator,
		windows: TrustArbitrator
	};

	/**************************************************************
	 * Web PKI standard PKCS#11 modules. Useful presets for `pkcs11Modules` argument of [[listTokens]], [[generateTokenRsaKeyPair]] and [[importTokenCertificate]] methods.
	 */
	readonly pkcs11Modules: {
		/** SafeSign PKCS#11 lib modules. */
		safeSign: Pkcs11Module,
		/** SafeNet PKCS#11 lib modules. */
		safeNet: Pkcs11Module
	}

	// /**************************************************************
	//  * Preset filters for [[listCertificates.filters]]
	//  */
	// readonly filters: {
	// 	isPkiBrazilPessoaFisica: Filter,
	// 	hasPkiBrazilCpf: Filter,
	// 	hasPkiBrazilCnpj: Filter,
	// 	pkiBrazilCpfEquals(cpf: string): Filter,
	// 	pkiBrazilCnpjEquals(cnpj: string): Filter,
	// 	hasPkiItalyCodiceFiscale: Filter,
	// 	pkiItalyCodiceFiscaleEquals(cf: string): Filter,
	// 	isWithinValidity: Filter,
	// 	all(filters: Filter[]): Filter,
	// 	all(...filters: Filter[]): Filter,
	// 	any(filters: Filter[]): Filter,
	// 	any(...filters: Filter[]): Filter
	// };

	/**************************************************************
	 * Object with CAdES acceptable policies preset
	 */
	readonly cadesAcceptablePolicies: {
		/** Any PKI Brazil acceptable policies */
		pkiBrazil: LacunaWebPKI.CadesPolicies[]
	}

	/**************************************************************
	 * Object with XAdES acceptable policies preset
	 */
	readonly xmlAcceptablePolicies: {
		/** Any PKI Brazil acceptable policies */
		pkiBrazil: LacunaWebPKI.XmlPolicies[]
	}

	/**************************************************************
	 * Whether or not currently running on a supported mobile platform (andoird, iOS) and current vendor supports mobile.
	 */
	readonly isSupportedMobile: boolean;


	/**************************************************************
	 * Initializes the instance of the LacunaWebPKI object. This method must be called before calling any other methods.
	 *
	 * @returns
	 *
	 * Simple `ready` example
	 * ```javascript
	 * // This is the simplest way to call the method, in case you don't wish to register a default error callback nor
	 * // define a custom behavior for when the component is not installed/outdated.
	 * pki.init({ ready: onWebPkiReady });
	 * 
	 * // The ready callback receives no arguments
	 * function onWebPkiReady() {
	 *     // start using the component
	 * }
	 * ```
	 * 
	 * Complete example
	 * ```javascript
	 * // If you wish to pass any other argument, you must use the extended version of the method:
	 * pki.init({
	 *     ready: onWebPkiReady,
	 *     notInstalled: onWebPkiNotInstalled,
	 *     defaultFail: onWebPkiFail
	 * });
	 * 
	 * function onWebPkiReady() {
	 *     // start using the component
	 * }
	 * 
	 * // The notInstalled callback
	 * function onWebPkiNotInstalled(status, message) {
	 *     alert(message + '\n\nYou will be redirected to the installation page');
	 *     pki.redirectToInstallPage();
	 * }
	 * 
	 * // The default fail callback
	 * function onWebPkiFail(ex) {
	 *     alert(ex.userMessage);
	 *     console.log('Web PKI error from ' + ex.origin + ': ' + ex.error + ' (' + ex.code + ')');
	 * }
	 * ```
	 *
	 * JSFiddle live example: [init method full example](https://jsfiddle.net/LacunaSoftware/apak22ba/)
	 */
	init(args: {
		/** A function to be called when the component is ready to be used. The function receives no arguments. */
		ready: () => any,

		/** The license for the component, if not already set when instantiating the object. */
		license?: string | Object,
		
		/** If you intend to use a specifc features set, pass the equivalent API version required parameter, so you can ensure that the users will have the minimum components required versions and will not force any unecessary update. See the [API changelog](http://docs.lacunasoftware.com/articles/web-pki/changelog) for more information. */
		requiredApiVersion?: LacunaWebPKI.ApiVersions,
		
		/** A function to be called if the component's installation is not OK (component not installed, outdated or user is using an unsupported browser). If no callback is given, the user is automatically redirected to the installation website and will be redirected back once the installation is completed. If you do pass a callback to override the default behavior, use the [[redirectToInstallPage]] method to redirect the user to the installation page whenever you think it's convenient. */
		notInstalled?: (
			/** The reason for the failed verification */
			status: LacunaWebPKI.InstallationStates,
			/** A user-friendly message describing the reason for the failure. */
			message: string
		) => any,
		
		/** The default callback to be called when an error occurrs (please refer to examples below for the exact function signature). */
		defaultFail?: FailCallback,

		/** Whether or not to share and persiste the native app instances per hostname. Default is one native app instance per page. */
		useDomainNativePool?: boolean,
		
		/** If your webpage uses AngularJS, you can pass here a reference to your $scope, which will then be used to call the callback functions properly, relieving you of doing a `$scope.$apply(function() { ... });` on every callback. The calls are actually wrapped around a "safe $apply", as described in [coderwall](https://coderwall.com/p/ngisma/safe-apply-in-angular-js). */
		angularScope?: Object,
		
		/** If your webpage uses Angular2+ technologies, you can pass a [NgZone](https://angular.io/api/core/NgZone) reference, so the page can properly detect elements changes on the callback functions. */
		ngZone?: Object,
		
		/** The brand name for customized install page, if license covered. */
		brand?: string,

		/** The mobile integration mode. Default is [[LacunaWebPKI.MobileIntegrationModes.AppIntegration]]. */
		mobileIntegrationMode?: LacunaWebPKI.MobileIntegrationModes,
		
		/** The *on premises* Rest PKI URL. For *on premises* Rest PKI clients integration only. */
		restPkiUrl?: string
	}): Promise<Object>;

	/**************************************************************
	 * Lists the user available certificates in OS certificate store or connected crypto devices
	 * 
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives an array of [[CertificateModel]]
	 *
	 * Usage example (JavaScript)
	 * ```javascript
	 * pki.listCertificates().success(function (certs) {
	 *     // Use certificate list "certs"
	 * });
	 * ```
	 * Lacuna Live Example: [Listing Certificates](https://jsfiddle.net/LacunaSoftware/ezg6hz7n/)
	 * Lacuna Live Example: [Listing Certificates And Show Details](https://jsfiddle.net/LacunaSoftware/fxpavm8y/)
	 */
	listCertificates(args?: {
		/** A html `<select>` (dropdown) element `id` to be automatically populated with the available certificates. You can also pass the `selectOptionFormatter` function argument for formatting the populated options text. If no formatter function is passed, the default text formatting for a certificate `c` is "`c.subjectName` (issued by `c.issuerName`)" */
		selectId?: string,

		/** An `<option>` text formatter for the passed `selectId`. The formatter function must return a desired text for each [[CertificateModel]]. */
		selectOptionFormatter?: (c: CertificateModel) => string
	}): Promise<CertificateModel[]>;

	/**************************************************************
	 * Gets a certificate content
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives the (Base64 encoded) certificate DER bytes.
	 *
	 * Usage example (JavaScript)
	 * ```javascript
	 * pki.readCertificate({
	 *     thumbprint: $('#certificateSelect').val()
	 * }).success(function (content) {
	 *     // Use certificate content
	 * });
	 * ```
	 *
	 * JSFiddle live example: [Listing and reading certificates](https://jsfiddle.net/LacunaSoftware/ezg6hz7n/)
	 */
	readCertificate(args: {
		/** The certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		thumbprint: string
	}): Promise<string>;

	/**************************************************************
	 * Signs a hash with signer certificate private key.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives the (Base64 encoded) signature bytes.
	 *
	 * Usage example (JavaScript)
	 * ```javascript
	 * var hashToSign = 'f4OxZX/x/FO5LcGBSKHWXfwtSx+j1ncoSt3SABJtkGk='; // Base64 encoded SHA-256 of 'Hello World!'
	 *
	 * pki.signHash({
	 *     thumbprint: $('#certificateSelect').val(),
	 *     hash: hashToSign,
	 *     digestAlgorithm: 'SHA-256'
	 * }).success(function (signature) {
	 *     // Use signature
	 * });
	 * ```
	 *
	 * JSFiddle live example: [Operates with selected certificate](https://jsfiddle.net/LacunaSoftware/4ayksync/)
	 */
	signHash(args: {
		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		thumbprint: string,
		/** The Base64 encoded hash to be signed. */
		hash: string,
		/** The digest algorithm identifier of the `hash` parameter. It can be the algorithm name or OID (i.e. `'SHA-256'` or `'2.16.840.1.101.3.4.2.1'`). */
		digestAlgorithm: string
	}): Promise<string>;

	/**********************************************************
	 * Signs data with signer certificate private key.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives the (Base64 encoded) signature bytes.
	 *
	 * Usage example (JavaScript)
	 * ```javascript
	 * var dataToSign = 'SGVsbG8gV29ybGQh'; // 'Hello World!' Base64 encoded
	 *
	 * pki.signData({
	 *     thumbprint: $('#certificateSelect').val(),
	 *     data: dataToSign,
	 *     digestAlgorithm: 'SHA-256'
	 * }).success(function (signature) {                                     
	 *     // Use signature
	 * });
	 * ```
	 *
	 * JSFiddle live example: [Operates with selected certificate](https://jsfiddle.net/LacunaSoftware/4ayksync/)
	 */
	signData(args: {
		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		thumbprint: string,
		/** The Base64 encoded data to be signed. */
		data: string,
		/** The digest algorithm identifier to be used in the signature algorithm. It can be the algorithm name or OID (i.e. `'SHA-256'` or `'2.16.840.1.101.3.4.2.1'`). */
		digestAlgorithm: string
	}): Promise<string>;

	/**********************************************************
	 * Signs a hash with a generated private key.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives the (Base64 encoded) signature bytes.
	 *
	 */
	keySignHash(args: {
		/** The private key Id returned in the generate key pair methods [[generateSoftwareRsaKeyPair]] or [[generateTokenRsaKeyPair]]. */
		privateKeyId: string,
		/** The Base64 encoded hash to be signed. */
		hash: string,
		/** The digest algorithm identifier of the `hash` parameter. It can be the algorithm name or OID (i.e. `'SHA-256'` or `'2.16.840.1.101.3.4.2.1'`). */
		digestAlgorithm: string,
		/** The user crypto device returned from [[listTokens]], if the key pair was generated on a crypto device. */
		token?: TokenModel
	}): Promise<string>;

	/**********************************************************
	 * Signs data with a generated private key.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives the (Base64 encoded) signature bytes.
	 *
	 */
	keySignData(args: {
		/** The private key Id returned in the generate key pair methods [[generateSoftwareRsaKeyPair]] or [[generateTokenRsaKeyPair]]. */
		privateKeyId: string,
		/** The Base64 encoded data to be signed. */
		data: string,
		/** The digest algorithm identifier to be used in the signature algorithm. It can be the algorithm name or OID (i.e. `'SHA-256'` or `'2.16.840.1.101.3.4.2.1'`). */
		digestAlgorithm: string,
		/** The user crypto device returned from [[listTokens]], if the key pair was generated on a crypto device. */
		token?: TokenModel
	}): Promise<string>;

	/**************************************************************
	 * **OBSOLETE** Please use [[signHashes]]
	 */
	signHashBatch(args: {
		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		certificateThumbprint: string,
		/** The Array of Base64 encoded hashes to be signed. */
		batch: string[],
		/** The digest algorithm identifier of the hashes on `batch` parameter. It can be the algorithm name or OID (i.e. `'SHA-256'` or `'2.16.840.1.101.3.4.2.1'`). */
		digestAlgorithm: string,
		/** Set to be able to call [[preauthorizeSignatures]] in order to call [[signHashBatch]] multiple times.*/
		usePreauthorizedSignatures?: boolean
	}): Promise<SignHashBatchResponse>;

	/**************************************************************
	 * Signs a batch of hashes with signer certificate private key.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives the (Base64 encoded) signature bytes array.
	 *
	 * Usage example (JavaScript)
	 * ```javascript
	 * var hashes = [
	 *     { algorithm: 'SHA-256', value: 'f4OxZX/x/FO5LcGBSKHWXfwtSx+j1ncoSt3SABJtkGk=' }, // Base64 encoded SHA-256 of 'Hello World!'
	 *     { algorithm: 'SHA-256', value: 'f4OxZX/x/FO5LcGBSKHWXfwtSx+j1ncoSt3SABJtkGk=' },
	 *     { algorithm: 'SHA-256', value: 'f4OxZX/x/FO5LcGBSKHWXfwtSx+j1ncoSt3SABJtkGk=' }
	 * ];
	 *
	 * pki.signHashes({
	 *     certificateThumbprint: $('#certificateSelect').val(),
	 *     hashes: hashes
	 * }).success(function (result) {
	 *     // Use signatures array
	 *     var signatures = result.signatures;
	 * });
	 * ```
	 *
	 * JSFiddle live example: [Sign Hashes](https://jsfiddle.net/LacunaSoftware/1car2yjz)
	 */
	 signHashes(args: {
		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		certificateThumbprint: string,
		/** The Array of [[Hash]] with the hash algorithm and value to be signed. */
		hashes: Hash[],
	}): Promise<SignHashesResponse>;

	/**************************************************************
	 * Executes a document signature with Rest PKI (server-side) integration. See [Rest PKI documentation](https://docs.lacunasoftware.com/articles/rest-pki/) for more informations.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives the current signature process `token`.
	 */
	signWithRestPki(args: {
		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		thumbprint: string,
		/** The token returned by Rest PKI signature start process. See [Rest PKI documentation](https://docs.lacunasoftware.com/articles/rest-pki/) for more informations. */
		token: string
	}): Promise<string>;

	/**************************************************************
	 * Pre authorizes a number of signatures. Useful for cases in which a significant number of signatures will be performed and the user wants to authorize and enter its PIN only once for the whole signature batch.
	 *
	 * @return A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes.
	 *
	 * Usage example (JavaScript)
	 * ```javascript
	 * var batch = [
	 *     'SGVsbG8gV29ybGQh',      // 'Hello World!'  Base64 encoded
	 *     'SGVsbG8gV2ViUEtJIQ==',  // 'Hello WebPKI!' Base64 encoded
	 *     'SGVsbG8gQmF0Y2gh',      // 'Hello Batch!'  Base64 encoded
	 *     'SGVMbE8gd09yTGQh',      // 'HeLlO wOrLd!'  Base64 encoded
	 *     'SGVsbG8gQ3J5cHRvIQ=='   // 'Hello Crypto!' Base64 encoded
	 * ];
	 *
	 * pki.preauthorizeSignatures({
	 *     certificateThumbprint: $('#certificateSelect').val(),
	 *     signatureCount: batch.length
	 * }).success(function () {
	 *     signBatchItem(0); // start batch signatures
	 * });
	 *
	 * function signBatchItem(i) {
	 *     if (i >= batch.length) {
	 *          console.log('Batch finished');
	 *          return;
	 *     }
	 *
	 *     pki.signData({
	 *         thumbprint: $('#certificateSelect').val(),
	 *         data: batch[i],
	 *         digestAlgorithm: 'SHA-256'
	 *
	 *     }).success(function (signature) {
	 *         console.log('Signature ' + i + ': ' + signature);
	 *         signBatchItem(++i); // signs next item of batch
	 *     });
	 * }
	 *```
	 *
	 * JSFiddle live example: [Sign Batch Example](https://jsfiddle.net/LacunaSoftware/xxnkoouc/)
	 */
	preauthorizeSignatures(args: {
		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		certificateThumbprint: string,
		/** The number of signatures to be pre authorized. */
		signatureCount: number
	}): Promise<void>;

	/**************************************************************
	 * Shows the OS directory browser. Used for commands which the user needs to choose a directory.
	 *
	 * IMPORTANT
	 *
	 * In order to comply to user privacy policies, user paths are **never** returned to the page. All paths are handled inside extension or addon logic and an `Id` is returned instead.
	 * Later, the developer can refeer to the selected directory by using the returned [[ShowFolderBrowserResponse.folderId]].
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[ShowFolderBrowserResponse]] object.
	 */
	showFolderBrowser(args?: {
		/** A message title for the browser dialog. */
		message?: string
	}): Promise<ShowFolderBrowserResponse>;

	/**************************************************************
	 * Shows the OS file browser. Used for commands which the user needs to choose a file.
	 *
	 * IMPORTANT
	 *
	 * In order to comply to user privacy policies, user paths are **never** returned to the page. All paths are handled inside extension or addon logic and an `Id` is returned instead.
	 * Later, the developer can refeer to the selected file by using the returned [[FileModel.id]].
	 * 
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[ShowFileBrowserResponse]] object.
	 */
	showFileBrowser(args?: {
		/** Whether the user can select multiple files or not. */
		multiselect?: boolean,

		/** Any file extension filter for the browser dialog. */
		filters?: FileFilterModel[],

		/** The file browser dialog title */
		dialogTitle?: string
	}): Promise<ShowFileBrowserResponse>;

	/**************************************************************
	 * Downloads a specific content to a selected directory.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[DownloadToFolderResponse]] object
	 */
	downloadToFolder(args: {
		/** The content URL */
		url: string,

		/** The selected [[ShowFolderBrowserResponse.folderId]], as returned by [[showFolderBrowser]] method. */
		folderId: string,

		/** The file name of the content to be saved. */
		filename?: string
	}): Promise<DownloadToFolderResponse>;

	/**********************************************************
	 * Opens the selected folder in OS directory explorer.
	 * 
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a *boolean* argument with the success result.
	 */
	openFolder(args: {
		/** The selected [[ShowFolderBrowserResponse.folderId]], as returned by [[showFolderBrowser]] method. */
		folderId: string
	}): Promise<boolean>;

	/**************************************************************
	 * Opens a file with the OS default registered program for the file type. If the file type is not in the Web PKI whitelist, the file directory will be opened instead.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a *boolean* argument with the success result.
	 */
	openFile(args: {
		/** The selected [[FileModel.id]], as returned by [[showFileBrowser]] method. */
		fileId: string
	}): Promise<boolean>;


	/**********************************************************
	 * Redirects the user to the install page, with the appropriate url arguments so as to make the user be redirected back to the original page once the
	 * installation completes successfully.
	 *
	 * For an example of the proper way to call this method, see the complete example code at [[init]] method documentation.
	 */
	redirectToInstallPage(): void;


	//-------------Web PKI local signature methods

	/**************************************************************
	 * Signs a PDF document.
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[PdfSignResult]] obejct.
	 * 
	 * **Live Examples**
	 *
	 * [InCode PDF Signature](https://jsfiddle.net/LacunaSoftware/Lxts3keh/): JSFiddle example with the to sign PDF passed from JavasSript and the signed PDF returned to JavasSript.
	 * 
	 * [Local PDF File Signature](https://jsfiddle.net/LacunaSoftware/8r63boLd/): JSFiddle example with local computer PDF file and signed PDF result saved in the same directory with suffix '-signed'.
	 */
	signPdf(args: {
		/** The selected PDF [[FileModel.id]], as returned by [[showFileBrowser]] method. */
		fileId?: string,

		/** A PDF content (Base64 encoded bytes) to sign can be passed optionally to `filedId`. */
		content?: string,

		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		certificateThumbprint: string,

		/** The signed PDF output options. */
		output: Output,

		/** The trust arbitrators for the signer certificate validation. Not required if the `policy` already has a default one. */
		trustArbitrators?: TrustArbitrator[],

		/** Whether or not to remove the `policy` default trust arbitrator. If `true`, you must pass the `trustArbitrators` argument. */
		clearPolicyTrustArbitrators?: boolean,

		/** The PDF visual representation for the signer. */
		visualRepresentation?: VisualRepresentation,

		/** The PDF page marks. */
		pdfMarks?: PdfMark[],

		/** If `true`, will not apply the `pdfMarks` in case PDF already has a signature. If `false`, any previous signature will be removed before the marks be applied. */
		bypassMarksIfSigned?: boolean,

		/** A signing reason */
		reason?: string,

		/** The signing location or address */
		location?: string,

		/** The signer name */
		signerName?: string,

		/** A custom signature field name. Signature field name must be unique for the PDF */
		customSignatureFieldName?: string,

		/** Any metadata to be added to the PDF */
		metadata?: { [key: string]: string; },

		/** The PDF signature policy. */
		policy: LacunaWebPKI.PadesPolicies,

		/** A timestamp requester for signature policies which require timestamping */
		timestampRequester?: TimestampRequester,

		/** An optional signer certificate validation level to execute. Default is a signer certificate full validation. */
		certificateValidationLevel?: LacunaWebPKI.CertificateValidationLevels
	}): Promise<PdfSignResult>;

	/**************************************************************
	 * Signs a document with CAdES standard, generates a P7S.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[CadesSignResult]] object.
	 * 
	 * **Live Examples**
	 *
	 * [InCode Content CAdES Signature](https://jsfiddle.net/LacunaSoftware/01gLv3es/): JSFiddle example with the to sign file content passed from JavasSript and the signed CAdES (P7S) result returned to JavasSript.
	 * 
	 * [Local File CAdES Signature](https://jsfiddle.net/LacunaSoftware/njcz048y/): JSFiddle example with local computer file and signed CAdES (P7S) saved in the same directory with suffix '-signed'.
	 */
	signCades(args: {
		/** The selected document [[FileModel.id]], as returned by [[showFileBrowser]] method. */
		fileId?: string,

		/** A content (Base64 encoded bytes) to sign can be passed optionally to `filedId`. */
		content?: string,

		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		certificateThumbprint: string,

		/** The CAdES signature file (.p7s) output options. */
		output: Output,

		/** The trust arbitrators for the signer certificate validation. Not required if the `policy` already has a default one. */
		trustArbitrators?: TrustArbitrator[],

		/** Whether or not to remove the `policy` default trust arbitrator. If `true`, you must pass the `trustArbitrators` argument. */
		clearPolicyTrustArbitrators?: boolean,

		/** If you already have a CAdES file and a co-signature is intended, pass this argument instead of `fileId` or `content`. Optionally, you can use the `fileId` for CAdES signature file and enable the `autoDetectCosign`. */
		cmsToCosignFileId?: string,

		/** If you already have a CAdES file and a co-signature is intended, pass this argument instead of `fileId` or `content`. Optionally, you can use the `fileId` for CAdES signature file and enable the `autoDetectCosign`. */
		cmsToCosignContent?: string,

		/** Whether or not to auto-detect a co-signature intention if the `fileId` passed is a CAdES signature file.  */
		autoDetectCosign?: boolean,

		/** Whether or not to include the encapsulated content (the original document) in the resulting CAdES signature file. */
		includeEncapsulatedContent?: boolean,

		/** A signing description or reason */
		signingDescription?: string,

		/** The CAdES signature policy. */
		policy: LacunaWebPKI.CadesPolicies,

		/** A timestamp requester for signature policies which require timestamping */
		timestampRequester?: TimestampRequester,

		/** An optional signer certificate validation level to execute. Default is a signer certificate full validation. */
		certificateValidationLevel?: LacunaWebPKI.CertificateValidationLevels
	}): Promise<CadesSignResult>;

	/**************************************************************
	 * Fully signs a XML.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[XmlSignResult]] object.
	 */
	signFullXml(args: {
		/** The selected XML [[FileModel.id]], as returned by [[showFileBrowser]] method. */
		fileId?: string,

		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		certificateThumbprint: string,

		/** The XML signature file output options. */
		output: Output,

		/** The trust arbitrators for the signer certificate validation. Not required if the `policy` already has a default one. */
		trustArbitrators?: TrustArbitrator[],

		/** Whether or not to remove the `policy` default trust arbitrator. If `true`, you must pass the `trustArbitrators` argument. */
		clearPolicyTrustArbitrators?: boolean,

		/** A XML content (UTF-8 string or Base64 encoded bytes) to sign can be passed optionally to `filedId`. */
		content?: string,

		/** A signing description or reason */
		signingDescription?: string,

		/** The XML signature policy. */
		policy: LacunaWebPKI.XmlPolicies,

		/** A timestamp requester parameters for signature policies which require timestamping */
		timestampRequester?: TimestampRequester,

		/** An optional signer certificate validation level to execute. Default is a signer certificate full validation. */
		certificateValidationLevel?: LacunaWebPKI.CertificateValidationLevels,

		/** The signature element Id. If not set, a random Id will be generated. */
		signatureElementId?: string,

		/** The signature element include location on the resulting XML. If not set, the default is [[LacunaWebPKI.XmlInsertionOptions.AppendChild]] relative to the root element. */
		signatureElementLocation?: XmlSignatureElementLocation,

		/** Any required namespace for xpath resolvings. */
		namespaces?: NamespaceModel[]
	}): Promise<XmlSignResult>;

	/**************************************************************
	 * Signs an element, or elements, of a XML.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[XmlSignResult]] object.
	 */
	signXmlElement(args: {
		/** The XML element to sign Id. */
		toSignElementId?: string,

		/** Optionally to a single `toSignElementId`, multiple elements to sign Ids on the same XML.  */
		toSignElementsIds?: string[],

		/** Optionally to a single `toSignElementId`, multiple elements to sign Ids on the same XML, selected by a xpath. Also check if any `namespace` argument for xpath resolution is needed.  */
		toSignElementsXPath?: string,

		/** An Id resolution table. Needed in case the `toSignElementId` Id attribute name is not the default. */
		idResolutionTable?: XmlIdResolutionTableModel

		/** The selected XML [[FileModel.id]], as returned by [[showFileBrowser]] method. */
		fileId?: string,

		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		certificateThumbprint: string,

		/** The XML signature file output options. */
		output: Output,

		/** The trust arbitrators for the signer certificate validation. Not required if the `policy` already has a default one. */
		trustArbitrators?: TrustArbitrator[],

		/** Whether or not to remove the `policy` default trust arbitrator. If `true`, you must pass the `trustArbitrators` argument. */
		clearPolicyTrustArbitrators?: boolean,

		/** A XML content (UTF-8 string or Base64 encoded) to sign can be passed optionally to `filedId`.  */
		content?: string,

		/** A signing description or reason */
		signingDescription?: string,

		/** The XML signature policy. */
		policy: LacunaWebPKI.XmlPolicies,

		/** A timestamp requester for signature policies which require timestamping */
		timestampRequester?: TimestampRequester,

		/** An optional signer certificate validation level to execute. Default is a signer certificate full validation. */
		certificateValidationLevel?: LacunaWebPKI.CertificateValidationLevels,

		/** The signature element Id. If not set, a random Id will be generated. */
		signatureElementId?: string,

		/** The signature element include location on the resulting XML. If not set, the default is [[LacunaWebPKI.XmlInsertionOptions.AppendSibling]] relative to the selected `toSignElement`. */
		signatureElementLocation?: XmlSignatureElementLocation,

		/** Any required namespace for xpath resolvings. */
		namespaces?: NamespaceModel[]
	}): Promise<XmlSignResult>;

	/**************************************************************
	 * Opens a PDF signature.
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[PadesSignatureModel]] obejct.
	 */
	openPades(args: {
		/** The signed PDF [[FileModel.id]], as returned by [[showFileBrowser]] method. */
		signatureFileId?: string,

		/** The signed PDF content (Base64 encoded bytes) to open. It can be passed optionally to `signatureFileId`. */
		signatureContent?: string,

		/** Whether or not to validate the PDF sinatures. */
		validate: boolean,

		/** An external trusted date reference for the signature validation. If not set, the current date time will be used. */
		dateReference?: Date,

		/** The trust arbitrators for the signer certificate validation. Not required if the `policy` already has a default one. Only applies if `validate` argument is `true`. */
		trustArbitrators?: TrustArbitrator[],

		/** Whether or not to remove the `policy` default trust arbitrator. If `true`, you must pass the `trustArbitrators` argument. Only applies if `validate` argument is `true`. */
		clearPolicyTrustArbitrators?: boolean,

		/** A PDF signature policy for the signature validation. Only applies if `validate` argument is `true`. */
		specificPolicy: LacunaWebPKI.PadesPolicies
	}): Promise<PadesSignatureModel>;

	/**************************************************************
	 * Opens a CAdES (.p7s) signature.
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives [[CadesSignatureModel]] object.
	 */
	openCades(args: {
		/** The signed document (.p7s) [[FileModel.id]], as returned by [[showFileBrowser]] method. */
		signatureFileId?: string,

		/** The signed PDF content (Base64 encoded bytes) to open. It can be passed optionally to `signatureFileId`. */
		signatureContent?: string,

		/** The original file. Only applies if the passed `signatureFileId` or `signatureContent` does not have the encapsulated content. */
		originalFileId?: string,
		
		/** The original file content (Base64 encoded bytes). Only applies if the passed `signatureFileId` or `signatureContent` does not have the encapsulated content. */
		originalContent?: string,

		/** Set to return the encapsulated content */
		returnEncapsulatedContent?: boolean,

		/** Whether or not to validate the CAdES sinatures. */
		validate: boolean,

		/** An external trusted date reference for the signature validation. If not set, the current date time will be used. */
		dateReference?: Date,

		/** The trust arbitrators for the signer certificate validation. Not required if the `policy` already has a default one. Only applies if `validate` argument is `true`. */
		trustArbitrators?: TrustArbitrator[],

		/** Whether or not to remove the `policy` default trust arbitrator. If `true`, you must pass the `trustArbitrators` argument. Only applies if `validate` argument is `true`. */
		clearPolicyTrustArbitrators?: boolean,

		/** A CAdES signature policy for the signature validation. Only applies if `validate` argument is `true`. */
		specificPolicy?: LacunaWebPKI.CadesPolicies,

		/** A collection of acceptables signature policies. The policies *must* be explicit policies (signed-attributes must have a signature policy Id). Se useful presets [[cadesAcceptablePolicies]]. Only applies if `validate` argument is `true`. */
		acceptablePolicies?: LacunaWebPKI.CadesPolicies[]
	}): Promise<CadesSignatureModel>;

	/**************************************************************
	 * Opens a XML signature.
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives [[XmlSignatureModel]] obejct.
	 */
	openXmlSignature(args: {
		/** The signed XML [[FileModel.id]], as returned by [[showFileBrowser]] method. */
		signatureFileId?: string,

		/** The signed XML content (UTF-8 string or Base64 encoded bytes) to open. It can be passed optionally to `signatureFileId`. */
		signatureContent?: string,

		/** Whether or not to validate the CAdES sinatures. */
		validate: boolean,

		/** An external trusted date reference for the signature validation. If not set, the current date time will be used. */
		dateReference?: Date,

		/** An Id resolution table. Needed in case the `toSignElementId` Id attribute name is not the default. */
		idResolutionTable?: XmlIdResolutionTableModel,

		/** The trust arbitrators for the signer certificate validation. Not required if the `policy` already has a default one. Only applies if `validate` argument is `true`. */
		trustArbitrators?: TrustArbitrator[],

		/** Whether or not to remove the `policy` default trust arbitrator. If `true`, you must pass the `trustArbitrators` argument. Only applies if `validate` argument is `true`. */
		clearPolicyTrustArbitrators?: boolean,

		/** A XML signature policy for the signature validation. Only applies if `validate` argument is `true`. */
		specificPolicy?: LacunaWebPKI.XmlPolicies,

		/** A collection of acceptables signature policies. The policies *must* be explicit policies (signed-attributes must have a signature policy Id). Se useful presets [[cadesAcceptablePolicies]]. Only applies if `validate` argument is `true`. */
		acceptablePolicies?: LacunaWebPKI.XmlPolicies[]
	}): Promise<XmlSignatureModel>;

	/**************************************************************
	 * Lists the user connected crypto devices
	 * 
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives an array of [[TokenModel]].
	 *
	 * Usage sample (JavaScript)
	 * ```javascript
	 * pki.listTokens({
	 *     pkcs11Modules: [pki.pkcs11Modules.safeSign, pki.pkcs11Modules.safeNet]
	 * }).success(function (tokens) {
	 *     // Use token list "tokens"
	 * });
	 * ```
	 *
	 * Lacuna Live Example: [List Tokens And Show Details Example](https://jsfiddle.net/LacunaSoftware/t6c5jw2L/)
	 */
	listTokens(args: {
		/** The PKCS#11 modules to use for crypto devices communication. See standard supported [[pkcs11Modules]] */
		pkcs11Modules?: Pkcs11Module[]
	}): Promise<TokenModel[]>;

	/**************************************************************
	 * Generates a RSA key pair in the user selected crypto device and returns a CSR (PKCS#10 Certificate Signing Request).
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[GenerateTokenKeyPairResponse]] object.
	 *
	 * Lacuna Live Example: [Issue Token Certificate Example](https://jsfiddle.net/LacunaSoftware/oq36n7ka/)
	 */
	generateTokenRsaKeyPair(args: {
		/** The selected token to generate the key pair. As returned by [[listTokens]] method. Passing this parameter removes the need of `pkcs11Modules` and `tokenSerialNumber` parameters */
		token?: TokenModel,
		/** The PKCS#11 modules to use for crypto devices communication. See standard supported [[pkcs11Modules]] */
		pkcs11Modules?: Pkcs11Module[],
		/** A subject name (DN) string for the generated CSR. E.g. `'CN=My Name, O=ACME Inc., C=BR'` */
		subjectName?: string,
		/** The selected token serial number, available in [[TokenModel.serialNumber]] as returned by [[listTokens]] method. */
		tokenSerialNumber?: string,
		/** A label for the generated keys objects in the token. If not set, a random Id is used. */
		keyLabel?: string,
		/** The RSA keys size to be genarated. Be sure that the selected device supports the requested key size on [[TokenModel.mechanisms]]. */
		keySize: number,
		/** Whether or not to auto enable the used PKCS#11 module after command success. The **default** is `true` */
		enableUsedPkcs11Module?: boolean

	}): Promise<GenerateTokenKeyPairResponse>;

	/**************************************************************
	 * Generates a RSA key pair in the user computer, or OS certificate store, and returns a CSR (PKCS#10 Certificate Signing Request).
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[GenerateKeyPairResponse]] object.
	 *
	 * Lacuna Live Example: [Issue Software Certificate Example](https://jsfiddle.net/LacunaSoftware/s9daqkr2/) 
	 */
	generateSoftwareRsaKeyPair(args: {
		/** A subject name (DN) string for the generated CSR. E.g. `'CN=My Name, O=ACME Inc., C=BR'` */
		subjectName?: string,
		/** The RSA keys size to be genarated. */
		keySize: number,
		/** Generates a non exportable key. Software generated non exportable keys are **only supported on Windows platform**. */
		nonExportableKey?: boolean
	}): Promise<GenerateKeyPairResponse>;

	/**************************************************************
	 * Imports a digital certificate into the user crypto device. The device must be the one holding the private key of the certificate being imported.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[ImportTokenCertificateResponse]] object.
	 *
	 * Lacuna Live Example: [Issue Token Certificate Example](https://jsfiddle.net/LacunaSoftware/oq36n7ka/)
	 */
	importTokenCertificate(args: {
		/** The generated private key Id returned on [[GenerateTokenKeyPairResponse.privateKeyId]] */
		privateKeyId?: string,
		/** The selected token to import the certificate to. As returned by [[listTokens]] method. Passing this parameter removes the need of `pkcs11Modules` and `tokenSerialNumber` parameters */
		token?: TokenModel,
		/** The PKCS#11 modules to use for crypto devices communication. See standard supported [[pkcs11Modules]] */
		pkcs11Modules?: Pkcs11Module[],
		/** The selected token serial number, available in [[TokenModel.serialNumber]] as returned by [[listTokens]] method. */
		tokenSerialNumber?: string,
		/** The digital certificate content (PEM or Base64 encoded DER bytes formats). */
		certificateContent: string,
		/** A label for the imported certificate object in the token. If not set, the same key Id is used. */
		certificateLabel?: string,
		/** Whether or not to auto enable the used PKCS#11 module after command success. The **default** is `true` */
		enableUsedPkcs11Module?: boolean
	}): Promise<ImportTokenCertificateResponse>;

	/**************************************************************
	 * Imports a digital certificate into the user computer, or OS certificate store. The computer must be the one holding the private key of the certificate being imported.
	 * The command can result with the certificate available for usage and also with a PFX (PKCS#12) backup copy, in this last case, see arguments `savePkcs12`, `passwordMinLength` and `passwordPolicies`.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[ImportSoftwareCertificateResponse]] object.
	 *
	 * Lacuna Live Example: [Issue Software Certificate Example](https://jsfiddle.net/LacunaSoftware/s9daqkr2/) 
	 */
	importCertificate(args: {
		/** The generated private key Id returned on [[GenerateKeyPairResponse.privateKeyId]] */
		privateKeyId?: string,
		/** The digital certificate content (PEM or Base64 encoded DER bytes formats). */
		certificateContent: string,
		/** A password secure level policy for the PFX file backup. Applies only if `savePkcs12` is `true`. */
		passwordPolicies?: LacunaWebPKI.PasswordPolicies,
		/** A password required minimum length for the PFX file backup. Applies only if `savePkcs12` is `true`. */
		passwordMinLength?: number
		/** Whether or not to also create a PFX (PKCS#12) file backup for the imported certificate and keys. */
		savePkcs12: boolean
	}): Promise<ImportSoftwareCertificateResponse>;

	/**************************************************************
	 * Sends an authenticated Web request (Web request with mutual SSL/TLS authentication).
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[HttpResponseModel]] object.
	 *
	 * **Live Example**
	 *
	 * [Authenticated Request Sample](https://jsfiddle.net/LacunaSoftware/3cv5xjov/): JSFiddle example with SOAP POST request to a staging invoice server.
	 */
	sendAuthenticatedRequest(args: {
		/** The signer certificate thumbprint. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		certificateThumbprint: string,

		/** The URL to send the request to or a relative route, if it is in the same domain. It must have a HTTPS scheme. */
		url: string,

		/** The request method. */
		method: LacunaWebPKI.HttpMethods,

		/** The request headers object-map. E.g.
		 * ```javascript
		 * {
		 *     "Content-Type": "application/json; charset=utf-8",
		 *     "Accept-Encoding": "gzip, deflate"
		 * }
		 * ```
		 */
		headers?: Object,
		
		/** A request body content. If set, consider also to pass the Content-Type charset of the body encoding in the `headers` map. If not header charset is present, the Web PKI will, by default, attempt to decode as a Base64 string and, if fails, will get the UTF-8 bytes. */
		body?: string,
		
		/** A request timeout in milliseconds. If not set, default is `60000` (1 min). */
		timeout?: number
	}): Promise<HttpResponseModel>;

	/**********************************************************
	 * Encrypts data with selected certificate public key or generated public key.
	 *
	 * @returns A promise object that can register [[fail]] and [[success]] callbacks to be called when the operation completes. The [[success]] callback for this promise receives a [[EncryptResponse]] object.
	 *
	 * **Live Example**
	 *
	 * [Encrypt Sample](https://jsfiddle.net/LacunaSoftware/mo3p4g7x/): JSFiddle example for encrypting text with a selected certificate public key.
	 */
	 encrypt(args: {
		/** A certificate thumbprint which public key will be used to encrypt data. Available in [[CertificateModel.thumbprint]] property returned by [[listCertificates]] method. */
		certifica