@cryptolize/core

cryptolize core

Usage no npm install needed!

<script type="module">
  import cryptolizeCore from 'https://cdn.skypack.dev/@cryptolize/core';
</script>

README

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

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

RecordMetadata

RecordMetadata

Type: Object

Parameters

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

Properties

HeaderWrapperEncryptionParams

Header wrapper encryption params

Type: Object

Parameters

  • id
  • tag
  • encryptionParams

Properties

Block

Block

Type: Object

Parameters

  • header
  • data
  • files

Properties

Header

Header

Type: Object

Parameters

  • symmetricEncryption
  • asymmetricEncryption
  • dataEncryptionParams
  • filesEncryptionParams
  • filesStorageParams

Properties

SymmetricEncryptionWrapper

Symmetric encryption wrapper

Type: Object

Parameters

  • hint
  • derivationParams
  • encryptionParams
  • encryptedKey

Properties

AsymmetricEncryptionWrapper

Asymmetric encryption wrapper

Type: Object

Parameters

  • id
  • version
  • tag
  • encryptionParams
  • encryptedKey

Properties

FilesEncryptionParams

Files encryption params

Type: Object

Parameters

  • id
  • encryptionParams

Properties

FilesStorageParams

Files storage params

Type: Object

Parameters

  • id
  • path
  • service

Properties

Data

Data

Type: Object

Parameters

  • text
  • files

Properties

FileMetadata

File metadata

Type: Object

Parameters

  • name
  • size
  • type
  • id

Properties

EncryptedFile

Encrypted file

Type: Object

Parameters

  • id
  • path
  • service
  • data

Properties

SymmetricEncryptionParams

Symmetric encryption params

Type: Object

Parameters

  • iv

Properties

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

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

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

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