Winter 2018 Release train for Atbash libraries

Introduction

Atbash is a set of libraries which tries to make security easier. It contains features around cryptographic keys (RSA and EC keys for example), reading and writing keys in all the different formats, algorithms (like the Diffie-Hellman Algorithm), securing JAX-RS endpoints, and many more. The top-level project is Atbash Octopus which is a complete platform for declarative security for Java SE, Java EE and Micro-Services (MicroProfile).

Besides this security focus point, some useful Java SE and MicroProfile extensions are also made available instead of just bundling them with the security features which uses them.

A new set of Atbash features are ready and are released to Maven Central. This blog post gives a short overview of the different new features but in the coming weeks, the main features are described in more detail in separate blogs.

Winter 2018 release

The first time I released multiple Atbash libraries to Maven Central was last summer, with the Summer 2018 release. Also now there are multiple features ready so I found it a good time to release again a lot of the libraries together.

The 3 main top features in this winter release are

  • Reading and writing many cryptographic key types (RSA, EC, OCT, and DH) in many formats like PEM (including different encodings like PKCS1 and PKCS8), JWK, JWKSet, and Java KeyStore (‘old versions’ and PKCS12).
  • Easy encryption helper methods (using symmetric AES keys) and methods for creating JWE objects (Encrypted JWT tokens).
  • Implementation of the Diffie-Hellman algorithm to exchange data in an encrypted way without the need for exchanging the key.

The non-security highlights in this release are

  • An extensible Resource API
  • The option to define alternative keys for MicroProfile config.

More on them in the next section and in the upcoming dedicated blogs

Supported Java versions.

The goal of Atbash is also to bring you all those goodies, even when you are still stuck with Java 7. Therefore are libraries support Java 7 as the minimum version. But with the release of JDK 11 a few months ago, I made sure that all the libraries which are released as part of this Winter 2018 release, can also run on this new Long Term supported Java version. It only supports the Class-Path fully, there are no Java modules created.

New features

Atbash Utils
A library containing some useful utilities for Java SE, CDI, and JSF. In the new 0.9.3 version, there are 2 major new features implemented.

Resource API

With the resource API, it becomes easy to retrieve the content of a file, a class path resource, a URL or any custom defined location in a uniform way.

Based on the prefix, like classpath:, http:, etc …, the implementation will look up and read the resource correctly. But you can also define your own type, defining your custom prefix, and register is through the Service Loader mechanism.

This uniform reading of a resource is very handy when you need to read some resource content in your application (or your own framework) and wants to make the location of the file configurable.
You just need to retrieve the ‘location’ from the configuration and can call

ResourceUtil.getInstance().getStream();

Resource Scanner

Another addition, also related to resources, is the resource scanner to retrieve all class path resources matching a certain pattern. There are various use cases where it could be handy that you can retrieve a list of resources, like all files ending on .config.properties, from the class path. This allows having some extension mechanism that brings their own configuration files.

The alternative keys for MicroProfile config make use of this.

Atbash Config

The library contains a few useful extensions for MicroProfile Configuration. It has also an implementation of the MicroProfile Config 1.2 version for Java 7. It is a compatible version (not certified) as MP Config requires Java 8.

Alternative keys

A useful addition in this release is the alternative keys which can be defined. Useful in case you want to change the name of a config parameter key but you want to the users of your library the time to adapt to your new key value.
So you can basically define a mapping between 2 keys, old value, and a new value. Within your library code, you already use the new value. But when the Atbash Config library is on the classpath, the developer can still use the old name.

Atbash JWT support

A library to support many aspects of the JWT stack. Not only signed and encrypted JWT tokens, but also JWK (storing keys). And by extension, it has extensive support for cryptographic keys.

In this library, the most notable new features of this winter release can be found.

Reading and writing many cryptographic keys

Reading and writing cryptographic keys was already partially implemented in the previous version of the library. But now it supports more or less all possible scenarios.

On the one side, there is support for the different types

  • RSA keys
  • Elliptic Curve (EC) keys
  • OCT keys (just a set of bits usable for HMAC and AES)

