UnboundCot

UnboundCot

Unbound COT API for executing crypto operations using Unbound's secured distributed key storage.

Constructor

new UnboundCot()

Example
async function enroll() {
  var cot = unbound_cot;
  // verify connection to server
  try {
   await cot.healthCheck();
  } catch(e) {
    console.log(`COT unavailable ${e}`);
    return;
  }
  try {
    await cot.login("12345678!");
  } catch(e) {
    console.log(`login failed ${e}`);
    return;
  }

  var keyInfo = await cot.enrollKeyWithCertificate("app1", "User name",
                                                   "RSA", 2048);
  var certificateContent = keyInfo.certificate.dataDER;

  var objects = await cot.listObjects(); // we should now have one object

  objects.forEach(o => console.log(`${o.UID}, ${o.name}, ${o.objectType}`));
  var signature = await cot.sign(keyInfo.UID, "CKM_SHA256_RSA_PKCS", "data to sign");
  await cot.logout();
}

Methods

(async) changeKeyInfo(keyId, newName, newDescription)

Change key name and description

Parameters:
Name Type Description
keyId string

A text name for the key pair
newName string

The key new name
newDescription string

The key new description

(async) changePIN(currentPIN, newPIN) → {Promise}

Change CORE PIN

Parameters:
Name Type Description
currentPIN string

The current PIN
newPIN string

The new PIN. Must have a minimum of 4 characters.
Returns:
Type:
Promise

A promise which is resolved if changed successfully, or rejected on error.

(async) createCsr(keyUID, subject, mecahnism) → {Promise}

Creates a certificate signing request (CSR) for a CORE key

Parameters:
Name Type Description
keyUID string

The UID of the target key
subject string

The subject for the certificate. It should be in the format: "CN=John Doe, O=Company, OU=department, L=New york, C=US, ST=NY"
mecahnism string

The hash algorithm for the certificate. One of: 'SHA1', 'SHA256', 'SHA384', 'SHA512'
Returns:
Type:
Promise

A promise which is resolved with the CSR in PEM format or rejected with error

(async) deleteObject(uid) → {Object}

Delete object

Parameters:
Name Type Description
uid string

key UID
Returns:
Type:
Object

(async) detectBrowser() → {String}

Returns the name of the current browser. Throws exception if the current browser or OS is not suported.

Returns:
Type:
String

The name of the supported browser.

(async) enrollKeyWithCertificate(name, certificateSubjectName, signAlgo, keyAlgorithm, keySize) → {Promise.<SecuredObject>}

Create a key with self-signed certificate.

This method executes the following steps:

  1. Generate a key pair
  2. Generate a self-signed certificate for the key pair
  3. Store the generated certificate with the key

Note: The purpose of this method is mainly for test in order to avoid the more complex process of working with CSR and CA

Parameters:
Name Type Description
name string

A name for the key
certificateSubjectName string

The certificate subject name
signAlgo RSA_SIGN_MECHANISM
keyAlgorithm KEY_ALGORITHM

The key algorithm type
keySize number

The key size
Returns:
Type:
Promise.<SecuredObject>

A promise which resolves with the generated key object and its associated certificate object available from the certificate attribute

(async) exportCertificate(certUID)

Export a certificate to PEM

Parameters:
Name Type Description
certUID string

The UID of the certificate to export

(async) generateKeyPair(name, algorithm, size, ECCurveopt) → {Promise.<SecuredObject>}

Creates a new asymmetric key pair

Parameters:
Name Type Attributes Default Description
name string

A text name for the key pair
algorithm KEY_GEN_MECHANISM RSA

The key algorithm type
size number 2048

The size for the key in bits
ECCurve EC_CURVE_TYPE <optional>
 null

If algorithm is ECDSA, specifies the curve to use. Ignored if not applicable
Returns:
Type:
Promise.<SecuredObject>

A promise which resolves with the generated key info or rejected with error

Example
generateKeyPair('rsa1', "RSA", 2048)
     .then(key => {
       console.log(key.UID);
     })

getClientVersion(retryInterval, maxRetries) → {Promise}

Retrieves the CORE native client version. The following errors can be thrown:

  • CONNECT_TO_EXTENSION_FAILED - In case the Unbound CORE browser extension is not installed or the extension "Access to local file URLS" is disabled (in case the extension was manually installed not from the store)
  • CONNECT_TO_NATIVE_CLIENT_FAILED - In case the native host files are not installed correctly
