Ayza 🔐

Install library with:

Install with Maven

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

Install with Gradle

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

Install with Gradle Kotlin DSL

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

Install with Scala SBT

libraryDependencies += "io.github.hakky54" % "ayza" % "10.0.5"

Install with Apache Ivy

<dependency org="io.github.hakky54" name="ayza" rev="10.0.5"/>

Table of contents

1. Introduction
2. History
3. Advantages
4. Definitions
5. Compatibility
6. Usage
7. Example configuration
8. Other possible configurations
   • Loading keystore from the classpath
   • Loading keystore from the file system
   • Loading keystore from InputStream
   • Loading trust material with OCSP options
     • TrustStore from the classpath
     • TrustStore from the file system
     • TrustManager
     • Certificates
   • Enhanceable trust validations
   • Hide trusted certificate names of a server
   • Skip certificate validation
   • Skip hostname validation
   • Loading JDK and OS trusted certificates
   • Using specific protocols and ciphers with custom secure-random and hostname-verifier
   • Enhanceable hostname verifier
   • Using multiple identity materials and trust materials
   • Using custom KeyManager and TrustManager
   • Using dummy identity and trust material
   • Using KeyStore with multiple keys having different passwords
   • Using custom PrivateKey and Certificates
   • Reloading SSL at runtime
   • Hot swap KeyManager and TrustManager at runtime
   • Trust additional new certificates at runtime
   • Routing client identity to specific host
   • Updating client identity routes at runtime
   • Managing additional identities at runtime
   • Managing ssl session
   • Extracting server certificates
   • Single server
   • Bulk extraction from multiple servers
   • Extracting certificates behind proxy
   • Extracting certificates behind proxy with authentication
   • Extracting certificates as pem
   • Using P7B or PKCS#7 files
   • Using DER files
   • Using PFX or P12 or PKCS#12 Files
   • Using PEM Files
   • Loading pem files from the classpath
   • Loading pem files from the file system
   • Loading pem files from InputStream
   • Loading pem files from string content
   • Loading encrypted pem files
   • Migrating from classic configuration
   • Global SSL configuration
   • Logging certificate validation
   • Logging detailed KeyManager flow, input and output
   • Fluently mapping SSLFactory
9. Returnable values from the SSLFactory
10. Additional mappers for specific libraries
11. Netty
12. Jetty
13. Apache
    • Apache 4
    • Apache 5
14. Tested HTTP Clients
15. Tested HTTP Servers
16. Support
17. Contributors
18. License

Introduction

Ayza is a library which provides various utilities to easily configure SSL/TLS for your Http Client and Server. It takes away the verbosity and provides powerful features such as hot reloading of ssl material for rotating certificates without downtime, support for multiple identity and trust materials, support for encrypted pem files, trusting additional certificates at runtime or easily bypassing ssl configuration of other libraries and much more. Please check out the Table of contents to discover all the possibilities which Ayza can offer.

History

As a Java developer I worked for different kinds of clients. Most of the time the application required to call other microservices within the organization or some other http servers. These requests needed to be secured, and therefore it was required to load the ssl materials into the http client. Each http client may require different input value to enable https requests, and therefore I couldn't just copy-paste my earlier configuration into the new project. The resulting configuration was in my opinion always verbose, not reusable, hard to test and hard to maintain.

As a developer you also need to know how to properly load your file into your application and consume it as a KeyStore instance. Therefore, you also need to understand how to properly create for example a KeyManager and a TrustManager for you SSLContext. Ayza is taking the responsibility of creating an instance of SSLContext from the provided arguments, and it will provide you all the ssl materials which are required to configure 40+ different Http Client for Java, Scala and Kotlin. I wanted the library to be as easy as possible to use for all developers to give them a kickstart when configuring their Http Client. So feel free to provide feedback or feature requests.

The library has been renamed to Ayza in September 2025 as I wanted a shorter name, which is easy to pronounce and to make it easy to remember. Detailed information about the rename can be found here: Renaming project to Ayza

The library by the way also provides other utilities such as: - CertificateExtractingClient - CertificateUtils - HostnameVerifierUtils - KeyStoreUtils - KeyManagerUtils - TrustManagerUtils - PemUtils - ProviderUtils - SSLContextUtils - SSLFactoryUtils - SSLParametersUtils - SSLSessionUtils - SSLSocketUtils

Advantages:

• No need for low-level SSLContext configuration anymore
• No knowledge needed about SSLContext, TrustManager, TrustManagerFactory, KeyManager, KeyManagerFactory and how to create it.
• Above classes will all be created with just providing an identity and a trust material
• Load multiple identities/trustStores/keyManagers/trustManagers
• Hot reload ssl material without need of restarting/recreating Http Client or Server

Definitions

• Identity material: A KeyStore or KeyManager which holds the key pair also known as private and public key
• Trust material: A KeyStore or TrustManager containing one or more certificates also known as public key. This KeyStore contains a list of trusted certificates
• One way authentication (also known as one way tls, one way ssl): Https connection where the client validates the certificate of the counter party
• Two way authentication (also known as two way tls, two way ssl, mutual authentication): Https connection where the client as well as the counter party validates the certificate, also known as mutual authentication

Compatibility

Usage

Basic example configuration

Example configuration with apache http client, or click here to view the other client configurations

import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import org.json.JSONException;
import org.json.JSONObject;

import nl.altindag.ssl.SSLFactory;

public class App {

    public static void main(String[] args) throws IOException, JSONException {
        SSLFactory sslFactory = SSLFactory.builder()
                .withDefaultTrustMaterial()
                .build();

        HttpClient httpClient = HttpClients.custom()
                .setSSLContext(sslFactory.getSslContext())
                .setSSLHostnameVerifier(sslFactory.getHostnameVerifier())
                .build();

        HttpGet request = new HttpGet("https://api.chucknorris.io/jokes/random");

        HttpResponse response = httpClient.execute(request);
        String chuckNorrisJoke = new JSONObject(EntityUtils.toString(response.getEntity())).getString("value");

        System.out.println(String.format("Received the following status code: %d", response.getStatusLine().getStatusCode()));
        System.out.println(String.format("Received the following joke: %s", chuckNorrisJoke));
    }

}

Response:

Received the following status code: 200
Received the following joke: If a black cat crosses your path, you have bad luck. If Chuck Norris crosses your path, it was nice knowing you.

Other possible configurations

Loading keystore and truststore from the classpath

```text SSLFactory.builder() .withIdentityMateri