@alessiofrittoli/crypto-signature

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

Parameter	Type	Default	Description
data	CoerceToUint8ArrayInput	-	The data to be signed.
key	Sign.PrivateKey	-	The private key used for signing. This can be a symmetric key, PEM private key or a key object.
algorithm	Sign.AlgorithmJwkName	HS256	The JWK algorithm name.

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

Parameter	Type	Default	Description
signature	CoerceToUint8ArrayInput	-	The signature to verify.
data	CoerceToUint8ArrayInput	-	The original data that was signed.
key	Sign.PublicKey	-	The public key used for verification. This can be a symmetric key, PEM public key or a key object.
algorithm	Sign.AlgorithmJwkName	HS256	The JWK algorithm name.

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:

Type	JWK name	Description
HMAC
	HS1	Signature generated/verified with HMAC key and SHA-1.
	HS256	Signature generated/verified with HMAC key and SHA-256.
	HS384	Signature generated/verified with HMAC key and SHA-384.
	HS512	Signature generated/verified with HMAC key and SHA-512.
DSA
	DS1	Signature generated/verified with DSA keys and SHA-1.
	DS256	Signature generated/verified with DSA keys and SHA-256.
	DS384	Signature generated/verified with DSA keys and SHA-384.
	DS512	Signature generated/verified with DSA keys and SHA-512.
EcDSA
	ES256	Signature generated/verified with EC keys and SHA-256.
	ES384	Signature generated/verified with EC keys and SHA-384.
	ES512	Signature generated/verified with EC keys and SHA-512.
EdDSA
	EdDSA	Signature generated/verified with ed448 keys.
	EdDSA	Signature generated/verified with ed25519 keys.
RSA
	RS1	Signature generated/verified with RSA keys and SHA-1.
	RS256	Signature generated/verified with RSA keys and SHA-256.
	RS384	Signature generated/verified with RSA keys and SHA-384.
	RS512	Signature generated/verified with RSA keys and SHA-512.
RSASSA-PSS
	PS256	Signature generated/verified with RSASSA-PSS keys and SHA-256.
	PS384	Signature generated/verified with RSASSA-PSS keys and SHA-384.
	PS512	Signature generated/verified with RSASSA-PSS keys and SHA-512.

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.

`ErrorCode` enum

Constant	Description
UNKNOWN	Thrown when:
	- Signature.sign() encounters an unexpected error while creating a signature (mostly due to unsupported routine). The original thrown error is being reported in the Exception.cause property.
	- Signature.isValid() encounters an unexpected error while verifying a signature (mostly due to unsupported routine). The original thrown error is being reported in the Exception.cause property.
EMPTY_VALUE	Thrown when:
	Signature.sign() has no data to sign.
	Signature.isValid() has no data to verify.
INVALID_SIGN	Thrown when Signature.isValid() encounter an invalid signature (altered data, altered signature, wrong PublicKey).
NO_SIGN	Thrown when Signature.isValid() has no signature to verify.
NO_PRIVATEKEY	Thrown when Signature.sign() has no Private Key to sign with.
NO_PUBLICKEY	Thrown when Signature.isValid() has no Public Key to verify the signature with.

Example usage

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 [e-mail] to disclose any security vulnerabilities.

Made with ☕

Alessio Frittoli https://alessiofrittoli.it | [e-mail]