Parameters:
Name Type Description
retryInterval number

The retry interval in milliseconds. Sometimes it takes a few milliseconds for the extension to load, so this function retries several times before returning a failure.
maxRetries number

The maximum number of retries to make
Returns:
Type:
Promise

A promise which is resolved if the extension is installed and connection to client is ok.

(async) getExtensionInstallUrl() → {String}

Returns the URL for installing the required Unbound extension according to the current browser. Throws an error if the current browser or OS is not supported.

Returns:
Type:
String

The url for installing Unbound CORE browser extension.

(async) healthCheck() → {Promise}

Performs a health check to verify CORE is operational and connected to the server

Returns:
Type:
Promise

A promise which is resolved if health is ok or rejected with reason if not healthy

(async) importCertificate(file) → {Promise.<SecuredObject>}

Import a certificate into CORE

Parameters:
Name Type Description
file File

A file with a certificate in PEM format
Returns:
Type:
Promise.<SecuredObject>

A promise resolved with the created certificate object or rejected with an error.

(async) initPartition(newPIN) → {Promise}

Reset CORE data and set a new PIN Warning - this removes all keys and certificates from the local key store.

Parameters:
Name Type Description
newPIN string

The new PIN. Must have a minimum of 4 characters.
Returns:
Type:
Promise

A promise which is resolved if changed successfully. or rejected on error.

(async) isGenerateKeyAvailable() → {boolean}

Check if the system is ready to generate a new key. Unbound CORE runs background processes that prepare the necessary objects to generate a new key. This method checks if the necessary objects are prepared. Calling the generateKeyPair method before system is prepared results in an error.

Returns:
Type:
boolean

True if generate is available, false otherwise

(async) listObjects() → {Promise.<Array.<SecuredObject>>}

List available keys and certificates

Returns:
Type:
Promise.<Array.<SecuredObject>>

A promise which resolves with the list of keys or rejected with error

(async) login(pin) → {Promise}

Authenticate and start a new user session with Unbound enclave to use secure operations such as generate key and sign

Parameters:
Name Type Description
pin string

The security PIN
Returns:
Type:
Promise

Resolved if login was successful or rejected with error

(async) logout() → {Promise}

Logout from any active CORE sessions

Returns:
Type:
Promise

A promise which resolves if logout successful or rejected on error

(async) sign(keyUID, mechanism, data) → {Promise.<Array.<byte>>}

Sign with a key

Parameters:
Name Type Description
keyUID string

The UID of the key to sign with
mechanism RSA_SIGN_MECHANISM | ECDSA_SIGN_MECHANISM

The sign mechanism to use. Must match the key type (Ex. CKM_SHA1_RSA_PKCS does not work with an ECDSA key)
data Array.<byte> | string

The data to sign. If string is provided, it is converted to bytes using UTF-8 encoder
Returns:
Type:
Promise.<Array.<byte>>

Resolves with signature bytes or rejected with error

Example
sign('ef4b9670468f31aa', 'CKM_ECDSA_SHA1', 'data to sign')

(async) signHash(keyUID, mechanism, data) → {Promise.<Array.<byte>>}

Sign with a key, Here hashing is done here instead of pkcs

Parameters:
Name Type Description
keyUID string

The UID of the key to sign with
mechanism RSA_SIGN_MECHANISM | ECDSA_SIGN_MECHANISM

The sign mechanism to use. Must match the key type (Ex. CKM_SHA1_RSA_PKCS does not work with an ECDSA key)
data Array.<byte> | string

The data to sign. If string is provided, it is converted to bytes using UTF-8 encoder
Returns:
Type:
Promise.<Array.<byte>>

Resolves with signature bytes or rejected with error

(async) signPkcs7(keyUID, hashAlgorithm, data, detached) → {Promise.<Array.<byte>>}

Sign PKCS7 with a key. The key must have a certificate.

Parameters:
Name Type Description
keyUID string

The UID of the key to sign with
hashAlgorithm HASH_ALGORITHM

The hash algorithm to use
data Array.<byte> | string

The data to sign. If string is provided, it is converted to bytes
detached boolean
Returns:
Type:
Promise.<Array.<byte>>

Resolves with signature bytes or rejected with error