https://github.com/tsaarni/reloading-keystore

KeyStore for Java with certificate hot-reload and PEM file support
https://github.com/tsaarni/reloading-keystore

certificates java keystore tls x509

Last synced: about 1 month ago
JSON representation

KeyStore for Java with certificate hot-reload and PEM file support

• Host: GitHub
• URL: https://github.com/tsaarni/reloading-keystore
• Owner: tsaarni
• License: apache-2.0
• Created: 2022-06-12T18:49:48.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2024-04-15T07:19:01.000Z (7 months ago)
• Last Synced: 2024-04-24T06:31:04.636Z (7 months ago)
• Topics: certificates, java, keystore, tls, x509
• Language: Java
• Homepage:
• Size: 479 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Reloading KeyStore for Java

![](https://github.com/tsaarni/reloading-keystore/workflows/unit-tests/badge.svg)

[![Maven Central](https://img.shields.io/maven-central/v/fi.protonode/reloading-keystore)](https://search.maven.org/search?q=g:fi.protonode%20AND%20a:reloading-keystore)

## Description

This project is a library that implements custom `KeyStore` with following features:

* Automatically reload credentials from disk when the underlying files change.

* Load certificates and private keys directly from `.pem` files, in addition to `.p12` and `.jks` keystore files.

* Allow user to set fallback certificate which will be used by server when a client does not send TLS SNI extension (Server Name Indication) or sends unknown servername.

These features can be implemented in relatively few lines of code, without external dependencies and without background threads.

Use this project either as a tutorial on how to implement custom `KeyStoreSpi` or import the library directly into your application.

## Documentation

The code is compatible with JDK 8 and above.

See the [implementation description](docs/implementation-description.md)

for details and related background discussion about JSSE (Java Secure Socket Extension).

Read the latest API documentation [here](https://tsaarni.github.io/reloading-keystore).

## Example

Following example shows how to create a TLS server that reads its server credentials from PEM files.

It constructs an instance of custom `KeyStore` which will have the special capabilities mentioned previously.

It is then passed to `KeyManager` just like the standard `KeyStores`.

```java

// Create KeyManagerFactory with ReloadingKeyStore, implemented by custom KeyStoreSpi.

// Credentials in the KeyStore are loaded from server.pem and server-key.pem.

// ReloadingKeyStore keeps track of the files for being able to reload them later.

KeyManagerFactory kmf = KeyManagerFactory.getInstance("NewSunX509");

kmf.init(new KeyStoreBuilderParameters(ReloadingKeyStore.Builder.fromPem(

    Paths.get("server.pem"), Paths.get("server-key.pem"))));

// Otherwise continue as with any KeyStore implementation:

// Initialize SSLContext with our KeyManager.

SSLContext ctx = SSLContext.getInstance("TLS");

ctx.init(kmf.getKeyManagers(), null, null);

// Create server socket and start accepting connections.

// Server will query our KeyManager for server credentials every time it

// gets a new connection from clients.

// Credentials will be reloaded automatically when they are updated on disk.

SSLServerSocketFactory ssf = ctx.getServerSocketFactory();

SSLServerSocket socket = (SSLServerSocket) ssf.createServerSocket(

    8443, 1, InetAddress.getByName("localhost"));

try (SSLSocket client = (SSLSocket) socket.accept()) {

    // ...

}

```

For more code examples, see the test suite [here](lib/src/test/java/fi/protonode/reloadingkeystore/).