Skip to content

seald/sscrypto

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

SSCrypto

npm version

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:

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