And this can be stored (and read) in many formats

  • Asymmetric private keys in PEM (using PKCS1, PKCS8 or none encoding), JWK, JWKSet, and KeyStores (JKS, JCEKS, and PKCS12)
  • Asymmetric private keys in PEM, JWK, JWKSet, and KeyStores (JKS, JCEKS, and PKCS12)
  • OCT keys as JWK and JWKSet.

And this reading and writing are performed by a single method (all checking is done behind the scenes) namely KeyWriter.writeKeyResource and KeyReader.readKeyResource.

More info in a later blog post.

Encryption

There are various helper methods to perform encryption easier. The encryption can be performed with an OCT key, or this key can be generated based on a password or passphrase using the Key Derivation Functions.

A second possibility for encryption is the use of JWE, an encrypted version of the JWT token. In the blog post, an example will be given how you can easily create a JWE. And it is the same method to create a JWT, without encryption, just a different parameter.

Key Server

The Key Server is more an example of the Diffie-Hellman algorithm which is implemented in this release more than it is a production-ready component. With the Diffie-Hellman algorithm, it is possible to perform encryption of the data without the need to exchange the secret key. The same principle is used for SSL communication. But now it is performed by the application itself and thus no termination like the one performed by the firewalls is possible.

The blog will explain the Key Server principals and another use case where the posting of JSON data to an endpoint is transparently encrypted.

Future

More features from Octopus are also transferred from the original Octopus to the Atbash Octopus framework, including the support for OAuth2 and OpenId Connect. But there wasn’t enough time to migrate all the features that I wanted, so Octopus isn’t released is this time. But migration and improvements will continue to be performed.

With the release of JDK 11, more focus will be placed on this new version and thus the master branch will hold only code which will be compatible with Java 8 and Java 11. The support for Java 7 will be transferred to a separate branch and will go in maintenance mode. No real new features will be implemented anymore in this branch unless required for Atbash Octopus which will stay at Java 7 for a little longer.

Since the first application server supporting JDK 11 is released, and more of them coming in the next months, more focus will be placed on that runtime environment.

Conclusion

As you can read in the above paragraphs, this release contains some interesting features around security and configuration. And the good thing, they all can be used already with JDK 11 in Class-Path mode.

In the follow-up blogs, the mean new features will be discussed more in details, so I hope to welcome you again in the near future.

Have fun.

MicroProfile support in Java EE Application servers

Introduction

With Java EE, you can create enterprise-type application quickly as you can concentrate on implementing the business logic.
You are also able to create applications which are more micro-service oriented, but some handy ‘features’ are not yet standardised. Standardisation is a process of specifying the best practices which of course takes some time to discover and validate these best practices.

The MicroProfile group wants to create standards for those micro-services concepts which are not yet available in Java EE. Their motto is

Optimising Enterprise Java for a micro-services architecture

This ensures that each application server, following these specifications, is compatible, just like Java EE itself. And it prepares the introduction of these specifications into Java EE, now Jakarta EE under the governance of the Eclipse Foundation.

Specification

There are already quite some specifications available under the MicroProfile flag. Have a look at the MicroProfile site and learn more about them over there.

The topics range from Configuration, Security (JWT tokens), Operations (Metric, Health, Tracing), resilience (Fault tolerance), documentation (OpenApi docu), etc …

Implementations

Just as with Java EE, there are different implementations available for each spec. The difference is that there is no Reference Implementation (RI), the special implementation which goes together with the specification documents.
All implementations are equally.

You can find standalone implementations for all specs within the SmallRye umbrella project or at Apache (mostly defined under the Apache Geronimo umbrella)

There exists also specific ‘server’ implementations which are specifically written for MicroProfile. Mostly based on Jetty or Netty, all implementations are added to have a compatible server.
Examples are KumuluzEE, Hammock, Launcher, Thorntail (v4 version) and Helidon for example.

But implementations are also made available within Java EE servers which brings both worlds tightly integrated. Examples are Payara and OpenLiberty but more servers are following this path like WildfFly and TomEE.

