SSL/TLS Certificate Rotation Without Restarts in NGINX Open Source

Maxim Ivanitskiy

In the world of high-performance web servers, NGINX is a popular choice because its lightweight and efficient architecture enables it to handle large loads of traffic. With the introduction of the shared dictionary function as part of the NGINX JavaScript module (njs), NGINX’s performance capabilities reach the next level.

In this blog post, we explore the njs shared dictionary’s functionality and benefits, and show how to set up NGINX Open Source without the need to restart when rotating SSL/TLS certificates.

Shared Dictionary Basics and Benefits

The new js_shared_dict_zone directive allows NGINX Open Source users to enable shared memory zones for efficient data exchange between worker processes. These shared memory zones act as key-value dictionaries, storing dynamic configuration settings that can be accessed and modified in real-time.

Key benefits of the shared dictionary include:

• Minimal Overhead and Easy to Use – Built directly into njs, it’s easy to provision and utilize with an intuitive API and straightforward implementation. It also helps you simplify the process of managing and sharing data between worker processes.
• Lightweight and Efficient – Integrates seamlessly with NGINX, leveraging its event-driven, non-blocking I/O model. This approach reduces memory usage, and improves concurrency, enabling NGINX to handle many concurrent connections efficiently.
• Scalability – Leverages NGINX’s ability to scale horizontally across multiple worker processes so you can share and synchronize data across those processes without needing complex inter-process communication mechanisms. The time-to-live (TTL) setting allows you to manage records in shared dictionary entries by removing them from the zone due to inactivity. The evict parameter removes the oldest key-value pair to make space for new entries.

SSL Rotation with the Shared Dictionary

One of the most impactful use cases for the shared dictionary is SSL/TLS rotation. When using js_shared_dict_zone, there’s no need to restart NGINX in the event of an SSL/TLS certificate or key update. Additionally, it gives you a REST-like API to manage certificates on NGINX.

Below is an example of the NGINX configuration file that sets up the HTTPS server with the js_set and ssl_certificate directives. The JavaScript handlers use js_set to read the SSL/TLS certificate or key from a file.

This configuration snippet uses the shared dictionary to store certificates and keys in shared memory as a cache. If the key is not present, then it reads the certificate or key from the disk and puts it into the cache.

You can also expose a location that clears the cache. Once files on the disk are updated (e.g., the certificates and keys are renewed), the shared dictionary enforces reading from the disk. This adjustment allows rotating certificates/keys without the need to restart the NGINX process.

[@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop

And here is the JavaScript implementation for rotation of SSL/TLS certificates and keys using js_shared_dict_zone:

[@portabletext/react] Unknown block type "codeBlock", specify a component for it in the `components.types` prop

By sending the /clear request, the cache is invalidated and NGINX loads the SSL/TLS certificate or key from the disk on the next SSL/TLS handshake. Additionally, you can implement a js_content that takes an SSL/TLS certificate or key from the request while persisting and updating the cache too.

The full code of this example can be found in the njs GitHub repo.

Get Started Today

The shared dictionary function is a powerful tool for your application’s programmability that brings significant advantages in streamlining and scalability. By harnessing the capabilities of js_shared_dict_zone, you can unlock new opportunities for growth and efficiently handle increasing traffic demands.

Ready to supercharge your NGINX deployment with js_shared_dict_zone? You can upgrade your NGINX deployment with js_shared_dict_zone to unlock new use cases and learn more about this feature in our documentation. In addition, you can see a complete example of a shared dictionary function in the recently introduced njs-acme project, which enables the njs module runtime to work with ACME providers.

If you’re interested in getting started with NGINX Open Source and have questions, join NGINX Community Slack – introduce yourself and get to know this community of NGINX users!

About the Author

Maxim Ivanitskiy

More blogs by Maxim Ivanitskiy