node package manager

absio-secured-container

Absio Secured Containers

Protect your application's sensitive data with Absio Secured Containers.

Index

Absio Technology

Absio offers a set of tools that developers can use to protect application data throughout its lifecycle, from creation to deletion, everywhere it exists, without having to manage keys, add hardware, increase latency or rely on a third-party service for access to data. Absio's cross-platform, Serverless Encryption technology automatically encrypts any type of data (bits, file or stream) generated or processed by an application prior to being stored or transmitted, each with its own unique key. Data content keys are uniquely encrypted for each user given access to the data, allowing user-specific access and permissions to be added or revoked at any time without needing to re-encrypt the data object. All key generation and management is performed automatically on the device running the application and not by a central key server. Encrypted data objects and content keys can be stored locally in an obfuscating file system to reduce network latency impacts and enable local content to be decrypted and encrypted while offline. Absio technology automatically obfuscates file names and types and randomizes the folder structure, enabling keys and content to be stored locally without putting data at risk.

In addition, developers can use Absio tools to associate classification, audit history, policy and other metadata from any source, enabling software applications to consume this information and 1) process and update metadata without providing access to, or decrypting content, and/or 2) restrict who, how, where, and for how long decrypted content can be used. For data sharing, Absio technology provides an automated public key infrastructure, and a portable (installable anywhere), zero-knowledge server application for authentication, content/key exchange, sync, and backup.

Components

The Absio developer toolset consists of cross platform-capable software development kits (SDKs), each with a simple application programming interface (API), and a portable server application (Absio API Server Application). The Absio SDK is currently available in JavaScript (Browser and Node.js) and C#. SDKs for Swift, Java and Python will be available late summer 2017. The Absio Server Application is written in Python and can be deployed by the organization via a Python package, RPM, VM or Docker container. All communication with the Absio Server Application is handled by the SDK methods, so no separate API calls are required.

Goals

Several goals were identified and met in the creation of Absio's developer toolset:

  • Simple API
  • Flexible architecture
  • Serverless Encryption - key generation and encryption at the application
  • Automatic key generation and management
  • Bound metadata - encrypted with content (See the header portion of an Absio Secured Container for more details)
  • Associated metadata - stored in database and related to content (See the type field under the Containers section for more details)
  • Offline access (See Obfuscating File System)
  • Strong, safe and verifiable encryption

Absio API Server Application

The Absio API Server Application is used for identity management in the Absio ecosystem through usage and distribution of public keys. Users are registered through the SDK and their public keys are stored on the Absio API Server Application, accessible to all other registered Users. Container access is stored on the Absio API Server Application.

The Absio API Server Application tracks and distributes container-related events when Absio Secured Containers are:

  • Accessed
  • Created
  • Deleted (access or content removed)
  • Updated

Users

A User is an entity with a set of private keys and an identifier. There are two main key types: those used for signature verification, and those used for derivation. The user's public keys are registered with the Absio API Server Application and are made available to other Absio users. These public keys allow for granting access to Absio Secured Containers and validating user actions. The identifier (User ID) is a GUID generated by the SDK.

Users are able to create Absio Secured Containers that are each uniquely encrypted. Optionally, a User can grant other Users access to an Absio Secured Container and add unique permissions or lifespan controls.

Absio Secured Containers

An Absio Secured Container (ASC) is the fundamental encrypted data structure in the Absio ecosystem. A Container's header and content are part of the encrypted data.

Header

The header is any information about the content that is private or sensitive (should be encrypted), or that needs to remain with the data wherever it goes. The header must be JSON serializable. The header can be independently decrypted without downloading and/or decrypting the content.

Content

The content is the data payload of the container. While there are no limitations on maximum size of a container, your performance and experience may vary depending on platform limitations.

Granting Access

Access to Absio Secured Containers can be shared with other Users registered with the Absio API Server Application. Granting access allows a user to define explicit Permissions for each user to view and modify aspects of the container, as well as define when access to the container will expire.

Unless Permissions are explicitly defined, the User creating or updating the Container will be given full permissions to the container without an expiration.

Permissions

The permissions define how the Absio API Server Application will respond to create, read, update and delete operations for a given Container. Therefore, the Absio SDK and API Server Application will be enabled or disabled from performing certain operations based on these permissions as well. For instance, if the container.download property is false for a User, and they request the Container with the Get method, the container returned to the user will not have the decrypted content or header since the Absio API Server Application will not return the content URL to the SDK.

