globalid-crypto-library
This library groups together all the crypto-related functionality in the globaliD platform, and makes it available so that it works for Node.js on the server.
Note that this is not a standalone npm
package in its own right.
Breaking Changes
Support for Node 12 and up
globaliD crypto library version 5 only supports Node 12 and up. We are going to support version based on the maintenance plan found here - https://nodejs.org/en/about/releases
Migrating from v3/v4 to v5
- Because all most every method in this package can be done without a promise, we decided to refactor the package so it can be used without a promise.
- Fixed how the Typescript interfaces are defined and because of that names of the sub-packages changed. The list of renames:
- cryptosdk.aes -> cryptosdk.AES
- cryptosdk.gid -> cryptosdk.GID
- cryptosdk.jwe -> cryptosdk.JWE
- cryptosdk.jwk -> cryptosdk.JWK
- cryptosdk.hmac -> cryptosdk.HMAC
- cryptosdk.pbkdf -> cryptosdk.PBKDF
- cryptosdk.rsa -> cryptosdk.RSA
- cryptosdk.util -> cryptosdk.Util
- Package no longer has a sub-package
bcrypt
, dependencebcrypt
was removed from the project. - Package no longer has a default export
- Method
cryptosdk.util.hmacSHA512
was remove, now it can be done withcryptosdk.HMAC.sha512
orcryptosdk.HMAC.nodeHmac('sha512',...)
Example or how to migrate:
// version 3 or 4
import cryptosdk from 'globalid-crypto-library'
const result: string = await cryptosdk.aes.encrypt(data, password)
// version 5
import * as cryptosdk from 'globalid-crypto-library'
const result: string = cryptosdk.AES.encrypt(data, password)
// or
import { AES } from 'globalid-crypto-library'
const result: string = AES.encrypt(data, password)
Dependencies
Currently the project has only one dependence:
Installation
To install, simply add the crypto library as a dependency within your project. For example:
$ npm install globalid-crypto-library --save
Usage
To use the globalid-crypto-library, simply require
the library, like this in the commonJS format:
const crypto = require('globalid-crypto-library')
or if you are using a transpiler (i.e. when using TypeScript):
import * as crypto from 'globalid-crypto-library'
Once it has been required, you can use a consistent interface across all the various platforms, following the API described below. For example:
let keyPair = crypto.RSA.generateKeyPair()
Available Methods
The crypto library is broken into several sections, grouping functions according to the type of cryptographic functionality they provide:
- crypto.AES: symmetric encryption and decryption
- crypto.GID: utility functions for globaliD identities
- crypto.JOSE: exporting npm package node-jose
- crypto.JWE: utility functions to create encryption and decryption
- crypto.JWS: utility functions to verify and create signature
- crypto.JWK: utility functions to import JWK keys public or private to PEM format
- crypto.HMAC: HMAC hashing algorithms
- crypto.PBKDF: key-generation using passwords
- crypto.RSA: key generation, signing, signing validation, encryption and decryption with RSA keys
- crypto.ED25519: key generation, signing, signing validation, encryption and decryption with ED25519 keys
- crypto.Util: utility functions
crypto.AES
encrypt
crypto.AES.encrypt(data: string, password: string): string
Encrypt string data using AES-256-CBC
. Returns a string containing
the IV in hex (first 32 characters) and encrypted data in base64-encoded encrypted data.
decrypt
crypto.AES.decrypt(data: string, password: string): string
Decrypt some data previously encrypted using the ```typescript crypto.AES.decrypt(data: string, password: string)` function.
Note: Taking the first 32 characters from the data
string is the IV value in hex needed for AES-256-CBC
.
encryptBuffer
crypto.AES.encryptBuffer(data: Buffer, password: string): Buffer
Encrypt Buffer data using AES-256-CBC
. First 16 bytes are IV value everything else it is encrypted value Buffer type.
decryptBuffer
crypto.AES.decryptBuffer(data, password): Buffer
Decrypt Buffer data previously encrypted using the ```typescript crypto.AES.encryptBuffer(data, password)` function.
encryptStream
crypto.AES.encryptStream(password): stream.Transform
Get the encrypt stream which can then be piped to destination.
decryptStream
crypto.AES.decryptStream(password): stream.Transform
Get the decrypt stream which can then be piped to destination.
crypto.GID
aesCbcEncryptSecurity
crypto.GID.aesCbcEncryptSecurity(data: string, password: string): string
Helper function to encrypt data. Password is hashed with PBKDF.get method and then use to encrypt the data. Iteration parameter on PBKDF.get here is hardcoded to value 100001.
aesCbcEncryptIdentity
crypto.GID.aesCbcEncryptIdentity(data: string, password: string, iterations: number = 100000): string
Helper function to encrypt data. Password is hashed with PBKDF.get method and then use to encrypt the data.
aesCbcDecryptSecurity
crypto.GID.aesCbcDecryptSecurity(encryptedData: string, password: string): string
Helper function to decrypt data. Password is hashed with PBKDF.get method and then use to decrypt the data. Iteration parameter on PBKDF.get here is hardcoded to value 100001.
aesCbcDecryptIdentity
crypto.GID.aesCbcDecryptIdentity(encryptedData: string, password: string, iterations: number = 100000): string
Helper function to decrypt data. Password is hashed with PBKDF.get method and then use to decrypt the data.
crypto.JOSE
Exporting package node-jose. You can read more about the package on their NPM page.
crypto.JWE
encrypt
type JwkKey = string | {[key: string]: string | string[] } | JWK.RawKey
async crypto.JWE.encrypt(public_key: JwkKey, data: string): Promise<string>
Encrypt data with JWK public key, with format compact
and content algorithm A256CBC-HS512
decrypt
type JwkKey = string | {[key: string]: string | string[] } | JWK.RawKey
async crypto.JWE.decrypt(private_key: JwkKey, encrypted_data: string): Promise<string>
Decrypting data with JWK private key.
crypto.JWK
publicKeyToPem
type JwkKey = string | {[key: string]: string | string[] } | JWK.RawKey
async crypto.JWK.publicKeyToPem(key: JwkKey): Promise<string>
Converting JWK public key format into PEM format
privateKeyToPem
type JwkKey = string | {[key: string]: string | string[] } | JWK.RawKey
async crypto.JWK.privateKeyToPem(key: JwkKey): Promise<string>
Converting JWK private key format into PEM format
crypto.JWS
sign
type JwkKey = string | {[key: string]: string | string[] } | JWK.RawKey
type KeyForm = 'json' | 'private' | 'pkcs8' | 'public' | 'spki' | 'pkix' | 'x509' | 'pem'
async crypto.JWS.sign(private_key: JwkKey, payload: string, key_form?: KeyForm): Promise<string>
Sign payload using JWK private key. Note that if the private key is not in standard JWK format, key_form parameter should also be specified. Signature algorithm used is RSA-SHA256
verify
type JwkKey = string | {[key: string]: string | string[] } | JWK.RawKey
type KeyForm = 'json' | 'private' | 'pkcs8' | 'public' | 'spki' | 'pkix' | 'x509' | 'pem'
async crypto.JWS.verify(public_key: JwkKey, jwk: string, key_form?: KeyForm): Promise<string>
Verify JWK signature using JWK public key. Note that if the private key is not in standard JWK format, key_form parameter should also be specified.
crypto.HMAC
md5
crypto.HMAC.md5(data: string, key: string): string
Calculate the MD5
hash of the given data, using the given salt. data
should
be the data to hash, as a string, and key
should be a string to
use as the key.
Returns the hash as a hex-encoded string.
sha1
crypto.HMAC.sha1(data: string, key: string): string
Calculate the SHA-1
hash of the given data, using the given salt. data
should be the data to hash, as a string, and key
should be a hex-encoded
string to use as the key.
Returns the hash as a hex-encoded string.
sha256
crypto.HMAC.sha256(data: string, key: string): string
Calculate the SHA-256
hash of the given data, using the given salt. data
should be the data to hash, as a string, and key
should be a hex-encoded
string to use as the key.
Returns the hash as a hex-encoded string.
sha384
crypto.HMAC.sha384(data: string, key: string): string
Calculate the SHA-384
hash of the given data, using the given salt. data
should be the data to hash, as a string, and key
should be a hex-encoded
string to use as the key.
Returns the hash as a hex-encoded string.
sha512
crypto.HMAC.sha512(data: string, key: string): string
Calculate the SHA-512
hash of the given data, using the given salt. data
should be the data to hash, as a string, and key
should be a hex-encoded
trying to use as the key.
Returns the hash as a hex-encoded string.
nodeHmac
crypto.HMAC.nodeHmac(algorithm: string, data: string, key: string): string
Calculate hmac hash of the given algorithm and data, using the given salt. data
should be the data to hash, as a string, and key
should be a hex-encoded
trying to use as the key.
Returns the hash as a hex-encoded string.
crypto.PBKDF
generate
crypto.PBKDF.generate(data: string, num_iterations?: number =20000, salt_length?: number = 16, key_length?: number = 16): Generate
Generate a new password-based key derivation function (PBKDF) using HMAC-SHA256. Returns an object with the following fields:
-
iterations
: The number of iterations used to generate the PBKDF. -
_salt
: A copy of the salt, as a Uint8Array. -
_pbkdf
: A copy of the generated hash, as a Uint8Array. -
salt
: A copy of the salt, as a base64-encoded string. -
hash
The generated hash, as a hex-encoded string. -
keySize
: The specified key length.
get
crypto.PBKDF.get(data: string, salt: string | Buffer, iterations: number, keySize: number): string
Uses a previously-generated PBDKF function to hash a password. Returns values encoded in hex.
crypto.RSA
generateKeyPair
crypto.RSA.generateKeyPair(bytes?: number = 2048): KeyPair
Upon completion, return an object containing two strings, the public and private key making up a new key pair.
Returns an object with public_key
and private_key
fields.
encrypt
crypto.RSA.encrypt(public_key: string, data: string): string`
Encrypt the given data using the given public key, using RSA. Both
public_key
and data
should be strings.
Upon completion, returns the encrypted data as a base64-encoded string.
Note that if can throw an Error with a "DATA_TOO_LARGE" exception if the data is too large to be encrypted.
Note for Node: the encrypt method as first parameter, public_key
, can accept pem encoded string of the key or path to the pem file in the filesystem.
decrypt
crypto.RSA.decrypt(private_key: nodeCrypto.RsaPrivateKey | string, encrypted_data: string): string
Decrypt the given encrypted data using the given private key, using RSA. Both
encrypted_data
should be string and private_key
should be the following type nodeCrypto.RsaPrivateKey | string
.
Upon completion, returns the encrypted data as a string.
Note for Node: first parameter private_key
of the decrypt method can be string
or nodeCrypto.RsaPrivateKey
.
sign
crypto.RSA.sign(private_key: PrivateKey | string, data: string): string
Sign a piece of data using the given private key. This generates an SHA256
signature hash of the given data using the given private key. data
should be string
and private_key
should be the following type PrivateKey | string
.
Upon completion, returns the digital signature as a base64-encoded string
.
verifySignature
crypto.RSA.verifySignature(public_key: string, data: string, signature: string): boolean
Verify a previously-signed piece of data using the given public key. The given signature is verified as being generated using the private key associated with the given public key and the given data. All three parameters should be strings.
Upon completion, returns a boolean indicating whether or not the verification was successful.
Note for Node: the encrypt method as first parameter, public_key
, can accept pem encoded string of the key or path to the pem file in the filesystem.
crypto.ED25519
We are using the following package here - https://sodium-friends.github.io/docs/
generateKeys
interface Ed25519Keys {
privateKey: string
publicSigningKey: string
}
crypto.ED25519.generateKeys(privateKeyBase58?: string): Ed25519Keys
It will generate you a ED25519 keypair, if arguments privateKeyBase58 is send, it will create public key from it and return the keypair.
signMessage
crypto.ED25519.signMessage(message: string, privateKey: string): string
Signing a message with a secret/private key ED25519. Signed message is in Base58.
verifySignature
crypto.ED25519.verifySignature(message: string, publicKey: string, signature: string): boolean
Verifies that the message was signed with the secret/private key.
getSharedSecretHex
crypto.ED25519.getSharedSecretHex(privateKey: string, publicKey: string): string
Generates a shared secret, with secret/private key and public key. Secret and public key needs to either be the following:
- Secret and public key needs to be converted to curve 25519.
- Secret key is ED25519 and public key is a scalar multiplication public key based on a secret ED25519 key. Secret Key A and Public Key B will generate the same secret as Secret Key B and Public Key A.
sealedBox
crypto.ED25519.sealedBox(message: string, publicKey: string): string
Encrypt the given message using the given public key. Public key here needs to be ED25519, function will do the conversion to curve25519.
sealedBoxOpen
crypto.ED25519.sealedBoxOpen(ciphertext: string, publicKey: string, privateKey: string): string
Decrypt the given ciphertext using the given public key and secret/private key. Keys here needs to be ED25519, function will do the conversion to curve25519.
getPublicEncryptionKey
crypto.ED25519.getPublicEncryptionKey(publicKey: string): string
Converts an ed25519 public key to curve 25519
getPrivateEncryptionKey
crypto.ED25519.getPrivateEncryptionKey(privateKey: string): string
Converts an ed25519 secret/private key to curve 25519
getXPublicKey
crypto.ED25519.getXPublicKey(secretKey: string): string
Creates a scalar multiplication public key based on a secret key.
deriveIntoED25519Key
crypto.ED25519.deriveIntoED25519Key(secretKey: string, index: number, context: string): string
Creates a new ED25519 signing key, derived based on the secretKey, index and context. secretKey
needs to be ED25519 private/secret key.
crypto.Util
randomBytes
crypto.Util.randomBytes(bytes: number): number[]
Generates an array of num_bytes
cryptographically-random bytes. Each array
entry will be an integer in the range 0..255.
bytesToUint8Array
crypto.Util.bytesToUint8Array(bytes: number[]): Uint8Array
Convert an array of bytes into a Uint8Array.
uint8ArrayToBytes
crypto.Util.uint8ArrayToBytes(uint8Array: Uint8Array): number[]
Convert a Uint8Array back into a regular array of number in the range 0..255.
bytesToString
crypto.Util.bytesToString(bytes: number[]): string
Convert an array of bytes into a string. Each byte in the array will correspond to a single character with that ordinal value in the resulting string.
stringToBytes
crypto.Util.stringToBytes(rawString: string): number[]
Convert a string back into an array of bytes. Each character in the string corresponds to one byte in the returned array.
bytesToBase64
crypto.Util.bytesToBase64(bytesArray: number[]): string
Convert an array of bytes into a base64-encoded string.
base64ToBytes
crypto.Util.base64ToBytes(base64String: string): number[]
Convert a base64-encoded string back into an array of bytes.
bytesToHex
crypto.Util.bytesToHex(bytesArray: number[]): string
Convert an array of bytes into a hex-encoded string.
hexToBytes
crypto.Util.hexToBytes(hexString: string): number[]
Convert a hex-encoded string back into an array of bytes.
nodeHash
crypto.Util.nodeHash(algorithm: string, data: string | NodeJS.ArrayBufferView): string;
Calculate the hash ( based on algorithm
) of the given data. data
can be a string or a
Buffer like object, salt should be string or NodeJS.ArrayBufferView.
Returns the hash as a hex-encoded string.
hashSHA512
crypto.Util.hashSHA512(data: string | NodeJS.ArrayBufferView): string
Calculate the SHA-512
hash of the given data. data
can be a string or a
Buffer like object.
Returns the hash as a hex-encoded string.
bytesToBase58
crypto.Util.bytesToBase58(byteData: Uint8Array): string
Convert bytes into an base58 string
base58ToBytes
crypto.Util.base58ToBytes(str: string): Uint8Array
Convert base58 string into bytes ( Uint8Array )
stringToUint8Array
crypto.Util.stringToUint8Array(str: string): Uint8Array
Convert string into Uint8Array array
Examples with encrypt / decrypt streams
// encrypt the file
createReadStream('file path')
.pipe(encryptStream(password))
.on('error', handleError)
.pipe(createWriteStream('encrypted file path'))
.on('close', done)
// decrypt the file
createReadStream('encrypted file path')w
.pipe(decryptStream(password))
.on('error', handleError)
.pipe(createWriteStream('decrypted file path'))
.on('close', done)
// re-encrypt the file with different password
createReadStream('encrypted file path')
.pipe(decryptStream(password))
.on('error', handleError)
.pipe(encryptStream(newPassword))
.on('error', handleError)
.pipe(createWriteStream('reencrypted file path'))
.on('close', done)
using aws s3
// encrypt the file and upload to s3 bucket
const encryptStream: stream.Transform =
createReadStream('path to file') // some valid read stream
.pipe(GIDCrypto.AES.encryptStream(password))
const params: aws.S3.Types.PutObjectRequest = {
Body: encryptStream,
Bucket: '<bucket>',
Key: `<s3 file path>`,
}
await S3.upload(params).promise()
// download decrypted file from s3
return new Promise((resolve, reject) => {
const params: aws.S3.GetObjectRequest = {
Bucket: '<bucket>',
Key: `<path to entrypted file>`,
}
// some valid write stream
const destinationStream = createWriteStream('/path/to/dec/file.ext')
S3
.getObject(params)
.createReadStream()
.pipe(GIDCrypto.AES.decryptStream(password))
.on('error', reject)
.pipe(destinationStream)
.on('error', reject)
.on('finish', resolve)
})
// re-uploading encrypted file from one S3 bucket to another
// with on-the-fly re-encryption
const password: string = '<current password>'
const newPassword: string = '<new desired password>'
return new Promise((resolve, reject) => {
// currently encrypted file on s3
const downloadParams: aws.S3.GetObjectRequest = {
Bucket: currentBucket,
Key: `<path to encrypted file>`,
}
// decrypt and encrypt stream
const reencStream: stream.Transform = S3
.getObject(downloadParams)
.createReadStream()
.on('error', reject)
.pipe(GIDCrypto.AES.decryptStream(password))
.on('error', reject)
.pipe(GIDCrypto.AES.encryptStream(newPassword))
.on('error', reject)
// upload params for re-encrypted file on different bucket
const uploadParams: aws.S3.Types.PutObjectRequest = {
Body: reencStream,
Bucket: bucket2,
Key: `<desired encrypted file path>`,
}
S3
.upload(uploadParams)
.promise()
.then(resolve)
.catch(reject)
})