Documentation: Signature generation and verification

This module offers utility functions for creating and verifying detached signatures with additional context information to ensure data integrity and authenticity.

Importing the Module

import {
  SignatureContext,
  AdditionalContext,
  verifyDetachedSignatureAsymmetric,
  createDetachedSignatureAsymmetric
} from '@skiff-org/skiff-crypto';

Overview

This module offers utility functions for creating and verifying detached signatures with additional context information to ensure data integrity and authenticity. The module utilizes the tweetnacl library for cryptographic operations and base64-js for Base64 encoding and decoding.

Dependencies

• base64-js: Convert between binary data and Base64 encoded strings.
• ./utf8: UTF-8 utility module for encoding and decoding strings.
• tweetnacl: Cryptographic operations.

Enums

AdditionalContext

This enum represents the additional context that can be used to qualify the nature of the signature.

export enum AdditionalContext {
  LastChunk,
  NotLastChunk,
  NoContext
  // ...
}

SignatureContext

This enum lists various contexts under which a signature can be created or verified. This context can include different types of data like document metadata, user data, or email content.

export enum SignatureContext {
  DeleteAccount,
  DeleteDoc,
  DeleteRecoveryData,
  // ...
}

Functions

verifyDetachedSignatureAsymmetric

• Description: Verifies the authenticity of a detached signature for a given message, using the provided signing public key and contexts.
• Parameters:
  • message: string - The message used to verify the signature.
  • signature: string - The detached signature to verify.
  • signingPublicKey: string - The signing public key used to verify the signature.
  • context: SignatureContext - The primary context of the signature.
  • additionalContext?: AdditionalContext - An optional additional context for the signature.
• Returns: boolean - true if the signature is valid, false otherwise.

createDetachedSignatureAsymmetric

• Description: Creates a detached signature for a given message using the provided signing private key and contexts.
• Parameters:
  • message: string - The message to sign.
  • signingPrivateKey: string - The signing private key used to create the signature.
  • context: SignatureContext - The primary context of the signature.
  • additionalContext?: AdditionalContext - An optional additional context for the signature.
• Returns: string - The detached signature.

Examples

Creating a Detached Signature

import { createDetachedSignatureAsymmetric, SignatureContext } from '@skiff-org/skiff-crypto';

const message = 'This is a test message.';
const signingPrivateKey = 'base64_encoded_signing_private_key';

const signature = createDetachedSignatureAsymmetric(
  message,
  signingPrivateKey,
  SignatureContext.DocumentData
);

console.log(`Detached signature: ${signature}`);

Verifying a Detached Signature

import { verifyDetachedSignatureAsymmetric, SignatureContext } from '@skiff-org/skiff-crypto';

const message = 'This is a test message.';
const signature = 'base64_encoded_detached_signature';
const signingPublicKey = 'base64_encoded_signing_public_key';

const isValid = verifyDetachedSignatureAsymmetric(
  message,
  signature,
  signingPublicKey,
  SignatureContext.DocumentData
);

console.log(`Is the signature valid? ${isValid}`);

Please use this module responsibly and make sure you are adhering to security best practices when handling cryptographic keys and signatures.