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, nodeJS crypto, and WebCrypto.subtle), and well-chosen parameters.

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

Table of Contents

Installation

API:

• SymKey

  • constructor

  • Properties

    • key
    • keySize

  • Methods

    • decrypt
    • decryptAsync
    • decryptStream
    • encrypt
    • encryptAsync
    • encryptStream
    • toB64
    • toString
    • fromB64
    • fromString
    • generate

• PublicKey

  • constructor

  • Properties

    • publicKeyBuffer

  • Methods

    • encrypt
    • encryptAsync
    • getHash
    • toB64
    • toString
    • verify
    • verifyAsync
    • fromB64

• PrivateKey

  • constructor

  • Properties

    • privateKeyBuffer
    • publicKeyBuffer

  • Methods

    • decrypt
    • decryptAsync
    • encrypt
    • encryptAsync
    • getHash
    • sign
    • signAsync
    • toB64
    • verify
    • verifyAsync
    • fromB64
    • generate

• Utils

  • randomBytes
  • randomBytesAsync
  • 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 { forge } = require('sscrypto')
// or
const { SymKey, PrivateKey, PublicKey, utils } = require('sscrypto/forge')
// or
const SymKey = require('sscrypto/forge/aes')
const { PrivateKey, PublicKey } = require('sscrypto/forge/rsa')

For use with the WebCrypto back-end:

To use the WebCrypto back-end, you still need to install forge, because it falls back to forge for unimplemented features & when the browser is not compatible with WebCrypto.

Of course, the WebCrypto back-end only works in browsers. You will have to use a build system to package everything, and provide the relevant NodeJS polyfills (such as Buffer). Using Webpack works well.

npm i -S sscrypto node-forge

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

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

Class: SymKey

Constructor

⊕ new SymKey(key: Buffer | SymKeySize): SymKey

Constructor of SymKey

Using a number as argument, or relying on default, is deprecated. Use SymKey.generate instead.

Defaults to a new 256 bits key (deprecated).

constructs: SymKey

Parameters:

Name | Type | Default | Description | ------ | ------ | ------ | ------ | key | Buffer | SymKeySize | 256 | The key to construct the SymKey with. Passing a keySize is deprecated. Use SymKey.generate instead. |

Returns: SymKey

Properties

Readonly key

● key: Buffer

Readonly keySize

