Class CryptoAlgorithm

java.lang.Object
zeroecho.core.CryptoAlgorithm
Direct Known Subclasses:
AbstractCryptoAlgorithm
public abstract class CryptoAlgorithm extends Object
Abstract base class for all cryptographic algorithm definitions in ZeroEcho.

A CryptoAlgorithm declares:

  • Metadata: an identifier, display name, provider, and priority.
  • Capabilities: declared features such as AEAD, streaming, or deterministic signatures.
  • Roles: supported KeyUsage operations (e.g., ENCRYPT, SIGN) bound to concrete CryptoContext constructors.
  • Key operations: exact generation and import capabilities.

Metadata

Each algorithm instance is uniquely identified by id(), a canonical string such as "AES/GCM/NOPADDING" or "Ed25519". A human-readable displayName() is provided for logs and diagnostics.

Capabilities

Algorithms may declare extra Capability flags that can be inspected by higher layers. This allows adaptive protocols to choose the right primitive (e.g., preferring AEAD over raw block ciphers).

Roles and contexts

Each algorithm may support multiple KeyUsage roles. For each role, the algorithm binds a key type, context type, and optional ContextSpec. When createContext(KeyUsage, Key, ContextSpec) is called:
  1. The binding for the role is located.
  2. The supplied key and spec are validated against the expected types.
  3. A new CryptoContext is constructed using the registered factory.

Key operations

Providers register generation and import operations independently. Lookup returns an interface that guarantees the requested operation.

Parameter sets

An algorithm may advertise named, discoverable key-generation configurations via parameterSets(). Each entry is either a ParameterSetDescriptor.Concrete (a ready-to-use spec with a fixed security level) or a ParameterSetDescriptor.Template (a parameterised family where the caller supplies named values and a factory produces the spec). Callers such as UIs, provisioning tools, and policy engines can enumerate these without prior knowledge of the concrete algorithm.

Provider model

Each algorithm belongs to a providerName, allowing multiple providers (e.g., JCA, BouncyCastle, ZeroEcho-native) to coexist. priority() can be used to prefer one provider over another when resolving duplicates.

Thread safety

CryptoAlgorithm instances are immutable once constructed and are safe to share across threads. The created CryptoContext instances, however, are not necessarily thread-safe.

Security note: Algorithms must enforce strong validation of keys and specs during registration and createContext(KeyUsage, Key, ContextSpec) to prevent downgrade or misuse attacks.

