SSCrypto

Super-Simple Crypto is a wrapper around other cryptography libraries, intended to be simple to use, provide a consistent interface for multiple encryption backends (for now, forge and nodeJS crypto), and well-chosen parameters.

It was created by Seald to unify crypto accross its projects.

Table of Contents

Installation

API:

• SymKey

  • constructor

  • Properties

    • encryptionKey
    • keySize
    • signingKey

  • Methods

    • calculateHMAC
    • decrypt
    • decryptStream
    • encrypt
    • encryptStream
    • toB64
    • toString
    • fromB64
    • fromString

• PublicKey

  • constructor

  • Properties

    • publicKey

  • Methods

    • encrypt
    • getB64Hash
    • getHash
    • toB64
    • verify
    • fromB64

• PrivateKey

  • constructor

  • Properties

    • privateKey
    • publicKey

  • Methods

    • decrypt
    • encrypt
    • getB64Hash
    • getHash
    • sign
    • toB64
    • verify
    • fromB64
    • generate

• Utils

  • randomBytes
  • sha256

Installation

For use with the nodeJS back-end:

npm i -S sscrypto

// ES Module syntax
import { node } from 'sscrypto' // this may cause trouble if you do not have forge installed and are not using a build-system with tree-shaking
// or
import { SymKey, PrivateKey, PublicKey } from 'sscrypto/node'
// or
import SymKey from 'sscrypto/node/aes'
import { PrivateKey, PublicKey } from 'sscrypto/node/rsa'

// CommonJS syntax
const { node } = require('sscrypto') // this may cause trouble if you do not have forge installed and are not using a build-system with tree-shaking
// or
const { SymKey, PrivateKey, PublicKey } = require('sscrypto/node')
// or
const SymKey = require('sscrypto/node/aes')
const { PrivateKey, PublicKey } = require('sscrypto/node/rsa')

For use with the forge back-end:

npm i -S sscrypto node-forge

// ES Module syntax
import { forge } from 'sscrypto'
// or
import { SymKey, PrivateKey, PublicKey, utils } from 'sscrypto/forge'
// or
import SymKey from 'sscrypto/forge/aes'
import { PrivateKey, PublicKey } from 'sscrypto/forge/rsa'

// CommonJS syntax
const { node } = require('sscrypto')
// or
const { SymKey, PrivateKey, PublicKey, utils } = require('sscrypto/node')
// or
const SymKey = require('sscrypto/node/aes')
const { PrivateKey, PublicKey } = require('sscrypto/node/rsa')

Class: SymKey

Constructor

⊕ new SymKey(arg?: SymKeySize | Buffer): SymKey

Constructor of SymKey, if you want to construct an SymKey with an existing key, use the static methods SymKey.fromString or fromB64 Defaults to a new 256 bits key.

constructs: SymKey

Parameters:

Name	Type	Default value
Default value arg	SymKeySize | Buffer	256

Returns: SymKey

---

Properties

<Private> encryptionKey

● encryptionKey: string

---

keySize

● keySize: number

---

<Private> signingKey

● signingKey: string

---

Methods

calculateHMAC

▸ calculateHMAC(textToAuthenticate: Buffer): Buffer

Calculates a SHA-256 HMAC with the SymKey#signingKey on the textToAuthenticate

Parameters:

Name	Type	Description
textToAuthenticate	Buffer	-

Returns: Buffer

---

decrypt

▸ decrypt(cipheredMessage: Buffer): Buffer

Decrypts the cipheredMessage using the same algorithms as SymKey#encrypt

Parameters:

Name	Type	Description
cipheredMessage	Buffer	-

Returns: Buffer

---

decryptStream

▸ decryptStream(): Transform

Creates a Transform stream that decrypts the encrypted data piped to it.

Returns: Transform

---

encrypt

▸ encrypt(clearText: Buffer): Buffer

Encrypts the clearText with SymKey#encryptionKey using AES-CBC, and a SHA-256 HMAC calculated with SymKey#signingKey, returns it concatenated in the following order: InitializationVector CipherText HMAC

Parameters:

Name	Type	Description
clearText	Buffer	-

Returns: Buffer

---

encryptStream

▸ encryptStream(): Transform

Creates a Transform stream that encrypts the data piped to it.

Returns: Transform

---

toB64

▸ toB64(): string

Returns both SymKey#signingKey and SymKey#encryptionKey concatenated encoded with b64

Returns: string

---

toString

▸ toString(): string

Returns both SymKey#signingKey and SymKey#encryptionKey concatenated as a binary string

Returns: string

---

<Static> fromB64

▸ fromB64(messageKey: string): SymKey

Static method to construct a new SymKey from a b64 encoded messageKey

Parameters:

Name	Type	Description
messageKey	string	b64 encoded messageKey

Returns: SymKey

---

<Static> fromString

▸ fromString(messageKey: string): SymKey

Static method to construct a new SymKey from a binary string encoded messageKey

Parameters:

Name	Type	Description
messageKey	string	binary encoded messageKey

Returns: SymKey

---

Class: PublicKey

Hierarchy

PublicKey

