Ayza configures SSL on the JVM from keystores, PEM files and the OS store

SSL configuration as a library rather than a set of defaults

Ayza is described as an SSL library for configuring an HTTP client or server, with features including hot reloading SSL, trusting additional certificates during runtime, combining multiple keystores, loading PEM files and OS and JDK certificates, logging certificate information during the SSL handshake, and bypassing SSL configuration from other libraries. The problem it addresses is real and specific to the JVM. The platform ships with a trust store, and that is fine until it is not, because you have to talk to a service with a private certificate, or your enterprise root is not in the Java trust store, or you need to rotate identity certificates without dropping connections. The usual workarounds are unpleasant, whether that means installing certificates into the JVM cacerts file, writing a custom X509ExtendedTrustManager, or adding a third party HTTP client with its own TLS opinions. The audience is JVM developers working with Java, Kotlin or Scala, on Android or on the server, who need the second and third of those situations solved in one place.

One artifact, four build tools, a wide runtime range

The install section is unusually thorough, which is a good sign for a library that has to be dropped into an existing build. The current version is 10.1.0 and the group id is io.github.hakky54 with the artifact ayza. Maven looks like this:

<dependency>
    <groupId>io.github.hakky54</groupId>
    <artifactId>ayza</artifactId>
    <version>10.1.0</version>
</dependency>

Gradle uses a single line:

implementation 'io.github.hakky54:ayza:10.1.0'

and the Gradle Kotlin DSL variant:

implementation("io.github.hakky54:ayza:10.1.0")

Scala SBT is a libraryDependencies line, and Apache Ivy takes a single dependency element with an org, name and rev attribute. The compatibility badges give the runtime range: JDK 8 and newer, Kotlin 1.5 and newer, Scala 2.11 and newer, and Android API level 24 and newer. That combination is the point of the project, a single TLS configuration library usable from Java, from Kotlin, from Scala and from an Android application without a second implementation for each. The package is published to Maven Central under io.github.hakky54/ayza, and the repository also carries a KEYS.txt, a CHANGELOG.md, an ayza-bom/ directory for dependency version alignment, and a release.sh script alongside the Maven wrapper files.

Loading identity and trust sources from every format

The table of contents lists the surface area, and it is the clearest statement of what the library does. Trust sources can be loaded from a keystore on the classpath, a keystore from anywhere on the file system, a keystore from an InputStream, and each of those with OCSP options attached, and there is a separate path for loading trust sources with a TrustManager and with certificates directly. The same set of loading routes exists for PEM files, again from the classpath, from the file system and from an InputStream. On top of that sit the container and key formats, with entries for P7B or PKCS#7 files, DER files, PFX, P12 or PKCS#12 files, and PEM files. The formats list is the reason this library exists, because a real enterprise environment hands you a mix. A server gives you a PEM chain, an internal tool hands you a PFX with a password, a partner sends a PKCS#7 bundle, and the operating system has its own trust store you also want. There is also a documented entry for loading JDK and OS trusted certificates, which means the library can start from the platform trust store and add to it rather than replacing it. The docs also cover using a single keystore containing multiple keys with different passwords, and using a custom PrivateKey with certificates, which are the two cases that break naive loaders.

Runtime changes, which is the reason to use a library here

The section list from the documentation shows a set of runtime capabilities that go well beyond building an SSLContext once. There is support for reloading SSL at runtime, for hot swapping the KeyManager and TrustManager at runtime, and for trusting additional new certificates at runtime. There is routing of client identity to a specific host, and updating those identity routes at runtime, plus managing additional identities at runtime. There is managing the SSL session and extracting server certificates, both for a single server and in bulk from multiple servers, including behind a proxy, behind a proxy with authentication, and as PEM. There is an enhanceable trust validation, an enhanceable hostname verifier, the ability to hide trusted certificate names of a server, and options for specific protocols and ciphers with a custom secure random and hostname verifier. The distinction between a static library and a configurable one matters for long running services. If a certificate expires at 3am, a static SSLContext will not notice, and a service that has to be restarted to pick up a renewed certificate is a service with an outage attached. The hot reload and hot swap features exist to make that a non-event, and the certificate extraction features exist so you can see what a server is actually presenting before you trust it.

Adapters for the HTTP clients people actually use

The repository layout shows the structure of the distribution, and it is the part that tells you how the library fits into an application. The core lives in ayza/, and there is a directory for each integration: ayza-for-netty/, ayza-for-jetty/, ayza-for-apache4/ and ayza-for-apache5/. The naming of the last two is the interesting detail, since it signals a major version split in Apache HttpClient and therefore a separate artifact per major, so a project on HttpClient 4 and one on HttpClient 5 both get support without a compatibility shim. The description also mentions bypassing SSL configuration from other libraries, which is a real need in the Java HTTP client world where several libraries each carry their own idea of how TLS should be set up and will happily override what you configured. Choosing the adapter module that matches your client is the practical first step, and the documentation has a dedicated section for providing SSL options per client. The repository also includes an images/ directory for the documentation, an ayza-for-pem/ module, and a pom.xml at the root, so the project is a Maven multi-module build with a parent pom.

The options that will get you into trouble, and how to treat them

The documentation has entries for trusting all certificates without validation, with the title marking it as not recommended for production use, and separately for skipping hostname validation. These exist, and they exist because test environments with self signed certificates and hostname mismatches are a real daily problem, but the naming is the warning. A library that makes it easy to disable certificate validation is a library that will have it disabled in production at some point, often by a developer under deadline, and the failure is silent because the connection works. The rules that follow from this are simple. The trust all and skip hostname options belong in test configuration that is selected by an environment or profile, never in the same config file that production loads. The enhanceable trust validation and the enhanceable hostname verifier are the safe alternatives, since they let you add a specific certificate or a specific host rule without turning off the whole check. There is also a documented way to hide trusted certificate names of a server, which is about not leaking internal hostnames in logs rather than about weakening verification. The project also publishes a security rating badge from SonarCloud and a known vulnerabilities badge from Snyk, which is a reasonable signal for a library whose job is to get TLS right.

Editorial conclusion

Adopt Ayza if you are on the JVM and need TLS behaviour the default trust store cannot give you, such as pinning a private CA, trusting an extra certificate at runtime, or swapping identity certificates without a restart. Do not adopt it if your TLS needs are standard, because the JDK defaults are simpler and audited. Before you start, pick the module for your HTTP client from the ayza-for-netty, ayza-for-jetty, ayza-for-apache4 and ayza-for-apache5 directories, read the CHANGELOG.md for breaking changes across the 10.x line, and treat the trust-all and skip-hostname-validation options as test tooling rather than configuration.

Frequently asked questions

Official sources

1. Hakky54/ayza on GitHub
2. Issues
3. License: Apache-2.0
4. README