@cryptolize/core NPM

Install

npm install @cryptolize/core --save

Usage

ES6 (Javascript Modules)

import * as CryptolizeCore from '@cryptolize/core'

const keys = CryptolizeCore.createAsymmetricKeys()

...

import { encryptRecordAsync } from '@cryptolize/core'

encryptRecordAsync(...).then((record) => console.log(record))

ES5 (CommonJS)

var CryptolizeCore = require('@cryptolize/core')

var keys = CryptolizeCore.createAsymmetricKeys()
CryptolizeCore.encryptRecordAsync(...).then((record) => console.log(record))

UMD (Browser)

var keys = CryptolizeCore.createAsymmetricKeys()
CryptolizeCore.encryptRecordAsync(...).then((record) => console.log(record))

Record Format

Record

Type: Object

Parameters

headerWrapper
headerWrapperEncryptionParams
blocks

Properties

headerWrapper HeaderWrapper
headerWrapperEncryptionParams HeaderWrapperEncryptionParams
blocks Array<Block> consists of the data and files keys only. the header is stored inside the encrypted headerWrapper.

Examples

const record = {
   headerWrapper: {
     metadata: {
       type: 'standard',
       id: 'id',
       creator: 'creator',
       personalPage: 'personalPage',
       signature: 'signature',
       signatureKeyVersion: 'signatureKeyVersion',
       timestamp: 1488992366155,
       timezoneOffset: 120,
       isOnce: false,
       expiration: 1488992300000,
       subject: 'subject',
       origin: 'origin',
       custom: {
         key1: value1,
         key2: value2,
         ...
       }
     },
     blocks: [
       {
         symmetricEncryption: [
           {
             hint: 'hint',
             derivationParams: {
               iterations: 'iterations',
               salt: 'salt'
             },
             encryptionParams: {
               iv: 'iv',
               mode: 'gcm',
               ts: 128,
               adata: 'cryptolize'
             },
             encryptedKey: 'encryptedKey'
           },
           ...
         ],
         asymmetricEncryption: [
           {
             id: 'id',
             version: 'version',
             tag: 'tag',
             encryptionParams: {
               iv: 'iv',
               mode: 'gcm',
               ts: 128,
               adata: 'cryptolize'
             },
             encryptedKey: 'encryptedKey'
           },
           ...
         ],
         dataEncryptionParams: {
           iv: 'iv',
           mode: 'gcm',
           ts: 128,
           adata: 'cryptolize'
         },
         filesEncryptionParams: [
           {
             id: 'id',
             encryptionParams: {
               iv: 'iv',
               mode: 'gcm',
               ts: 128,
               adata: 'cryptolize'
             }
           },
           ...
         ],
         filesStorageParams: [
           {
             id: 'id',
             path: 'path',
             service: 'service'
           },
           ...
         ]
       }
       ...
     ]
   },
   headerWrapperEncryptionParams: {
     id: 'id',
     tag: 'tag',
     encryptionParams: {
       iv: 'iv',
       mode: 'gcm',
       ts: 128,
       adata: 'cryptolize'
     },
   },
   blocks: [
     {
       data: {
         text: 'text',
         files: [
           {
             name: 'name',
             size: 'size',
             type: 'type',
             id: 'id'
           },
           ...
         ]
       },
       files: [
         {
           id: 'id',
           data: 'data'
         },
         ...
       ]
     },
     ...
   ]
 }

HeaderWrapper

Header wrapper

Type: Object

Parameters

metadata
blocks

Properties

metadata RecordMetadata
blocks Array<Header>

RecordMetadata

Type: Object

Parameters

id
creator
personalPage
signature
signatureKeyVersion
timestamp
timezoneOffset
isOnce
expiration
subject
origin
custom

Properties

type String
id String
creator String?
personalPage String?
signature Base64UrlString?
signatureKeyVersion String?
timestamp Number
timezoneOffset Number
isOnce Boolean
expiration Number?
subject String?
origin String?
custom Object?

HeaderWrapperEncryptionParams

