morihofi / acmeserver

Java-based ACME server for SSL/TLS certificate management with ACME V2 protocol support (RFC 8555)

ACME Server

📃 About

This is an implementation of an Automatic Certificate Management Environment (ACME) Server, fully written in Java

• Java 17 and up
• Any JDBC (and Hibernate compatible) database. Currently, H2, MariaDB and PostgreSQL drivers are in classpath
• Proxy support for HTTP Challenge

🎉 ACME Server is now one year old!

One year ago, I started this project. I'm happy to announce that this project is now one year old! And we're reaching version 2.0 😮 with a lots of features.

⚠ Breaking Changes from Version 1.x to Version 2.x

• Provisioner directory is now in /acme/provisionername/directory
• Database scheme has been complete rebuilt, please clean database before use
• Due to move of provisioner directory, the URLs to OCSP and CRL have also been moved, please regenerate your intermediate certificates by delete the corresponding entries in the keystore

📰 Changelog

Changelog has been moved here

📒 Disclaimer

This version is not fully RFC 8555 compliant, but should work with most clients. I'll hope to say one day that we are fully compliant.

📖 Documentation

Documentation is now located here. In the same directory are also other tutorials related to this ACME Server.

✨ Features

• Self-hosted ACME Server for use with your own CA
• Download CA support
  • Download in standard formats like CRT, PEM, DER
  • CAB file CA export for install on legacy Windows Mobile based devices (e.g. older embedded devices, old PDAs, ...)
• Support for PKCS#12 (.p12) KeyStore and PKCS#11 Hardware Security Modules (HSM)
• Revokation support for certificates
• ACME Account deactivation
• Mostly ACME RFC compliant in its behaviour
• Multiple provisioners support with own intermediate CA
  • Set expiration and key algorithm for each intermediate
  • Set expiration for each issued certificate in provisioner
  • Each provisioner has its own CRL (Certificate Revokation List)
  • Set a domain naming restriction for each provisioner (e.g. domain must end with ".example.com")
  • Enable wildcard support individually for each provisioner (e.g. *.example.com)
• Built-in OCSP (Online Certificate Status Protocol) server
• Signature check of client's requests
• Support for multiple identifiers in one order (multiple domains)
• Nonce validation (Replay protection)
• Supported challenges:
  • HTTP-01
  • DNS-01
• Statistics
• API and WebUI TLS Security can be automatically configured using Mozilla's SSL Config Guidelines, see Wiki here (JSON configuration from 4.0 until 5.7 (latest at writing this) are included, if specified version not available it will try to fetch these from the Mozilla server. Note: Version before 5.1 might be a bit buggy)

✅ Testing status

🤖 Tested ACME Clients

	HTTP-01	DNS-01
GetHttpsForFree	✅	✅	-> modified version is included
Certbot	✅	✅	ℹ Note, works only correctly, if certificate issuing is not async in the server (default)
acme.sh	🐞	✅	For HTTP-01 use Standalone mode, nginx mode won't work for no reason. Should also work for OPNsense, cause it also uses acme.sh as backend
Traefik	✅	❓
win-acme	✅	❓	Tested with IIS 8.5 on Win Server 2012 r2. Only use Provisioner with RSA, because IIS doesn't support Elliptical Curves
acme4j	✅	✅

💻 Tested Operating Systems

	Test status	Notes
Debian 11, 12	✅
FreeBSD 13.2, 13.3, 14	✅	Only the RELEASE Builds were tested
Windows 10	✅

🗃️ Tested Databases

	JDBC Driver Built-in	Test status	Notes
MariaDB	Yes	✅
H2	Yes	✅	Only embedded mode has been tested, server mode should be supported
PostgreSQL	Yes	✅	Use a up-to-date database version. Tested with PostgreSQL 16.2, older version may won't work properly
MySQL	No	❓	Hibernate configuration has been prepared, but not tested yet

If you want to use a database engine, where the JDBC driver isn't built in, you have to add the driver manually to the classpath and specify the Main-Class manually.

🔎 Meanings of the Emojis

✅	❌	🐞	❓
works without issues	not working at the moment	buggy	not tested

🐛 Debug Mode

Enable debug mode by set environment variable DEBUG to TRUE or start ACME Server with --debug. Do not use this in production as it disables some security mechanisms (e.g. nonce check) and can lead to misuse of your CA.

💻 Development Contributions

We welcome every contribution to the ACME Server project. Please refer to our style guide located in the styleguide directory for more information on coding standards and practices. This ensures that the code keeps readable and easier to test.