Key File

An AES256 encrypted key file is created for each User, which contains the user's private keys (both signing and derivation) and password reset information. The user's password is used to encrypt the private keys.

A passphrase may also be provided allowing a key file to be synchronized between devices, as well as enabling secure password reset. By default, the user's key file is backed up on the Absio API Server Application, but may optionally be stored locally in the Obfuscating File System.

Obfuscating File System

If the application using the SDK supports file storage, then the SDK can be used for secure local storage. The local storage acts as a cache allowing for offline access of data, as well improved performance (no need to request the keys and content from the Absio API Server Application).

Local storage is performed in the Obfuscating File System (OFS). The OFS creates random, nonsensical paths within the root directory for all files. This serves to remove any identifiable attributes (file name and associated content), ruining the economics of an attempt to target specific files for brute-force decryption. Optionally, the content within the OFS can be segregated by User ID.

Encryption

A User's private keys are stored in an encrypted Key File. The key file is encrypted with AES256 using a key derived from the user's password.

Each Absio Secured Container has a unique set of secret keys.

  • HMAC-SHA256 digests are used for content validation to mitigate content tampering.
  • AES256 keys are used to individually encrypt the header and content.

These secret keys are uniquely encrypted for each user that can access the container. This encryption process uses Static-Ephemeral Diffie-Hellman Key Exchange (DHKE) based upon a user's public derivation key. This process ensures that the decryption of the container's secret keys can only be accomplished using the user's corresponding private key. Furthermore the container keys are signed with the creator's private signing keys to help mitigate Man-in-the-Middle attacks.

Getting Started

After Obtaining an API Key, reference the Quick Start section to begin adding Absio Secured Containers to your application.

Obtaining an API Key

The Absio SDK requires a valid API Key that must be passed into the initialize() method. Obtain an API Key by contacting us here or sending an email to sales@absio.com. An API key should be considered private and protected as such.

Asynchronous

Module Import Support

We use Rollup to produce unique CommonJS and ES6 bundles for node and browser. Our goal is to make using our SDK as easy as possible. Contact us if you experience any issues or have suggestions to improve this.

The module and jsnext:main fields of the package.json reference the CommonJS and ES6 specific bundles for Node.js. The browser field of the package.json maps to the corresponding browser bundles. The browser bundle contains all external dependencies needed for execution, whereas the Node.js version does not.

// ES6
import { register, create, initialize } from 'absio-secured-container';
// Node.js/CommonJS
var securedContainer = require('absio-secured-container');

If your project does not use a module bundling tool like Browserify or Rollup, then the dist/browser/index.min.js bundle can be imported directly in HTML and adds a window.securedContainer global.

<script src="node_modules/absio-secured-container/dist/browser/index.min.js"></script>

Quick Start

The userId, password, and passphrase used below are the credentials for two existing users. To simplify the example, the users are called Alice and Bob. Users can be created with the register() method. For more details, see the Users section above.

  1. Installation:

    npm install absio-secured-container
    
  2. Import as regular module and initialize:

    var securedContainer = require('absio-secured-container');
  3. Initialize the module:

    await securedContainer.initialize('your.absioApiServer.com', yourApiKey);
  4. Create accounts:

    const aliceUserId = await securedContainer.register('password', 'reminder', 'passphrase');
    const bobUserId = await securedContainer.register('password', 'reminder', 'passphrase');
  5. Log in with an account:

    await securedContainer.logIn(alicesId, alicesPassword, alicesPassphrase);
  6. Create and share an Absio Secured Container:

    const sensitiveData = new Buffer('Sensitive Data...000-00-0000...');
    const containerId = await securedContainer.create(sensitiveData, { access: [bobUserId] });
  7. Securely access this Absio Secured Container from another system:

    await securedContainer.logIn(bobUserId, 'password', 'passphrase');
     
    // Access the container with the Container ID returned from create() or a Container Event.
    const container = await securedContainer.get(containerId);

Usage

The following usage examples require that the general setup in Getting Started has been completed.

Container Providers

By default, Absio Secured Containers can come from one of two locations. The Obfuscating File System (if local storage is used) or the Absio API Server Application (if a connection exists and server storage is used). To help accommodate the different requirements that customers will have, three different Absio Secured Container providers were created to help manage user intent on Container source and destination location. Each of the providers are described below.

