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.

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

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>

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

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

Parameters:

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

Returns: Promise<Buffer>

getHash

▸ getHash(): string

Inherited from PublicKey.getHash

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

Parameters:

Name	Type	Description
textToCheckAgainst	`Buffer`	-
signature	`Buffer`	-

Returns: boolean

verifyAsync

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

Inherited from PublicKey.verify

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

sscrypto

SSCrypto

Table of Contents

Installation

For use with the nodeJS back-end:

For use with the forge back-end:

For use with the WebCrypto back-end:

Class: SymKey

Constructor

Properties

Readonly key

Readonly keySize

Methods

decrypt

decryptAsync

decryptStream

encrypt

encryptAsync

encryptStream

toB64

toString

<Static> fromB64

<Static> fromString

<Static> generate

Class: PublicKey

Hierarchy

Constructor

Properties

Readonly publicKeyBuffer

Methods

encrypt

encryptAsync

getHash

toB64

toString

verify

verifyAsync

<Static> fromB64

Class: PrivateKey

Hierarchy

Constructor

Properties

Readonly privateKeyBuffer

Readonly publicKeyBuffer

Methods

decrypt

decryptAsync

encrypt

encryptAsync

getHash

sign

signAsync

toB64

toString

verify

verifyAsync

<Static> fromB64

<Static> generate

<Static> [Symbol.hasInstance]

Utils

randomBytes

randomBytesAsync

sha256

Type aliases

SymKeySize

AsymKeySize

Dependents (8)

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`Readonly` key

`Readonly` keySize

`<Static>` fromB64

`<Static>` fromString

`<Static>` generate

`Readonly` publicKeyBuffer

`<Static>` fromB64

`Readonly` privateKeyBuffer

`Readonly` publicKeyBuffer

`<Static>` fromB64

`<Static>` generate

`<Static>` [Symbol.hasInstance]

Weekly Downloads