SM2 Multikey Library

A comprehensive implementation of the SM2 cryptographic algorithm with multikey support, designed for both Node.js and browser environments.

Overview

The SM2 Multikey library provides a complete implementation of the SM2 cryptographic algorithm with support for the W3C Multikey format. It is specifically designed for:

Verifiable Credentials: Create and verify digital credentials using SM2 signatures
Digital Signatures: Generate and verify SM2 signatures with SM3 digest
Key Management: Handle SM2 key pairs in multiple formats
Data Integrity: Create and verify Data Integrity Proofs
Cross-Platform: Consistent API across Node.js and browser environments

The library implements a pluggable architecture that allows for platform-specific optimizations while maintaining a consistent API. In Node.js environments, it leverages native crypto implementations for optimal performance, while in browsers it uses a pure JavaScript implementation.

Features

Cryptographic Operations

SM2 key pair generation with secure defaults
Digital signature creation and verification
SM3 message digest calculation
Support for compressed public keys

Key Management

Multiple key format support:
- JSON Web Key (JWK)
- W3C Multikey format
- Support for key compression
Secure key import/export operations
Key format validation and error handling

Standards Integration

W3C Data Integrity Proofs compatibility
Verifiable Credentials support
Document canonicalization (URDNA2015)
Cross-platform compatibility

Security

Memory-safe key operations
Protected private key handling
Comprehensive input validation
Proper error handling

Standards Compliance

Cryptographic Standards

GB/T 32918.1-2016: SM2 Elliptic Curve Cryptography
- Key generation and management
- Digital signature algorithms
- Public key encryption
GB/T 32905-2016: SM3 Cryptographic Hash Algorithm
- Message digest calculation
- Data integrity verification

W3C Standards

Data Integrity 1.0
- Proof creation and verification
- Document canonicalization
- Signature suite implementation
Verifiable Credentials
- Credential issuance and verification
- Proof format compatibility
- Multikey format support

Additional Standards

RDF Dataset Normalization 1.0
- Deterministic document canonicalization
- URDNA2015 algorithm implementation

Installation

npm install @instun/sm2-multikey

Usage

Basic Key Operations

import { SM2Multikey, cryptosuite } from '@instun/sm2-multikey';

// Generate a new key pair
const key = await SM2Multikey.generate({
  controller: 'did:example:123'
});

// Create and verify signatures
const signer = key.signer();
const signature = await signer.sign({ data });
const isValid = await key.verifier().verify({ data, signature });

Data Integrity Integration

const suite = {
  ...cryptosuite,
  signer: () => key.signer(),
  verifier: () => key.verifier()
};

Key Export/Import

// Export key
const exported = key.export({
  publicKey: true,
  secretKey: false,
  includeContext: true
});

// Import from JWK
const imported = SM2Multikey.fromJwk({
  jwk,
  id: 'key-1',
  controller: 'did:example:123'
});

Platform Requirements

Node.js 16.x or later
OpenSSL 1.1.1 or later with SM2 support
Modern browsers with ES6+ support

Security Features

Protected private key operations
Key format validation
Secure key generation
Proper error handling

API Documentation

SM2Multikey Class

Core class for SM2 key pair operations.

Static Methods

generate(options)

Creates a new SM2 key pair.

Parameters:
- options (Object, optional)
  - id (string): Key identifier
  - controller (string): Controller identifier
Returns: SM2Multikey instance
Throws:
- ArgumentError: If options are invalid
- KeyError: If key generation fails
- FormatError: If key encoding fails

from(key)

Imports a key from Multikey format.

Parameters:
- key (Object): Multikey formatted key data
Returns: SM2Multikey instance
Throws:
- ArgumentError: If key object is invalid
- FormatError: If key format is invalid

fromJwk(options)

Imports a key from JWK format.

Parameters:
- options (Object)
  - jwk (Object): JWK key data
  - secretKey (boolean, optional): Whether to import private key
  - id (string, optional): Key identifier
  - controller (string, optional): Controller identifier
Returns: SM2Multikey instance
Throws:
- ArgumentError: If JWK is invalid
- FormatError: If JWK format is incorrect

Instance Methods

export(options)

Exports the key pair in specified format.

Parameters:
- options (Object, optional)
  - publicKey (boolean): Export public key (default: true)
  - secretKey (boolean): Export private key (default: false)
  - includeContext (boolean): Include @context field (default: false)
  - raw (boolean): Export in raw format (default: false)
  - canonicalize (boolean): Sort properties (default: false)
Returns: Exported key object
Throws:
- ArgumentError: If options are invalid
- KeyError: If required key is not available

signer()

Creates a signing function for this key pair.

Returns: Object with properties:
- algorithm (string): 'SM2'
- id (string): Key identifier
- sign (Function): Signing function
  - Parameters:
    - data (Buffer|Uint8Array): Data to sign
  - Returns: Promise Signature
Throws: KeyError if private key is not available

verifier()

Creates a verification function for this key pair.

Returns: Object with properties:
- algorithm (string): 'SM2'
- id (string): Key identifier
- verify (Function): Verification function
  - Parameters:
    - data (Buffer|Uint8Array): Original data
    - signature (Buffer|Uint8Array): Signature to verify
  - Returns: Promise Verification result
Throws: KeyError if public key is not available

Cryptographic Suite

Implementation of the SM2 2023 cryptographic suite for Data Integrity.

Properties

name (string): 'sm2-2023'
requiredAlgorithm (string): 'SM2'

Methods

canonize(input, options)

Canonicalizes a JSON-LD document.

Parameters:
- input (Object|string): JSON-LD document
- options (Object, optional): Canonicalization options
  - algorithm (string): Canonicalization algorithm (default: 'URDNA2015')
  - format (string): Output format (default: 'application/n-quads')
Returns: Promise Canonicalized N-Quads string
Throws: JsonLdError if canonicalization fails

createVerifier(options)

Creates a verifier for SM2 signatures.

Parameters:
- options (Object)
  - verificationMethod (Object): Verification method object
    - Must contain valid SM2 public key data
    - Must specify key format (JWK or Multikey)
Returns: Verifier object with verify() method
Throws: Error if verification method is invalid

Error Types

The library provides several error types for specific failure cases:

ArgumentError

Thrown when an invalid argument is provided.

Properties:
- message: Error description
- code: Error code (ERR_ARGUMENT_INVALID)
- argument: Name of the invalid argument

KeyError

Thrown when a key operation fails.

Properties:
- message: Error description
- code: Error code (ERR_KEY_*)
- operation: Failed operation name

FormatError

Thrown when a format conversion fails.

Properties:
- message: Error description
- code: Error code (ERR_FORMAT_*)
- format: Name of the problematic format

SM2Error

Base class for SM2-specific errors.

Properties:
- message: Error description
- code: Error code
- cause: Original error (if any)

Each error includes:

Descriptive error message
Specific error code for programmatic handling
Original error cause when applicable
Additional context-specific properties

@instun/sm2-multikey