Since:
1.0

  • Constructor Details

    • CryptoAlgorithm

      protected CryptoAlgorithm(String id, String displayName)
      Create a new algorithm with default priority and provider.
      Parameters:
      id - unique canonical identifier
      displayName - human-readable name

    • CryptoAlgorithm

      protected CryptoAlgorithm(String id, String displayName, String providerName)
      Create a new algorithm with default priority and a named provider.
      Parameters:
      id - unique canonical identifier
      displayName - human-readable name
      providerName - provider or implementation source

    • CryptoAlgorithm

      protected CryptoAlgorithm(String id, String displayName, int priority, String providerName)
      Create a new algorithm with explicit metadata.
      Parameters:
      id - unique canonical identifier
      displayName - human-readable name
      priority - preference when multiple providers offer the same algorithm
      providerName - provider or implementation source

  • Method Details

    • id

      public final String id()
      Returns the canonical identifier of this algorithm.

      The identifier is a stable, implementation-independent string such as "AES/GCM/NOPADDING" or "Ed25519". It is suitable for persistence in configuration files, protocol negotiation, or audit logs.

      Unlike displayName(), the identifier is not localized and should be treated as a primary key across providers.

      Returns:
      canonical, provider-independent algorithm identifier

    • displayName

      public final String displayName()
      Returns a human-readable display name for this algorithm.

      This name is intended for logs, error messages, and user interfaces. Unlike id(), the display name may vary by provider and is not guaranteed to be stable across versions.

      Returns:
      human-friendly algorithm name

    • priority

      public int priority()
      Returns the priority of this algorithm within its provider.

      When multiple providers expose the same id(), the priority is used as a tiebreaker. Higher values indicate stronger preference.

      Priority values are advisory; applications may still override selection based on policy.

      Returns:
      numeric provider preference (higher means more preferred)

    • providerName

      public String providerName()
      Returns the provider that supplies this algorithm implementation.

      Typical values include "default", "JCA", "BouncyCastle", or a project-specific label.

      Provider names allow coexistence of multiple implementations of the same algorithm identifier.

      Returns:
      provider or implementation source name

    • addCapability

      protected final void addCapability(Capability capability)
      Adds a capability flag to this algorithm.

      Intended for use by concrete subclasses during construction to advertise features (e.g., AEAD support, deterministic signatures). Adding capabilities after publication is discouraged as callers may have already inspected them.

      Parameters:
      capability - non-null capability to add
      Throws:
      NullPointerException - if capability is null

    • listCapabilities

      public final List<Capability> listCapabilities()
      Returns an immutable view of the algorithm’s declared capabilities.
      Returns:
      unmodifiable list of capability flags

    • bindContext

      protected final <C extends CryptoContext, K extends Key, S extends ContextSpec> void bindContext(KeyUsage role, Class<C> ctxType, Class<K> keyType, Class<S> specType, ContextFactoryKS<C,K,S> factory, Supplier<? extends S> defaultSpec)
      Binds a role to a concrete context factory and its expected key/spec types.

      Concrete algorithms call this during construction to declare support for specific roles (e.g., ENCRYPT, VERIFY). When createContext(KeyUsage, Key, ContextSpec) is later invoked, the provided key and optional spec are matched against these bindings.

      Type Parameters:
      C - context type
      K - key type
      S - spec type
      Parameters:
      role - supported KeyUsage role
      ctxType - context type to be returned by the factory
      keyType - key type accepted by the factory
      specType - spec type accepted by the factory (may be a marker type)
      factory - constructor that creates a context for (key, spec)
      defaultSpec - default spec supplier used when spec is null
      Throws:
      NullPointerException - if any class or factory argument is null

    • supports

      public final boolean supports(KeyUsage role)
      Returns whether this algorithm supports the given role.
      Parameters:
      role - a KeyUsage role
      Returns:
      true if a binding exists, otherwise false

    • roles

      public final Set<KeyUsage> roles()
      Returns the set of roles supported by this algorithm.
      Returns:
      unmodifiable set of supported KeyUsage values

    • createContext

      public final <C extends CryptoContext, K extends Key, S extends ContextSpec> C createContext(KeyUsage role, K key, S spec)
      Creates a new CryptoContext for the given role, key, and optional spec.

      Resolution proceeds as follows:

      1. Locate bindings for role; if none exist, throw UnsupportedRoleException.
      2. For each binding, check that key is an instance of the required key type and spec is either null or an instance of the required spec type.
      3. If matched, resolve the effective spec: use the provided spec or obtain one from the binding’s defaultSpec supplier.
      4. Invoke the factory to create a context and verify the returned type matches the declared ctxType.
      Type Parameters:
      C - context type
      K - key type
      S - spec type
      Parameters:
      role - the intended KeyUsage for the created context
      key - key instance compatible with the binding
      spec - optional context spec; if null, the binding’s default is used
      Returns:
      a newly constructed context suitable for the requested role
      Throws:
      UnsupportedRoleException - if the algorithm does not support role
      UnsupportedSpecException - if no binding accepts the provided key/spec
      IllegalStateException - if the factory returns an unexpected context type

    • registerAsymmetricKeyPairGenerator

      protected final <S extends AlgorithmKeySpec> void registerAsymmetricKeyPairGenerator(Class<S> specType, AsymmetricKeyPairGenerator<S> generator, Supplier<? extends S> defaultSpecOrNull)
      Registers asymmetric key-pair generation for one exact specification class.

      The optional default is resolved and validated during registration. Registered generators must be safe for concurrent invocation after the algorithm is published.

      Type Parameters:
      S - specification type
      Parameters:
      specType - exact specification class
      generator - non-null generator
      defaultSpecOrNull - optional default supplier, evaluated once
      Throws:
      NullPointerException - if a required argument or supplied default is null
      IllegalArgumentException - if the supplied default has the wrong type

    • registerPublicKeyImporter

      protected final <S extends AlgorithmKeySpec> void registerPublicKeyImporter(Class<S> specType, PublicKeyImporter<S> importer)
      Registers public-key import for one exact specification class.
      Type Parameters:
      S - specification type
      Parameters:
      specType - exact specification class
      importer - non-null importer safe for concurrent invocation
      Throws:
      NullPointerException - if an argument is null

    • registerPrivateKeyImporter

      protected final <S extends AlgorithmKeySpec> void registerPrivateKeyImporter(Class<S> specType, PrivateKeyImporter<S> importer)
      Registers private-key import for one exact specification class.
      Type Parameters:
      S - specification type
      Parameters:
      specType - exact specification class
      importer - non-null importer safe for concurrent invocation
      Throws:
      NullPointerException - if an argument is null

    • registerSymmetricKeyGenerator

      protected final <S extends AlgorithmKeySpec> void registerSymmetricKeyGenerator(Class<S> specType, SymmetricKeyGenerator<S> generator, Supplier<? extends S> defaultSpecOrNull)
      Registers symmetric-key generation for one exact specification class.

      The optional default is resolved and validated during registration.

      Type Parameters:
      S - specification type
      Parameters:
      specType - exact specification class
      generator - non-null generator safe for concurrent invocation
      defaultSpecOrNull - optional default supplier, evaluated once
      Throws:
      NullPointerException - if a required argument or supplied default is null
      IllegalArgumentException - if the supplied default has the wrong type

    • registerSymmetricKeyImporter

      protected final <S extends AlgorithmKeySpec> void registerSymmetricKeyImporter(Class<S> specType, SymmetricKeyImporter<S> importer)
      Registers symmetric-key import for one exact specification class.
      Type Parameters:
      S - specification type
      Parameters:
      specType - exact specification class
      importer - non-null importer safe for concurrent invocation
      Throws:
      NullPointerException - if an argument is null

    • asymmetricKeyPairGenerator

      public final <S extends AlgorithmKeySpec> AsymmetricKeyPairGenerator<S> asymmetricKeyPairGenerator(Class<S> specType)
      Returns the asymmetric key-pair generator registered for an exact specification class.

      The returned implementation may be shared and invoked concurrently.

      Type Parameters:
      S - specification type
      Parameters:
      specType - exact specification class; subclasses are not matched
      Returns:
      registered generator
      Throws:
      NullPointerException - if specType is null
      IllegalArgumentException - if no generator is registered

    • publicKeyImporter

      public final <S extends AlgorithmKeySpec> PublicKeyImporter<S> publicKeyImporter(Class<S> specType)
      Returns the public-key importer registered for an exact specification class.

      The returned implementation may be shared and invoked concurrently.

      Type Parameters:
      S - specification type
      Parameters:
      specType - exact specification class; subclasses are not matched
      Returns:
      registered importer
      Throws:
      NullPointerException - if specType is null
      IllegalArgumentException - if no importer is registered

    • privateKeyImporter

      public final <S extends AlgorithmKeySpec> PrivateKeyImporter<S> privateKeyImporter(Class<S> specType)
      Returns the private-key importer registered for an exact specification class.

      The returned implementation may be shared and invoked concurrently.

      Type Parameters:
      S - specification type
      Parameters:
      specType - exact specification class; subclasses are not matched
      Returns:
      registered importer
      Throws:
      NullPointerException - if specType is null
      IllegalArgumentException - if no importer is registered

    • symmetricKeyGenerator

      public final <S extends AlgorithmKeySpec> SymmetricKeyGenerator<S> symmetricKeyGenerator(Class<S> specType)
      Returns the symmetric-key generator registered for an exact specification class.

      The returned implementation may be shared and invoked concurrently.

      Type Parameters:
      S - specification type
      Parameters:
      specType - exact specification class; subclasses are not matched
      Returns:
      registered generator
      Throws:
      NullPointerException - if specType is null
      IllegalArgumentException - if no generator is registered

    • symmetricKeyImporter

      public final <S extends AlgorithmKeySpec> SymmetricKeyImporter<S> symmetricKeyImporter(Class<S> specType)
      Returns the symmetric-key importer registered for an exact specification class.

      The returned implementation may be shared and invoked concurrently.

      Type Parameters:
      S - specification type
      Parameters:
      specType - exact specification class; subclasses are not matched
      Returns:
      registered importer
      Throws:
      NullPointerException - if specType is null
      IllegalArgumentException - if no importer is registered

    • parameterSets

      public List<ParameterSetDescriptor<? extends AlgorithmKeySpec>> parameterSets()
      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.

      Returns:
      immutable list of parameter set descriptors; never null

    • requiresStatefulSigning

      public boolean requiresStatefulSigning()
      Indicates that signing consumes durable private-key state. This declaration does not enable the ordinary SIGN role: callers need a keyring-owned StatefulSigner capability.
      Returns:
      whether durable state ownership is required for signing

    • keyOperations

      public final List<KeyOperationInfo> keyOperations()
      Returns deterministic metadata for every exact key operation.
      Returns:
      immutable metadata ordered by operation and specification class