Skip to content

seald/sscrypto

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

141 Commits
src
src
 
 
.eslintrc.js
.eslintrc.js
 
 
.gitignore
.gitignore
 
 
.gitlab-ci.yml
.gitlab-ci.yml
 
 
.ncurc.json
.ncurc.json
 
 
.npmignore
.npmignore
 
 
CHANGELOG.md
CHANGELOG.md
 
 
README.md
README.md
 
 
README_DEV.md
README_DEV.md
 
 
browsers.js
browsers.js
 
 
check_readme.sh
check_readme.sh
 
 
karma.conf.local.js
karma.conf.local.js
 
 
karma.conf.saucelabs.js
karma.conf.saucelabs.js
 
 
karma.conf.template.js
karma.conf.template.js
 
 
mochaReportConfig.json
mochaReportConfig.json
 
 
nyc.config.js
nyc.config.js
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
run-karma-saucelabs.spec.js
run-karma-saucelabs.spec.js
 
 
saucelabs-tunnel-utils.spec.js
saucelabs-tunnel-utils.spec.js
 
 
tsconfig.json
tsconfig.json
 
 
webpack.config.js
webpack.config.js
 
 

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

About

Super Simple Cryptography

Topics

nodejs javascript browser crypto hacktoberfest

Resources

Readme
Activity
Custom properties

Stars

6 stars

Watchers

3 watching

Forks

1 fork
Report repository

Releases

25 tags

Packages

No packages published

Languages