OFS Container Provider

Use this provider to create, read, update and delete Absio Secured Containers from local storage (Obfuscating File System). Using this provider, you cannot grant/modify access to other users in the system. All create, update and delete operations only affect the local storage for the authenticated user. There is no event system for local storage.

Server Container Provider

Use this provider to create, read, update and delete Absio Secured Containers from the Absio API Server Application. Using this provider, you can grant/modify access to other users in the system. All create, read, update and delete operations will be tracked by the Absio API Server Application for the relevant user. Use the event system on the Absio API Server Application to retrieve the events. See getLatestEvents([options]) for more detail on events. This is the default provider when you do not have local storage (browser).

NOTE: If the system running the SDK has local storage (not a browser), the SDK will still cache all public signing and derivation keys in the Obfuscating File System.

Server Cache OFS Container Provider

Use this provider for the best user experience. This provider acts similar to the Server Container Provider, but also uses the local storage (Obfuscating File System) as an Absio Secured Container cache to facilitate faster read times and allow for offline access. This is the default provider when you have local storage (not in a browser).

Container Create

All created Containers and associated keys are stored on the Absio API Server Application and cached locally (Obfuscating File System). If the Absio API Server Application cannot be reached, the whole transaction will be aborted.

Container Read

If available, containers will be pulled from the cache (local storage - Obfuscating File System). If not available, containers will be pulled from the Absio API Server Application. When a container is pulled from the Absio API Server Application, the container and associated keys will be stored in the Obfuscating File System.

Container Update

All updated containers and associated keys are stored on the Absio API Server Application and cached locally (Obfuscating File System). If the Absio API Server Application cannot be reached, the whole transaction will be aborted.

Container Delete

All deleted containers and associated keys are removed locally (Obfuscating File System) and on the Absio API Server Application. If the Absio API Server Application cannot be reached, the whole transaction will be aborted.

Changing Container Providers

By default, if you have access to local storage (not running in a browser), the Server Cache OFS Container Provider is used. Otherwise, the OFS Container Provider is used. Below is an example on how to change to the Server Container Provider.

securedContainer.setCurrentProvider(securedContainer.providers.serverContainerProvider);

Initialization

This is an example of initializing the module. You will need the URL of the Absio API Server Application and your API Key.

await securedContainer.initialize('your.absioApiServer.com', yourApiKey);

Registration

This is an example of creating a user. You will need the password, reminder and passphrase for the new user.

NOTE: This assumes an initialized module.

const newUserId = await securedContainer.register('password', 'reminder', 'passphrase');

Authentication

This is an example of authenticated a user.

NOTE: This assumes an existing account (account has already been registered).

await securedContainer.logIn(usersId, usersPassword, usersPassphrase);

Create

This is an example of creating an Absio Secured Container that contains sensitive data.

NOTE: This assumes an authenticated session.

const sensitiveData = new Buffer('Sensitive Data...000-00-0000...');
 
// Optional: Define a custom header that is bound to the content with encryption.
const containerHeader = {
    recordCount: 500,
    applicationEnforceableMetadata: {
        allowPrint: false,
        allowExport: false
    }
};
 
// Optional: Grant access to the Container with permissions and/or expiration.
const containerAccess = {
    'userId': {
        expiration: new Date(2022),
        permissions: {
            access: {
                view: true
            },
            container: {
                decrypt: true,
                download: true
            }
        }
    }
};
 
// Create the container
const containerId = await securedContainer.create(sensitiveData, {
    access: containerAccess,
    header: containerHeader
});

Get

This demonstrates the ways to get containers.

// Get the Container with a known ID
const container = await securedContainer.get(knownContainerId);
 
// The Absio API Server Application creates an event for when a Container is new, updated, deleted, or first accessed.
const latestEvents = await securedContainer.getLatestEvents();
 
// Events contain the corresponding Container ID for getting the related Container.
const eventContainerId = latestEvents[0].containerId;
const containerFromEvent = await securedContainer.get(eventContainerId);
 
// Optionally can be filtered to return only the latest events of a given Container type and/or event action.
const latestUpdatedOfType = await securedContainer.getLatestEvents({
    containerType: 'exampleType',
    eventAction: 'updated'
});

Update

The update() method can be used to update fields specified in the options. Only the fields specified will be updated. To clear a value, this must be explicitly set.

// Get the Container securely.
const container = await securedContainer.get(knownContainerId);
 