Using MicroProfile in Stock Java EE Servers

When you have your large legacy application which still needs to be maintained, you can also add the MicroProfile implementations to the server and benefits from their features.

It can be the first step in taking out parts of your large monolith and place it in a separate micro-service. When your package structure is already defined quite well, the separation can be done relatively easily and without the need to rewrite your application.

Although adding individual MicroProfile applications to the server is not always successful due to the usage of the advanced CDI features in MicroProfile implementations. To try things out, take one of the standalone implementations from SmallRye or Apache (Geronimo) – Config is the probably easiest to test, add it to the lib folder of your application server.

Dedicated Java EE Servers

There is also the much easier way to try out the combination which is choosing a certified Java server which has already all the MicroProfile implementations on board. Examples today are Payara and OpenLiberty. But also other vendors are going this way as the integration has started for WildLy and TomEE.

Since the integration part is already done, you can just start using them. Just add the MicroProfile Maven bom to your pom file and you are ready to go.

<dependency>
   <groupId>org.eclipse.microprofile</groupId>
   <artifactId>microprofile</artifactId>
   <version>2.0.1</version>
   <type>pom</type>
   <scope>provided</scope>
</dependency>

This way, you can define how much Java EE or MicroProfile stuff you want to use within your application and can achieve the gradual migration from existing Java EE legacy applications to a more micro-service alike version.

In addition, there exists also maven plugins to convert your application to an uber executable jar or you can run your WAR file also using the hollow jar technique with Payara Micro for example.

Conclusion

With the inclusion of the MicroProfile implementations into servers like Payara and OpenLiberty, you can enjoy the features of that framework in your Java EE Application server which you are already familiar with.

It allows you to make use of these features when you need them and create even more micro-service alike applications and make a start of the decomposition of your legacy application into smaller parts if you feel the need for this.

Enjoy it.

MicroProfile 1.3 support for Jessie

Introduction

In a previous release of Jessie, there was support added for MicroProfile specifications. Initially, it was only for version 1.2 because this is the specification for which you have to most implementations available, Payara Micro, Open Liberty, WildFly Swarm and KumuluzEE.

Now I have added support for version 1.3 which is already supported by Open Liberty and Payara Micro.

MicroProfile 1.3

With the release of MicroProfile 1.3, there are a few specifications added to the mix.

OpenAPI 1.0

The specification defines the documentation of your JAX-RS endpoints using the OpenAPI v3 JSON or YAML specification.
The MicroProfile specification defines various ways on how this can be generated, like using specific annotations, fixed document, java based generator and filter.
More information and usage scenario can be found in the specification document.

OpenTracing 1.0

This specification will help you to keep track of the requests flow between all your micro-services. It has 2 main goals, define how the correlation id and additional information is transferred between different micro-services and the format of the trace records which are produced.

More information can be found in the document at link.

REST Client 1.0

The last addition is the most attractive one for developers I guess, at least for me. It builds on top of the JAX-RS client specification of Java EE/Jakarta EE.
It allows you to use type-safe access to your endpoints without the need to programmatic interact with the Client API.
You define with an interface how the JAX-RS endpoint should be called and by adding the required JAX-RS constraints (defining, for example, the method and the format like JSON) the JAX-RS client is generated dynamically.
You can read more about this nice feature in my previous blog post where I explored this specification and presented you with a client for Java SE.

What is available in Jessie?

In this release, support for MicroProfile 1.3 is added as mentioned in the introduction. It means you can select the version within a dropdown and later on, the server implementations capable of providing your selection are shown.

Not for all specifications added in this 1.3 version, have examples in the generated application. They will be added in a next version, but for those who want to get started, this version of Jessie can help them.

There are 2 other improvements added to this version
– Since there are quite some specifications now, you can specify for which of them you want a simple example in the generated application. This doesn’t restrict you in any way of using the other specifications but can help you to better keep the overview.
– A readme file is generated with more information about the specifications which are selected and how some of the specifications can be tested within the generated application.

Conclusion

