Crypto Signature 🔏

Version 1.2.1

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.

| 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. |

import Exception from '@alessiofrittoli/exception'
import Signature from '@alessiofrittoli/crypto-jwt'
import { ErrorCode } from '@alessiofrittoli/crypto-jwt/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.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 source code

Run the following command to 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

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

You can eventually run specific suits like so:

pnpm test:jest
pnpm test:signature
pnpm test:verify

Contributing

Contributions are truly welcome!
Please refer to the Contributing Doc for more information on how to start contributing to this project.

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

Made with ☕