// Add access with full permissions and no expiration.
container.access['userIdForAddedPermission'] = {
    permissions: {
        access: {
            view: true,
            modify: true
        },
        container: {
            decrypt: true,
            download: true,
            viewType: true,
            modifyType: true,
            upload: true
        }
    }
};
 
// Update the Container.
await securedContainer.update(knownContainerId, {
    access: container.access,
    content: new Buffer('updated content'),
    header: {},
    type: 'redefinedContainerType'
});

This shows redefining only the type of an Absio Secured Container with known ID. The type is the only field of the Absio Secured Container that will be changed in this update call.

await securedContainer.update(knownContainerId, { type: 'redefinedContainerType' });

Delete

Permanently remove access to an Absio Secured Container for the authenticated user.

NOTE: This does not delete the content for all users with access. See the deleteContainer(id) method for more details.

await securedContainer.deleteContainer(knownContainerId);

Examples

Visit our Examples page on GitHub to find Node and Browser specific examples.

API

Information about the available functions of the Absio SDK (such as data requirements, error codes, etc) can be found below, followed by a list of the available functions organized by subject.

Data Requirements and Details

  • Dates
    • All dates returned from the API are ISO-8601 formatted.
    • All dates passed into the API should be ISO-8601 formatted.
  • Header
    • The header will be serialized with JSON.Stringify(). Thus, it is best represented as JSON.

Available Functions

Container

Containers are the method by which data is passed between users securely.

Crucial to utilizing a container is understanding 'access'. This specifies details such as with whom the container should be shared, what access and permissions are enabled, if the access should be revoked at a particular time, etc.

Containers have headers and content. Headers are intended to include metadata information. They could contain client-enforceable controls such as "is this recipient allowed to print"? or identifiers that help tie the content back to something your system understands. The only restriction is that the header must be JSON serializable.

The content is assumed to be a file body. However, it too could be more JSON, or XML, or any other type of data. The content is intended to be just that - the data.

Other metadata exists for containers that is not wrapped up and protected by encryption. This information includes the date the container was created, when it was modified, the 'type', and the length of the container.

Access Information Object

The Access Information Object is used by the create(), update() and get() methods to define a user's access to a container. The key is the user's ID, and the value contains the user's access for this container. The access consists of an optional expiration, the encrypted container key and the specific permissions.

The create() and update() methods allow access to be defined as a list of user IDs. When the access is defined in this manner, the permissions defined in the code block below will be the defaults for the users specified in the array.

In the get() method, access is part of the returned container object. In the getLatestEvents() method, access can be in the changes field. Access for these methods is always defined as the object shown below.

Unless a permission is explicitly defined, the user creating or updating the container will be given full permissions to the container without an expiration. This is true even if they are not included in the access list.

Attributes of an Access Information Object

The following table outlines the access attributes for a specific user for a specific container.

Attribute Type Default Value Description
'expiration' Date null This is date/time when a user's access will expire. If null, the access will not expire.

NOTE: this must be defined as an ISO formatted date and will also be returned as one.
'keyBlob' String null The base 64 encoded string of the encrypted key blob.
'permissions' Object null The specific permissions for this user/container. See the JSON example for the format of the permissions object and below for the permissions definitions.

Possible Permissions in an Access Information Object

The following table defines the possible permissions in an Access Information Object for a user who is granted access to a container. These permissions are rules for the Absio API Server Application to enforce. The permissions define how the Absio API Server Application will respond to create, read, update and delete operations for a given container. Therefore, the Absio SDK and API Server Application will be enabled or disabled from performing certain operations based on these permissions as well. For instance, if the container.download property is false for a user and they request the container with the get() method, the container returned to the user will not have the decrypted content or header since the Absio API Server Application will not return the content URL to the SDK.

NOTE: The user creating or updating the container will be given the "Creator's Default" below unless specified otherwise. This is true even if they are not included in the access list. All other users in the access list will be given the "Other User's Default" below unless specified otherwise. These defaults are used if the access list is an array of user ids.

Permission Creator's Default Other User's Default Description
access.view true true Permission to view the full access list containing all other user's IDs, expiration dates, and permissions. Set to false to prevent a user from seeing other users' access information for the container.
access.modify true false Permission to add, remove, or update all users' access to a container. Set to true to allow a user to modify access to the container.