Support for MicroProfile 1.3 version is added to Jessie at the request of some users who wanted to get started with it. Example code for some of the specifications will be added soon.

You can find Jessie here.

Have Fun

MicroProfile Rest Client for Java SE

Introduction

One of the cool specifications produced by the MicroProfile group is the Rest Client for MicroProfile  available from MP release 1.3.

It builds on top of the Client API of JAX-RS and allows you to use type-safe access to your endpoints without the need to programmatic interact with the Client API.

MicroProfile compliant server implementations need to implement this specification, but nothing says we cannot expand the usage into other environments (with a proper implementation) like use in Java SE (JavaFX seems must useful here) and plain Java EE.

Atbash has created an implementation of the specification so that it can be used in these environments and will use it within Octopus framework to propagate authentication and authorization information automatically in calls to JAX-RS endpoints.

The specification

A few words about the specification itself. JAX-RS 2.x contains a client API which allows you to access any ‘Rest’ endpoint in a uniform way.

Client client = ClientBuilder.newClient();
WebTarget employeeWebTarget = client.target("http://localhost:8080/demo/data").path("employees");
employeeWebTarget.request(MediaType.APPLICATION_JSON).get(new GenericType<List<Employee>>() {
});

This client API is great because we can use it to call any endpoint, not even limited to Java ones. As long as they behave in a standard way.

But things can be improved, by moving away from the programmatic way of performing these calls, into a more declarative way.

If we could define some kind of interface like this

@Path("/employees")
public interface EmployeeService {

@GET
@Produces(MediaType.APPLICATION_JSON)
List<Employee> getAll();
}

And we just could ask an implementation of this interface which performs the required steps of creating the Client, WebTarget and invoke it for us in the background. This would make it much easier for the developer and makes it much more type-safe.

Creating the implementation of that interface is what MicroProfile Rest Client is all about.

The interface defined above can then be injected in any other CDI bean (need to add the @RegisterRestClient on the interface and preferably a CDI scope like @ApplicationScoped) and by calling the method, we actually perform a call to the endpoint and retrieve the result.

@Inject
@RestClient
private EmployeeService employeeService;

public void doSomethingWithEmployees() {
....
... employeeService.getAll();
....
}

Atbash Rest Client

The specification also allows for a programmatic retrieval of the implementation, for those scenarios where no CDI is available.
However, remember that if we are running inside a CDI container, we can always retrieve some CDI bean by using

CDI.current().select();

from within any method.

The programmatic retrieval is thus an ideal candidate to use it in other environments or frameworks like JavaFX (basically every Java SE program), Spring, Kotlin, etc …

The programmatic retrieval starts from the RestClientBuilder with the newBuilder() method.

EmployeeService employeeService = RestClientBuilder.newBuilder()
    .baseUrl(new URL("http://localhost:8080/server/data"))
    .build(EmployeeService.class);

The above retrieves also an implementation for the Employee retrieval endpoint we used earlier on in this text.

For more information about the features like Exception handling, adding custom providers and more, look at the specification document.

The Atbash Rest Client is an implementation in Java 7 which can run on Java SE. It is created mainly for the Octopus Framework to propagate the user authentication (like username) and authorization information (like permissions) to JAX-RS endpoints in a transparent, automatically way.

A ClientRequestFilter is created in Octopus which creates a JWT token (compatible with MicroProfile JWT auth specification) containing username and permissions of the current user and this Filter can then be added as a provider to the MicroProfile Rest Client to have this security information available within the header of the call.

Since the current Octopus version is still based on Java SE 7, no other existing implementation could be used (MicroProfile is Java SE 8 based). The implementation is based on the DeltaSpike Proxy features and uses any Client API compatible implementation which is available at runtime.

Compliant, not certified.

Since all the MicroProfile specifications are Java 8 based, the API is also converted to Java SE 7. Except for a few small incompatibilities, the port is 100% interchangeable.

The most notable difference is creating the builder with the newBuilder() method. In the original specification, this is a static method of an interface which is not allowed in Java 7. For that purpose, an abstract class is created, AbstractRestClientBuilder which contains the method.

