HSM Service

Hardware Security Module Backend Service specification.

Overview

The HSM Backend is an internal microservice that handles all cryptographic operations:

• Certificate generation
• Document signing (PKCS#7)
• Certificate validation
• Key management

Internal Only

The HSM service is only accessible from within the Docker network. It cannot be accessed from the public internet.

Architecture

┌─────────────────────────────────────────┐
│           GSign Backend                  │
│        (Public-facing API)              │
└──────────────┬──────────────────────────┘
               │
               │ HTTP (internal network)
               │
┌──────────────▼──────────────────────────┐
│           HSM Backend                    │
│     (Internal microservice)             │
│                                         │
│  • Certificate generation               │
│  • Document signing                     │
│  • Certificate validation               │
│  • Key storage (encrypted)              │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│        PostgreSQL (hsm)                 │
│     (Separate database)                 │
└─────────────────────────────────────────┘

API Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0"
}

Generate Certificate

POST /api/v1/certificates/generate
Authorization: X-API-Key: <internal-api-key>

Request:

{
  "common_name": "John Doe",
  "email": "john@example.com",
  "organization": "Example Corp",
  "validity_days": 365,
  "key_type": "RSA",
  "key_size": 2048
}

Response:

{
  "success": true,
  "data": {
    "certificate_id": "uuid",
    "serial_number": "123456",
    "public_key": "-----BEGIN CERTIFICATE-----...",
    "valid_from": "2026-01-24T00:00:00Z",
    "valid_to": "2027-01-24T00:00:00Z"
  }
}

Sign Document

POST /api/v1/sign
Authorization: X-API-Key: <internal-api-key>

Request:

{
  "certificate_id": "uuid",
  "document_hash": "sha256:abcd1234...",
  "pin": "1234"
}

Response:

{
  "success": true,
  "data": {
    "signature": "base64-encoded-pkcs7-signature",
    "signed_at": "2026-01-24T10:00:00Z",
    "algorithm": "SHA256withRSA"
  }
}

Verify Signature

POST /api/v1/verify
Authorization: X-API-Key: <internal-api-key>

Request:

{
  "document_hash": "sha256:abcd1234...",
  "signature": "base64-encoded-pkcs7-signature"
}

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "signer": {
      "common_name": "John Doe",
      "email": "john@example.com"
    },
    "signed_at": "2026-01-24T10:00:00Z"
  }
}

List Certificates

GET /api/v1/certificates?user_id=<user_id>
Authorization: X-API-Key: <internal-api-key>

Revoke Certificate

POST /api/v1/certificates/{id}/revoke
Authorization: X-API-Key: <internal-api-key>

Configuration

Environment Variables

Variable	Description	Default
SERVER_PORT	HTTP port	8080
INTERNAL_API_KEY	Authentication key	(required)
DB_HOST	PostgreSQL host	gsign-postgres
DB_PORT	PostgreSQL port	5432
DB_USER	PostgreSQL user	gsign
DB_PASSWORD	PostgreSQL password	(required)
DB_NAME	Database name	hsm
REDIS_HOST	Redis host	gsign-redis
REDIS_PASSWORD	Redis password	(required)
KEY_ENCRYPTION_KEY	AES-256 key (32 bytes)	(required)
CA_COUNTRY	CA country code	MN
CA_ORGANIZATION	CA organization	GSign
CA_COMMON_NAME	CA common name	GSign HSM CA

Docker Deployment

gsign-hsm-backend:
  image: gsign/hsm-backend:latest
  container_name: gsign-hsm-backend
  networks:
    - gsign-network
  environment:
    - SERVER_PORT=8080
    - INTERNAL_API_KEY=${HSM_INTERNAL_API_KEY}
    - DB_HOST=gsign-postgres
    - DB_PASSWORD=${DB_PASSWORD}
    - REDIS_PASSWORD=${REDIS_PASSWORD}
    - KEY_ENCRYPTION_KEY=${KEY_ENCRYPTION_KEY}
  restart: unless-stopped

Security

Key Storage

• Private keys encrypted with AES-256-GCM
• Key encryption key (KEK) in environment variable
• KEK should be 32 bytes exactly
• Keys never transmitted in plaintext

Access Control

• Internal API key required for all requests
• Only accessible within Docker network
• No public endpoints

Audit Logging

All operations are logged:

• Certificate generation
• Signing operations
• Validation requests
• Failed attempts

Database Schema

-- HSM Database (separate from main)
CREATE TABLE certificates (
    id UUID PRIMARY KEY,
    user_id UUID NOT NULL,
    serial_number VARCHAR(100) UNIQUE,
    subject_cn VARCHAR(255),
    issuer_cn VARCHAR(255),
    public_key TEXT NOT NULL,
    private_key_encrypted TEXT NOT NULL,
    key_type VARCHAR(20) DEFAULT 'RSA',
    key_size INTEGER DEFAULT 2048,
    valid_from TIMESTAMPTZ NOT NULL,
    valid_to TIMESTAMPTZ NOT NULL,
    status VARCHAR(20) DEFAULT 'active',
    revoked_at TIMESTAMPTZ,
    revocation_reason TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE signing_operations (
    id UUID PRIMARY KEY,
    certificate_id UUID REFERENCES certificates(id),
    document_hash VARCHAR(100) NOT NULL,
    signature TEXT NOT NULL,
    algorithm VARCHAR(50) NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

Development Mode

For development, the HSM service can generate self-signed certificates without a real HSM device.

Production mode would integrate with an actual HSM device via PKCS#11 or vendor API.

# Environment variable
ENV=development  # Use software crypto
ENV=production   # Use HSM device