Package zeroecho.core

Class CryptoCatalog

java.lang.Object
zeroecho.core.CryptoCatalog
public final class CryptoCatalog extends Object
Immutable snapshot of discovered CryptoAlgorithm implementations, with utilities to validate and serialize the catalog.

CryptoCatalog is a lightweight registry built at a point in time via load(). It collects algorithms published through the Java SPI for CryptoAlgorithm, ensures identifier uniqueness, and exposes:

  • validate() — sanity checks that each algorithm publishes at least one capability or key builder,
  • toJson() — a compact JSON description of algorithms, capabilities, and registered key builders, and
  • toXml() — an XML rendition of the same data.

Identity and uniqueness

Algorithm ids are treated as canonical keys. If two providers expose the same id, the catalog build fails with IllegalStateException.

Immutability & thread-safety

After construction, the internal map is unmodifiable and safe to share across threads. This class performs no lazy discovery or on-demand mutation.

Serialization formats

  • JSON: produced by toJson() as a single object with an algorithms array; trivial string escaping is applied.
  • XML: produced by toXml() with a <cryptoCatalog> root; &amp;&lt;&gt; escaping is applied to element text and attributes.

Note: Default spec / key-spec values shown in outputs are derived from Suppliers registered by algorithms. Suppliers may compute labels or return lightweight descriptors; their intent is documentation, not round‑tripping.

Since:
1.0

  • Method Details

    • load

      public static CryptoCatalog load()
      Discovers CryptoAlgorithm implementations via ServiceLoader and returns an immutable catalog snapshot.

      During loading, algorithm ids are checked for uniqueness. A duplicate id results in an IllegalStateException to prevent ambiguous resolution.

      Returns:
      an immutable CryptoCatalog with all discovered algorithms
      Throws:
      IllegalStateException - if two providers declare the same algorithm id

    • validate

      public void validate()
      Verifies that each algorithm in this catalog exposes at least one capability or key builder.

      This is a sanity check for provider completeness. If an algorithm publishes neither capabilities nor asymmetric/symmetric key builders, the validation fails.

      Throws:
      IllegalStateException - if any algorithm has no capabilities and no key builders

    • toJson

      public String toJson()
      Serializes the catalog to a compact JSON document.

      The schema is: 

      
 {
   "algorithms": [
     {
       "id": "AES/GCM",
       "displayName": "AES-GCM",
       "capabilities": [
         {
           "family": "SYMMETRIC",
           "role": "ENCRYPT",
           "contextType": "AeadEncryptContext",
           "keyType": "SecretKey",
           "specType": "AeadSpec",
           "defaultSpec": "Random nonce, 128-bit tag"
         }
       ],
       "asymmetricKeyBuilders": [
         { "specType": "Ed25519Spec", "defaultKeySpec": "Ed25519 default" }
       ],
       "symmetricKeyBuilders": [
         { "specType": "AesKeySpec", "defaultKeySpec": "AES-256" }
       ]
     }
   ]
 }

      String values are escaped for quotes and backslashes. The method does not attempt to pretty-print; callers can format the output if needed.

      Returns:
      a JSON string describing algorithms, capabilities, and key builders

    • toXml

      public String toXml()
      Serializes the catalog to an XML document.

      The root element is <cryptoCatalog>. Each algorithm becomes an <algorithm> element with id and name attributes, plus nested sections for <capabilities>, <asymmetricKeyBuilders>, and <symmetricKeyBuilders>.

      Element text and attribute values are escaped for &amp;, &lt;, &gt;.

      Returns:
      an XML string describing algorithms, capabilities, and key builders