NOTE: you should also set access.view to true if this is true. Otherwise, the user can modify the access list, but not include others who have access.
container.decrypt true true Permission to access the key blob required for this user to decrypt the container. Set to false to prevent a user from being able to decrypt the container's content and header.
container.download true true Permission to allow a user to download the encrypted container's data. Set to false to prevent a user from accessing the encrypted container data.
container.viewType true false Permission to view the container's type field. Set to true to allow a user to see the container's type field.
container.modifyType true false Permission to modify the container's type field. Set to true to allow a user to make changes to a container's type field (in events and container requests).
container.upload true false Permission to upload changes to the container's content and header. Set to true to allow a user to upload changes to the content and header of a container.

NOTE: If setting access.modify to true, access.view and access.modify should also be set to true. Otherwise this combination of permissions will be rejected by the Absio SDK and API Server Application.

Known Permission Error Cases

Below are some permissions states that may have adverse effects.

  • view is false and modify is true. The user can update the access list, but will not know the other user with current access. Thus, the update could potentially remove all access from the current access list (aside from the User performing the operation).
  • view is false and upload is true and modify is true. The user can update the access list and content, but will not know the other users with current access. Thus, the update could potentially remove all access from the current access list (aside from the user performing the operation).
  • view is true and upload is true and modify is false. This operation will be rejected by the Absio API Server Application. Since uploading content requires re-keying the data, all access must be updated (each user with access will get a new keyBlob). Since they cannot modify access, it will be rejected.
  • upload is false. Calls to update() will be rejected by the Absio API Server Application.
  • upload is true and modifyType is false. Calls to update() that include the type will be rejected by the Absio API Server Application.
  • download is false or decrypt is false. If the data is not cached locally in the Obfuscating File System, calls to get() will return a container with content and header null.

JSON Example of Access for a User

{
    'userIdGrantedAccess': {
        expiration: null, // This will never expire. Define a Date for this access to expire.
        permissions: {
            access: {
                view: true,
                modify: false,
            },
            container: {
                decrypt: true,
                download: true,
                viewType: true,
                modifyType: false,
                upload: false
            }
        }
    }
}

Container Object

The Container consists of the Access Information Object, the content, the header and additional metadata. The attributes of a Container are defined below, as well as an example of the JSON representation. This object is returned from the get() method.

Attributes of a Container

Attribute Type Default Value Description
'access' Object null Details about with whom the container is shared and what permissions they have. This is in the form of dictionary of User ID to the Access Information Object.

NOTE: If a user did not create the container and/or does not have access.view permission, they will only see the access for their user ID.
'content' Buffer null The decrypted content (payload) portion of the Absio Secured Container.

NOTE: If this is null, the content was not included/decrypted or the authenticated user does not have the container.download and/or container.decrypt permission.
'created' Date null ISO formatted date/time when a container was created.

NOTE: This field will be null if the authenticated user does not have the container.download permission.
'header' string/JSON null The decrypted header (metadata) portion of the Absio Secured Container. The header is JSON.

NOTE: If this is null, the content was not included/decrypted or the authenticated User does not have the container.download and/or container.decrypt permission.
'id' String null The ID of the container.
'modifiedAt' Date null ISO formatted date/time when a container was last modified. If the container has never been modified, this will be null.

NOTE: This field will be null if the authenticated user does not have the container.download permission.
'modifiedBy' String/GUID null The user Id who last modified the container. If the container has never been modified this will be null.

NOTE: This field will be null if the authenticated user does not have access.view permission.
'createdBy' String/GUID null The user Id for the user who created this container.

NOTE: This field will be null if the authenticated user does not have the access.view permission.
'length' integer null The length in bytes of the encrypted Absio Secured Container.

NOTE: This field will be null if the authenticated user does not have the container.download permission.
'type' String null An optional clear bit of metadata that can be used to describe what type of data has been wrapped up into the container. This can be used to organize containers on the Absio API Server Application.

NOTE: This field will be null if the authenticated user does not have the container.download permission.

JSON Example of a Container

{
    access: {
        userIdWithAccess: {
            expiration: 'ISO formatted date string',
            keyBlob: 'Base64EncodedStringOfEncryptedKeyBlob'
            permissions: {
                access: {
                    view: true,
                    modify: false,
                },
                container: {
                    decrypt: true,
                    download: true,
                    viewType: true,
                    modifyType: false,
                    upload: false
                }
            }
        },
        ...
    },
    content: Buffer(),
    created: Date(),
    header: {},
    id: 'container ID',
    modifiedAt: Date(),
    modifiedBy: 'user ID that modified',
    createdBy: 'user ID of creator',
    length: 12345,
    type: 'container type'
}