Header wrapper encryption params

Type: Object

Parameters

id
tag
encryptionParams

Properties

keyId String
tag Base64UrlString
encryptionParams SymmetricEncryptionParams

Block

Type: Object

Parameters

header
data
files

Properties

header Header
data Data encrypted and represented by Base64UrlString
files Array<EncryptedFile>

Header

Type: Object

Parameters

symmetricEncryption
asymmetricEncryption
dataEncryptionParams
filesEncryptionParams
filesStorageParams

Properties

symmetricEncryption Array<SymmetricEncryptionWrapper>
asymmetricEncryption Array<AsymmetricEncryptionWrapper>
encryptionParams SymmetricEncryptionParams
filesEncryptionParams Array<FilesEncryptionParams>
filesStorageParams Array<FilesStorageParams>

SymmetricEncryptionWrapper

Symmetric encryption wrapper

Type: Object

Parameters

hint
derivationParams
encryptionParams
encryptedKey

Properties

hint String
derivationParams DerivationParams
encryptionParams SymmetricEncryptionParams
encryptedKey Base64UrlString

AsymmetricEncryptionWrapper

Asymmetric encryption wrapper

Type: Object

Parameters

id
version
tag
encryptionParams
encryptedKey

Properties

id String
version String
tag Base64UrlString
encryptionParams SymmetricEncryptionParams
encryptedKey Base64UrlString

FilesEncryptionParams

Files encryption params

Type: Object

Parameters

id
encryptionParams

Properties

id String
encryptionParams SymmetricEncryptionParams

FilesStorageParams

Files storage params

Type: Object

Parameters

id
path
service

Properties

id String
path String
service String

Data

Type: Object

Parameters

text
files

Properties

text String
files Array<FileMetadata>

FileMetadata

File metadata

Type: Object

Parameters

name
size
type
id

Properties

name String
size Number
type String
id String

EncryptedFile

Encrypted file

Type: Object

Parameters

id
path
service
data

Properties

id String
path String
service String
data ArrayBuffer

SymmetricEncryptionParams

Symmetric encryption params

Type: Object

Parameters

iv

Properties

iv Base64UrlString
mode String
ts Number
adata String

DerivationParams

Derivation params

Type: Object

Parameters

iterations
salt

Properties

iterations Number
salt Base64UrlString

API

Sync

deriveKey

Derives encryption key from simple text

Parameters

password String
$1 Object derivation params
- $1.salt Base64UrlString
- $1.iterations Number

Throws Error if a parameter is invalid

Returns Base64UrlString

createRandom

Create random string

Parameters

bits Number number of bits 64, 128, 256

Throws Error if a generator isn't seeded

Returns Base64UrlString

createKey

Create encryption key of size 256 bits

Throws Error if a generator isn't seeded

Returns Base64UrlString

createIV

Create initialization vector of size 128 bits

Throws Error if a generator isn't seeded

Returns Base64UrlString

createAsymmetricKeys

Create ECC (P-521 NIST curve) public and private keys

Parameters

privateKey ElGamalPrivateKey? create the keys from specific private key

Examples

const keys = CryptolizeCore.createAsymmetricKeys()
 console.log(keys.public)
 console.log(keys.private)

Throws Error if a parameter is invalid or generator isn't seeded

Returns {public: ElGamalPublicKey, private: PrivateKey}

createAsymmetricKeysECDSA

Create ECC (P-521 NIST curve) public and private keys for ECDSA

Parameters

privateKey ECDSAPrivateKey? create the keys from specific private key

Examples

const keys = CryptolizeCore.createAsymmetricKeysECDSA()
 console.log(keys.public)
 console.log(keys.private)

Throws Error if a parameter is invalid or generator isn't seeded

Returns {public: PublicKey, private: PrivateKey}

signWithECDSAPrivateKey

Sign text with ECDSA private key

Parameters

privateKey ECDSAPrivateKey the key to sign with
text String the text to sign

Examples

