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

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

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

Block

Type: Object

Parameters

• header
• data
• files

Properties

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

Header

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

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 [email protected]: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