https://github.com/exodusmovement/secure-container
https://github.com/exodusmovement/secure-container
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/exodusmovement/secure-container
- Owner: ExodusMovement
- License: mit
- Created: 2016-05-26T19:01:25.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2024-01-26T17:19:27.000Z (over 2 years ago)
- Last Synced: 2024-04-14T13:10:04.247Z (about 2 years ago)
- Language: JavaScript
- Size: 51.8 KB
- Stars: 11
- Watchers: 31
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
secure-container
================
[](https://travis-ci.org/ExodusMovement/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.
```js
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
```js
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
```js
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
```js
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
```js
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`.
1. Byte-length of the `blob`, stored as `UInt32BE`.
1. 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.