absio-secured-container

1.1.3 • Public • Published

Absio Secured Containers

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

Index

About

For deails about the technology, the quickstart (usage), support and the licensing please see the Absio Documenation Site.

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 Broker application to enforce. The permissions define how the Absio Broker 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 Broker 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 Broker 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 Broker application.
  • upload is true and modifyType is false. Calls to update() that include the type will be rejected by the Absio Broker 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 Broker 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 Broker 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 Broker 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 Broker application.

deleteContainer(id)

This revokes the authenticated user's access to the Absio Secured Container from the Absio Broker 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 Broker 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 Broker 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 Broker 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 Broker 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 Broker 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 Broker 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 Broker 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 Broker application.
apiKey String The API Key is required for using the Absio Broker 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 Broker 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 Broker 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 Broker 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 Broker 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 Broker 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 Broker application. If the key file is not cached locally in the Obfuscating File System, the passphrase is used to download it from the Absio Broker 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 Broker 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 Broker 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 Broker 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 Broker 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 Broker 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.

Keywords

none

install

npm i absio-secured-container

Downloadsweekly downloads

2

version

1.1.3

license

SEE LICENSE IN LICENSE.txt

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
  • avatar
Report a vulnerability