Container Event Object

The Absio API Server Application tracks all container actions (accessed, added, updated and deleted) related to Absio Secured Containers. Calls to the getLatestEvents() return a list of container event objects. The attributes of these objects are defined below, along with some sample JSON.

Container Event Object Attributes

Attribute Type Default Value Description
'action' String not null Always one of accessed, added, deleted, or updated.
'changes' Dictionary null Information about what has changed. For example { fieldThatChanged updatedValue }
'clientAppName' String null The name of the application responsible for the action, optionally specified in the initialize() method.
'containerExpiredAt' Date null ISO-formatted container expiration date if the container has expired.
'containerId' String/GUID not null The container ID that this event relates to, if type is container.
'containerModifiedAt' Date null ISO formatted date string corresponding to when the container content property was last modified. It does not change when updating access, header or type (it will be null).
'containerType' String null The container type as specified upon creation or last update.
'date' Date not null ISO formatted date string corresponding to when the event occurred.
'eventId' int not null An integer ID value for the event.
'relatedUserId' String/GUID not null If this event relates to another user, this field will be set to that user's ID.
'type' String not null The event type, always one of container or keysFile.

Container Event Object Example JSON

{
    action: 'updated',
    changes: { 
        fieldThatChanged: 'updatedValue',
        ...
    },
    clientAppName: 'My App Name',
    containerId: '4cc66990-e4e1-4e06-8f4c-0aeb15d1f712',
    containerModifiedAt: '2017-06-13T22:10:23.859Z',
    containerType: 'The Changed Type',
    date: '2017-06-14T22:10:23.859Z',
    eventId: '5005',
    relatedUserId: '910084d7-b5b4-477e-880d-f8f8adf79160',
    type: 'container',
}

create(content[, options]) -> 'containerId'

Creates an Absio Secured Container with the provided content. The container will be uploaded to the Absio API Server Application and access will be granted to the specified users. If local storage is being utilized, the Absio Secured Container and associated access will also be stored in the Obfuscating File System.

The Container will never expire for the creator. The creator is automatically granted full permission to the container, unless a limited permission is defined in access for the creator.

Returns a Promise that resolves to the new container's ID.

Throws an Error if the connection is unavailable or an access user Id is not found.

Parameter Type Description
content Buffer Node.js Buffer for the data to be stored in the Absio Secured Container.
options Object [optional] See table below.
Option Type Default Description
access Array of user IDs (String) or Access Information for setting permissions and expiration {} Access will be granted to the users in this array with any specified permissions or expiration.
header Object {} This will be serialized with JSON.Stringify(), independently encrypted, and can be retrieved prior to downloading and decrypting the full content. Thus, it is optimal to pass in JSON. Use this to store any data related to the content.
type String null A string used to categorize the Absio Secured Container on the Absio API Server Application.

deleteContainer(id)

This revokes the authenticated user's access to the Absio Secured Container from the Absio API Server Application. If local storage is being utilized, the Absio Secured Container and associated access will also be removed from the Obfuscating File System. If the authenticated user is the only user with access, then the content will be deleted from the Absio API Server Application as well.

NOTE: If you want the content to be deleted, you must first remove all other users' access and then call delete. This will result in no users having access and the content being removed locally and on the Absio API Server Application.

Returns a Promise.

Throws an Error if the ID is not found or a connection is unavailable.

Parameter Type Description
id String The ID of the container to delete.

get(id[, options]) -> container

Gets the Absio Secured Container and decrypts it for use. If local storage is being utilized, the SDK will first check the Obfuscating File System. If not using local storage or the Absio Secured Container is not found, the latest version is downloaded from the Absio API Server Application. By default, the content is included (downloaded and decrypted). See the options below for overriding this behavior.

Returns a Promise that resolves to a container.

Throws an Error if the container or connection is unavailable.

Parameter Type Description
id String The ID of the container to get.
options Object [optional] See table below.
Option Type Default Description
includeContent boolean true Set to false to prevent downloading and decrypting content. This is helpful when the content is very large.

getMetadata(id) -> container

Gets the Absio Secured Container metadata (no content or header).

Returns a Promise that resolves to a container.