const keys = CryptolizeCore.createAsymmetricKeysECDSA()
 const signature = CryptolizeCore.signWithECDSAPrivateKey(keys.private, 'text to sign')

Returns Base64UrlString

verifyWithECDSAPublicKey

Verify text with ECDSA public key

Parameters

publicKey ECDSAPublicKey the key to verify with
text String the text to verify
signature Base64UrlString the signature to verify with

Examples

const keys = CryptolizeCore.createAsymmetricKeysECDSA()
 const signature = CryptolizeCore.signWithECDSAPrivateKey(keys.private, 'text to sign')
 const isOk = CryptolizeCore.verifyWithECDSAPublicKey(keys.public, 'text to sign', signature)

Returns Boolean

createRecordMetadata

Create record metadata

Parameters

id String
creator String?
personalPage String?
signature Base64UrlString?
signatureKeyVersion String?
timestamp Number
timezoneOffset Number
isOnce Boolean
expiration Number?
subject String?
origin String?
custom Object?

Returns RecordMetadata

createEncryptionParams

Create encryption params

Parameters

iv Base64UrlString

Returns SymmetricEncryptionParams

encryptText

Encrypt text

Parameters

data String
key Base64UrlString
encryptionParams Object
- encryptionParams.iv Base64UrlString initialization vector
- encryptionParams.mode String aes encryption mode 'ccm', 'gcm', 'ocb2'
- encryptionParams.ts Number tag size 64, 96, 128
- encryptionParams.adata String authenticated data to associate with the data

Throws Error if a parameter is invalid

Returns Base64UrlString the encrypted data

encryptObject

Encrypt object

Parameters

data Object
key Base64UrlString
encryptionParams Object
- encryptionParams.iv Base64UrlString initialization vector
- encryptionParams.mode String aes encryption mode 'ccm', 'gcm', 'ocb2'
- encryptionParams.ts Number tag size 64, 96, 128
- encryptionParams.adata String authenticated data to associate with the data

Throws Error if a parameter is invalid

Returns Base64UrlString the encrypted data

encryptKey

Encrypt key

Parameters

data Base64UrlString
key Base64UrlString
encryptionParams Object
- encryptionParams.iv Base64UrlString initialization vector
- encryptionParams.mode String aes encryption mode 'ccm', 'gcm', 'ocb2'
- encryptionParams.ts Number tag size 64, 96, 128
- encryptionParams.adata String authenticated data to associate with the data

Throws Error if a parameter is invalid

Returns Base64UrlString the encrypted data

decryptText

Decrypt text

Parameters

data Base64UrlString
key Base64UrlString
encryptionParams Object
- encryptionParams.iv Base64UrlString initialization vector
- encryptionParams.mode String aes encryption mode 'ccm', 'gcm', 'ocb2'
- encryptionParams.ts Number tag size 64, 96, 128
- encryptionParams.adata String authenticated data to associate with the data

Throws Error if a parameter is invalid, data is corrupt or wrong key

Returns String the decrypted data

decryptObject

Decrypt object

Parameters

data Base64UrlString
key Base64UrlString
encryptionParams Object
- encryptionParams.iv Base64UrlString initialization vector
- encryptionParams.mode String aes encryption mode 'ccm', 'gcm', 'ocb2'
- encryptionParams.ts Number tag size 64, 96, 128
- encryptionParams.adata String authenticated data to associate with the data

Throws Error if a parameter is invalid, data is corrupt or wrong key

Returns Object the decrypted data

decryptFile

Decrypt file

Parameters

data ArrayBuffer
decryptionKey Base64UrlString
decryptionParams SymmetricEncryptionParams

Examples

const keys = CryptolizeCore.createAsymmetricKeys()
 const password = 'password'
 const hint = 'hint'
 const record = CryptolizeCore.encryptRecord(..., keys.public, ..., [{ password, hint }], ...)
 const header = CryptolizeCore.decryptRecord(record, keys.private)[0]
 const key = CryptolizeCore.decryptKeyWithSymmetricEncryption(password, header)
 const file = CryptolizeCore.decryptFile(record.blocks[0].files[0].data, key, header.filesEncryptionParams[0].encryptionParams)
 console.log(file)