Other than that, class and method names should be identical, which makes the switch from Atbash Rest Client to any other implementation using Java 8 very smooth.

The Maven dependency has following coordinates (available on Maven Central):

<dependency>
   <groupId>be.atbash.mp.rest-client</groupId>
   <artifactId>atbash-rest-client-impl</artifactId>
   <version>0.5</version>
</dependency>

If you are running on Java 8, you can use the Apache CXF MicroProfile Rest client

<dependency>
   <groupId>org.apache.cxf</groupId>
   <artifactId>cxf-rt-rs-mp-client</artifactId>
   <version>3.2.4</version>
</dependency>

Which also can be used in a plain Java SE environment. Other implementations like the ones within Liberty and Payara Micro aren’t useable standalone in Java SE.

Remark

This first release of Atbash Rest Client is a pre-release, meaning that not all features of the specification are completely implemented. It is just a bare minimum for the a POC within Octopus.
For example, the handling of exceptions (because the endpoint returned a status in the range 4xx or 5xx) isn’t completely covered yet.

The missing parts will be implemented or improved in a future version.

Conclusion

With the MicroProfile Rest Client specification, it becomes easy to call some JAX-RS endpoints in a type-safe way. By using a declarative method, calling some endpoint becomes as easy as calling any other method within the JVM.

And since micro-services need to be called at some point from non-micro-service code, Java SE executable implementation is very important. It makes it possible to call it from plain Java EE, Java SE, any other framework or a JVM based language.

Have fun.

MicroProfile support for Jessie

Introduction

In some previous blog, I introduced Jessie, a tool for creating maven based applications which contain the skeleton for applications using Java EE, DeltaSpike, PrimeFaces, and Octopus (the declarative security framework for Java EE)

Although most people just copy and paste from an existing application, I find it very handy that I can generate very easily some as I create quite some demo type applications.

The last few months, besides Java EE applications, I’m also creating more and more Eclipse MicroProfile based demos. So in the last few weeks, I added support for MicroProfile into Jessie. It generates a demo app which uses the MicroProfile Specifications and specific support for the different server implementations.

MicroProfile 1.2

Version 1.2 is not the latest version of the specification. It is released end of September 2017 but is supported by quite a number of implementations as you can see on this overview page.

Besides the basic buildings blocks JAX-RS, JSON-P, and CDI, it contains

Configuration

This specification defines how configuration values can be read from different sources to customize your application.

Fault tolerance

It defines some various options for resilient micro-services like retry policies, bulkheads, circuit breakers, and fallback options.

JWT Authentication

This first version defines the basics of authentication and authorization information propagation to the micro-service using JWT. Inspired on OAuth2 and OpenId Connect, it is possible to define user information and the roles it has in a self-contained way so that no external parties need to be consulted.

Health Metrics

It defines the way how developers can expose some ‘telemetry’ data in a uniform way. It has support for things like the number of invocations, statistics on the execution time of endpoints, and so on.

Health Checks

The health checks are on a different level as the metrics. Which the checks we can verify if our service is still performing well. Or that we should kill it and start a new one. Besides standard checks (using memory, CPU, etc …) you can define your own checks very easily.

Application Generation

In this first version, the generation is still at a basic level. The online version of Jessie can be found here.

After you have selected the ‘MicroProfile’ technology stack, added some basic information about the maven artifact name, you can select one of the 4 implementations that support MicroProfile 1.2 completely

– WildFly swarm – 2017.12.1
– Liberty 17.0.0.3
– KumuluzEE 2.5.2
– Payara micro 5.181

The app contains examples of all specifications mentioned above (the JWT auth code is not always completely working due to small issues in configuration and calling the endpoint) and can be seen in action from the index.html overview page.

Conclusion

In this second official release of Jessie, you can now also generate MicroProfile 1.2 applications. You can choose one of the 4 supported implementations and all the required code for generating a fat jar application is in place.

In a future version of Jessie, newer releases of MicroProfile will be supported, the small known issues will be handled and selection of the included specifications will be possible.

