Dynamically Generating KeyStores, TrustStores, and Certificates with WildFly Elytron
Dynamically Generating KeyStores, TrustStores, and Certificates with WildFly Elytron
Overview
It is now possible to quickly and easily generate KeyStores, TrustStores, and Certificates by utilizing the Elytron Examples methods. A new utility class, CertificateGenerator, has been added that can generate a KeyStore and TrustStore, along with saving them to a file-system directory, with a single API call. This utility class can further be used to easily generate client and server KeyStores and TrustStores for Two Way SSL or can be easily fully customized to create as many KeyStores, TrustStores, Certificates (self signed and signed) as wanted, along with saving as many of those KeyStores and TrustStores to as many or as few directories as wanted. This blog post will go into several of the customization and default methods available, along with showing an example. Further examples can be found in the CertificateGenerationExample class and further information on the various methods can be found in the Elytron Examples Javadoc. It is important to remember that this utility is designed to be used for testing purposes and examples, since the certificates are self-signed or signed by a test certificate authority.
Pre-requirements
- Clone the Elytron Examples git repository from Github
- Compile the project with Maven, for example with bash: cd dynamic-certificates;mvn clean install
- Either import the jar (target/dynamic-certificates-1.0.0.Alpha1-SNAPSHOT.jar) into your Java project or add a Maven dependency to depend on the dynamic-certificates artifact built in the previous step
- Alternatively to the previous step, mvn exec:exec can be used to create the default Two-Way SSL keystores and truststores, which will placed in the target directory
Usage Basics
To use any of the methods in CertificateGenerator, the Builder will first have to be called and use to build and instance of CertificateGenerator. The builder requires a String of the path to the desired output directory to be passed directly into it. After this, the various Builder methods can be used to, optionally, pass in alias(es), distinguished name(s), key password(s), and serial number(s). Note: while some CertificateGenerator methods can be used without the optional parameters set, such as createKeyStore, all the methods are designed to be used in unison.
Generating and Saving the KeyStores and TrustStores to File
CertificateGenerator provides two ways for generating KeyStores and TrustStores, the first is using one of two utility methods, generate() and generateTwoWaySSL(), while the second way is directly calling the generation methods. In the first case, all parameters can be set using the set() and add() methods, both in the Builder and after the CertificateGenerator class is built. Once the CertificateGenerator is built and parameters set, calling the generate() method will create the authority, create the certificates, create the KeyStore(s) and TrustStore(s), and then save the KeyStore(s) and TrustStore(s) to the output directory.
Using the Default Methods
The generate() Method
To use this method, parameters can be set using the set() and add() methods, both in the Builder and after the CertificateGenerator class is built. There must be at least one alias and one distinguished name specified in either the Builder methods or with the CertificateGenerator methods, with all other parameters being optional. Once the CertificateGenerator is built and parameters set, calling the generate() method will create the authority, create the certificates, create the KeyStore(s) and TrustStore(s), and then save the KeyStore(s) and TrustStore(s) to the output directory. See below for an example on generating a KeyStore containing one certificate, with an alias of “example-cert-1” and a DN of “CN=example-cert-1”, which will be signed by a Certificate Authority. The Certificate Authority will be a self signed certificate with a DN of “CN=Elytron CA, ST=Elytron” and will have its certificate as a trusted certificate in a generated TrustStore with an alias of “Example-CA”. The KeyStore and TrustStore will be saved to an output directory of “/home/elytron/example/” with their respective names being “example.keystore.jks” and “example.truststore.jks”.
CertificateGenerator generator = new CertificateGenerator.Builder()
.setOutputLocation("/home/elytron/example/")
.addAlias("example-cert-1")
.addDN("CN=example-cert-1")
.build();
generator.setAuthorityAlias("Example-CA")
generator.setAuthorityDN("CN=Elytron CA, ST=Elytron")
generator.setKeyStoreName("example.keystore.jks")
generator.setTrustStoreName("example.truststore.jks")
generator.generate();The generateTwoWaySSL() Method
This method has the required parameters all set already, but some optional parameters, including key passwords and key size, can be set. Calling it will create three KeyStores and three TrustStores, one for the server and one for each of the clients, client1 and client2, in a given output directly. Each client KeyStore will have one certificate each with a randomly generated serial number. The two certificates will have an alias of client1 and client2 with the distinguished names being, respectively, CN=client1 and CN=client2. The server KeyStore will contain a single certificate, server, that has a randomly generated serial number and a distinguished name of CN=server. All truststores will contain a single trusted certificate, the certificate authority, that is configured with the default authority parameters. See below for an example on using this method, which will create the KeyStores and TrustStores with the above stated defaults in the /home/elytron/example directory.
new CertificateGenerator.Builder()
.setOutputLocation("/home/elytron/example/")
.build()
.generateTwoWaySSL();Directly Calling the Methods
It is possible to use CertificateGenerator to step by step, in the same manner as the default methods use it, in order to create the KeyStores and TrustStores. While it will generally be easier to use the default methods, this way can be useful for the ability to do customize the result. This includes being able to stop part way through generation, for example if the certificates are wanted but not the KeyStores and TrustStores, using custom methods for certain steps, such as creating a certificate authority, or if only some output is wanted, such as only KeyStores.
Public Methods
The majority of CertificateGenerator’s methods are public for integration into any Java project, these are listed below. The methods are listed without their arguments (… signifying one or more arguments), more information can be found on the methods in the Javadoc.
createAuthority()
createSignedCertificates(...)
createKeyStore(...)
createTrustStore(...)
createKeyStoreAndTrustStore(...)
saveKeyStoreToFile()
saveTrustStoreToFile()
saveKeyStoreAndTrustStoreToFile()
createKeyStoreAndSaveToFile(...)
createTrustStoreAndSaveToFile(...)
createKeyStoreAndTrustStoreAndSaveToFile(...)Using the Public Methods
In general, the public methods should be used in the order of createAuthority() -> createSignedCertificates(…) -> KeyStore and/or TrustStore creation -> KeyStore and/or TrustStore save to file. However, this order is not strict since the only public method depending on any other is saving the KeyStore and/or TrustStore creation to saving. An example of modifying this order can be seen in the generateTwoWaySSL method, where the order is createAuthority() -> createSignedCertificates(…) -> KeyStore and TrustStore creation -> KeyStore and TrustStore save to file -> createSignedCertificates() -> KeyStore creation -> KeyStore and TrustStore save to file. As can also be seen in that method, the various public parameters can be modified at any point during the API calls.
Summary
This blog post provides some information on the various ways that the new CertificateGenerator utility can be used to both generate KeyStores and TrustStores for examples or to be directly integrated into projects. The post provides some examples for some of the possible ways that the default methods, and through them the public parameters, can be set and modified during creation.
In short, the new tool can be used to quickly create a KeyStore and TrustStore with minimal configuration with:
Alternatively, the tool can be quickly used for creating two-way SSL KeyStores and TrustStores by executing the project with mvn exec:exec or by using the following methods, with the resulting KeyStores and TrustStores placed in the target directory:
Comments
Post a Comment