enceeper-jslib

Enceeper JS library

A reference library for building Javascript applications on top of the Enceeper service. Our cross-platform Enceeper app is using this library.

Introduction

The Enceeper app and the Enceeper service are used to securely store and retrieve credentials (usernames, passwords, API keys etc). The Enceeper app is divided into two parts:

• The User Interface (UI) that handles all user input
• The core functionality and the utilization of the Enceeper service

For the latter, use this repository which serves as a basis project for easier integration (via npm) to other solutions.

Purpose of this library:

• To execute the SRP6a protocol both for user registration and authentication (https://github.com/alax/jsrp)
• Implement all cryptographic functionality, utilizing SJCL and TweetNaCl
• Handle all network communication with the Enceeper service using ajax calls (via JQuery)
• Expose a convenient and abstract API to enable integration with other solutions
• Allow transparent re-authentication when the auth token expires

Installation with npm

npm install enceeper-jslib --save

Important notes

The library assumes that the machine we are running is not hostile. If another hostile process can acquire a memory segment previously used by our app it could gain access to important key information. Given that JS allocates memory dymanically, even considering zeroing variables after usage could add unnecessary complexity without accomplishing its goal.

The safest way is to use the library in your personal machine.

Usage

The library is broken into the following files:

• enceeper.exceptions.js: contains the exceptions used throughout the library
• enceeper.network.js: handling the network communication with the Enceeper service
• enceeper.srp6a.js: the SRP6a protocol details for user registration and authentication
• enceeper.crypto.js: all the crypto related operations (keys, slots, key sharing etc.)
• enceeper.api.js: a low-level mapping of the Enceeper service API calls to Javascript functions
• enceeper.app.js: a high-level usage of the library with convenient methods and an internal data structure to access the keys

Only a small portion of the operations do not rely on network calls (i.e. logout or getCategories). Most operations will either perform a lengthy crypto calculation or communicate with the Enceeper service. This requires the use of callbacks in order to make the required operations asynchronous and report back the outcome. There are two types of callbacks available:

• a success callback that will provide the outcome of the request
• a failure callback providing the error code (most likely an HTTP status code) and an exception message

The following example illustrates how to sign-in to a user account and then retrieve various details about the stored keys.

const enceeper = require('enceeper-jslib')

// This user is used by our test suite
var enc = new enceeper.app('[e-mail]', 'ShareSecret')

enc.signin(function (data) {
  var categories, keys, password

  console.log('OK with data')

  categories = enc.getCategories()
  keys = enc.getKeys('Internet')
  // Get the password of the first key
  password = enc.getPassword(keys[0].key_id)

  // Since we store previous passwords we need to access the value of the first
  // element of the array. We should also check the version of the structure (password.v)
  // for completeness.
  console.log('The password: ' + password.p[0].v)
}, function (status, errorMessage) {
  console.log('Error: [' + status + '] [' + errorMessage + ']')
})

Copyright and license

Copyright 2019 Vassilis Poursalidis. Released under GNU GPL3 or later - see the LICENSE file for details.