↳ PrivateKey

---

Constructor

⊕ new PublicKey(key: Buffer): PublicKey

PublicKey constructor. Should be given a Buffer containing a DER serialization of the key.

constructs: PublicKey

Parameters:

Name	Type	Description
key	Buffer

Returns: PublicKey

---

Properties

<Protected> publicKey

● publicKey: PublicKey

---

Methods

encrypt

▸ encrypt(clearText: Buffer, doCRC?: boolean): Buffer

Encrypts a clearText for the Private Key corresponding to this PublicKey.

method:

Parameters:

Name	Type	Default value	Description
clearText	Buffer	-	-
Default value doCRC	boolean	true	-

Returns: Buffer

---

getB64Hash

▸ getB64Hash(): string

Returns: string

---

getHash

▸ getHash(): string

Returns: string

---

toB64

▸ toB64(options?: __type): string

Serializes the key to DER format and encodes it in b64.

method:

Parameters:

Name	Type	Default value
Default value options	__type	null

Returns: string

---

verify

▸ verify(textToCheckAgainst: Buffer, signature: Buffer): boolean

Verify that the message has been signed with the Private Key corresponding to this PublicKey.

Parameters:

Name	Type	Description
textToCheckAgainst	Buffer	-
signature	Buffer	-

Returns: boolean

---

<Static> fromB64

▸ fromB64(b64DERFormattedPublicKey: string): PublicKey

Returns a PublicKey from it's DER base64 serialization.

method:

static:

Parameters:

Name	Type	Description
b64DERFormattedPublicKey	string	a b64 encoded public key formatted with DER

Returns: PublicKey

---

Class: PrivateKey

Hierarchy

PublicKey

↳ PrivateKey

---

Constructor

⊕ new PrivateKey(key: Buffer): PrivateKey

Overrides PublicKey.constructor

Private Key constructor. Shouldn't be used directly, use fromB64 or generate static methods

constructs: PrivateKey

Parameters:

Name	Type	Description
key	Buffer

Returns: PrivateKey

---

Properties

<Protected> privateKey

● privateKey: PrivateKey

---

<Protected> publicKey

● publicKey: PublicKey

Inherited from PublicKey.publicKey

---

Methods

decrypt

▸ decrypt(cipherText: Buffer, doCRC?: boolean): Buffer

Deciphers the given message.

Parameters:

Name	Type	Default value	Description
cipherText	Buffer	-	-
Default value doCRC	boolean	true

Returns: Buffer

---

encrypt

▸ encrypt(clearText: Buffer, doCRC?: boolean): Buffer

Inherited from PublicKey.encrypt

Encrypts a clearText for the Private Key corresponding to this PublicKey.

method:

Parameters:

Name	Type	Default value	Description
clearText	Buffer	-	-
Default value doCRC	boolean	true	-

Returns: Buffer

---

getB64Hash

▸ getB64Hash(): string

Inherited from PublicKey.getB64Hash

Returns: string

---

getHash

▸ getHash(): string

Inherited from PublicKey.getHash

Returns: string

---

sign

▸ sign(textToSign: Buffer): Buffer

Signs the given message with this Private Key.

Parameters:

Name	Type	Description
textToSign	Buffer	-

Returns: Buffer

---

toB64

▸ toB64(__namedParameters?: object): string

Overrides PublicKey.toB64

Serializes the key to DER format and encodes it in b64.

method:

Parameters:

Default value __namedParameters: object

Name	Type	Default value
publicOnly	boolean	false

Returns: string

---

verify

▸ verify(textToCheckAgainst: Buffer, signature: Buffer): boolean

Inherited from PublicKey.verify

Verify that the message has been signed with the Private Key corresponding to this PublicKey.

Parameters:

Name	Type	Description
textToCheckAgainst	Buffer	-
signature	Buffer	-

Returns: boolean

---

<Static> fromB64

▸ fromB64(b64DERFormattedPrivateKey: string): PrivateKey

Overrides PublicKey.fromB64

Returns a PrivateKey from it's DER base64 serialization.

method:

static:

Parameters:

Name	Type	Description
b64DERFormattedPrivateKey	string	a b64 encoded private key formatted with DER

Returns: PrivateKey

---

<Static> generate

▸ generate(size?: AsymKeySize): Promise<PrivateKey>

Generates a PrivateKey asynchronously

⚠️ On nodeJS back-end, this is only available if you have node 10.12 or newer

Parameters:

Name	Type	Default value
Default value size	AsymKeySize	4096

Returns: Promise<PrivateKey>

---

Utils

randomBytes

▸ randomBytes(length?: number): Buffer

Returns a Buffer of random bytes

Parameters:

Name	Type	Default value
Default value length	number	10

Returns: Buffer

---

sha256

▸ sha256(data: Buffer): Buffer

Returns a Buffer containing the hash of the given data

Parameters:

Name	Type	Description
data	Buffer	-

Returns: Buffer

---

Type aliases

SymKeySize

Ƭ SymKeySize: 128 | 192 | 256

AsymKeySize

Ƭ AsymKeySize: 4096 | 2048 | 1024

---