Nourishing Pizza Microservice

    sscrypto
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published

    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


    Keywords

    none

    Install

    npm i sscrypto

    DownloadsWeekly Downloads

    32

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    141 kB

    Total Files

    37

    Last publish

    Collaborators

    • tex0l
    • seald
    • arantes