Show:

LacunaWebPKI

Summary

This class is used to communicate with the Web PKI component. Although the component is different for each browser (in Chrome it consists of both an extension and an application installed on the user's machine, on Internet Explorer it is only an add-on), all interfacing with the component is done through this class regardless of the user's browser. The gory details of browser-dependant code are hidden by this class.

Notice: make sure you call the init method before you call other methods.

Constructor

LacunaWebPKI

Syntax

LacunaWebPKI

(
  • [license]
)

Summary

Parameters:

  • [license] String | Object optional

    The license for the component. May be a string or an object (see examples). In order for the component to work, you must set a valid purchased license that matches the URL of the site running the code. The exception is when running the code from localhost. In that case, no license is needed, so you can test the component as much as you want in development before deciding to license it.

Examples

// 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=="
});
// 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==');

Methods

getVersion

Syntax

getVersion

(
  • [args]
)
Promise

Summary

Retrieves the installed component's version.

Parameters:

  • [args] Object optional

    An object with the following options:

    • [success] Function optional

      A function to be called when the operation is completed successfully, receiving a string with the retrieved version.

    • [error] Function optional

      A function to be called if an error occurrs during the operation.

Returns:

Promise:

A promise object that can be used to register a callback to be called when the operation completes. The success callback for this promise receives a string with the retrieved version.

Examples

pki.getVersion().success(function (version) {
    // The success callback receives a string containing the installed component version
    log('Version: ' + version);
});

Live examples:

init

Syntax

init

(
  • args
)
Promise

Summary

Initializes the instance of the LacunaWebPKI object. This method must be called before calling any other methods.

Parameters:

  • args Object | String

    An object with the options below. Alternatively, a function, which is interpreted as the parameter args.ready.

    • ready Function

      A function to be called when the component is ready to be used. The function receives no arguments.

    • [notInstalled] Function optional

      A function to be called if the component's installation is not OK (component not installed, outdated or user is using an unsupported browser). Refer to examples below for the exact function signature. 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.

    • [defaultError] Function optional

      The default callback to be called when an error occurrs (please refer to examples below for the exact function signature).

    • [angularScope] Object optional

      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 https://coderwall.com/p/ngisma/safe-apply-in-angular-js.

    • [license] Object | String optional

      The license for the component, if not already set when instantiating the object.

Returns:

Promise:

A promise object that can be used to register a callback to be called when the operation completes. Specifically in the case of this method, it is recommended to pass callbacks on the function arguments (ready and notInstalled) rather than on the promise.

Examples

// 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(onWebPkiReady);

// The ready callback receives no arguments
function onWebPkiReady() {
    // start using the component
}
// If you wish to pass any other argument, you must use the extended version of the method:
pki.init({
    ready: onWebPkiReady,
    notInstalled: onWebPkiNotInstalled,
    defaultError: onWebPkiError,
    angularScope: $scope
});

function onWebPkiReady() {
    // start using the component
}

// The notInstalled callback receives two parameters:
// - status: A number indicating the reason for the failed verification, whose value is equal to one of the values of the
//           LacunaWebPKI.installationStates object (NOT_INSTALLED: 1, OUTDATED: 2, BROWSER_NOT_SUPPORTED: 3)
// - message: A user-friendly message describing the reason for the failure.
function onWebPkiNotInstalled(status, message) {
    alert(message + '\n\nYou will be redirected to the installation page');
    pki.redirectToInstallPage();
}

// The default error callback receives 3 arguments:
// - message: a user-friendly message describing the error that occurred
// - error: a detailed string containing as much information about the error as possible, for instance the stack trace. This is a good value to be logged, not to be shown to the user.
// - origin: a string denoting where the error originated. This should also not be shown to the user, but rather logged for diagnostic purposes.
function onWebPkiError(message, error, origin) {
    alert(message);
    if (window.console) {
        window.console.log('Web PKI error from ' + origin + ': ' + error);
    }
}

Live examples:

listCertificates

Syntax

listCertificates

(
  • [args]
)
Promise

Summary

Lists the available certificates.

Parameters:

  • [args] Object optional
    • [success] Function optional

      A function to be called when the operation is completed successfully, receiving an array with the retrieved certificates (please refer to examples for the properties in each item of the array).

    • [error] Function optional

      A function to be called if an error occurrs during the operation.

Returns:

Promise:

A promise object that can be used to register a callback to be called when the operation completes. The success callback for this promise receives an array with the retrieved certificates (please refer to examples for the properties in each item of the array).

Examples

pki.listCertificates().success(function (certs) {
    var select = $("#certificateSelect");
    $.each(certs, function() {
        // The certs parameter, passed to the success callback, is an array whose each element has the following properties:
        // - thumbprint (used to reference the certificate in the other methods such as readCertificate and signData)
        // - subjectName (the CommonName portion of the subject's name)
        // - issuerName (the CommonName portion of the issuer's name)
        select.append($("<option />").val(this.thumbprint).text(this.subjectName + ' (issued by ' + this.issuerName + ')'));
    });
});
pki.listCertificates({
    success: function (certs) {
        var select = $("#certificateSelect");
        $.each(certs, function() {
            select.append($("<option />").val(this.thumbprint).text(this.subjectName + ' (issued by ' + this.issuerName + ')'));
        });
    }
});

