@alessiofrittoli/crypto-signature v2.3.0

Crypto Signature 🔏

Lightweight TypeScript Signatures library

This documentation provides an overview of the Digital Signature module and demonstrates how to use its methods for creating and verifying digital signatures.

Table of Contents

• Getting started
  • Usage
  • Creating a Digital Signature
  • Verifying a Digital Signature
  • Supported Algorithms
  • Error Handling
• Development
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Overview

The module supports multiple algorithms for signing and verifying data, including HMAC, RSA, RSASSA-PSS, DSA, EcDSA and EdDSA. It provides a synchronous interface for cryptographic operations using Node.js's crypto module and custom utility classes.

Getting started

Run the following command to start using crypto-signature in your projects:

npm i @alessiofrittoli/crypto-signature

or using pnpm

pnpm i @alessiofrittoli/crypto-signature

Usage

Importing the Module

import { Signature } from '@alessiofrittoli/crypto-signature'
import type { Sign } from '@alessiofrittoli/crypto-signature'
// or
import type { Sign } from '@alessiofrittoli/crypto-signature/types'

Creating a Digital Signature

The Signature.sign() method generates a signature for a given data input using a specified algorithm and private key.

Parameters

Returns

Type: Buffer

The generated signature Node.js Buffer.

Example

const data		= 'This is the data to sign'
const key		= crypto.createSecretKey( Buffer.from( 'your-secret-key' ) )
const algorithm	= 'HS256'

try {
    const signature = Signature.sign( data, key, algorithm )
    console.log( 'Generated Signature:', signature.toString( 'hex' ) )
} catch ( error ) {
    console.error( 'Error generating signature:', error )
}

Verifying a Digital Signature

The Signature.isValid() method verifies the integrity and authenticity of a digital signature.

Parameters

Returns

Type: true

Returns true if the signature is valid. Throws an exception otherwise.

Example

const signature	= Buffer.from( 'signature-in-hex', 'hex' )
const data		= 'This is the data to verify'
const key		= crypto.createSecretKey( Buffer.from( 'your-secret-key' ) )
const algorithm	= 'HS256'

try {
    const isValid = Signature.isValid( signature, data, key, algorithm )
    console.log( 'Signature is valid:', isValid )
} catch ( error ) {
    console.error( 'Error verifying signature:', error )
}

Supported Algorithms

The module supports the following algorithms:

Error handling

This module throws a new Exception when an error occures providing an error code that will help in error handling.

The ErrorCode enumerator can be used to handle different errors with ease.

import { Exception } from '@alessiofrittoli/exception'
import { Signature } from '@alessiofrittoli/crypto-signature'
import { ErrorCode } from '@alessiofrittoli/crypto-signature/error'

try {
    Signature.isValid( 'invalid signature', 'Data', 'myscretkey' )
} catch ( error ) {
    console.log( error )
    // safe type guard the `error` variable.
    if ( Exception.isException<string, ErrorCode>( error ) ) {
        // ... do somethign with `error.code`
        if ( error.code === ErrorCode.Signature.INVALID_SIGN ) {
            // ...
        }
    }
}

This documentation covers the essential functionality of the module, allowing users to securely sign and verify data using various cryptographic algorithms.

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

• See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email security@alessiofrittoli.it to disclose any security vulnerabilities.

Made with ☕