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'
// OR
const seco = require('secure-container')

seco.encrypt()

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)

seco.decrypt()

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 * as header from 'secure-container/lib/header'
// OR
const header = require('secure-container/lib/header')

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 * as metadata from 'secure-container/lib/metadata'
// OR
const metadata = require('secure-container/lib/metadata')

metadata.create()

Create a metadata object. Returns an Object.

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.

metadata.decryptBlobKey(metadata, passphrase)

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

Returns blobKey as a buffer.

blob module

import * as blob from 'secure-container/lib/blob'
// OR
const blob = require('secure-container/lib/blob')

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.

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 * as file from 'secure-container/lib/file'
// OR
const file = require('secure-container/lib/file')

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.

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.