● keySize: [SymKeySize](#symkeysize)

Methods

decrypt

▸ decrypt(cipheredMessage: Buffer): Buffer

Decrypts the cipherText using AES-CBC with the embedded IV, and checking the embedded SHA-256 HMAC

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | cipheredMessage | Buffer | - |

Returns: Buffer

decryptAsync

▸ decryptAsync(cipheredMessage: Buffer): Promise<Buffer>

Decrypts the cipherText using AES-CBC with the embedded IV, and checking the embedded SHA-256 HMAC

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | cipheredMessage | Buffer | - |

Returns: Promise<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#authenticationKey, returns it concatenated in the following order: InitializationVector CipherText HMAC

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | clearText | Buffer | - |

Returns: Buffer

encryptAsync

▸ encryptAsync(clearText: Buffer): Promise<Buffer>

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

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | clearText | Buffer | - |

Returns: Promise<Buffer>

encryptStream

▸ encryptStream(): Transform

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

Returns: Transform

toB64

▸ toB64(): string

Returns the SymKey's key encoded with b64

Returns: string

toString

▸ toString(): string

Returns the SymKey's key encoded as a binary string

Returns: string

<Static> fromB64

▸ fromB64(messageKey: string): SymKey

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

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | messageKey | string | b64 encoded key |

Returns: SymKey

<Static> fromString

▸ fromString(messageKey: string): SymKey

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

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | messageKey | string | binary encoded key |

Returns: SymKey

<Static> generate

▸ generate(size?: SymKeySize): Promise<SymKey>

Static method to generate a new SymKey of a given size asynchronously

Parameters:

| Name | Type | Default value | | ------ | ------ | ------ | | size | SymKeySize | 256 |

Returns: Promise<SymKey>

Class: PublicKey

Hierarchy

PublicKey

↳ PrivateKey

Constructor

⊕ new PublicKey(key: Buffer): PublicKey

Constructor for PublicKey class for every public key implementation of SSCrypto. It ensures that given buffer is a valid PublicKey, either encoded in an SPKI enveloppe or as a bare public key representation using ASN.1 syntax with DER encoding, and sets the publicKeyBuffer

constructs: PublicKey

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | key | Buffer | |

Returns: PublicKey

Properties

Readonly publicKeyBuffer

● publicKeyBuffer: Buffer

A Buffer that contains a representation of the instantiated RSA PublicKey using ASN.1 syntax with DER encoding wrapped in an SPKI enveloppe as per RFC 5280, and encoded per PKCS#1 v2.2 specification.

Methods

encrypt

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

Optionally prefixes the cleartext with a CRC32 of the initial clearText then, encrypts the result synchronously with RSAES-OAEP-ENCRYPT with SHA-1 as a Hash function and MGF1-SHA-1 as a mask generation function as per PKCS#1 v2.2 section 7.1.1 using the instantiated PublicKey

Parameters:

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

Returns: Buffer

encryptAsync

▸ encryptAsync(clearText: Buffer, doCRC?: boolean): Promise‹Buffer›

Optionally prefixes the cleartext with a CRC32 of the initial clearText then, encrypts the result asynchronously with RSAES-OAEP-ENCRYPT with SHA-1 as a Hash function and MGF1-SHA-1 as a mask generation function as per PKCS#1 v2.2 section 7.1.1 using the instantiated PublicKey

Parameters:

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

Returns: Promise‹Buffer›

getHash

▸ getHash(): string

Gives a SHA-256 hash encoded in base64 of the RSA PublicKey encoded in base64 using ASN.1 syntax with DER encoding wrapped in an SPKI enveloppe as per RFC 5280, and encoded per PKCS#1 v2.2 specification

Returns: string

toB64

▸ toB64(options?: object): string

Exports the instance of an RSA PublicKey in base64 using ASN.1 syntax with DER encoding wrapped in an SPKI enveloppe as per RFC 5280, and encoded per PKCS#1 v2.2 specification.

Parameters:

▪Default value options: object= null

| Name | Type | | ------ | ------ | | publicOnly? | boolean |

Returns: string

toString

▸ toString(options?: object): string

Exports the instance of an RSA PublicKey in binary string using ASN.1 syntax with DER encoding wrapped in an SPKI enveloppe as per RFC 5280, and encoded per PKCS#1 v2.2 specification.

deprecated

Parameters:

▪Default value options: object= null

| Name | Type | | ------ | ------ | | publicOnly? | boolean |

Returns: string

verify

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

Verifies synchronously that the given signature is valid for textToCheckAgainst using RSASSA-PSS-VERIFY which itself uses EMSA-PSS encoding with SHA-256 as the Hash function and MGF1-SHA-256, and a salt length sLen of Math.ceil((keySizeInBits - 1)/8) - digestSizeInBytes - 2 as per PKCS#1 v2.2 section 8.1.2 using instantiated PublicKey.

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | textToCheckAgainst | Buffer | - | | signature | Buffer | - |

Returns: boolean

verifyAsync

▸ verifyAsync(textToCheckAgainst: Buffer, signature: Buffer): Promise<boolean>

Verifies asynchronously that the given signature is valid for textToCheckAgainst using RSASSA-PSS-VERIFY which itself uses EMSA-PSS encoding with SHA-256 as the Hash function and MGF1-SHA-256, and a salt length sLen of Math.ceil((keySizeInBits - 1)/8) - digestSizeInBytes - 2 as per PKCS#1 v2.2 section 8.1.2 using instantiated PublicKey.

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | textToCheckAgainst | Buffer | - | | signature | Buffer | - |

Returns: Promise<boolean>

<Static> fromB64

▸ fromB64(b64DERFormattedPublicKey: string): PublicKey

Instantiates a PublicKey from a base64 representation of an RSA public key using ASN.1 syntax with DER encoding per PKCS#1 v2.2 specification and optionally wrapped in an SPKI enveloppe as per RFC 5280.

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

PrivateKey constructor. Should be given a Buffer either encoded in a PKCS#8 enveloppe or as a bare private key representation using ASN.1 syntax with DER encoding.

constructs: PrivateKey

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | key | Buffer | |

Returns: PrivateKey

Properties

Readonly privateKeyBuffer

● privateKeyBuffer: Buffer

Readonly publicKeyBuffer

● publicKeyBuffer: Buffer

Inherited from PublicKey.publicKeyBuffer

Methods

decrypt

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

Decrypts the given cipherText synchronously with RSAES-OAEP-DECRYPT as per PKCS#1 v2.2 section 7.1.2 using the instantiated PrivateKey, and optionally checks that the result is prefixed with a valid CRC32.

Parameters:

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

Returns: Buffer

decryptAsync

▸ decryptAsync(cipherText: Buffer, doCRC?: boolean): Promise<Buffer>

Decrypts the given cipherText asynchronously with RSAES-OAEP-DECRYPT as per PKCS#1 v2.2 section 7.1.2 using the instantiated PrivateKey, and optionally checks that the result is prefixed with a valid CRC32.

Parameters:

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

Returns: Promise<Buffer>

encrypt

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

Inherited from PublicKey.encrypt

Optionally prefixes the cleartext with a CRC32 of the initial clearText then, encrypts the result synchronously with RSAES-OAEP-ENCRYPT with SHA-1 as a Hash function and MGF1-SHA-1 as a mask generation function as per PKCS#1 v2.2 section 7.1.1 using the instantiated PublicKey

Parameters:

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

Returns: Buffer

encryptAsync

▸ encryptAsync(clearText: Buffer, doCRC?: boolean): Promise<Buffer>

Inherited from PublicKey.encryptAsync

Optionally prefixes the cleartext with a CRC32 of the initial clearText then, encrypts the result asynchronously with RSAES-OAEP-ENCRYPT with SHA-1 as a Hash function and MGF1-SHA-1 as a mask generation function as per PKCS#1 v2.2 section 7.1.1 using the instantiated PublicKey

Parameters:

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

Returns: Promise<Buffer>

getHash

▸ getHash(): string

Inherited from PublicKey.getHash

Gives a SHA-256 hash encoded in base64 of the RSA PublicKey encoded in base64 using ASN.1 syntax with DER encoding wrapped in an SPKI enveloppe as per RFC 5280, and encoded per PKCS#1 v2.2 specification

Returns: string

sign

▸ sign(textToSign: Buffer): Buffer

Generates synchronously a signature for the given textToSign using RSASSA-PSS-Sign which itself uses EMSA-PSS encoding with SHA-256 as the Hash function and MGF1-SHA-256, and a salt length sLen of Math.ceil((keySizeInBits - 1)/8) - digestSizeInBytes - 2 as per PKCS#1 v2.2 section 8.1.1 using instantiated PrivateKey.

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | textToSign | Buffer | - |

Returns: Buffer

signAsync

▸ signAsync(textToSign: Buffer): Promise‹Buffer›

Generates asynchronously a signature for the given textToSign using RSASSA-PSS-Sign which itself uses EMSA-PSS encoding with SHA-256 as the Hash function and MGF1-SHA-256, and a salt length sLen of Math.ceil((keySizeInBits - 1)/8) - digestSizeInBytes - 2 as per PKCS#1 v2.2 section 8.1.1 using instantiated PrivateKey.

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | textToSign | Buffer | - |

Returns: Promise‹Buffer›

toB64

▸ toB64(__namedParameters?: object): string

Overrides PublicKey.toB64

Exports the instance of an RSA PrivateKey in base64 using ASN.1 syntax with DER encoding wrapped in a PKCS#8 enveloppe as per RFC 5958, and encoded per PKCS#1 v2.2 specification. If publicOnly is specified, it exports the RSA PublicKey in base64 using ASN.1 syntax with DER encoding wrapped in an SPKI enveloppe as per RFC 5280, and encoded per PKCS#1 v2.2 specification.

Parameters:

Default value __namedParameters: object

| Name | Type | Default value | | ------ | ------ | ------ | | publicOnly | boolean | false |

Returns: string

toString

▸ toString(__namedParameters?: object): string

Overrides PublicKey.toB64

Exports the instance of an RSA PrivateKey in binary string using ASN.1 syntax with DER encoding wrapped in a PKCS#8 enveloppe as per RFC 5958, and encoded per PKCS#1 v2.2 specification. If publicOnly is specified, it exports the RSA PublicKey in binary string using ASN.1 syntax with DER encoding wrapped in an SPKI enveloppe as per RFC 5280, and encoded per PKCS#1 v2.2 specification.

deprecated

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

Verifies synchronously that the given signature is valid for textToCheckAgainst using RSASSA-PSS-VERIFY which itself uses EMSA-PSS encoding with SHA-256 as the Hash function and MGF1-SHA-256, and a salt length sLen of Math.ceil((keySizeInBits - 1)/8) - digestSizeInBytes - 2 as per PKCS#1 v2.2 section 8.1.2 using instantiated PublicKey.

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | textToCheckAgainst | Buffer | - | | signature | Buffer | - |

Returns: boolean

verifyAsync

▸ verifyAsync(textToCheckAgainst: Buffer, signature: Buffer): Promise‹boolean›

Inherited from PublicKey.verify

Verifies asynchronously that the given signature is valid for textToCheckAgainst using RSASSA-PSS-VERIFY which itself uses EMSA-PSS encoding with SHA-256 as the Hash function and MGF1-SHA-256, and a salt length sLen of Math.ceil((keySizeInBits - 1)/8) - digestSizeInBytes - 2 as per PKCS#1 v2.2 section 8.1.2 using instantiated PublicKey.

Parameters:

| Name | Type | Description | | ------ | ------ | ------ | | textToCheckAgainst | Buffer | - | | signature | Buffer | - |

Returns: Promise‹boolean›

<Static> fromB64

▸ fromB64(b64DERFormattedPrivateKey: string): PrivateKey

Overrides PublicKey.fromB64

Instantiates a PrivateKey from a base64 ASN.1 syntax with DER encoding wrapped in a PKCS#8 enveloppe as per RFC 5958, and encoded per PKCS#1 v2.2 specification.

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 asynchronously an RSA Private Key Key and instantiates it.

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

Parameters:

| Name | Type | Default value | | ------ | ------ | ------ | | size | AsymKeySize | 4096 |

Returns: Promise<PrivateKey>

<Static> [Symbol.hasInstance]

▸ [Symbol.hasInstance](instance: unknown): boolean

Returns true if instance is PrivateKey. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance

| Name | Type | Description | | ------ | ------ | ------ | | instance | unknown | - |

Returns: boolean

Utils

randomBytes

▸ randomBytes(length?: number): Buffer

Returns a Buffer of random bytes synchronously

Parameters:

| Name | Type | Default value | | ------ | ------ | ------ | | length | number | 10 |

Returns: Buffer

randomBytesAsync

▸ randomBytesAsync(length?: number): Promise<Buffer>

Returns a Buffer of random bytes asynchronously

Parameters:

| Name | Type | Default value | | ------ | ------ | ------ | | length | number | 10 |

Returns: Promise<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