Throws Error if a parameter is invalid, data is corrupt or wrong key

Returns ArrayBuffer

decryptKey

Decrypt key

Parameters

data Base64UrlString
key Base64UrlString
encryptionParams Object
- encryptionParams.iv Base64UrlString initialization vector
- encryptionParams.mode String aes encryption mode 'ccm', 'gcm', 'ocb2'
- encryptionParams.ts Number tag size 64, 96, 128
- encryptionParams.adata String authenticated data to associate with the data

Throws Error if a parameter is invalid, data is corrupt or wrong key

Returns Base64UrlString the decrypted data

encryptRecord

Encrypt record

Parameters

headerKey ElGamalPublicKey public key for header encryption
metadata RecordMetadata
blocks {text: String, files: Array<{name: String, size: Number, type: String, id: String, path: String, service: String, data: ArrayBuffer}>, passwords: Array<{password: String, hint: String, iterations: Number}>, publicKeys: Array<{id: String, version: String, key: ElGamalPublicKey}>}

Examples

const headerKey = CryptolizeCore.createAsymmetricKeys().public

 const metadata = CryptolizeCore.createRecordMetadata(
   'id',
   'creator',
   'personalPage',
   'signature',
   'signatureKeyVersion',
   new Date().getTime(),
   new Date().getTimezoneOffset(),
   false,
   new Date().getTime(),
   'subject',
   'origin',
   {
     key1: 'value1',
     key2: 'value2'
   }
 )

 const password = { password: 'password', hint: 'hint', iterations: 100000 }
 const publicKey = { id: 'publicKeyOwnerId', version: CryptolizeCore.createAsymmetricKeys().public, key: CryptolizeCore.createAsymmetricKeys().public }
 const text = 'text'
 const file = {
   name: 'name',
   size: 1024,
   type: 'type',
   id: 'id',
   path: 'path',
   service: 'service',
   data: 'ArrayBuffer'
 }
 const block = { passwords: [password], publicKeys: [publicKey], text: 'text', files: [file] }

 const record = CryptolizeCore.encryptRecord(headerKey, metadata, [block])
 console.log(record)

Throws Error if a parameter is invalid

Returns Record the encrypted record

decryptRecord

Decrypt record

Parameters

record Record
headerKey ElGamalPrivateKey

Examples

const keys = CryptolizeCore.createAsymmetricKeys()
 const record = CryptolizeCore.encryptRecord(..., keys.public, ...)
 const headerWrapper = CryptolizeCore.decryptRecord(record, keys.private)
 console.log(headerWrapper)

Throws Error if a parameter is invalid, data is corrupt or wrong key

Returns HeaderWrapper header wrapper

decryptKeyWithSymmetricEncryption

Decrypt key with symmetric encryption

Parameters

password String
header Header
- header.symmetricEncryption

Examples

const keys = CryptolizeCore.createAsymmetricKeys()
 const password = 'password'
 const hint = 'hint'
 const record = CryptolizeCore.encryptRecord(..., keys.public, ..., [{ password, hint }], ...)
 const headers = CryptolizeCore.decryptRecord(record, keys.private)
 const key = CryptolizeCore.decryptKeyWithSymmetricEncryption(password, header[0])
 console.log(key)

Throws Error if the symmetricEncryption array is empty, data is corrupt or wrong password

Returns Base64UrlString encrypted key

decryptKeyWithAsymmetricEncryption

Decrypt key with asymmetric encryption

Parameters

id String
version String
privateKey ElGamalPrivateKey
header Header
- header.asymmetricEncryption

Examples

const headerKeys = CryptolizeCore.createAsymmetricKeys()
 const id = 'id'
 const keys = CryptolizeCore.createAsymmetricKeys()
 const password = 'password'
 const hint = 'hint'
 const record = CryptolizeCore.encryptRecord(..., headerKeys.public, ..., [{ id: id, version: keys.public, key: keys.public }], ...)
 const headers = CryptolizeCore.decryptRecord(record, headerKeys.private)
 const key = CryptolizeCore.decryptKeyWithAsymmetricEncryption(id, keys.public, keys.private, header[0])
 console.log(key)

