Secure Keystore

Secure Keystore is a remote key custody service for the EUDI wallet and for Wultra backend components. It keeps the private keys in an HSM operated by the wallet provider and signs on demand, so that no private key ever leaves the HSM in clear form.

Where to Start

• Backend integrators: Concepts and Architecture, then API General Principles.
• Wallet-app developers: PowerAuth Integration and EUDI Wallet Flows.
• Operators: System Requirements, HSM Setup and Docker Deployment.

Unfamiliar terms are explained in the Glossary.

Documentation

Overview

• Concepts and Architecture - what the keystore is, the five security concepts and the participants
• PowerAuth Integration - how a user request is authorized with the PowerAuth activation
• EUDI Wallet Flows - credential issuance and presentation
• Backend Key Storage - long-term keys of PowerAuth Server and diw-gateway in the HSM
• Comparison with the German Model - what is the same and what is different

API Reference

• API General Principles - conventions, authentication, envelope, error codes and types
• PowerAuth Unit API - /v1/pa
• EUDI API - /v1/eudi
• Backend Keys API - /v1/backend

Operations

• System Requirements - Java, database, HSM and PowerAuth Server
• Configuration Properties - environment variables, profiles, actuator
• Database Setup - Liquibase migrations and changeset rules
• Docker Deployment - migration and service images, hardening
• HSM Setup - tokens, resident keys, the wrapped-key format, Thales Luna
• Monitoring - health and info endpoints

Development

• Build and Test - requirements, Maven build, CVE scan, running locally
• SoftHSM2 Development Setup - tokens, test PKI, provisioning, mechanisms, CI

Reference

• Key Naming Conventions - labels, domains and storage modes of the HSM keys
• Glossary - terms and abbreviations

Technology

• Java 25, Spring Boot with Spring Modulith
• PKCS#11 through the Java Foreign Function & Memory (FFM) API
• PostgreSQL with Liquibase; the schema is in the Liquibase changelog
• SoftHSM2 for development and tests; a Thales Luna 7 HSM as the production target