secure-container

Install

npm i --save secure-container

API

Main Module

This is the main module most users should use; other modules are for advanced users only.

import * as seco from 'secure-container'

async seco.encrypt(data, options)

• data (String | Buffer) Data to encrypt
• options (Object)
  • header (Object)
    • appName (String) Name of your app
    • appVersion (String) Version of your app
  • passphrase (String | Buffer) Passphrase used to encrypt the data
  • metadata (Object)
  • blobKey (Buffer)

Note: Must set either passphrase or metadata & blobKey.

Returns an Object that contains:

• encryptedData (Buffer) The encrypted data
• blobKey (Buffer)
• metadata (Object)

async seco.decrypt(encryptedData, passphrase)

• encryptedData (Buffer) Data to decrypt
• passphrase (String | Buffer) Passphrase to decrypt the data

Returns an Object that contains:

• data (Buffer) The file data
• header (Object) The header for the secure-container
• blobKey (Buffer)
• metadata (Object)

header module

import { header } from 'secure-container'

header.create(data)

Create a header object.

• data (Object)
  • appName (String) Name of your app
  • appVersion (String) Version of your app

Returns an Object.

header.serialize(headerObj)

Serialize a header object. headerObj is a header object made with create(). Returns a Buffer.

header.decode(buffer)

Decodes a header buffer and returns the Object.

metadata module

import { metadata } from 'secure-container'

metadata.create()

Create a metadata object. Returns an Object.

async metadata.encryptBlobKey(metadata, passphrase, blobKey)

• metadata (Object) Metadata created with metadata.create().
• passphrase (String | Buffer)
• blobKey (Buffer)

Mutates metadata object; returns undefined.

metadata.serialize(metadata)

Serialize a metadata object. Returns a Buffer.

metadata.decode(buffer)

Takes a metadata buffer, decodes it, and returns an object.

async metadata.decryptBlobKey(metadata, passphrase)

• metadata (Object) Metadata with an encrypted blobKey.
• passphrase (String | Buffer)

Returns blobKey as a buffer.

blob module

import { blob } from 'secure-container'

async blob.encrypt(data, metadata, blobKey)

• data (Buffer) Data or message to encrypt.
• metadata (Object) Metadata object.
• blobKey (Buffer)

Mutates metadata. Returns an object:

• blob (Buffer) Encrypted data.
• blobKey (Buffer) The blobKey you passed in.

async blob.decrypt(blob, metadata, blobKey)

• blob (Buffer) Encrypted data.
• metadata (Object) Metadata object.
• blobKey (Buffer)

Returns the decrypted data as a buffer.

file module

import { file } from 'secure-container'

async file.computeChecksum(metadata, blob)

• metadata (Buffer) Metadata as a Buffer
• blob (Buffer) Encrypted blob

Returns a sha256 checksum as a buffer.

file.encode(fileObj)

• fileObj (Object)
  • header (Buffer) Serialized header
  • checksum (Buffer) Checksum from file.computeChecksum()
  • metadata (Buffer) Metadata as a Buffer
  • blob (Buffer) Encrypted blob

Returns a buffer.

file.decode(fileBuffer)

The opposite of file.encode(). Takes a buffer and returns an object.

async file.checkContents(fileBuffer)

Performs .decode() and checks that the checksum matches.

Return a boolean, true if checksum matched, false if not.

File Format Description

This is the documentation for the binary structure of secure containers.

For clarity, we have split the documentation into four sections: header, checksum, metadata, and blob.

Header

Size	Label	Description
4	magic	The magic header indicating the file type. Always SECO.
4	version	File format version. Currently 0, stored as UInt32BE.
4	reserved	Reserved for future use.
1	versionTagLength	Length of versionTag as UInt8.
versionTagLength	versionTag	Should be 'seco-v0-scrypt-aes'.
1	appNameLength	Length of appName as UInt8.
appNameLength	appName	Name of the application writing the file.
1	appVersionLength	Length of appVersion as UInt8.
appVersionLength	appVersion	Version of the application writing the file.

Checksum

32-byte sha256 checksum of the following data:

1. The metadata.
2. Byte-length of the blob, stored as UInt32BE.
3. The blob.

Metadata

Size	Label	Description
32	salt	Scrypt salt.
4	n	Scrypt n parameter.
4	r	Scrypt r parameter.
4	p	Scrypt p parameter.
32	cipher	Currently aes-256-gcm stored as a zero-terminated C-string.
12	iv	blobKey's iv.
16	authTag	blobKey's authTag.
32	key	blobKey's key.
12	iv	The blob's iv.
16	authTag	The blob's authTag.

Blob

Size	Label	Description
4	blobLength	Length of blob as UInt32BE.
blobLength	blob	Encrypted data.