Throws Error if the asymmetricEncryption array is empty, data is corrupt or wrong keyId

Returns Base64UrlString encrypted key

hasSymmetricEncryption

returns true if symmetric encryption exists, false otherwise

Parameters

header Header
- header.symmetricEncryption

Examples

const headerKeys = CryptolizeCore.createAsymmetricKeys()
 const id = 'id'
 const keys = CryptolizeCore.createAsymmetricKeys()
 const password = 'password'
 const hint = 'hint'
 const record = CryptolizeCore.encryptRecord(..., headerKeys.public, ..., [{ id: id, version: keys.public, key: keys.public }], ...)
 const headers = CryptolizeCore.decryptRecord(record, headerKeys.private)
 const hasSymmetricEncryption = CryptolizeCore.hasSymmetricEncryption(header[0])
 console.log(hasSymmetricEncryption)

Returns Boolean

hasAsymmetricEncryption

returns true if asymmetric encryption with supplied id exists, false otherwise

Parameters

id String
header Header

Examples

const headerKeys = CryptolizeCore.createAsymmetricKeys()
 const id = 'id'
 const keys = CryptolizeCore.createAsymmetricKeys()
 const password = 'password'
 const hint = 'hint'
 const record = CryptolizeCore.encryptRecord(..., headerKeys.public, ..., [{ id: id, version: keys.public, key: keys.public }], ...)
 const headers = CryptolizeCore.decryptRecord(record, headerKeys.private)
 const hasAsymmetricEncryption = CryptolizeCore.hasAsymmetricEncryption(id, header[0])
 console.log(hasAsymmetricEncryption)

Returns Boolean

getAsymmetricEncryptionParams

returns asymmetric encryption params of the supplied id

Parameters

id String
header Header
- header.asymmetricEncryption

Examples

const headerKeys = CryptolizeCore.createAsymmetricKeys()
 const id = 'id'
 const keys = CryptolizeCore.createAsymmetricKeys()
 const password = 'password'
 const hint = 'hint'
 const record = CryptolizeCore.encryptRecord(..., headerKeys.public, ..., [{ id: id, version: keys.public, key: keys.public }], ...)
 const headers = CryptolizeCore.decryptRecord(record, headerKeys.private)
 const asymmetricEncryptionParams = CryptolizeCore.getAsymmetricEncryptionParams(id, header[0])
 console.log(asymmetricEncryptionParams)

Returns (AsymmetricEncryptionWrapper | undefined)

decryptData

Decrypt data

Parameters

data Base64UrlString
decryptionKey Base64UrlString
decryptionParams SymmetricEncryptionParams

Examples

const keys = CryptolizeCore.createAsymmetricKeys()
 const password = 'password'
 const hint = 'hint'
 const record = CryptolizeCore.encryptRecord(..., keys.public, ..., [{ password, hint }], ...)
 const header = CryptolizeCore.decryptRecord(record, keys.private)[0]
 const key = CryptolizeCore.decryptKeyWithSymmetricEncryption(password, header)
 const data = CryptolizeCore.decryptData(record.blocks[0].data, key, header.dataEncryptionParams)
 console.log(data)

Throws Error if a parameter is invalid, data is corrupt or wrong key

Returns Data decrypted data

Async

Same as the sync API (except the createRecordMetadata and createEncryptionParams functions) but with Async suffix (encryptRecord -> encryptRecordAsync) and the functions return Promise

Can be used in browser environment only

Development

make sure node installed - install nvm if not
git clone git@bitbucket.org:witalize/cryptolize-core.git
cd cryptolize-core
npm install
lint code - npm run lint
run tests - npm test
run benchmarks - npm run benchmark
build from src - npm run build
update README - npm run docs
publish to npm (runs automatically tests, lint and build before) - npm publish