Live examples:

readCertificate

Syntax

readCertificate

(
  • args
)
Promise

Summary

Reads a certificate's binary encoding.

Most browser signature schemes that relay to the server-side code the responsibility of encoding the signature require that the signer certificate's binary encoding be read and sent back to the server for the generation of the "to-sign-bytes" or "signed attributes". This method enables your code to do that.

Parameters:

  • args Object | String

    An object with the options below. Alternatively, a string, which is interpreted as the parameter args.thumbprint.

    • thumbprint String

      The certificate's thumbprint, as yielded by the method listCertificates.

    • [success] Function optional

      A function to be called when the operation is completed successfully, receiving a string with the certificate's binary encoding in Base64

    • [error] Function optional

      A function to be called if an error occurrs during the operation.

Returns:

Promise:

A promise object that can be used to register a callback to be called when the operation completes. The success callback for this promise receives a string containing the certificate's binary encoding in Base64.

Examples

// Let's assume you're using jQuery and have populated the dropdown "certificateSelect" with the certificates returned
// by the listCertificates method, putting on the value attribute of each option the certificate's thumbprint.
var selectedCertThumbprint = $('#certificateSelect').val();
// We use the certificate's thumbprint as previously returned by the listCertificates method
// to read the certificate's encoding using the readCertificate method.
pki.readCertificate({
    thumbprint: selectedCertThumbprint,
}).success(function (certContent) {
    // The success callback receives a single argument containing the certificate's binary encoding in Base64
    alert('Certificate read: ' + certContent);
});
// Here, we'll use the shortcut version of the method, passing the certificate's thumbprint directly in the first argument of the method.
pki.readCertificate(selectedCertThumbprint).success(function (certContent) {
    alert('Certificate read: ' + certContent);
});

Live examples:

redirectToInstallPage

Syntax

redirectToInstallPage

()

Summary

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.

Live examples:

signData

Syntax

signData

(
  • args
)
Promise

Summary

Signs a collection of bytes with a certificate.

Parameters:

  • args Object

    An object with the following options:

    • thumbprint String

      The thumbprint of the certificate to be used, as yielded by the method listCertificates.

    • data String

      The bytes to be signed, encoded in Base64.

    • digestAlgorithm String

      The name or OID of the digest algorithm to be used to compute the hash of the bytes during the signature operation. Common values for this parameter are 'SHA-256' or 'SHA-1'. The forms 'SHA256', 'sha256', 'sha 256', 'sha-256' will also work.

    • [success] Function optional

      A function to be called when the operation is completed successfully, receiving a string with the signature algorithm's output encoded in Base64.

    • [error] Function optional

      A function to be called if an error occurrs during the operation.

Returns:

Promise:

A promise object that can be used to register a callback to be called when the operation completes The success callback for this promise receives a string with the signature algorithm's output encoded in Base64.

Examples

// Let's assume you're using jQuery and have populated the dropdown "certificateSelect" with the certificates returned
// by the listCertificates method, putting on the value attribute of each option the certificate's thumbprint. Let's
// also assume that you received from the server the data to be signed and the digest algorithm to be used.
var selectedCertThumbprint = $('#certificateSelect').val();
var dataToSign = '...'; // typically received from server
var digestAlgorithmOid = '...'; // typically received from server
pki.signData({
    thumbprint: selectedCertThumbprint,
    data: dataToSign,
    digestAlgorithm: digestAlgorithm
}).success(function (signature) {
    // The success callback receives a single argument containing the signature output, encoded in Base64
    alert('Signature: ' + signature);
});

Live examples:

signHash

Syntax

signHash

(
  • args
)
Promise

Summary

Signs a pre-computed digest value with a certificate.

Parameters:

  • args Object

    An object with the following options:

    • thumbprint String

      The thumbprint of the certificate to be used, as yielded by the method listCertificates.

    • hash String

      The pre-computed digest value to be signed, encoded in Base64.

    • digestAlgorithm String

      The name or OID of the digest algorithm used to compute the given digest value. Common values for this parameter are 'SHA-256' or 'SHA-1'. The forms 'SHA256', 'sha256', 'sha 256', 'sha-256' will also work.

    • [success] Function optional

      A function to be called when the operation is completed successfully, receiving a string with the signature algorithm's output encoded in Base64.

    • [error] Function optional

      A function to be called if an error occurrs during the operation.

Returns:

Promise:

A promise object that can be used to register a callback to be called when the operation completes The success callback for this promise receives a string with the signature algorithm's output encoded in Base64.

Examples

// Let's assume you're using jQuery and have populated the dropdown "certificateSelect" with the certificates returned
// by the listCertificates method, putting on the value attribute of each option the certificate's thumbprint. Let's
// also assume that you received from the server the digest to be signed and the digest algorithm used to compute
// the digest.
var selectedCertThumbprint = $('#certificateSelect').val();
var hashToSign = '...'; // typically received from server
var digestAlgorithm = '...'; // typically received from server
pki.signHash({
    thumbprint: selectedCertThumbprint,
    hash: hashToSign,
    digestAlgorithm: digestAlgorithm
}).success(function (signature) {
    // The success callback receives a single argument containing the signature output, encoded in Base64
    alert('Signature: ' + signature);
});

Live examples: