README.md

@signumjs/crypto

Cryptographic functions for building Signum apps.

Installation

SignumJS can be used with NodeJS or Web. Two formats are available

Using with NodeJS and/or modern web frameworks

Install using npm:

npm install @signumjs/crypto

or using yarn:

yarn add @signumjs/crypto

Example

import {sha256AsHex, Crypto, NodeJSCryptoProvider} from '@signumjs/crypto'

Crypto.init(new NodeJSCryptoProvider()); // or WebCryptoProvider
console.log(sha256AsHex('test'))

Using in classic <script>

Each package is available as bundled standalone library using UMD. This way signumJS can be used also within <script>-Tags. This might be useful for Wordpress and/or other PHP applications.

Just import the package using the HTML <script> tag.

<script src='https://cdn.jsdelivr.net/npm/@signumjs/crypto/dist/signumjs.crypto.min.js'></script>

Example

console.log(sig$crypto.sha256AsHex('test'))

The "legacy" web bundle initializes the Crypto module automatically with the WebCryptoAdapter. So, no initialization is necessary.

See more here: @signumjs/crypto Online Documentation

Crossplatform Usage

As there are different crypto implementations for different platforms available the underlying crypto contexts need to be initialized. The crypto package provides used out of the box implementations for modern web browsers and NodeJS (and alike backends, i.e. deno and bun). Depending on the runtime environment the correct CryptoAdapter-implementation needs to be set for cryptographic routines. In a web browser the Crypto Web API is used, i.e. a secure (https) environment is required. In NodeJS the NodeJS Crypto API is used.

Run the following before any usage of crypto functions

Web

import {Crypto, WebCryptoAdapter} from "@signumjs/crypto"
Crypto.init(new WebCryptoAdapter());

NodeJS (Deno, Bun)

import {Crypto, NodeJSCryptoAdapter} from "@signumjs/crypto"
Crypto.init(new NodeJSCryptoAdapter());

For web localhost is considered a secure context

If using signumjs.crypto.min.js the initialization is not required. It is automatically set to WebCryptoAdapter

Implementing CryptoAdapter-Interface

If needed in other environments, e.g. React Native, a custom implementation of the CryptoAdapter interface is required. The interface implements the bare minimum crypto functions needed for Signum:

export interface CryptoAdapter {
    encryptAes256Cbc(plaintext: Uint8Array, key: Uint8Array): Promise<Uint8Array>;

    decryptAes256Cbc(ciphertext: Uint8Array, key: Uint8Array): Promise<Uint8Array>;

    sha256(data: ArrayBuffer): Promise<Uint8Array>;

    getRandomValues(array: Uint8Array): Uint8Array;
}

Like this:

import {type CryptoAdapter} from '@signumjs/crypto'

class CustomCryptoAdapter implements CryptoAdapter {
    decryptAes256Cbc(ciphertext: Uint8Array, key: Uint8Array): Promise<Uint8Array> {
        // Do your platforms implementation here
        return Promise.resolve(undefined);
    }

    encryptAes256Cbc(plaintext: Uint8Array, key: Uint8Array): Promise<Uint8Array> {
        // Do your platforms implementation here
        return Promise.resolve(undefined);
    }

    getRandomValues(array: Uint8Array): Uint8Array {
        // Do your platforms implementation here
        return undefined;
    }

    sha256(data: ArrayBuffer): Uint8Array {
        // Do your platforms implementation here
        return undefined;
    }

}

Then use the custom crypto provider like this:

import {Crypto, sha256AsHex} from '@signumjs/crypto'

Crypto.init(new CustomCryptoAdapter());

(async ()=> {
    // internally uses the custom crypto provider
    console.log("SHA256", await sha256AsHex("blablubb"))
})()