Class HqcAlgorithm

java.lang.Object

zeroecho.core.CryptoAlgorithm

zeroecho.core.alg.AbstractCryptoAlgorithm

zeroecho.core.alg.hqc.HqcAlgorithm

public final class HqcAlgorithm
extends AbstractCryptoAlgorithm

HQC (Hamming Quasi-Cyclic) Algorithm Integration

Concrete CryptoAlgorithm implementation for the post-quantum key encapsulation mechanism (KEM) HQC, as defined in the NIST PQC standardization process.

HQC is based on error-correcting codes and offers IND-CCA2 security against quantum adversaries. This implementation delegates to the BouncyCastlePQCProvider for actual cryptographic operations and exposes HQC through the unified CryptoAlgorithm API surface.

Declared capabilities

• AlgorithmFamily.KEM:
  • KeyUsage.ENCAPSULATE with a PublicKey, returning a KemContext.
  • KeyUsage.DECAPSULATE with a PrivateKey, returning a KemContext.
• AlgorithmFamily.AGREEMENT (message-based):
  • Initiator: given recipient's PublicKey, wraps an HQC KEM context in a KemMessageAgreementAdapter.
  • Responder: given own PrivateKey, wraps an HQC KEM context in a KemMessageAgreementAdapter.

Key builders

• HqcKeyGenSpec: supports generation of key pairs for the HQC-128, HQC-192, and HQC-256 parameter sets, via BouncyCastle's KeyPairGenerator.
• HqcPublicKeySpec: supports import of HQC public keys from X.509-encoded form.
• HqcPrivateKeySpec: supports import of HQC private keys from PKCS#8-encoded form.

Provider dependency

All operations require the Bouncy Castle PQC provider (BouncyCastlePQCProvider) to be registered in Security. The private helper ensureProvider() validates provider availability before key generation or import.

Thread-safety

Instances of HqcAlgorithm are immutable and safe to share. Contexts created via capabilities (e.g., KemContext, MessageAgreementContext) are not necessarily thread-safe.

Usage example

// Generate an HQC key pair
HqcAlgorithm hqc = new HqcAlgorithm();
KeyPair kp = hqc.asymmetricKeyPairGenerator(HqcKeyGenSpec.class)
                 .generateKeyPair(HqcKeyGenSpec.hqc256());

// Encapsulation by initiator
KemContext encapsCtx = hqc.createContext(KeyUsage.ENCAPSULATE, kp.getPublic(), VoidSpec.INSTANCE);

// Decapsulation by responder
KemContext decapsCtx = hqc.createContext(KeyUsage.DECAPSULATE, kp.getPrivate(), VoidSpec.INSTANCE);

Since:

1.0

Constructor Summary

Constructors

Constructor	Description
HqcAlgorithm()	Constructs and registers the HQC algorithm with the BouncyCastle PQC provider.

Method Summary

Modifier and Type	Method	Description
List<ParameterSetDescriptor<? extends AlgorithmKeySpec>>	parameterSets()	Returns the discoverable parameter sets (or parameterized templates) supported by this algorithm.

Methods inherited from class AbstractCryptoAlgorithm

capability

Methods inherited from class CryptoAlgorithm

addCapability, asymmetricKeyPairGenerator, bindContext, createContext, displayName, id, keyOperations, listCapabilities, priority, privateKeyImporter, providerName, publicKeyImporter, registerAsymmetricKeyPairGenerator, registerPrivateKeyImporter, registerPublicKeyImporter, registerSymmetricKeyGenerator, registerSymmetricKeyImporter, requiresStatefulSigning, roles, supports, symmetricKeyGenerator, symmetricKeyImporter

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

HqcAlgorithm

public HqcAlgorithm()

Constructs and registers the HQC algorithm with the BouncyCastle PQC provider.

During construction this algorithm:

• Registers KEM encapsulation/decapsulation capabilities bound to PublicKey and PrivateKey respectively.
• Registers message-based agreement roles (initiator/responder) using KemMessageAgreementAdapter wrappers.
• Registers asymmetric key builders for:
  • HqcKeyGenSpec (for fresh key generation),
  • HqcPublicKeySpec (for importing X.509 public keys),
  • HqcPrivateKeySpec (for importing PKCS#8 private keys).

The default key generation spec is HqcKeyGenSpec.hqc256(), corresponding to the HQC-256 parameter set.

Throws:

IllegalStateException - if BouncyCastle PQC provider is missing at runtime

Method Details

parameterSets

public List<ParameterSetDescriptor<? extends AlgorithmKeySpec>> parameterSets()

Description copied from class: CryptoAlgorithm

Returns the discoverable parameter sets (or parameterized templates) supported by this algorithm.

Callers (UIs, provisioning tools, policy engines) use this list to present users with valid, named key-generation options without prior knowledge of the concrete algorithm. Each entry is either a pre-built ParameterSetDescriptor.Concrete (ready spec) or a ParameterSetDescriptor.Template (user-supplied arguments produce the spec).

The default implementation returns an empty list. Algorithms with finite, enumerable parameter sets should override this method. Overrides must return immutable lists in stable order, with unique nonblank descriptor identifiers. Registry loading validates a snapshot; external providers remain responsible for maintaining the contract on subsequent calls. Implementations may use ParameterSetDescriptor.snapshot(List) to validate and copy their list.

Overrides:

parameterSets in class CryptoAlgorithm

Returns:

immutable list of parameter set descriptors; never null