Throws an Error if the container or connection is unavailable.

Parameter Type Description
id String The ID of the container to get.

getLatestEvents([options]) -> { Container Event }

Gets all new container events since the last call of this method, unless specified with startingEventId in options. Options can be used to change the criteria for the container events returned by this method. The events are retrieved from the Absio API Server Application.

Returns a Promise that resolves to an array of container events.

Throws an Error if the connection is unavailable.

Parameter Type Description
options Object [optional] See table below.
Option Type Default Description
containerType String undefined Only events of the specified container type will be returned. Type is a string used to categorize containers on the Absio API Server Application.
containerId String undefined Filters the results to only include events related to the specified container ID.
eventAction String 'all' All container actions are included in the results by default. Possible values are: 'all', 'accessed', 'added', 'deleted', or 'updated'.
startingEventId Number -1 0 will start from the beginning and download all events for the current user with the specified criteria. Use the eventId field of the Container event to start from a known event. -1 will download all new since last call.

update(id[, options])

Updates the Absio Secured Container with the specified ID. At least one optional parameter must be provided for an update to occur. This will update the Absio Secured Container and access on the Absio API Server Application and in the Obfuscating File System if local storage is being utilized.

Returns a Promise.

Throws an Error if the connection is unavailable or an ID is not found.

Parameter Type Description
id String The ID of the container to update.
options Object [optional] See table below.
Option Type Default Description
access Array of user IDs (String) or accessInformation for setting permissions and expiration undefined The access granted to the container on upload. If not specified, the currently defined access will be left unchanged.
content Buffer undefined The content to update.
header Object undefined This will be serialized with JSON.stringify(), independently encrypted, and can be retrieved prior to downloading and decrypting the full content. Thus, it is optimal to pass in JSON. Use this to store any data related to the content.
type String undefined A string used to categorize the container on the Absio API Server Application.

setCurrentProvider(storageProvider)

Sets the current Container Provider to the specified one. This is used to instruct the SDK where to get containers from, as well as where to store them.

Parameter Type Description
storageProvider module The provider to use for all container storage.

General

hash(stringToHash) -> 'hashedString'

Produces a sha256 hash of the specified String.

Returns a String with the hashed value.

Parameter Type Description
stringToHash String The string used for producing the hash.

initialize(serverUrl, apiKey[, options])

This method must be called first to initialize the module. See the Obtaining an API Key section for more information about the API Key parameter.

Returns a Promise.

Parameter Type Description
serverUrl String The URL of the Absio API Server Application.
apiKey String The API Key is required for using the Absio API Server Application. See the Obtaining an API Key section for more information about the API Key parameter.
options Object [optional] See table below.
Option Type Default Description
applicationName String '' Name used by the Absio API Server Application to identify different applications.
passphraseValidator Function By default, the passphrase must be at least 8 characters long and include at least 1 character from 3 of the following types of characters: uppercase, lowercase, number and special. A Function that takes a String passphrase parameter and returns a Boolean value indicating whether the passphrase is valid.
passwordValidator Function By default, the password must be at least 8 characters long and include at least 1 character from 3 of the following types of characters: uppercase, lowercase, number and special. A Function that takes a String password parameter and returns a Boolean value indicating whether the password is valid.
reminderValidator Function Absio does not enforce any complexity upon the reminder, therefore this implementation just returns true. A Function that takes a String reminder parameter and returns a Boolean value indicating whether the reminder is valid.
rootDirectory String './' By default the root directory for storing data will be the current directory. Only encrypted data is stored here.

User Accounts

changeBackupCredentials(currentPassphrase, currentPassword, newReminder, newPassphrase)

Change the backup credentials for the account. Use a secure value for the passphrase as it can be used to reset the user's password. This operation causes the key file to be re-encrypted. The new copy of the key file will be pushed to the Absio API Server Application. If local storage is being utilized, it will also be saved in the Obfuscating File System.

Returns a Promise.

Throws an Error if the currentPassphrase or currentPassword is incorrect.

Parameter Type Description
currentPassphrase String The currentPassphrase set up during registration of the account.
currentPassword String The current password for the user.
newReminder String The new backup reminder for the user's passphrase. The reminder is publicly available in plain text. Do not include sensitive information or wording that allows the passphrase to be easily compromised.
newPassphrase String The new backup passphrase for the user. Use a secure value for this. This can be used to reset the password for the user's account.

