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
RecordType: Object
Parameters
headerWrapper
headerWrapperEncryptionParams
blocks
Properties
headerWrapper
HeaderWrapperheaderWrapperEncryptionParams
HeaderWrapperEncryptionParamsblocks
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 wrapperType: Object
Parameters
metadata
blocks
Properties
metadata
RecordMetadatablocks
Array<Header>
RecordMetadata
RecordMetadataType: Object
Parameters
id
creator
personalPage
signature
signatureKeyVersion
timestamp
timezoneOffset
isOnce
expiration
subject
origin
custom
Properties
type
Stringid
Stringcreator
String?personalPage
String?signature
Base64UrlString?signatureKeyVersion
String?timestamp
NumbertimezoneOffset
NumberisOnce
Booleanexpiration
Number?subject
String?origin
String?custom
Object?
HeaderWrapperEncryptionParams
Header wrapper encryption paramsType: Object
Parameters
id
tag
encryptionParams
Properties
keyId
Stringtag
Base64UrlStringencryptionParams
SymmetricEncryptionParams
Block
BlockType: Object
Parameters
header
data
files
Properties
header
Headerdata
Data encrypted and represented by Base64UrlStringfiles
Array<EncryptedFile>
Header
HeaderType: Object
Parameters
symmetricEncryption
asymmetricEncryption
dataEncryptionParams
filesEncryptionParams
filesStorageParams
Properties
symmetricEncryption
Array<SymmetricEncryptionWrapper>asymmetricEncryption
Array<AsymmetricEncryptionWrapper>encryptionParams
SymmetricEncryptionParamsfilesEncryptionParams
Array<FilesEncryptionParams>filesStorageParams
Array<FilesStorageParams>
SymmetricEncryptionWrapper
Symmetric encryption wrapperType: Object
Parameters
hint
derivationParams
encryptionParams
encryptedKey
Properties
hint
StringderivationParams
DerivationParamsencryptionParams
SymmetricEncryptionParamsencryptedKey
Base64UrlString
AsymmetricEncryptionWrapper
Asymmetric encryption wrapperType: Object
Parameters
id
version
tag
encryptionParams
encryptedKey
Properties
id
Stringversion
Stringtag
Base64UrlStringencryptionParams
SymmetricEncryptionParamsencryptedKey
Base64UrlString
FilesEncryptionParams
Files encryption paramsType: Object
Parameters
id
encryptionParams
Properties
id
StringencryptionParams
SymmetricEncryptionParams
FilesStorageParams
Files storage paramsType: Object
Parameters
id
path
service
Properties
Data
DataType: Object
Parameters
text
files
Properties
text
Stringfiles
Array<FileMetadata>
FileMetadata
File metadataType: Object
Parameters
name
size
type
id
Properties
EncryptedFile
Encrypted fileType: Object
Parameters
id
path
service
data
Properties
id
Stringpath
Stringservice
Stringdata
ArrayBuffer
SymmetricEncryptionParams
Symmetric encryption paramsType: Object
Parameters
iv
Properties
DerivationParams
Derivation paramsType: Object
Parameters
iterations
salt
Properties
iterations
Numbersalt
Base64UrlString
API
Sync
deriveKey
Derives encryption key from simple textParameters
- `$1.salt` **Base64UrlString**
- `$1.iterations` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**
- Throws Error if a parameter is invalid
Returns Base64UrlString
createRandom
Create random stringParameters
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 keysParameters
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 ECDSAParameters
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 keyParameters
privateKey
ECDSAPrivateKey the key to sign withtext
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 keyParameters
publicKey
ECDSAPublicKey the key to verify withtext
String the text to verifysignature
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 metadataParameters
id
Stringcreator
personalPage
signature
signatureKeyVersion
timestamp
timezoneOffset
isOnce
expiration
subject
origin
custom
Returns RecordMetadata
createEncryptionParams
Create encryption paramsParameters
iv
Base64UrlString
Returns SymmetricEncryptionParams
encryptText
Encrypt textParameters
data
Stringkey
encryptionParams
- `encryptionParams.iv` **Base64UrlString** initialization vector
- `encryptionParams.mode` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** aes encryption mode ['ccm', 'gcm', 'ocb2']
- `encryptionParams.ts` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** tag size [64, 96, 128]
- `encryptionParams.adata` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** authenticated data to associate with the data
- Throws Error if a parameter is invalid
Returns Base64UrlString the encrypted data
encryptObject
Encrypt objectParameters
data
Objectkey
encryptionParams
- `encryptionParams.iv` **Base64UrlString** initialization vector
- `encryptionParams.mode` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** aes encryption mode ['ccm', 'gcm', 'ocb2']
- `encryptionParams.ts` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** tag size [64, 96, 128]
- `encryptionParams.adata` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** authenticated data to associate with the data
- Throws Error if a parameter is invalid
Returns Base64UrlString the encrypted data
encryptKey
Encrypt keyParameters
data
Base64UrlStringkey
Base64UrlStringencryptionParams
Object
- `encryptionParams.iv` **Base64UrlString** initialization vector
- `encryptionParams.mode` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** aes encryption mode ['ccm', 'gcm', 'ocb2']
- `encryptionParams.ts` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** tag size [64, 96, 128]
- `encryptionParams.adata` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** authenticated data to associate with the data
- Throws Error if a parameter is invalid
Returns Base64UrlString the encrypted data
decryptText
Decrypt textParameters
data
Base64UrlStringkey
Base64UrlStringencryptionParams
Object
- `encryptionParams.iv` **Base64UrlString** initialization vector
- `encryptionParams.mode` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** aes encryption mode ['ccm', 'gcm', 'ocb2']
- `encryptionParams.ts` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** tag size [64, 96, 128]
- `encryptionParams.adata` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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 objectParameters
data
Base64UrlStringkey
Base64UrlStringencryptionParams
Object
- `encryptionParams.iv` **Base64UrlString** initialization vector
- `encryptionParams.mode` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** aes encryption mode ['ccm', 'gcm', 'ocb2']
- `encryptionParams.ts` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** tag size [64, 96, 128]
- `encryptionParams.adata` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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 fileParameters
data
ArrayBufferdecryptionKey
decryptionParams
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 keyParameters
data
Base64UrlStringkey
Base64UrlStringencryptionParams
Object
- `encryptionParams.iv` **Base64UrlString** initialization vector
- `encryptionParams.mode` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** aes encryption mode ['ccm', 'gcm', 'ocb2']
- `encryptionParams.ts` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** tag size [64, 96, 128]
- `encryptionParams.adata` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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 recordParameters
headerKey
ElGamalPublicKey public key for header encryptionmetadata
RecordMetadatablocks
{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 recordParameters
record
RecordheaderKey
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 encryptionParameters
password
Stringheader
- `header.symmetricEncryption`
Examplesconst 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 encryptionParameters
id
Stringversion
privateKey
header
- `header.asymmetricEncryption`
Examplesconst 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 otherwiseParameters
header
Header
- `header.symmetricEncryption`
Examplesconst 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 otherwiseParameters
id
Stringheader
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 idParameters
id
Stringheader
- `header.asymmetricEncryption`
Examplesconst 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 dataParameters
data
Base64UrlStringdecryptionKey
Base64UrlStringdecryptionParams
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 thecreateRecordMetadata
and createEncryptionParams
functions) but with Async
suffix (encryptRecord
-> encryptRecordAsync
) and the functions return PromiseCan 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