have fun.

Atbash Configuration Server

Introduction

MicroProfile Config specification defines how configuration values can be picked up by the application. It has the concept of a Configuration source and converters to supply the values you need.

By default, only a ConfigSource for a classpath defined file and environment and system variables are defined.

But since we have the concepts in place, we can create our custom ConfigSource to retrieve the configuration from a central server.

Configuration Server

Instead of putting the configuration of each application within the application itself, we can store it in a central location.

It is very convenient to have an overview of the configuration of all your application at one place. Which makes updating it also very simple.

The first version of the Atbash Configuration Server exposes the configuration of an application through a JAX-RS endpoint.

The URL

/config/{application}

will give you the configuration values as a JSON structure for the specified application.

{
   "pets":"dog,cat",
   "dateValue":"2017-11-15",
   "value2":"500",
   "classname":"be.atbash.config.examples.se.testclasses.ConvTestTypeWStringCt",
   "value1":"Classpath Value",
   "value3":"true",
   "dateValueFmt":"16-11-2017,dd-MM-yyyy"
}

Creating the Configuration server

The configuration server is available within the directory  <server> of the repository https://github.com/atbashEE/atbash-config-server

You can build the server in 3 flavors

1. Java EE war.

With the maven command, mvn package -Pee7-servera WAR file is created which can be run by any Java EE 7 compliant server (Java 8 required)

2. WildFly Swarm executable JAR

The Configuration server can also be wrapped within a WildFly swarm application with the mvn package -Pwildfly-swarmcommand.

3. WebSphere Liberty executable JAR

There is also a profile defined to create a WebSphere Liberty JAR file, use the mvn package -Plibertycommand.

More servers will be supported when they have support for Config Spec 1.2.

Configuration of Server

Define within a config-server.properties or config-sever.yaml file on the classpath the following configuration information.

– rootDirectory: Root directory containing the configuration files for the application. See further for a directory structure.

– applications: List of known applications.

example (as yaml)

rootDirectory : /Users/rubus/atbash/config-server/server/demo
applications : ["app1", "app2"]

Possible directory structure

/demo
├── /app1
│  ├── app1.properties
│  └── app1-test.properties
└── /app2
   └── app2.properties

A subdirectory for each application so that the configuration values are nicely separated for each application.

All the features of Atbash config (like stage, yaml support, date support, etc) are available.

Client configuration

A ConfigSource implementation is available which integrates the result of the call to the JAX-RS endpoint into the configuration of the application.

In this first version, Atbash configuration extension is required (which makes it a bit more work) but this requirement will be removed in the next version.

Add the Maven artifact to your dependencies

    <dependency>
        <groupId>be.atbash.config</groupId>
        <artifactId>atbash-config-client</artifactId>
        <version>${atbash-config.version}</version>
    </dependency>

Define the base name of the configuration file which contains the configuration of the Config server.

Create a class implementing the be.atbash.config.spi.BaseConfigurationName interface and defining this class for usage with the ServiceLoader mechanism of Java.

Define the class name within src/main/resources/META-INF/services/be.atbash.config.spi.BaseConfigurationName

be.atbash.config.examples.DemoBaseName

Define the configuration within the specified properties file.

config.server.url=http://localhost:8181
config.server.app=app1
config.server.stage=test

* config.server.url: The _root_ of the Config server endpoint.

* config.server.app: The name of your application

* config.server.stage: (optional) Indication of the stage of the application to retrieve specific values.

We can use all the regular features of Configuration or Atbash config to specify the stage value, like environment or system properties.

The client can be used in a Java SE, Java EE or a MicroProfile environment.

Conclusion

With the Atbash Configuration server, you can store the configuration values for all your applications at a central location. The values can be picked up by a JAX-RS call through the Client ConfigSource.

The server can be run by WildFly Swarm, Liberty or a regular Java EE 7 server. The client can be used for all environments capable of using the MicroProfile Configuration spec (including Java SE and Java EE)

A future version will bring you some more features and makes it easier to set things up.

Have fun.