changePassword(currentPassphrase, currentPassword, newPassword)

Change the password for the current user. The current passphrase is required for updating the backup. This operation causes the key file to be re-encrypted. The new copy of the key file will be pushed to the Absio API Server Application. If local storage is being utilized, it will also be saved in the Obfuscating File System.

Returns a Promise.

Throws an Error if the currentPassphrase or currentPassword is incorrect.

Parameter Type Description
currentPassphrase String The currentPassphrase is set up during registration of the account. This is used to reset the password.
currentPassword String The current password for the user.
newPassword String The new password for the user.

deleteUser()

Important: All data for the current user will be deleted from the Absio API Server Application and from the Obfuscating File System if local storage is used in any way. This user will be permanently deleted. Take caution using this method as there is no recovery mechanism.

Returns a Promise.

Throws an exception if the connection is unavailable.


getBackupReminder(userId) -> 'Reminder for the backup passphrase'

Gets the publicly accessible reminder for the user's backup passphrase. If no ID is provided, the user ID for the currently authenticated user will be used. This operation causes the key file to be re-encrypted. The new copy of the key file will be pushed to the Absio API Server Application. If local storage is being utilized, it will also be saved in the Obfuscating File System.

Returns a Promise that resolves to the user's reminder.

Throws an exception if the connection is unavailable.

Parameter Type Description
userId String A string ID representing the user.

logIn(userId, password, passphrase[, options])

Decrypts the key file containing the user's private keys with the provided password. If the decryption succeeds, then a private key will be used to authenticate with the Absio API Server Application. If the key file is not cached locally in the Obfuscating File System, the passphrase is used to download it from the Absio API Server Application. If local storage is being used, the downloaded key file will be stored in the Obfuscating File System.

Returns a Promise.

Throws an Error if the password or passphrase are incorrect, the userId is not found, or a connection is unavailable. If the password is correct and a connection is unavailable, then calling logIn() again is not required. Authentication with the Absio API Server Application will be attempted again automatically on the next call that requires it.

Parameter Type Description
userId String The user ID value is returned at registration. Call register() to register a user.
password String The password used to decrypt the key file.
passphrase String The passphrase used to retrieve the key file from the Absio API Server Application.
Option Type Default Description
cacheLocal boolean false By default, the encrypted key file is not cached locally. Set to true to enable using the cache for offline access and greater efficiency. When set to true, the encrypted key file will be stored and accessed using the local file system in Node.js and using HTML 5 Local Storage in the browser.

logOut()

Clears any user data cached in memory after awaiting any pending background operations. In a Node.js environment, this closes the database.

Returns a Promise.


register(password, reminder, passphrase) -> 'userId'

Important: The password and passphrase should be kept secret. Do not store them publicly in plain text. By default, the password and passphrase must be at least 8 characters, and include at least 1 uppercase letter, 1 lowercase letter, and 1 number. To override this behavior or to add a reminder validation, see the optional validator parameters of the initialize() method.

Generates private keys and registers a new user on the Absio API Server Application. The user's private keys are encrypted with the password to produce a key file. The passphrase is used to reset the password and download the key file from the Absio API Server Application. If local storage is utilized, the Key File is also saved in the Obfuscating File System.

Returns a Promise that resolves to the new user's) ID.

Throws an Error if the connection is unavailable.

Parameter Type Description
password String The password used to encrypt the key file.
reminder String The reminder should only be used as a hint to remember the passphrase. This String is stored in plain text and should not contain sensitive information.
passphrase String The passphrase can be used later to reset the password or to allow logging in from another system.

resetPassword(userId, passphrase, newPassword)

Use this method to reset a user's password. Call getBackupReminder(userId) to get the reminder for the passphrase. This operation causes the key file to be re-encrypted. The new copy of the key file will be pushed to the Absio API Server Application. If local storage is being utilized, it will also be saved in the Obfuscating File System.

Returns a Promise.

Throws an Error if the passphrase is incorrect or user ID is not found. If the key file is not cached locally (Obfuscating File System), then an error will be thrown if the connection is unavailable.

Parameter Type Description
userId String A String ID representing the user.
passphrase String The passphrase is set up during registration of the account. This is used to reset the password.
newPassword String The new password for the user.

Support and Bug Reporting

Please contact us if you experience any issues using this module. Use the project's Github issue tracker to report all issues.

License Agreement

See the LICENSE.txt file of the module.