---

❤ Thanks to

• OpenAI's ChatGPT (Helped me, when I was struggling)
• BouncyCastle (For a great cryptographic library in Java)
• KeyStore Explorer (Helped me debugging my generated certificates)
• GetHttpsForFree (For debugging my ACME Server and understanding the ACME protocol, a modified version is built-in the server)
• Acme4j (It's client implementation helped me to generate the expected DNS Challenge value on the server side)
• CabinetMaker for generating CAB file using pure Java, it has been refactored for Java 17+

acmeserver's Issues

Allow easy import of CA certificates on first run

Currently, the process for importing CA (Certificate Authority) certificates into the system during the initial setup is manual and can be cumbersome for users who are not familiar with the necessary steps. This can pose a significant barrier to entry, especially in environments where custom or self-signed CA certificates are prevalent. To enhance user experience and streamline the initial setup process, I propose the implementation of a feature that simplifies the import of CA certificates on the first run of the application.

Refactor: Refactoring Log4j Logging Statements

Currently, there is concatenating for logging in use, like log.info("E-Mail validation successful for email \"" + email + "\"");. A better way to do this is log.info("E-Mail validation successful for email {}", email);. This is an issue across the codebase, SpotBugs also doesn't like it.

Nonces are not strike off the list, generated nonces are not checked agenist

Looks like a randome nonce can be send in a request, since server only inserts nonce in to db when nonce was used.

References:

acmeserver/src/main/java/de/morihofi/acmeserver/tools/crypto/Crypto.java

Lines 41 to 53 in 6e5ac3b

	public static String createNonce() {
	try {
	SecureRandom prng = SecureRandom.getInstance("SHA1PRNG");
	String randomNum = String.valueOf(prng.nextInt());
	MessageDigest sha = MessageDigest.getInstance("SHA-256");
	byte[] result = sha.digest(randomNum.getBytes(StandardCharsets.UTF_8));
	return Hashing.hexEncode(result);
	} catch (Exception e) {
	throw new IllegalArgumentException("Unable to create nonce", e);
	}
	}

acmeserver/src/main/java/de/morihofi/acmeserver/certificate/acme/security/NonceManager.java

Lines 63 to 94 in 6e5ac3b

	public static boolean isNonceUsed(String nonce) {
	if (Main.debug) {
	// Nonce protection is disabled when DEBUG environment variable is set to TRUE
	return false;
	}
	try (Session session = Objects.requireNonNull(HibernateUtil.getSessionFactory()).openSession()) {
	org.hibernate.Transaction transaction = session.beginTransaction();
	// Check if the nonce exists in the database
	String hql = "SELECT 1 FROM HttpNonces hn WHERE hn.nonce = :nonce";
	Query query = session.createQuery(hql, HttpNonces.class);
	query.setParameter("nonce", nonce);
	List<HttpNonces> results = TypeSafetyHelper.safeCastToClassOfType(query.getResultList(), HttpNonces.class);
	boolean nonceExists = !results.isEmpty();
	if (!nonceExists) {
	// If the nonce does not exist, add it to the database
	HttpNonces newNonce = new HttpNonces(nonce, LocalDateTime.now());
	session.persist(newNonce);
	}
	transaction.commit();
	// Return true if nonce exists, false if it was added
	return nonceExists;
	} catch (Exception e) {
	LOG.error("Error checking or adding nonce", e);
	return false;
	}
	}

The precise method used to generate and track nonces is up to the
server. For example, the server could generate a random 128-bit
value for each response, keep a list of issued nonces, and strike
nonces from this list as they are used.
-- RFC 8555 6.5. Replay Protection

Package nonce implements a service for generating and redeeming nonces.
To generate a nonce, it encrypts a monotonically increasing counter (latest)
using an authenticated cipher. To redeem a nonce, it checks that the nonce
decrypts to a valid integer between the earliest and latest counter values,
and that it's not on the cross-off list. To avoid a constantly growing cross-off
list, the nonce service periodically retires the oldest counter values by
finding the lowest counter value in the cross-off list, deleting it, and setting
"earliest" to its value. To make this efficient, the cross-off list is represented
two ways: Once as a map, for quick lookup of a given value, and once as a heap,
to quickly find the lowest value.
The MaxUsed value determines how long a generated nonce can be used before it
is forgotten. To calculate that period, divide the MaxUsed value by average
redemption rate (valid POSTs per second).
-- letsencrypt/boulder nonce/nonce.go

ACME Request Unit Tests

Add unit test, that covers the whole ACME Certificate Request Process.